diff options
| author | John Fieber <jfieber@FreeBSD.org> | 1995-04-28 16:19:59 +0000 |
|---|---|---|
| committer | John Fieber <jfieber@FreeBSD.org> | 1995-04-28 16:19:59 +0000 |
| commit | 4776451dac895d2c78d6aa20083001d7d5c3c535 (patch) | |
| tree | 501a08a088792c7d47b8001e64148f3217eab864 /handbook | |
| download | doc-4776451dac895d2c78d6aa20083001d7d5c3c535.tar.gz doc-4776451dac895d2c78d6aa20083001d7d5c3c535.zip | |
The FreeBSD handbook finds a new home.
Notes
Notes:
svn path=/head/; revision=2
Diffstat (limited to 'handbook')
| -rw-r--r-- | handbook/authors.sgml | 20 | ||||
| -rw-r--r-- | handbook/basics.sgml | 73 | ||||
| -rw-r--r-- | handbook/bibliography.sgml | 110 | ||||
| -rw-r--r-- | handbook/ctm.sgml | 199 | ||||
| -rw-r--r-- | handbook/current.sgml | 179 | ||||
| -rw-r--r-- | handbook/dialup.sgml | 809 | ||||
| -rw-r--r-- | handbook/diskless.sgml | 153 | ||||
| -rw-r--r-- | handbook/eresources.sgml | 118 | ||||
| -rw-r--r-- | handbook/glossary.sgml | 5 | ||||
| -rw-r--r-- | handbook/handbook.sgml | 237 | ||||
| -rw-r--r-- | handbook/kerberos.sgml | 329 | ||||
| -rw-r--r-- | handbook/nfs.sgml | 79 | ||||
| -rw-r--r-- | handbook/porting.sgml | 414 | ||||
| -rw-r--r-- | handbook/ports.sgml | 240 | ||||
| -rw-r--r-- | handbook/ppp.sgml | 372 | ||||
| -rw-r--r-- | handbook/scsi.sgml | 688 | ||||
| -rw-r--r-- | handbook/slipc.sgml | 196 | ||||
| -rw-r--r-- | handbook/slips.sgml | 488 | ||||
| -rw-r--r-- | handbook/submitters.sgml | 181 | ||||
| -rw-r--r-- | handbook/sup.sgml | 92 | ||||
| -rw-r--r-- | handbook/troubleshooting.sgml | 185 |
21 files changed, 5167 insertions, 0 deletions
diff --git a/handbook/authors.sgml b/handbook/authors.sgml new file mode 100644 index 0000000000..336549c96b --- /dev/null +++ b/handbook/authors.sgml @@ -0,0 +1,20 @@ +<!-- $Id: authors.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<!-- +Names and email address of contributing authors. Use these +entities when referencing people. +--> + +<!ENTITY a.jkh "Jordan Hubbard <tt><jkh@FreeBSD.org></tt>"> +<!ENTITY a.jfieber "John Fieber <tt><jfieber@FreeBSD.org></tt>"> +<!ENTITY a.phk "Poul-Henning Kamp <tt><phk@FreeBSD.org></tt>"> +<!ENTITY a.gclarkii "Gary Clark II <tt><gclarkii@FreeBSD.org></tt>"> +<!ENTITY a.gena "Gennady B. Sorokopud <tt><gena@NetVision.net.il></tt>"> +<!ENTITY a.ghelmer "Guy Helmer <tt><ghelmer@alpha.dsu.edu></tt>"> +<!ENTITY a.md "Mark Dapoz <tt><md@bsc.no></tt>"> +<!ENTITY a.martin "Martin Renters <tt><martin@innovus.com></tt>"> +<!ENTITY a.gpalmer "Gary Palmer <tt><gpalmer@FreeBSD.org></tt>"> +<!ENTITY a.john "John Lind <tt><john@starfire.MN.ORG></tt>"> +<!ENTITY a.asami "Satoshi Asami <tt><asami@FreeBSD.org></tt>"> +<!ENTITY a.wilko "Wilko Bulte <tt><wilko@yedi.iaf.nl></tt>"> diff --git a/handbook/basics.sgml b/handbook/basics.sgml new file mode 100644 index 0000000000..dfa49b6569 --- /dev/null +++ b/handbook/basics.sgml @@ -0,0 +1,73 @@ +<!-- $Id: basics.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Unix Basics</heading> + + <sect> + <heading>The online manual</heading> + + <p>The most comprehensive documentation on FreeBSD is in + the form of <em>man pages</em>. Nearly every program + on the system comes with a short reference manual + explaining the basic operation and various argument. + These manuals can be view with the + <tt><bf>man</bf></tt> command. Use of the + <tt><bf>man</bf></tt> command is simple: + <tscreen> + <tt><bf>man</bf> <it>command</it></tt> + </tscreen> + where <it>command</it> is the name of the command + you wish to find. For example, to learn more about + <tt><bf>ls</bf></tt> command type: + <tscreen> + <tt><bf>man</bf> ls</tt> + </tscreen> + + <p>The online manual is divided up into numbered + sections: + <enum> + <item>User commands</item> + <item>System calls and error numbers</item> + <item>Functions in the C libraries</item> + <item>Device drivers</item> + <item>File formats</item> + <item>Games and other diversions</item> + <item>Miscellaneous information</item> + <item>System maintenance and operation commands</item> + </enum> + in some cases, the same topic may appear in more than + one section of the on-line manual. For example, there + is a <tt><bf>chmod</bf></tt> user command and a + <tt><bf>chmod()</bf></tt> system call. In this case, + you can tell the <tt><bf>man</bf></tt> command which + you want by specifying the section: + <tscreen> + <tt><bf>man</bf> 1 chmod</tt> + </tscreen> + which will display the manual page for the user command + <tt><bf>chmod</bf></tt>. + + <p>This is fine if you know the name of the command and + forgot how to use it, but what if you cannot recall the + command name? You can use <tt><bf>man</bf></tt> to + search through the command <em>descriptions</em> by + using the <tt><bf>-k</bf></tt> switch: + <tscreen> + <tt><bf>man</bf> -k mail</tt> + </tscreen> + With this command you will be presented with a list of + commands that have the keyword `mail' in their + descriptions. + + <sect> + <heading>GNU Info files</heading> + + <p>FreeBSD includes many applications and utilities + produced by the Free Software Foundation (FSF). In + addition to man pages, these programs come with more + extensive <em>info</em> files which can be viewed with + the <tt>info</tt> command or, if you installed + <tt>emacs</tt>, the info mode of <tt>emacs</tt>. + + </sect> + diff --git a/handbook/bibliography.sgml b/handbook/bibliography.sgml new file mode 100644 index 0000000000..fea48a3cb9 --- /dev/null +++ b/handbook/bibliography.sgml @@ -0,0 +1,110 @@ +<!-- $Id: bibliography.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + + <chapt> + <heading>Bibliography</heading> + + <p>While the manual pages provide the definative reference + for individual pieces of the FreeBSD operating system, + they are notorious for not illustrating how to put the + pieces together to make the whole operating system run + smoothly. For this, there is no substitute for a good + book on Unix system administration, and a good users' + manual. + + <sect> + <heading>Users' guides</heading> + + <p><itemize> + <item>Gilley, Daniel. <sl>Unix in a Nutshell</sl>. + O'Reilly & Associates, Inc. 1990</item> + </itemize> + + <sect> + <heading>Administrators' guides</heading> + + <p><itemize> + + <item>Albitz, Paul; Liu, Cricket. <em>DNS and + BIND</em>. O'Reilley & Associates. 1993. ISBN + 1-56592-010-4 </item> + + <item>Costales, Brian; Allman, Eric; Rickert, + Neil. <em>sendmail</em> O'Reilley & + Associates. 1993. ISBN 1-56592-056-2 </item> + + <item>Frisch, Æleen. <em>Essential System + Administration</em>. O'Reilley & + Associates. 1993. ISBN 0-937175-80-3 </item> + + <item>Hunt, Craig. <em>TCP/IP Network Administration</em> + O'Reilley & Associates. 1992. ISBN 0-937175-82-X</item> + + <item>Nemeth, Evi. <em>Unix System Administration + Handbook</em>. Prentice Hall. 1989. ISBN + 0-13-933441-6</item> + + </itemize> + + + + <sect> + <heading>Programmers' guides</heading> + + <p><itemize> + + <item>Asente, Paul. <em>X Window System + Toolkit</em>. Digital Press. ISBN + 1-55558-051-3</item> + + <item>Ellis, Margaret A. and Stroustrup, + Bjarne. <em>The Annotated C++ Reference + Manual</em>. Addison-Wesley. 1990. ISBN + 0-201-51459-1</item> + + <item>Harbison, Samuel P. and Steele, Guy + L. Jr. <em>C: A Reference Manual</em>. Prentice + Hall. 3rd Edition, 1991. ISBN + 0-13-110933-2</item> + + <item>Jolitz, William. "Porting UNIX to the + 386". <em>Dr. Dobb's Journal</em>. January + 1991-July 1992.</item> + + <item>Leffler, Samuel J. <em>The Design and + implementation of the 4.3BSD UNIX operating + system</em>. Addison-Wesley. 1989.</item> + + <item>Plauger, P. J. <em>The Standard C + Library</em>. Prentice Hall. 1992. ISBN + 0-13-131509-9</item> + + <item>Wells, Bill. "Writing Serial Drivers for UNIX". + <em>Dr. Dobb's Journal</em>. 19(15), December + 1994. pp68-71, 97-99.</item> + + </itemize> + + <sect> + <heading>Hardware reference</heading> + + <p><itemize> + + <item>Stanley, Tom; Anderson, Don. <em>PCI System + Architechure</em>. Mindshare, Inc. ISBN + 1-881609-08-1</item> + + </itemize> + + <sect> + <heading>Magazines and journals</heading> + + <p><itemize> + + <item><em>The C/C++ Users Journal</em>. R&D Publications + Inc. ISSN 1075-2838</item> + + </itemize> + + </sect> + diff --git a/handbook/ctm.sgml b/handbook/ctm.sgml new file mode 100644 index 0000000000..be80df0e25 --- /dev/null +++ b/handbook/ctm.sgml @@ -0,0 +1,199 @@ +<!-- +# This is the sgml version of the ctm.FAQ file. +# +# Converted by Ollivier RObert <roberto@FreeBSD.ORG> +# +# $Id: ctm.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ +# +# ---------------------------------------------------------------------------- +# "THE BEER-WARE LICENSE" (Revision 42): +# <phk@login.dknet.dk> wrote this file. As long as you retain this notice you +# can do whatever you want with this stuff. If we meet some day, and you think +# this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +# ---------------------------------------------------------------------------- +# +--> + +<sect><heading>CTM</heading> + +<p><em>Contributed by &a.phk;. Updated 16-Mar-1995.</em> + + <tt/CTM/ is a method for keeping a remote directory tree in sync with a + central one. It has been developed for usage with FreeBSD's source + trees, though other people may find it useful for other purposes as + time goes by. Little, if any, documentation currently exists at + this time on the process of creating deltas, so talk to &a.phk; + for more information should you wish to use <tt/CTM/ for other things. + + <sect1>Why should I use <tt/CTM/ ? + <p><tt/CTM/ will give you a local copy of the ``FreeBSD-current'' + sources. If you are an active developer on FreeBSD, but have lousy + or non-existent TCP/IP connectivity, <tt/CTM/ was made for you. + You will need to transfer up to four deltas per day (or you can + have them arrive in email automatically), the sizes for which are + always kept as small as possible. This is typically less than 5K, + with the occasional (one in ten) being 10-50K and every now and + then a biggie of 100K+ or more coming around. + + You will also need to make yourself aware of the various caveats in + running ``current'' sources, and for this it is recommended that + you refer to the relevant FAQ which can be found in + <verb> + /usr/share/FAQ/Text/current-policy.FAQ + </verb> + <!-- XXX --> + + <sect1>What do I need to use <tt/CTM/? + + <p>You will need two things: The ``<tt/CTM/'' program and the initial + deltas to feed it (to get up to ``current'' levels). + + The <tt/CTM/ program is in the <tt/FreeBSD-current/ tree from + version 2.0.0 and forward (<tt>/usr/src/usr.sbin/<tt/CTM/</tt>). + If you are running an older version of FreeBSD, you can fetch the + current <tt/CTM/ sources directly from: + + <url + url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm"> + + The ``deltas'' you feed <tt/CTM/ can be had two ways, ftp or email. + If you have general ftp access to the Internet, then the following + ftp sites support access to <tt/CTM/: + + <url url="ftp://freefall.cdrom.com/pub/CTM"> + + Ftp the the relevant directory and fetch the <tt/README/ file, + starting from there. + + If you only have access to electronic mail or are otherwise blocked + from using ftp, then you may wish to your deltas via email: + + Send email to <tt/<majordomo@freebsd.org>/ to subscribe to + the list ``ctm-src-cur''. (If you do not know how to subscribe + yourself using majordomo, send a message first containing the + word ``help'', it will send you back usage instructions.) + + When you begin receiving your <tt/CTM/ updates in the mail, you may + use the <tt/ctm_rmail/ program to unpack and apply them with. You + can actually use the <tt/ctm_rmail/ program directly from a entry + in <tt>/etc/aliases</tt> if you want. Check the <tt/ctm_rmail/ man + page for more details. + + <bf/NOTE/: No matter what method you use to get the <tt/CTM/ + deltas, you should subscribe to the <tt/ctm-announce@freebsd.org/ + mailing list. In the future this will be the only place where + announcements about the operation of the <tt/CTM/ system will be + posted. Send an email to <tt/majordomo@freebsd.org/ with a single + line of ``<tt/subscribe ctm-announce/'' to get added to the list. + + <sect1>Starting off with <tt/CTM/ for the first time: + <p>Before you can start using <tt/CTM/ deltas, you will need to get a + special ``base'' delta that provides a starting point for all + deltas produced subsequently to it. + + You can recognize a base delta by the ``<tt/A/'' appended to the + number (<tt/src-cur.0341A.gz/ for instance). As a rule a base + delta is produced every 100 deltas, the next one will be + <tt/src-cur.0400A.gz/. By the way, they are large! 25 to 30 + Megabytes of <tt/gzip/'ed data is common for a base delta. + + If you do have the 2.0-RELEASE <tt/srcdist/, you can instead + retreive the <tt/src-cur.0372R20.gz/ file, it's only 4Mb and it + will take you to current from the 2.0-RELEASE sources. + + Once you've picked a base delta to start from, you will also need + all deltas with higher numbers following it. + + <sect1>Using <tt/CTM/ in your daily life: + <p>To apply the deltas, simply say + <verb> + cd /where/ever/you/want/the/stuff + ctm -v -v /where/you/store/your/deltas/src-cur.* + </verb> + <tt/CTM/ understands deltas which have been put through <tt/gzip/, + so you don't need to gunzip them first, this saves diskspace. + + Unless it feels very secure about the entire process, <tt/CTM/ will + not touch your tree. To check out a delta you can also use the + ``<tt/-c/'' flag and <tt/CTM/ won't actually touch your tree, but + only check the integrity of the delta, and see if it would apply + cleanly to the tree. + + There are other options to <tt/CTM/ as well, look in the sources. + + I would also be very happy if somebody could help with the ``user + interface'' portions, as I have realized that I can't make up my + mind on what options should do what, how and when... + + That's really all there is to it. Everytime you get a new delta, + you run it through <tt/CTM/. + + Don't remove the deltas if they are hard to download again. You + just might want to keep them around in case something bad happens. + Even if you only have floppy disks, consider using <tt/fdwrite/ to + make a copy. + + + <sect1>Future plans for <tt/CTM/ + <p> + Tons of them: + <itemize> + <item> + Make local modifications to the tree possible. One way to do + it could be this:<p> When <tt/CTM/ wants to edit the file + ``<tt>foo/bar.c</tt>'', it would first check for the existence + of <tt>foo/bar.c#CTM</tt> If this file exists, the delta is + applied to it instead. This way the <tt>foo/bar.c</tt> file + can be edited to suit local needs. + <item> + Make a ``restore file(s)'' option to <tt/CTM/, something like: + <verb> + ctm -r src/sys/i386/wd.c /here/are/my/deltas/src-cur.* + </verb> + would restore <tt/wd.c/ to the current status from the files. + <item> + Clean up the options to <tt/CTM/, they became confusing and + counter intuitive. + </itemize> + + The bad news is that I am very busy, so any help in doing this will + be most welcome. And don't forget to tell me what you want also... + + <sect1>Miscellaneous stuff + <p> + All the ``DES infected'' (e.g. export controlled) source is not + included. You will get the ``international'' version only. If + sufficient interest appears, we will set up a ``<tt/sec-cur/'' + sequence too. + + If you are a frequent or valuable contributor to FreeBSD, I will be + willing to arrange special services, one option is delivery via + <tt/ftp/ or <tt/rcp/ to a machine closer to you. You need to have + earned this, since it takes time to do, but I'll be all the more + happy to do it for you then. + + There is a sequence of deltas for the <tt/ports/ collection too, + but interest has not been all that high yet. Tell me if you want + an email list for that too and we'll consider setting it up. + + If you have commit priviledges or are similary authorized by the + FreeBSD core team, you can also get access to the CVS repository + tree by the same means. Contact &a.phk; + for details. + + + <sect1>Thanks! + <p> + <descrip> + <tag/Bruce Evans/ + for his pointed pen and invaluable comments. + <tag/Soren Schmidt/ + for patience. + <tag/Stephen McKay/ + wrote <tt/ctm_[rs]mail/, much appreciated. + <tag/Jordan Hubbard/ + for being so stubborn that I had to make it better. + <tag/All the users/ + I hope you like it... + </descrip> + diff --git a/handbook/current.sgml b/handbook/current.sgml new file mode 100644 index 0000000000..bfb0751121 --- /dev/null +++ b/handbook/current.sgml @@ -0,0 +1,179 @@ +<!-- $Id: current.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + + +<chapt><heading>Staying current with FreeBSD</heading> + +<p><em>Contributed by &a.jkh;.</em> + +<!-- + + THE FREEBSD CURRENT POLICY + +Last updated: $Date: 1995-04-28 16:19:59 $ + +This document attempts to explain the rationale behind FreeBSD-current, +what you should expect should you decide to run it, and states some +prerequisites for making sure the process goes as smoothly as possible. +--> + +<sect><heading>What is FreeBSD-current?</heading> + +<p>FreeBSD-current is, quite literally, nothing more than a daily snapshot of +the working sources for FreeBSD. These include work in progress, experimental +changes, and transitional mechanisms that may or may not be present in +the next official release of the software. While many of us compile +almost daily from FreeBSD-current sources, there are periods of time when +the sources are literally uncompilable. These problems are generally resolved +as expeditiously as possible, but whether or not FreeBSD-current sources bring +disaster or greatly desired functionality can literally be a matter of which +part of any given 24 hour period you grabbed them in! + +Under certain circumstances we will sometimes make binaries for parts of +FreeBSD-current available, but only because we're interested in getting +something tested, not because we're in the business of providing binary +releases of current. If we don't offer, please don't ask! It takes far +too much time to do this as a general task. + +<sect><heading>Who needs FreeBSD-current?</heading> + +<p>FreeBSD-current is made generally available for 3 primary interest groups: +<enum> + <item> Members of the FreeBSD group who are actively working on one + part or another of the source tree and for whom keeping `current' + is an absolute requirement. + + <item> Members of the FreeBSD group who are active ALPHA or BETA testers + and willing to spend time working through problems in order to + ensure that FreeBSD-current remains as sane as possible. These + are also people who wish to make topical suggestions on changes + and the general direction of FreeBSD. + + <item> Peripheral members of the FreeBSD (or some other) group who merely + wish to keep an eye on things and use the current sources for + reference purposes (e.g. for <em>reading</em>, not running). These + people also make the occasional comment or contribute code. +</enum> + +<sect><heading>What is FreeBSD-current <em>NOT</em>?</heading> + +<p><enum> + <item> A fast-track to getting pre-release bits because there's something + you heard was pretty cool in there and you want to be the first on + your block to have it. + + <item> A quick way of getting bug fixes. + + <item> In any way ``officially supported'' by us. + + We do our best to help people genuinely in one of the 3 + ``legitimate'' FreeBSD-current catagories, but we simply <em>do not + have the time</em> to help every person who jumps into FreeBSD-current + with more enthusiasm than knowledge of how to deal with + experimental system software. This is not because we're mean and + nasty people who don't like helping people out (we wouldn't even be + doing FreeBSD if we were), it's literally because we can't answer + 400 messages a day <em>and</em> actually work on FreeBSD! I'm sure if + given the choice between having us answer lots of questions or + continue to improve FreeBSD, most of you would vote for us + improving it. +</enum> + +<sect><heading>Using FreeBSD-current</heading> + +<p><enum> <item> Join the freebsd-hackers and freebsd-commit + mailing lists. This is not just a good idea, it's + <em>essential</em>. If you aren't on freebsd-hackers, you + won't read the comments that people are making about the + current state of the system and thus will end up stumbling + over a lot of problems that others have already found and + solved. Even more importantly, you will miss out on + potentially critical information (e.g. ``Yo, Everybody! + Before you rebuild <tt>/usr/src</tt>, you <em>must</em> + rebuild the kernel or your system will crash horribly!"). + + The freebsd-commit list will allow you to see the commit log + entry for each change as its made. This can also contain + important information, and will let you know what parts of + the system are being actively changed. + + To join these lists, send mail to `majordomo@FreeBSD.ORG' + and say: +<verb> + subscribe freebsd-hackers + subscribe freebsd-commit +</verb> + In the body of your message. Optionally, you can also say `help' + and MajorDomo will send you full help on how to subscribe and + unsubscribe to the various other mailing lists we support. + + <item> Grab the sources from ftp.FreeBSD.ORG. You can do this in + three ways: + + <enum> + <item> Using the CTM facility desribed below. Unless you + have a good TCP/IP connection at a flat rate, this is + the way to do it. + + <item> Use the CMU `sup' program (Software Update + Protocol), also described below. + This is the second most recommended method, since it allows + you to grab the entire collection once and then only what's + changed from then on. Many people run sup from cron + and keep their sources up-to-date automatically. + + The problem is that sup does not use the bandwidth efficient, + unless the round-trip is very fast. If the cost of connection + or the duration of the session is a concern, use CTM. + + <item> Use ftp. The source tree for FreeBSD-current is always + "exported" on: +<verb> + ftp.FreeBSD.ORG:~ftp/pub/FreeBSD/FreeBSD-current +</verb> + We use `wu-ftpd' which allows compressed/tar'd grabbing + of whole trees. e.g. you see: +<verb> + usr.bin/lex +</verb> + You can do: +<verb> + ftp> cd usr.bin + ftp> get lex.tar.Z +</verb> + And it will get the whole directory for you as a compressed + tar file. + </enum> + + <item> If you're grabbing the sources to run, and not just look at, + then grab <em>all</em> of current, not just selected portions. The + reason for this is that various parts of the source depend on + updates elsewhere and trying to compile just a subset is almost + guaranteed to get you into trouble. + + <item> Before compiling current, read the Makefile in /usr/src + carefully. You'll see one-time targets like `bootstrapld' + which <em><bf>must</bf></em> be run as part of the upgrading process. Reading + freebsd-hackers will keep you up-to-date on other bootstrapping + procedures that sometimes become necessary as we move towards + the next release. + + <item> Be active! If you're running FreeBSD-current, we want to know + what you have to say about it, especially if you have suggestions + for enhancements or bug fixes. Suggestions with accompanying code + are received most enthusiastically! +</enum> + +<!-- +Thank you for taking the time to read this all the way through. We're +always very keen to remain "open" and share the fruits of our labor +with the widest possible audience, but sharing development sources has +always had certain pitfalls associated with it (which is why most +commercial organizations won't even consider it) and I want to make +sure that people at least come into this with their eyes open, and +don't make the leap unless they're good at working without a net! +--> + + + + diff --git a/handbook/dialup.sgml b/handbook/dialup.sgml new file mode 100644 index 0000000000..4eeaf28471 --- /dev/null +++ b/handbook/dialup.sgml @@ -0,0 +1,809 @@ +<!-- This is an SGML document in the linuxdoc DTD of the Tutorial for + Configuring a FreeBSD for Dialup Services by Guy Helmer. + $Id: dialup.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ + +<!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN"> + + +<article> + +<title> +Configuring FreeBSD for Dialup Services +<author>Guy Helmer, <tt/ghelmer@alpha.dsu.edu/ +<date>v0.1, 28 March 1995 +<abstract> + +--> + +<sect><heading>Dialup access</heading> + +<p><em>Contributed by &a.ghelmer;.</em> + +This document provides suggestions for configuring a FreeBSD system to +handle dialup modems. This document is written based on the author's +experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience +with dialup modems on other UNIX-like operating systems); however, +this document may not answer all of your questions or provide examples +specific enough to your environment. The author cannot be responsible +if you damage your system or lose data due to attempting to follow the +suggestions here. + +<sect1><heading>Prerequisites<label id="dialup:prereqs"></> +<p> + +To begin with, the author assumes you have some basic knowledge of +FreeBSD. You need to have FreeBSD installed, know how to edit files +in a UNIX-like environment, and how to look up manual pages on the +system. As discussed below, you'll need certain versions of FreeBSD, +and knowledge of some terminology & modem and cabling. + +<sect2>FreeBSD Version +<p> + +First, it is assumed that you are using FreeBSD version 1.1 or higher +(including versions 2.x). FreeBSD version 1.0 included two different +serial drivers, which complicates the situation. Also, the serial +device driver (<tt/sio/) has improved in every release of FreeBSD, so +more recent versions of FreeBSD are assumed to have better and more +efficient drivers than earlier versions. + +<sect2>Terminology +<p> + +A quick rundown of terminology: + +<descrip> + +<tag/bps/ Bits per Second - the rate at which data is transmitted + +<tag/DTE/ Data Terminal Equipment - for example, your computer + +<tag/DCE/ Data Communications Equipment - your modem + +<tag/RS-232/ EIA standard for serial communications via hardware + +</descrip> + +If you need more information about these terms and data communications +in general, the author remembers reading that <em/The RS-232 Bible/ +(anybody have an ISBN?) is a good reference. + +When talking about communications data rates, the author doesn't use +the term <bf/baud/. Baud refers to the number of electrical state +transitions that may be made in a period of time, while <bf/bps/ (bits +per second) is the ``correct'' term to use (at least it doesn't seem +to bother the curmudgeons quite a much). + +<sect2>External vs. Internal Modems +<p> + +External modems seem to be more convenient for dialup, because +external modems often can be semi-permanently configured via +parameters stored in non-volatile RAM and they usually provide lighted +indicators that display the state of important RS-232 signals. +Blinking lights impress visitors, but lights are also very useful to +see whether a modem is operating properly. + +Internal modems usually lack non-volatile RAM, so their configuration +may be limited only to setting DIP switches. If your internal modem +has any signal indicator lights, it is probably difficult to view the +lights when the system's cover is in place. + +<sect2>Modems and Cables +<p> + +A background knowledge of these items is assumed + +<itemize> + +<item> You know how to connect your modem to your computer so that the +two can communicate (unless you have an internal modem, which doesn't +need such a cable) + +<item> You are familiar with your modem's command set, or know where +to look up needed commands + +<item> You know how to configure your modem (probably via a terminal +communications program) so you can set the non-volatile RAM +parameters + +</itemize> + +The first, connecting your modem, is usually simple - most +straight-through serial cables work without any problems. You need to +have a cable with appropriate connectors (DB-25 or DB-9, male or +female) on each end, and the cable must be a DCE-to-DTE cable with +these signals wired: + +<itemize> +<item> Transmitted Data (<tt/SD/) +<item> Received Data (<tt/RD/) +<item> Request to Send (<tt/RTS/) +<item> Clear to Send (<tt/CTS/) +<item> Data Set Ready (<tt/DSR/) +<item> Data Terminal Ready (<tt/DTR/) +<item> Carrier Detect (<tt/CD/) +<item> Signal Ground (<tt/SG/) +</itemize> + +FreeBSD needs the <tt/RTS/ and <tt/CTS/ signals for flow-control at +speeds above 2400bps, the <tt/CD/ signal to detect when a call has +been answered or the line has been hung up, and the <tt/DTR/ signal to +reset the modem after a session is complete. Some cables are wired +without all of the needed signals, so if you have problems, such as +a login session not going away when the line hangs up, you may have a +problem with your cable. + +The second prerequisite depends on the modem(s) you use. If you don't +know your modem's command set by heart, you will need to have the +modem's reference book or user's guide handy. Sample commands for USR +Sportster 14,400 external modems will be given, which you may be able +to use as a reference for your own modem's commands. + +Lastly, you'll need to know how to setup your modem so that it will +work well with FreeBSD. Like other UNIX-like operating systems, +FreeBSD uses the hardware signals to find out when a call has been +answered or a line has been hung up and to hangup and reset the modem +after a call. FreeBSD avoids sending commands to the modem or +watching for status reports from the modem. If you are familiar with +connecting modems to PC-based bulletin board systems, this may seem +awkward. + +<sect2>Serial Interface Considerations +<p> + +FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA +RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 +devices have single-character buffers. The 16550 device provides a +16-character buffer, which allows for better system performance. +(Bugs in plain 16550's prevent the use of the 16-character buffer, so +use 16550A's if possible). Because single-character-buffer devices +require more work by the operating system than the 16-character-buffer +devices, 16550A-based serial interface cards are much prefered. If +the system has many active serial ports or will have a heavy load, +16550A-based cards are better for low-error-rate communications. + +<sect1>Quick Overview +<p> + +Here is the process that FreeBSD follows to accept dialup logins. A +<tt/getty/ process, spawned by <tt/init/, patiently waits to open the +assigned serial port (<tt>/dev/ttyd0</tt>, for our example). The +command <tt/ps ax/ might show this: + +<tscreen><verb> + 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 +</verb></tscreen> + +When a user dials the modem's line and the modems connect, the <tt/CD/ +line is asserted by the modem. The kernel notices that carrier has +been detected and completes <tt/getty/'s open of the port. <tt/getty/ +sends a <tt/login:/ prompt at the specified initial line speed. +<tt/getty/ watches to see if legitimate characters are received, and, +in a typical configuration, if it finds junk (probably due to the +modem's connection speed being different than <tt/getty/'s speed), +<tt/getty/ tries adjusting the line speeds until it receives +reasonable characters. + +We hope <tt/getty/ finds the correct speed and the user sees a +<tt/login:/ prompt. After the user enters his/her login name, +<tt/getty/ executes <tt>/usr/bin/login</tt>, which completes the login +by asking for the user's password and then starting the user's shell. + +Let's dive into the configuration... + +<sect1>Kernel Configuration +<p> + +FreeBSD kernels typically come prepared to search for four serial +ports, known in the PC-DOS world as <tt/COM1:/, <tt/COM2:/, +<tt/COM3:/, and <tt/COM4:/. FreeBSD can presently also handle +``dumb'' multiport serial interface cards, such as the Boca Board +1008 and 2016 (please see the manual page <tt/sio(4)/ for kernel +configuration information if you have a multiport serial card). The +default kernel only looks for the standard COM ports, though. + +To see if your kernel recognizes any of your serial ports, watch for +messages while the kernel is booting, or use the +<tt>/sbin/dmesg</tt> command to replay the kernel's boot messages. In +particular, look for messages that start with the characters <tt/sio/. +Hint: to view just the messages that have the word <tt/sio/, use the +command + +<tscreen><verb> +/usr/sbin/dmesg | grep 'sio' +</verb></tscreen> + +For example, on a system with four serial ports, these are the +serial-port specific kernel boot messages: + +<tscreen><verb> +sio0 at 0x3f8-0x3ff irq 4 on isa +sio0: type 16550A +sio1 at 0x2f8-0x2ff irq 3 on isa +sio1: type 16550A +sio2 at 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A +sio3 at 0x2e8-0x2ef irq 9 on isa +sio3: type 16550A +</verb></tscreen> + +If your kernel doesn't recognize all of your serial ports, you'll +probably need to configure a custom FreeBSD kernel for your system. + +Please see the BSD System Manager's Manual chapter on ``Building +Berkeley Kernels with Config'' [the source for which is in +<tt>/usr/src/share/doc/smm</tt>] and ``FreeBSD Configuration +Options'' [in <tt>/sys/doc/options.doc</tt>] for more +information on configuring and building kernels. You may have to +unpack the kernel source distribution if haven't installed the system +sources already (<tt>srcdist/srcsys.??</tt> in FreeBSD 1.1, +<tt>srcdist/sys.??</tt> in FreeBSD 1.1.5.1, or the entire source +distribution in FreeBSD 2.0) to be able to configure and build +kernels. + +Create a kernel configuration file for your system (if you haven't +already) by <tt/cd/ing to <tt>/sys/i386/conf</tt>. Then, if you are +creating a new custom configuration file, copy the file GENERICAH (or +GENERICBT, if you have a BusTek SCSI controller on FreeBSD 1.x) to +<em/YOURSYS/, where <em/YOURSYS/ is the name of your system, but in +upper-case letters. Edit the file, and change the device lines + +<tscreen><verb> +device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr +device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr +device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr +device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr +</verb></tscreen> + +You can comment-out or completely remove lines for devices you don't +have. If you have a multiport serial board, such as the Boca Board +BB2016, please see the <tt/sio(4)/ man page for complete information +on how to write configuration lines for multiport boards. Be careful +if you are using a configuration file that was previously used for a +different version of FreeBSD because the device flags have changed +between versions. + +Note that <tt/port "IO_COM1"/ is a substitution for <tt/port 0x3f8/, +<tt/IO_COM2/ is <tt/0x2f8/, <tt/IO_COM3/ is <tt/0x3e8/, and +<tt/IO_COM4/ is <tt/0x2e8/, which are fairly common port addresses for +their respective serial ports; interrupts 4, 3, 5, and 9 are fairly +common interrupt request lines. Also note that regular serial ports +<bf>can't</bf> share interrupts on ISA-bus PCs (multiport boards have +on-board electronics that allow all the 16550A's on the board to share +one or two interrupt request lines). + +When you are finished adjusting the kernel configuration file, use the +program <tt/config/ as documented in ``Building Berkeley Kernels with +Config'' and the <tt/config(8)/ manual page to prepare a kernel +building directory, then build, install, and test the new kernel. + +<sect1>Device Special Files +<p> + +Most devices in the kernel are accessed through ``device special +files'', which are located in the <tt>/dev</tt> directory. The +<tt/sio/ devices are accessed through the <tt>/dev/ttyd?</tt> +(dial-in) and <tt>/dev/cua0?</tt> (call-out) devices. On FreeBSD +version 1.1.5 and higher, there are also initialization devices +(<tt>/dev/ttyid?</tt> and <tt>/dev/cuai0?</tt>) and locking devices +(<tt>/dev/ttyld?</tt> and <tt>/dev/cual0?</tt>). The initialization +devices are used to initialize communications port parameters each +time a port is opened, such as <tt>crtscts</tt> for modems which use +<tt>CTS/RTS</tt> signalling for flow control. The locking devices are +used to lock flags on ports to prevent users or programs changing +certain parameters; see the manual pages <tt/termios(4)/, <tt/sio(4)/, +and <tt/stty(1)/ for information on the terminal settings, locking +& initializing devices, and setting terminal options, +respectively. + +<sect2>Making Device Special Files +<p> + +A shell script called <tt/MAKEDEV/ in the <tt>/dev</tt> directory +manages the device special files. (The manual page for +<tt/MAKEDEV(8)/ on FreeBSD 1.1.5 is fairly bogus in its discussion of +<tt/COM/ ports, so ignore it.) To use <tt/MAKEDEV/ to make dialup +device special files for <tt/COM1:/ (port 0), <tt/cd/ to <tt>/dev</tt> +and issue the command <tt/MAKEDEV ttyd0/. Likewise, to make dialup +device special files for <tt/COM2:/ (port 1), use <tt/MAKEDEV ttyd1/. + +<tt/MAKDEV/ not only creates the <tt>/dev/ttyd?</tt> device special +files, but also creates the <tt>/dev/cua0?</tt> (and all of the +initializing and locking special files under FreeBSD 1.1.5 and up) and +removes the hardwired terminal special file <tt>/dev/tty0?</tt>, if it +exists. + +After making new device special files, be sure to check the +permissions on the files (especially the <tt>/dev/cua*</tt> files) to +make sure that only users who should have access to those device +special files can read & write on them - you probably don't want +to allow your average user to use your modems to dialout. The default +permissions on the <tt>/dev/cua*</tt> files should be sufficient: + +<tscreen><verb> +crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01 +crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01 +crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01 +</verb></tscreen> + +These permissions allow the user <tt/uucp/ and users in the group +<tt/dialer/ to use the call-out devices. + +<sect1>Configuration Files +<p> + +There are three system configuration files in the <tt>/etc</tt> +directory that you'll probably need to edit to allow dialup access to +your FreeBSD system. The first, <tt>/etc/gettytab</tt>, contains +configuration information for the <tt>/usr/libexec/getty</tt> daemon. +Second, <tt>/etc/ttys</tt> holds information that tells +<tt>/sbin/init</tt> what <tt/tty/ devices should have <tt/getty/ +processes running on them. Lastly, you can place port initialization +commands in the <tt>/etc/rc.serial</tt> script if you have FreeBSD +1.1.5.1 or higher; otherwise, you can initialize ports in the +<tt>/etc/rc.local</tt> script. + +There are two schools of thought regarding dialup modems on UNIX. One +group likes to configure their modems and system so that no matter at +what speed a remote user dials in, the local computer-to-modem RS-232 +interface runs at a locked speed. The benefit of this configuration +is that the remote user always sees a system login prompt immediately. +The downside is that the system doesn't know what a user's true data +rate is, so full-screen programs like Emacs won't adjust their +screen-painting methods to make their response better for slower +connections. + +The other school configures their modems' RS-232 interface to vary its +speed based on the remote user's connection speed. For example, +V.32bis (14.4 Kbps) connections to the modem might make the modem run +its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the +modem's RS-232 interface run at 2400 bps. Because <tt/getty/ doesn't +understand any particular modem's connection speed reporting, +<tt/getty/ gives a <tt/login:/ message at an initial speed and watches +the characters that come back in response. If the user sees junk, +it's assumed that they know they should press the +<tt><Enter></tt> key until they see a recognizable prompt. If +the data rates don't match, <tt/getty/ sees anything the user types as +``junk'', tries going to the next speed and gives the <tt/login:/ +prompt again. This procedure can continue ad nauseum, but normally +only takes a keystroke or two before the user sees a good prompt. +Obviously, this login sequence doesn't look as clean as the former +``locked-speed'' method, but a user on a low-speed connection should +receive better interactive response from full-screen programs. + +The author will try to give balanced configuration information, but is +biased towards having the modem's data rate follow the connection +rate. + +<sect2>/etc/gettytab +<p> + +<tt>/etc/gettytab</tt> is a <tt/termcap(5)/-style file of +configuration information for <tt/getty(8)/. Please see the +<tt/gettytab(4)/ manual page for complete information on the format of +the file and the list of capabilities. + +<sect3>Locked-Speed Config +<p> + +If you are locking your modem's data communications rate at a +particular speed, you probably won't need to make any changes to +<tt>/etc/gettytab</tt>. + +<sect3>Matching-Speed Config +<p> + +You'll need to setup an entry in <tt>/etc/gettytab</tt> to give +<tt/getty/ information about the speeds you wish to use for your +modem. If you have a 2400 bps modem, you can probably use the +existing <tt/D2400/ entry. This entry already exists in the FreeBSD +1.1.5.1 <tt/gettytab/ file, so you don't need to add it unless it is +missing under your version of FreeBSD: + +<tscreen><verb> +# +# Fast dialup terminals, 2400/1200/300 rotary (can start either way) +# +D2400|d2400|Fast-Dial-2400:\ + :nx=D1200:tc=2400-baud: +3|D1200|Fast-Dial-1200:\ + :nx=D300:tc=1200-baud: +5|D300|Fast-Dial-300:\ + :nx=D2400:tc=300-baud: +</verb></tscreen> + +If you have a higher speed modem, you'll probably need to add an entry +in <tt>/etc/gettytab</tt>; here's an entry you could use for a 14.4 +Kbps modem with a top interface speed of 19.2 Kpbs: + +<tscreen><verb> +# +# Additions for a V.32bis Modem +# +um|V300|High Speed Modem at 300,8-bit:\ + :nx=V19200:tc=std.300: +un|V1200|High Speed Modem at 1200,8-bit:\ + :nx=V300:tc=std.1200: +uo|V2400|High Speed Modem at 2400,8-bit:\ + :nx=V1200:tc=std.2400: +up|V9600|High Speed Modem at 9600,8-bit:\ + :nx=V2400:tc=std.9600: +uq|V19200|High Speed Modem at 19200,8-bit:\ + :nx=V9600:tc=std.19200: +</verb></tscreen> + +On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity +connections. Under FreeBSD 1.1, add <tt/:np:/ parameters to the +<tt>std.<em/xxx/</tt> entries at the top of the file for 8 bits, no +parity; otherwise, the default is 7 bits, even parity. + +The example above starts the communications rate at 19.2 Kbps (for a +V.32bis connection), then cycles through 9600 bps (for V.32), 2400 +bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communcations rate +cycling is implemented with the <tt/nx=/ (<bf/next table/) capability. +Each of the lines uses a <tt/tc=/ (<bf/table continuation/) entry to +pick up the rest of the ``standard'' settings for a particular data +rate. + +If you have a 28.8 Kbps modem and/or you want to take advantage of +compression on a 14.4 Kbps modem, you need to use a higher +communications rate than 19.2 Kbps. Here's an example of a +<tt/gettytab/ entry starting a 57.6 Kpbs: + +<tscreen><verb> +# +# Additions for a V.32bis or V.34 Modem +# Starting at 57.6 Kpbs +# +vm|VH300|Very High Speed Modem at 300,8-bit:\ + :nx=VH57600:tc=std.300: +vn|VH1200|Very High Speed Modem at 1200,8-bit:\ + :nx=VH300:tc=std.1200: +vo|VH2400|Very High Speed Modem at 2400,8-bit:\ + :nx=VH1200:tc=std.2400: +vp|VH9600|Very High Speed Modem at 9600,8-bit:\ + :nx=VH2400:tc=std.9600: +vq|VH57600|Very High Speed Modem at 57600,8-bit:\ + :nx=VH9600:tc=std.57600: +</verb></tscreen> + +If you have a slow CPU or a heavily loaded system and you don't have +16550A-based serial ports, you may receive sio ``silo'' errors at 57.6 +Kbps. + +<sect2>/etc/ttys +<p> + +<tt>/etc/ttys</tt> is the list of <tt/ttys/ for <tt/init/ to monitor. +<tt>/etc/ttys</tt> also provides security information to <tt/login/ +(user <tt/root/ may only login on ttys marked <tt/secure/). See the +manual page for <tt/ttys(5)/ for more information. + +You'll need to either modify existing lines in <tt>/etc/ttys</tt> or +add new lines to make <tt/init/ run <tt/getty/ processes automatically +on your new dialup ports. The general format of the line will be the +same, whether you are using a locked-speed or matching-speed +configuration: + +<tscreen><verb> +ttyd0 "/usr/libexec/getty xxx" dialup on +</verb></tscreen> + +The first item in the above line is the device special file for this +entry - <tt/ttyd0/ means <tt>/dev/ttyd0</tt> is the file that this +<tt/getty/ will be watching. The second item, <tt>"/usr/libexec/getty +<em/xxx/"</tt> (<em/xxx/ will be replaced by the initial <tt/gettytab/ +capability) is the process <tt/init/ will run on the device. The +third item, <tt/dialup/, is the default terminal type. The fourth +parameter, <tt/on/, indicates to <tt/init/ that the line is +operational. There can be a fifth parameter, <tt>secure</tt>, but it +should only be used for terminals which are physically secure (such as +the system console). + +The default terminal type (<tt/dialup/ in the example above) may +depend on local preferences. <tt/dialup/ is the traditional default +terminal type on dialup lines so that users may customize their login +scripts to notice when the terminal is <tt/dialup/ and automatically +adjust their terminal type. However, the author finds it easier at +his site to specify <tt/vt102/ as the default terminal type, since the +users just use VT102 emulation on their remote systems. + +After you have made changes to <tt>/etc/ttys</tt>, you may send the +<tt/init/ process a <tt/HUP/ signal to re-read the file. You can use +the command + +<tscreen><verb> +kill -1 1 +</verb></tscreen> + +to send the signal. If this is your first time setting up the system, +though, you may want to wait until your modem(s) are properly +configured and connected before signalling <tt/init/. + +<sect3>Locked-Speed Config +<p> + +For a locked-speed configuration, your <tt/ttys/ entry needs to +have a fixed-speed entry provided to <tt/getty/. For a modem whose +port speed is locked at 19.2 Kbps, the <tt/ttys/ entry might look like +this: + +<tscreen><verb> +ttyd0 "/usr/libexec/getty std.19200" dialup on +</verb></tscreen> + +If your modem is locked at a different data rate, substitute the +appropriate name for the <tt>std.<em/speed/</tt> entry for +<tt/std.19200/ from <tt>/etc/gettytab</tt> for your modem's data rate. + +<sect3>Matching-Speed Config +<p> + +In a matching-speed configuration, your <tt/ttys/ entry needs to +reference the appropriate beginning ``auto-baud'' (sic) entry in +<tt>/etc/gettytab</tt>. For example, if you added the above suggested +entry for a matching-speed modem that starts at 19.2 Kbps (the +<tt/gettytab/ entry containing the <tt/V19200/ starting point), your +<tt/ttys/ entry might look like this: + +<tscreen><verb> +ttyd0 "/usr/libexec/getty V19200" dialup on +</verb></tscreen> + +<sect2>/etc/rc.serial or /etc/rc.local +<p> + +High-speed modems, like V.32, V.32bis, and V.34 modems, need to use +hardware (<tt>RTS/CTS</tt>) flow control. You can add <tt/stty/ +commands to <tt>/etc/rc.serial</tt> on FreeBSD 1.1.5.1 and up, or +<tt>/etc/rc.local</tt> on FreeBSD 1.1, to set the hardware flow +control flag in the FreeBSD kernel for the modem ports. + +For example, on a sample FreeBSD 1.1.5.1 system, +<tt>/etc/rc.serial</tt> reads: + +<tscreen><verb> +#!/bin/sh +# +# Serial port initial configuration + +stty -f /dev/ttyid1 crtscts +stty -f /dev/cuai01 crtscts +</verb></tscreen> + +which sets the <tt/termios/ flag <tt/crtscts/ on serial port #1's +(<tt/COM2:/) dialin and dialout initialization devices. + +On an old FreeBSD 1.1 system, these entries were added to +/etc/rc.local to set the <tt/crtscts/ flag on the devices: + +<tscreen><verb> +# Set serial ports to use RTS/CTS flow control +stty -f /dev/ttyd0 crtscts +stty -f /dev/ttyd1 crtscts +stty -f /dev/ttyd2 crtscts +stty -f /dev/ttyd3 crtscts +</verb></tscreen> + +Since there isn't an initialization device special file on FreeBSD +1.1, one has to just set the flags on the sole device special file and +hope the flags aren't cleared by a miscreant. + +<sect1>Modem Settings +<p> + +If you have a modem whose parameters may be permanently set in +non-volatile RAM, you'll need to use a terminal program (such as Telix +under PC-DOS or <tt/tip/ under FreeBSD) to set the parameters. +Connect to the modem using the same communications speed as the +initial speed <tt/getty/ will use and configure the modem's +non-volatile RAM to match these requirements: + +<itemize> + +<item> <tt/CD/ asserted when connected + +<item> <tt/DTR/ asserted for operation; dropping DTR hangs up line +& resets modem + +<item> <tt/CTS/ transmitted data flow control + +<item> Disable <tt>XON/XOFF</tt> flow control + +<item> <tt/RTS/ received data flow control + +<item> Quiet mode (no result codes) + +<item> No command echo + +</itemize> + +Please read the documentation for your modem to find out what commands +and/or DIP switch settings you need to give it. + +For example, to set the above parameters on a USRobotics Sportster +14,400 external modem, one could give these commands to the modem: + +<tscreen><verb> +ATZ +AT&C1&D2&H1&I0&R2&W +</verb></tscreen> + +You might also want to take this opportunity to adjust other settings +in the modem, such as whether it will use V.42bis and/or MNP5 +compression. + +The USR Sportster 14,400 external modem also has some DIP switches +that need to be set; for other modems, perhaps you can use these +settings as an example: + +<itemize> + +<item> Switch 1: UP - DTR Normal + +<item> Switch 2: Don't care (Verbal Result Codes/Numeric Result Codes) + +<item> Switch 3: UP - Suppress Result Codes + +<item> Switch 4: DOWN - No echo, offline commands + +<item> Switch 5: UP - Auto Answer + +<item> Switch 6: UP - Carrier Detect Normal + +<item> Switch 7: UP - Load NVRAM Defaults + +<item> Switch 8: Don't care (Smart Mode/Dumb Mode) + +</itemize> + +Result codes should be disabled/suppressed for dialup modems to avoid +problems that can occur if <tt/getty/ mistakenly gives a <tt/login:/ +prompt to a modem that is in command mode and the modem echoes the +command or returns a result code. I've heard this sequence can result +in a extended, silly conversation between <tt/getty/ and the modem. + +<sect2>Locked-speed Config +<p> + +For a locked-speed configuration, you'll need to configure the modem +to maintain a constant modem-to-computer data rate independent of the +communications rate. On a USR Sportster 14,400 external modem, these +commands will lock the modem-to-computer data rate at the speed used +to issue the commands: + +<tscreen><verb> +ATZ +AT&B1&W +</verb></tscreen> + +<sect2>Matching-speed Config +<p> + +For a variable-speed configuration, you'll need to configure your +modem to adjust its serial port data rate to match the incoming call +rate. On a USR Sportster 14,400 external modem, these commands will +lock the modem's error-corrected data rate to the speed used to issue +the commands, but allow the serial port rate to vary for +non-error-corrected connections: + +<tscreen><verb> +ATZ +AT&B2&W +</verb></tscreen> + +<sect2>Checking the Modem's Configuration +<p> + +Most high-speed modems provide commands to view the modem's current +operating parameters in a somewhat human-readable fashion. On the USR +Sportster 14,400 external modems, the command <tt/ATI5/ displays the +settings that are stored in the non-volatile RAM. To see the true +operating parameters of the modem (as influenced by the USR's DIP +switch settings), use the commands <tt/ATZ/ and then <tt/ATI4/. + +If you have a different brand of modem, check your modem's manual to +see how to double-check your modem's configuration parameters. + +<sect1>Troubleshooting +<p> + +Here are a few steps you can follow to check out the dialup modem on +your system. + +<sect2>Checking out the FreeBSD system +<p> + +Hook up your modem to your FreeBSD system, boot the system, and, if +your modem has status indication lights, watch to see whether the +modem's <tt/DTR/ indicator lights when the <tt/login:/ prompt appears +on the system's console - if it lights up, that should mean that +FreeBSD has started a <tt/getty/ process on the appropriate +communications port and is waiting for the modem to accept a call. + +If the <tt/DTR/ indicator doesn't light, login to the FreeBSD system +through the console and issue a <tt/ps ax/ to see if FreeBSD is trying +to run a <tt/getty/ process on the correct port. You should see a +lines like this among the processes displayed: + +<tscreen><verb> + 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 + 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 +</verb></tscreen> + +If you see something different, like this: + +<tscreen><verb> + 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 + ^^ +</verb></tscreen> + +and the modem hasn't accepted a call yet, this means that <tt/getty/ +has completed its open on the communications port. This could +indicate a problem with the cabling or a mis-configured modem, because +<tt/getty/ should not be able to open the communications port until +<tt/CD/ (carrier detect) has been asserted by the modem. + +If you don't see any <tt/getty/ processes waiting to open the desired +<tt/ttyd?/ port, double-check your entries in <tt>/etc/ttys</tt> to +see if there are any mistakes there. Also, check the log file +<tt>/var/log/messages</tt> to see if there are any log messages from +<tt/init/ or <tt/getty/ regarding any problems. If there are any +messages, triple-check the configuration files <tt>/etc/ttys</tt> and +<tt>/etc/gettytab</tt>, as well as the appropriate device special +files <tt>/dev/ttyd?</tt>, for any mistakes, missing entries, or +missing device special files. + +<sect2>Try Dialing In +<p> + +Try dialing into the system; be sure to use 8 bits, no parity, 1 stop +bit on the remote system. If you don't get a prompt right away, or +get garbage, try pressing <tt><Enter></tt> about once per +second. If you still don't see a <tt/login:/ prompt after a while, +try sending a <tt>BREAK</tt>. If you are using a high-speed modem to +do the dialing, try dialing again after locking the dialing modem's +interface speed (via <tt>AT&B1</tt> on a USR Sportster, for +example). + +If you still can't get a <tt/login:/ prompt, check +<tt>/etc/gettytab</tt> again and double-check that + +<itemize> +<item> The initial capability name specified in <tt>/etc/ttys</tt> for +the line matches a name of a capability in <tt>/etc/gettytab</tt> + +<item> Each <tt/nx=/ entry matches another <tt/gettytab/ capabilty +name + +<item> Each <tt/tc=/ entry matches another <tt/gettytab/ capability +name + +</itemize> + +If you dial but the modem on the FreeBSD system won't answer, make +sure that the modem is configured to answer the phone when <tt/DTR/ is +asserted. If the modem seems to be configured correctly, verify that +the <tt/DTR/ line is asserted by checking the modem's indicator lights +(if it has any). + +If you've gone over everything several times and it still doesn't work, +take a break and come back to it later. If it still doesn't work, +perhaps you can send an electronic mail message to +<tt>FreeBSD-Questions@freebsd.org</tt> describing your modem and your +problem, and the good folks on the list will try to help. + +<sect1>Acknowledgements +<p> + +Thanks to these people for comments and advice: + +<descrip> + +<tag/Sean Kelly/ <kelly@fsl.noaa.gov> for a number of good +suggestions + +</descrip> + + diff --git a/handbook/diskless.sgml b/handbook/diskless.sgml new file mode 100644 index 0000000000..25baa4dc03 --- /dev/null +++ b/handbook/diskless.sgml @@ -0,0 +1,153 @@ +<!-- $Id: diskless.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Diskless operation</heading> + +<p><em>Contributed by &a.martin;.</em> + + <tt>netboot.com/netboot.rom</tt> allow you to boot your + FreeBSD machine over the network and run FreeBSD without + having a disk on your client. Under 2.0 it is now + possible to have local swap. Swapping over NFS is also + still supported. + + Supported Ethernet cards include: Western Digital/SMC + 8003, 8013, 8216 and compatibles; NE1000/NE2000 and + compatibles (requires recompile) + + <sect1> + <heading>Setup Instructions</heading> + + <p><enum> + <item> Find a machine that will be your server. This + machine will require enough disk space to hold the + FreeBSD 2.0 binaries and have bootp, tftp and NFS + services available. + + Tested machines: + <itemize> + <item>HP9000/8xx running HP-UX 9.04 or later (pre + 9.04 doesn't work)</item> + <item>Sun/Solaries 2.3. (you may need to get + bootp)</item> + </itemize> + + <item>Set up a bootp server to provide the client with + IP, gateway, netmask. +<tscreen><verb> +diskless:\ + :ht=ether:\ + :ha=0000c01f848a:\ + :sm=255.255.255.0:\ + :hn:\ + :ds=192.1.2.3:\ + :ip=192.1.2.4:\ + :gw=192.1.2.5:\ + :vm=rfc1048: +</verb></tscreen></item> + + <item>Set up a TFTP server (on same machine as bootp + server) to provide booting information to client. + The name of this file is <tt>cfg.X.X.X.X</tt> (or + <tt>/tftpboot/cfg.X.X.X.X</tt>, it will try both) + where <tt>X.X.X.X</tt> is the IP address of the + client. The contents of this file can be any valid + netboot commands. Under 2.0, netboot has the + following commands: +<tscreen><verb> +help - print help list +ip <X.X.X.X> - print/set client's IP address +server <X.X.X.X> - print/set bootp/tftp server address +netmask <X.X.X.X> - print/set netmask +hostname <name> - print/set hostname +kernel <name> - print/set kernel name +rootfs <ip:/fs> - print/set rootfilesystem +swapfs <ip:/fs> - print/set swapfilesystem +swapsize <size> - set diskless swapsize in Kbytes +diskboot - boot from disk +autoboot - continue boot process +</verb></tscreen> + A typical completely diskless cfg file might contain: +<tscreen><verb> +rootfs 192.1.2.3:/rootfs/myclient +swapfs 192.1.2.3:/swapfs +swapsize 20000 +hostname myclient.mydomain +</verb></tscreen> + A cfg file for a machine with local swap might contain: +<tscreen><verb> +rootfs 192.1.2.3:/rootfs/myclient +hostname myclient.mydomain +</verb></tscreen> + + <item>Ensure that your NFS server has exported the root + (and swap if applicable) filesystems to your client, + and that the client has root access to these + filesystems + + A typical <tt>/etc/exports</tt> file on FreeBSD might + look like: +<tscreen><verb> +/rootfs/myclient -maproot=0:0 myclient.mydomain +/swapfs -maproot=0:0 myclient.mydomain +</verb></tscreen> + + And on HP-UX: +<tscreen><verb> +/rootfs/myclient -root=myclient.mydomain +/swapfs -root=myclient.mydomain +</verb></tscreen> + + <item>If you are swapping over NFS (completely diskless + configuration) create a swap file for your client + using touch. If your <tt>swapfs</tt> command has the + argument <tt>/swapfs</tt> as in the example above, + the swapfile for myclient will be called + <tt>/swapfs/swap.X.X.X.X</tt> where <tt>X.X.X.X</tt> + is the client's IP addr, eg: +<tscreen><verb> +# touch /swapfs/swap.192.1.2.4 +</verb></tscreen> + + <item> Unpack the root filesystem in the directory the + client will use for its root filesystem + (<tt>/rootfs/myclient</tt> in the example above). + + <itemize> + + <item> On HP-UX systems: The server should be + running HP-UX 9.04 or later for HP9000/800 series + machines. Prior versions don't allow the + creation of device files over NFS. + + <item> When extracting <tt>/dev</tt> in + <tt>/rootfs/myclient</tt>, beware that some + systems (HPUX) will not create device files that + FreeBSD is happy with. You may have to go to + single user mode on the first bootup (press + control-c during the bootup phase), cd + <tt>/dev</tt> and do a "<tt>sh ./MAKEDEV + all</tt>" from the client to fix this. + </itemize> + + <item>Run <tt>netboot.com</tt> on the client or make an EPROM + from the <tt>netboot.rom</tt> file + </enum> + + <sect1> + <heading>Using Shared <tt>/</tt> and <tt>/usr</tt> filesystems</heading> + + <p>At present there isn't an officially sanctioned way of + doing this, although I have been using a shared <tt>/usr</tt> + filesystem and individual <tt>/</tt> filesystems for each client. + If anyone has any suggestions on how to do this cleanly, + please let me and/or the core group know. + + <sect1> + <heading>Compiling netboot for specific setups</heading> + + <p>Netboot can be compiled to support NE1000/2000 cards by + changing the configuration in + <tt>/sys/i386/boot/netboot/Makefile</tt>. See the + comments at the top of this file. + diff --git a/handbook/eresources.sgml b/handbook/eresources.sgml new file mode 100644 index 0000000000..c8da616aae --- /dev/null +++ b/handbook/eresources.sgml @@ -0,0 +1,118 @@ +<!-- $Id: eresources.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + + <chapt> + <heading>Additional resources on the Internet</heading> + + <sect> + <heading>Mailing lists</heading> + + <p>The FreeBSD Project runs a number of Internet mailing + lists dedicated to the discussion of FreeBSD and + related topics. Users with access to Internet mail are + encouraged to subscribe to the lists that interest them + and ask questions. The procedure is quite simple, just + send a mail message to: + <tscreen> + <tt>majordomo@freebsd.org</tt> + </tscreen> + with a message body of: + <tscreen> + <tt><bf>subscribe <it>listname</it></bf></tt> + </tscreen> + where <em>listname</em> is one of the lists described + below. You can subscribe to multiple lists with a + single message by having several <em>subscribe</em> + lines. For more detailed information, send a message + to: + <tscreen> + <tt>majordomo@freebsd.org</tt> + </tscreen> + with a message body of + <tscreen> + <tt><bf>help</bf></tt> + </tscreen> + + <sect1> + <heading>General discussion lists</heading> + <p><descrip> + <tag>freebsd-announce</tag> Important announcements + about FreeBSD are posted here. + + <tag>freebsd-questions</tag> General discussion of + problems people experience in setting up and using + FreeBSD. + + <tag>freebsd-hackers</tag> Technical discussions + about the design and implementation of FreeBSD. + + <tag>freebsd-bugs</tag> Bug reports and discussions + of reported bugs are posted here, although the + discussions are usually moved over to the + <em>freebsd-hackers</em> mailing list if the become involved. + </descrip> + + <sect1> + <heading>CVS lists</heading> + + <sect> + <heading>Usenet newsgroups</heading> + + <p>While no newsgroups dedicated to FreeBSD exist, there + are many in which FreeBSD is discussed or are otherwise + relevant to FreeBSD users. + + <sect1> + <heading>BSD specific newsgroups</heading> + + <p><itemize> + <item> comp.unix.bsd.freebsd.announce + <item> comp.unix.bsd.freebsd.misc + </itemize> + + <sect1> + <heading>Other Unix newsgroups of interest</heading> + + <p><itemize> + <item> comp.unix + <item> comp.unix.questions + <item> comp.unix.admin + <item> comp.unix.programmer + <item> comp.unix.shell + <item> comp.unix.user-friendly + <item> comp.security.unix + <item> comp.sources.unix + <item> comp.unix.advocacy + <item> comp.unix.misc + <item> comp.os.386bsd.announce + <item> comp.os.386bsd.apps + <item> comp.os.386bsd.bugs + <item> comp.os.386bsd.development + <item> comp.os.386bsd.misc + <item> comp.os.386bsd.questions + <item> comp.bugs.4bsd + <item> comp.bugs.4bsd.ucb-fixes + <item> comp.unix.bsd + </itemize> + + <sect1> + <heading>X-Window system</heading> + + <p><itemize> + <item> comp.windows.x.i386unix + <item> comp.windows.x + <item> comp.windows.x.apps + <item> comp.windows.x.announce + <item> comp.windows.x.intrinsics + <item> comp.windows.x.motif + <item> comp.windows.x.pex + <item> comp.emulators.ms-windows.wine + </itemize> + + <sect> + <heading>Word Wide Web servers</heading> + + <p><itemize> + <item> <url url="http://www.freebsd.org/"></item> + </itemize> + </sect> diff --git a/handbook/glossary.sgml b/handbook/glossary.sgml new file mode 100644 index 0000000000..385e6731a6 --- /dev/null +++ b/handbook/glossary.sgml @@ -0,0 +1,5 @@ +<!-- $Id: glossary.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Glossary</heading> + diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml new file mode 100644 index 0000000000..a53bb2638a --- /dev/null +++ b/handbook/handbook.sgml @@ -0,0 +1,237 @@ +<!-- $Id: handbook.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN" [ +<!ENTITY % authors SYSTEM "authors.sgml"> +%authors; + +<!ENTITY bibliography SYSTEM "bibliography.sgml"> +<!ENTITY basics SYSTEM "basics.sgml"> +<!ENTITY ctm SYSTEM "ctm.sgml"> +<!ENTITY current SYSTEM "current.sgml"> +<!ENTITY dialup SYSTEM "dialup.sgml"> +<!ENTITY diskless SYSTEM "diskless.sgml"> +<!ENTITY eresources SYSTEM "eresources.sgml"> +<!ENTITY glossary SYSTEM "glossary.sgml"> +<!ENTITY kerberos SYSTEM "kerberos.sgml"> +<!ENTITY nfs SYSTEM "nfs.sgml"> +<!ENTITY porting SYSTEM "porting.sgml"> +<!ENTITY ports SYSTEM "ports.sgml"> +<!ENTITY ppp SYSTEM "ppp.sgml"> +<!ENTITY scsi SYSTEM "scsi.sgml"> +<!ENTITY slipc SYSTEM "slipc.sgml"> +<!ENTITY slips SYSTEM "slips.sgml"> +<!ENTITY submitters SYSTEM "submitters.sgml"> +<!ENTITY sup SYSTEM "sup.sgml"> +<!ENTITY troubleshooting SYSTEM "troubleshooting.sgml"> + +]> + +<!-- + +Potential target audience: + 1. Potential users + a. new to unix + b. somewhat familiar with unix + c. veterans + 2. Existing users + a. new to unix + b. somewhat familiar with unix + c. veterans + + +OUTLINE: + +--> + +<linuxdoc> + <book> + + <title>FreeBSD Handbook + <author> + <name></name> + <!-- <date> --> + + + <abstract>Welcome to FreeBSD! This handbook covers the + installation and day to day use of FreeBSD. + + This manual is a <bf>work in progress</bf> and is the + work of many individials. Many sections do not yet exist + and some of those that do exist need to be updated. If + you are interested in helping with this project, send + email to &a.jfieber; or to the FreeBSD Documentantion + Project mailing list <tt><doc@freebsd.org></tt>. + </abstract> + + <toc> + + + <chapt><heading>Introduction</heading> + + <sect><heading>FreeBSD In a nutshell</heading> + + <sect><heading>History</heading> + + <sect><heading>About this release</heading> + + <sect><heading>FreeBSD now and in the future</heading> + + + <chapt><heading>Installing FreeBSD</heading> + + <sect><heading>Preparing for the installation</heading> + + <sect1><heading>Hardware checklist</heading> + + <sect2><heading>minimal requirements</heading> + + <sect2><heading>IRQs, IO Addresses, and DMA channels</heading> + + <sect1><heading>Software checklist</heading> + + <sect2><heading>Making the installation floppies</heading> + + <sect2><heading>CD-ROM</heading> + + <sect2><heading>Tape</heading> + + <sect2><heading>Disk</heading> + + <sect><heading>Installation</heading> + + <sect><heading>Set up a user account</heading> + + &basics; + + <chapt><heading>Installing applications</heading> + + <sect><heading>Installing packages</heading> + &ports; + &porting; + + <chapt><heading>Reconfiguring the kernel</heading> + + <p>Once you have your FreeBSD system installed and + operational it is a good idead to re-configure the + kernel. You may also need to re-configure the kernel if + you add, change, or remove hardware from your system. + + <p> + + <chapt><heading>Basic Networking</heading> + <sect><heading>Ethernet basics</heading> + <sect><heading>Serial basics</heading> + <sect><heading>Hardwired Terminals</heading> + &dialup; + + <chapt><heading>PPP and SLIP</heading> + + &ppp; + &slipc; + &slips; + + <chapt><heading>Advanced networking</heading> + <sect><heading>Gateways and routing</heading> + &nfs; + <sect><heading>Yellow Pages/NIS</heading> + &diskless; + <sect><heading>ISDN</heading> + + <chapt><heading>Mail</heading> + + <chapt><heading>Printing</heading> + + <chapt><heading>Users, groups and security</heading> + + <sect><heading>DES, MD5 and Crypt</heading> + + &kerberos; + + <sect><heading>S/Key</heading> + + <sect><heading>Firewalls</heading> + + <chapt><heading>The X-Window System</heading> + + <chapt><heading>Managing hardware</heading> + &scsi; + <sect><heading>adding/reconfiguring disks</heading> + <sect><heading>tapes and backups</heading> + <sect><heading>serial ports</heading> + <sect><heading>sound cards</heading> + + <chapt><heading>PC Hardware compatibility</heading> + + <sect><heading>CORE/PROCESSING</heading> + + <sect1><heading>Motherboards</heading> + + <sect2><heading>ISA</heading> + + <sect2><heading>EISA</heading> + + <sect2><heading>VLB</heading> + + <sect2><heading>PCI</heading> + + <sect1><heading>CPUs/FPUs</heading> + + <sect1><heading>Memory</heading> + + <sect1><heading>BIOS</heading> + + <sect><heading>INPUT/OUTPUT</heading> + + <sect1><heading>Video cards</heading> + + <sect1><heading>Sound cards</heading> + + <sect1><heading>Serial ports (including multiport cards)</heading> + + <sect1><heading>Parallel ports</heading> + + <sect1><heading>Modems</heading> + + <sect1><heading>Etherenet cards</heading> + + <sect1><heading>Keyboards</heading> + + <sect1><heading>Mice</heading> + + <sect1><heading>Other (joysticks? tablets?)</heading> + + <sect><heading>STORAGE</heading> + + <sect1><heading>Disk/tape controllers</heading> + + <sect2><heading>SCSI</heading> + + <sect2><heading>IDE</heading> + + <sect2><heading>Floppy</heading> + + <sect1><heading>Hard drives</heading> + + <sect1><heading>Tape drives</heading> + + <sect1><heading>CD-ROM drives</heading> + + <sect1><heading>Other</heading> + + <sect><heading>OTHER</heading> + + <sect1><heading>PCMCIA</heading> + + ¤t; + &ctm; + ⊃ + &troubleshooting; + &submitters; + + &bibliography; + &eresources; + &glossary; + + </book> +</linuxdoc> diff --git a/handbook/kerberos.sgml b/handbook/kerberos.sgml new file mode 100644 index 0000000000..7eca30e497 --- /dev/null +++ b/handbook/kerberos.sgml @@ -0,0 +1,329 @@ +<!-- $Id: kerberos.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Kerberos</heading> + +<p><em>Contributed by &a.md;.</em> + + <p>The following instructions can be used as a quick + guide on how to set up kerberos as distributed in 4.4 + BSD. However, you should refer to the original Athena + documentation for a complete description. + + <sect1> + <heading>Creating the initial database</heading> + + <p>First make sure that you don't have any old kerberos + databases around. You should change to the directory + <tt>/etc/kerberosIV</tt> and check that only the + following files are present: + +<tscreen><verb> +mideon# cd /etc/kerberosIV +mideon# ls +README krb.conf krb.realms register_keys + </verb></tscreen> + + If any additional files (such as <tt>principal.dir</tt>) exist, + then use the <tt>kdb_destroy</tt> command to destroy the + old kerberos database. + + <p>You should now edit the <tt>krb.conf</tt> and + <tt>krb.realms</tt> files to define your kerberos realm. + In this case the realm will be <it>BSC.NO</it> and the + server is <it>mideon.bsc.no</it>. We would edit the + <tt>krb.conf</tt> file to be as follows: + +<tscreen><verb> +mideon# cat krb.conf +BSC.NO +BSC.NO mideon.bsc.no admin server +CS.BERKELEY.EDU okeeffe.berkeley.edu +ATHENA.MIT.EDU kerberos.mit.edu +ATHENA.MIT.EDU kerberos-1.mit.edu +ATHENA.MIT.EDU kerberos-2.mit.edu +ATHENA.MIT.EDU kerberos-3.mit.edu +LCS.MIT.EDU kerberos.lcs.mit.edu +TELECOM.MIT.EDU bitsy.mit.edu +ARC.NASA.GOV trident.arc.nasa.gov + </verb></tscreen> + + <p>Now we have to add <it>mideon.bsc.no</it> to the + <it>BSC.NO</it> realm and also add an entry to put all + hosts in the <it>.bsc.no</it> domain in the + <it>BSC.NO</it> realm. The <tt>krb.realms</tt> file + would be updated as follows: + +<tscreen><verb> + mideon# cat krb.realms + mideon.bsc.no BSC.NO + .bsc.no BSC.NO + .berkeley.edu CS.BERKELEY.EDU + .MIT.EDU ATHENA.MIT.EDU + .mit.edu ATHENA.MIT.EDU +</verb></tscreen> + + <p>Now we're ready to create the database, issue the + <tt>kdb_init</tt> command to do this: + +<tscreen><verb> +mideon# kdb_init +Realm name [default CS.BERKELEY.EDU ]: BSC.NO +You will be prompted for the database Master Password. +It is important that you NOT FORGET this password. + +Enter Kerberos master key: + </verb></tscreen> + + <p>Now we have to save the key so that servers on the local + machine can pick it up. Use the <tt>kstash</tt> command to + do this. + +<tscreen><verb> +mideon# kstash + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + </verb></tscreen> + + <sect1> + <heading>Populating the database</heading> + + <p>We now have to add some entries into the database. + First lets create an entry for the user <it>md</it>. Use + the <tt>kdb_edit</tt> command to do this: + +<tscreen><verb> +mideon# kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: md +Instance: +md. not found, Create [y] ? +Principal: md, Instance: , kdc_key_ver: 1 +New Password: +New Password: + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? 100 +Attributes [ 0 ] ? +Edit O.K. + </verb></tscreen> + + <p>Now lets add an entry for the password changing daemon, + <tt>kpasswd</tt>. The principal name must be <it>kpasswd</it> and + the instance must be the name of the local machine, + <it>mideon</it> in this case. Similarily, we must also + add an entry for the principal <it>rcmd</it> with an + instance equal to the hostname of the local machine. + +<tscreen><verb> +Principal name: kpasswd +Instance: mideon +kpasswd.mideon not found, Create [y] ? +Principal: kpasswd, Instance: mideon, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +New Password: <---- and here +Random password [y] ? + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: rcmd +Instance: mideon +rcmd.mideon not found, Create [y] ? +Principal: rcmd, Instance: mideon, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +New Password: <---- and here +Random password [y] ? + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: <---- null entry here will cause an exit + </verb></tscreen> + + <sect1> + <heading>Creating the server file</heading> + + <p>We now have to extract all the instances which define + the services on this machine. For this we use the + <tt>ext_srvtab</tt> command. + +<tscreen><verb> +mideon# ext_srvtab mideon + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Generating 'mideon-new-srvtab'.... + </verb></tscreen> + + <p>Now, this command only generates a temporary file + which must be renamed to <tt>srvtab</tt> so that all the + server can pick it up. Use the <tt>mv</tt> command to move it + into place: + +<tscreen><verb> +mideon# mv mideon-new-srvtab srvtab + </verb></tscreen> + + <sect1> + <heading>Testing it all out</heading> + + <p>First we have to start the kerberos daemon: + +<tscreen><verb> +mideon# kerberos & +[1] 774 +mideon# Kerberos server starting + Sleep forever on error + Log file is /var/log/kerberos.log +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + +Current Kerberos master key version is 1 +Local realm: BSC.NO + </verb></tscreen> + + Now we can try using the <tt>kinit</tt> command to get + tokens for the id <it>md</it> that we created above: + +<tscreen><verb> +mideon# kinit md +Kerberos Initialization for "md" +Kerberos Password: + </verb></tscreen> + + Try listing the tokens using <tt>klist</tt> to see if we + really have them: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt0 +Principal: md@BSC.NO + + Issued Expires Principal +Mar 23 21:06:52 Mar 24 05:06:52 krbtgt.BSC.NO@BSC.NO + </verb></tscreen> + + And now try changing the password using <tt>passwd</tt> + to check if the kpasswd daemon can get authorisation to + the kerberos database: + +<tscreen><verb> +mideon# passwd md +Changing Kerberos password for md.@BSC.NO. +Old Kerberos password: +New Kerberos password: +Retype new Kerberos password: +Update complete. + </verb></tscreen> + + <sect1> + <heading>Adding <tt>su</tt> priviledges</heading> + + <p>We should now add an id which is authorised to <tt>su</tt> to + <it>root</it>. This is controlled by having an instance of + <it>root</it> associated with a principal. Using + <tt>kdb_edit</tt> we can create the entry + <it>md.root</it> in the kerberos database: + +<tscreen><verb> +mideon# kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: md +Instance: root +md.admin not found, Create [y] ? +Principal: md, Instance: admin, kdc_key_ver: 1 +New Password: +New Password: + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? 12 +Attributes [ 0 ] ? +Edit O.K. +Principal name: + </verb></tscreen> + + Now try getting tokens for it to make sure it works: + +<tscreen><verb> +mideon# kinit md.root +Kerberos Initialization for "md.root" +Kerberos Password: + </verb></tscreen> + + And list them to check expiry times: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt0 +Principal: md.root@BSC.NO + + Issued Expires Principal +Mar 23 21:08:47 Mar 23 22:08:47 krbtgt.BSC.NO@BSC.NO +mideon# + </verb></tscreen> + + Now we need to add the user to root's <tt>.klogin</tt> file: + +<tscreen><verb> +mideon# cat /root/.klogin +md.root@BSC.NO + </verb></tscreen> + + Now try doing the <tt>su</tt>: + +<tscreen><verb> +[md@mideon.bsc.no 10407] su +Kerberos Password: +Warning: tgt not verified. + </verb></tscreen> + + and take a look at what tokens we have: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt_root_1250 +Principal: md.root@BSC.NO + + Issued Expires Principal +Mar 23 22:09:59 Mar 23 22:19:59 krbtgt.BSC.NO@BSC.NO +mideon# + </verb></tscreen> + + Notice that with this setup each user has their own entry + for <tt>su</tt>'ing to root (the <it>user</it>.root entry + in kerberos). This can allow you to give root access to + multiple users without the need to share a common root + password. diff --git a/handbook/nfs.sgml b/handbook/nfs.sgml new file mode 100644 index 0000000000..8d0e4b25fb --- /dev/null +++ b/handbook/nfs.sgml @@ -0,0 +1,79 @@ +<!-- $Id: nfs.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>NFS</heading> + +<p><em>Contributed by &a.john;.</em> + +Certain Ethernet adapters for ISA PC systems have limitations which +can lead to serious network problems, particularly with NFS. This +difficulty is not specific to FreeBSD, but FreeBSD systems are affected +by it. + +The problem nearly always occurs when (FreeBSD) PC systems are networked +with high-performance workstations, such as those made by Silicon Graphics, +Inc., and Sun Microsystems, Inc. The NFS mount will work fine, and some +operations may succeed, but suddenly the server will seem to become +unresponsive to the client, even though requests to and from other systems +continue to be processed. This happens to the client system, whether the +client is the FreeBSD system or the workstation. On many systems, there is +no way to shut down the client gracefully once this problem has manifested +itself. The only solution is often to reset the client, because the NFS +situation cannot be resolved. + +Though the "correct" solution is to get a higher performance and capacity +Ethernet adapter for the FreeBSD system, there is a simple workaround that +will allow satisfactory operation. If the FreeBSD system is the SERVER, +include the option "wsize=1024" on the mount from the client. If the +FreeBSD system is the CLIENT, then mount the NFS file system with the +option "rsize=1024". These options may be specified using the fourth +field of the fstab entry on the client for automatic mounts, or by using +the "-o" parameter of the mount command for manual mounts. + +In the following examples, "fastws" is the host (interface) name of a +high-performance workstation, and "freebox" is the host (interface) name of +a FreeBSD system with a lower-performance Ethernet adapter. Also, +"/sharedfs" will be the exported NFS filesystem (see "man exports"), and +"/project" will be the mount point on the client for the exported file +system. In all cases, note that additional options, such as "hard" or +"soft" and "bg" may be desireable in your application. + +Examples for the FreeBSD system ("freebox") as the client: + in /etc/fstab on freebox: +fastws:/sharedfs /project nfs rw,rsize=1024 0 0 + as a manual mount command on freebox: +mount -t nfs -o rsize=1024 fastws:/sharedfs /project + +Examples for the FreeBSD system as the server: + in /etc/fstab on fastws: +freebox:/sharedfs /project nfs rw,wsize=1024 0 0 + as a manual mount command on fastws: +mount -t nfs -o wsize=1024 freebox:/sharedfs /project + +Nearly any 16-bit Ethernet adapter will allow operation without the above +restrictions on the read or write size. + +For anyone who cares, here is what happens when the failure occurs, which +also explains why it is unrecoverable. NFS typically works with a "block" +size of 8k (though it may do fragments of smaller sizes). Since the maximum +Ethernet packet is around 1500 bytes, the NFS "block" gets split into +multiple Ethernet packets, even though it is still a single unit to the +upper-level code, and must be received, assembled, and ACKNOWLEDGED as a +unit. The high-performance workstations can pump out the packets which +comprise the NFS unit one right after the other, just as close together as +the standard allows. On the smaller, lower capacity cards, the later +packets overrun the earlier packets of the same unit before they can be +transferred to the host and the unit as a whole cannot be reconstructed or +acknowledged. As a result, the workstation will time out and try again, +but it will try again with the entire 8K unit, and the process will be +repeated, ad infinitum. + +By keeping the unit size below the Ethernet packet size limitation, we +ensure that any complete Ethernet packet received can be acknowledged +individually, avoiding the deadlock situation. + +Overruns may still occur when a high-performance workstations is slamming +data out to a PC system, but with the better cards, such overruns are +not guarranteed on NFS "units". When an overrun occurs, the units affected +will be retransmitted, and there will be a fair chance that they will be +received, assembled, and acknowledged. diff --git a/handbook/porting.sgml b/handbook/porting.sgml new file mode 100644 index 0000000000..a633ac990b --- /dev/null +++ b/handbook/porting.sgml @@ -0,0 +1,414 @@ +<!-- $Id: porting.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Porting applications</heading> + +<p><em>Contributed by &a.jkh;.</em> + +Here are the guidelines one should follow in + creating a new port for FreeBSD 2.x . This documentation will + change as this process is progressively refined, so watch + this space for details. The <tt>${..}</tt> + variable names you see in this document all refer to + various user-overridable defaults used (and documented) + by <tt>/usr/share/mk/bsd.port.mk</tt>. Please refer to + that file for more details. + + <sect1> + <heading>Before starting the port</heading> + + <p> <em>Note: Only a fraction of the overridable variables + are mentioned in this document. Most (if not all) are + documented at the start of the <tt>bsd.port.mk</tt> + file which can be found in /usr/share/mk. This file + uses a non-standard tab setting. <tt>Emacs</tt> should + recognise the setting on loading the file. <tt>vi</tt> + or <tt>ex</tt> can be set to using the correct value by + typing "<tt>:set tabstop=4</tt>" once the file has been + loaded. - &a.gpalmer;</em> + + You may come across code that needs modifications or + conditional compilation based upon what version of UNIX + it's running under. If you need to make such changes to + the code for conditional compilation, make sure you make + the changes as general as possible so that we can + back-port code to FreeBSD 1.x systems and cross-port to + other BSD systems such as 4.4bsd from CSRG, BSD/386, + 386BSD and NetBSD. + + The preferred way to tell 4.3BSD/Reno and newer versions + of the BSD code apart is by using the "<tt>BSD</tt>" + macro defined in <tt><sys/param.h></tt>. Hopefully + that file is already included; if not, add the code: + +<tscreen><verb> +#ifdef _HAVE_PARAM_H +#include <sys/param.h> +#endif +</verb></tscreen> + + to the proper place in the <tt>.c</tt> file and add + <tt>-D_HAVE_PARAM_H</tt> to the <tt>CFLAGS</tt> in the + Makefile. + + Then, you may use: + +<tscreen><verb> +#if (defined(BSD) && (BSD >= 199103)) +</verb></tscreen> + + to detect if the code is being compiled on a 4.3 Net2 + code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD + 0.9, 386BSD, BSD/386 1.0). + + Use: + +<tscreen><verb> +#if (defined(BSD) && (BSD >= 199306)) +</verb></tscreen> + + to detect if the code is being compiled on a 4.4 code + base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, + BSD/386 1.1). + + Use sparingly: + + <itemize> + <item><tt>__FreeBSD__</tt> is defined in all + versions of FreeBSD. Use it if the change you + are making ONLY affects FreeBSD. Porting gotchas + like the use of <tt>sys_errlist[]</tt> vs + <tt>strerror()</tt> are Berkeleyisms, not FreeBSD + changes. + + <item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is + defined to be <tt>2</tt>. In earlier versions, + it's <tt>1</tt>. + + <item>If you need to tell the difference between a + FreeBSD 1.x system and a FreeBSD 2.x system, + usually the right answer is to use the + <tt>BSD</tt> macros described above. If there + actually is a FreeBSD specific change (such as + special shared library options when using + '<tt>ld</tt>') then it's OK to use + <tt>__FreeBSD__</tt> and "<tt>#if __FreeBSD_ > + 1</tt>" to detect a FreeBSD 2.x system. + + </itemize> + + In the dozens of ports that have been done, there have + only been one or two cases where <tt>__FreeBSD__</tt> + should have been used. Just because an earlier port + screwed up and used it in the wrong place doesn't mean + you should do so too. + + <sect1> + <heading> Doing the port</heading> + + <p>NOTE: If your sources work without change under FreeBSD, + skip to the next section. + + <enum> + <item>Get the original sources (normally) as a + compressed tarball (<tt><foo>.tar.gz</tt> or + <tt><foo>.tar.Z</tt>) and copy it into + <tt>${DISTDIR}</tt>. Always use + <em>mainstream</em> sources when and where you can, + and don't be tempted to patch a tarball 2 or 3 + revisions ahead just to save yourself trouble. The + idea is that the ports collection should be usable + even with all of <tt>${DISTDIR}</tt> blown + away, which is to say that it should be possible for + a user to repopulate all of + <tt>${DISTDIR}</tt> with publically available + files. + + <item>Unpack a copy of the tarball in a private + directory and make whatever changes are necessary to + get the port to compile properly under FreeBSD 2.0. + Keep <em>careful track</em> of everything you do, as + you will be automating the process shortly. + Everything, including the deletion, addition or + modification of files should be doable using an + automated script or patch file when your port is + finished. If your port requires significant user + interaction/customization to compile or install, you + should take a look at one of Larry Wall's classic + Configure scripts and perhaps do something similar + yourself. The goal of the new ports collection is to + make each port as `plug-and-play' as possible for the + end-user while using a minimum of disk space. + + <item>Carefully consider the list of patches, shell + commands or user queries necessary for customizing + the port, then, making sure you understand the + following thoroughly, go for it. The sequence of + events you need to understand is that which occurs + when the user first types `<tt>make</tt>' in your + port's directory, and you may find that having + <tt>bsd.port.mk</tt> in another window while you read + this really helps to understand it: + + Sequence of events: + + <enum> + <item>The pre-fetch and fetch targets are run. The + fetch target is responsible for making sure that + the tarball exists locally in <tt>${DISTDIR}</tt>. + The pre-fetch target hook is optional. If fetch + cannot find the required files in + <tt>${DISTDIR}</tt> it will look up the URL + <tt>${MASTER_SITES}</tt>, which can be set in the + Makefile or allowed to default to the Walnut + Creek CDROM archive site. It will then attempt + to fetch the named distribution file with + <tt>${NCFTP}</tt>, assuming that the requesting + site has direct access to the Internet. If that + succeeds, it will save the file in + <tt>${DISTDIR}</tt> for future use and proceed. + + <item>The pre-extract target hook, if it exists, is + run. + + <item>The extract target, if not disabled, is run. + It looks for your ports' distribution file in + <tt>${DISTDIR}</tt> (typically a gzip'd + tarball) and unpacks it into a temporary + directory. + + <item>The pre-configure target hook is run. + + <item>The configure target is run. This can do any + one of many different things. First, if any + patches are found in the + <tt>${PATCHDIR}</tt> subdirectory, they + are applied at this time in alphabetical order. + Next, a series of scripts, if detected, are run + in the following order: + + <enum> + + <item><tt>${SCRIPTDIR}/pre-configure</tt> + + <item><tt>${SCRIPTDIR/configure</tt> or + <tt>${WRKSRC}/configure</tt> if + <tt>${HAS_CONFIGURE}</tt> is set. + + <item>If <tt>${USE_IMAKE}</tt> is set, an + xmkmf command is done. + + <item><tt>${SCRIPTDIR}/post-configure</tt> + </enum> + + As you can see, it's possible to do just about anything to your + port, in a variety of stages! + + <item>The pre-build target hook is run. + + <item>The build target is run. This is responsible + for decending into the ports' private working + directory (<tt>${WRKSRC}</tt>) and + building it. If <tt>${USE_GMAKE}</tt> is + set, GNU <tt>make</tt> will be used, otherwise + the system <tt>${MAKE}</tt>. + </enum> + + <item>In the preparation of the port, files that have + been added or changed can be picked up with a + recursive diff for later feeding to patch. This is + the easiest kind of change to make as it doesn't + involve any mucking around with configuration files. + Each set of patches you wish to apply should be + collected into a file named + "<tt>patch-<xx></tt>" where <tt><xx></tt> + denotes the sequence in which the patches will be + applied - these are done in <em>alphabetical + order</em>, thus "<tt>aa</tt>" first, "<tt>ab</tt>" + second and so on. These files should be stored in + <tt>${PATCHDIR}</tt>, from where they will be + automatically applied. All patches should be + relative to <tt>${WRKSRC}</tt> (generally the + directory your port's tarball unpacks itself into, + that being where the make is done). + + <item>Include any additional customization commands to + your `<tt>configure</tt>' script and save it to + <tt>${SCRIPTDIR}/configure</tt>. Add your + port to the Makefile one level above it so that it + will be made automatically. + + <item>Always try to install relative to + <tt>${PREFIX}</tt> in your Makefiles. This will + normally be set to <tt>/usr/local</tt>, though it can be can + be reassigned in your Makefile or in the users + environment. Not hardcoding <tt>/usr/local</tt> anywhere in + your installation will make the port much more + flexible and cater to the needs of other sites. Note + that this doesn't count for package `packing list' + files since they have their own scheme for relocating + themselves and can be left independant of + <tt>${PREFIX}</tt> unless the package is one that + hardcodes itself to a compiled-in location. + + <item>If your port requires user input to build, + configure or install, then set + <tt>IS_INTERACTIVE</tt> in your Makefile. This will + allow "overnight builds" to progress past your port + if the user sets the variable <tt>BATCH</tt> in his + environment (and if the user sets the variable + <tt>INTERACTIVE</tt>, then <em>only</em> those ports + requiring interaction are built). + + For more details on any of this (since it may not be + clear at first reading), examine an existing port and + read the contents of <tt>/usr/share/mk/bsd.port.mk</tt>; + you'll see that it's not as difficult as it sounds! + + </enum> + +<sect1> + <heading>Configuring the Makefile</heading> + + <p>Configuring the Makefile is pretty simple, and again I + suggest that you look at existing examples before + starting. Consider the following problems in sequence as + you design your new Makefile: + + <enum> + <item>Does it live in <tt>${DISTDIR}</tt> as a + standard gzip'd tarball? If so, you can go on to the + next step. If not, you should look at overriding any + of the <tt>${EXTRACT_CMD}</tt>, + <tt>${EXTRACT_ARGS}</tt>, + <tt>${EXTRACT_SUFX}</tt>, or + <tt>${DISTFILE}</tt> variables, depending on + how alien a format your port's distribution file is. + In the worst case, you can simply create your own + `<tt>extract</tt>' target to override the default, + though this should be rarely, if ever, necessary. If + you do find it necessary to do your own, your extract + target should take care to "leave tracks" for itself + so that files are not unnecessarily extracted + twice---see the default extract rule in + <tt>bsd.port.mk</tt> for an example of this. + + <item>If your port is integrated into the ports + directory directly (original sources are already part + of FreeBSD), you may also consider simply setting + <tt>NO_EXTRACT</tt> and dispensing with the idea of a + distribution file altogether. + + <item>You should set <tt>${DISTNAME}</tt> to be the base + name of your port. The default rules expect the + distribution file list (<tt>${DISTFILES}</tt>) to be + named + <tt>${DISTDIR}/${DISTFILE}${EXTRACT_SUFX}</tt> + by default which, if it's a normal tarball, is going + to be something like: +<tscreen><verb> +foozolix-1.0.tar.gz +</verb></tscreen> + For a setting of "<tt>DISTNAME=foozolix-1.0</tt>" + + The default rules also expect the tarball(s) to + extract into a subdirectory called + <tt>${WRKDIR}/${DISTNAME}</tt>, e.g. +<tscreen><verb> +"<blah>/foozolix-1.0/" +</verb></tscreen> + + All this behavior can be overridden, of course, it + simply represents the most common time-saving + defaults. For a port requiring multiple distribution + files, simply set <tt>${DISTFILES}</tt> explicitly. If + only a subset of <tt>${DISTFILES}</tt> are actual + extractable archives, then set them up in + <tt>${EXTRACT_ONLY}</tt>, which will override the + <tt>${DISTFILES}</tt> list when it comes to extraction. + + <item>If your package uses GNU <tt>make</tt>, set + "<tt>USE_GMAKE=yes</tt>". If your package uses GNU + <tt>configure</tt>, set "<tt>GNU_CONFIGURE=yes</tt>". + If you want to override the default GNU <tt>configure</tt> + arguments from `<tt>i386--freebsd</tt>' to something else, + set those arguments in <tt>${GNU_CONFIGURE_ARGS}</tt>. + + If your package uses <tt>imake</tt> (e.g. is an X + application that has an <tt>Imakefile</tt>), then set + "<tt>USE_IMAKE=yes</tt>". This will cause the + configure stage to automatically do an <tt>xmkmf</tt> and then + a `<tt>make Makefiles</tt>'. + + <item>If you have a URL pointing at the the original + tarball, record the directory containing the tarball + in <tt>${MASTER_SITES}</tt>. This will provide a + backup site, as well as a direct pointer to the + original source location. + + The make macros will currently try to use this + specification for grabbing the distribution file with + <tt>${NCFTP}</tt> if they can't find it + already on the system. See some of the other ports + for examples. + + <item>Due to a problem in some of the ports, 2.0 was + distributed with a setting which meant ports that + have <tt>${USE_IMAKE}</tt> set do not install their + manpages by default. Although -current has the logic + reversed, for compatability with 2.0 systems (at + least until 2.1 comes out) you should set + "<tt>INSTALL_MANPAGES=yes</tt>". For complete forward + compatability, if the port doesn't understand the + "<tt>install.man</tt>" target, "<tt>NO_INSTALL_MANPAGES=yes</tt>" + should be set (which conforms with the current logic + in <tt>bsd.port.mk</tt>) + + <item>Don't forget to include + <tt><bsd.port.mk></tt> at the bottom. That + should do it! + + </enum> + +<sect1> + <heading>Do's and Dont's</heading> + + <p><enum> + + <item>Don't leave anything valuable lying around in + <tt>${WRKDIR}</tt>, `<tt>make clean</tt>' will + <em>nuke</em> it completely! If you need auxilliary + files that aren't scripts or patches, put them in + <tt> ${FILESDIR}</tt>. + + <item>Do install package information, if possible. It + would sure be nice if `<tt>make package</tt>' worked + for the whole ports tree this time. + + <item>Do look at existing examples and the + <tt>bsd.port.mk</tt> file before asking me questions! + ;-) + + <item>Do ask me questions if you have any trouble! + Don't just beat your head against a wall! :-) + + <item>Don't rely on custom utilities in your local + configure script---they may not be there on the + user's system! If you really need something else to + be installed before you can work, detect this from + your configure script, print a helpful message and + exit with a non-zero status! At least you'll have + given the user some idea of what's needed. If the + custom utility or package is actually part of the + ports tree, then set a pointer to it in your + <tt>DEPENDS</tt> variable---the port structure will + ensure that all <tt>DEPENDS</tt> targets are built + first. + + <item>Do send applicable changes/patches to the + original author/maintainer for inclusion in next + release of the code. This will only make your job + that much easier for the next release. + + </enum> + diff --git a/handbook/ports.sgml b/handbook/ports.sgml new file mode 100644 index 0000000000..702c232225 --- /dev/null +++ b/handbook/ports.sgml @@ -0,0 +1,240 @@ +<!-- $Id: ports.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>The Ports collection</heading> + +<p><em>Contributed by &a.gpalmer; and &a.jkh;.</em> + + Unfortunately, there are more variations of UN*X than most people +know of, and hence not all software for UN*X available on the Internet +will work on all versions of UN*X (in fact, I can guarantee it!). +Hence, some software needs modifications to work under some UN*Xs. The +process of making those modifications is known as ``porting'' and the +result known as a ``port'' (not to be confused with the sockets on the +back of your computer!). + + +<sect1><heading>What is the FreeBSD Ports Collection?</heading> + +<p> People who (allegedly) know what they are doing have automated the +process of ``porting'' software to FreeBSD, and the result is the +Ports Collection. The general idea is that a combination of various +programming tools available in the base FreeBSD installation will +allow you to fetch the port from a FreeBSD mirror site, type ``make'' +and get the fully working program. + + The ports collection itself normally doesn't have any of the +original source code necessary for the compilation in the tree, just +those shell scripts, Makefiles and source code ``diffs'' that are +necessary to compile the program under FreeBSD. This is meant to keep +the entire system down to a manageable size, and the current system +has over 100 ports in the master source tree, and yet a compressed tar +file of that tree is about 2 megabytes (all the source code needed is +over 100Mb's!). + + +<sect1><heading>How does the system compile with no source code?</heading> + +<p> A ports' Makefile automatically looks in a central location on +your system (usually /usr/ports/distfiles, though this value can be +customized) for the associated set of original distribution files that +have been ``ported''. These are generally provided at various places +on the Internet, though if you have a CDROM distribution of FreeBSD +then you've already got them available on your CD for ease of use. +See section 3.1 if you have such a CD distribution, otherwise skip to +section 3.2. + +<!-- +3.1 Compiling ports from CD + + Type something profound here. +--> + +<sect2><heading>Compiling ports using an Internet connection</heading> + +<p> The ports collection can also use an auto-fetch system to keep +your ports collection source tree up to date, updating the central +``distfiles'' version for you the next time you compile the port. + + Of course, this always assumes you have a permanent network link, +or don't mind heavy usage of your telephone. If you don't want heavy +network usage when you compile your ports tree, you can pre-fetch the +necessary tarballs beforehand and put them into /usr/ports/distfiles +(or wherever DISTDIR points) by hand. A good way to see what files a +port is going to need is to cd to that port's directory and do a +``make -n fetch'' to see what it does. + + You can also chose to get the source files either from the master +FTP site as defined in the relevant Makefile (in the MASTER_SITES +line), or some FreeBSD mirror site also carrying a set of distfiles, +as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in +the directory /pub/FreeBSD/ports/distfiles. Note that the files in +that directory are not guarenteed to be kept up to date - this is a +volunteer project! We can't make any guarantees about the mirror +sites either - they are obviously under independant control and don't +even have to mirror the distfiles directory. + + If you have a non-permanant link, you can fetch all the distfiles by +going to the top of the tree and typing ``make fetch''. + + +<sect1><heading>It doesn't work?!</heading> + +<p>Oh. You can do one of four (4) things : +<enum> + +<item> Fix it yourself. Technical details can be found in the GUIDELINES file, + available from URL ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES + +<item> Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are + in no way responsible for the functionality (or lack thereof) of the + FreeBSD system as a whole, and especially the ports system, which + is mainly contributed by 3rd parties. (If you don't believe me, check + the catalogue, especially the line saying "We cannot offer tech-support + on this product") + + The e-mail address is Ports@FreeBSD.org. Please include details of + the port, where you got both the port source & distfile(s) from, and + what the error was. + + Note: At time of writing, lang/Sather doesn't seem to work on Pentium + machines due to the Intel Curse (aka the Floating Point Division Bug). + Please don't tell us about this - gripe to Intel instead - it's their + bug! + +<item> Forget it. This is the easiest for most - very few of the programs in + ports can be classed as `essential'! + +<item> Grab the pre-compiled package from a ftp server. The ``master'' package + collection is in: + ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/ + + though check your local mirror first, please! + + These are more likely to work (on the whole) than trying to compile from + source, and a lot faster! +</enum> + +<sect1><heading>I've ported a program and I want to make a port out of it. What now?</heading> + +<p> See the file GUIDELINES, in: + ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES + This contains details of the procedure and structure involved. + + +<sect1><heading>I've got a good port, what now?</heading> + +<p> Upload the fixed version to freefall.cdrom.com /pub/incoming or +ftp.FreeBSD.org /pub/FreeBSD/incoming and send e-mail to +ports@FreeBSD.org with the filename and details. Someone on the +all-volunteer `ports committee' will (hopefully) look it over and +commit it to the ports collection if they like the looks of it. + + +<sect1><heading>Things go funny during the fetch stage of compilation!</heading> + +<p> We know. Please don't blame us. There is a program called `ncftp' +which is used instead of the normal ftp as it can do so-called +``background'' or ``batch'' transfers, ideal for this situation. +Unfortunately it can do strange things, and has crashed at least one +machine (during circumstances stranger than most, I'll admit, but it +was still responsible). Hopefully a future release of ncftp will fix +these problems (it is not maintained by the main FreeBSD team, but a +third party, who is I believe aware of its shortcomings) + + +<sect1><heading>I want to leave the compile going overnight, but some ports don't like this.</heading> + +<p> There is a way around this. Before starting the compilation, type: +<verb> + setenv BATCH yes # (if you use csh/tcsh) or + BATCH=yes # (for sh/bash) +</verb> + This should miss out ports which need user interaction. Unfortunately, +ncftp doesn't know about this trick, and can often screw up and ask +stupid questions in unattended batch mode. See (7). + + To compile those ports left out by doing the above, using a +different login shell (or unsetting the above BATCH variable), set the +INTERACTIVE variable instead (you can use the same statements as above +except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This +should now compile only those ports which will definitely ask for user +interaction. + + +<sect1><heading>The ports collection is weak. What can I do to help?</heading> + +<p> First read the bsd.port.mk file (which may be found in +/usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of +the weirdness can be explained properly in there (most of the current +weirdness is due to the lack of assumptions about anything, which is +necessary due to the generic nature of these files). Also check that +you have an up-to-date copy, as the file can change from minute to +minute. A reasonably up-to-date copy can be found in: + + <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> + + If you find that you still need to go in there and alter things, +by all means do so, and then send the diffs to ports@FreeBSD.org if +you'd like them to be a part of the default distribution. Please also +remember that any changes must respect backwards-compatability with +any and all older Makefiles, unless you want a real nightmare of +/usr/ports munging ahead of you! Large scale changes will generally +not be warmly welcomed unless all the existing makefiles work without +alteration. Sorry! + + +<sect1><heading>This FAQ is weak. What can I do?</heading> + +<p> Send changes to ports@FreeBSD.org. Changes are most welcome! +This FAQ is also very green and should be considered no more than +a `good start' for now. Authors? You can come out of hiding any +time now! :-) + + +<sect1><heading>How do I get more information on all the ports?</heading> + +<p> One good method is to cd to the top of the ports tree (say /usr/ports) +and type something like: +<verb> + make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 +</verb> +The ``make describe'' will try to extract the one-line description from +each port, and the ``sed'' will delete the extraneous output. ``expand'' +just makes it a little more readable (sort of - you may want to season +the output of this more to taste). + + +<sect1><heading>I've heard of a new checksum system. What is this for?</heading> + +<p> For various reasons, when using FTP over the Internet to obtain the +source code, you may not always end up with the same copy of the code +that the origional porter worked from, and this can lead to problems. +So a simple checksumming system has been employed to try and highlight +problems in this area. + + To check the entire system, go to the top of the ports tree +(defaults to /usr/ports) and type +<verb> + make checksum +</verb> +This will give a report on the validity of the files you have FTP'd. If some +are missing, the system will attempt to retrieve them before running the +checksum routine. The same technique can be applied to a single port. + + The system will complain if there is no pre-computed checksum available +for that port. Not all ports currently have checksums, but this should be +cured soon. + + Some older versions of the system don't recognise the ``checksum'' +target. In that case, try the command +<verb> + make check-md5 +</verb> +(``check-md5'' was the pre-cursor to the ``checksum'' target). If neither +work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from + + <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> + +and install them in /usr/share/mk. This will get you the latest version +of the ports system. diff --git a/handbook/ppp.sgml b/handbook/ppp.sgml new file mode 100644 index 0000000000..92d82bc289 --- /dev/null +++ b/handbook/ppp.sgml @@ -0,0 +1,372 @@ +<!-- $Id: ppp.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Setting up a PPP link</heading> + +<p><em>Contributed by &a.gena;.</em> + +Before you start setting up PPP on your machine make +sure that pppd is located in /usr/sbin and directory /etc/ppp +exists. + +pppd can work in two modes: +<enum> +<item> as a "client" , i.e. you want to connect your machine to outside +world via PPP serial connection or modem line. + +<item> as a "server" , i.e. your machine is located on the network and +used to connect other computers using PPP. +</enum> +In both cases you will need to set up an options file ( /etc/ppp/options +or ~/.ppprc if you have more then one user on your machine that uses +PPP ). + +You also will need some modem/serial software ( preferably kermit ) +so you can dial and establish connection with remote host. + +<sect1><heading>Working as a PPP client</heading> + +<p>I used the following /etc/ppp/options to connect to CISCO terminal server PPP +line. +<verb> +crtscts # enable hardware flow control +modem # modem control line +noipdefault # remote PPP server must supply your IP address. + # if the remote host doesn't send your IP during IPCP + # negotiation , remove this option +passive # wait for LCP packets +domain ppp.foo.com # put your domain name here + +:<remote_ip> # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <local_ip>:<remote_ip> + +defaultroute # put this if you want that PPP server will be your + # default router +</verb> + +To connect: +<enum> +<item> Dial to the remote host using kermit ( or other modem program ) +enter your user name and password ( or whatever is needed to enable PPP +ont the remote host ) + +<item> Exit kermit. ( without hanging up the line ) + +<item> enter: +<verb> +/usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200 +</verb> +( put the appropriate speed and device name ) +</enum> + +Now your computer is connected with PPP. If the connection fails for some +reasons you can add the "debug" option to the /etc/ppp/options file +and check messages on the console to track the problem + +Following /etc/ppp/pppup script will make all 3 stages automatically: +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.dial +pppd /dev/tty01 19200 +</verb> + +/etc/ppp/kermit.dial is kermit script that dials and makes all +necessary authorization on the remote host. +( Example of such script is attached to the end of this document ) + +Use the follwing /etc/ppp/pppdown script to disconnect the PPP line: +<verb> +#!/bin/sh +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill -TERM ${pid} +fi + +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +/sbin/ifconfig ppp0 down +/sbin/ifconfig ppp0 delete +kermit -y /etc/ppp/kermit.hup +/etc/ppp/ppptest +</verb> + +Check if PPP is still running (/usr/etc/ppp/ppptest): +<verb> +#!/bin/sh +pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'pppd running: PID=' ${pid-NONE} +else + echo 'No pppd running.' +fi +set -x +netstat -n -I ppp0 +ifconfig ppp0 +</verb> + +Hangs up modem line (/etc/ppp/kermit.hup): +<verb> +set line /dev/tty01 ; put your modem device here +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +echo \13 +exit +</verb> + +<sect1><heading>Working as a PPP server</heading> + +<p>/etc/ppp/options: +<verb> +crtscts # Hardware flow control +netmask 255.255.255.0 # netmask ( not required ) +192.114.208.20:192.114.208.165 # ip's of local and remote hosts + # local ip must be different from one + # you assigned to the ethernet ( or other ) + # interface on your machine. + # remote IP is ip address that will be + # assigned to the remote machine +domain ppp.foo.com # your domain +passive # wait for LCP +modem # modem line +</verb> + +Following /etc/ppp/pppserv script will enable ppp server on your machine +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +# reset ppp interface +ifconfig ppp0 down +ifconfig ppp0 delete + +# enable autoanswer mode +kermit -y /etc/ppp/kermit.ans + +# run ppp +pppd /dev/tty01 19200 +</verb> + +Use this /etc/ppp/pppservdown script to stop ppp server: +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.noans +</verb> + +Following kermit script will enable/disable autoanswer mode +on your modem (/etc/ppp/kermit.ans): +<verb> +set line /dev/tty01 +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +inp 5 OK +echo \13 +out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable + ; autoanswer mod +inp 5 OK +echo \13 +exit +</verb> + +This /etc/ppp/kermit.dial script is used for dialing and authorizing on remote host. +You will need to customize it for your needs. +Put your login and password in this script , also you'll need +to change input statement depending on responces from your modem +and remote host. +<verb> +; +; put the com line attached to the modem here: +; +set line /dev/tty01 +; +; put the modem speed here: +; +set speed 19200 +set file type binary ; full 8 bit file xfer +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none +set modem hayes +set dial hangup off +set carrier auto ; Then SET CARRIER if necessary, +set dial display on ; Then SET DIAL if necessary, +set input echo on +set input timeout proceed +set input case ignore +def \%x 0 ; login prompt counter +goto slhup + +:slcmd ; put the modem in command mode +echo Put the modem in command mode. +clear ; Clear unread characters from input buffer +pause 1 +output +++ ; hayes escape sequence +input 1 OK\13\10 ; wait for OK +if success goto slhup +output \13 +pause 1 +output at\13 +input 1 OK\13\10 +if fail goto slcmd ; if modem doesn't answer OK, try again + +:slhup ; hang up the phone +clear ; Clear unread characters from input buffer +pause 1 +echo Hanging up the phone. +output ath0\13 ; hayes command for on hook +input 2 OK\13\10 +if fail goto slcmd ; if no OK answer, put modem in command mode + +:sldial ; dial the number +pause 1 +echo Dialing. +output atdt9,550311\13\10 ; put phone number here +assign \%x 0 ; zero the time counter + +:look +clear ; Clear unread characters from input buffer +increment \%x ; Count the seconds +input 1 {CONNECT } +if success goto sllogin +reinput 1 {NO CARRIER\13\10} +if success goto sldial +reinput 1 {NO DIALTONE\13\10} +if success goto slnodial +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 60 goto look +else goto slhup + +:sllogin ; login +assign \%x 0 ; zero the time counter +pause 1 +echo Looking for login prompt. + +:slloop +increment \%x ; Count the seconds +clear ; Clear unread characters from input buffer +output \13 +; +; put your expected login prompt here: +; +input 1 {Username: } +if success goto sluid +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 10 goto slloop ; try 10 times to get a login prompt +else goto slhup ; hang up and start again if 10 failures + +:sluid +; +; put your userid here: +; +output ppp-login\13 +input 1 {Password: } +; +; put your password here: +; +output ppp-password\13 +input 1 {Entering SLIP mode.} +echo +quit + +:slnodial +echo \7No dialtone. Check the telephone line!\7 +exit 1 + +; local variables: +; mode: csh +; comment-start: "; " +; comment-start-skip: "; " +; end: +</verb> + +<!-- +################################################################### +Gennady B. Sorokopud ( gena@NetVision.net.il ) 24/10/94 12:00 +--> + diff --git a/handbook/scsi.sgml b/handbook/scsi.sgml new file mode 100644 index 0000000000..babcd0db8e --- /dev/null +++ b/handbook/scsi.sgml @@ -0,0 +1,688 @@ +<!-- $Id: scsi.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<!-- + <title>An introduction to SCSI and its use with FreeBSD</title> + <author>(c) 1995, Wilko Bulte, <tt/wilko@yedi.iaf.nl/ + <date>V0.2, Thu Apr 20 22:45:23 MET DST 1995</date> + Copyright 1995, W. C. Bulte, Arnhem, The Netherlands + + <abstract> + This document attempts to describe the background of SCSI, its + (mis)use with FreeBSD and some common pitfalls. + </abstract> + +--> + <sect><heading>SCSI</heading> + + <p><em>© 1995, &a.wilko;.</em> + + SCSI is an acronym for Small Computer Systems Interface. It is an + ANSI standard that has become one of the leading I/O buses in the + computer industry. The foundation of the SCSI standard was laid by + Shugart Associates (the same guys that gave the world the first + mini floppy disks) when they introduced the SASI bus (Shugart Associates + Standard Interface). + + After some time an industry effort was started to come to a more strict + standard allowing devices from different vendors to work together. + This effort was recognised in the ANSI SCSI-1 standard. The SCSI-1 + standard (approx 1985) is now more or less obsolete. The current + standard is SCSI-2 (see <ref id="further-reading" name="Further + reading">), with SCSI-3 on the drawing boards. + + In addition to a physical interconnection standard, SCSI defines a + logical (command set) standard to which disk devices must adhere. + This standard is called the Common Command Set (CCS) and was + developed more or less in parallel with ANSI SCSI-1. SCSI-2 + includes the (revised) CCS as part of the standard itself. The + commands are dependent on the type of device at hand. It does not + make much sense of course to define a Write command for a + scanner... + + The SCSI bus is a parallel bus, which comes in a number of + variants. The oldest and most used is an 8 bit wide bus, with + single-ended signals, carried on 50 wires. (If you don't know what + single-ended means, don't worry, that is what this document is all + about.) Modern designs also use 16 bit wides buses, with + differential signals. This allows transfer speeds of + 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 + allows a maximum buswidth of 32 bits, using an additional cable. + + Of course the SCSI bus not only has data lines, but also a number + of control signals. A very elaborate protocol is part of the + standard to allow multiple devices to share the bus in an efficient + manner. In SCSI-2, the data is always checked using a seperate + parity line. In pre-SCSI-2 designs parity was optional. + + In SCSI-3 even faster bustypes are introduced, along with a serial + SCSI bus that reduces the cabling overhead and allows a higher + maximum buslength. + + As you could have guessed from the description above, SCSI devices + are intelligent. They have to be to adhere to the SCSI standard + (which is over 2 inches thick BTW). So, for a hard disk drive for + instance you do not specify a head/cylinder/sector to address a + particular block, but simply the number of the block you want. + Elaborate caching schemes, automatic badblock replacement etc + are all made possible by this 'intelligent device' approach. + + On a SCSI bus, each possible pair of devices can communicate. If + their function allows this is another matter, but the standard does + not restrict it. To avoid signal contention, the 2 devices have to + arbitrate for the bus before using it. + + The philosophy of SCSI is to have a standard that allows + older-standard devices to work with newer-standard ones. So, an + old SCSI-1 device should normally work on a SCSI-2 bus. Normally, + because it is not absolutely sure that the implementation of an old + device follows the (old) standard closely enough to be acceptable + on a new bus. Modern devices are usually more well-behaved, + because the standardisation has become more strict and is better + adhered to by the device manufacturers. Generally speaking, the + chances of getting a working set of devices on a single bus is + better when all the devices are SCSI-2 or newer. This does not + imply that you have to dump all your old stuff when you get that + shiny 2Gb disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2 + QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks + work together quite happily. + + <sect1>Concepts of SCSI + <p> + <sect2>A <it>smart</it> interface + <p> + As said before, SCSI devices are smart. The idea is to put the + knowledge about intimate hardware details onto the SCSI device + itself. In this way, the host system does not have to worry + about things like how many heads are hard disks has, or how many + tracks there are on a specific tape device. If you are curious, + the standard specifies commands with which you can query your + devices on their hardware particulars. + + The advantage of intelligent devices is obvious: the device + drivers on the host can be made in a much more generic fashion, + there is no longer a need to change (and qualify!) drivers for + every odd new device that is introduced. + + <sect2>Do's and don't's on interconnections + <p> + For cabling and connectors there is a golden rule: get good + stuff. With bus speeds going up all the time you will save + yourself a lot of grief by using good material. + + So, gold plated connectors, shielded cabling, sturdy connector + hoods with strain reliefs etc are the way to go. Second golden + rule: don't use cables longer than necessary. I once spent 3 days + hunting down a problem with a flaky machine only to discover that + shortening the SCSI bus with 1 meter solved the problem. And the + original bus length was well within the SCSI specification. + <sect2>SCSI bus types + <p> + From an electrical point of view, there are two Incompatible bus + types: single-ended and differential. This means that there are + two different main groups of SCSI devices and controllers, which + cannot be mixed on the same bus. It is possible however to use + special converter hardware to transform a single-ended bus into a + differential one (and vice versa). The differences between the + bus types are explained in the next sections. + + In lots of SCSI related documentation there is a sort of jargon + in use to abbreviate the different bus types. A small list: + + <itemize> + <item>FWD: Fast Wide Differential + <item>FND: Fast Narrow Differential + <item>SE: Single Ended + <item>FN: Fast Narrow + <item>etc. + </itemize> + + With a minor amount of imagination one can usually imagine what + is meant. + + Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As + far as I know, the 32 bit variant is not (yet) in use, so wide + normally means 16 bit. + + Fast means that the timing on the bus is somewhat different, so + that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead + of 5 Mbytes/sec for 'slow' SCSI. More on this later. + + It should be noted that the datalines > 8 are only used for + datatransfers and device addressing. The transfers of commands + and status messages etc are only performed on the lowest 8 + datalines. The standard allows narrow devices to operate on + a wide bus. The usable buswidth is negotiated + between the devices. You have to watch your device addressing + closely when mixing wide and narrow. + + <sect3>Single ended buses + <p> + A single-ended SCSI bus uses signals that are either 5 Volts or + 0 Volts (indeed, TTL levels) and are relative to a COMMON + ground reference. A singled ended 8 bit SCSI bus has + approximately 25 ground lines, who are all tied to a single + 'rail' on all devices. A standard single ended bus has a + maximum length of 6 meters. If the same bus is used with + fast-SCSI devices, the maximum length allowed drops to 3 + meters. Fast-SCSI means that instead of 5Mbytes/sec the bus + allows 10Mbytes/sec transfers. + + Please note that this means that + if some devices on your bus use 'fast' to communicate your + bus must adhere to the length restrictions for fast buses! + + It is obvious that with the newer fast-SCSI devices the + buslength can become a real bottleneck. This is why the + differential SCSI bus was introduced in the SCSI-2 standard. + + For connector pinning and connector types please refer to the + SCSI-2 standard (see <ref id="further-reading" name="Further + reading">) itself, connectors etc are listed there in + painstaking detail. + + Beware of devices using non-standard cabling. For instance + Apple uses a 25pin D-type connecter (like the one on serial + ports and parallel printers). Considering + that the official SCSI bus needs 50 pins you can imagine + the use of this connector needs some 'creative cabling'. + The reduction of the number of ground wires they used + is a bad idea, you better stick to 50 pins cabling + in accordance with the SCSI standard. + + <sect3>Differential buses + <p> + A differential SCSI bus has a maximum length of 25 + meters. Quite a difference from the 3 meters for a single-ended + fast-SCSI bus. The idea behind differential signals is that + each bus signal has it's own return wire. So, each signal is + carried on a (preferably twisted) pair of wires. The voltage + difference between these two wires determines whether the + signal is asserted or de-asserted. To a certain extent the + voltage difference between ground and the signal wire pair is + not relevant (don't try 10 kVolts though..). + + It is beyond the scope of this document to explain why this + differential idea is so much better. Just accept that + electrically seen the use of differential signals gives a much + better noise margin. You will normally find differential buses + in use for inter-cabinet connections. Because of the lower cost + single ended is mostly used for shorter buses like inside + cabinets. + + There is nothing that stops you from using differential stuff + with FreeBSD, as long as you use a controller that has device + driver support in FreeBSD. As an example, Adaptec marketed the + AH1740 as a single ended board, whereas the AH1744 was differential. + The software interface to the host is identical for both. + + <sect3>Terminators + <p> + Terminators in SCSI terminology are resistor networks that are + used to get a correct impedance matching. Impedance matching + is important to get clean signals on the bus, without + reflections or ringing. If you once made a long distance + telephone call on a bad line you probably know what reflections + are. With 20Mbytes/sec travelling over your SCSI bus, you + don't want signals echoing back. + + Terminators come in various incarnations, with more or less + sophisticated designs. Of course, there are internal and + external variants. Almost every SCSI device comes with a + number of sockets in which a number of resistor networks can + (must be!) installed. If you remove terminators from a device, + carefully stock 'm. You will need them when you ever decide to + reconfigure your SCSI bus. There is enough variation in even + these simple tiny things to make finding the exact replacement + a frustrating business. There are also SCSI devices that have + a single jumper to enable or disable a builtin terminator. + There are special terminators you can stick onto a flatcable + bus. Others look like external connectors, so a connector hood + without a cable. So, lots of choice as you can see. + + There is much debate going on if and when you should switch + from simple resistor (passive) terminators to active + terminators. Active terminators contain more or less elaborate + circuits to give more clean bus signals. The general consensus + seems to be that the usefullnes of active termination increases + when you have long buses and/or fast devices. If you ever have + problems with your SCSI buses you might consider trying an + active terminator. Try to borrow one first, they reputedly are + quite expensive. + + Please keep in mind that terminators for differential and + single-ended buses are not identical. You should <bf>not + mix</bf> the two variants. + + OK, and now where should you install your terminators? This is + by far the most misunderstood part of SCSI. And it is by far + the simplest.. The rule is: <bf>every SCSI bus has 2 (two) + terminators, one at each end of the bus.</bf> So, two and not + one or three or whatever. Do yourself a favour and stick to + this rule. It will save you endless grief, because wrong + termination has the potential to introduce highly mysterious + bugs. + + A common pitfall is to have an internal (flat)cable in a + machine and also an external cable attached to the + controller. It seems almost everybody forgets to remove the + terminators from the controller. The terminator must now be on + the last external device, and not on the controller! In + general, every reconfiguration of a SCSI bus must pay attention + to this. + + What I did myself is remove all terminators from my SCSI + devices and controllers. I own a couple of external + terminators, for both the Centronics-type external cabling and + for the internal flat cable connectors. This makes + reconfiguration much easier. + + <sect3>Terminator power + <p> + The terminators discussed in the previous chapter need power to + operate properly. On the SCSI bus, a line is dedicated to this + purpose. So, simple huh? + + Not so. Each device can provide it's own terminator power to + the terminator sockets it has on-device. But if you have + external terminators, or when the device supplying the + terminator power to the SCSI bus line is switched off you are + in trouble. + + The idea is that initiators (these are devices that initiate + actions on the bus, a discussion follows) must supply + terminator power. All SCSI devices are allowed (but not + required) to supply terminator power. + + To allow for switched-off devices on a bus, the terminator + power must be supplied to the bus via a diode. This prevents + the backflow of current to switched-off devices. + + To prevent all kinds of nastiness, the terminator power is + usually fused. As you can imagine, fuses might blow. This can, + but does not have to, lead to a non functional bus. If multiple + devices supply terminator power, a single blown fuse will not + put you out of business. A single supplier with a blown fuse + certainly will. Clever external terminators sometimes have a + LED indication that shows whether terminator power is present. + + In newer designs auto-restoring fuses are used who 'reset' + themselves after some time. + + On modern devices, sometimes integrated terminators are + used. These things are special purpose integrated circuits that + can be dis/en-abled with a control pin. It is not necessary to + physically remove them from a device. You may find them on + newer host adapters, sometimes they even are software + configurable, using some sort of setup tool. Consult you + documentation! + + <sect3>Device addressing + <p> + Because the SCSI bus is, ehh, a bus there must be a way to + distinguish or address the different devices connected to it. + + This is done by means of the SCSI or target ID. Each device has + a unique target ID. You can select the ID to which a device + must respond using a set of jumpers, or a dipswitch, or + something similar. Consult the documentation of your device for + more information. + + Beware of multiple devices configured to use the same ID. Chaos + normally reigns in this case. + + For an 8 bit bus, a maximum of 8 targets is possible. The + maximum is 8 because the selection is done bitwise using the 8 + datalines on the bus. For wide this increases to the number of + datalines. + + The higher the SCSI target ID, the higher the priority the + devices has. When it comes to arbitration between devices that + want to use the bus at the same time, the device that has the + highest SCSI ID will win. This also means that the SCSI + hostadapter usually uses target ID 7 (for narrow buses). + + For a further subdivision, the standard allows for Logical + Units or LUNs for short. A single target ID may have multiple + LUNs. For example, a tape device including a tape changer may + have LUN 0 for the tape device itself, and LUN 1 for the + tapechanger. In this way, the host system can address each of + the parts of the tape unit as desired. + + <sect3>Bus layout + <p> + SCSI buses are linear. So, not shaped like Y-junctions, star + topologies, cobwebbs or whatever else people might want to + invent. + + You might notice that the terminator issue discussed earlier + becomes rather hairy if your bus is not linear.. + + The electrical characteristics, it's noise margins and + ultimately the reliability of it all are tightly related to + linear bus rule. + + <bf>Stick to the linear bus rule!</bf> + + <sect1>Using SCSI with FreeBSD + <p> + <sect2>About translations, BIOSes and magic.. + <p> + As stated before, you should first make sure that you have a + electrically sound bus. + + When you want to use a SCSI disk on your PC as boot disk, you + must aware of some quirks related to PC BIOSes. The PC BIOS in + it's first incarnation used a low level physical interface to the + harddisk. So, you had to tell the BIOS (using a setup tool or a + BIOS builtin setup) how your disk physically looked like. This + involved stating number of heads, number of cylinders, number of + sectors per track, obscure things like precompensation and + reduced write current cylinder etc. + + One might be inclined to think that since SCSI disks are smart + you can forget about this. Alas, the arcane setup issue is still + present today. The system BIOS needs to know how to access your + SCSI disk with the head/cyl/sector method. + + The SCSI host adapter or SCSI controller you have put in your + AT/EISA/PCI/whatever bus to connect your disk therefore has it's + own onboard BIOS. During system startup, the SCSI BIOS takes over + the harddisk interface routines from the system BIOS. To fool the + system BIOS, the system setup is normally set to No harddisk + present. Obvious, isn't it? + + The SCSI BIOS itself presents to the system a so called + <bf>translated</bf> drive. This means that a fake drive table is + constructed that allows the PC to boot the drive. This + translation is often (but not always) done using a pseudo drive + with 32 heads and 64 sectors per track. By varying the number of + cylinders, the SCSI BIOS adapts to the actual drive size. It is + useful to note that 32 * 64 / 2 = the size of your drive in + megabytes. The division by 2 is to get from disk blocks that are + normally 512 bytes in size to Kbytes. + + Right.. All is well now?! No, it isn't. The system BIOS has + another quirk you might run into. The number of cylinders of a + bootable harddisk cannot be greater than 1024. Using the + translation above, this is a showstopper for disks greater than + 1 Gb. With disk capacities going up all the time this is causing + problems. + + Fortunately, the solution is simple: just use another + translation, e.g. with 128 heads instead of 32. In most cases new + SCSI BIOS versions are available to upgrade older SCSI host + adapters. Some newer adapters have an option, in the form of a + jumper or software setup selection, to switch the translation the + SCSI BIOS uses. + + It is very important that <bf>all</bf> operating systems on the disk use + the <bf>same translation</bf> to get the right idea about where to find + the relevant partitions. So, when installing FreeBSD you must + answer any questions about heads/cylinders etc using the + translated values your host adapter uses. + + Failing to observe the translation issue might be un-bootable systems or + operating systems overwriting eachothers partitions. Using fdisk + you should be able to see all partitions. + + As promised earlier: what is this talk about 'lying' devices? As + you might already know, the FreeBSD kernel reports the geometry + of SCSI disks when booting. An example from one of my systems: + + <verb> +Feb 9 19:33:46 yedi /386bsd: aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> +Feb 9 19:33:46 yedi /386bsd: sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, + 53 sec, bytes/sec 512 + </verb> + + This info is retrieved from the SCSI disk itself. Newer disks + often use a technique called zone bit recording. The idea is that + on the outer cylinders of the drive there is more space so more + sectors per track can be put on them. This results in disks that + have more tracks on outer cylinders than on the inner cylinders + and, last but not least, have more capacity. You can imagine that + the value reported by the drive when inquiring about the geometry + now becomes fake. + + <sect2>SCSI subsystem design + <p> + FreeBSD uses a sort of layered SCSI subsystem. For each different + controller card a so called device driver is written. This driver + knows all the intimate details about the hardware it + controls. The driver has a interface to the upper layers of the + SCSI subsystem through which it receives it's commands and + reports back any status. + + On top of the card drivers there are a number of more generic + drivers for a class of devices. More specific: a driver for + tape devices (abbreviation: st), magnetic disks (sd), cdroms (cd) + etc. In case you are wondering where you can find this stuff, it + all lives in <tt>/sys/scsi</tt>. See the man pages in section 4 + for more details. + + The multi level design allows a decoupling of low-level bit + banging and more high level stuff. Adding support for another + piece of hardware is a much more managable problem. + + <sect2>Kernel configuration + <p> + Dependent on your hardware, the kernel configuration file must + contain a line which describes your hostadapter. This includes + I/O addresses, interrupts etc. Consult the man page for your + adapter driver to get more info. + + Although it is probably an obvious remark: the kernel config + file should reflect your actual hardware setup. So, interrupts, + I/O addresses etc must match the kernel config file. + + An example from the kernel config file (they live in + <tt>/sys/i386/conf</tt> BTW), with some added comments (between + []): + + <verb> +controller ahb0 at isa? bio irq 11 vector ahbintr [driver for Adaptec 174x] +controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Adaptec 154x] +controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr [for Seagate +ST01/02] +controller scbus0 + +device sd0 [support for 4 SCSI harddisks, sd0 up sd3] +device sd1 +device sd2 +device sd3 + +device st0 [support for 2 SCSI tapes] +device st1 + +device cd0 #Only need one of these, the code dynamically grows [for the cdrom] + </verb> + + So, the ahb driver is used for the Adaptec 1740, the aha driver + for the Adaptec 154x etc. If you have more than one card of the + same type in your system you get an ahb1, ahb2 line etc. + + The example above supports 4 SCSI disks. If during boot more + devices of a specific type (e.g. sd disks) are found than are + configured in the booting kernel, the system will complain. You + will have to build and boot a new kernel (after adapting the kernel + configuration file) before you can use all of the devices. It + does not hurt to have 'extra' devices in the kernel, the example + above will work fine when you have only 2 SCSI disks. + + Use <tt>man 4 scsi</tt> to check for the latest info on the SCSI + subsystem. For more detailed info on hostadapter drivers use eg + <tt>man 4 aha</tt> for info on the Adaptec 154x driver. + + <sect2>Tuning your SCSI kernel setup + <p> + Experience has shown that some devices are slow to respond to INQUIRY + commands after a SCSI bus reset. An INQUIRY command is sent by the kernel + on boot to see what kind of device (disk, tape, cdrom etc) is connected + to a specific target ID. This process is called device probing by the way. + + To work around this problem, FreeBSD allows a tunable delay time before + the SCSI devices are probed following a SCSI bus reset. You can set this + delaytime in your kernel configuration file using a line like: + + <verb> +options "SCSI_DELAY=15" #Be pessimistic about Joe SCSI device + </verb> + This line sets the delay time to 15 seconds. On my own system I had to + use 3 seconds minimum to get my trusty old CDROM drive to be recognised. + Start with a high value (say 30 seconds or so) when you have problems + with device recognition. If this helps, tune it back until it just stays + working. + + <sect2>Rogue SCSI devices + <p> + Although the SCSI standard tries to be complete and concise, it is + a complex standard and implementing things correctly is no easy task. + Some vendors do a better job then others. + + This is exactly where the 'rogue' devices come into view. Rogues are + devices that are recognised by the FreeBSD kernel as behaving slightly + (...) non-standard. Rogue devices are reported by the kernel when + booting. An example for two of my cartridge tape units: + + <verb> +Feb 25 21:03:34 yedi /386bsd: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> +Feb 25 21:03:34 yedi /386bsd: st0: Tandberg tdc3600 is a known rogue + +Mar 29 21:16:37 yedi /386bsd: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> +Mar 29 21:16:37 yedi /386bsd: st1: Archive Viper 150 is a known rogue + </verb> + + For instance, there are devices that respond to + all LUNs on a certain target ID, even if they are actually only one + device. It is easy to see that the kernel might be fooled into + believing that there are 8 LUNs at that particular target ID. The + confusion this causes is left as an exercise to the user. + + The SCSI subsystem of FreeBSD recognises devices with bad habits by + looking at the INQUIRY response they send when probed. Because the + INQUIRY response also includes the version number of the device + firmware, it is even possible that for different firmware versions + different workarounds are used. + + This scheme works fine, but keep in mind that it of course only + works for devices that are KNOWN to be weird. If you are the first + to connect your bogus Mumbletech SCSI cdrom you might be the one + that has to define which workaround is needed. + + <sect2>Busmaster host adapters + <p> + Most, but not all, SCSI host adapters are bus mastering controllers. + This means that they can do I/O on their own without putting load onto + the host CPU for data movement. + + This is of course an advantage for a multitasking operating system like + FreeBSD. It must be noted however that there might be some rough edges. + + For instance an Adaptec 1542 controller can be set to use different + transferspeeds on the host bus (ISA or AT in this case). The controller + is settable to different rates because not all motherboards can handle + the higher speeds. Problems like hangups, bad data etc might be the + result of using a higher data transfer rate then your motherboard + can stomach. + + The solution is of course obvious: switch to a lower data transfer rate + and try if that works better. + + In the case of a Adaptec 1542, there is an option that can be put + into the kernel config file to allow dynamic determination of the + right, read: fastest feasible, transfer rate. This option is + disabled by default: + + <verb> +options "TUNE_1542" #dynamic tune of bus DMA speed + </verb> + + Check the man pages for the host adapter that you use. Or better + still, use the ultimate documentation (read: driver source). + + <sect1>Tracking down problems + <p> + The following list is an attempt to give a guideline for the most + common SCSI problems and their solutions. It is by no means + complete. + + <itemize> + <item> + Check for loose connectors and cables. + <item> + Check and doublecheck the location and number of your terminators. + <item> + Check if your bus has at least one supplier of terminator power + (especially with external terminators. + <item> + Check if no double target IDs are used. + <item> + Check if at least one device provides terminator power to the bus. + <item> + Check if all devices to be used are powered up. + <item> + Make a minimal bus config with as little devices as possible. + <item> + If possible, configure your hostadapter to use slow bus speeds. + </itemize> + + <sect1><heading>Further reading<label id="further-reading"></> + <p> + If you intend to do some serious SCSI hacking, you might want to + have the official standard at hand: + + Approved American National Standards can be purchased from ANSI at + 11 West 42nd Street, 13th Floor, New York, NY 10036, Sales Dept: + (212) 642-4900. You can also buy many ANSI standards and most + committee draft documents from Global Engineering Documents, 15 + Inverness Way East, Englewood, CO 80112-5704, Phone: (800) + 854-7179, Outside USA and Canada: (303) 792-2181, FAX: (303) 792- + 2192. + + Many X3T10 draft documents are available electronically on the SCSI + BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site. + + Latest X3T10 committee documents are: + <verb> + AT Attachment (ATA or IDE) [X3.221-1994] Approved + ATA Extensions (ATA-2) [X3T10/948D Rev 2i] + Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] Approved + Small Computer System Interface - 2 (SCSI-2) [X3.131-1994] Approved + SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) + [X3T10/792D Rev 11] + </verb> + Other publications that might provide you with additional information are: + <verb> +"SCSI: Understanding the Small Computer System Interface", written by NCR +Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 +Phone: (201) 767-5937 ISBN 0-13-796855-8 + +"Basics of SCSI", a SCSI tutorial written by Ancot Corporation +Contact Ancot for availability information at: +Phone: (415) 322-5322 Fax: (415) 322-0455 + +"SCSI Interconnection Guide Book", an AMP publication (dated 4/93, Catalog +65237) that lists the various SCSI connectors and suggests cabling schemes. +Available from AMP at (800) 522-6752 or (717) 564-0100 + +"Fast Track to SCSI", A Product Guide written by Fujitsu. +Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 +Phone: (201) 767-5937 ISBN 0-13-307000-X + +"The SCSI Bench Reference", "The SCSI Encyclopedia", and the "SCSI Tutor", +ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070 +Phone: (408) 867-6642 + +"Zadian SCSI Navigator" (quick ref. book) and "Discover the Power of SCSI" +(First book along with a one-hour video and tutorial book), Zadian Software, +Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800 + </verb> + + On Usenet the newsgroups comp.periphs.scsi and comp.periphs are + noteworthy places to look for more info. You can also find the + SCSI-Faq there, which posted periodically. + + Most major SCSI device and hostadapter suppliers operate ftp sites + and/or BBS systems. They may be valuable sources of information + about the devices you own. diff --git a/handbook/slipc.sgml b/handbook/slipc.sgml new file mode 100644 index 0000000000..9787331388 --- /dev/null +++ b/handbook/slipc.sgml @@ -0,0 +1,196 @@ +<!-- $Id: slipc.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Setting up a SLIP client</heading> + +<p><em>Contributed by &a.asami;.</em> + +The following is one way to set up a FreeBSD machine for SLIP on a +static host network. For dynamic hostname assignments (i.e., your +address changes each time you dial up), you probably need to do +something much fancier. + +<!-- +This is just "what I did, and it worked for me". I'm sharing this +just for your reference, I'm no expert in SLIP nor networking so your +mileage may vary. +--> + +Note: for 1.1 systems (not 1.1.5), you need to use /dev/tty01 instead +of /dev/cua01. substitute all the occurences of "cua" in this document +with "tty". + +Note: the default 1.1.5(.1) system only comes with cua/ttyd pairs for +the last two ports (2 and 3), so if your modem is at sio0/sio1 +(COM1/COM2), you need to make the devices. Try "cd /dev; sh MAKEDEV +cua01" to make the new special files for sio1 (ditto for sio0). This +will delete tty01, but you shouldn't need it anymore...or you can make +a symbolic link /dev/tty01 -> ttyd1 if you don't want to hunt down all +occurences of tty01 in your setup files. + +I actually have a symbolic link /dev/modem -> cua01 (and /dev/mouse -> +ttyd0). I use only the modem/mouse names in my configuration files. +This helped a lot when I switched from 1.1 to 1.1.5.1 (tty01 => cua01) +and when I had to move my modem temporarily to sio2 to enable the +RS-232C port on the serial card. It can become quite cumbersome when +you need to fix a bunch of files in /etc and .kermrc's all over the +system! + +First, make sure you have +<verb> +pseudo-device sl 2 +</verb> +in your kernel's config file. It is included in the GENERIC, GENERICAH +and GENERICBT kernels, so this won't be a problem unless you deleted it. + +<sect1><heading>Things you have to do only once</heading> + +<p><enum> +<item> Add your home machine, the gateway and nameservers to your + /etc/hosts file. Mine looks like this: +<verb> +127.0.0.1 localhost loghost +136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia + +136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway +128.32.136.9 ns1.Berkeley.edu ns1 +128.32.136.12 ns2.Berkeley.edu ns2 +</verb> + By the way, silvia is the name of the car that I had when I was + back in Japan (it's called 2?0SX here in U.S.). + +<item> Make sure you have "hosts" before "bind" in your /etc/host.conf. + Otherwise, funny things may happen. + +<item> Edit the /etc/netstart and add this to the end of the file: +<verb> +# set up slip +gateway=slip-gateway +ifconfig sl0 inet $hostname $gateway netmask 0xffffff00 +route add default $gateway +</verb> + Note that because of the "slip-gateway" entry in /etc/hosts, there + is no local dependency in the netstart file. Also, you might want + to un-comment the "<verb>route add $hostname localhost</verb>" line. + +<item> Make a file /etc/resolv.conf which contains: +<verb> +domain HIP.Berkeley.EDU +nameserver 128.32.136.9 +nameserver 128.32.136.12 +</verb> + As you can see, these set up the nameserver hosts. Of course, the + actual addresses depend on your environment. + +<item> Set the password for root and toor (and any other accounts that + doesn't have a password). Use passwd, don't edit the passwd or + passwd.master files! + +<item> Edit /etc/myname and reboot the machine. +</enum> + + +<sect1><heading>Making a SLIP connection</heading> + +<p><enum> +<item> Dial up, type "slip" at the prompt, enter your machine name and + password. The things you need to enter depends on your + environment. I use kermit, with a script like this: +<verb> +# kermit setup +set modem hayes +set line /dev/cua01 +set speed 57600 +set parity none +set flow rts/cts +set terminal bytesize 8 +set file type binary +# The next macro will dial up and login +define slip dial 643-9600, input 10 =>, if failure stop, - +output slip\x0d, input 10 Username:, if failure stop, - +output silvia\x0d, input 10 Password:, if failure stop, - +output ***\x0d, echo \x0aCONNECTED\x0a +</verb> + (of course, you have to change the hostname and password to fit + yours). Then you can just type "slip" from the kermit prompt to + get connected. + + Note: leaving your password in plain text anywhere in the + filesystem is generally a BAD idea. Do it at your own risk. I'm + just too lazy. + + Note: If you have an 1.1 machine, and kermit doesn't give you a + prompt, try "stty -f /dev/tty01 clocal". I put this in + /etc/rc.local so that it works the first time I boot the machine. + This doesn't apply to 1.1.5(.1) systems, as cua0? are already + configured for dialouts. + +<item> Leave the kermit there (you can suspend it by "z") and as root, + type +<verb> +slattach -h -c -s 57600 /dev/cua01 +</verb> + if you are able to "ping" hosts on campus, you are connected! + If it doesn't work, you might want to try "-a" instead of "-c". +</enum> + +<sect1><heading>How to shutdown the connection</heading> + + <p>Type "ps gx" (as root) to find out the PID of slattach, and use + "kill -INT" to kill it. + Then go back to kermit ("fg" if you suspended it) and exit from it + ("q"). + + The slattach man page says you have to use "ifconfig sl0 down" to + mark the interface down, but this doesn't seem to make any + difference for me. ("ifconfig sl0" reports the same thing.) + + Some times, your modem might refuse to drop the carrier (mine + often does). In that case, simply start kermit and quit it again. + It usually goes out on the second try. + + When you want to connect again, go back to (XXX). You may have to + watch out for clocal mode. If "stty -f /dev/tty01" doesn't tell + you it's clocal, you need to re-set it before kermitting. Again, + this is only for 1.1 machines. + +<sect1><heading>Troubleshooting</heading> + +<p>If it doesn't work, feel free to ask me. The things that people +tripped over so far: +<itemize> +<item> Not using "-c" or "-a" in slattach (I have no idea why this can be + fatal, but adding this flag solved the problem for at least one + person) + +<item> Using "s10" instead of "sl0" (might be hard to see the difference on + some fonts. + +<item> Try "ifconfig sl0" to see your interface status. I get: +<verb> +silvia# ifconfig sl0 +sl0: flags=10<POINTOPOINT> + inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 +</verb> + +<item>Also, "netstat -r" will give the routing table, in case you get the +"no route to host" messages from ping. Mine looks like: +<verb> +silvia# netstat -r +Routing tables +Destination Gateway Flags Refs Use IfaceMTU Rtt +Netmasks: +(root node) +(root node) + +Route Tree for Protocol Family inet: +(root node) => +default inr-3.Berkeley.EDU UG 8 224515 sl0 - - +localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438 +inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - - +silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438 +(root node) +</verb> +(this is after transferring a bunch of files, your numbers should be +smaller). +</itemize>
\ No newline at end of file diff --git a/handbook/slips.sgml b/handbook/slips.sgml new file mode 100644 index 0000000000..799ead042e --- /dev/null +++ b/handbook/slips.sgml @@ -0,0 +1,488 @@ +<!-- This is an SGML version in the linuxdoc DTD of the SLIP Server + FAQ by Guy Helmer. + + This guide provides instruction in configuring and preparing + a FreeBSD system to be a dialup SLIP server. + +<title> +Setting up FreeBSD as a SLIP Server +<author>Guy Helmer, <tt/ghelmer@alpha.dsu.edu/ +<date>v0.2, 20 March 1995 + +--> + +<sect><heading>Setting up a SLIP server</heading> + +<p><em>Contributed by &a.ghelmer;.</em> + +This document provides suggestions for setting up SLIP Server services +on a FreeBSD system, which typically means configuring your system to +automatically startup connections upon login for remote SLIP clients. +I've written this document based on my own experience; however, as +your system and needs may be different, this document may not answer +all of your questions, and I cannot be responsible if you damage your +system or lose data due to attempting to follow the suggestions here. + +I have only setup SLIP Server services on a FreeBSD 1.1 system, so if +you are running a different version (such as FreeBSD 2.0), your system +may be different. + +<sect1><heading>Prerequisites<label id="prereqs"></> + +<p> +This document is very technical in nature, so background knowledge is +required. I must assume that you are familiar with the TCP/IP network +protocol, and in particular, network and node addressing, network +address masks, subnetting, routing, and routing protocols, such as +RIP. Configuring SLIP services on a dial-up server requires a +knowledge of these concepts, and if you are not familiar with them, +please read a copy of either Craig Hunt's <em>TCP/IP Network +Administration</em> published by O'Reilly & Associates, Inc. (ISBN +Number 0-937175-82-X), or Douglas Comer's book on the TCP/IP protocol. + +I will assume that you have already setup your modem(s) and configured +the appropriate system files to allow logins through your modems (see +the manual pages for <tt>sio(4)</tt> for information on the serial +port device driver and <tt>ttys(5)</tt>, <tt>gettytab(5)</tt>, +<tt>getty(8)</tt>, & <tt>init(8)</tt> for information relevant to +configuring the system to accept logins on modems, and perhaps +<tt>stty(1)</tt> for information on setting serial port parameters +[such as <tt>clocal</tt> for directly-connected serial +interfaces]). + +<sect1>Quick Overview + +<p> +In its typical configuration, using FreeBSD as a SLIP server works as +follows: a SLIP user dials up your FreeBSD SLIP Server system and logs +in with a special SLIP login ID that uses <tt>/usr/sbin/sliplogin</tt> +as the special user's shell. The <tt/sliplogin/ program browses the +file <tt>/etc/slip.hosts</tt> to find a matching line for the special +user, and if it finds a match, connects the serial line to an +available SLIP interface and then runs the shell script +<tt>/etc/slip.login</tt> to configure the SLIP interface. + +<sect2>An Example of a SLIP Server Login + +<p> +For example, if my SLIP user ID were <tt>Shelmerg</tt>, that user's +entry in <tt>/etc/master.passwd</tt> would look something like this +(except it would be all on one line): + +<tscreen><verb> +Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP: + /usr/users/Shelmerg:/usr/sbin/sliplogin +</verb></tscreen> + +and, when I log in with that user ID, <tt>sliplogin</tt> will search +<tt>/etc/slip.hosts</tt> for a line that had a matching user ID; on my +system, I may have a line in <tt>/etc/slip.hosts</tt> that reads: + +<tscreen><verb> +Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp +</verb></tscreen> + +sliplogin will find that matching line, hook the serial line I'm on +into the next available SLIP interface, and then execute +<tt>/etc/slip.login</tt> like this: + +<tscreen><verb> +/etc/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp +</verb></tscreen> + +If all goes well, <tt>/etc/slip.login</tt> will issue an +<tt>ifconfig</tt> for the SLIP interface to which sliplogin attached +itself (slip interface 0, in the above example, which was the first +parameter in the list given to <tt>slip.login</tt>) to set the local +IP address (<tt>dc-slip</tt>), remote IP address (<tt>sl-helmer</tt>), +network mask for the SLIP interface (<tt>0xfffffc00</tt>), and any +additional flags (<tt>autocomp</tt>). If something goes wrong, +sliplogin usually logs good informational messages via the daemon +syslog facility, which usually goes into <tt>/var/log/messages</tt> +(see the manual pages for <tt>syslogd(8)</tt> and +<tt>syslog.conf(5)</tt>, and perhaps check <tt>/etc/syslog.conf</tt> +to see to which files <tt>syslogd</tt> is logging). + +OK, enough of the examples -- let's dive into setting up the system. + +<sect1>Kernel Configuration +<p> +FreeBSD's default kernels usually come with two SLIP interfaces +defined (<tt>sl0</tt> and <tt>sl1</tt>); you can use <tt>netstat +-i</tt> to see whether these interfaces are defined in your kernel. + +Sample output from <tt>netstat -i</tt>: + +<tscreen><verb> +Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll +ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133 +ed0 1500 138.247.224 ivory 291311 0 174209 0 133 +lo0 65535 <Link> 79 0 79 0 0 +lo0 65535 loop localhost 79 0 79 0 0 +sl0* 296 <Link> 0 0 0 0 0 +sl1* 296 <Link> 0 0 0 0 0 +</verb></tscreen> + +The <tt>sl0</tt> and <tt>sl1</tt> interfaces shown in <tt>netstat +-i</tt>'s output indicate that there are two SLIP interfaces built +into the kernel. (The asterisks after the <tt>sl0</tt> and +<tt>sl1</tt> indicate that the interfaces are ``down''.) + +However, FreeBSD's default kernels do not come configured to forward +packets (ie, your FreeBSD machine will not act as a router) due to +Internet RFC requirements for Internet hosts (see RFC's 1009 +[Requirements for Internet Gateways], 1122 +[Requirements for Internet Hosts -- Communication Layers], +and perhaps 1127 [A Perspective on the Host Requirements +RFCs]), so if you want your FreeBSD SLIP Server to act as a +router, you'll have to add the line <tt>options GATEWAY </tt> to your +machine's kernel configuration file and re-compile the kernel anyway. +(Trivia: ``Gateways'' are the Internet's old name for what are now +usually called ``routers''.) + +Please see the BSD System Manager's Manual chapter on ``Building +Berkeley Kernels with Config'' [the source for which is in +<tt>/usr/src/share/doc/smm</tt>] and ``FreeBSD Configuration +Options'' [in <tt>/sys/doc/options.doc</tt>] for more +information on configuring and building kernels. You may have to +unpack the kernel source distribution if haven't installed the system +sources already (<tt>srcdist/srcsys.??</tt> in FreeBSD 1.1, +<tt>srcdist/sys.??</tt> in FreeBSD 1.1.5.1, or the entire source +distribution in FreeBSD 2.0) to be able to configure and build +kernels. + +You'll notice that near the end of the default kernel configuration +file (<tt>/sys/i386/conf/GENERICAH</tt>) is a line that reads: + +<tscreen><verb> +pseudo-device sl 2 +</verb></tscreen> + +which is the line that defines the number of SLIP devices available in +the kernel; the number at the end of the line is the maximum number of +SLIP connections that may be operating simultaneously. + +See the document ``Building Berkeley Kernels with Config'' and the +manual page for <tt>config(8)</tt> to see how to configure and build +kernels. + +<sect1>Sliplogin Configuration + +<p> +As mentioned earlier, there are three files in the <tt>/etc</tt> directory that are part of the configuration for +<tt>/usr/sbin/sliplogin</tt> (see <tt>sliplogin(8)</tt> for the actual +manual page for <tt>sliplogin</tt>): <tt>slip.hosts</tt>, which +defines the SLIP users & their associated IP addresses; +<tt>slip.login</tt>, which usually just configures the SLIP interface; +and (optionally) <tt>slip.logout</tt>, which undoes <tt>slip.login</tt>'s +effects when the serial connection is terminated. + +<sect2>slip.hosts Configuration + +<p> +<tt>/etc/slip.hosts</tt> contains lines which have at least four items +listed: + +<itemize> +<item> SLIP user's login ID +<item> Local address (local to the SLIP server) of the SLIP link +<item> Remote address of the SLIP link +<item> Network mask +</itemize> + +The local and remote addresses may be host names (resolved to IP +addresses by <tt>/etc/hosts</tt> or by the domain name service, +depending on your specifications in <tt>/etc/host.conf</tt>), and I +believe the network mask may be a name that can be resolved by a +lookup into <tt>/etc/networks</tt>. On one of my systems, +<tt>/etc/slip.hosts</tt> looks like this: + +<tscreen><verb> +----- begin /etc/slip.hosts ----- +# +# login local-addr remote-addr mask opt1 opt2 +# (normal,compress,noicmp) +# +Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp +----- end /etc/slip.hosts ------ +</verb></tscreen> + +At the end of the line is one or more of the options: + +<itemize> +<item> <tt>normal</tt> - no header compression +<item> <tt>compress</tt> - compress headers +<item> <tt>autocomp</tt> - compress headers if the remote end allows it +<item> <tt>noicmp</tt> - disable ICMP packets (so any ``ping'' packets will be + dropped instead of using up your bandwidth) +</itemize> + +Your choice of local and remote addresses for your SLIP links depends +on whether you are going to dedicate a TCP/IP subnet or if you are +going to use ``proxy ARP'' on your SLIP server (it's not ``true'' proxy +ARP, but that is the terminology that I will use in this document to +describe it). If you're not sure which method to select or how to +assign IP addresses, please refer to the TCP/IP books referenced in +the <ref id="prereqs"> section and/or consult your IP network manager. + +If you are going to use a separate subnet for your SLIP clients, you +will need to allocate the subnet number out of your assigned IP +network number and assign each of your SLIP client's IP numbers out of +that subnet. Then, you will probably either need to configure a +static route to the SLIP subnet via your SLIP server on your nearest +IP router, or install <tt>gated</tt> on your FreeBSD SLIP server and +configure it to talk the appropriate routing protocols to your other +routers to inform them about your SLIP server's route to the SLIP +subnet. + +Otherwise, if you will use the ``proxy ARP'' method, you will need to +assign your SLIP client's IP addresses out of your SLIP server's +Ethernet subnet, and you'll also need to adjust your +<tt>/etc/slip.login</tt> and <tt>/etc/slip.logout</tt> scripts to use +<tt>arp(8)</tt> to manage the proxy-ARP entries in the SLIP server's +ARP table. + +<sect2>slip.login Configuration + +<p> +The typical <tt>/etc/slip.login</tt> file looks like this: + +<tscreen><verb> +----- begin /etc/slip.login ----- +#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +----- end /etc/slip.login ----- +</verb></tscreen> + +This <tt>slip.login</tt> file merely ifconfig's the appropriate SLIP +interface with the local and remote addresses and network mask of the +SLIP interface. + +If you have decided to use the ``proxy ARP'' method (instead of using +a separate subnet for your SLIP clients), your <tt>/etc/slip.login</tt> +file will need to look something like this: + +<tscreen><verb> +----- begin /etc/slip.login for "proxy ARP" ----- +#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +# Answer ARP requests for the SLIP client with our Ethernet addr +/usr/sbin/arp -s $5 00:11:22:33:44:55 pub +----- end /etc/slip.login for "proxy ARP" ----- +</verb></tscreen> + +The additional line in this <tt>slip.login</tt>, <tt>arp -s $5 +00:11:22:33:44:55 pub</tt>, creates an ARP entry in the SLIP server's +ARP table. This ARP entry causes the SLIP server to respond with the +SLIP server's Ethernet MAC address whenever a another IP node on the +Ethernet asks to speak to the SLIP client's IP address. + +When using the example above, be sure to replace the Ethernet MAC +address (<tt>00:11:22:33:44:55</tt>) with the MAC address of your +system's Ethernet card, or your ``proxy ARP'' will definitely not work! +You can discover your SLIP server's Ethernet MAC address by looking at +the results of running <tt>netstat -i</tt>; the second line of the output +should look something like: + +<tscreen><verb> +ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116 + ^^^^^^^^^^^^^^^ +</verb></tscreen> + +which indicates that this particular system's Ethernet MAC address is +<tt>00:02:c1:28:5f:4a</tt> -- the periods in the Ethernet MAC address +given by <tt>netstat -i</tt> must be changed to colons and leading zeros +should be added to each single-digit hexadecimal number to convert the +address into the form that <tt>arp(8)</tt> desires; see the manual page on +<tt>arp(8)</tt> for complete information on usage. + +Note that when you create <tt>/etc/slip.login</tt> and +<tt>/etc/slip.logout</tt>, the ``execute'' bit (ie, <tt>chmod 755 +/etc/slip.login /etc/slip.logout</tt>) must be set, or +<tt>sliplogin</tt> will be unable to execute it. + +<sect2>slip.logout Configuration + +<p> + +<tt>/etc/slip.logout</tt> isn't strictly needed (unless you are +implementing ``proxy ARP''), but if you decide to create it, this is +an example of a basic <tt>slip.logout</tt> script: + +<tscreen><verb> +----- begin /etc/slip.logout ----- +#!/bin/sh - +# +# slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +----- end /etc/slip.logout ----- +</verb></tscreen> + +If you are using ``proxy ARP'', you'll want to have +<tt>/etc/slip.logout</tt> remove the ARP entry for the SLIP client: + +<tscreen><verb> +----- begin /etc/slip.logout for "proxy ARP" ----- +#!/bin/sh - +# +# @(#)slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +# Quit answering ARP requests for the SLIP client +/usr/sbin/arp -d $5 +----- end /etc/slip.logout for "proxy ARP" ----- +</verb></tscreen> + +The <tt>arp -d $5</tt> removes the ARP entry that the ``proxy ARP'' +<tt>slip.login</tt> added when the SLIP client logged in. + +It bears repeating: make sure <tt>/etc/slip.logout</tt> has the +execute bit set for after you create it (ie, <tt>chmod 755 +/etc/slip.logout</tt>). + +<sect1>Routing Considerations + +<p> +If you are not using the ``proxy ARP'' method for routing packets +between your SLIP clients and the rest of your network (and perhaps +the Internet), you will probably either have to add static routes to +your closest default router(s) to route your SLIP client subnet via +your SLIP server, or you will probably need to install and configure +<tt>gated</tt> on your FreeBSD SLIP server so that it will tell your +routers via appropriate routing protocols about your SLIP subnet. + +<sect2>Static Routes + +<p> +Adding static routes to your nearest default routers can be +troublesome (or impossible, if you don't have authority to do so...). +If you have a multiple-router network in your organization, some +routers, such as Cisco and Proteon, may not only need to be configured +with the static route to the SLIP subnet, but also need to be told +which static routes to tell other routers about, so some expertise and +troubleshooting/tweaking may be necessary to get static-route-based +routing to work. + +<sect2>Running gated + +<p> +An alternative to the headaches of static routes is to install +<tt>gated</tt> on your FreeBSD SLIP server and configure it to use the +appropriate routing protocols (RIP/OSPF/BGP/EGP) to tell other routers +about your SLIP subnet. <tt/gated/ is available via anonymous ftp from +<tt>ftp.gated.cornell.edu</tt> in the directory <tt>/pub/gated</tt>; I +believe the current version as of this writing is +<tt>gated-R3_5Alpha_8.tar.Z</tt>, which includes support for FreeBSD +``out-of-the-box''. Complete information and documentation on +<tt>gated</tt> is available on the Web starting at +<tt>http://www.gated.cornell.edu/</tt>. Compile and install it, and +then write a <tt>/etc/gated.conf</tt> file to configure your gated; +here's a sample, similar to what I use on my FreeBSD SLIP server: + +<tscreen><verb> +----- begin sample /etc/gated.conf for gated version 3.5Alpha5 ----- +# +# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 +# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface +# +# +# tracing options +# +traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; + +rip yes { + interface sl noripout noripin ; + interface ed ripin ripout version 1 ; + traceoptions route ; +} ; + +# +# Turn on a bunch of tracing info for the interface to the kernel: +kernel { + traceoptions remnants request routes info interface ; +} ; + +# +# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP +# + +export proto rip interface ed { + proto direct { + xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections + } ; +} ; + +# +# Accept routes from RIP via ed Ethernet interfaces + +import proto rip interface ed { + all ; +} ; + +----- end sample /etc/gated.conf ----- +</verb></tscreen> + +The above sample <tt>gated.conf</tt> file broadcasts routing +information regarding the SLIP subnet <tt>xxx.xxx.yy</tt> via RIP onto +the Ethernet; if you are using a different Ethernet driver than the +<tt/ed/ driver, you'll need to change the references to the <tt/ed/ +interface appropriately. This sample file also sets up tracing to +<tt>/var/tmp/gated.output</tt> for debugging <tt>gated</tt>'s +activity; you can certainly turn off the tracing options if +<tt>gated</tt> works OK for you. I've changed my SLIP subnet's +address to <tt>xxx.xxx.yy</tt> throughout the above file; you'll need +to change the <tt>xxx.xxx.yy</tt>'s into the network address of your +own SLIP subnet (be sure to change the net mask in the <tt>proto +direct</tt> clause as well). + +When you get <tt>gated</tt> built and installed and create a +configuration file for it, you'll need to run <tt>gated</tt> in place +of <tt>routed</tt> on your FreeBSD system; change the +<tt>routed/gated</tt> startup parameters in <tt>/etc/netstart</tt> as +appropriate for your system. Please see the manual page for +<tt>gated</tt> for information on <tt>gated</tt>'s command-line +parameters. + +<sect1>Acknowledgements + +<p> +Thanks to these people for comments and advice regarding this FAQ: + +<descrip> +<tag/Wilko Bulte/ <wilko@yedi.iaf.nl> +<tag/Piero Serini/ <Piero@Strider.Inet.IT> +</descrip> + +<!-- </article> --> + diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml new file mode 100644 index 0000000000..6607e5593c --- /dev/null +++ b/handbook/submitters.sgml @@ -0,0 +1,181 @@ +<!-- $Id: submitters.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Contributing to FreeBSD</heading> + +<p><em>Contributed by &a.jkh;.</em> + +This guide is intended for those who are moderately familar with FreeBSD +and are now to the point where they have some locally developed +customizations or fixes to the system which they'd like to incorporate +back into the mainstream sources, thus saving the work of having to +re-integrate the changes for each subsequent FreeBSD release. Submitting +something to the FreeBSD project is also an excellent way of getting your +code seriously *tested*! Many people have developed an original concept +far beyond what they might have envisioned at the start just due to the +flood of feedback and ideas generated by the many thousands of users of +FreeBSD. Contributions are also what FreeBSD lives and grows from, +and so your contributions are very important to the continued survival +of this communal effort of ours - we're very glad to see you reading this +documentation! :-) + +Submissions to FreeBSD can generally be classified into four catagories: +<enum> +<item> Ideas, general suggestions, bug reports. +<item> Addition, deletion, renaming or patching of existing sources. +<item> Significant contribution of a large body of independant work. +<item> Porting of freely available software. +</enum> +A submission in *any* of these catagories is highly welcomed as they +are each, in their own way, quite significant to the project. + + +<sect><heading>Ideas and suggestions</heading> + +<p>An idea, suggestion or fix can be communicated in one of the following ways: +<itemize> + <item> An idea or suggestion of general technical interest should be + mailed to <hackers@freebsd.org>. Likewise, people with an interest + in such things (and a tolerance for a HIGH volume of mail!) may + subscribe by sendimg mail to <majordomo@freebsd.org>. See also the + file /usr/share/FAQ/mailing-list.FAQ. + + <item> An actual bug report should be filed by using the send-pr(1) + command (``man send-pr'' for information). This will prompt + you for various fields to fill in. Simply go to the fields + surrounded by <>'s and fill in your own information in place of + what's suggested there. You should receive confirmation of your + bug report and a tracking number (which you should also reference in + any subsequent correspondence). + + If you do not receive confirmation in a timely fashion (3 days to + a week, depending on your email connection) or are, for some + reason, unable to use the send-pr command, then you may also + file a bug report (or follow-up to one) by sending mail to: + + <bugs@freebsd.org> +</itemize> + +<sect><heading>Changes to the existing code</heading> + +<p>An addition or change to the existing source code is a somewhat trickier + affair and depends a lot on how far out of date you are with the current + state of the core FreeBSD development. There is a special on-going release + of FreeBSD known as "FreeBSD-current" and made available in a variety of + ways (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for + the convenience of developers who wish to actively work on the system. + + Working from older sources unfortunately means that your changes may + sometimes be too obsolete to use, or too divergent to allow for easy + re-integration. This can be minimized somewhat by subscribing to the + <announce@freebsd.org> mailing list (among others) where periodic + announcements concerning the current state of the system are made. + If you see a change being proposed for which you have a better solution, + then please, by all means come forward with your contribution and we + will do our very best to evaluate it fairly and perhaps integrate it if + it is indeed a better (or easier :) solution. + + Assuming that you can manage to secure fairly up-to-date sources to base + your changes on, the next step is to produce a set of diffs to send to the + FreeBSD maintainers for evaluation and possible adoption. This is done + with the diff(1) command, with the FreeBSD maintainers preferring to receive + diffs in `context diff' form. See the man page for diff for more details + on producing both context and recursive context diffs + (diff -c <oldfile> <newfile> or diff -c -r <olddir> <newdir>). + + Once you have a set of diffs that are capable of taking a copy of the + original code and bringing it to a state identical to the "new" sources + (you may test this with the patch(1) command - see patch man page), you + should bundle them up in an email message and send it, along with a brief + description of what the diffs are for, to <hackers@freebsd.org>. Someone + will very likely get back in touch with you in 24 hours or less, assuming + of course that your diffs are interesting! :-) + + If your changes don't express themselves well as diffs alone (e.g. you've + perhaps added, deleted or renamed files as well) then you may be better off + bundling any new files, diffs and instructions for deleting/renaming any + others into a tar file and running the `uuencode' program on it before + sending the output of that to <hackers@freebsd.org>. See the man pages + on tar and uuencode for more info on bundling files through the mail this + way. + + If your change is of a potentially sensitive nature, e.g. you're unsure + of copyright issues governing its further distribution, or you're simply + not ready to release it without a tighter review first, then you should + send it to <core@freebsd.org> rather than <hackers@freebsd.org>. The core + mailing list reaches a much smaller group of people who do much of the + day-to-day work on FreeBSD. Note that this group is also VERY BUSY and so + you should really only mail to them in cases where mailing to hackers + truly is impractical. + + +<sect><heading>Contributions of new code</heading> + +<p>In the case of a significant contribution of a large body work, or the + addition of an important new feature to FreeBSD, it becomes almost always + necessary to either send changes as uuencoded tar files (see above) + or upload them to our ftp site: + + <url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> + + Users may log in anonymously and upload their work or download the + work-in-progress files left by others. + + When working with large amounts of code, the touchy subject of copyrights + also invariably comes up. The view of the FreeBSD project towards + acceptable copyrights (for code included in FreeBSD) are: + +<enum> + <item> Contributions under the BSD copyright (see the file + /usr/share/examples/etc/bsd-style-copyright for a template) + is greatly preferred due to its "no strings attached" + nature and general attractiveness to commercial enterprises + who might then be inclined to invest something of their own + into FreeBSD. + + <item> Contributions under the GNU Public License, or "GPL". This is + not quite as popular a solution for us, due to (all religious + issues aside) the amount of extra effort demanded of anyone + using the code for commercial purposes. However, given the + sheer quantity of GPL'd code we currently require (compiler, + assembler, text formatter, etc), it would be silly to pretend + that we couldn't deal with the GPL at all and so we have become + more willing to accept code with either the BSD or the GPL + copyright. Code under the GPL also goes into a different part + of the tree, that being /sys/gnu or /usr/src/gnu. + + <item> Contributions coming under any other type of copyright must be + carefully reviewed before their inclusion into FreeBSD will even + be considered. Contributions for which particularly restrictive + commercial copyrights apply are generally rejected, though the + authors are always free to make the changes available through + their own channels. +</enum> + +<sect><heading>Porting of software</heading> + +<p>The porting of freely available software, while perhaps not as gratifying + as developing your own package from scratch, is still a vital part of + FreeBSD's growth and of great usefulness to those who wouldn't otherwise + know where to turn for it. All ported software is organized into a + hierarchy know as ``the ports collection''. This collection enables + a new user to get a complete overview of what's available in a short time, + and with a logical (we hope) framework. The ports collection also saves + considerable space by not actually containing the the majority of the + sources being ported. This can be confusing to the new user and the file + /usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works. + + If you have the ports collection on your machine, the file + /usr/ports/GUIDELINES also helps to explain the process of creating + and contributing a port of your own. For more information on the ports + collection (that wasn't available in the FAQ), you may also send mail to + <ports@freebsd.org>. + + +Whichever way you decide to contribute, we hope you'll find it an enjoyable +process and also realize how valuable your contributions are to the project! +FreeBSD is one of those great projects where the more we all put in, the +more we all get back out of it again, and with enough steady contributions +it begins to aquire a momentum of its own. It is through such momentum +that mountains are moved! + diff --git a/handbook/sup.sgml b/handbook/sup.sgml new file mode 100644 index 0000000000..600aafa7fd --- /dev/null +++ b/handbook/sup.sgml @@ -0,0 +1,92 @@ +<!-- $Id: sup.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + + +<sect><heading>SUP</heading> + +<p><em>Contributed by &a.jkh; and &a.gclarkii;.</em> + +SUP is a network based software update tool developed at CMU. The +purpose of this document is get the beginner up and running with sup. + +<sect1><heading>Getting setup</heading> + +<p>First off you will need to pick up the sup binaries. The easiest +way of doing this is to grab the sup.tgz package from: +<verb> + ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/packages/sup.tgz +</verb> +Install the sup package using pkg_add and add the following line to +your /etc/services file: +<verb> + sup 871/tcp #sup +</verb> + +SUP gets the information it needs to run from a configuration file +called a supfile. This file tells sup what collections it will be updating +and/or installing and where they go. The supfile in this directory will +sup both the source and ports collection - look for the blank line seperating +the two collections; if you don't want ports, you can simply delete all the +ports entries. If you're inside the United States, you may also uncomment +the `secure' collection line to grab the DES code. If you're outside the +U.S., you should NOT sup this code from FreeBSD.ORG as this will +violate U.S. export restrictions. Simply sup everything *but* the secure +collection and then go look on "braae.ru.ac.za", where it's available for +anonymous ftp for those outside the U.S. + +Any other distributions you do not wish to receive can be commented out +with a # at the begining of the distribution line. + +Once this is setup, you're ready to go. To start sup type: +<verb> + sup supfile +</verb> +If you wish to see what sup is doing "verbosely", give it the -v option, +like so: +<verb> + sup -v supfile +</verb> +Thats all there is to it! Remember that if you're running current, +which is what you will have if you sup, please join the freebsd-current +mailing list. You should also be sure to read: +<verb> + ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/FAQ/current-policy.FAQ +</verb> +For important information on just what we can and cannot do for you as +a -current user. + +<sect1><heading>Description of FreeBSD SUP distributions</heading> + +<p>For the main FreeBSD distribution: +<verb> +base: /usr/src/... misc files at the top of /usr/src +bin: /usr/src/bin system binaries +secure: /usr/src/secure DES Sources. U.S./Canada only! +etc: /usr/src/etc system files +games: /usr/src/games games +gnu: /usr/src/gnu sources under the GNU Public License +include: /usr/src/include include files +sys: /usr/src/sys kernel sources +lib: /usr/src/lib libraries +libexec: /usr/src/libexec more system binaries +share: /usr/src/share various shared resources +sbin: /usr/src/sbin even more system binaries +usrbin: /usr/src/usr.bin user binaries +usrsbin: /usr/src/usr.sbin that's it for the system binaries +</verb> + +And for the ports collection: +<verb> +ports-base: /usr/ports/... misc files at the top of /usr/ports +ports-editors: /usr/ports/editors text editors +ports-game: /usr/ports/games games +ports-lang: /usr/ports/lang programming languages +ports-mail: /usr/ports/mail mail software +ports-math: /usr/ports/math math software +ports-net: /usr/ports/net networking software +ports-news: /usr/ports/news USENET news software +ports-print: /usr/ports/print printing software +ports-shells: /usr/ports/shells various UN*X shells +ports-utils: /usr/ports/utils miscellaneous utilities +ports-x11: /usr/ports/x11 X11 software +</verb>
\ No newline at end of file diff --git a/handbook/troubleshooting.sgml b/handbook/troubleshooting.sgml new file mode 100644 index 0000000000..311821fcee --- /dev/null +++ b/handbook/troubleshooting.sgml @@ -0,0 +1,185 @@ +<!-- $Id: troubleshooting.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Troubleshooting</heading> + +<p>The following tips and tricks may help you turn a + failing (or failed) installation attempt into a success. + Please read them carefully. + +<sect> + <heading>Hardware conflict or misconfiguration</heading> + + + <p><descrip> + <tag>Problem:</tag> A device is conflicting with + another or doesn't match the kernel's compiled-in IRQ or + address. + + <tag>Cause:</tag> While most device drivers in + FreeBSD are now smart enough to match themselves to your + hardware settings dynamically, there are a few that still + require fairly rigid configuration parameters to be + compiled in (and matched by the hardware) before they'll + work. We're working hard to eliminate as many of these + last hold-outs as we can, but it's not always as easy as + it looks. + + <tag>Solution:</tag> There are several possible + solutions. The first, and easiest, is to boot the kernel + with the <tt>-c</tt> flag. When you see the initial boot prompt + (from floppy or hard disk), type: + +<tscreen><verb> +/kernel -c + </verb></tscreen> + + This will boot just past the memory sizing code and then + drop into a dynamic kernel configuration utility. Type + `<tt>?</tt>' at the prompt to see a list of commands. + You can use this utility to reset the IRQ, memory + address, IO address or a number of other device + configuration parameters. You can also disable a device + entirely if it's causing problems for other devices you'd + much rather have work. Note that this only affects the + kernel being booted temporarily, it does not write out + the information to the kernel so that these settings are + permanantly altered (this would be actually rather hard). + If you reboot, you'll have to make the same changes + again. The goal of the <tt>-c</tt> utility is to get you + up far enough to be able to download the appropriate + sources and configure and rebuild a kernel more specific + to your needs. + + Another solution is, obviously, to remove the offending + hardware or simply strip the system down to the bare + essentials until the problem (hopefully) goes away. Once + you're up, you can do the same thing mentioned + above---compile a kernel more suited to your hardware, or + incrementally try to figure out what it was about your + original hardware configuration that didn't work. + + </descrip> + +<sect> + <heading>My floppy-tape drive isn't probed</heading> + + <p>Cause: Last-minute problems with this driver caused it + to be disabled by default. + + Solution: Boot with -c (described above) and set the + flags value of fdc0 to 1. This will re-enable the floppy + tape driver. Sorry, but it was causing problems for + other people! + +<sect> + <heading>When I boot for the first time, it still looks for + /386bsd!</heading> + + <p>Cause: You still have the old FreeBSD 1.x boot blocks on + your boot partition. + + Solution: You should re-enter the installation process, + invoke the (F)disk editor and chose the (W)rite option. + This won't hurt an existing installation and will make + sure that the new boot blocks get written to the drive. + If you're installing for the first time, don't forget to + (W)rite out your new boot blocks! :-) + +<sect> + <heading>I want to boot FreeBSD off the second drive. It + doesn't!</heading> + + <p>Cause: FreeBSD will actually install just fine on a + drive other than 0 (the first drive), and the boot + manager will even allow you to select it, but the boot + blocks rather pathologically assume 0. This should be + fixed in 2.1. + + Solution: Easy - follow these steps: + + 1. Select the first (0) drive from the (F)disk editor + and write out the boot manager with the (B) option. + This will enable the boot manager that allows you to + actually boot off the other drive. + + 2. Exit the fdisk editor for the first drive and and + re-enter it again for the drive you wish to install + on. Set up a partition on this drive, or select + (A)ll for the entire drive. + + 3. Enter the disklabel editor and allocate space on + your second drive as normal. Proceed with the + installation. + + 4. Once you've installed on the disk and are going to + reboot from the hard disk, enter the following at + the boot prompt: + + hd(1,a)/kernel + + This will ensure that you really boot from the second + drive. If you've actually installed on a drive other + than 1 (the 3rd or 4th drive?), substitute that number + in for the above. You will need to enter this EVERY + time you reboot from the hard disk. If you're feeling + brave and have a srcdist + the requisite experience, + you can hack the boot blocks in: + + /usr/src/sys/i386/boot/biosboot + + So that this drive you're booting from is hard-coded. + Recompile the boot blocks and reinstall them on your + drive with `disklabel -B ...' You can then have the + default Do The Right Thing. + +<sect> + <heading>Newfs crashes, requesting that blocksize be 32K</heading> + + <p>Cause: You have your SCSI controller configured to + translate geometries for disks >1GB in size. + + Solution: Turn such translation OFF in your controller's + BIOS setup! FreeBSD has no problems with disks >1GB just + so long as the root partition starts and ends BELOW + cylinder 1024. This is a PC hardware limitation. + +<sect> + <heading>FreeBSD won't boot off the hard disk</heading> + + <p>Cause: Root partition does not start and end below + cylinder 1024. + + Solution: See solution for newfs crashes, or move your + root partition. This limitation holds true for ANY + operating system you wish to boot from your hard drive. + + +<sect> + <heading>FreeBSD still won't boot off the hard disk</heading> + + <p>Cause: No boot code is installed in sector 1. + + Solution: Chose the Write MBR (B)oot code in the FDISK + editor. + +<sect> + <heading>Nope, FreeBSD's still not booting from the hard + disk</heading> + + <p>Cause: BIOS disk geometry different from that used when + installing FreeBSD. + + Solution: With IDE drives, pay careful attention to the + geometry information that FreeBSD prints out when it's + first booting off the floppy. Use this geometry in your + BIOS setup or use the BIOS geometry when you install + FreeBSD. Either way, they have to match. + + With SCSI drives, the values they report is most often + bogus and cannot be used. In this situation, the SCSI + controller is performing geometry translation and it's + probably wise to assume a default of 64 heads, 32 sectors + and 1MB/cylinder. Use these values when you install + FreeBSD. See above comments concerning newfs failures + for more info. |