diff options
| author | Jordan K. Hubbard <jkh@FreeBSD.org> | 1996-06-19 20:28:30 +0000 |
|---|---|---|
| committer | Jordan K. Hubbard <jkh@FreeBSD.org> | 1996-06-19 20:28:30 +0000 |
| commit | 8f8eb63a5a541d9fe183835eeccd0f9246a8ce8f (patch) | |
| tree | babf3b45278ff730781c4c6d874636e1489ea67d /handbook | |
| parent | 31444442c3a0c70f1c4de4aa0e4f95e5a6b9c31a (diff) | |
| download | doc-8f8eb63a5a541d9fe183835eeccd0f9246a8ce8f.tar.gz doc-8f8eb63a5a541d9fe183835eeccd0f9246a8ce8f.zip | |
Merge from HEAD. This is part of a multi-part commit since the SGML tools
need to be merged as well for this to work, but they're in a different part of
the subtree. I have to merge this because a) our -stable docs are way out of
date and b) I need the "doc" distribution to appear in -stable if I'm to use
a single copy of sysinstall for both. Reviewers of this MOST welcome!
Notes
Notes:
svn path=/branches/RELENG_2_1_0/; revision=372
Diffstat (limited to 'handbook')
40 files changed, 2767 insertions, 2002 deletions
diff --git a/handbook/authors.sgml b/handbook/authors.sgml index dc88e6eda5..8b173b6b28 100644 --- a/handbook/authors.sgml +++ b/handbook/authors.sgml @@ -1,31 +1,31 @@ -<!-- $Id: authors.sgml,v 1.3.4.3 1995-10-22 00:50:22 jfieber Exp $ --> +<!-- $Id: authors.sgml,v 1.3.4.4 1996-06-19 20:27:24 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- -Names and email address of contributing authors. Use these -entities when referencing people. Please not the use of single +Names and email address of contributing authors and CVS committers. +Use these entities when referencing people. Please note the use of single and double quotes. --> <!ENTITY a.asami "Satoshi Asami - <tt><htmlurl url='mailto:asami@FreeBSD.org' - name='<asami@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:asami@FreeBSD.ORG' + name='<asami@FreeBSD.ORG>'></tt>"> <!ENTITY a.awebster "Andrew Webster <tt><htmlurl url='mailto:awebster@dataradio.com' name='<awebster@dataradio.com>'></tt>"> <!ENTITY a.davidg "David Greenman - <tt><htmlurl url='mailto:davidg@Root.COM' - name='<davidg@Root.COM>'></tt>"> + <tt><htmlurl url='mailto:davidg@FreeBSD.ORG' + name='<davidg@FreeBSD.ORG>'></tt>"> -<!ENTITY a.dufalt "Peter Dufault - <tt><htmlurl url='mailto:dufault@hda.com' - name='<dufault@hda.com>'></tt>"> +<!ENTITY a.dufault "Peter Dufault + <tt><htmlurl url='mailto:dufault@FreeBSD.ORG' + name='<dufault@FreeBSD.ORG>'></tt>"> <!ENTITY a.gclarkii "Gary Clark II - <tt><htmlurl url='mailto:gclarkii@FreeBSD.org' - name='<gclarkii@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:gclarkii@FreeBSD.ORG' + name='<gclarkii@FreeBSD.ORG>'></tt>"> <!ENTITY a.gena "Gennady B. Sorokopud <tt><htmlurl url='mailto:gena@NetVision.net.il' @@ -36,8 +36,8 @@ and double quotes. name='<ghelmer@alpha.dsu.edu>'></tt>"> <!ENTITY a.gpalmer "Gary Palmer - <tt><htmlurl url='mailto:gpalmer@FreeBSD.org' - name='<gpalmer@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:gpalmer@FreeBSD.ORG' + name='<gpalmer@FreeBSD.ORG>'></tt>"> <!ENTITY a.gryphon "Coranth Gryphon <tt><htmlurl url='mailto:gryphon@healer.com' @@ -48,16 +48,16 @@ and double quotes. name='<jehamby@lightside.com>'></tt>"> <!ENTITY a.jfieber "John Fieber - <tt><htmlurl url='mailto:jfieber@FreeBSD.org' - name='<jfieber@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:jfieber@FreeBSD.ORG' + name='<jfieber@FreeBSD.ORG>'></tt>"> -<!ENTITY a.jkh "Jordan Hubbard - <tt><htmlurl url='mailto:jkh@FreeBSD.org' - name='<jkh@FreeBSD.org>'></tt>"> +<!ENTITY a.jkh "Jordan K. Hubbard + <tt><htmlurl url='mailto:jkh@FreeBSD.ORG' + name='<jkh@FreeBSD.ORG>'></tt>"> <!ENTITY a.joerg "Jörg Wunsch - <tt><htmlurl url='mailto:joerg_wunsch@uriah.heep.sax.de' - name='<joerg_wunsch@uriah.heep.sax.de>'></tt>"> + <tt><htmlurl url='mailto:joerg@FreeBSD.ORG' + name='<joerg@FreeBSD.ORG>'></tt>"> <!ENTITY a.john "John Lind <tt><htmlurl url='mailto:john@starfire.MN.ORG' @@ -67,14 +67,6 @@ and double quotes. <tt><htmlurl url='mailto:kelly@fsl.noaa.gov' name='<kelly@fsl.noaa.gov>'></tt>"> -<!ENTITY a.mark "Mark Murray - <tt><htmlurl url='mailto:mark@grondar.za' - name='<mark@grondar.za>'></tt>"> - -<!ENTITY a.martin "Martin Renters - <tt><htmlurl url='mailto:martin@innovus.com' - name='<martin@innovus.com>'></tt>"> - <!ENTITY a.md "Mark Dapoz <tt><htmlurl url='mailto:md@bsc.no' name='<md@bsc.no>'></tt>"> @@ -84,20 +76,20 @@ and double quotes. name='<nik@blueberry.co.uk>'></tt>"> <!ENTITY a.phk "Poul-Henning Kamp - <tt><htmlurl url='mailto:phk@FreeBSD.org' - name='<phk@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:phk@FreeBSD.ORG' + name='<phk@FreeBSD.ORG>'></tt>"> <!ENTITY a.paul "Paul Richards - <tt><htmlurl url='mailto:paul@FreeBSD.org' - name='<paul@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:paul@FreeBSD.ORG' + name='<paul@FreeBSD.ORG>'></tt>"> <!ENTITY a.rgrimes "Rodney Grimes - <tt><htmlurl url='mailto:rgrimes@FreeBSD.org' - name='<rgrimes@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:rgrimes@FreeBSD.ORG' + name='<rgrimes@FreeBSD.ORG>'></tt>"> <!ENTITY a.uhclem "Frank Durda IV - <tt><htmlurl url='mailto:uhclem@nemesis.lonestar.org' - name='<uhclem@nemesis.lonestar.org>'></tt>"> + <tt><htmlurl url='mailto:uhclem@FreeBSD.ORG' + name='<uhclem@FreeBSD.ORG>'></tt>"> <!ENTITY a.whiteside "Don Whiteside <tt><htmlurl url='mailto:whiteside@acm.org' @@ -108,5 +100,205 @@ and double quotes. name='<wilko@yedi.iaf.nl>'></tt>"> <!ENTITY a.wollman "Garrett Wollman - <tt><htmlurl url='mailto:wollman@FreeBSD.org' - name='<wollman@FreeBSD.org>'></tt>"> + <tt><htmlurl url='mailto:wollman@FreeBSD.ORG' + name='<wollman@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.peter "Peter Wemm + <tt><htmlurl url='mailto:peter@FreeBSD.ORG' + name='<peter@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.dyson "John Dyson + <tt><htmlurl url='mailto:dyson@FreeBSD.ORG' + name='<dyson@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.ache "Andrey A. Chernov + <tt><htmlurl url='mailto:ache@FreeBSD.ORG' + name='<ache@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.gibbs "Justin T. Gibbs + <tt><htmlurl url='mailto:gibbs@FreeBSD.ORG' + name='<gibbs@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.pst "Paul Traina + <tt><htmlurl url='mailto:pst@FreeBSD.ORG' + name='<pst@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.sos "Søren Schmidt + <tt><htmlurl url='mailto:sos@FreeBSD.ORG' + name='<sos@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.nate "Nate Williams + <tt><htmlurl url='mailto:nate@FreeBSD.ORG' + name='<nate@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.karl "Karl Strickland + <tt><htmlurl url='mailto:karl@FreeBSD.ORG' + name='<karl@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.csgr "Geoff Rehmet + <tt><htmlurl url='mailto:csgr@FreeBSD.ORG' + name='<csgr@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.ats "Andreas Schulz + <tt><htmlurl url='mailto:ats@FreeBSD.ORG' + name='<ats@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.rich "Rich Murphey + <tt><htmlurl url='mailto:rich@FreeBSD.ORG' + name='<rich@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jvh "Johannes Helander + <tt><htmlurl url='mailto:jvh@FreeBSD.ORG' + name='<jvh@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.proven "Chris Provenzano + <tt><htmlurl url='mailto:proven@FreeBSD.ORG' + name='<proven@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.guido "Guido van Rooij + <tt><htmlurl url='mailto:guido@FreeBSD.ORG' + name='<guido@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.hsu "Jeffrey Hsu + <tt><htmlurl url='mailto:hsu@FreeBSD.ORG' + name='<hsu@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.bde "Bruce Evans + <tt><htmlurl url='mailto:bde@FreeBSD.ORG' + name='<bde@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.sef "Sean Eric Fagan + <tt><htmlurl url='mailto:sef@FreeBSD.ORG' + name='<sef@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.se "Stefan Esser + <tt><htmlurl url='mailto:se@FreeBSD.ORG' + name='<se@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.torstenb "Torsten Blum + <tt><htmlurl url='mailto:torstenb@FreeBSD.ORG' + name='<torstenb@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.julian "Julian Elischer + <tt><htmlurl url='mailto:julian@FreeBSD.ORG' + name='<julian@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.dfr "Doug Rabson + <tt><htmlurl url='mailto:dfr@FreeBSD.ORG' + name='<dfr@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.martin "Martin Renters + <tt><htmlurl url='mailto:martin@FreeBSD.ORG' + name='<martin@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.swallace "Steven Wallace + <tt><htmlurl url='mailto:swallace@FreeBSD.ORG' + name='<swallace@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.ljo "L Jonas Olsson + <tt><htmlurl url='mailto:ljo@FreeBSD.ORG' + name='<ljo@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.dima "Dima Ruban + <tt><htmlurl url='mailto:dima@FreeBSD.ORG' + name='<dima@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.lars "Lars Fredriksen + <tt><htmlurl url='mailto:lars@FreeBSD.ORG' + name='<lars@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jmz "Jean-Marc Zucconi + <tt><htmlurl url='mailto:jmz@FreeBSD.ORG' + name='<jmz@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.ugen "Ugen J.S.Antsilevich + <tt><htmlurl url='mailto:ugen@FreeBSD.ORG' + name='<ugen@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.wpaul "Bill Paul + <tt><htmlurl url='mailto:wpaul@FreeBSD.ORG' + name='<wpaul@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.amurai "Atsushi Murai + <tt><htmlurl url='mailto:amurai@FreeBSD.ORG' + name='<amurai@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jmacd "Joshua Peck Macdonald + <tt><htmlurl url='mailto:jmacd@FreeBSD.ORG' + name='<jmacd@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.olah "Andras Olah + <tt><htmlurl url='mailto:olah@FreeBSD.ORG' + name='<olah@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.roberto "Ollivier Robert + <tt><htmlurl url='mailto:roberto@FreeBSD.ORG' + name='<roberto@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.markm "Mark Murray + <tt><htmlurl url='mailto:markm@FreeBSD.ORG' + name='<markm@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.gj "Gary Jennejohn + <tt><htmlurl url='mailto:gj@FreeBSD.ORG' + name='<gj@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.mpp "Mike Pritchard + <tt><htmlurl url='mailto:mpp@FreeBSD.ORG' + name='<mpp@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.smace "Scott Mace + <tt><htmlurl url='mailto:smace@FreeBSD.ORG' + name='<smace@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.erich "Eric L. Hernes + <tt><htmlurl url='mailto:erich@FreeBSD.ORG' + name='<erich@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.graichen "Thomas Graichen + <tt><htmlurl url='mailto:graichen@FreeBSD.ORG' + name='<graichen@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.adam "Adam David + <tt><htmlurl url='mailto:adam@FreeBSD.ORG' + name='<adam@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.tg "Thomas Gellekum + <tt><htmlurl url='mailto:tg@FreeBSD.ORG' + name='<tg@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jdp "John Polstra + <tt><htmlurl url='mailto:jdp@FreeBSD.ORG' + name='<jdp@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jlrobin "James L. Robinson + <tt><htmlurl url='mailto:jlrobin@FreeBSD.ORG' + name='<jlrobin@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.jmb "Jonathan M. Bresler + <tt><htmlurl url='mailto:jmb@FreeBSD.ORG' + name='<jmb@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.wosch "Wolfram Schneider + <tt><htmlurl url='mailto:wosch@FreeBSD.ORG' + name='<wosch@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.fenner "Bill Fenner + <tt><htmlurl url='mailto:fenner@FreeBSD.ORG' + name='<fenner@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.brian "Brian N. Handy + <tt><htmlurl url='mailto:handy@sxt4.physics.montana.edu' + name='<handy@sxt4.physics.montana.edu>'></tt>"> + +<!ENTITY a.chuck "Chuck Robey + <tt><htmlurl url='mailto:chuckr@glue.umd.edu' + name='<chuckr@glue.umd.edu>'></tt>"> + +<!ENTITY a.jraynard "James Raynard + <tt><htmlurl url='mailto:jraynard@freebsd.org' + name='<jraynard@freebsd.org>'></tt>"> + +<!ENTITY a.alex "Alex Nash + <tt><htmlurl url='mailto:alex@freebsd.org' + name='<alex@freebsd.org>'></tt>"> diff --git a/handbook/basics.sgml b/handbook/basics.sgml index 59af6284ca..e3889e1adf 100644 --- a/handbook/basics.sgml +++ b/handbook/basics.sgml @@ -1,4 +1,4 @@ -<!-- $Id: basics.sgml,v 1.1.1.1.4.3 1995-10-22 00:50:23 jfieber Exp $ --> +<!-- $Id: basics.sgml,v 1.1.1.1.4.4 1996-06-19 20:27:25 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Unix Basics<label id="basics"></heading> @@ -9,7 +9,7 @@ <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. + explaining the basic operation and various arguments. These manuals can be view with the <tt><bf>man</bf></tt> command. Use of the <tt><bf>man</bf></tt> command is simple: @@ -40,20 +40,20 @@ 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: + one you want by specifying the section: <tscreen> % <bf>man 1 chmod</bf> </tscreen> which will display the manual page for the user command <tt><bf>chmod</bf></tt>. References to a particular section of the on-line manual are traditionally placed - in paranthesis in written documentation; so + in parenthesis in written documentation, so <tt><bf>chmod(1)</bf></tt> refers to the <tt><bf>chmod - </bf></tt> user command, while <tt><bf>chmod(2)</bf></tt> - means the system call. + </bf></tt> user command and <tt><bf>chmod(2)</bf></tt> + refers to the system call. <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 + simply wish to know how to use it, but what if you cannot recall the command name? You can use <tt><bf>man</bf></tt> to search for keywords in the command <em>descriptions</em> by using the <tt><bf>-k</bf></tt> switch: @@ -62,13 +62,12 @@ </tscreen> With this command you will be presented with a list of commands that have the keyword `mail' in their - descriptions. This is the same as the separate command - <tt><bf>apropos</bf></tt>. + descriptions. This is actually functionally equivalent to + using the <tt><bf>apropos</bf></tt> command. - <p>You are seeing all those fancy commands in <tt> - /usr/bin</tt>, but don't even have the silliest idea - what most of the names do actually stand for? Simply - do a + <p>So, you are looking at all those fancy commands in <tt> + /usr/bin</tt> but do not even have the faintest idea + what most of them actually do? Simply do a <tscreen> % <bf>cd /usr/bin; man -f *</bf> </tscreen> @@ -76,7 +75,7 @@ <tscreen> % <bf>cd /usr/bin; whatis *</bf> </tscreen> - which is the same. + which does the same thing. <sect> <heading>GNU Info files<label id="basics:info"></heading> @@ -90,8 +89,8 @@ mode of <tt>emacs</tt>. To use the <tt>info(1)</tt> command, simply type: - <tscreen>% <bf>info</bf></tscreen> For a brief - introduction, type <tt><bf>h</bf></tt>, and for a quick + <tscreen>% <bf>info</bf></tscreen> For a brief + introduction, type <tt><bf>h</bf></tt>. For a quick command reference, type <tt><bf>?</bf></tt>. diff --git a/handbook/bibliography.sgml b/handbook/bibliography.sgml index 6b7686a696..3d88b8f1de 100644 --- a/handbook/bibliography.sgml +++ b/handbook/bibliography.sgml @@ -1,4 +1,4 @@ -<!-- $Id: bibliography.sgml,v 1.1.1.1.4.2 1995-10-12 03:15:45 jfieber Exp $ --> +<!-- $Id: bibliography.sgml,v 1.1.1.1.4.3 1996-06-19 20:27:26 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt> @@ -9,8 +9,8 @@ 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. + book on Unix system administration and a good users' + manual. <sect> <heading>Users' guides</heading> @@ -92,8 +92,8 @@ <newline>ISBN 0-201-51459-1</item> <item>Harbison, Samuel P. and Steele, Guy - L. Jr. <em>C: A Reference Manual</em>. 3rd ed. Prentice - Hall, 1991. <newline>ISBN 0-13-110933-2</item> + L. Jr. <em>C: A Reference Manual</em>. 4rd ed. Prentice + Hall, 1995. <newline>ISBN 0-13-326224-3</item> <item>Jolitz, William. "Porting UNIX to the 386". <em>Dr. Dobb's Journal</em>. January diff --git a/handbook/boothelp.sgml b/handbook/boothelp.sgml index 78db5f6c83..cef81a7c23 100644 --- a/handbook/boothelp.sgml +++ b/handbook/boothelp.sgml @@ -1,4 +1,4 @@ -<!-- $Id: boothelp.sgml,v 1.1 1995-09-03 21:12:24 jfieber Exp $ --> +<!-- $Id: boothelp.sgml,v 1.1.2.1 1996-06-19 20:27:27 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [ @@ -28,7 +28,7 @@ <abstract>Welcome to FreeBSD! This guide describes the FreeBSD installation process. To navigate through the sections in this guide using the <bf>up</bf> and - <bf>down</bf> arrow keys to select a section you wish to + <bf>down</bf> arrow keys to select the section you wish to read. Then use the <bf>right arrow</bf> or the <bf>enter key</bf> to view the section. You can backtrack through sections you have read by using the <bf>left arrow</bf>. diff --git a/handbook/booting.sgml b/handbook/booting.sgml index 5b4a38b3c4..589015aec8 100644 --- a/handbook/booting.sgml +++ b/handbook/booting.sgml @@ -3,7 +3,7 @@ This conversion has been made by Ollivier Robert. - $Id: booting.sgml,v 1.2.4.4 1996-01-31 14:32:10 mpp Exp $ + $Id: booting.sgml,v 1.2.4.5 1996-06-19 20:27:30 jkh Exp $ <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> @@ -51,13 +51,13 @@ Dosboot was written by DI. Christian Gusenbauer, and is unfortunately at this time one of the few pieces of code that - isn't compilable under FreeBSD itself because it is written for + will not compile under FreeBSD itself because it is written for Microsoft compilers. Dosboot will boot the kernel from a MS-DOS file or from a FreeBSD filesystem partition on the disk. It attempts to negotiate with the various and strange kinds of memory manglers that lurk in - high memory on MS/DOS systems and usually wins them for it's + high memory on MS/DOS systems and usually wins them for its case. <tag>Netboot</tag> @@ -83,7 +83,7 @@ <tag>MSDOS</tag> - While this is technically possible, it isn't particular useful, + While this is technically possible, it is not particular useful, because of ``FAT'' filesystems inability to make links, device nodes and such ``UNIXisms''. @@ -147,7 +147,7 @@ <tt>/nfs</tt>, chroots to <tt>/nfs</tt> and executes <tt>/sbin/init</tt> there - Now you run FreeBSD diskless, even though you don't control + Now you run FreeBSD diskless, even though you do not control the NFS server... <tag/C -- Start an X-server/ diff --git a/handbook/contrib.sgml b/handbook/contrib.sgml index a43fdc04e7..b67260a49b 100644 --- a/handbook/contrib.sgml +++ b/handbook/contrib.sgml @@ -1,4 +1,4 @@ -<!-- $Id: contrib.sgml,v 1.15.2.7 1996-05-15 17:35:24 joerg Exp $ --> +<!-- $Id: contrib.sgml,v 1.15.2.8 1996-06-19 20:27:31 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>FreeBSD contributor list<label id="contrib"></heading> @@ -36,10 +36,10 @@ couple of FreeBSD hackers alive and busy. Thanks! Thanks also to Dermot McDonnell for his donation of a - Toshiba XM3401B CDROM drive. It's been most useful! + Toshiba XM3401B CDROM drive. It has been most useful! - Thanks to Chuck Robey <chuckr@eng.umd.edu> who's been - contributing his floppy tape streamer for experimental + Thanks to Chuck Robey <chuckr@eng.umd.edu> who + contributed his floppy tape streamer for experimental work. Thanks to Larry Altneu <larry@ALR.COM>, and to Wilko Bulte @@ -58,43 +58,93 @@ <sect><heading>The FreeBSD core team<label id="contrib:core"></heading> - <p>(in alphabetical order by first name): + <p>(in alphabetical order by last name): <itemize> - <item>Andrey A. Chernov <ache@FreeBSD.org> - <item>Bruce Evans <bde@FreeBSD.org> - <item>David Greenman <davidg@FreeBSD.org> - <item>Garrett A. Wollman <wollman@FreeBSD.org> - <item>Gary Palmer <gpalmer@FreeBSD.org> - <item>Jörg Wunsch <joerg@FreeBSD.org> - <item>John Dyson <dyson@FreeBSD.org> - <item>Jordan K. Hubbard <jkh@FreeBSD.org> - <item>Justin Gibbs <gibbs@FreeBSD.org> - <item>Peter Wemm <peter@FreeBSD.org> - <item>Poul-Henning Kamp <phk@FreeBSD.org> - <item>Rich Murphey <rich@FreeBSD.org> - <item>Satoshi Asami <asami@FreeBSD.org> - <item>Søren Schmidt <sos@FreeBSD.org> + <item>&a.asami + <item>&a.ache + <item>&a.dyson + <item>&a.bde + <item>&a.gibbs + <item>&a.davidg + <item>&a.jkh + <item>&a.phk + <item>&a.rich + <item>&a.gpalmer + <item>&a.sos + <item>&a.peter + <item>&a.wollman + <item>&a.joerg </itemize> - <sect><heading>Who is responsible for what</heading> + <sect><heading>The FreeBSD Developers</heading> + + <p>These are the people who have commit privileges and do the work on + FreeBSD source tree. All core team members are also developers. + + <itemize> + <item>&a.torstenb; + <item>&a.gclarkii; + <item>&a.adam; + <item>&a.dufault; + <item>&a.uhclem; + <item>&a.julian; + <item>&a.sef; + <item>&a.se; + <item>&a.fenner; + <item>&a.jfieber; + <item>&a.lars; + <item>&a.tg; + <item>&a.graichen; + <item>&a.rgrimes; + <item>&a.hsu; + <item>&a.ugen; + <item>&a.gj; + <item>&a.ljo; + <item>&a.erich; + <item>&a.smace; + <item>&a.amurai; + <item>&a.markm; + <item>&a.alex; + <item>&a.olah; + <item>&a.wpaul; + <item>&a.jmacd; + <item>&a.jdp; + <item>&a.mpp; + <item>&a.dfr; + <item>&a.csgr; + <item>&a.martin; + <item>&a.paul; + <item>&a.roberto; + <item>&a.jraynard; + <item>&a.dima; + <item>&a.wosch; + <item>&a.ats; + <item>&a.karl; + <item>&a.pst; + <item>&a.guido; + <item>&a.swallace; + <item>&a.nate; + <item>&a.jmz; + </itemize> + <sect><heading>Who is responsible for what<label id="contrib:who"></heading> + <p><descrip> - <tag/President/ Jordan K. Hubbard <jkh@FreeBSD.org> - <tag/Principal Architect/ David Greenman <davidg@FreeBSD.org> - <tag/Documentation/ John Fieber <jfieber@FreeBSD.org> - <tag/Internationalization/ Andrey A. Chernov <ache@FreeBSD.org> - <tag/Networking/ Garrett A. Wollman <wollman@FreeBSD.org> - <tag/Postmaster/ Jonathan M. Bresler <jmb@FreeBSD.org> - <tag/Public Relations/ Jordan Hubbard <jkh@FreeBSD.org> - <tag/Release Coordinator/ Jordan Hubbard <jkh@FreeBSD.org> - <tag/Source Repository Manager/ Peter Wemm <peter@FreeBSD.org> - <tag/Ports Manager/ Satoshi Asami <asami@FreeBSD.org> - <tag/System Administration/ Gary Palmer <gpalmer@FreeBSD.org> - <tag/Webmasters/ John Fieber <jfieber@FreeBSD.org> and - James L. Robinson <jlrobin@FreeBSD.org> - <tag/XFree86 Project, Inc. Liason/ Rich Murphey - <rich@FreeBSD.org> + <tag/President/ &a.jkh + <tag/Principal Architect/ &a.davidg + <tag/Documentation/ &a.mpp + <tag/Internationalization/ &a.ache + <tag/Networking/ &a.wollman + <tag/Postmaster/ &a.jmb; + <tag/Public Relations/ &a.jkh + <tag/Release Coordinator/ &a.jkh + <tag/Security Officer/ &a.pst + <tag/Source Repository Manager/ &a.peter + <tag/Ports Manager/ &a.asami + <tag/System Administration/ &a.gpalmer + <tag/Webmasters/ &a.jkh; and &a.jfieber + <tag/XFree86 Project, Inc. Liason/ &a.rich </descrip> <sect><heading>Additional FreeBSD contributors</heading> @@ -102,28 +152,31 @@ <p>(in alphabetical order by first name): <itemize> - <item>Adam David <adam@veda.is> + <item>ABURAYA Ryushirou <pcs51674@asciinet.or.jp> <item>Adam Glass <glass@postgres.berkeley.edu> <item>Adrian T. Filipi-Martin <atf3r@agate.cs.virginia.edu> <item>Akito Fujita <fujita@zoo.ncl.omron.co.jp> <item>Alain Kalker <A.C.P.M.Kalker@student.utwente.nl> - <item>Andras Olah <olah@cs.utwente.nl> + <item>Alex Nash <nash@mcs.com> <item>Andreas Klemm <andreas@knobel.GUN.de> + <item>Andrew Gordon <andrew.gordon@net-tel.co.uk> <item>Andrew Herbert <andrew@werple.apana.org.au> + <item>Andrew McRae <amcrae@cisco.com> <item>Andrew Moore <alm@FreeBSD.org> + <item>Andrew V. Stesin <stesin@elvisti.kiev.ua> <item>Anthony Yee-Hang Chan <yeehang@netcom.com> - <item>Atsushi Murai <amurai@spec.co.jp> - <item>Bill Fenner <fenner@parc.xerox.com> - <item>Bill Paul <wpaul@FreeBSD.org> + <item>Bernd Rosauer <br@netland.inka.de> <item>Bob Wilcox <bob@obiwan.uucp> - <item>Brian Tao <taob@gate.sinica.edu.tw> + <item>Brent J. Nordquist <nordquist@platinum.com> + <item>Brian Clapper <bmc@telebase.com> + <item>Brian Tao <taob@io.org> <item>Charles Hannum <mycroft@ai.mit.edu> <item>Chet Ramey <chet@odin.INS.CWRU.Edu> <item>Chris G. Demetriou <cgd@postgres.berkeley.edu> - <item>Chris Provenzano <proven@athena.mit.edu> <item>Chris Stenton <jacs@gnome.co.uk> <item>Chris Torek <torek@ee.lbl.gov> <item>Christian Gusenbauer <cg@fimp01.fim.uni-linz.ac.at> + <item>Christian Haury <Christian.Haury@sagem.fr> <item>Christoph Robitschko <chmr@edvz.tu-graz.ac.at> <item>Chuck Hein <chein@cisco.com> <item>Chuck Robey <chuckr@Glue.umd.edu> @@ -131,97 +184,95 @@ <item>Craig Struble <cstruble@vt.edu> <item>Cristian Ferretti <cfs@riemann.mat.puc.cl> <item>Curt Mayer <curt@toad.com> + <item>Daniel Baker <dbaker@crash.ops.neosoft.com> + <item>Daniel M. Eischen <deischen@iworks.InterWorks.org> <item>Danny J. Zerkel <dzerkel@feephi.phofarm.com> <item>Dave Burgess <burgess@hrd769.brooks.af.mil> <item>Dave Chapeskie <dchapes@zeus.leitch.com> <item>Dave Rivers <rivers@ponds.uucp> <item>David Dawes <dawes@physics.su.OZ.AU> + <item>David O'Brien <obrien@cs.ucdavis.edu> <item>Dean Huxley <dean@fsa.ca> <item>Dirk Froemberg <dirk@hal.in-berlin.de> <item>Don Whiteside <dwhite@anshar.shadow.net> - <item>Eric L. Hernes <erich@lodgenet.com> + <item>Don Yuniskis <dgy@rtd.com> + <item>Donald Burr <d_burr@ix.netcom.com> + <item>Doug Ambrisko <ambrisko@ambrisko.roble.com> <item>Frank Bartels <knarf@camelot.de> - <item>Frank Durda IV <bsdmail@nemesis.lonestar.org> <item>Frank Maclachlan <fpm@crash.cts.com> <item>Frank Nobis <fn@trinity.radio-do.de> <item>Gary A. Browning <gab10@griffcd.amdahl.com> - <item>Gary Clark II <gclarkii@FreeBSD.ORG> - <item>Gary Jennejohn <gj%pcs.dec.com@inet-gw-1.pa.dec.com> <item>Gene Stark <stark@cs.sunysb.edu> - <item>Guido van Rooij <guido@gvr.win.tue.nl> + <item>Greg Ungerer <gerg@stallion.oz.au> + <item>Harlan Stenn <Harlan.Stenn@pfcs.com> <item>Havard Eidnes <Havard.Eidnes@runit.sintef.no> <item>Hideaki Ohmon <ohmon@sfc.keio.ac.jp> + <item>Hidetoshi Shimokawa <simokawa@sat.t.u-tokyo.ac.jp> <item>Holger Veit <Holger.Veit@gmd.de> <item>Ishii Masahiro, R. Kym Horsell - <item>J.T. Conklin <jtc@winsey.com> + <item>J.T. Conklin <jtc@cygnus.com> <item>James Clark <jjc@jclark.com> + <item>James FitzGibbon <james@nexis.net> <item>James da Silva <jds@cs.umd.edu> et al <item>Janusz Kokot <janek@gaja.ipan.lublin.pl> <item>Javier Martin Rueda <jmrueda@diatel.upm.es> - <item>Jean-Marc Zucconi <jmz@FreeBSD.ORG> + <item>Jian-Da Li <jdli@FreeBSD.csie.NCTU.edu.tw> <item>Jim Wilson <wilson@moria.cygnus.com> - <item>Jonathan Bresler < jmb@FreeBSD.ORG> - <item>Josh MacDonald <jmacd@uclink.berkeley.edu> + <item>John Capo <jc@irbs.com> + <item>John Hay <jhay@mikom.csir.co.za> + <item>John Perry <perry@vishnu.alias.net> <item>Juergen Lock <nox@jelal.hb.north.de> - <item>Julian Elischer <julian@dialix.oz.au> + <item>Julian Jenkins <kaveman@magna.com.au> <item>Julian Stacey <stacey@guug.de> (fallback: <julian@meepmeep.pcs.com>) <item>Keith Bostic <bostic@toe.CS.Berkeley.EDU> <item>Keith Moore <?> <item>Kirk McKusick <mckusick@mckusick.com> <item>Kurt Olsen <kurto@tiny.mcs.usu.edu> - <item>L Jonas Olsson <ljo@po.cwru.edu> - <item>Lars Fredriksen <fredriks@mcs.com> <item>Lucas James <Lucas.James@ldjpc.apana.org.au> <item>Marc Frajola <marc@dev.com> <item>Marc Ramirez <mrami@mramirez.sy.yale.edu <item>Marc van Kempen <wmbfmk@urc.tue.nl> - <item>Mark Murray <mark@grondar.za> <item>Mark Tinguely <tinguely@plains.nodak.edu> <tinguely@hookie.cs.ndsu.NoDak.edu> <item>Martin Birgmeier - <item>Martin Renters <martin@innovus.com> + <item>Masafumi Nakane <max@sfc.wide.ad.jp> <item>Matt Thomas <thomas@lkg.dec.com> - <item>Michael Elbel <me@freebsd.org> + <item>Michael Elbel <me@FreeBSD.ORG> <item>Michael Smith <msmith@atrad.adelaide.edu.au> - <item>Mike Pritchard <mpp@mpp.minn.net> + <item>Mike Peck <mike@binghamton.edu> + <item>MITA Yoshio <mita@iis.u-tokyo.ac.jp> <item>NIIMI Satoshi <sa2c@and.or.jp> - <item>Nate Williams <nate@FreeBSD.org> + <item>Nisha Talagala <nisha@cs.berkeley.edu> <item>Nobuhiro Yasutomi <nobu@psrc.isac.co.jp> <item>Nobuyuki Koganemaru <kogane@kces.koganemaru.co.jp> - <item>Ollivier Robert <roberto@FreeBSD.org> + <item>Noritaka Ishizumi <graphite@taurus.bekkoame.or.jp> <item>Paul Kranenburg <pk@cs.few.eur.nl> <item>Paul Mackerras <paulus@cs.anu.edu.au> - <item>Paul Richards <paul@FreeBSD.org> - <item>Paul Traina <pst@cisco.com> - <item>Peter Dufault <dufault@hda.com> - <item>Peter Wemm <peter@haywire.DIALix.COM> + <item>Peter Stubbs <PETERS@staidan.qld.edu.au> <item>Philippe Charnier <charnier@lirmm.fr> <item>Richard Stallman <rms@gnu.ai.mit.edu> + <item>Richard Wiwatowski <rjwiwat@adelaide.on.neti> <item>Rob Shady <rls@id.net> <item>Rob Snow <rsnow@txdirect.net> - <item>Rodney W. Grimes <rgrimes@FreeBSD.org> + <item>Robert Sanders <rsanders@mindspring.com> <item>Sascha Wildner <swildner@channelz.GUN.de> <item>Scott Blachowicz <scott@sabami.seaslug.org> - <item>Scott Mace <smace@FreeBSD.org> - <item>Sean Eric Fagan <sef@kithrup.com> <item>Serge V. Vakulenko <vak@zebub.msk.su> - <item>Stefan Esser <se@MI.Uni-Koeln.DE> <item>Stephen McKay <syssgm@devetir.qld.gov.au> <item>Steve Gerakines <steve2@genesis.tiac.net> <item>Steve Passe <smp@csn.net> - <item>Steven Wallace <swallace@ece.uci.edu> <item>Tatsumi Hosokawa <hosokawa@mt.cs.keio.ac.jp> + <item>Terry Lambert <terry@lambert.org> <item>Terry Lee <terry@uivlsi.csl.uiuc.edu> <item>Theo Deraadt <deraadt@fsa.ca> <item>Thomas Gellekum <thomas@ghpc8.ihf.rwth-aachen.de> <item>Tom Samplonius <tom@misery.sdf.com> <item>Torbjorn Granlund <tege@matematik.su.se> - <item>Torsten Blum <torstenb@FreeBSD.ORG> - <item>Ugen J.S.Antsilevich <ugen@latte.WorldBank.org> <item>Werner Griessl <werner@btp1da.phy.uni-bayreuth.de> + <item>Wes Santee <wsantee@wsantee.oz.net> <item>Wolfgang Stanglmeier <wolf@kintaro.cologne.de> - <item>Wolfram Schneider <wosch@cs.tu-berlin.de> + <item>Yoshiro Mihira <sanpei@yy.cs.keio.ac.jp> <item>Yuval Yarom <yval@cs.huji.ac.il> <item>Yves Fonk <yves@cpcoup5.tn.tudelft.nl> </itemize> @@ -264,7 +315,7 @@ <item>Herb Peyerl <hpeyerl@novatel.cuc.ab.ca <item>Holger Veit <Holger.Veit@gmd.de> <item>Ishii Masahiro, R. Kym Horsell - <item>J.T. Conklin <jtc@winsey.com> + <item>J.T. Conklin <jtc@cygnus.com> <item>Jagane D Sundar < jagane@netcom.com > <item>James Clark <jjc@jclark.com> <item>James Jegers <jimj@miller.cs.uwm.edu> @@ -291,9 +342,10 @@ <item>Marc Frajola <marc@dev.com> <item>Mark Tinguely <tinguely@plains.nodak.edu> <tinguely@hookie.cs.ndsu.NoDak.edu> - <item>Martin Renters <martin@innovus.com> + <item>Martin Renters <martin@tdc.on.ca> <item>Michael Galassi <nerd@percival.rain.com> <item>Mike Durkin <mdurkin@tsoft.sf-bay.org> + <item>Naoki Hamada <nao@sbl.cl.nec.co.jp> <item>Nate Williams <nate@bsd.coe.montana.edu> <item>Nick Handel <nhandel@NeoSoft.com> <nick@madhouse.neosoft.com> @@ -303,6 +355,7 @@ <item>Paul Popelka <paulp@uts.amdahl.com> <item>Peter da Silva <peter@NeoSoft.com> <item>Phil Sutherland <philsuth@mycroft.dialix.oz.au> + <item>Poul-Henning Kamp<phk@FreeBSD.ORG> <item>Ralf Friedl <friedl@informatik.uni-kl.de> <item>Rick Macklem <root@snowhite.cis.uoguelph.ca> <item>Robert D. Thrush <rd@phoenix.aii.com> @@ -324,7 +377,3 @@ <item>Wolfgang Stanglmeier <wolf@dentaro.GUN.de> <item>Yuval Yarom <yval@cs.huji.ac.il> </itemize> - - Last, but not least, the release engineer would like to - thank: His Wife, for chocolate chip cookies, and some other - things. The DGB project @ TFS, for patience and tolerance. diff --git a/handbook/ctm.sgml b/handbook/ctm.sgml index 51624ad081..397437561b 100644 --- a/handbook/ctm.sgml +++ b/handbook/ctm.sgml @@ -3,7 +3,7 @@ # # Converted by Ollivier Robert <roberto@FreeBSD.ORG> # -# $Id: ctm.sgml,v 1.1.1.1.4.4 1996-01-31 14:32:13 mpp Exp $ +# $Id: ctm.sgml,v 1.1.1.1.4.5 1996-06-19 20:27:32 jkh Exp $ # # ---------------------------------------------------------------------------- # "THE BEER-WARE LICENSE" (Revision 42): @@ -52,7 +52,7 @@ current <tt/CTM/ sources directly from: <url - url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm"> + 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 e-mail. If you have general FTP access to the Internet then the following @@ -66,7 +66,7 @@ If you only have access to electronic mail or are otherwise blocked from using FTP then you may wish to get your deltas via email: - Send email to <tt/<majordomo@freebsd.org>/ to subscribe to + Send email to &a.majordomo 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.) @@ -79,10 +79,10 @@ 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/ + deltas, you should subscribe to the <tt/ctm-announce@FreeBSD.ORG/ mailing list. In the future, this will be the only place where announcements concerning the operations of the <tt/CTM/ system will be - posted. Send an email to <tt/majordomo@freebsd.org/ with a single + posted. Send an email to &a.majordomo with a single line of ``<tt/subscribe ctm-announce/'' to get added to the list. <sect1><heading>Starting off with <tt/CTM/ for the first time</heading> @@ -97,7 +97,7 @@ 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 - retrieve the <tt/src-cur.0372R20.gz/ file, it's only 4Mb and it + retrieve the <tt/src-cur.0372R20.gz/ file, it is 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 @@ -110,11 +110,11 @@ 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 disk space. + so you do not need to gunzip them first, this saves disk space. Unless it feels very secure about the entire process, <tt/CTM/ will not touch your tree. To verify a delta you can also use the - ``<tt/-c/'' flag and <tt/CTM/ won't actually touch your tree; it will + ``<tt/-c/'' flag and <tt/CTM/ will not actually touch your tree; it will merely verify the integrity of the delta and see if it would apply cleanly to your current tree. @@ -122,13 +122,13 @@ for more details. 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 + interface'' portions, as I have realized that I cannot make up my mind on what options should do what, how and when... That's really all there is to it. Every time you get a new delta, just run it through <tt/CTM/ to keep your sources up to date. - Don't remove the deltas if they are hard to download again. You + Do not 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. @@ -157,7 +157,7 @@ </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... + be most welcome. And do not forget to tell me what you want also... <sect1><heading>Miscellaneous stuff</heading> <p> @@ -174,7 +174,7 @@ 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. + an email list for that too and we will consider setting it up. If you have commit privileges or are similarly authorized by the FreeBSD core team, you can also get access to the CVS repository @@ -187,7 +187,7 @@ <descrip> <tag/Bruce Evans/ for his pointed pen and invaluable comments. - <tag/Soren Schmidt/ + <tag/Søren Schmidt/ for patience. <tag/Stephen McKay/ wrote <tt/ctm_[rs]mail/, much appreciated. diff --git a/handbook/current.sgml b/handbook/current.sgml index 210512ebe9..1a745486e4 100644 --- a/handbook/current.sgml +++ b/handbook/current.sgml @@ -1,4 +1,4 @@ -<!-- $Id: current.sgml,v 1.2.4.3 1995-10-18 04:36:25 jfieber Exp $ --> +<!-- $Id: current.sgml,v 1.2.4.4 1996-06-19 20:27:33 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> @@ -10,41 +10,43 @@ THE FREEBSD CURRENT POLICY -Last updated: $Date: 1995-10-18 04:36:25 $ +Last updated: $Date: 1996-06-19 20:27:33 $ -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. +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. +<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 un-compilable. +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 are interested in +getting something tested, not because we are in the business of +providing binary releases of current. If we do not offer, please do not +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 actively working on some + part 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 + <item> Members of the FreeBSD group who are active testers, + 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. @@ -58,8 +60,8 @@ too much time to do this as a general task. <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 + <item> A fast-track to getting pre-release bits because you heard there's + some cool new feature in there and you want to be the first on your block to have it. <item> A quick way of getting bug fixes. @@ -70,22 +72,22 @@ too much time to do this as a general task. ``legitimate'' FreeBSD-current categories, 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 + experimental system software. This is not because we are mean and + nasty people who do not like helping people out (we would not even be + doing FreeBSD if we were), it is literally because we cannot answer + 400 messages a day <em>and</em> actually work on FreeBSD! I am sure + that, if given the choice between having us answer lots of questions or + continuing 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-current and cvs-all - mailing lists. This is not just a good idea, it's - <em>essential</em>. If you aren't on freebsd-current, you - won't read the comments that people are making about the - current state of the system and thus will end up stumbling + mailing lists. This is not just a good idea, it is + <em>essential</em>. If you are not on the &a.current, you + will not see the comments that people are making about the + current state of the system and thus will probably 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! @@ -93,12 +95,10 @@ too much time to do this as a general task. rebuild the kernel or your system will crash horribly!"). The cvs-all mailing list will allow you to see the commit log - entry for each change as it's made. This can also contain - important information, and will let you know what parts of - the system are being actively changed. + entry for each change as it is made along with any pertinent + information on possible side-effects. - To join these lists, send mail to `majordomo@FreeBSD.ORG' - and say: + To join these lists, send mail to &a.majordomo and specify: <verb> subscribe current subscribe cvs-all @@ -118,16 +118,15 @@ too much time to do this as a general task. <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 + you to grab the entire collection once and then only what has changed from then on. Many people run sup from cron and keep their sources up-to-date automatically. <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 + <htmlurl url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable" + name="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current"> + We also use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: <verb> usr.bin/lex @@ -145,31 +144,21 @@ too much time to do this as a general task. communications bandwidth is not a consideration, use sup or ftp. Otherwise, use CTM. - <item> If you're grabbing the sources to run, and not just look at, + <item> If you are 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 + 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. + carefully. You should at least run a `make world' the first time + through as part of the upgrading process. + Reading the &a.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 + <item> Be active! If you are 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 index 1848075b3c..ed382e0628 100644 --- a/handbook/dialup.sgml +++ b/handbook/dialup.sgml @@ -1,6 +1,6 @@ <!-- 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.4.3 1996-01-31 14:32:14 mpp Exp $ + $Id: dialup.sgml,v 1.1.1.1.4.4 1996-06-19 20:27:35 jkh Exp $ <!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN"> @@ -68,10 +68,10 @@ 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 +When talking about communications data rates, the author does notuse 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 +per second) is the ``correct'' term to use (at least it does not seem to bother the curmudgeons quite a much). <sect2><heading>External vs. Internal Modems</heading> @@ -97,7 +97,7 @@ 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 +two can communicate (unless you have an internal modem, which does not need such a cable) <item> You are familiar with your modem's command set, or know where @@ -134,7 +134,7 @@ 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 +The second prerequisite depends on the modem(s) you use. If you do not 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 @@ -208,10 +208,10 @@ 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 +command: <tscreen><verb> -/usr/sbin/dmesg | grep 'sio' +/sbin/dmesg | grep 'sio' </verb></tscreen> For example, on a system with four serial ports, these are the @@ -228,26 +228,28 @@ 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 +If your kernel does not recognize all of your serial ports, you will 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 +Options'' [in <tt>/sys/conf/options</tt> and in +<tt>/sys/<em>arch</em>/conf/options.<em>arch</em></tt>, with +<em>arch</em> for example being <tt>i386</tt>] for more information on configuring and building kernels. You may have to -unpack the kernel source distribution if haven't installed the system +unpack the kernel source distribution if have not 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 +Create a kernel configuration file for your system (if you have not 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 +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 @@ -256,7 +258,7 @@ 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 +You can comment-out or completely remove lines for devices you do not 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 @@ -269,7 +271,7 @@ Note that <tt/port "IO_COM1"/ is a substitution for <tt/port 0x3f8/, <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 +<bf>cannot</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). @@ -317,7 +319,7 @@ 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 +special files can read & write on them - you probably do not 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: @@ -334,7 +336,7 @@ These permissions allow the user <tt/uucp/ and users in the group <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 +directory that yo will 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 @@ -349,8 +351,8 @@ 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 +The downside is that the system does not know what a user's true data +rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections. @@ -358,17 +360,17 @@ 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 +modem's RS-232 interface run at 2400 bps. Because <tt/getty/ does not 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 +it is 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 +the data rates do not 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 +Obviously, this login sequence does not look as clean as the former ``locked-speed'' method, but a user on a low-speed connection should receive better interactive response from full-screen programs. @@ -388,17 +390,17 @@ the file and the list of capabilities. <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 +particular speed, you probably will not need to make any changes to <tt>/etc/gettytab</tt>. <sect3><heading>Matching-Speed Config</heading> <p> -You'll need to setup an entry in <tt>/etc/gettytab</tt> to give +You will 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 +1.1.5.1 <tt/gettytab/ file, so you do not need to add it unless it is missing under your version of FreeBSD: <tscreen><verb> @@ -413,8 +415,8 @@ D2400|d2400|Fast-Dial-2400:\ :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 +If you have a higher speed modem, you will probably need to add an entry +in <tt>/etc/gettytab</tt>; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kpbs: <tscreen><verb> @@ -448,7 +450,7 @@ 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 +communications rate than 19.2 Kbps. Here is an example of a <tt/gettytab/ entry starting a 57.6 Kpbs: <tscreen><verb> @@ -468,11 +470,11 @@ 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 +If you have a slow CPU or a heavily loaded system and you dobnot have 16550A-based serial ports, you may receive sio ``silo'' errors at 57.6 Kbps. -<sect2><heading>/etc/ttys</heading> +<sect2><heading>/etc/ttys<label id="dialup:ttys"></heading> <p> <tt>/etc/ttys</tt> is the list of <tt/ttys/ for <tt/init/ to monitor. @@ -480,7 +482,7 @@ Kbps. (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 +You will 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 @@ -586,7 +588,7 @@ stty -f /dev/ttyd2 crtscts stty -f /dev/ttyd3 crtscts </verb></tscreen> -Since there isn't an initialization device special file on FreeBSD +Since there is no 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. @@ -594,7 +596,7 @@ hope the flags aren't cleared by a miscreant. <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 +non-volatile RAM, you will 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 @@ -642,7 +644,7 @@ settings as an example: <item> Switch 1: UP - DTR Normal -<item> Switch 2: Don't care (Verbal Result Codes/Numeric Result Codes) +<item> Switch 2: Do not care (Verbal Result Codes/Numeric Result Codes) <item> Switch 3: UP - Suppress Result Codes @@ -654,20 +656,20 @@ settings as an example: <item> Switch 7: UP - Load NVRAM Defaults -<item> Switch 8: Don't care (Smart Mode/Dumb Mode) +<item> Switch 8: Do not 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 +command or returns a result code. I have heard this sequence can result in a extended, silly conversation between <tt/getty/ and the modem. <sect2><heading>Locked-speed Config</heading> <p> -For a locked-speed configuration, you'll need to configure the modem +For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a USR Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used @@ -681,7 +683,7 @@ AT&B1&W <sect2><heading>Matching-speed Config</heading> <p> -For a variable-speed configuration, you'll need to configure your +For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a USR Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue @@ -739,13 +741,13 @@ If you see something different, like this: ^^ </verb></tscreen> -and the modem hasn't accepted a call yet, this means that <tt/getty/ +and the modem has not 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 +If you do not 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 @@ -759,15 +761,15 @@ missing device special files. <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 +bit on the remote system. If you do not 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, +second. If you still do not 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 +If you still cannot get a <tt/login:/ prompt, check <tt>/etc/gettytab</tt> again and double-check that <itemize> @@ -782,17 +784,17 @@ name </itemize> -If you dial but the modem on the FreeBSD system won't answer, make +If you dial but the modem on the FreeBSD system will not 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. +If you have gone over everything several times and it still does not work, +take a break and come back to it later. If it still does not work, +perhaps you can send an electronic mail message to the &a.questions +describing your modem and youer problem, and the good folks on the list will +try to help. <sect1><heading>Acknowledgments</heading> <p> @@ -801,8 +803,7 @@ Thanks to these people for comments and advice: <descrip> -<tag/Sean Kelly/ <kelly@fsl.noaa.gov> for a number of good -suggestions +<tag>&a.kelly</tag> for a number of good suggestions </descrip> diff --git a/handbook/diskless.sgml b/handbook/diskless.sgml index 9947afc4cb..4de06487b5 100644 --- a/handbook/diskless.sgml +++ b/handbook/diskless.sgml @@ -1,4 +1,4 @@ -<!-- $Id: diskless.sgml,v 1.1.1.1.4.3 1996-01-31 14:32:15 mpp Exp $ --> +<!-- $Id: diskless.sgml,v 1.1.1.1.4.4 1996-06-19 20:27:36 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>Diskless operation<label id="diskless"></heading> @@ -117,7 +117,7 @@ hostname myclient.mydomain <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 + machines. Prior versions do not allow the creation of device files over NFS. <item> When extracting <tt>/dev</tt> in diff --git a/handbook/dma.sgml b/handbook/dma.sgml index 9e56dfab06..02b190e8d3 100644 --- a/handbook/dma.sgml +++ b/handbook/dma.sgml @@ -1,4 +1,4 @@ -<!-- $Id: dma.sgml,v 1.1.2.3 1996-01-31 14:32:16 mpp Exp $ --> +<!-- $Id: dma.sgml,v 1.1.2.4 1996-06-19 20:27:38 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -156,7 +156,7 @@ If a peripheral wants to generate an interrupt when the transfer of a buffer is complete, it can test for its -DACK signal and the EOP signal both being asserted at - the same time. When that happens, it means the DMA won't + the same time. When that happens, it means the DMA will not transfer any more information for that peripheral without intervention by the CPU. The peripheral can then assert one of the interrupt signals to get the processors' @@ -223,7 +223,7 @@ PC-compatible DMA cannot access locations above 16Meg. To get around this restriction, operating systems will - reserve a buffer in an area below 16Meg that also doesn't + reserve a buffer in an area below 16Meg that also does not span a physical 64K boundary. Then the DMA will be programmed to read data to that buffer. Once the DMA has moved the data into this buffer, the operating system diff --git a/handbook/eresources.sgml b/handbook/eresources.sgml index 4e9a4d04b3..52a213e55a 100644 --- a/handbook/eresources.sgml +++ b/handbook/eresources.sgml @@ -1,80 +1,82 @@ -<!-- $Id: eresources.sgml,v 1.2.4.4 1996-01-31 14:32:17 mpp Exp $ --> +<!-- $Id: eresources.sgml,v 1.2.4.5 1996-06-19 20:27:40 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt> <heading>Resources on the Internet<label id="eresources"></heading> + <p><em>Contributed by &a.jkh;.</em> + <p>The rapid pace of FreeBSD progress makes print media impractical as a means for following the latest - developments. Electronic resources are the best, if not the - only way stay informed of the latest advances. Also, since - FreeBSD is a volunteer effort, the user community also serves - as the technical support department and invariably, - electronic mail and Usenet news are the most effective way of - getting technical problems resolved. - - Below, the most important points of contact with the FreeBSD - user community are outlined. If you are aware of other - resources not included, please send them to - <tt>doc@freebsd.org</tt> so they may be included. + developments. Electronic resources are the best, if not often the + only way stay informed of the latest advances. Since + FreeBSD is a volunteer effort, the user community itself also generally + serves as a `technical support department' of sorts, with electronic mail + and Usenet news being the most effective way of reaching that community. + + The most important points of contact with the FreeBSD + user community are outlined below. If you are aware of other + resources not mentioned here, please send them to the &a.doc + so that they may also be included. <sect> <heading>Mailing lists<label id="eresources:mail"></heading> <p>Though many of the FreeBSD development members read USENET, we cannot -always guarantee that we'll get to your questions in a timely fashion -(or at all) if you post them only to one of the comp.unix.bsd.* +always guarantee that we will get to your questions in a timely fashion +(or at all) if you post them only to one of the comp.unix.bsd.freebsd.* groups. By addressing your questions to the appropriate mailing list you will reach both us and a concentrated FreeBSD audience, invariably assuring a better (or at least faster) response. -There are list charters at the bottom of this document. Please read -the list charter before joining a list. We must strive to -keep the signal to noise ratio of the lists high, especially in -the technical lists. +<p>The charters for the various lists are given at the bottom of this +document. Please read the charter before joining a list since we must +strive to keep the signal to noise ratio of the lists high, especially +in the technical ones. Archives are kept for all of the mailing lists and can be searched -using the the <url url="http://www.freebsd.org/" +using the the <url url="http://www.FreeBSD.ORG/search.html" name="FreeBSD World Wide Web server">. The keyword searchable archive -offers an excellent way to find answers to frequently asked questions -and should be consulted before posting a question. +offers an excellent way of finding answers to frequently asked +questions and should be consulted before posting a question. <sect1><heading>List summary</heading> -<p><bf>General lists:</bf> The following are general lists that +<p><bf>General lists:</bf> The following are general lists which anyone is free to join: <verb> List Purpose ---------------------------------------------------------------------- -freebsd-announce Important events / milestones +freebsd-announce Important events and project milestones freebsd-bugs Bug reports -freebsd-chat Non technical items related to the community -freebsd-current Discussions about the use of FreeBSD-current -freebsd-isp Issues for ISP's using FreeBSD -freebsd-policy Policy issues and suggestions +freebsd-chat Non-technical items related to the FreeBSD community +freebsd-current Discussion concerning the use of FreeBSD-current +freebsd-stable Discussion concerning the use of FreeBSD-stable +freebsd-isp Issues for Internet Service Providers using FreeBSD +freebsd-policy General policy issues and suggestions freebsd-questions User questions </verb> -<bf>Technical lists:</bf> The following are the technical lists. You should -read the charter carefully before joining them, and you should keep -your e-mail within the scope of the guidelines. +<bf>Technical lists:</bf> The following lists are for technical discussion. +You should read the charter carefully before joining one, keeping any +messages sent to a list within the scope of the guidelines. <verb> List Purpose ---------------------------------------------------------------------- -freebsd-doc Documentation project +freebsd-doc The FreeBSD Documentation project +freebsd-emulation Emulation of other systems such as Linux/DOS/Windows freebsd-fs Filesystems -freebsd-hackers General Technical discussions -freebsd-hardware General discussion of FreeBSD hardware -freebsd-multimedia Multimedia discussions -freebsd-platforms Porting to Non-Intel platforms -freebsd-ports Discussion of "ports" +freebsd-hackers General technical discussion +freebsd-hardware General discussion of hardware for running FreeBSD +freebsd-multimedia Multimedia discussion +freebsd-platforms Concerning ports to non-Intel architecture platforms +freebsd-ports Discussion of the ports collection freebsd-security Security issues -freebsd-scsi SCSI subsystem +freebsd-scsi The SCSI subsystem </verb> -<bf>Limited lists:</bf> The following are limited lists that you will need -approval to join. Even though access to these lists is controled, -anyone is free to send suggestions and comments to them. It is a +<bf>Limited lists:</bf> The following lists require approval to join, +though anyone is free to send suggestions and comments to them. It is a good idea establish a presence in the technical lists before asking to join one of these limited lists. <verb> @@ -87,8 +89,8 @@ freebsd-install Installation development freebsd-user-groups User group coordination </verb> -<bf>CVS lists:</bf> The following lists are for people seeing the log messages -for source changes in specific areas: +<bf>CVS lists:</bf> The following lists are for people interested in +seeing the log messages for changes to various areas of the source tree. <verb> List name Source area Area Description (source for) ---------------------------------------------------------------------- @@ -113,15 +115,10 @@ cvs-usrsbin /usr/src/usr.sbin System binaries <sect1><heading>How to subscribe</heading> <p>All mailing lists live on <tt>FreeBSD.ORG</tt>, so to post to a -list you simply mail to <em>listname</em><tt>@FreeBSD.ORG</tt>. It -will then be redistributed to mailing list members throughout the -world. +given list you simply mail to <em>listname</em><tt>@FreeBSD.ORG</tt>. It +will then be redistributed to mailing list members world-wide. -To subscribe to a list, send mail to: -<tscreen><verb> -majordomo@FreeBSD.ORG -</verb></tscreen> -And include the keyword +To subscribe to a list, send mail to &a.majordomo and include <tscreen><verb> subscribe <listname> [<optional address>] </verb></tscreen> @@ -150,10 +147,10 @@ list of available commands, do this: help ^D </verb></tscreen> -Finally, we again request that you keep the technical mailing lists on -a technical track. If you're only interested in the "high points", -then it's suggested that you join freebsd-announce, which will contain -only infrequent traffic. +Again, we would like to request that you keep discussion in the technical mailing +lists on a technical track. If you are only interested in the "high points" +then it is suggested that you join freebsd-announce, which is intended only +for infrequent traffic. <sect1><heading>List charters</heading> @@ -182,7 +179,7 @@ submitted using "send-pr". community</em><newline> This list contains the overflow from the other lists about non-technical, social information. It includes discussion about -whether Jordan looks like a tune ferret or not, whether or not to +whether Jordan looks like a toon ferret or not, whether or not to type in capitals, who is drinking too much coffee, where the best beer is brewed, who is brewing beer in their basement, and so on. Occasional announcements of important events (such as upcoming @@ -206,6 +203,13 @@ freebsd-current mailing list. The digest consists of all messages sent to freebsd-current bundled together and mailed out as a single message. The average digest size is about 40kB. +<tag/FREEBSD-STABLE/ <em>Discussions about the use of +FreeBSD-stable</em><newline> This is the mailing list for users +of freebsd-stable. It includes warnings about new features +coming out in -stable that will affect the users, and +instructions on steps that must be taken to remain -stable. +Anyone running ``stable'' should subscribe to this list. + <tag/FREEBSD-DOC/ <em>Documentation project</em><newline> This mailing list belongs to the FreeBSD Doc Project and is for the discussion of documentation related issues and projects. @@ -304,53 +308,70 @@ User Groups. <heading>BSD specific newsgroups</heading> <p><itemize> - <item>comp.unix.bsd.freebsd.announce - <item>comp.unix.bsd.freebsd.misc + <item><url url="news:comp.unix.bsd.freebsd.announce" + name="comp.unix.bsd.freebsd.announce"></item> + <item><url url="news:comp.unix.bsd.freebsd.misc" + name="comp.unix.bsd.freebsd.misc"></item> </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 + <item><url url="news:comp.unix" name="comp.unix"></item> + <item><url url="news:comp.unix.questions" name="comp.unix.questions"></item> + <item><url url="news:comp.unix.admin" name="comp.unix.admin"></item> + <item><url url="news:comp.unix.programmer" name="comp.unix.programmer"></item> + <item><url url="news:comp.unix.shell" name="comp.unix.shell"></item> + <item><url url="news:comp.unix.user-friendly" name="comp.unix.user-friendly"></item> + <item><url url="news:comp.security.unix" name="comp.security.unix"></item> + <item><url url="news:comp.sources.unix" name="comp.sources.unix"></item> + <item><url url="news:comp.unix.advocacy" name="comp.unix.advocacy"></item> + <item><url url="news:comp.unix.misc" name="comp.unix.misc"></item> + <item><url url="news:comp.os.386bsd.announc" name="comp.os.386bsd.announc"></item> + <item><url url="news:comp.os.386bsd.app" name="comp.os.386bsd.app"></item> + <item><url url="news:comp.os.386bsd.bugs" name="comp.os.386bsd.bugs"></item> + <item><url url="news:comp.os.386bsd.development" name="comp.os.386bsd.development"></item> + <item><url url="news:comp.os.386bsd.misc" name="comp.os.386bsd.misc"></item> + <item><url url="news:comp.os.386bsd.questions" name="comp.os.386bsd.questions"></item> + <item><url url="news:comp.bugs.4bsd" name="comp.bugs.4bsd"></item> + <item><url url="news:comp.bugs.4bsd.ucb-fixes" name="comp.bugs.4bsd.ucb-fixes"></item> + <item><url url="news:comp.unix.bsd" name="comp.unix.bsd"></item> </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 + <item><url url="news:comp.windows.x.i386unix" name="comp.windows.x.i386unix"></item> + <item><url url="news:comp.windows.x" name="comp.windows.x"></item> + <item><url url="news:comp.windows.x.apps" name="comp.windows.x.apps"></item> + <item><url url="news:comp.windows.x.announce" name="comp.windows.x.announce"></item> + <item><url url="news:comp.windows.x.intrinsics" name="comp.windows.x.intrinsics"></item> + <item><url url="news:comp.windows.x.motif" name="comp.windows.x.motif"></item> + <item><url url="news:comp.windows.x.pex" name="comp.windows.x.pex"></item> + <item><url url="news:comp.emulators.ms-windows.wine" name="comp.emulators.ms-windows.wine"></item> </itemize> <sect> <heading>World Wide Web servers<label id="eresources:web"></heading> <p><itemize> - <item><url url="http://www.freebsd.org/"></item> + <item><url url="http://www.FreeBSD.ORG/"> <bf>- Central Server</bf>.</item> + <item><url url="http://www.au.freebsd.org/FreeBSD/"> <bf>- Australia</bf>.</item> + <item><url url="http://www.br.freebsd.org/"> <bf>- Brazil</bf>.</item> + <item><url url="http://www.ca.freebsd.org/"> <bf>- Canada</bf>.</item> + <item><url url="http://sunsite.mff.cuni.cz/www.freebsd.org/"><bf>- Czech Republic</bf>.</item> + <item><url url="http://sunsite.auc.dk/www.freebsd.org/"> <bf>- Denmark</bf>.</item> + <item><url url="http://www.ee.freebsd.org/"> <bf>- Estonia</bf>.</item> + <item><url url="http://www.fi.freebsd.org/"> <bf>- Finland</bf>.</item> + <item><url url="http://www.de.freebsd.org/"> <bf>- Germany</bf>.</item> + <item><url url="http://www.ie.freebsd.org/"> <bf>- Ireland</bf>.</item> + <item><url url="http://www.jp.freebsd.org/"> <bf>- Japan</bf>.</item> + <item><url url="http://www.kr.freebsd.org/"> <bf>- Korea</bf>.</item> + <item><url url="http://www.nl.freebsd.org/"> <bf>- Netherlands</bf>.</item> + <item><url url="http://www.pt.freebsd.org/"> <bf>- Portugal</bf>.</item> + <item><url url="http://www.se.freebsd.org/www.freebsd.org/"> <bf>- Sweden</bf>.</item> + <item><url url="http://www.tw.freebsd.org/freebsd.html"> <bf>- Taiwan</bf>.</item> </itemize> </sect> diff --git a/handbook/esdi.sgml b/handbook/esdi.sgml index 19f7f4c753..2f4bade5b2 100644 --- a/handbook/esdi.sgml +++ b/handbook/esdi.sgml @@ -1,4 +1,4 @@ -<!-- $Id: esdi.sgml,v 1.2.2.1 1996-01-31 14:32:18 mpp Exp $ --> +<!-- $Id: esdi.sgml,v 1.2.2.2 1996-06-19 20:27:42 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -21,7 +21,7 @@ </abstract> --> - <sect><heading>ESDI hard disks and FreeBSD<label id="esdi"></heading> + <sect1><heading>Using ESDI hard disks<label id="esdi"></heading> <p><em>Copyright © 1995, &a.wilko;.<newline>24 September 1995.</em> @@ -40,15 +40,15 @@ Capacities of the drives are boosted by putting more sectors on each track. Typical is 35 sectors per track, high capacity - drives I've seen were up to 54 sectors/track. + drives I have seen were up to 54 sectors/track. Although ESDI has been largely obsoleted by IDE and SCSI interfaces, the availability of free or cheap surplus drives makes them ideal for low (or now) budget systems. - <sect1><heading>Concepts of ESDI</heading> + <sect2><heading>Concepts of ESDI</heading> <p> - <sect2><heading>Physical connections</heading> + <sect3><heading>Physical connections</heading> <p> The ESDI interface uses two cables connected to each drive. One cable is a 34 pin flat cable edge connector that carries @@ -59,7 +59,7 @@ The second cable is a a 20 pin flat cable edge connector that carries the data to and from the drive. This cable is radially - connected, so each drive has it's own direct connection to the + connected, so each drive has its own direct connection to the controller. To the best of my knowledge PC ESDI controllers are limited @@ -67,7 +67,7 @@ compatibility feature(?) left over from the WD1003 standard that reserves only a single bit for device addressing. - <sect2><heading>Device addressing</heading> + <sect3><heading>Device addressing</heading> <p> On each command cable a maximum of 7 devices and 1 controller can be present. To enable the controller to uniquely @@ -76,11 +76,11 @@ On PC type controllers the first drive is set to address 0, the second disk to address 1. <it>Always make sure</it> you - set each disk to an unique address! So, on a PC with it's + set each disk to an unique address! So, on a PC with its two drives/controller maximum the first drive is drive 0, the second is drive 1. - <sect2><heading>Termination</heading> + <sect3><heading>Termination</heading> <p> The daisy chained command cable (the 34 pin cable remember?) needs to be terminated at the last drive on the chain. @@ -90,12 +90,12 @@ So, one and <it>only</it> one drive, the one at the farthest end of the command - cable has it's terminator installed/enabled. The controller + cable has its terminator installed/enabled. The controller automatically terminates the other end of the cable. Please note that this implies that the controller must be at one end of the cable and <it>not</it> in the middle. - <sect1><heading>Using ESDI disks with FreeBSD</heading> + <sect2><heading>Using ESDI disks with FreeBSD</heading> <p> Why is ESDI such a pain to get working in the first place? @@ -109,7 +109,7 @@ The following sections try to list all the pitfalls and solutions. - <sect2><heading>ESDI speed variants</heading> + <sect3><heading>ESDI speed variants</heading> <p> As briefly mentioned before, ESDI comes in two speed flavors. The older drives and controllers use a 10 Mbits/second @@ -120,7 +120,7 @@ As always, consult your controller <it>and</it> drive documentation to see if things match. - <sect2><heading>Stay on track</heading> + <sect3><heading>Stay on track</heading> <p> Mainstream ESDI drives use 34 to 36 sectors per track. Most (older) controllers cannot handle more than this @@ -139,7 +139,7 @@ or might not work. Give it a try or get another more capable controller. - <sect2><heading>Hard or soft sectoring</heading> + <sect3><heading>Hard or soft sectoring</heading> <p> Most ESDI drives allow hard or soft sectoring to be selected using a jumper. Hard sectoring means that the @@ -167,7 +167,7 @@ FreeBSD because you need to re-run the low-level format after each change. - <sect2><heading>Low level formatting</heading> + <sect3><heading>Low level formatting</heading> <p> ESDI drives need to be low level formatted before they are usable. A reformat is needed whenever you figgle @@ -191,7 +191,7 @@ and more importantly causes you grief with bad144 (see the section on bad144). - <sect2><heading>Translations</heading> + <sect3><heading>Translations</heading> <p> Translations, although not exclusively a ESDI-only problem, might give you real trouble. @@ -219,8 +219,8 @@ The result is that the number of cylinders is reduced to something below 1024 and is therefore usable by the system without problems. - It is noteworthy to know that FreeBSD after it's kernel has - started no longer uses the BIOS. More on this later. + It is noteworthy to know that FreeBSD does not use the + BIOS after its kernel has started. More on this later. A second reason for translations is the fact that most older system BIOSes could only handle drives with 17 sectors @@ -232,7 +232,7 @@ keep in mind that if you have multiple operating systems on the same disk, all must use the same translation</em> - While on the subject of translations, I've seen one controller + While on the subject of translations, I have seen one controller type (but there are probably more like this) offer the option to logically split a drive in multiple partitions as a BIOS option. I had select 1 drive == 1 partition because this @@ -240,7 +240,7 @@ read the info and presented itself to the system based on the info from the disk. - <sect2><heading>Spare sectoring</heading> + <sect3><heading>Spare sectoring</heading> <p> Most ESDI controllers offer the possibility to remap bad sectors. During/after the low-level format of the disk bad sectors are @@ -265,7 +265,7 @@ whatever it may be called by the controller manufacturer when you want to use the disk for FreeBSD.</em> - <sect2><heading>Bad block handling</heading> + <sect3><heading>Bad block handling</heading> <p> The preceding section leaves us with a problem. The controller's bad block handling is not usable and still FreeBSD's filesystems @@ -276,8 +276,8 @@ these bad blocks, it writes a table with the offending block numbers to the end of the FreeBSD slice. - When the disk is in operation, the diskaccesses are checked - against the table read from the disk. Whenever a blocknumber + When the disk is in operation, the disk accesses are checked + against the table read from the disk. Whenever a block number is requested that is in the bad144 list, a replacement block (also from the end of the FreeBSD slice) is used. In this way, the bad144 replacement scheme presents 'perfect' @@ -303,7 +303,7 @@ rather the entire <em>slice</em> that contains the root filesystem. - <sect2><heading>Kernel configuration</heading> + <sect3><heading>Kernel configuration</heading> <p> ESDI disks are handled by the same <it>wd</it>driver as IDE and ST412 MFM disks. The <it>wd</it> driver should work @@ -332,13 +332,13 @@ disk wd3 at wdc1 drive 1 </verb></tscreen> <!-- - <sect2><heading>Tuning your ESDI kernel setup</heading> + <sect3><heading>Tuning your ESDI kernel setup</heading> <p> --> - <sect1><heading>Particulars on ESDI hardware</heading> + <sect2><heading>Particulars on ESDI hardware</heading> <p> - <sect2><heading>Adaptec 2320 controllers</heading> + <sect3><heading>Adaptec 2320 controllers</heading> <p> I successfully installed FreeBSD onto a ESDI disk controlled by a ACB-2320. No other operating system was present on the disk. @@ -352,7 +352,7 @@ disk wd3 at wdc1 drive 1 Before using NEFMT.EXE I tried to format the disk using the ACB-2320 BIOS builtin formatter. This proved to be a show stopper, - because it didn't give me an option to disable spare sectoring. + because it did not give me an option to disable spare sectoring. With spare sectoring enabled the FreeBSD installation process broke down on the bad144 run. @@ -370,7 +370,7 @@ disk wd3 at wdc1 drive 1 All variations should be capable of using 1:1 interleaving. Use 1:1, FreeBSD is fast enough to handle it. - <sect2><heading>Western Digital WD1007 controllers</heading> + <sect3><heading>Western Digital WD1007 controllers</heading> <p> I successfully installed FreeBSD onto a ESDI disk controlled by a WD1007 controller. To be precise, it was a WD1007-WA2. Other @@ -382,7 +382,7 @@ disk wd3 at wdc1 drive 1 WDFMT.EXE from www.wdc.com Running this formatted my drive just fine. - <sect2><heading>Ultrastor U14F controllers</heading> + <sect3><heading>Ultrastor U14F controllers</heading> <p> According to multiple reports from the net, Ultrastor ESDI boards work OK with FreeBSD. I lack any further info on @@ -390,11 +390,11 @@ disk wd3 at wdc1 drive 1 <!-- - <sect1><heading>Tracking down problems</heading> + <sect2><heading>Tracking down problems</heading> <p> --> - <sect1><heading>Further reading<label id="esdi:further-reading"></> + <sect2><heading>Further reading<label id="esdi:further-reading"></> <p> If you intend to do some serious ESDI hacking, you might want to have the official standard at hand: @@ -414,7 +414,7 @@ disk wd3 at wdc1 drive 1 For info on Western Digital controllers see <htmlurl url="http://www.wdc.com/">. - <sect1>Thanks to... + <sect2>Thanks to... <p> Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk for testing. diff --git a/handbook/firewalls.sgml b/handbook/firewalls.sgml index cc39cdebd3..2bbf124233 100644 --- a/handbook/firewalls.sgml +++ b/handbook/firewalls.sgml @@ -1,4 +1,4 @@ -<!-- $Id: firewalls.sgml,v 1.1.2.2 1996-01-31 14:32:19 mpp Exp $ --> +<!-- $Id: firewalls.sgml,v 1.1.2.3 1996-06-19 20:27:44 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>Firewalls<label id="firewalls"></heading> @@ -47,7 +47,7 @@ impossible to cover them in this document. <sect2><heading>Packet filtering routers<label id="firewalls:packet_filters"></heading> <p>A router is a machine which forwards packets between two or more -networks. A packet filtering router has an extra piece of code in it's +networks. A packet filtering router has an extra piece of code in its kernel, which compares each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software has packet filtering code in it, which defaults to forwarding all @@ -56,7 +56,7 @@ the filtering code, so that it can decide if the packet should be allowed to pass or not. <p>To decide if a packet should be passed on or not, the code looks -through it's set of rules for a rule which matches the contents of +through its set of rules for a rule which matches the contents of this packets headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only @@ -146,7 +146,7 @@ will happen. <p>The configuration of the <tt>IPFW</tt> software is done through the <tt>ipfw(8)</tt> utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand -it's structure. +its structure. <p>There are currently two different command line formats for the utility, depending on what you are doing. The first form is used when diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index 05eafa8106..b340eff994 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,4 +1,4 @@ -<!-- $Id: handbook.sgml,v 1.7.4.6 1996-01-31 14:32:20 mpp Exp $ --> +<!-- $Id: handbook.sgml,v 1.7.4.7 1996-06-19 20:27:46 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [ @@ -11,6 +11,10 @@ <!ENTITY % authors SYSTEM "authors.sgml"> %authors; +<!-- Entity shorthand for mailing list email addresses --> +<!ENTITY % lists SYSTEM "lists.sgml"> +%lists; + <!-- Entity definitions for all the parts --> <!ENTITY % sections SYSTEM "sections.sgml"> %sections; @@ -24,22 +28,23 @@ <author> <name>The FreeBSD Documentation Project</name> </author> - <date>October 30, 1995</date> + <date>May 15, 1996</date> <abstract>Welcome to FreeBSD! This handbook covers the installation and day to day use of <bf>FreeBSD Release -2.1</bf>. +2.1.0</bf>. This manual is a <bf>work in progress</bf> and is the work of many individuals. 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 the FreeBSD Documentation -Project mailing list <tt><htmlurl url="mailto:doc@freebsd.org" -name="<doc@freebsd.org>"></tt>. +email to the &a.doc The latest version of this document is always available from -the <url url="http://www.freebsd.org/" name="FreeBSD World Wide -Web server">. +the <url url="http://www.FreeBSD.ORG/" name="FreeBSD World Wide +Web server">. It may also be downloaded in ascii, LaTeX, postscript +or HTML from the <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs" +name="FreeBSD FTP server"> or one of the numerous +<ref id="mirrors" name="mirror sites">. </abstract> <toc> @@ -49,8 +54,20 @@ Web server">. <part><heading>Basics</heading> <chapt><heading>Introduction</heading> + <p>FreeBSD is a 4.4 BSD Lite based operating system for Intel + architecture (x86) based PCs. For an overview of FreeBSD, see + <ref id="nutshell" name="FreeBSD in a nutshell">. For a + history of the project, read <ref id="history" + name="a brief history of FreeBSD">. To see a description of the + latest release, read <ref id="relnotes" + name="about the current release">. If you're interested + in contributing something to the FreeBSD project (code, equipment, + sacks of unmarked bills), please see about <ref id="submitters" + name="contributing to FreeBSD">. + &nutshell; &history; + &goals; &relnotes; &install; @@ -59,7 +76,6 @@ Web server">. <chapt><heading>Installing applications</heading> <sect><heading>* Installing packages</heading> &ports; - &porting; <!-- ************************************************************ --> @@ -73,18 +89,14 @@ Web server">. &firewalls; &printing; + + "as; <chapt><heading>The X-Window System</heading> <p>Pending the completion of this section, please refer to documentation supplied by the <url url="http://www.xfree86.org/" name="The XFree86 Project, Inc">. - <chapt><heading>Managing hardware</heading> - <sect><heading>* Adding and reconfiguring disks</heading> - &scsi; - &esdi; - <sect><heading>* Tapes and backups</heading> - <sect><heading>* Serial ports</heading> - <sect><heading>* Sound cards</heading> + &hw; <!-- ************************************************************ --> @@ -127,25 +139,28 @@ Web server">. <part><heading>Advanced topics</heading> ¤t; - &ctm; - ⊃ - &kerneldebug; + &stable; + &synching; &submitters; &troubleshooting; + &kerneldebug; + &linuxemu; + <chapt><heading>FreeBSD internals</heading> + &booting; + &memoryuse; + &dma; <!-- ************************************************************ --> <part><heading>Appendices</heading> + &mirrors; &bibliography; &eresources; - &hw; - <chapt><heading>Assorted technical topics</heading> - &booting; - &memoryuse; - &dma; &contrib; + &pgpkeys; + <!-- &glossary; --> </book> diff --git a/handbook/history.sgml b/handbook/history.sgml index 0c69992bb6..f988e848ac 100644 --- a/handbook/history.sgml +++ b/handbook/history.sgml @@ -1,19 +1,19 @@ -<!-- $Id: history.sgml,v 1.1.4.5 1995-11-15 07:50:30 jkh Exp $ --> +<!-- $Id: history.sgml,v 1.1.4.6 1996-06-19 20:27:47 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>A brief history of FreeBSD<label id="history"></heading> <p><em>Contributed by &a.jkh;</em>. -The FreeBSD project had its genesis in the early part of 1992, +The FreeBSD project had its genesis in the early part of 1993, partially as an outgrowth of the "Unofficial 386BSD Patchkit" by the patchkit's last 3 coordinators: Nate Williams, Rod Grimes and myself. David Greenman and Julian Elischer were also lurking in the background -around this time, though they didn't come fully into the project until +around this time, though they did not come fully into the project until a month or two after it was more or less officially launched. Our original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems with it that the patchkit mechanism -just wasn't capable of solving. Some of you may remember the early +just was not capable of solving. Some of you may remember the early working title for the project being "386BSD 0.5" or "386BSD Interim" in reference to that fact. @@ -26,7 +26,7 @@ snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project and without any clear indication of what would be done instead. -It didn't take us long to decide that the goal remained worthwhile +It did not take us long to decide that the goal remained worthwhile even without Bill's support, and so we adopted the name "FreeBSD", which was coined by David Greenman. Our initial objectives were set after consulting with the system's current users, and once it became @@ -76,31 +76,41 @@ more than a little rough around the edges, the release was a significant success and has since been followed by the more robust and easier to install FreeBSD 2.0.5 release in June of 1995. -Where to from here? Well, we intend to release FreeBSD 2.1 sometime -in November of 1995 and have reasonable expectations that it will -meet or exceed all of the standards for quality we set with FreeBSD -1.1.5.1 back in July of 1994. From there, we'll probably continue our now -two-track scheme of a "stable" branch of FreeBSD and a "current" -branch, where development can continue at its usually rapid pace without -penalizing those who just want a working system without too much excitement. +<em>Where to from here?</em> + +We just released FreeBSD 2.1.0 on November 19th, 1995 and, by all +accounts, people are pretty happy with it. We will therefore continue +with the 2.1-STABLE branch of FreeBSD (which actually began with 2.0.5) +well into Q1 of 1996 with at least one additional release: +FreeBSD 2.1.1. + +A 2.1.2 release may follow 2.1.1, though this will depend heavily on the +status of FreeBSD 2.2 in Q2 of 1996. 2.2 is our development branch, +where long term projects for everything from NFS v3 to PCCARD support +are currently taking place. Preliminary timelines suggest that development +in 2.2 will begin slowing down and early release engineering simulations +(2.2 SNAPshots) started in Q1 of 1996. Given a favorable prognosis for 2.2's +general health, a migration to 2.2 will then begin in early Q2 of 1996 and +a new 2.3 branch created for next-generation development. Around the +time that 2.2-RELEASE is produced (late Q2 1996), the 2.1.x lineage will +also be phased out. + We also intend to focus on any remaining areas of weakness, like documentation or missing drivers, and steadily increase the overall quality and feature set of the system well into 1996 and beyond. -It should also be noted that the development of FreeBSD is <em>not</em> a closed -process, despite some popular misconceptions to the contrary, and anyone -is free to contribute code or ideas. Once a contributor has established -a reasonable track record for reliability, we generally even give them direct -access to the central source tree (kept under CVS) where their changes will -propagate automatically to all users of FreeBSD. Our centralised development -model is designed for the convenience of the <em>users</em> of FreeBSD, who -are thus provided with an easy way of tracking one central code base, not -to keep potential contributors out! Anyone and everyone is free to -contribute, and people who've shown a consistent and significant dedication -to the project are generally asked to join the FreeBSD core team to -help in setting the project's overall directions and goals. No part of the -project is closed to additional members, and all we ask of those wishing for -closer ties to the project is the same dedication its current members have +Now might also be a good time to note that the development of FreeBSD is +<em>not</em> a closed process, despite some popular misconceptions to the +contrary, and anyone is free to contribute code or ideas. Once a contributor +has established a reasonable track record for reliability, we generally, in +fact, give them write access to the project's CVS repository, where their +changes can propagate automatically to other users of FreeBSD. Our +centralized development model is designed for the convenience of the +<em>users</em> of FreeBSD, who are thereby provided with an easy way of +tracking one central code base, not to keep potential contributors out! +Individuals who hae shown a consistent and significant dedication to the project +are even often asked to join the FreeBSD core team to help in setting +the project's overall directions and goals, so truly no part of the project +is closed to additional members. All we ask of those wishing for closer +ties to this project is some of the same dedication its current members have to its continued success! - - Jordan diff --git a/handbook/hw.sgml b/handbook/hw.sgml index caee46b8c0..5ffa8cf4fa 100644 --- a/handbook/hw.sgml +++ b/handbook/hw.sgml @@ -1,4 +1,4 @@ -<!-- $Id: hw.sgml,v 1.6.2.2 1996-01-31 14:32:20 mpp Exp $ --> +<!-- $Id: hw.sgml,v 1.6.2.3 1996-06-19 20:27:49 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -25,13 +25,191 @@ experience of hardware that does or does not work with FreeBSD, please let us know by sending email to <tt>doc@freebsd.org</tt>. Questions about supported hardware - should be directed to <tt>questions@freebsd.org</tt> (see + should be directed to the &a.questions (see <ref id="eresources:mail" name="Mailing Lists"> for more information). When submitting information or asking a question, please remember to specify exactly what version of FreeBSD you are using and include as many details of your hardware as possible. + +<sect><heading>FreeBSD on Laptop computers</heading> + +<p>Because laptop computers operate under a unique set of constraints, + they often behave differently or require more specialized knowledge + than their desktop and deskside PC siblings. This section attempts to + list the most useful (and current) laptop specific information on the + net. + +<itemize> + <item>Tatsumi Hosokawa's <htmlurl + url="http://www.mt.cs.keio.ac.jp/person/hosokawa/freebsd-pcmcia/" + name="PCCARD driver"> page. + + <p><htmlurl url="mailto:hosokawa@mt.cs.keio.ac.jp" + name="Tatsumi Hosokawa"> and the BSD Nomads have created a + complete subsystem for dealing with PCCARD (PCMCIA) peripherals, + from modems to ethernet cards to SCSI adaptors. Much of this work + is now part of FreeBSD <htmlurl url="current.html" name="2.2-current">, + though more up-to-date experimental code snapshots may be found on + this page. + </item> + + <item>Here is <htmlurl url="mailto:edwin.kremer@cs.ruu.nl" + name="Edwin Kremer's"> report on using FreeBSD with his + <htmlurl url="http://www.cs.ruu.nl/people/edwin/FreeBSD/" + name="Toshiba Satellite Pro 410CDT Notebook">. + + <item>FreeBSD on the <htmlurl url="http://www.kfu.com/~nsayer/zenith/" + name="Zenith Z-NoteFlex Laptop"> + + <p>Nick tells us about life with what he deems to be the ideal laptop + for FreeBSD. + </item> +</itemize> +</sect> + +<sect><heading>Sample Configurations<label id="hw:configs"></heading> +<p>The following list of sample hardware configurations by no means +constitutes an endorsement of a given hardware vendor or product by +<em>The FreeBSD Project</em>. This information is provided only as a public +service and merely catalogs some of the experiences that various individuals +have had with different hardware combinations. Your mileage may vary. +Slippery when wet. Beware of dog. + + <sect1><heading>Jordan's Picks</heading> + <p>I have had fairly good luck building workstation and server + configurations with the following components. I cannot guarantee that + you will too, nor that any of the companies here will remain "best buys" + forever. I will try, when I can, to keep this list up-to-date but + cannot obviously guarantee that it will be at any given time. + + <sect2><heading>Motherboards</heading> + <p>The <htmlurl url="http://asustek.asus.com.tw/" name="ASUS"> + <htmlurl url="http://asustek.asus.com.tw/FTP/ASUS/Info/Spec/pi-p55tp4xe.txt" + name="P55TP4XE"> + motherboard appears to be a good choice for mid-to-high range Pentium + server and workstation systems. If you are really looking for performance, + be also sure to get the <htmlurl url="http://asustek.asus.com.tw/Products/TB/mem-0002.html" name="pipelined burst cache module">. I feel that it is worth + the extra cost. If you are looking for a 486 class motherboard, you might + also investigate ASUS's <htmlurl url="http://asustek.asus.com.tw/FTP/ASUS/Info/Spec/pvi-486sp3.txt" name="486SP3G"> offering. + + NOTE: The Intel <htmlurl url="http://asustek.asus.com.tw/Products/TB/triton-intro.html" name="Triton"> chipset based motherboards do not offer memory + parity logic, making it almost impossible to detect when a memory error + has occurred. Those wishing to build highly fault-tolerant systems may + therefore want to wait for Intel's newest generation of motherboards + based on the Orion chipset or investigate ASUS's SiS chipset based + motherboard, the <htmlurl url="http://asustek.asus.com.tw/FTP/ASUS/Info/Spec/pi-p55sp4.txt" name="P55SP4">. I have no personal experience with this + motherboard and have heard mixed reports - some say it is a fine MB, others + say that it is measurably slower than the Triton. The only undisputed + advantage it offers is being available <em>now</em>. + + <sect2><heading>Disk Controllers</heading> + <p>This one is a bit trickier, and while I used to recommend the + <htmlurl url="http://www.buslogic.com" name="Buslogic"> controllers + unilaterally for everything from ISA to PCI, now I tend to lean + towards the <htmlurl url="http://www.adaptec.com" name="Adaptec"> + 1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940 for PCI. + + <sect2><heading>Disk drives</heading> + <p>In this particular game of Russian roulette, I will make few specific + recommendations except to say "SCSI over IDE whenever you can afford it." + Even in small desktop configurations, SCSI often makes more sense since it + allows you to easily migrate drives from server to desktop as falling drive + prices make it economical to do so. If you have more than one machine + to administer then think of it not simply as storage, think of it as a + food chain! + + <p>I do not currently see SCSI WIDE drives as a necessary expense unless + you are putting together an NFS or NEWS server that will be doing a lot + of multiuser disk I/O. + + <sect2><heading>CDROM drives</heading> + <p>My SCSI preferences extend to SCSI CDROM drives as well, and the + <htmlurl url="http://www.toshiba.com" name="Toshiba"> XM-3501B (now + released in a caddy-less model called the XM-5401B) drive has always + performed well for me. Generally speaking, most SCSI CDROM drives I have + seen have been of pretty solid construction (probably because they do not + occupy the lower end of the market, due to their higher price) and you + probably will not go wrong with an HP or NEC SCSI CDROM drive either. + + <sect2><heading>Tape drives</heading> + <p>I've had pretty good luck with both + <htmlurl url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html" + name="8mm drives"> from <htmlurl url="http://www.exabyte.com" + name="Exabyte"> and + <htmlurl url="http://www-dmo.external.hp.com:80/tape/_cpb0001.htm" + name="4mm (DAT)"> drives from <htmlurl url="http://www.hp.com" name="HP">. + + <p>For backup purposes, I would have to give the higher recommendation to the + Exabyte due to the more robust nature (and higher storage capacity) of + 8mm tape. + + <sect2><heading>Video Cards</heading> + <p>If you can also afford to buy a commercial X server for US$99 from + <htmlurl url="http://www.xinside.com/" name="X Inside"> then I + can heartily recommend the <htmlurl url="http://www.matrox.com/" + name="Matrox"> <htmlurl url="http://www.matrox.com/mgaweb/brochure.htm" + name="Millenium"> card. If free X servers are more to your + liking, you certainly cannot go wrong with one of <htmlurl url="http://www.nine.com/" name="Number 9's"> cards - their S3 Vision 868 and 968 based cards + (the 9FX series) are pretty fast cards as well, and are supported by + <htmlurl url="http://www.xfree86.org" name="XFree86">'s S3 server. + + <sect2><heading>Monitors</heading> + <p>I have had very good luck with the <htmlurl url="http://cons3.sel.sony.com/SEL/ccpg/display/ms17se2.html" + name="Sony Multiscan 17SE monitors">, as have I with + the Viewsonic offering in the same (trinitron) tube. For larger than + 17", all I can recommend at the time of this writing is to not spend + any less than U.S. $2,500 for a 21" monitor if that is what you really + need. There are good monitors available in the >=20" range and there + are also cheap monitors in the >=20" range. Unfortunately, none are + both cheap and good! + + <sect2><heading>Networking</heading> + <p>I can recommend the <htmlurl url="http://www.smc.com/" name="SMC"> + Ultra 16 controller for any ISA application and the SMC EtherPower + or Compex ENET32 cards for any serious PCI based networking. Both of + the PCI cards are based around DEC's DC21041 Ethernet controller + chip and other cards using it, such as the Zynx ZX342 or DEC DE435, + will generally work as well. + + <sect2><heading>Serial</heading> + <p>If you are looking for high-speed serial networking solutions, then + <htmlurl url="http://www.dgii.com/" name="Digi International"> + makes the <htmlurl url="http://www.dgii.com/prodprofiles/profiles-prices/digiprofiles/digispecs/sync570.html" name="SYNC/570"> series, with drivers now in + FreeBSD-current. <htmlurl url="http://www.etinc.com" + name="Emerging Technologies"> also manufactures a board with T1/E1 + capabilities, using software they provide. + + <p>Multiport card options are somewhat more numerous, though it has to be + said that FreeBSD's support for <htmlurl url="http://www.cyclades.com/" + name="Cyclades">'s products is probably the tightest, primarily as a result + of that company's committment to making sure that we are adequately supplied + with evaluation boards and technical specs. I have heard that the Cyclom-16Ye + offers the best price/performance, though I have not checked the prices lately. + Other multiport cards I have heard good things about are the BOCA and AST + cards, and <htmlurl url="http://www.stallion.com/" name="Stallion + Technologies"> apparently offers an unofficial driver for their + cards at <htmlurl url="ftp://ftp.stallion.com/drivers/unsupported/freebsd/stalbsd-0.0.4.tar.gz" name="this"> location. + + <sect2><heading>Audio</heading> + <p>I currently use the <htmlurl url="http://www.gravis.com/" name="Gravis"> + Ultrasound MAX due to its high sound quality and full-duplex audio + capabilities (dual DMA channels). Support for Windows NT and OS/2 is + fairly anemic, however, so I am not sure that I can recommend it as an + all-around card for a machine that will be running both FreeBSD and NT + or OS/2. In such a scenario, I might recommend the <htmlurl url="http://www.creaf.com/" name="Creative Labs"> AWE32 instead. + + <sect2><heading>Video</heading> + <p>For video capture, there is really only once choice - the + <htmlurl url="http://www.matrox.com/" name="Matrox"> + <htmlurl url="http://www.matrox.com/imgweb/meteor.htm" name="Meteor"> + card. FreeBSD also supports the older video spigot card from + Creative Labs, but those are getting somewhat difficult to find + and the Meteor is a more current generation frame-grabber with + a higher-speed PCI interface. I use one for broadcasting video + on the MBONE and it works quite well! + <sect><heading>Core/Processing<label id="hw:core"></heading> <sect1><heading>Motherboards, busses, and chipsets</heading> @@ -42,9 +220,10 @@ <p><em>Contributed by &a.rgrimes;.<newline>25 April 1995.</em></p> - <p>Of the Intel PCI chip sets the following is a list - of brokenness from worst to best and a short - description of brokenness.</p> + <p>Of the Intel PCI chip sets, the following list describes + various types of known-brokenness and the degree of + breakage, listed from worst to best. + </p> <p><descrip> @@ -83,8 +262,8 @@ parity checking. Workaround for parity issue. Wait for Triton-II. - <tag>Triton-II:</tag> Unknown, not yet shipping. - + <tag>Triton-II:</tag> No known problems. This chipset + appears to be a winner for everyone so far. </descrip> </p> @@ -98,200 +277,9 @@ <sect1><heading>* Sound cards</heading> <sect1><heading>Serial ports and multiport cards</heading> - <p>The <tt>sio</tt> driver provides support for NS8250-, - NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT - V.24) communications interfaces. Several multiport - cards are supported as well. See the <tt>sio(4)</tt> - manual page for detailed technical documentation. - -<sect2><heading>Digiboard PC/8</heading> - - <p><em>Contributed by &a.awebster;.<newline>26 August - 1995.</em> - - Here is a config snippet from a machine with - digiboard PC/8 with 16550. It has 8 modems connected - to these 8 lines, and they work just great. Do not - forget to add <tt>options "COM_MULTIPORT"</tt> or it - will not work very well! - -<tscreen><verb> -device sio4 at isa? port 0x100 tty flags 0xb05 -device sio5 at isa? port 0x108 tty flags 0xb05 -device sio6 at isa? port 0x110 tty flags 0xb05 -device sio7 at isa? port 0x118 tty flags 0xb05 -device sio8 at isa? port 0x120 tty flags 0xb05 -device sio9 at isa? port 0x128 tty flags 0xb05 -device sio10 at isa? port 0x130 tty flags 0xb05 -device sio11 at isa? port 0x138 tty flags 0xb05 irq 9 vector siointr -</verb></tscreen> - - The trick in setting this up is that the MSB of the - flags represent the last SIO port, in this case 11 so - flags are 0xb05. - -<sect2><heading>Boca 16</heading> - - <p><em>Contributed by &a.whiteside;.<newline>26 August - 1995.</em> - - The procedures to make a Boca 16 pord board with - FreeBSD are pretty straightforward, but you will need - a couple things to make it work: - - <enum> - <item>You either need the kernel sources installed - so you can recompile the necessary options or - you will need someone else to compile it for you. - The 2.0.5 default kernel does <bf>not</bf> come with - multiport support enabled and you will need to add - a device entry for each port anyways. - </item> - <item>Two, you will need to know the interrupt and IO - setting for your Boca Board so you can set these - options properly in the kernel.</item> - </enum> - - One important note - the actual UART chips for the - Boca 16 are in the connector box, not on the internal - board itself. So if you have it unplugged, probes of - those ports will fail. I have never tested booting with - the box unplugged and plugging it back in, and I - suggest you do not either. - - If you do not already have a custom kernel - configuration file set up, refer to <ref - id="kernelconfig" name="Kernel Configuration"> for - general procedures. The following are the specifics - for the Boca 16 board and assume you are using the - kernel name MYKERNEL and editing with vi. - - <enum> - <item>Add the line -<tscreen><verb> -options "COM_MULTIPORT" -</verb></tscreen> -to the config file. -</item> - - <item>Where the current <tt>device sio - <em>xxx</em></tt> lines are, you will need to add - 16 more devices. <em>Only the last device - includes the interrupt vector for the - board</em>. (See the <tt>sio(4)</tt> manual page - for detail as to why.) - - The following example is for a Boca Board with an - interrupt of 3, and a base IO address 100h. The - IO address for Each port is +8 hexadecimal from - the previous port, thus the 100h, 108h, 110h... - addresses. - -<tscreen><verb> -device sio1 at isa? port 0x100 tty flags 0x1005 -device sio2 at isa? port 0x108 tty flags 0x1005 -device sio3 at isa? port 0x110 tty flags 0x1005 -device sio4 at isa? port 0x118 tty flags 0x1005 -[...] -device sio15 at isa? port 0x170 tty flags 0x1005 -device sio16 at isa? port 0x178 tty flags 0x1005 irq 3 vector siointr -</verb></tscreen> - - The flags entry <em>must</em> be changed from - this example unless you are using the exact same - sio assignments. Flags are set according to - 0x<em>MYY</em> where <em>M</em> indicates the - minor number of the master port (the last port on - a Boca 16) and <em>YY</em> indicates if FIFO is - enabled or disabled(enabled), IRQ sharing is - used(yes) and if there is an AST/4 compatible IRQ - control register(no). - - In this example, -<tscreen><verb> -flags 0x1005 -</verb></tscreen> - - indicates that the master port is sio16. If I - added another board and assigned sio17 through - sio28, the flags for all 16 ports on - <em>that</em> board would be 0x1C05, where 1C - indicates the minor number of the master port. - Do not change the 05 setting.</item> - - <item>Save and complete the kernel configuration, - recompile, install and reboot. - - Presuming you have successfully installed the - recompiled kernel and have it set to the correct - address and IRQ, your boot message should - indicate the successful probe of the Boca ports - as follows: (obviously the sio numbers, IO and - IRQ could be different) - -<tscreen><verb> -sio1 at 0x100-0x107 flags 0x1005 on isa -sio1: type 16550A (multiport) -sio2 at 0x108-0x10f flags 0x1005 on isa -sio2: type 16550A (multiport) -sio3 at 0x110-0x117 flags 0x1005 on isa -sio3: type 16550A (multiport) -sio4 at 0x118-0x11f flags 0x1005 on isa -sio4: type 16550A (multiport) -sio5 at 0x120-0x127 flags 0x1005 on isa -sio5: type 16550A (multiport) -sio6 at 0x128-0x12f flags 0x1005 on isa -sio6: type 16550A (multiport) -sio7 at 0x130-0x137 flags 0x1005 on isa -sio7: type 16550A (multiport) -sio8 at 0x138-0x13f flags 0x1005 on isa -sio8: type 16550A (multiport) -sio9 at 0x140-0x147 flags 0x1005 on isa -sio9: type 16550A (multiport) -sio10 at 0x148-0x14f flags 0x1005 on isa -sio10: type 16550A (multiport) -sio11 at 0x150-0x157 flags 0x1005 on isa -sio11: type 16550A (multiport) -sio12 at 0x158-0x15f flags 0x1005 on isa -sio12: type 16550A (multiport) -sio13 at 0x160-0x167 flags 0x1005 on isa -sio13: type 16550A (multiport) -sio14 at 0x168-0x16f flags 0x1005 on isa -sio14: type 16550A (multiport) -sio15 at 0x170-0x177 flags 0x1005 on isa -sio15: type 16550A (multiport) -sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa -sio16: type 16550A (multiport master) -</verb></tscreen> - - If the messages go by too fast to see, <tt>dmesg - > more</tt> will show you the boot - messages.</item> - - <item>Next, appropriate entries in <tt>/dev</tt> for the devices - must be made using the <tt>/dev/MAKEDEV</tt> - script. After becoming root: -<tscreen> -# cd /dev<newline> -# ./MAKEDEV tty1<newline> -# ./MAKEDEV cua1<newline> -<em>(everything in between)</em><newline> -# ./MAKEDEV ttyg<newline> -# ./MAKEDEV cuag -</tscreen> - - If you do not want or need callout devices for some - reason, you can dispense with making the <tt>cua*</tt> - devices.</item> - - <item>If you want a quick and sloppy way to make - sure the devices are working, you can simply plug - a modem into each port and (as root) <tt>echo at - > ttyd*</tt> for each device you have - made. You <em>should</em> see the RX lights flash - for each working port.</item> - </enum> - + &uart; + &sio; + &cy; <sect1><heading>* Parallel ports</heading> <sect1><heading>* Modems</heading> @@ -300,8 +288,9 @@ sio16: type 16550A (multiport master) <sect1><heading>* Mice</heading> <sect1><heading>* Other</heading> -<sect><heading>* Storage Devices<label id="hw:storage"></heading> - +<sect><heading>Storage Devices<label id="hw:storage"></heading> +&esdi; +&scsi; <sect1><heading>* Disk/tape controllers</heading> <sect2><heading>* SCSI</heading> <sect2><heading>* IDE</heading> @@ -312,8 +301,4 @@ sio16: type 16550A (multiport master) <sect1><heading>* Other</heading> <sect><heading>* Other<label id="hw:other"></heading> - <sect1><heading>* PCMCIA</heading> - - - diff --git a/handbook/install.sgml b/handbook/install.sgml index 9cde9ee19b..bc10b56645 100644 --- a/handbook/install.sgml +++ b/handbook/install.sgml @@ -1,4 +1,4 @@ -<!-- $Id: install.sgml,v 1.9.2.6 1996-01-31 14:32:21 mpp Exp $ --> +<!-- $Id: install.sgml,v 1.9.2.7 1996-06-19 20:27:52 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -14,12 +14,12 @@ anonymous ftp or NFS. Regardless of the installation media you choose, you can - get started by downleading the <bf>installation disk</bf> + get started by downloading the <bf>installation disk</bf> as described below. Booting your computer with disk will provide important information about compatibility between FreeBSD and your hardware which could dictate which installation options are possible. It can also provide - early clues to compatibilty problems that could prevent + early clues to compatibility problems that could prevent FreeBSD running on your system at all. If you plan on installing via anonymous FTP, then this installation disk is all you need to download. @@ -35,13 +35,13 @@ configurations"> section of this installation guide to be sure that your hardware is supported by FreeBSD. It may be helpful to make a list of any special cards you - have installed, such as SCSI controllers, etherernet + have installed, such as SCSI controllers, Ethernet adapters or sound cards. This list should include relevant configuration parameters such as interrupts (IRQ) and IO port addresses. </item> <item>Download the <url - url="ftp://ftp.freebsd.org/pub/FreeBSD/2.1-RELEASE/floppies/boot.flp" + url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/2.1.0-RELEASE/floppies/boot.flp" name="installation boot disk image"> file to your hard drive, and be sure to tell your browser to <em>save</em> rather than <em>display</em>. @@ -53,7 +53,7 @@ <itemize> <item>If you are using MS-DOS download <url -url="ftp://ftp.freebsd.org/pub/FreeBSD/tools/dos-tools/rawrite.exe" +url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/tools/dos-tools/rawrite.exe" name="rawrite.exe">, then run it: <tscreen><verb> C:\> rawrite @@ -181,6 +181,7 @@ Boot: <item>Adaptec 274x/284x/2940/3940 (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers + <item>Adaptec AIC7850 on-board SCSI controllers <item>Adaptec <!-- AIC-6260 and - actually not working, joerg --> AIC-6360 based boards, @@ -200,18 +201,18 @@ Boot: more details. <item>Buslogic 545S & 545c - <bf>Note:</bf> that Buslogic was formerly known as "Bustec". + <bf>Note:</bf> that Buslogic was formerly known as "Bustek". <item>Buslogic 445S/445c VLB SCSI controller - <item>Buslogic 742A, 747S, 747c EISA SCSI controller. + <item>Buslogic 742A/747S/747c EISA SCSI controller. <item>Buslogic 946c PCI SCSI controller <item>Buslogic 956c PCI SCSI controller - <item>NCR 53C810 and 53C825 PCI SCSI controller. + <item>NCR 53C810/53C815/53C825/53C860/53C875 PCI SCSI controller. <item>NCR5380/NCR53400 (``ProAudio Spectrum'') SCSI controller. <item>DTC 3290 EISA SCSI controller in 1542 emulation mode. - <item>UltraStor 14F, 24F and 34F SCSI controllers. + <item>UltraStor 14F/24F/34F SCSI controllers. <item>Seagate ST01/02 SCSI controllers. @@ -254,13 +255,32 @@ Boot: <item>DEC EtherWORKS III NICs (DE203, DE204, and DE205) <item>DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422) - <item>DEC DC21140 based NICs (SMC???? DE???) + <item>DEC DC21040/DC21041/DC21140 based NICs: + <itemize> + <item>ASUS PCI-L101-TB + <item>Accton ENI1203 + <item>Cogent EM960PCI + <item>Compex CPXPCI/32C + <item>D-Link DE-530 + <item>DEC DE435 + <item>Danpex EN-9400P3 + <item>JCIS Condor JC1260 + <item>Linksys EtherPCI + <item>Mylex LNP101 + <item>SMC EtherPower 10/100 (Model 9332) + <item>SMC EtherPower (Model 8432) + <item>Zynx ZX342 + </itemize> <item>DEC FDDI (DEFPA/DEFEA) NICs <item>Fujitsu FMV-181 and FMV-182 + <item>Fujitsu MB86960A/MB86965A + <item>Intel EtherExpress + <item>Intel EtherExpress Pro/100B 100Mbit. + <item>Isolan AT 4141-0 (16 bit) <item>Isolink 4110 (8 bit) @@ -276,6 +296,8 @@ Boot: <item>3Com 3C509, 3C579, 3C589 (PCMCIA) Etherlink III + <item>3Com 3C590, 3C595 Etherlink III + <item>Toshiba ethernet cards <item>PCMCIA ethernet cards from IBM and National @@ -284,7 +306,8 @@ Boot: <p><em>Note:</em> FreeBSD does not currently support PnP (plug-n-play) features present on some ethernet - cards. If your card has PnP, it should be disabled. + cards. If your card has PnP and is giving you problems, + try disabling its PnP features. <sect1><heading>Miscellaneous devices</heading> @@ -304,16 +327,15 @@ Boot: <item>SDL Communications Riscom/8 Serial Board. + <item>Digiboard Sync/570i high-speed sync serial card. + <item>Adlib, SoundBlaster, SoundBlaster Pro, - ProAudioSpectrum, Gravis UltraSound and Roland - MPU-401 sound cards. + ProAudioSpectrum, Gravis UltraSound, Gravis UltraSound MAX + and Roland MPU-401 sound cards. </itemize> - FreeBSD currently does not support IBM's microchannel - (MCA) bus, but support is apparently close to - materializing. Details will be posted as the situation - develops. + FreeBSD does not currently support IBM's microchannel (MCA) bus. <sect><heading>Preparing for the installation</heading> @@ -323,18 +345,18 @@ Boot: <sect1><heading>Before installing from CDROM</heading> - <p>If your CDROM is of an unsupported type, such as an - IDE CDROM, then please skip to <ref id="install:msdos" - name="MS-DOS Preparation">. + <p>If your CDROM is of an unsupported type, then please + skip to <ref id="install:msdos" name="MS-DOS Preparation">. - There is not a lot of preparatory work that needs to be - done to successfully install from one of Walnut Creek's - FreeBSD CDROMs (other CDROM distributions may work as - well, we simply cannot say as we have no hand or say in - their creation). You can either boot into the CD - installation directly from DOS using Walnut Creek's - supplied ``install.bat'' batch file or you can make a - boot floppy with the ``makeflp.bat'' command. + There is not a lot of preparatory work that needs to be done to + successfully install from one of Walnut Creek's FreeBSD CDROMs (other + CDROM distributions may work as well, though we cannot say for certain + as we have no hand or say in how they are created). You can either + boot into the CD installation directly from DOS using Walnut Creek's + supplied ``install.bat'' batch file or you can make a boot floppy with + the ``makeflp.bat'' command. [NOTE: If you are running + FreeBSD 2.1-RELEASE and have an IDE CDROM, use the + inst_ide.bat or atapiflp.bat batch files instead]. For the easiest interface of all (from DOS), type ``view''. This will bring up a DOS menu utility that @@ -349,27 +371,12 @@ Boot: menu and load the entire distribution from CDROM. No other types of installation media should be required. - After your system is fully installed and you have - rebooted from the hard disk, you should find the CD - mounted on the directory <bf>/cdrom</bf>. A utility - called `lndir' comes with the XFree86 distribution - which you may also find useful: It allows you to create - "link tree" directories to things on Read-Only media - like CDROM. One example might be something like this: - -<tscreen><verb> -mkdir /usr/ports -lndir /cdrom/ports /usr/ports -</verb></tscreen> + After your system is fully installed and you have rebooted + from the hard disk, you can mount the cdrom at any time by + typing: <tt>mount /cdrom</tt> - Which would allow you to then ``cd /usr/ports; make'' - and get all the sources from the CD, but yet create all - the intermediate files in <bf>/usr/ports</bf>, which is - presumably on a more writable media. - - This is, in fact, what the Ports entry in the - Configuration menu does at installation time if you - select it. + Before removing the CD again, also note that it is necessary to first + type: <tt>umount /cdrom</tt>. Do not just remove it from the drive! <quote><bf>Special note:</bf> Before invoking the installation, be sure that the CDROM is in the drive @@ -377,9 +384,8 @@ lndir /cdrom/ports /usr/ports true if you wish the CDROM to be added to the default system configuration automatically during the install (whether or not you actually use it as the - installation media). <!-- XXX This will be fixed for - 2.1, but for now this simple work-around will ensure - that your CDROM is detected properly. --></quote> + installation media). + </quote> Finally, if you would like people to be able to FTP install FreeBSD directly from the CDROM in your @@ -392,49 +398,67 @@ lndir /cdrom/ports /usr/ports ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent </verb></tscreen> - No further work is necessary. The other installers - will now be able to chose a Media type of FTP and type + Anyone with network connectivity to your machine (and permission + to log into it) can now chose a Media type of FTP and type in: <tt>ftp://<em>your machine</em></tt> after picking ``Other'' in the ftp sites menu. <sect1><heading>Before installing from Floppy</heading> <p>If you must install from floppy disks, either due to - unsupported hardware or just because you enjoy doing + unsupported hardware or simply because you enjoy doing things the hard way, you must first prepare some floppies for the install. - The first floppy you will need is ``floppies/root.flp'', - which is somewhat special in that it is not a DOS - filesystem floppy at all, but rather an ``image'' - floppy (it is actually a gzip'd cpio file). You can use - the rawrite.exe program to do this under DOS, or dd to - do it on a UNIX Workstation. See <ref id="install" - name="the beginning of this guide"> for examples. of - how to create the boot floppy. Once this floppy is - made, go on to make the distribution set floppies: - - You will need, at minimum, as many 1.44MB or 1.2MB - floppies as it takes to hold all files in the bin - (binary distribution) directory. These floppies - <em>must</em> be formatted using MS-DOS, using the - FORMAT command in MS-DOS or the File Manager format - command in Microsoft Windows(tm). Do <em>not</em> - trust Factory Preformatted floppies. Format them again - yourself, just to make sure. - - Many problems reported by our users in the past have - resulted from the use of improperly formatted media, so - we simply take special care to mention it here! - - After you have DOS formatted the floppies, you will - need to copy the files onto them. The distribution - files are split into chunks conveniently sized so that - 5 of them will fit on a conventional 1.44MB floppy. Go - through all your floppies, packing as many files as - will fit on each one, until you have got all the - distributions you want packed up in this fashion. Each - distribution should go into a subdirectory on the + + The first floppy that you will need in addition to the boot.flp + image is ``floppies/root.flp'', which is somewhat special in that + it is not a DOS filesystem floppy at all, but rather a floppy "image" + (it's actually a gzip'd cpio file). You can create this floppy in + the same way that you created the boot floppy <ref id="install" + name="the beginning of this guide">. Once this floppy is + made, you can go on to make the distribution set floppies + using ordinary DOS or UFS (if you are preparing the floppies on + another FreeBSD machine) formatted diskettes. + + You will need, at minimum, as many 1.44MB or 1.2MB floppies as + it takes to hold all files in the bin (binary distribution) + directory. If you are preparing these floppies under DOS, then + THESE floppies *must* be formatted using the MS-DOS FORMAT + command. If you are using Windows, use the Windows File + Manager format command. + + Do <em>not</em> trust Factory Preformatted floppies! Format + them again yourself, just to make sure. Many problems + reported by our users in the past have resulted from the use + of improperly formatted media, which is why I am taking such + special care to mention it here! + + If you are creating the floppies from another FreeBSD machine, + a format is still not a bad idea though you do nott need to put + a DOS filesystem on each floppy. You can use the `disklabel' + and `newfs' commands to put a UFS filesystem on them instead, + as the following sequence of commands (for a 3.5" 1.44MB floppy + disk) illustrates: + +<tscreen><verb> + fdformat -f 1440 fd0.1440 + disklabel -w -r fd0.1440 floppy3 + newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0 + +(Use "fd0.1200" and "floppy5" for 5.25" 1.2MB disks). +</verb></tscreen> + + Then you can mount and write to them like any other file + system. + + After you have formatted the floppies, you will need to copy + the files onto them. The distribution files are split into + chunks conveniently sized so that 5 of them will fit on a + conventional 1.44MB floppy. Go through all your floppies, + packing as many files as will fit on each one, until you have + got all the distributions you want packed up in this fashion. + Each distribution should go into a subdirectory on the floppy, e.g.: <bf>a:\bin\bin.aa</bf>, <bf>a:\bin\bin.ab</bf>, and so on. @@ -554,7 +578,7 @@ tar cvf /dev/rwt0 (or /dev/rst0) dist1 .. dist2 PCMCIA ethernet cards, also be sure that it is plugged in <em>before</em> the laptop is powered on! FreeBSD does not, unfortunately, currently support hot - insertion of PCMCIA cards. + insertion of PCMCIA cards during installation. You will also need to know your IP address on the network, the netmask value for your address class, @@ -621,7 +645,7 @@ tar cvf /dev/rwt0 (or /dev/rst0) dist1 .. dist2 of a name server: <tscreen><verb> -ftp://192.216.222.4/pub/FreeBSD/2.1-RELEASE +ftp://192.216.222.4/pub/FreeBSD/2.1.0-RELEASE </verb></tscreen> There are two FTP installation modes you can use: @@ -644,9 +668,9 @@ ftp://192.216.222.4/pub/FreeBSD/2.1-RELEASE </descrip> - <quote><bf>Note:</bf> ACTIVE AND PASSIVE MODES ARE - NOT THE SAME AS A `PROXY' CONNECTION, WHERE A PROXY - FTP SERVER IS LISTENING ON A DIFFERENT PORT!</quote> + <quote><bf>Note:</bf> Active and passive modes are + not the same as a `proxy' connection, where a proxy + ftp server is listening on a different port!</quote> In such instances, you should specify the URL as something like: <tscreen><verb> @@ -674,8 +698,8 @@ ftp://foo.bar.com:1234/pub/FreeBSD documentation you should need to be able to navigate through an installation and if it does not then we would like to know what you found most confusing. Send your - comments to <htmlurl url="mailto:doc@freebsd.org" - name="doc@freebsd.org">. It is the objective of the + comments to the &a.doc;. + It is the objective of the FreeBSD installation program (sysinstall) to be self-documenting enough that painful ``step-by-step'' guides are no longer necessary. It may take us a little @@ -701,15 +725,16 @@ ftp://foo.bar.com:1234/pub/FreeBSD <item>Select the Options item and set any special preferences you may have. - <item>Select a Custom or Express install, depending on - whether or not you would like the installation to give - you a high degree of control over each step of the - installation or simply lead you through it, choosing - reasonable defaults when possible. See details on - both installation types below. + <item>Select a Novice, Custom or Express install, depending on + whether or not you would like the installation to help + you through a typical installation, give you a high degree of + control over each step of the installation or simply whizz + through it (using reasonable defaults when possible) as fast + as possible. If you've never used FreeBSD before then the + Novice installation method is most recommended. - <item>The Configure menu choice allows you to further - configure your FreeBSD installation by giving you + <item>The final configuration menu choice allows you to + further configure your FreeBSD installation by giving you menu-driven access to various system defaults. Some items, like networking, may be especially important if you did a CDROM/Tape/Floppy installation and have @@ -719,82 +744,6 @@ ftp://foo.bar.com:1234/pub/FreeBSD when you first reboot from the hard disk. </enum> - <sect1><heading>Express installation</heading> - - <p>The express installation is not too much different than - the Custom one except that it leads you through the - required stages in the proper order and presents you - with various helpful prompts along the way. - - <enum> - <item>The first step is the `Partition Editor', which - allows you to chose how your drives will be used - for FreeBSD. If you are dedicating an entire drive - to FreeBSD, the `A' command is probably all you - need to type here. - - <item>Next, with the `Label Editor', you can specify - how the space in any allocated FreeBSD partitions - should be used by FreeBSD, or where to mount a - non-FreeBSD partition (such as DOS). If you want - the standard layout, simply type `A' here. - - <item>Next, the `Distributions' menu allows you to - specify which parts of FreeBSD you wish to load. A - good choice is ``User'' for a small system or - ``Developer'' for someone wanting a bit more out of - FreeBSD. If none of the existing collections sound - applicable, select Custom. - - <item>Next, the `Media' menu allows you to specify - what kind of media you wish to install from. If a - desired media choice is found and configured - automatically then this menu will simply return, - otherwise you will be asked for additional details on - the media device type. - - <item>Finally, you will be prompted to commit all of - these actions at once (nothing has been written to - your disk so far, nor will it until you give the - final confirmation). All new or changed partition - information will be written out, file systems will - be created and/or non-destructively labeled - (depending on how you set their newfs flags in the - Label Editor) and all selected distributions will - be extracted. - </enum> - - At this point, you are generally done with the - sysinstall utility and can select the final `Quit'. If - you are running it as an installer (e.g., before the - system is all the way up) then the system will now - reboot after you press return one last time. If you - selected the boot manager option, you will see a small - boot menu with an `F?' prompt. Press the function key - for BSD (it will be shown) and you should boot up into - FreeBSD off the hard disk. - - If this fails to happen for some reason, see the Q&A - section of the Hardware Guide for possible clues! - - <sect1><heading>Custom installation</heading> - - <p>You can do anything you like in this menu without - altering your system <em>except</em> for ``Commit'', - which will perform any requests to alter your system - you may have made. Some of the menu options will also - have direct `Write' commands available for committing an - operation immediately, but they should only be used if - you are absolutely sure it is necessary. It is generally - better to make your changes and then commit them all at - once so that you are left with the option of changing - your mind up to the very last minute. - - If you are confused at any point, the F1 key usually - pulls up the right information for the screen you are - in. - - <sect><heading>MS-DOS user's Questions and Answers</heading> <p>Many FreeBSD users wish to install FreeBSD on PCs inhabited @@ -838,27 +787,30 @@ ftp://foo.bar.com:1234/pub/FreeBSD between MS-DOS and FreeBSD. -<!-- XXX Status??? <bf>Can I mount my MS-DOS extended partitions?</bf> - This feature is not in FreeBSD 2.0.5 but should be in 2.1. - We have laid all the groundwork for making this happen, now - we just need to do the last 1 percent of the work involved. ---> + Yes. DOS extended partitions are mapped in at the end of the other + ``slices'' in FreeBSD, e.g. your D: drive might be /dev/sd0s5, + your E: drive /dev/sd0s6, and so on. This example assumes, of + course, that your extended partition is on SCSI drive 0. For IDE drives, + substitute ``wd'' for ``sd'' appropriately. You otherwise mount extended + partitions exactly like you would mount any other DOS drive, e.g.: + +<tscreen><verb> +mount -t msdos /dev/sd0s5 /dos_d +</verb></tscreen> <bf>Can I run MS-DOS binaries under FreeBSD?</bf> Not yet! We would like to add support for this someday, but - are still lacking anyone to actually do the work. - Ongoing work with Linux's DOSEMU utility may bring this - much closer to being a reality sometime soon. Send mail - to hackers@freebsd.org if you're interested in joining + are still lacking anyone to actually do the work. BSDI has + also donated their DOS emulator to the BSD world and this is slowly + being ported to FreeBSD-current. + + Send mail to the &a.emulation if you're interested in joining this effort! - However, there is a nice application available in the - <ref id="ports" name="The Ports Collection"> called pcemu, - that allows you to run many basic MS-DOS text-mode binaries + In the interim, there is a nice application available in the + <ref id="ports" name="The Ports Collection"> called pcemu + which allows you to run many basic MS-DOS text-mode binaries by entirely emulating an 8088 CPU. - - - diff --git a/handbook/kerberos.sgml b/handbook/kerberos.sgml index f65fa4d440..c34b4eac39 100644 --- a/handbook/kerberos.sgml +++ b/handbook/kerberos.sgml @@ -1,9 +1,9 @@ -<!-- $Id: kerberos.sgml,v 1.2.4.2 1995-10-12 03:16:05 jfieber Exp $ --> +<!-- $Id: kerberos.sgml,v 1.2.4.3 1996-06-19 20:27:55 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>Kerberos<label id="kerberos"></heading> -<p><em>Contributed by &a.mark; (based on contribution by &a.md;).</em> +<p><em>Contributed by &a.markm; (based on contribution by &a.md;).</em> Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. @@ -30,7 +30,7 @@ <heading>Creating the initial database</heading> <p>This is done on the Kerberos server only. First make sure that your - don't have any old Kerberos databases around. You should change to the + do not 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: @@ -98,7 +98,7 @@ ARC.NASA.GOV trident.arc.nasa.gov realm. The rest of the lines show how to default systems of a particular subdomain to a named realm. - Now we're ready to create the database. This only needs to run on + Now we are ready to create the database. This only needs to run on the Kerberos server (or Key Distribution Centre). Issue the <tt>kdb_init</tt> command to do this: diff --git a/handbook/kernelconfig.sgml b/handbook/kernelconfig.sgml index 18989c5758..2a007d001a 100644 --- a/handbook/kernelconfig.sgml +++ b/handbook/kernelconfig.sgml @@ -1,4 +1,4 @@ -<!-- $Id: kernelconfig.sgml,v 1.1.2.2 1996-01-31 14:32:22 mpp Exp $ --> +<!-- $Id: kernelconfig.sgml,v 1.1.2.3 1996-06-19 20:27:58 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> --> <chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading> @@ -44,7 +44,7 @@ </itemize></p> - <sect><heading>Building and Installing a Custom Kernel</heading> + <sect><heading>Building and Installing a Custom Kernel<label id="kernelconfig:building"></heading> <p>First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to @@ -77,7 +77,7 @@ </verb></tscreen> Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with - different hardware, it's a good idea to name it after + different hardware, it is a good idea to name it after your machine's hostname. We will call it MYKERNEL for the purpose of this example. @@ -89,24 +89,32 @@ you're just starting out, the only editor available will probably be <tt>vi</tt>, which is too complex to explain here, but is covered well in many books in the <ref - id="bibliography" name="bibliography">. Feel free to change the comment - lines at the top to reflect your configuration or the - changes you've made to differentiate it from GENERIC. + id="bibliography" name="bibliography">. Feel free to change the + comment lines at the top to reflect your configuration or the + changes you have made to differentiate it from GENERIC. - If you've build a kernel under SunOS or some other BSD + If you have build a kernel under SunOS or some other BSD operating system, much of this file will be very familiar - to you. If you're coming from some other operating + to you. If you are coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the <ref id="kernelconfig:config" name="Configuration File"> section slowly and carefully. - When you're finished, type the following to compile and + <quote><em/Note:/ If you are trying to upgrade your kernel from an + older version of FreeBSD, you will probably have to get a new + version of <tt>config(8)</tt> from the same place you got the new + kernel sources. It is located in <tt>/usr/src/usr.sbin</tt>, so + you will need to download those sources as well. Re-build and install + it before running the next commands.</quote> + + When you are finished, type the following to compile and install your kernel: <tscreen><verb> # /usr/sbin/config MYKERNEL # cd ../../compile/MYKERNEL +# make depend # make # make install </verb></tscreen> @@ -120,7 +128,7 @@ to recover in case your new kernel <ref id="kernelconfig:noboot" name="does not boot">. - <quote><em/Note:/ If you've added any new devices (such + <quote><em/Note:/ If you have added any new devices (such as sound cards) you may have to add some <ref id="kernelconfig:nodes" name="device nodes"> to your <tt>/dev</tt> directory before you can use them.</quote> @@ -136,9 +144,27 @@ GENERIC, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the GENERIC - file. An exhaustive list of options is present in the - LINT configuration file, located in the same directory as - GENERIC. + file. An exhaustive list of options and more detailed explanations + of the device lines is present in the LINT configuration file, + located in the same directory as GENERIC. If you are in doubt as to + the purpose or necessity of a line, check first in LINT. + + <p>The kernel is currently being moved to a better organization + of the option handling. Traditionally, each option in the + config file was simply converted into a <tt>-D</tt> switch + for the <tt>CFLAGS</tt> line of the kernel Makefile. Naturally, + this caused a creaping optionism, with nobody really knowing + which option has been referenced in what files. + + <p>In the new scheme, every <tt>#ifdef</tt> that is intended to + be dependant upon an option gets this option out of an + <tt>opt_<em>foo</em>.h</tt> declaration file created in the + compile directory by <tt>config</tt>. The list of valid options + for <tt>config</tt> lives in two files: options that do nott + depend on the architecture are listed in + <tt>/sys/conf/options</tt>, architecture-dependant ones + in <tt>/sys/<em>arch</em>/conf/options.<em>arch</em></tt>, + with <em>arch</em> being for example <tt>i386</tt>. <sect1><heading>Mandatory Keywords</heading> @@ -184,7 +210,7 @@ this from GENERIC to whatever you named your kernel, in this example, MYKERNEL. The value you put in <tt>ident</tt> will print when you boot up - the kernel, so it's useful to give a kernel a + the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your usual kernel (if you want to build an experimental kernel, for example). Note that, as @@ -193,7 +219,7 @@ contains any numbers. Since this name is passed to the C compiler as a - <tt>-D</tt> switch, don't use names like <tt> + <tt>-D</tt> switch, do not use names like <tt> DEBUG</tt>, or something that could be confused with another machine or CPU name, like <tt>vax</tt>. @@ -205,7 +231,7 @@ you expect to have on your machine. However, under normal circumstances, you will want to set <tt>maxusers</tt> to at least four, especially if - you're using X Windows or compiling software. The + you are using X Windows or compiling software. The reason is that the most important table set by <tt>maxusers</tt> is the maximum number of processes, which is set to <bf><tt>20 + 16 * @@ -310,7 +336,7 @@ Windows, which many graphics-intensive programs (such as the movie player XAnim, and Linux DOOM) will automatically take advantage of for extra - speed. If you use X Windows, you'll definitely + speed. If you use X Windows, you will definitely want to include this. <tag>options SYSVSEM</tag> @@ -387,8 +413,6 @@ is a pretend filesystem mounted on /proc which allows programs like <tt>ps(1)</tt> to give you more information on what processes are running. - <-- XXX why? it's perfectly working as LKM. joerg --> - Leave it in. <tag>options MFS</tag> @@ -481,7 +505,7 @@ <tt>wdc1</tt> is a secondary IDE controller where you might have a third or fourth hard drive, or an IDE CD-ROM. Comment out the lines which do not - apply (if you have a SCSI hard drive, you'll + apply (if you have a SCSI hard drive, you will probably want to comment out all six lines, for example). @@ -495,11 +519,9 @@ <tag>device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr</tag> - <p><tt>npx0</tt> is the interface to the - math coprocessor. If you have one then make sure - you've commented out <ref id="kernelconfig:mathemu" - name="MATH_EMULATE"> above. If you do not have a - math coprocessor, you can comment this out. + <p><tt>npx0</tt> is the interface to the floating point math + unit in FreeBSD, either the hardware co-processor or the + software math emulator. It is <em/NOT/ optional. <tag>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr</tag> @@ -603,11 +625,11 @@ <p>This causes the kernel to pause 15 seconds before probing each SCSI device in your system. If you only have IDE hard - drives, you can ignore this, otherwise you'll + drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to 5 seconds, to speed up booting. Of course if you do this, and FreeBSD has trouble recognizing your SCSI - devices, you'll have to raise it back up. + devices, you will have to raise it back up. <tag>controller scbus0</tag> @@ -775,7 +797,7 @@ <p>The next lines enable support for various Ethernet cards. If you do not have a network card, you can - comment out all of these lines. Otherwise, you'll + comment out all of these lines. Otherwise, you will want to leave in support for your particular Ethernet card(s): @@ -847,7 +869,7 @@ </descrip> <quote><em/Note:/ With certain cards (notably the - NE2000) you'll have to change the port and/or IRQ + NE2000) you will have to change the port and/or IRQ since there is no ``standard'' location for these cards.</quote> @@ -924,7 +946,7 @@ <p>This is the first section containing lines that are not in the GENERIC kernel. To include sound card - support, you'll have to copy the appropriate lines from + support, you will have to copy the appropriate lines from the LINT kernel (which contains support for <em>every</em> device) as follows: @@ -1019,12 +1041,10 @@ <tag>pseudo-device gzip</tag> <p><tt>gzip</tt> allows you to run FreeBSD programs - that have been compressed with <tt>gzip</tt>. This - is really only useful when you need to compress - FreeBSD programs to fit on a boot floppy. You will - probably never need to compress programs on your - hard drive in this fashion, so you'll probably want - to comment out this line. + that have been compressed with <tt>gzip</tt>. The + programs in <tt>/stand</tt> are compressed so it + is a good idea to have this option in your kernel.</p> + <tag>pseudo-device log</tag> <p><tt>log</tt> is used for logging of kernel error @@ -1034,7 +1054,7 @@ <tag>pseudo-device pty <em>number</em><label id="kernelconfig:ptys"></tag> <p><tt>pty</tt> is a ``pseudo-terminal'' or simulated - login port. It's used by incoming <bf>telnet</bf> + login port. It is used by incoming <bf>telnet</bf> and <bf>rlogin</bf> sessions, xterm, and some other applications such as emacs. The <em>number</em> indicates the number of <tt>pty</tt>s to create. @@ -1068,7 +1088,7 @@ <p>This section describes some miscellaneous hardware devices supported by FreeBSD. Note that none of these - lines are included in the GENERIC kernel, you'll have + lines are included in the GENERIC kernel, you will have to copy them from this handbook or the LINT kernel (which contains support for <em>every</em> device): @@ -1086,7 +1106,7 @@ script that plays some simple songs, and <tt>/usr/games/piano</tt> which lets you play songs using the keyboard as a simple piano (this file - only exists if you've installed the <em>games</em> + only exists if you have installed the <em>games</em> package). Also, the excellent text role-playing game NetHack (in the ports collection) can be configured to use this device to play songs when @@ -1154,7 +1174,7 @@ controller wcd0 <p>If the <tt>config</tt> command fails when you give it your kernel - description, you've probably made a simple error + description, you have probably made a simple error somewhere. Fortunately, <tt>config</tt> will print the line number that it had trouble with, so you can quickly skip to it with <tt>vi</tt>. For example, if @@ -1174,9 +1194,7 @@ config: line 17: syntax error kernel description, but not severe enough for <tt>config</tt> to catch it. Again, look over your configuration, and if you still cannot resolve the - problem, send mail to <tt><htmlurl - url="mailto:questions@freebsd.org" - name="questions@FreeBSD.ORG"></tt> with your kernel + problem, send mail to the &a.questions with your kernel configuration, and it should be diagnosed very quickly. @@ -1226,7 +1244,7 @@ config: line 17: syntax error <tag>Kernel works, but <tt>ps</tt> does not work any more!</tag> - <p>If you've installed a different version + <p>If you have installed a different version of the kernel from the one that the system utilities have been built with, for example, an experimental ``2.2.0'' kernel on a 2.1.0-RELEASE system, many diff --git a/handbook/kerneldebug.sgml b/handbook/kerneldebug.sgml index 9834864355..f924496dbc 100644 --- a/handbook/kerneldebug.sgml +++ b/handbook/kerneldebug.sgml @@ -1,4 +1,4 @@ -<!-- $Id: kerneldebug.sgml,v 1.3.2.3 1996-01-31 14:32:23 mpp Exp $ --> +<!-- $Id: kerneldebug.sgml,v 1.3.2.4 1996-06-19 20:28:00 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Kernel Debugging<label id="kerneldebug"></heading> @@ -36,7 +36,7 @@ done by default, however.</em> When the kernel has been built make a copy of it, say - <tt>kernel.debug</tt>, and then run <tt>strip -x</tt> on the + <tt>kernel.debug</tt>, and then run <tt>strip -d</tt> on the original. Install the original as normal. You may also install the unstripped kernel, but symbol table lookup time for some programs will drastically increase, and since @@ -64,16 +64,16 @@ <tt>kgdb</tt>. From <tt>kgdb</tt> do: <tscreen><verb> symbol-file kernel.debug - exec-file /var/crash/system.0 - core-file /var/crash/ram.0 + exec-file /var/crash/kernel.0 + core-file /var/crash/vmcore.0 </verb></tscreen> and voila, you can debug the crash dump using the kernel sources just like you can for any other program. - Here's a script log of a <tt>kgdb</tt> session illustrating the + Here is a script log of a <tt>kgdb</tt> session illustrating the procedure. Long lines have been folded to improve readability, and the lines are - numbered for reference. Despite of this, it's a real-world error + numbered for reference. Despite this, it is a real-world error trace taken during the development of the pcvt console driver. <tscreen><verb> 1:Script started on Fri Dec 30 23:15:22 1994 @@ -169,10 +169,10 @@ <tag/line 36:/ Force usage of a new stack frame; this is no longer necessary now. The stack frames are supposed to point to the right locations now, even in case of a trap. - (I don't have a new core dump handy <g>, my kernel - didn't panic for rather long.) + (I do not have a new core dump handy <g>, my kernel + did not panic for ia rather long time.) From looking at the code in source line 403, - there's a high probability that either the pointer + there is a high probability that either the pointer access for ``tp'' was messed up, or the array access was out of bounds. <tag/line 52:/ The pointer looks suspicious, but happens to be a valid @@ -188,23 +188,23 @@ <sect><heading>Post-mortem analysis of a dump</heading> <p>What do you do if a kernel dumped core but you did not expect - it, and it's therefore not compiled using <tt>config -g</tt>? - Not everything is lost here. Don't panic! + it, and it is therefore not compiled using <tt>config -g</tt>? + Not everything is lost here. Do not panic! Of course, you still need to enable crash dumps. See above - on the options you've got in order to do this. + on the options you have to specify in order to do this. Go to your kernel compile directory, and edit the line containing <tt>COPTFLAGS?=-O</tt>. Add the <tt>-g</tt> option - there (but <em>don't</em> change anything on the level of + there (but <em>do not</em> change anything on the level of optimization). If you do already know roughly the probable location of the failing piece of code (e.g., the <tt>pcvt</tt> driver in the example above), remove all the object files for this code. Rebuild the kernel. Due to the time stamp change on the Makefile, there will be some other object files rebuild, for example <tt>trap.o</tt>. With a bit of luck, the added - <tt>-g</tt> option won't change anything for the generated - code, so you'll finally get a new kernel with similar code to + <tt>-g</tt> option will not change anything for the generated + code, so you will finally get a new kernel with similar code to the faulting one but some debugging symbols. You should at least verify the old and new sizes with the <tt>size(1)</tt> command. If there is a mismatch, you probably need to give up here. @@ -226,8 +226,8 @@ The most important ones being breakpointing and single-stepping kernel code. - If you need to do low-level debugging on your kernel, there's - an on- line debugger available called DDB. It allows to + If you need to do low-level debugging on your kernel, there is + an on-line debugger available called DDB. It allows to setting breakpoints, single-steping kernel functions, examining and changing kernel variables, etc. However, it cannot not access kernel source files, and only has access to the global @@ -255,7 +255,7 @@ The second scenario is a hot-key on the keyboard, usually Ctrl-Alt-ESC. For syscons, this can be remapped, and some of the distributed maps do this, so watch out. - There's an option + There is an option available for serial consoles that allows the use of a serial line BREAK on the console line to enter DDB (``<tt>options BREAK_TO_DEBUGGER</tt>'' @@ -314,7 +314,7 @@ <tscreen><verb> n </verb></tscreen> - <bf>Note:</bf> this is different from <tt>gdb</tt>'s `next' statement, it's like + <bf>Note:</bf> this is different from <tt>gdb</tt>'s `next' statement, it is like <tt>gdb</tt>'s `finish'. To examine data from memory, use (for example): @@ -405,9 +405,9 @@ <tscreen><verb> help </verb></tscreen> - However, it's highly recommended to have a printed copy of the + However, it is highly recommended to have a printed copy of the <tt>ddb(4)</tt> manual page ready for a debugging session. - Remember that it's hard to read the on-line manual while + Remember that it is hard to read the on-line manual while single-stepping the kernel. diff --git a/handbook/memoryuse.sgml b/handbook/memoryuse.sgml index ebacd3942b..e0e42d174f 100644 --- a/handbook/memoryuse.sgml +++ b/handbook/memoryuse.sgml @@ -1,4 +1,4 @@ -<!-- $Id: memoryuse.sgml,v 1.1.4.3 1995-10-22 00:50:32 jfieber Exp $ --> +<!-- $Id: memoryuse.sgml,v 1.1.4.4 1996-06-19 20:28:01 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>PC memory utilization<label id="memoryuse"></heading> @@ -6,10 +6,8 @@ <p><em>Contributed by &a.joerg;.<newline> 16 Apr 1995.</em> -<bf>Question:</bf> <em>By the way, I have seen no description -of how FreeBSD uses PC memory, ie -what 0-640K gets used for, does the kernel load there or higher, -is the kernel relocated, etc. Is there a paper on this?</em> +<em>A short description of how FreeBSD uses the memory on the i386 +platform</em> The boot sector will be loaded at <tt>0:0x7c00</tt>, and relocates itself immediately to <tt>0x7c0:0</tt>. (This is nothing magic, just an adjustment @@ -18,7 +16,7 @@ for the <tt>%cs</tt> selector, done by an <tt>ljmp</tt>.) It then loads the first 15 sectors at <tt>0x10000</tt> (segment BOOTSEG in the biosboot Makefile), and sets up the stack to work below <tt>0x1fff0</tt>. After this, it jumps to the entry of boot2 within that code. I.e., it -jumps over itself and the (dummy) partition table, and it's going to +jumps over itself and the (dummy) partition table, and it is going to adjust the %cs selector---we are still in 16-bit mode there. boot2 asks for the boot file, and examines the <tt>a.out</tt> header. It masks @@ -32,7 +30,7 @@ The boot code itself uses segment selectors <tt>0x18</tt> and <tt>0x20</tt> for kernel is finally started with <tt>%cs</tt> <tt>0x08</tt> and <tt>%ds/%es/%ss</tt> <tt>0x10</tt>, which refer to dummy descriptors covering the entire address space. -The kernel will be started at its load point. Since it's been linked +The kernel will be started at its load point. Since it has been linked for another (high) address, it will have to execute PIC until the page table and page directory stuff is setup properly, at which point paging will be enabled and the kernel will finally run at the address diff --git a/handbook/mirrors.sgml b/handbook/mirrors.sgml index f54fb10b70..0119e60181 100644 --- a/handbook/mirrors.sgml +++ b/handbook/mirrors.sgml @@ -1,4 +1,4 @@ -<!-- $Id: mirrors.sgml,v 1.1.2.5 1995-11-19 19:52:21 jkh Exp $ --> +<!-- $Id: mirrors.sgml,v 1.1.2.6 1996-06-19 20:28:04 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -9,8 +9,8 @@ <p>The official sources for FreeBSD available via anonymous FTP from: <quote> -<htmlurl url="ftp://ftp.freebsd.org/pub/FreeBSD" -name="ftp://ftp.FreeBSD.org/pub/FreeBSD"> +<htmlurl url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD" +name="ftp://ftp.FreeBSD.ORG/pub/FreeBSD"> </quote> and on CD-ROM from Walnut Creek CDROM: <quote> @@ -30,43 +30,108 @@ and on CD-ROM from Walnut Creek CDROM: <descrip> <tag>Australia</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@au.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.physics.usyd.edu.au/FreeBSD" - name="ftp://ftp.physics.usyd.edu.au/FreeBSD"><newline> - Contact: <htmlurl url="mailto:dawes@xfree86.org" - name="dawes@xfree86.org">. - +<htmlurl url="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://minnie.cs.adfa.oz.au/FreeBSD" - name="ftp://minnie.cs.adfa.oz.au/FreeBSD"><newline> - Contact: <htmlurl url="mailto:wkt@dolphin.cs.adfa.oz.au" - name="wkt@dolphin.cs.adfa.oz.au">. +<htmlurl url="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD"><newline> + +</itemize> + +<tag>Brazil</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@br.FreeBSD.ORG" name="hostmaster"> +for this domain. + +<itemize> +<item> +<htmlurl url="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> <tag>Canada</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@ca.FreeBSD.ORG" name="hostmaster"> +for this domain. + +<itemize> + +<item> +<htmlurl url="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD"><newline> + +</itemize> + +<tag>Czech Republic</tag> + +<itemize> + +<item> +<htmlurl url="ftp://sunsite.mff.cuni.cz/OS/FreeBSD" + name="ftp://sunsite.mff.cuni.cz/OS/FreeBSD"><newline> + Contact: <htmlurl url="jj@sunsite.mff.cuni.cz" + name="jj@sunsite.mff.cuni.cz">. + +</itemize> + +<tag>Estonia</tag> + +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@ee.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.synapse.net/contrib/FreeBSD" - name="ftp://ftp.synapse.net/contrib/FreeBSD"><newline> - Contact: <htmlurl url="mailto:evanc@synapse.net" - name="evanc@synapse.net">. +<htmlurl url="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD" + name="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD"><newline> </itemize> <tag>Finland</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@fi.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://nic.funet.fi/pub/unix/FreeBSD" - name="ftp://nic.funet.fi/pub/unix/FreeBSD"><newline> - Contact: <htmlurl url="mailto:count@nic.funet.fi" - name="count@nic.funet.fi">. +<htmlurl url="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD" + name="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD"><newline> </itemize> @@ -84,37 +149,33 @@ and on CD-ROM from Walnut Creek CDROM: <tag>Germany</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@de.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.fb9dv.uni-duisburg.de/pub/unix/FreeBSD" - name="ftp://ftp.fb9dv.uni-duisburg.de/pub/unix/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp@ftp.fb9dv.uni-duisburg.de" - name="ftp@ftp.fb9dv.uni-duisburg.de">. - +<htmlurl url="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://gil.physik.rwth-aachen.de/pub/FreeBSD" - name="ftp://gil.physik.rwth-aachen.de/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:kuku@gil.physik.rwth-aachen.de" - name="kuku@gil.physik.rwth-aachen.de">. - +<htmlurl url="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.uni-paderborn.de/freebsd" - name="ftp://ftp.uni-paderborn.de/freebsd"><newline> - Contact: <htmlurl url="mailto:ftp@uni-paderborn.de" - name="ftp@uni-paderborn.de">. - +<htmlurl url="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.leo.org/pub/comp/os/bsd/FreeBSD" - name="ftp://ftp.leo.org/pub/comp/os/bsd/FreeBSD"><newline> - Contact: <htmlurl url="mailto:bsd@leo.org" - name="bsd@leo.org">. - +<htmlurl url="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.tu-dresden.de/pub/soft/unix/bsd/FreeBSD" - name="ftp://ftp.tu-dresden.de/pub/soft/unix/bsd/FreeBSD"><newline> - Contact: <htmlurl url="mailto:pdsowner@rcs1.urz.tu-dresden.de" - name="pdsowner@rcs1.urz.tu-dresden.de">. +<htmlurl url="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> @@ -123,8 +184,8 @@ and on CD-ROM from Walnut Creek CDROM: <itemize> <item> -<htmlurl url="ftp://ftp.hk.super.net/pub/mirror/FreeBSD" - name="g ftp://ftp.hk.super.net/pub/mirror/FreeBSD"><newline> +<htmlurl url="ftp://ftp.hk.super.net/pub/FreeBSD" + name="ftp://ftp.hk.super.net/pub/FreeBSD"><newline> Contact: <htmlurl url="mailto:ftp-admin@HK.Super.NET" name="ftp-admin@HK.Super.NET">. @@ -132,13 +193,15 @@ and on CD-ROM from Walnut Creek CDROM: <tag>Ireland</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@ie.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.internet-eireann.ie/pub/FreeBSD" - name="ftp://ftp.internet-eireann.ie/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftpadmin@internet-eireann.ie" - name="ftpadmin@internet-eireann.ie">. +<htmlurl url="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> @@ -152,41 +215,95 @@ and on CD-ROM from Walnut Creek CDROM: Contact: <htmlurl url="mailto:serg@klara.weizmann.ac.il" name="serg@klara.weizmann.ac.il">. +<item> +<htmlurl url="ftp://xray4.weizmann.ac.il/pub/FreeBSD" + name="ftp://xray4.weizmann.ac.il/pub/FreeBSD"><newline> + Contact: <htmlurl url="mailto:serg@klara.weizmann.ac.il" + name="serg@klara.weizmann.ac.il">. + +</itemize> + +<tag>Japan</tag> + +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@jp.FreeBSD.ORG" name="hostmaster"> +for this domain. + +<itemize> + +<item> +<htmlurl url="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD"><newline> + </itemize> <tag>Korea</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@kr.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.cau.ac.kr/pub/FreeBSD" - name="ftp://ftp.cau.ac.kr/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftpadm@ftp.cau.ac.kr" - name="ftpadm@ftp.cau.ac.kr">. +<htmlurl url="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> <tag>Netherlands</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@nl.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.nl.net/pub/os/FreeBSD" - name="ftp://ftp.nl.net/pub/os/FreeBSD"><newline> - Contact: <htmlurl url="mailto:archive@nl.net" - name="archive@nl.net">. +<htmlurl url="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD" + name="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD"><newline> </itemize> <tag>Poland</tag> <itemize> + +<item> +<htmlurl url="ftp://SunSITE.icm.edu.pl/pub/FreeBSD" + name="ftp://SunSITE.icm.edu.pl/pub/FreeBSD"><newline> + Contact: <htmlurl url="mailto:ftp@SunSITE.icm.edu.pl" + name="ftp@SunSITE.icm.edu.pl">. + +</itemize> + +<tag>Portugal</tag> + +<itemize> <item> -<htmlurl url="ftp://SunSITE.icm.edu.pl/pub/FreeBSD/ftp.freebsd.org" - name="ftp://SunSITE.icm.edu.pl/pub/FreeBSD/ftp.freebsd.org"><newline> - Contact: <htmlurl url="mailto:archive@nl.net" - name="archive@nl.net">. +<htmlurl url="ftp://ftp.ua.pt/pub/misc/FreeBSD" + name="ftp://ftp.ua.pt/pub/misc/FreeBSD"><newline> + Contact: <htmlurl url="mailto:archie@ua.pt" + name="archie@ua.pt">. </itemize> @@ -202,33 +319,54 @@ and on CD-ROM from Walnut Creek CDROM: </itemize> +<tag>South Africa</tag> + +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@za.FreeBSD.ORG" name="hostmaster"> +for this domain. + +<itemize> + +<item> +<htmlurl url="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD"><newline> + +</itemize> + <tag>Sweden</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@se.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.luth.se/pub/FreeBSD" - name="ftp://ftp.luth.se/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ragge@ludd.luth.se" - name="ragge@ludd.luth.se">. +<htmlurl url="ftp://ftp.se.freebsd.ORG/pub/FreeBSD" + name="ftp://ftp.se.freebsd.ORG/pub/FreeBSD"><newline> </itemize> <tag>Taiwan</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@tw.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://NCTUCCCA.edu.tw/Operating-Systems/FreeBSD" - name="ftp://NCTUCCCA.edu.tw/Operating-Systems/FreeBSD"><newline> - Contact: <htmlurl url="mailto:freebsd@NCTUCCCA.edu.tw" - name="freebsd@NCTUCCCA.edu.tw">. - +<htmlurl url="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://netbsd.csie.nctu.edu.tw/pub/FreeBSD" - name="ftp://netbsd.csie.nctu.edu.tw/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp@netbsd.csie.nctu.edu.tw" - name="ftp@netbsd.csie.nctu.edu.tw">. +<htmlurl url="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD"><newline> +<item> +<htmlurl url="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> @@ -246,129 +384,53 @@ and on CD-ROM from Walnut Creek CDROM: <tag>USA</tag> -<itemize> - -<item> -<htmlurl url="ftp://gatekeeper.dec.com/pub/BSD/FreeBSD" - name="ftp://gatekeeper.dec.com/pub/BSD/FreeBSD"><newline> - Contact: <htmlurl url="mailto:hubbard@gatekeeper.dec.com" - name="hubbard@gatekeeper.dec.com">. - -<item> -<htmlurl url="ftp://ftp.cybernetics.net/pub/FreeBSD" - name="ftp://ftp.cybernetics.net/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:michael@Cybernetics.NET" - name="michael@Cybernetics.NET">. - -<item> -<htmlurl url="ftp://ftp.neosoft.com/systems/FreeBSD" - name="ftp://ftp.neosoft.com/systems/FreeBSD"><newline> - Contact: <htmlurl url="mailto:smace@NeoSoft.COM" - name="smace@NeoSoft.COM">. - -<item> -<htmlurl url="ftp://kryten.atinc.com/pub/FreeBSD" - name="ftp://kryten.atinc.com/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:jmb@kryten.atinc.com" - name="jmb@kryten.atinc.com">. - -<item> -<htmlurl url="ftp://ftp.dataplex.net/pub/FreeBSD" - name="ftp://ftp.dataplex.net/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:rkw@dataplex.net" - name="rkw@dataplex.net">. - -<item> -<htmlurl url="ftp://ftp.cps.cmich.edu/pub/ftp.freebsd.org" - name="ftp://ftp.cps.cmich.edu/pub/ftp.freebsd.org"><newline> - Contact: <htmlurl url="mailto:ftpadmin@cps.cmich.edu" - name="ftpadmin@cps.cmich.edu">. - -<item> -<htmlurl url="ftp://ftp.cslab.vt.edu/pub/FreeBSD" - name="ftp://ftp.cslab.vt.edu/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp@ftp.cslab.vt.edu" - name="ftp@ftp.cslab.vt.edu">. - -</itemize> - -<tag>Japan</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@FreeBSD.ORG" name="hostmaster"> +for this domain. <itemize> <item> -<htmlurl url="ftp://ftp.tokyonet.ad.jp/pub/FreeBSD" - name="ftp://ftp.tokyonet.ad.jp/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftpadmin@TokyoNet.AD.JP" - name="ftpadmin@TokyoNet.AD.JP">. - +<htmlurl url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.tut.ac.jp/FreeBSD" - name="ftp://ftp.tut.ac.jp/FreeBSD"><newline> - Contact: <htmlurl url="mailto:<ashida@ftp.tut.ac.jp" - name="ashida@ftp.tut.ac.jp">. - +<htmlurl url="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.sra.co.jp/pub/os/FreeBSD" - name="ftp://ftp.sra.co.jp/pub/os/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp-admin@sra.co.jp" - name="ftp-admin@sra.co.jp">. - -<item> -<htmlurl url="ftp://ftp.ee.uec.ac.jp/pub/os/mirror/ftp.freebsd.org" - name="ftp://ftp.ee.uec.ac.jp/pub/os/mirror/ftp.freebsd.org"><newline> - Contact: <htmlurl url="mailto:ftp-admin@ftp.ee.uec.ac.jp" - name="ftp-admin@ftp.ee.uec.ac.jp">. - +<htmlurl url="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.mei.co.jp/free/PC-UNIX/FreeBSD" - name="ftp://ftp.mei.co.jp/free/PC-UNIX/FreeBSD"><newline> - Contact: <htmlurl url="mailto:tanig@isl.mei.co.jp" - name="tanig@isl.mei.co.jp">. - +<htmlurl url="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.waseda.ac.jp/pub/FreeBSD" - name="ftp://ftp.waseda.ac.jp/pub/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp-admin@waseda.ac.jp" - name="ftp-admin@waseda.ac.jp">. - -<item> -<htmlurl url="ftp://ftp.pu-toyama.ac.jp/pub/FreeBSD" - name="ftp://ftp.pu-toyama.ac.jp/pub/FreeBSD"><newline> - Contact: Yoshihiko USUI <htmlurl url="mailto:usui@pu-toyama.ac.jp" - name="usui@pu-toyama.ac.jp">. - +<htmlurl url="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftpsv1.u-aizu.ac.jp/pub/os/FreeBSD" - name="ftp://ftpsv1.u-aizu.ac.jp/pub/os/FreeBSD"><newline> - Contact: <htmlurl url="mailto:ftp-admin@u-aizu.ac.jp" - name="ftp-admin@u-aizu.ac.jp">. +<htmlurl url="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> <tag>UK</tag> +In case of problems, please contact the +<htmlurl url="mailto:hostmaster@uk.FreeBSD.ORG" name="hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://src.doc.ic.ac.uk/packages/unix/FreeBSD" - name="ftp://src.doc.ic.ac.uk/packages/unix/FreeBSD"><newline> - Contact: <htmlurl url="mailto:wizards@doc.ic.ac.uk" - name="wizards@doc.ic.ac.uk">. - +<htmlurl url="ftp://ftp.uk.FreeBSD.ORG/packages/unix/FreeBSD" + name="ftp://ftp.uk.FreeBSD.ORG/packages/unix/FreeBSD"><newline> <item> -<htmlurl url="ftp://unix.hensa.ac.uk/pub/walnut.creek/FreeBSD" - name="ftp://unix.hensa.ac.uk/pub/walnut.creek/FreeBSD"><newline> - Contact: <htmlurl url="mailto:archive-admin@unix.hensa.ac.uk" - name="archive-admin@unix.hensa.ac.uk">. - +<htmlurl url="ftp://ftp2.uk.FreeBSD.ORG/pub/walnut.creek/FreeBSD" + name="ftp://ftp2.uk.FreeBSD.ORG/pub/walnut.creek/FreeBSD"><newline> <item> -<htmlurl url="ftp://ftp.demon.co.uk/pub/BSD/FreeBSD" - name="ftp://ftp.demon.co.uk/pub/BSD/FreeBSD"><newline> - Contact: <htmlurl url="mailto:uploads@demon.net" - name="uploads@demon.net">. +<htmlurl url="ftp://ftp3.uk.FreeBSD.ORG/pub/BSD/FreeBSD" + name="ftp://ftp3.uk.FreeBSD.ORG/pub/BSD/FreeBSD"><newline> </itemize> + </descrip> The latest versions of export-restricted code for FreeBSD (2.0C or later) @@ -378,33 +440,33 @@ eBones (Kerberos) from one of the following foreign distribution sites: <descrip> -<tag>SouthAfrica</tag> +<tag>South Africa</tag> + +<htmlurl url="mailto:hostmaster@internat.FreeBSD.ORG" name="Hostmaster"> +for this domain. <itemize> <item> -<htmlurl url="ftp://ftp.internat.freebsd.org/pub/FreeBSD" - name="ftp://ftp.internat.freebsd.org/pub/FreeBSD"><newline> - Contact: Mark Murray <htmlurl url="mailto:mark@grondar.za" - name="mark@grondar.za">. +<htmlurl url="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD"><newline> <item> -<htmlurl url="ftp://storm.sea.uct.ac.za/pub/FreeBSD" - name="ftp://storm.sea.uct.ac.za/pub/FreeBSD"><newline> - Contact: Shaun Courtney <htmlurl url="mailto:ftp@storm.sea.uct.ac.za" - name="ftp@storm.sea.uct.ac.za">. +<htmlurl url="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> <tag>Brazil</tag> +<htmlurl url="mailto:hostmaster@br.FreeBSD.ORG" name="Hostmaster"> +for this domain. + <itemize> <item> -<htmlurl url="ftp://ftp.iqm.unicamp.br/pub/FreeBSD" - name="ftp://ftp.iqm.unicamp.br/pub/FreeBSD"><newline> - Contact: Pedro A M Vazquez <htmlurl url="mailto:vazquez@iqm.unicamp.br" - name="vazquez@iqm.unicamp.br">. +<htmlurl url="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD" + name="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD"><newline> </itemize> @@ -419,4 +481,5 @@ eBones (Kerberos) from one of the following foreign distribution sites: name="count@nic.funet.fi">. </itemize> + </descrip> diff --git a/handbook/nfs.sgml b/handbook/nfs.sgml index 2db4f2991a..a490c34c07 100644 --- a/handbook/nfs.sgml +++ b/handbook/nfs.sgml @@ -1,4 +1,4 @@ -<!-- $Id: nfs.sgml,v 1.1.1.1.4.2 1995-10-12 03:16:20 jfieber Exp $ --> +<!-- $Id: nfs.sgml,v 1.1.1.1.4.3 1996-06-19 20:28:06 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>NFS<label id="nfs"></heading> @@ -24,12 +24,19 @@ 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 +include the option "-w=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 +option "-r=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. +It should be noted that there is a different problem, +sometimes mistaken for this one, +when the NFS servers and clients are on different networks. +If that is the case, make CERTAIN that your routers are routing the +necessary UDP information, or you will not get anywhere, no matter +what else you are doing. + In the following examples, "fastws" is the host (interface) name of a high-performance workstation, and "freebox" is the host (interface) name of a FreeBSD system with a lower-performance Ethernet adapter. Also, @@ -39,16 +46,16 @@ system. In all cases, note that additional options, such as "hard" or "soft" and "bg" may be desirable in your application. Examples for the FreeBSD system ("freebox") as the client: - in /etc/fstab on freebox: -fastws:/sharedfs /project nfs rw,rsize=1024 0 0 + in <tt>/etc/fstab</tt> on freebox: +fastws:/sharedfs /project nfs rw,-r=1024 0 0 as a manual mount command on freebox: -mount -t nfs -o rsize=1024 fastws:/sharedfs /project +mount -t nfs -o -r=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 + in <tt>/etc/fstab</tt> on fastws: +freebox:/sharedfs /project nfs rw,-w=1024 0 0 as a manual mount command on fastws: -mount -t nfs -o wsize=1024 freebox:/sharedfs /project +mount -t nfs -o -w=1024 freebox:/sharedfs /project Nearly any 16-bit Ethernet adapter will allow operation without the above restrictions on the read or write size. diff --git a/handbook/nutshell.sgml b/handbook/nutshell.sgml index ece0a26847..565c3b2a71 100644 --- a/handbook/nutshell.sgml +++ b/handbook/nutshell.sgml @@ -1,4 +1,4 @@ -<!-- $Id: nutshell.sgml,v 1.1.4.3 1996-01-31 14:32:24 mpp Exp $ --> +<!-- $Id: nutshell.sgml,v 1.1.4.4 1996-06-19 20:28:07 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>FreeBSD in a nutshell<label id="nutshell"></heading> @@ -17,7 +17,7 @@ <item><bf>Multiuser</bf> access means that many people can use a FreeBSD system simultaneously for a variety of things. System peripherals such as printers and tape drives are also properly - shared between all users on the system.</item> + SHARED BETWEEN ALL users on the system.</item> <item>Complete <bf>TCP/IP networking</bf> including SLIP, PPP, NFS and NIS support. This means that your FreeBSD machine can inter-operate easily with other systems as well act as an enterprise @@ -33,7 +33,7 @@ provides a graphical user interface (GUI) for the cost of a common VGA card and monitor and comes with full sources.</item> <item><bf>Binary compatibility</bf> with many programs built for SCO, - BSDI, NetBSD, and 386BSD.</item> + BSDI, NetBSD, Linux and 386BSD.</item> <item>Hundreds of <bf>ready-to-run</bf> applications are available from the FreeBSD <bf>ports</bf> and <bf>packages</bf> @@ -77,7 +77,7 @@ limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can - be done with a commercial UNIX product then it's more than + be done with a commercial UNIX product then it is more than likely that you can do it with FreeBSD, too! FreeBSD also benefits significantly from the literally thousands of high quality applications developed by research centers and @@ -142,7 +142,7 @@ and easier to administer.</item> <item><bf>Software Development:</bf> The basic FreeBSD system comes with a full compliment of development tools - included the renowned GNU C/C++ compiler and + including the renowned GNU C/C++ compiler and debugger. </item> </itemize> diff --git a/handbook/porting.sgml b/handbook/porting.sgml index 4ab2acb49a..3aa88f84b8 100644 --- a/handbook/porting.sgml +++ b/handbook/porting.sgml @@ -1,22 +1,31 @@ -<!-- $Id: porting.sgml,v 1.2.4.4 1996-01-31 14:32:25 mpp Exp $ --> +<!-- $Id: porting.sgml,v 1.2.4.5 1996-06-19 20:28:08 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> -<sect><heading>Porting applications<label id="porting"></heading> +<sect1><heading>Porting an existing piece of free software<label id="porting"></heading> <p><em>Contributed by &a.jkh;, &a.gpalmer; and &a.asami;.<newline>19 August 1995.</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>The porting of freely available software, while perhaps not as +gratifying as developing your own from scratch, is still a vital part +of FreeBSD's growth and of great usefulness to those who would not +otherwise know where to turn for it. All ported software is organized +into a carefully organized hierarchy know as ``the ports collection''. +The collection enables a new user to get a quick and complete overview +of what is available for FreeBSD in an easy-to-compile form. It also +saves considerable space by not actually containing the the majority +of the sources being ported, but merely those differences required for +running under FreeBSD. + +<p>What follows are some guidelines for creating a new port for +FreeBSD 2.x . The <tt>${..}</tt> variable names you will +see in this document all refer to various user-overrideable defaults +used (and documented) by <tt>/usr/share/mk/bsd.port.mk</tt>. +Please refer to that file for more details on the inner workings of +the ports collection. + + <sect2> + <heading>Before Starting the Port<label id="porting:starting"></heading> <p>Note: Only a fraction of the overrideable variables are mentioned in this document. Most (if not all) are documented @@ -28,7 +37,7 @@ once the file has been loaded. <p>You may come across code that needs modifications or - conditional compilation based upon what version of UNIX it's + conditional compilation based upon what version of UNIX it is 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 @@ -80,29 +89,51 @@ 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>. + <tt>2</tt>. In earlier versions, it is <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_ > + shared library options when using `<tt>ld</tt>') then it is + OK to use <tt>__FreeBSD__</tt> and `<tt>#if __FreeBSD__ > 1</tt>' to detect a FreeBSD 2.x system. + If you need more granularity in detecting FreeBSD systems since + 2.0-RELEASE you can use the following: + +<tscreen><verb> +#if __FreeBSD__ >= 2 +#include <osreldate.h> +# if __FreeBSD_version >= 199504 + /* 2.0.5+ release specific code here */ +# endif +#endif +</verb></tscreen> +<tt>__FreeBSD_version</tt> values: +<tscreen><verb> +2.0-RELEASE: 199411 +2.1-current's: 199501, 199503 +2.0.5-RELEASE: 199504 +2.1.0-RELEASE: 199511 +2.2-current before 2.1: 199508 +2.2-current as 10 Jan 1996: 199512 (will certainly be bumped) +</verb></tscreen> +The pattern is the year followed by the month. + </itemize> <p>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 + screwed up and used it in the wrong place does not mean you should do so too. - <sect1> + <sect2> <heading>Quick Porting</heading> <p>This section tells you how to do a quick port. In many - cases, it is not enough, but we'll see. + cases, it is not enough, but we will see. <p>First, get the original tarball and put it into <tt>${DISTDIR}</tt>, which defaults to @@ -111,10 +142,10 @@ <p>Note: The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to - change something, you'll have to refer to the next section + change something, you will have to refer to the next section too. - <sect2> + <sect3> <heading>Writing the Makefile</heading> <p>The minimal <tt>Makefile</tt> would look something like this: @@ -125,7 +156,7 @@ # Date created: 5 December 1994 # Whom: asami # - # $Id: porting.sgml,v 1.2.4.4 1996-01-31 14:32:25 mpp Exp $ + # $Id: porting.sgml,v 1.2.4.5 1996-06-19 20:28:08 jkh Exp $ # DISTNAME= oneko-1.1b @@ -139,12 +170,12 @@ .include <bsd.port.mk> </verb></tscreen> - <p>See if you can figure it out. Don't worry about the contents + <p>See if you can figure it out. Do not worry about the contents of the <tt>$Id$</tt> line, it will be filled in automatically by CVS when the port is imported to our main ports tree. - <sect2> + <sect3> <heading>Writing the description files</heading> <p>There are three required description files that are @@ -152,7 +183,7 @@ They are <tt>COMMENT</tt>, <tt>DESCR</tt>, and <tt>PLIST</tt>, and reside in the <tt>pkg</tt> subdirectory. - <sect3> + <sect4> <heading>COMMENT</heading> <p>This is the one-line description of the port. It is @@ -162,7 +193,7 @@ A cat chasing a mouse all over the screen </verb></tscreen> - <sect3> + <sect4> <heading>DESCR</heading> <p>This is a longer description of the port. One to a few @@ -170,25 +201,23 @@ A cat chasing a mouse all over the screen sufficient. Note: This is <em>not</em> a manual nor an in-depth description on how to use or compile the port. In particular, please do not just copy the <tt>README</tt> - file here, unless, of course, it's a concise description + file here, unless, of course, it is a concise description of the port. <p>It is recommended that you sign the name at the end of - this file, and also state the version number, as in: + this file, as in: <tscreen><verb> This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) - : -This is version 1.1b. - Satoshi asami@cs.berkeley.edu </verb></tscreen> - <sect3> + <sect4> <heading>PLIST</heading> <p>This file lists all the files installed by the port. It @@ -208,13 +237,13 @@ lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm </verb></tscreen> - <sect2> + <sect3> <heading>Creating the checksum file</heading> <p>Just type `<tt>make makesum</tt>'. The ports make rules will automatically generate the file <tt>files/md5</tt>. - <sect2> + <sect3> <heading>Testing the port</heading> <p>You should make sure that the port rules do exactly what @@ -225,10 +254,10 @@ lib/X11/oneko/mouse.xpm <pkgname>.tgz</tt>' and see if everything re-appears and works correctly. - <sect2> + <sect3> <heading>Submitting the port</heading> - <p>Now that you're happy with your port, the only thing + <p>Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. To accomplish this, pack the necessary files (everything described in this @@ -236,23 +265,23 @@ lib/X11/oneko/mouse.xpm original source tarball or the `<tt>work</tt>' subdirectory) into a <tt>.tar.gz</tt> file, stick it in the directory <tscreen><verb> -ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ +ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ </verb></tscreen> - and send mail to <tt>ports@freebsd.org</tt>. We will take a + and send mail to the &a.ports;. We will take a look, get back to you if necessary, and put it in the tree. Your name will also appear in the list of `Additional FreeBSD contributors' on the FreeBSD Handbook and other files. Isn't that great?!? <tt>:)</tt> - <sect1> + <sect2> <heading>Slow Porting</heading> - <p>Ok, so it wasn't that simple, and the port required some - modifications to get it to work. In this section, we'll + <p>Ok, so it was not that simple, and the port required some + modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm. - <sect2> + <sect3> <heading>How things work</heading> <p>First, this is the sequence of events which occurs when the @@ -260,7 +289,7 @@ ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ and you may find that having <tt>bsd.port.mk</tt> in another window while you read this really helps to understand it. - <p>But don't worry if you don't really understand what + <p>But do not worry if you do not really understand what <tt>bsd.port.mk</tt> is doing, not many people do... <tt>:></tt> @@ -335,7 +364,7 @@ ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ targets `<tt>do-<something></tt>'. For example, the commands to extract a port are in the target `<tt>do-extract</tt>'. If you are not happy with the - default target, and you can't fix it by redefining the + default target, and you cannot fix it by redefining the `<tt>do-<something></tt>' target in your Makefile. <p>Note that the `main' targets (e.g., <tt>extract</tt>, @@ -346,10 +375,10 @@ ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ <tt>do-extract</tt>, but never ever touch <tt>extract</tt>! <p>Now that you understand what goes on when the user types - `<tt>make</tt>', let's go through the recommended steps to + `<tt>make</tt>', let us go through the recommended steps to create the perfect port. - <sect2> + <sect3> <heading>Getting the original sources</heading> <p>Get the original sources (normally) as a compressed tarball @@ -357,24 +386,24 @@ ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ and copy it into <tt>${DISTDIR}</tt>. Always use <em>mainstream</em> sources when and where you can. - <p>If you can't find a ftp site that is well-connected to the + <p>If you cannot find a ftp site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, we can `house' it ourselves by putting it on <tscreen><verb> -ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ +ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/ </verb></tscreen> - as the last resort. Send mail to <tt>ports@freebsd.org</tt> + as the last resort. Send mail to the &a.ports if you are not sure what to do. <p>If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in - <tt>${DISTDIR}</tt>. Don't worry if they come from + <tt>${DISTDIR}</tt>. Do not worry if they come from site other than where you got the the main source tarball, we have a way to handle these situations (see the description of <tt>${PATCHFILES}</tt> below). - <sect2> + <sect3> <heading>Modifying the port</heading> <p>Unpack a copy of the tarball in a private directory and @@ -394,13 +423,13 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ as possible for the end-user while using a minimum of disk space. - <sect2> + <sect3> <heading>Patching</heading> <p>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 + make as it does not 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> @@ -413,10 +442,10 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ the directory your port's tarball unpacks itself into, that being where the make is done). To make fixes and upgrades easier you should avoid having more than one patch fix the - same file (e.g., patch-ab and patch-ab both changing + same file (e.g., patch-aa and patch-ab both changing <tt>${WRKSRC}</tt>/foobar.c). - <sect2> + <sect3> <heading>Configuring</heading> <p>Include any additional customization commands to your @@ -425,7 +454,7 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ can also do this as Makefile targets and/or scripts with the name <tt>pre-configure</tt> or <tt>post-configure</tt>. - <sect2> + <sect3> <heading>Handling user input</heading> <p>If your port requires user input to build, configure or @@ -436,7 +465,7 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ then <em>only</em> those ports requiring interaction are built). - <sect1> + <sect2> <heading>Configuring the Makefile</heading> <p>Configuring the Makefile is pretty simple, and again we @@ -444,7 +473,7 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ starting. Consider the following problems in sequence as you design your new Makefile: - <sect2> + <sect3> <heading>The original source</heading> <p>Does it live in <tt>${DISTDIR}</tt> as a standard @@ -463,14 +492,14 @@ ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ `<tt>do-extract</tt>' target to override the default, though this should be rarely, if ever, necessary. - <sect2> + <sect3> <heading>DISTNAME</heading> <p>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>${DISTFILE}${EXTRACT_SUFX}</tt> - by default which, if it's a normal tarball, is going to be + <tt>${DISTNAME}${EXTRACT_SUFX}</tt> + by default which, if it is a normal tarball, is going to be something like: <tscreen><verb> foozolix-1.0.tar.gz @@ -494,8 +523,8 @@ work/foozolix-1.0/ extraction, and the rest will be just left in <tt>${DISTDIR}</tt> for later use. - <sect2> - <heading>CATEGORIES and KEYWORDS</heading> + <sect3> + <heading>CATEGORIES</heading> <p>When a package is created, it is put under <tt>/usr/ports/packages/All</tt> and links are made from one or more subdirectories of <tt>/usr/ports/packages</tt>. The @@ -509,23 +538,17 @@ work/foozolix-1.0/ truly belongs to something that is different from all the existing ones, you can even create a new category name. - <p>If you want to add more information than just the category - names, add them to <tt>${KEYWORDS}</tt>. The value - of this variable defaults to that of - <tt>${CATEGORIES}</tt>. This is currently used only - as a field of the <tt>/usr/ports/INDEX</tt> file. - - <sect2> + <sect3> <heading>MASTER_SITES</heading> <p>If you have a ftp-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. Don't forget the trailing slash (<tt>/</tt>)! + location. Do not forget the trailing slash (<tt>/</tt>)! <p>The make macros will try to use this specification for grabbing the distribution file with <tt>${NCFTP}</tt> - if they can't find it already on the system. + if they cannot find it already on the system. <p>It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard @@ -533,7 +556,7 @@ work/foozolix-1.0/ to add support for automatically determining the closest master site and fetching from there! - <sect2> + <sect3> <heading>PATCHFILES</heading> <p>If your port requires some additional patches that are available by ftp, set <tt>${PATCHFILES}</tt> to the @@ -548,55 +571,55 @@ work/foozolix-1.0/ patch has an extra `<tt>foozolix-1.0/</tt>' in front of the filenames, then set `<tt>PATCH_DIST_STRIP=-p1</tt>'. - <p>Don't worry if the patches are compressed, they will be + <p>Do not worry if the patches are compressed, they will be decompressed automatically if the filenames end with `<tt>.gz</tt>' or `<tt>.Z</tt>'. - <sect2> + <sect3> <heading>MAINTAINER</heading> <p>Set your mail-address here. Please. <tt>:)</tt> - <sect2> + <sect3> <heading>Dependencies</heading> <p>Many ports depend on other ports. There are five variables that you can use to ensure that all the required bits will be on the user's machine. - <sect3> + <sect4> <heading>LIB_DEPENDS</heading> <p>This variable specifies the shared libraries this port depends on. It is a list of `<tt>lib:dir</tt>' pairs where <tt>lib</tt> is the name of the shared library, and <tt>dir</tt> is the directory in which to find it in case - it's not available. For example, + it is not available. For example, <tscreen><verb> LIB_DEPENDS= tcl\\.7\\.:${PORTSDIR}/lang/tcl </verb></tscreen> will check for a shared tcl library with major version 7, and descend into the <tt>lang/tcl</tt> subdirectory of - your ports tree to build and install it if it's not found. + your ports tree to build and install it if it is not found. Note that the <tt>lib</tt> part is just an argument given to `<tt>ldconfig -r | grep</tt>', so periods should be escaped by two backslashes like in the example above. - <sect3> + <sect4> <heading>RUN_DEPENDS</heading> <p>This variable specifies executables this port depends on during run-time. It is a list of `<tt>exec:dir</tt>' pairs where <tt>exec</tt> is the name of the executable, and <tt>dir</tt> is the directory in which to find it in - case it's not available. For example, + case it is not available. For example, <tscreen><verb> RUN_DEPENDS= wish:${PORTSDIR}/x11/tk </verb></tscreen> will check for an executable called `<tt>wish</tt>', and descend into the <tt>x11/tk</tt> subdirectory of your - ports tree to build and install it if it's not found. + ports tree to build and install it if it is not found. The dependency is checked from within the <tt>install</tt> target. Also, the name of the dependency is put in to the package so that <tt>pkg_add</tt> will automatically install it if it is not on the user's system. - <sect3> + <sect4> <heading>BUILD_DEPENDS</heading> <p>This variable specifies executables this port requires to build. Like <tt>RUN_DEPENDS</tt>, it is a list of @@ -606,12 +629,12 @@ BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip </verb></tscreen> will check for an executable called `<tt>unzip</tt>', and descend into the <tt>archivers/unzip</tt> subdirectory of - your ports tree to build and install it if it's not found. + your ports tree to build and install it if it is not found. Note that `build' here means everything from extracting to compilation. The dependency is checked from within the <tt>extract</tt> target. - <sect3> + <sect4> <heading>FETCH_DEPENDS</heading> <p>This variable specifies executables this port requires to fetch. Like the previous two, it is a list of @@ -621,20 +644,20 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 </verb></tscreen> will check for an executable called `<tt>ncftp2</tt>', and descend into the <tt>net/ncftp2</tt> subdirectory of - your ports tree to build and install it if it's not found. + your ports tree to build and install it if it is not found. The dependency is checked from within the <tt>fetch</tt> target. - <sect3> + <sect4> <heading>DEPENDS</heading> - <p>If there is a dependency that doesn't fall into either of + <p>If there is a dependency that does not fall into either of the above four categories, or your port requires to have the source of the other port extracted (i.e., having them installed is not enough), then use this variable. This is just a list of directories, as there is nothing to check, unlike the previous two. - <sect2> + <sect3> <heading>Building mechanisms</heading> <p>If your package uses GNU <tt>make</tt>, set `<tt>USE_GMAKE=yes</tt>'. If your package uses GNU @@ -656,14 +679,14 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 <tt>${ALL_TARGET}</tt> accordingly. Same goes for `<tt>install</tt>' and <tt>${INSTALL_TARGET}</tt>. - <sect2> + <sect3> <heading>NO_INSTALL_MANPAGES</heading> - <p>If the port uses imake but doesn't understand the + <p>If the port uses imake but does not understand the `<tt>install.man</tt>' target, `<tt>NO_INSTALL_MANPAGES=yes</tt>' should be set. In addition, the author of the original port should be shot. - <sect1> + <sect2> <heading>Licensing Problems</heading> <p>Some software packages have restrictive licenses or are in violation to the law (PKP's patent on public key crypto, @@ -673,57 +696,56 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 <p>Note that it is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD - project won't held accountable of violating them by + project will not be held accountable of violating them by redistributing the source or compiled binaries either via ftp - or CD-ROM. If in doubt, please contact - <tt>ports@freebsd.org</tt>. + or CD-ROM. If in doubt, please contact the &a.ports;. <p>We usually get around this problem by setting <tt>${NO_PACKAGE}</tt> in the Makefile, and not putting the distfile up for ftp. However, for most cases, you should - at least be able to make a port, so don't let the license + at least be able to make a port, so do not let the license scare you away! <p>Note: The GNU General Public License (GPL), both version 1 - and 2, shouldn't be a problem for ports. + and 2, should not be a problem for ports. <p>Note: If you are a committer, make sure you update the <tt>ports/LEGAL</tt> file too. - <sect1> + <sect2> <heading>* Upgrading</heading> <p>This section is still under construction, sorry. - <sect1> + <sect2> <heading>Do's and Dont's</heading> - <p>Here's a list of common do's and dont's that you encounter + <p>Here is a list of common do's and dont's that you encounter during the porting process. - <sect2> + <sect3> <heading>WRKDIR</heading> - <p>Don't leave anything valuable lying around in the + <p>Do not leave anything valuable lying around in the `<tt>work</tt>' subdirectory, `<tt>make clean</tt>' will <em>nuke</em> it completely! If you need auxiliary files - that aren't scripts or patches, put them in the subdirectory + that are not scripts or patches, put them in the subdirectory `<tt>files</tt>' and use the <tt>post-extract</tt> target to copy them to the `<tt>work</tt>' subdirectory. - <sect2> + <sect3> <heading>Package information</heading> <p>Do install package information, i.e., the three files in <tt>pkg</tt>. Note that these files are not used only for packaging anymore, and are <em>mandatory</em> now, even if <tt>${NO_PACKAGE}</tt> is set. - <sect2> + <sect3> <heading>Compress manpages, strip binaries</heading> <p>Do compress manpages and strip binaries. If the original source already does that, fine; otherwise, you can add a <tt>post-install</tt> rule to do it yourself. Make sure that you check the variable <tt>NOMANCOMPRESS</tt> that the user can set in <tt>/etc/make.conf</tt> to disable man page - compression. Here's an example: + compression. Here is an example: <tscreen><verb> post-install: strip ${PREFIX}/bin/xdl @@ -734,16 +756,69 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 <p>Use the <tt>file</tt> command on the installed executable to check whether the binary is stripped or not. If it - doesn't say `not stripped', it is stripped. + does not say `not stripped', it is stripped. + + <sect3> + <heading>Install additional documentation</heading> + <p>If your software has some documentation other than the + standard man and info pages that you think is useful for the + user, install it under <tt>${PREFIX}/share/doc</tt>. + This can be done, like the previous item, in the + <tt>post-install</tt> target. + + <p>Create a new directory for your port. The directory name + should reflect what the port is. This usually means + <tt>${PKGNAME}</tt> minus the version part. However, + if you think the user might want different versions of the + port to be installed at the same time (e.g., tcl/tk), you + can use the whole <tt>${PKGNAME}</tt>. + + <p>Make the installation dependent to the variable + <tt>NOPORTDOCS</tt> so that users can disable it in + <tt>/etc/make.conf</tt>, like this: +<tscreen><verb> + post-install: + .if !defined(NOPORTDOCS) + mkdir -p ${PREFIX}/share/doc/xv + cp ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv + .endif +</verb></tscreen> - <sect2> + <p>Do not forget to add them to <tt>pkg/PLIST</tt> too! (Do not + worry about <tt>NOPORTDOCS</tt> here; there is currently no + way for the packages to read variables from + <tt>/etc/make.conf</tt>.) + + <sect3> + <heading>DIST_SUBDIR</heading> + <p>Do not let your port clutter <tt>/usr/ports/distfiles</tt>. If + your port requires a lot of files (including patchfiles) to be + fetched, or contains a file that has a name that might conflict + with other ports (e.g., `Makefile'), set + <tt>${DIST_SUBDIR}</tt> to the name of the port + (<tt>${PKGNAME}</tt> without the version part should work + fine). This will change <tt>${DISTDIR}</tt> from the + default <tt>/usr/ports/distfiles</tt> to + <tt>/usr/ports/distfiles/${DIST_SUBDIR}</tt>, and in + effect puts everything that is required for your port into that + subdirectory. + + <p>It will also look at the subdirectory with the same name on the + backup master site at <tt>ftp.freebsd.org</tt>. (Setting + <tt>${DISTDIR}</tt> explicitly in your Makefile will not + accomplish this, so please use <tt>${DIST_SUBDIR}</tt>.) + + <p>Note this does not affect the <tt>${MASTER_SITES}</tt> + you define in your Makefile. + + <sect3> <heading>Custom utilities</heading> - <p>Don't rely on custom utilities in your local configure + <p>Do not rely on custom utilities in your local configure script or anything -- 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. + least you will have given the user some idea of what is needed. If the custom utility or package is actually part of the ports tree, this should be dealt by the dependency mechanism of ports. @@ -757,23 +832,23 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 `<tt>make</tt>' and have that port, as well as everything it requires, built automatically. - <sect2> + <sect3> <heading>Feedback</heading> <p>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. - <sect2> + <sect3> <heading>RCS strings</heading> - <p>Don't put RCS strings in patches. CVS will mangle them + <p>Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar (`<tt>$</tt>') signs, and typically start with `<tt>$Id</tt>' or `<tt>$RCS</tt>'. - <sect2> + <sect3> <heading>Recursive diff</heading> <p>Using the recurse (`<tt>-r</tt>') option to <tt>diff</tt> to generate patches is fine, but please take a look at the @@ -785,25 +860,44 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 <tt>post-extract</tt> target rather than as part of the patch. - <sect2> + <sect3> <heading>PREFIX</heading> <p>Do try to make your port install relative to - <tt>${PREFIX}</tt> in your Makefiles. This will - normally be set to <tt>/usr/local</tt>, or - <tt>/usr/X11R6</tt> if <tt>${USE_IMAKE}</tt> or - <tt>${USE_X11}</tt> is set, though it can be - reassigned in your Makefile or in the users environment, if - need be. - - <p>Not hard-coding <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 independent - of <tt>${PREFIX}</tt> unless the package is one that - hard-codes itself to a compiled-in location. - - <sect2> + <tt>${PREFIX}</tt>. (The value of this variable will be + set to <tt>${LOCALBASE}</tt> (default + <tt>/usr/local</tt>), unless <tt>${USE_IMAKE}</tt> or + <tt>${USE_X11}</tt> is set, in which case it will be + <tt>${X11BASE}</tt> (default <tt>/usr/X11R6</tt>).) + + <p>Not hard-coding `<tt>/usr/local</tt>' or `<tt>/usr/X11R6</tt>' + anywhere in the source will make the port much more flexible and + able to cater to the needs of other sites. For X ports that use + imake, this is automatic; otherwise, this can often be done by + simply replacing the occurrences of `<tt>/usr/local</tt>' (or + `<tt>/usr/X11R6</tt>' for X ports that do not use imake) in the + various scripts/Makefiles in the port to read + `<tt>${PREFIX}</tt>', as this variable is automatically + passed down to every stage of the build and install processes. + + <p>The variable <tt>${PREFIX}</tt> can be reassigned in your + Makefile or in the user's environment. However, it is strongly + discouraged for individual ports to set this variable explicitly + in the Makefiles. (If your port is an X port but does not use + imake, set <tt>USE_X11=yes</tt>; this is quite different from + setting <tt>PREFIX=/usr/X11R6</tt>.) + + <p>Also, refer to programs/files from other ports with the + variables mentioned above, not explicit pathnames. For instance, + if your port requires a macro <tt>PAGER</tt> to be the full + pathname of <tt>less</tt>, use the compiler flag: + <verb>-DPAGER=\"${PREFIX}/bin/less\"</verb> or + <verb>-DPAGER=\"${LOCALBASE}/bin/less\"</verb> if this is an + X port, instead of <verb>-DPAGER=\"/usr/local/bin/less\"</verb>. + This way it will have a better chance of working if the system + administrator has moved the whole `/usr/local' tree somewhere + else. + + <sect3> <heading>Subdirectories</heading> <p>Try to let the port put things in the right subdirectories of <tt>${PREFIX}</tt>. Some ports lump everything @@ -820,7 +914,7 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 <tt>/usr</tt> pretty much applies to <tt>/usr/local</tt> too. - <sect2> + <sect3> <heading>ldconfig</heading> <p>If your port installs a shared library, add a <tt>post-install</tt> target to your Makefile that runs @@ -839,29 +933,29 @@ lib/libtcl.so.7.3 </verb></tscreen> <p>Note: the `-m' option is new since 2.0.5 and - 2.1.0-950726-SNAP, so don't be alarmed if it doesn't work on + 2.1.0-950726-SNAP, so do not be alarmed if it does not work on your machine. <p>Never, ever, <em>ever</em> add a line that says `<tt>ldconfig</tt>' without any arguments to your Makefile or pkg/PLIST. This will reset the shared library cache to the contents of <tt>/usr/lib</tt> only, and will royally - screw up the user's machine ("Help, xinit doesn't run + screw up the user's machine ("Help, xinit does not run anymore after I install this port!"). Anybody who does this will be shot and cut into 65,536 pieces by a rusty knife and have his liver chopped out by a bunch of crows and will eternally rot to death in the deepest bowels of hell (not necessarily in that order).... - <sect2> + <sect3> <heading>If you are stuck....</heading> <p>Do look at existing examples and the <tt>bsd.port.mk</tt> file before asking us questions! <tt>;)</tt> - <p>Do ask us questions if you have any trouble! Don't just + <p>Do ask us questions if you have any trouble! Do not just beat your head against a wall! <tt>:)</tt> - <sect1> + <sect2> <heading>A Sample Makefile</heading> <p>Here is a sample Makefile that you can use to create a new port. Make sure you remove all the extra comments (ones @@ -882,19 +976,18 @@ lib/libtcl.so.7.3 person who wrote this Makefile] # Whom: Satoshi Asami <asami@FreeBSD.ORG> # - # $Id: porting.sgml,v 1.2.4.4 1996-01-31 14:32:25 mpp Exp $ - [ ^^^^ don't worry about this...it will be automatically filled in by CVS when - it is committed to our repository] + # $Id: porting.sgml,v 1.2.4.5 1996-06-19 20:28:08 jkh Exp $ + [ ^^^^ do not worry about this...it will be automatically filled in by CVS + when it is committed to our repository] # [section to describe the package itself and main ftp site - DISTNAME is always first, followed by PKGNAME (if necessary), CATEGORIES, - KEYWORDs (if necessary) and then MASTER_SITES, and optionally - EXTRACT_SUFX or DISTFILES] + and then MASTER_SITES, and optionally EXTRACT_SUFX or DISTFILES] DISTNAME= xdvi PKGNAME= xdvi-pl18 CATEGORIES+= printing - [don't forget the trailing slash ("/")!] + [do not forget the trailing slash ("/")!] MASTER_SITES= ftp://crl.dec.com/pub/X11/contrib/applications/ [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z @@ -906,7 +999,7 @@ lib/libtcl.so.7.3 [maintainer; *mandatory*! This is the person (preferably with commit privileges) who a user can contact for questions and bug reports - this person should be the porter or someone who can forward questions to the - original porter reasonably promptly. If you really don't want to have your + original porter reasonably promptly. If you really do not want to have your address here, set it to "ports@FreeBSD.ORG".] MAINTAINER= asami@FreeBSD.ORG @@ -914,8 +1007,8 @@ lib/libtcl.so.7.3 RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm - [this section is for other standard bsd.port.mk variables that don't belong to - any of the above] + [this section is for other standard bsd.port.mk variables that do not belong + to any of the above] [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If it asks questions during configure, build, install...] @@ -945,7 +1038,7 @@ lib/libtcl.so.7.3 .include <bsd.port.mk> </verb></tscreen> - <sect1> + <sect2> <heading>Package Names</heading> <p>The following are the conventions you should follow in @@ -1000,13 +1093,13 @@ xvgr-2.10pl1 xvgr-2.10.1 `pl' allowed only when no maj/minor numbers original author or use the date string (`yy.mm.dd') as the version. - <sect1> - <heading>That's It, Folks!</heading> + <sect2> + <heading>That is It, Folks!</heading> <p>Boy, this sure was a long tutorial, wasn't it? Thanks for following us to here, really. - <p>Well, now that you know how to do a port, let's go at it and + <p>Well, now that you know how to do a port, let us go at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! <tt>:)</tt> diff --git a/handbook/ports.sgml b/handbook/ports.sgml index f4ea580c39..fa6942b2e9 100644 --- a/handbook/ports.sgml +++ b/handbook/ports.sgml @@ -1,4 +1,4 @@ -<!-- $Id: ports.sgml,v 1.2.4.2 1995-10-12 03:16:27 jfieber Exp $ --> +<!-- $Id: ports.sgml,v 1.2.4.3 1996-06-19 20:28:09 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>The Ports collection<label id="ports"></heading> @@ -32,7 +32,7 @@ those shell scripts, Makefiles and source code ``diffs'' that are necessary to configure and compile the program under FreeBSD. This keeps the entire system down to a manageable size, with the current system having over 300 ports in the master source tree and yet taking -up less than ten megabytes. +up less than twenty megabytes. <sect1><heading>How does the system compile with no source code?</heading> @@ -41,8 +41,8 @@ up less than ten megabytes. 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''. Those not found locally are searched for -wherever they're generally provided on the Internet. If you have a -CDROM distribution of FreeBSD then you've already got them available +wherever they are generally provided on the Internet. If you have a +CDROM distribution of FreeBSD then you already have them available on your CD for ease of use. See <ref id="ports:cd" name="Compiling ports from CD"> if you have such a CDROM distribution, otherwise skip to <ref id="ports:inet" @@ -58,11 +58,11 @@ from <tt>/usr/ports</tt> to that directory. Then invoke the <tt>lndir(1)</tt> c the full pathname of the ``ports'' directory on the CDROM as an argument (this might be, for example, something like: <tt>lndir /cdrom/ports</tt>). Then you can build ports directly off the CDROM by -building them in the link tree you've created. +building them in the link tree you have created. -Note that there are some ports for which we can't provide the original +Note that there are some ports for which we cannot provide the original source in the CDROM due to licensing limitations. In that case, -you'll need to look at the next section (<ref id="ports:inet" +you will need to look at the next section (<ref id="ports:inet" name="Compiling ports using an Internet connection">). <sect1><heading>Compiling ports using an Internet connection<label id="ports:inet"></heading> @@ -71,8 +71,8 @@ name="Compiling ports using an Internet connection">). 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 assumes you have a permanent network link or don't -mind heavy usage of your telephone. If you don't want heavy network + Of course, this assumes you have a permanent network link or do not +mind heavy usage of your telephone. If you do not 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 by hand. A good way to see what files a port is going to need is to @@ -86,15 +86,15 @@ 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 <tt>/pub/FreeBSD/distfiles</tt>. Note that the files in that directory are not guaranteed 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 independent control and don't +volunteer project! We canno make any guarantees about the mirror +sites either - they are obviously under independent control and do not even have to mirror the distfiles directory. If you have a non-permanent 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> +<sect1><heading>It does not work?!</heading> <p>Oh. You can do one of four (4) things : <enum> @@ -105,17 +105,17 @@ going to the top of the tree and typing ``make fetch''. <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 + is mainly contributed by 3rd parties. (If you do not 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 e-mail address is the &a.ports;. 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 + Note: At time of writing, lang/Sather does not 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 + Please do not tell us about this - gripe to Intel instead - it is their bug! <item> Forget it. This is the easiest for most - very few of the programs in @@ -132,23 +132,21 @@ going to the top of the tree and typing ``make fetch''. install them to your system. </enum> -<sect1><heading>I've ported a program and I want to make a port out of it. What now?</heading> +<sect1><heading>I have 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. +<p> See the <ref id="porting:starting" name="guidelines"> that + contain details of the procedure and structure involved. - -<sect1><heading>I've got a good port, what now?</heading> +<sect1><heading>I have got a good port, what now?</heading> <p>Upload the fixed version to <tt>ftp://freefall.cdrom.com/pub/incoming</tt> or <tt>ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming</tt> and send e-mail to -ports@FreeBSD.org with the filename and details. Someone on the +the &a.ports 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>I want to leave the compile going overnight, but some ports don't like this.</heading> +<sect1><heading>I want to leave the compile going overnight, but some ports do not like this.</heading> <p> There is a way around this. Before starting the compilation, type: <verb> @@ -175,11 +173,11 @@ 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. The most up-to-date copy can be found in: - <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> + <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 +by all means do so, and then send the diffs to the &a.ports if +you would like them to be a part of the default distribution. Please also remember that any changes must respect backwards-compatibility with any and all older Makefiles, unless you want a real nightmare of /usr/ports munging ahead of you! Large scale changes will generally @@ -189,7 +187,7 @@ alteration. Sorry! <sect1><heading>This FAQ is weak. What can I do?</heading> -<p> Send changes to ports@FreeBSD.org. Changes are most welcome! +<p> Send changes to the &a.ports;. 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! :-) @@ -204,7 +202,7 @@ and type: </verb> This will print a summary of all ports in the tree. -<sect1><heading>I've heard of a new checksum system. What is this for?</heading> +<sect1><heading>I have 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 @@ -225,7 +223,7 @@ checksum routine. The same technique can be applied to a single port. for that port. Not all ports currently have checksums, but this should be cured soon. - Some older versions of the system don't recognize the ``checksum'' + Some older versions of the system do not recognize the ``checksum'' target. In that case, try the command <verb> make check-md5 @@ -233,7 +231,7 @@ target. In that case, try the command (``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"> + <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 index ccfa137955..975b7c8cd2 100644 --- a/handbook/ppp.sgml +++ b/handbook/ppp.sgml @@ -1,4 +1,4 @@ -<!-- $Id: ppp.sgml,v 1.1.1.1.4.2 1995-10-12 03:16:29 jfieber Exp $ --> +<!-- $Id: ppp.sgml,v 1.1.1.1.4.3 1996-06-19 20:28:10 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>Setting up kernel PPP<label id="ppp"></heading> @@ -17,17 +17,17 @@ 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 ). +In both cases you will need to set up an options file (<tt>/etc/ppp/options</tt> +or <tt>~/.ppprc</tt> 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. +<p>I used the following <tt>/etc/ppp/options</tt> to connect to CISCO terminal +server PPP line. <verb> crtscts # enable hardware flow control modem # modem control line @@ -62,10 +62,10 @@ on the remote host ) </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 +reasons you can add the "debug" option to the <tt>/etc/ppp/options</tt> file and check messages on the console to track the problem -Following /etc/ppp/pppup script will make all 3 stages automatically: +Following <tt>/etc/ppp/pppup</tt> script will make all 3 stages automatically: <verb> #!/bin/sh ps ax |grep pppd |grep -v grep @@ -88,11 +88,11 @@ kermit -y /etc/ppp/kermit.dial pppd /dev/tty01 19200 </verb> -/etc/ppp/kermit.dial is kermit script that dials and makes all +<tt>/etc/ppp/kermit.dial</tt> 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 following /etc/ppp/pppdown script to disconnect the PPP line: +Use the following <tt>/etc/ppp/pppdown</tt> script to disconnect the PPP line: <verb> #!/bin/sh pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` @@ -114,7 +114,7 @@ kermit -y /etc/ppp/kermit.hup /etc/ppp/ppptest </verb> -Check if PPP is still running (/usr/etc/ppp/ppptest): +Check if PPP is still running (<tt>/usr/etc/ppp/ppptest</tt>): <verb> #!/bin/sh pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` @@ -128,7 +128,7 @@ netstat -n -I ppp0 ifconfig ppp0 </verb> -Hangs up modem line (/etc/ppp/kermit.hup): +Hangs up modem line (<tt>/etc/ppp/kermit.hup</tt>): <verb> set line /dev/tty01 ; put your modem device here set speed 19200 @@ -152,7 +152,7 @@ exit <sect1><heading>Working as a PPP server</heading> -<p>/etc/ppp/options: +<p><tt>/etc/ppp/options</tt>: <verb> crtscts # Hardware flow control netmask 255.255.255.0 # netmask ( not required ) @@ -167,7 +167,8 @@ passive # wait for LCP modem # modem line </verb> -Following /etc/ppp/pppserv script will enable ppp server on your machine +Following <tt>/etc/ppp/pppserv</tt> script will enable ppp server on your +machine <verb> #!/bin/sh ps ax |grep pppd |grep -v grep @@ -194,7 +195,7 @@ kermit -y /etc/ppp/kermit.ans pppd /dev/tty01 19200 </verb> -Use this /etc/ppp/pppservdown script to stop ppp server: +Use this <tt>/etc/ppp/pppservdown</tt> script to stop ppp server: <verb> #!/bin/sh ps ax |grep pppd |grep -v grep @@ -216,7 +217,7 @@ kermit -y /etc/ppp/kermit.noans </verb> Following kermit script will enable/disable autoanswer mode -on your modem (/etc/ppp/kermit.ans): +on your modem (<tt>/etc/ppp/kermit.ans</tt>): <verb> set line /dev/tty01 set speed 19200 @@ -243,9 +244,9 @@ 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 +This <tt>/etc/ppp/kermit.dial</tt> 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 will need to change input statement depending on responses from your modem and remote host. <verb> diff --git a/handbook/printing.sgml b/handbook/printing.sgml index 719a6d0890..a555258933 100644 --- a/handbook/printing.sgml +++ b/handbook/printing.sgml @@ -1,7 +1,7 @@ <!-- This is an SGML document in the linuxdoc DTD describing Printing with FreeBSD. By Sean Kelly, 1995. - $Id: printing.sgml,v 1.2.2.1 1996-01-31 14:32:26 mpp Exp $ + $Id: printing.sgml,v 1.2.2.2 1996-06-19 20:28:12 jkh Exp $ The FreeBSD Documentation Project @@ -24,13 +24,13 @@ <p><em>Contributed by &a.kelly;<newline>30 September 1995</em> - In order to use printers with FreeBSD, you'll need to set + In order to use printers with FreeBSD, you will need to set them up to work with the Berkeley line printer spooling - system, also known as the LPD spooling system. It's the + system, also known as the LPD spooling system. It iss the standard printer control system in FreeBSD. This section introduces the LPD spooling system, often simply called LPD. - If you're already familiar with LPD or another printer + If you are already familiar with LPD or another printer spooling system, you may wish to skip to section <ref id="printing:intro:setup" name="Setting up the spooling system">. @@ -38,7 +38,7 @@ <sect><heading>What the Spooler Does<label id="printing:intro:spooler"></heading> - <p> LPD controls everything about a host's printers. It's + <p> LPD controls everything about a host's printers. It is responsible for a number of things: <itemize> @@ -54,7 +54,7 @@ <item>It can print <em/header pages/ (also known as <em/banner/ or <em/burst/ pages) so users can easily - find jobs they've printed in a stack of printouts. + find jobs they have printed in a stack of printouts. <item>It takes care of communications parameters for printers connected on serial ports. @@ -77,7 +77,7 @@ <sect><heading>Why You Should Use the Spooler<label id="printing:intro:why"></heading> - <p> If you're the sole user of your system, you may be + <p> If you are the sole user of your system, you may be wondering why you should bother with the spooler when you don't need access control, header pages, or printer accounting. While it's possible to enable direct access to @@ -90,12 +90,12 @@ <item>LPD can conveniently run a job to be printed through filters to add date/time headers or convert a special file format (such as a TeX DVI file) into a - format the printer will understand. You won't have to do + format the printer will understand. You will not have to do these steps manually. <item>Many free and commercial programs that provide a print feature usually expect to talk to the spooler on - your system. By setting up the spooling system, you'll + your system. By setting up the spooling system, you will more easily support other software you may later add or already have. </itemize> @@ -103,7 +103,7 @@ <sect><heading>Setting Up the Spooling System<label id="printing:intro:setup"></heading> - <p> To use printers with the LPD spooling system, you'll need + <p> To use printers with the LPD spooling system, you will need to set up both your printer hardware and the LPD software. This document describes two levels of setup: @@ -137,12 +137,12 @@ file <tt>/etc/printcap</tt>. </itemize> - If you're setting up a printer that uses a network protocol + If you are setting up a printer that uses a network protocol to accept data to print instead of a serial or parallel interface, see <ref id="printing:advanced:network:net-if" name="Printers With Networked Data Stream Interaces">. - Although this section is called ``Simple Printer Setup,'' it's + Although this section is called ``Simple Printer Setup,'' it is actually fairly complex. Getting the printer to work with your computer and the LPD spooler is the hardest part. The advanced options like header pages and accounting are fairly @@ -155,7 +155,7 @@ cables, and also the kernel configuration you may need to enable FreeBSD to speak to the printer. - If you've already connected your printer and have + If you have already connected your printer and have successfully printed with it under another operating system, you can probably skip to section <ref id="printing:software" name="Software Setup">. @@ -193,21 +193,21 @@ one-way communication (computer to printer) while serial gives you two-way. Many newer parallel ports can also receive data from the printer, but only few printers need - to send data back to the computer. And FreeBSD doesn't + to send data back to the computer. And FreeBSD does not support two-way parallel communication yet. Usually, the only time you need two-way communication with the printer is if the printer speaks PostScript. PostScript printers can be very verbose. In fact, PostScript jobs are actually programs sent to the printer; - they needn't produce paper at all and may return results + they need not produce paper at all and may return results directly to the computer. PostScript also uses two-way communication to tell the computer about problems, such as errors in the PostScript program or paper jams. Your users may be appreciative of such information. Furthermore, the best way to do effective accounting with a PostScript printer requires two-way communication: you - ask the printer for its page count (how many pages it's + ask the printer for its page count (how many pages it has printed in its lifetime), then send the user's job, then ask again for its page count. Subtract the two values and you know how much paper to charge the user. @@ -219,11 +219,11 @@ port. FreeBSD does not yet support two-way communication over a parallel port. - <item>If you don't need two-way communication and can + <item>If you do not need two-way communication and can pick parallel or serial, prefer the parallel interface. It keeps a serial port free for other peripherals---such as a terminal or a modem---and is - faster most of the time. It's also easier to + faster most of the time. It is also easier to configure. <item>Finally, use whatever works. @@ -248,7 +248,7 @@ computer. The instructions that came with the printer, the computer, or both should give you complete guidance. - If you're unsure what the ``proper serial cable'' is, you + If you are unsure what the ``proper serial cable'' is, you may wish to try one of the following alternatives: <itemize> <item>A <em/modem/ cable connects each pin of the @@ -285,15 +285,15 @@ <p> This section describes the software setup necessary to print with the LPD spooling system in FreeBSD. - Here's an outline of the steps involved: + Here is an outline of the steps involved: <enum> <item>Configure your kernel, if necessary, for the port - you're using for the printer; section <ref + you are using for the printer; section <ref id="printing:kernel" name="Kernel Configuration"> tells you what you need to do. <item>Set the communications mode for the parallel port, - if you're using a parallel port; section <ref + if you are using a parallel port; section <ref id="printing:parallel-port-mode" name = "Setting the Communication Mode for the Parallel Port"> gives details. @@ -316,10 +316,10 @@ specific set of devices. The serial or parallel interface for your printer is a part of that set. Therefore, it might be necessary to add support for an additional serial - or parallel port if your kernel isn't already configured + or parallel port if your kernel is not already configured for one. - To find out if the kernel you're currently using supports a serial + To find out if the kernel you are currently using supports a serial interface, type <tscreen> <tt>dmesg | grep sio</tt><it/N/ @@ -346,7 +346,7 @@ lpt0 at 0x378-0x37f on isa You might have to reconfigure your kernel in order for the operating system to recognize and use the parallel or - serial port you're using for the printer. + serial port you are using for the printer. To add support for a serial port, see the section on kernel configuration. To add support for a parallel port, @@ -356,9 +356,9 @@ lpt0 at 0x378-0x37f on isa <label id="printing:dev-ports"></heading> <p> Even though the kernel may support communication along - a serial or parallel port, you'll still need a software + a serial or parallel port, you will still need a software interface through which programs running on the system - can send and receive data. That's what entries in the + can send and receive data. That is what entries in the <tt>/dev</tt> directory are for. <bf>To add a <tt>/dev</tt> entry for a port:</bf> @@ -391,7 +391,7 @@ cd /dev <sect3><heading>Setting the Communication Mode for the Parallel Port <label id="printing:parallel-port-mode"></heading> - <p> When you're using the parallel interface, you can + <p> When you are using the parallel interface, you can choose whether FreeBSD should use interrupt-driven or polled communication with the printer. @@ -402,7 +402,7 @@ cd /dev the printer is ready for data. <item>The <em/polled/ method directs the operating - system to repeatedly ask the printer if it's ready + system to repeatedly ask the printer if it is ready for more data. When it responds ready, the kernel sends more data. </itemize> @@ -419,7 +419,7 @@ cd /dev kernel:</bf> <enum> <item>Edit your kernel configuration file. Look for - or add an <tt/lpt0/ entry. If you're setting up the + or add an <tt/lpt0/ entry. If you are setting up the second parallel port, use <tt/lpt1/ instead. Use <tt/lpt2/ for the third port, and so on. <itemize> @@ -431,7 +431,7 @@ cd /dev where <it/N/ is the IRQ number for your computer's parallel port. - <item>If you want polled mode, don't add the + <item>If you want polled mode, do not add the <tt/irq/ specifier: <tscreen> <tt>device lpt0 at isa? port? tty vector lptintr</tt> @@ -469,17 +469,17 @@ cd /dev <p> Before proceeding to configure the spooling system, you should make sure the operating system can - successfully send data to your printer. It's a lot + successfully send data to your printer. It is a lot easier to debug printer communication and the spooling system separately. - To test the printer, we'll send some text to it. For + To test the printer, we will send some text to it. For printers that can immediately print characters sent to them, the program <tt/lptest/ is perfect: it generates all 96 printable ASCII characters in 96 lines. For a PostScript (or other language-based) printer, - we'll need a more sophisticated test. A small + we will need a more sophisticated test. A small PostScript program, such as the following, will suffice: <code> %!PS @@ -490,11 +490,11 @@ cd /dev showpage </code> <em/Note:/ When this document refers to a printer - language, I'm assuming a language like PostScript, and + language, I am assuming a language like PostScript, and not Hewlett Packard's PCL. Although PCL has great functionality, you can intermingle plain text with its escape sequences. PostScript cannot directly print - plain text, and that's the kind of printer language for + plain text, and that is the kind of printer language for which we must make special accommodations. <sect4><heading>Checking a Parallel Printer<label @@ -523,8 +523,8 @@ showpage <tt>cat > /dev/lpt<it/N/</tt> </tscreen> Then, line by line, type the program - <em/carefully/ as you can't edit a line once - you've pressed RETURN or ENTER. When you've + <em/carefully/ as you cannot edit a line once + you have pressed RETURN or ENTER. When you have finished entering the program, press CONTROL+D, or whatever your end of file key is. @@ -540,7 +540,7 @@ showpage </itemize> </enum> - You should see something print. Don't worry if the + You should see something print. Do not worry if the text doesn't look right; we'll fix such things later. <sect4><heading>Checking a Serial Printer<label @@ -565,7 +565,7 @@ showpage required by the printer (either <tt/even/, <tt/odd/, <tt/none/, or <tt/zero/). <p> - Here's a sample entry for a printer connected + Here is a sample entry for a printer connected via a serial line to the third serial port at 19200 bps with no parity: <code> @@ -576,7 +576,7 @@ printer:dv=/dev/ttyd2:br#19200:pa=none <tscreen><verb> tip printer </verb></tscreen> - If this step doesn't work, edit the file + If this step does not work, edit the file <tt>/etc/remote</tt> again and try using <tt>/dev/cuaa<it/N/</tt> instead of <tt>/dev/ttyd<it/N/</tt>. @@ -612,16 +612,16 @@ tip printer </itemize> </enum> - You should see something print. Don't worry if the - text doesn't look right; we'll fix that later. + You should see something print. Do not worry if the + text does not look right; we will fix that later. <sect2><heading>Enabling the Spooler: The <tt>/etc/printcap</tt> File <label id="printing:printcap"></heading> <p> At this point, your printer should be hooked up, your kernel configured to communicate with it (if necessary), - and you've been able to send some simple data to the - printer. Now, we're ready to configure LPD to control + and you have been able to send some simple data to the + printer. Now, we are ready to configure LPD to control access to your printer. You configure LPD by editing the file @@ -673,17 +673,17 @@ tip printer </enum> <em/Note:/ Language-based printers, such as PostScript - printers, can't directly print plain text. The simple + printers, cannot directly print plain text. The simple setup outlined above and described in the following - sections assumes that if you're installing such a printer - you'll print only files that the printer can understand. + sections assumes that if you are installing such a printer + you will print only files that the printer can understand. Users often expect that they can print plain text to any of the printers installed on your system. Programs that interface to LPD to do their printing usually make the - same assumption. If you're installing such a printer and + same assumption. If you are installing such a printer and want to be able to print jobs in the printer language - <em/and/ print plain text jobs, you're strongly urged to + <em/and/ print plain text jobs, you are strongly urged to add an additional step to the simple setup outlined above: install an automatic plain-text--to--PostScript (or other printer language) conversion program. Section <ref @@ -695,23 +695,23 @@ tip printer id="printing:naming"></heading> <p> The first (easy) step is to pick a name for your - printer. It really doesn't matter whether you choose + printer. It really does not matter whether you choose functional or whimsical names since you can also provide a number aliases for the printer. At least one of the printers specified in the <tt>/etc/printcap</tt> should have the alias <tt/lp/. This is the default printer's name. If users - don't have the PRINTER environment variable nor + do not have the PRINTER environment variable nor specify a printer name on the command line of any of the LPD commands, then <tt/lp/ will be the default printer they get to use. - Also, it's common practice to make the last alias for a + Also, it is common practice to make the last alias for a printer be a full description of the printer, including make and model. - Once you've picked a name and some common aliases, put + Once you have picked a name and some common aliases, put them in the <tt>/etc/printcap</tt> file. The name of the printer should start in the leftmost column. Separate each alias with a vertical bar and put a colon @@ -732,7 +732,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: In this example, the first printer is named <tt/rattan/ and has as aliases <tt/line/, <tt/diablo/, <tt/lp/, and <tt/Diablo 630 Line Printer/. Since it has the alias - <tt/lp/, it's also the default printer. The second is + <tt/lp/, it is also the default printer. The second is named <tt/bamboo/, and has as aliases <tt/ps/, <tt/PS/, <tt/S/, <tt/panasonic/, and <tt/Panasonic KX-P4455 PostScript v51.4/. @@ -745,12 +745,12 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: the user name who requested the job, the host from which the job came, and the name of the job, in nice large letters. Unfortunately, all this extra text gets in the - way of debugging the simple printer setup, so we'll + way of debugging the simple printer setup, so we will suppress header pages. To suppress header pages, add the <tt/sh/ capability to the entry for the printer in - <tt>/etc/printcap</tt>. Here's the example + <tt>/etc/printcap</tt>. Here is the example <tt>/etc/printcap</tt> with <tt/sh/ added: <code> # @@ -772,17 +772,17 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <p> The next step in the simple spooler setup is to make a <em/spooling directory/, a directory where print jobs - reside until they're printed, and where a number of + reside until they are printed, and where a number of other spooler support files live. Because of the variable nature of spooling directories, - it's customary to put these directories under - <tt>/var/spool</tt>. It's not necessary to backup the + it is customary to put these directories under + <tt>/var/spool</tt>. It is not necessary to backup the contents of spooling directories, either. Recreating them is as simple as running <tt/mkdir/. - It's also customary to make the directory with a name - that's identical to the name of the printer, as shown + It is also customary to make the directory with a name + that is identical to the name of the printer, as shown below: <tscreen> <tt>mkdir /var/spool/<it>printer-name</it></tt> @@ -790,7 +790,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ However, if you have a lot of printers on your network, you might want to put the spooling directories under a single directory that you reserve just for printing with - LPD. We'll do this for our two example printers + LPD. We will do this for our two example printers <tt/rattan/ and <tt/bamboo/: <tscreen><verb> mkdir /var/spool/lpd @@ -798,12 +798,12 @@ mkdir /var/spool/lpd/rattan mkdir /var/spool/lpd/bamboo </verb></tscreen> - <em/Note:/ If you're concerned about the privacy of jobs + <em/Note:/ If you are concerned about the privacy of jobs that users print, you might want to protect the spooling - directory so it's not publicly accessible. Spooling + directory so it is not publicly accessible. Spooling directories should be owned and be readable, writable, and searchable by user daemon and group daemon, and no - one else. We'll do this for our example printers: + one else. We will do this for our example printers: <tscreen><verb> chown daemon.daemon /var/spool/lpd/rattan @@ -831,7 +831,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ should be indented with a tab and each line escaped with a backslash. - If you don't specify a spooling directory with <tt/sd/, + If you do not specify a spooling directory with <tt/sd/, the spooling system will use <tt>/var/spool/lpd</tt> as a default. @@ -851,7 +851,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <tt>/etc/printcap</tt> file using the <tt/lp/ capability. - In our running example, let's assume that <tt/rattan/ is + In our running example, let us assume that <tt/rattan/ is on the first parallel port, and <tt/bamboo/ is on a sixth serial port; here are the additions to <tt>/etc/printcap</tt>: @@ -868,12 +868,12 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :lp=/dev/ttyd5: </code> - If you don't specify the <tt/lp/ capability for a + If you do not specify the <tt/lp/ capability for a printer in your <tt>/etc/printcap</tt> file, LPD uses <tt>/dev/lp</tt> as a default. <tt>/dev/lp</tt> - currently doesn't exist in FreeBSD. + currently does not exist in FreeBSD. - If the printer you're installing is connected to a + If the printer you are installing is connected to a parallel port, skip to the section <ref name="Installing the Text Filter" id="printing:textfilter">. Otherwise, be sure to follow the instructions in the next section. @@ -888,7 +888,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <itemize> <item>It lets you try different communication parameters by simply editing the - <tt>/etc/printcap</tt> file; you don't have to + <tt>/etc/printcap</tt> file; you do not have to recompile the filter program. <item>It enables the spooling system to use the same @@ -937,10 +937,10 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ the resultant setting. It does the same for the local mode bits as well. - Let's add to our example printer on the sixth serial - port. We'll set the bps rate to 38400. For the flag - bits, we'll set the TANDEM, ANYP, LITOUT, FLUSHO, and - PASS8 flags. For the local mode bits, we'll set the + Let us add to our example printer on the sixth serial + port. We will set the bps rate to 38400. For the flag + bits, we will set the TANDEM, ANYP, LITOUT, FLUSHO, and + PASS8 flags. For the local mode bits, we will set the LITOUT and PASS8 flags: <tscreen><verb> bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ @@ -952,7 +952,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <sect3><heading>Installing the Text Filter<label id="printing:textfilter"></heading> - <p> We're now ready to tell LPD what text filter to use to + <p> We are now ready to tell LPD what text filter to use to send jobs to the printer. A <em/text filter/, also known as an <em/input filter/, is a program that LPD runs when it has a job to print. When LPD runs the text @@ -976,7 +976,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <tt/lpf/ is described in detail in section <ref id="printing:advanced:lpf" name="lpf: a Text Filter">. - First, let's make the shell script + First, let uss make the shell script <tt>/usr/local/libexec/if-simple</tt> be a simple text filter. Put the following text into that file with your favorite text editor: @@ -997,7 +997,7 @@ chmod 555 /usr/local/libexec/if-simple </verb></tscreen> And then tell LPD to use it by specifying it with the - <tt/if/ capability in <tt>/etc/printcap</tt>. We'll add + <tt/if/ capability in <tt>/etc/printcap</tt>. We will add it to the two printers we have so far in the example <tt>/etc/printcap</tt>: <code> @@ -1017,9 +1017,9 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <sect3><heading>Trying It Out<label id="printing:trying"></heading> - <p> You've reached the end of the simple LPD setup. + <p> You have reached the end of the simple LPD setup. Unfortunately, congratulations are not quite yet in - order, since we've still got to test the setup and + order, since we still have to test the setup and correct any problems. To test the setup, try printing something. To print with the LPD system, you use the command <tt/lpr/, which submits a job for printing. @@ -1038,14 +1038,14 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ where <it/printer-name/ is a the name of a printer (or an alias) specified in <tt>/etc/printcap</tt>. To test the default printer, type <tt/lpr/ without any <tt/-P/ - argument. Again, if you're testing a printer that + argument. Again, if you are testing a printer that expects PostScript, send a PostScript program in that language instead of using <tt/lptest/. You can do so by putting the program in a file and typing <tt/lpr <it/file//. For a PostScript printer, you should get the results - of the program. If you're using <tt/lptest/, then your + of the program. If you are using <tt/lptest/, then your results should look like the following: <tscreen><verb> @@ -1062,7 +1062,7 @@ $%&ero;'()*+,-./01234567 <tt/lptest 80 60/ will produce 60 lines of 80 characters each. - If the printer didn't work, see the next section, <ref + If the printer did not work, see the next section, <ref id="printing:troubleshooting" name="Troubleshooting">. <sect3><heading>Troubleshooting<label @@ -1072,7 +1072,7 @@ $%&ero;'()*+,-./01234567 might have gotten one of the following results instead of the correct printout: <descrip> - <tag/It worked, after awhile; or, it didn't eject a full sheet./ + <tag/It worked, after awhile; or, it did not eject a full sheet./ The printer printed the above, but it sat for awhile and did nothing. In fact, you might have needed to @@ -1086,9 +1086,9 @@ $%&ero;'()*+,-./01234567 FEED character (or whatever is necessary) to the printer. This is usually sufficient to have the printer immediately print any text remaining in its - internal buffer. It's also useful to make sure each + internal buffer. It is also useful to make sure each print job ends on a full sheet, so the next job - doesn't start somewhere on the middle of the last + does not start somewhere on the middle of the last page of the previous job. The following replacement for the shell script @@ -1114,9 +1114,8 @@ exit 2 !"#$%&ero;'()*+,-./01234 "#$%&ero;'()*+,-./012345 #$%&ero;'()*+,-./0123456 - $%&ero;'()*+,-./01234567 </verb></tscreen> - You've become another victim of the <em/staircase + You have become another victim of the <em/staircase effect/, caused by conflicting interpretations of what characters should indicate a new-line. UNIX-style operating systems use a single character: @@ -1130,12 +1129,12 @@ exit 2 line feed character. The printer, upon seeing a line feed character, advanced the paper one line, but maintained the same horizontal position on the - page for the next character to print. That's what + page for the next character to print. That is what the carriage return is for: to move the location of the next character to print to the left edge of the paper. - Here's what FreeBSD wants your printer to do: + Here is what FreeBSD wants your printer to do: <tscreen><verb> Printer received CR Printer prints CR Printer received LF Printer prints CR + LF @@ -1171,7 +1170,7 @@ Printer received LF Printer prints CR + LF text filter to send the code first, then send the print job. - <p> Here's an example text filter for printers + <p> Here is an example text filter for printers that understand the Hewlett-Packard PCL escape codes. This filter makes the printer treat LF characters as a LF and CR; then it sends the @@ -1193,10 +1192,10 @@ printf "\033&ero;k2G" &ero;&ero; cat &ero;&ero; printf "\f" &ero;&ero; exit 0 exit 2 </code> - Here's an example <tt>/etc/printcap</tt> from + Here is an example <tt>/etc/printcap</tt> from a host called orchid. It has a single printer attached to its first parallel port, a Hewlett - Packard LaserJet 3Si named <tt/teak/. It's + Packard LaserJet 3Si named <tt/teak/. It is using the above script as its text filter: <code> # @@ -1231,14 +1230,14 @@ Printer received LF Printer prints CR + LF <tag/The printer lost characters./ - While printing, the printer didn't print a few + While printing, the printer did nott print a few characters in each line. The problem might have gotten worse as the printer ran, losing more and more characters. - The problem is that the printer can't keep up with + The problem is that the printer cannot keep up with the speed at which the computer sends data over a - serial line. (This problem shouldn't occur with + serial line. (This problem should not occur with printers on parallel ports.) There are two ways to overcome the problem: <itemize> @@ -1252,7 +1251,7 @@ Printer received LF Printer prints CR + LF printer to the computer is correctly wired for carrier flow control. - <item>If the printer doesn't support any flow + <item>If the printer does not support any flow control, use some combination of the NLDELAY, TBDELAY, CRDELAY, VTDELAY, and BSDELAY bits in the <tt/fs/ capability to add appropriate delays @@ -1277,8 +1276,8 @@ Printer received LF Printer prints CR + LF If nothing happened, the problem is probably within FreeBSD and not the hardware. Add the log file (<tt/lf/) capability to the entry for the printer - you're debugging in the <tt>/etc/printcap</tt> file. - For example, here's the entry for <tt/rattan/, with + you are debugging in the <tt>/etc/printcap</tt> file. + For example, here is the entry for <tt/rattan/, with the <tt/lf/ capability: <tscreen><verb> rattan|line|diablo|lp|Diablo 630 Line Printer:\ @@ -1292,13 +1291,13 @@ rattan|line|diablo|lp|Diablo 630 Line Printer:\ any error messages that might appear. Based on the messages you see, try to correct the problem. - If you don't specify a <tt/lf/ capability, LPD uses + If you do not specify a <tt/lf/ capability, LPD uses <tt>/dev/console</tt> as a default. </descrip> <sect><heading>Using Printers<label id="printing:using"></heading> - <p> This section tells you how to use printers you've setup with + <p> This section tells you how to use printers you have setup with FreeBSD. Here's an overview of the user-level commands: <descrip> <tag/<tt/lpr// @@ -1312,7 +1311,7 @@ rattan|line|diablo|lp|Diablo 630 Line Printer:\ </descrip> - There's also an administrative command, <tt/lpc/, described in + There is also an administrative command, <tt/lpc/, described in the section <ref id="printing:lpc" name="Administrating the LPD Spooler">, used to control printers and their queues. @@ -1320,15 +1319,15 @@ rattan|line|diablo|lp|Diablo 630 Line Printer:\ accept an option ``<tt/-P/ <it/printer-name/'' to specify on which printer/queue to operate, as listed in the <tt>/etc/printcap</tt> file. This enables you to submit, - remove, and check on jobs for various printers. If you don't + remove, and check on jobs for various printers. If you do not use the <tt/-P/ option, then these commands use the printer specified in the PRINTER environment variable. Finally, if - you don't have a PRINTER environment variable, these commands + you do not have a PRINTER environment variable, these commands default to the printer named <tt/lp/. Hereafter, the terminology <em/default printer/ means the printer named in the PRINTER environment variable, or the - printer named <tt/lp/ when there's no PRINTER environment + printer named <tt/lp/ when there is no PRINTER environment variable. <sect1><heading>Printing Jobs<label id="printing:lpr"></heading> @@ -1379,7 +1378,7 @@ ls -l | lpr -P rattan <tscreen><verb> lpq -P bamboo </verb></tscreen> - shows the queue for the printer named <tt/bamboo/. Here's + shows the queue for the printer named <tt/bamboo/. Here is an example of the output of the <tt/lpq/ command: <tscreen><verb> bamboo is ready and printing @@ -1392,16 +1391,16 @@ active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes first job, submitted by user kelly, got assigned <em/job number/ 9. Every job for a printer gets a unique job number. Most of the time you can ignore the job number, but - you'll need it if you want to cancel the job; see section + you will need it if you want to cancel the job; see section <ref id="printing:lprm" name="Removing Jobs"> for details. Job number nine consists of two files; multiple files given on the <tt/lpr/ command line are treated as part of a single - job. It's the currently active job (note the word + job. It is the currently active job (note the word <tt/active/ under the ``Rank'' column), which means the printer should be currently printing that job. The second job consists of data passed as the standard input to the - <tt/lpr/ command. The third job came from user mary; it's a + <tt/lpr/ command. The third job came from user mary; it is a much larger job. The pathname of the files she's trying to print is too long to fit, so the <tt/lpq/ command just shows three dots. @@ -1411,7 +1410,7 @@ active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes least what LPD thinks the printer is doing). The <tt/lpq/ command also support a <tt/-l/ option to - generate a detailed long listing. Here's an example of + generate a detailed long listing. Here is an example of <tt/lpq -l/: <tscreen><verb> waiting for bamboo to become ready (offline ?) @@ -1476,7 +1475,7 @@ lprm -P bamboo 10 lprm -P rattan - </verb></tscreen> - <em/Note:/ If you're working in a networked environment, + <em/Note:/ If you are working in a networked environment, <tt/lprm/ will let you remove jobs only from the host from which the jobs were submitted, even if the same printer is available from other hosts. The following command sequence @@ -1509,7 +1508,7 @@ rose% id="printing:lpr:options:format"></heading> <p> The following <tt/lpr/ options control formatting of the - files in the job. Use these options if the job doesn't + files in the job. Use these options if the job does not contain plain text or if you want plain text formatted through the <tt/pr/ utility. @@ -1519,7 +1518,7 @@ rose% <tscreen><verb> lpr -P bamboo -d fish-report.dvi </verb></tscreen> - These options apply to every file in the job, so you can't + These options apply to every file in the job, so you cannot mix (say) DVI and ditroff files together in a job. Instead, submit the files as separate jobs, using a different conversion option for each job. @@ -1546,7 +1545,7 @@ lpr -P bamboo -d fish-report.dvi <it/number/, indent by 8 columns. This option works only with certain conversion filters. - <em/Note:/ Don't put any space between the <tt/-i/ and + <em/Note:/ Do not put any space between the <tt/-i/ and the number. <tag/<tt/-l// @@ -1572,7 +1571,7 @@ lpr -P bamboo -d fish-report.dvi </descrip> - Here's an example: this command prints a nicely + Here is an example: this command prints a nicely formatted version of the <tt/ls/ manual page on the default printer: <tscreen><verb> @@ -1618,26 +1617,26 @@ lpr -#3 parser.c parser.h it will tell you if the job completed successfully or if there was an error, and (often) what the error was. - <tag/-s/ Don't copy the files to the spooling directory, + <tag/-s/ Do not copy the files to the spooling directory, but make symbolic links to them instead. - If you're printing a large job, you probably want to + If you are printing a large job, you probably want to use this option. It saves space in the spooling directory (your job might overflow the free space on the filesystem where the spooling directory resides). - It saves time as well since LPD won't have to copy + It saves time as well since LPD will not have to copy each and every byte of your job to the spooling directory. There is a drawback, though: since LPD will refer to - the original files directly, you can't modify or + the original files directly, you cannot modify or remove them until they have been printed. - <em/Note:/ If you're printing to a remote printer, LPD + <em/Note:/ If you are printing to a remote printer, LPD will eventually have to copy files from the local host to the remote host, so the <tt/-s/ option will save space only on the local spooling directory, not the - remote. It's still useful, though. + remote. It is still useful, though. <tag/-r/ @@ -1668,7 +1667,7 @@ lpr -#3 parser.c parser.h Replace the job name on the header page with <it/text/. The job name is normally the name of the - first file of the job, or ``stdin'' if you're printing + first file of the job, or ``stdin'' if you are printing standard input. <tag/-h/ @@ -1684,7 +1683,7 @@ lpr -#3 parser.c parser.h <sect1><heading>Administrating Printers<label id="printing:lpc"></heading> - <p> As an administrator for your printers, you've had to + <p> As an administrator for your printers, you have had to install, set up, and test them. Using the <tt/lpc/ command, you can interact with your printers in yet more ways. With <tt/lpc/, you can @@ -1698,14 +1697,14 @@ lpr -#3 parser.c parser.h </itemize> First, a note about terminology: if a printer is - <em/stopped/, it won't print anything in its queue. Users + <em/stopped/, it will not print anything in its queue. Users can still submit jobs, which will wait in the queue until the printer is <em/started/ or the queue is cleared. If a queue is <em/disabled/, no user (except root) can submit jobs for the printer. An <em/enabled/ queue allows jobs to be submitted. A printer can be <em/started/ for a - disabled queue, in which case it'll continue to print jobs + disabled queue, in which case it will continue to print jobs in the queue until the queue is empty. In general, you have to have root privileges to use the @@ -1728,10 +1727,10 @@ lpr -#3 parser.c parser.h <tag/<tt/clean <it/printer-name/// Remove old files from the printer's spooling directory. - Occasionally, the files that make up a job aren't + Occasionally, the files that make up a job are not properly removed by LPD, particularly if there have been errors during printing or a lot of administrative - activity. This command finds files that don't belong in + activity. This command finds files that do not belong in the spooling directory and removes them. <tag/<tt/disable <it/printer-name/// @@ -1741,9 +1740,9 @@ lpr -#3 parser.c parser.h queue. The superuser (root) can always submit jobs, even to a disabled queue. - This command is useful while you're testing a new + This command is useful while you are testing a new printer or filter installation: disable the queue and - submit jobs as root. Other users won't be able to + submit jobs as root. Other users will not be able to submit jobs until you complete your testing and re-enable the queue with the <tt/enable/ command. @@ -1757,7 +1756,7 @@ lpr -#3 parser.c parser.h <tag/<tt/enable <it/printer-name/// Enable the queue for a printer. Users can submit jobs - but the printer won't print anything until it's started. + but the printer will not print anything until it is started. <tag/<tt/help <it/command-name/// @@ -1769,7 +1768,7 @@ lpr -#3 parser.c parser.h Start the printer. Ordinary users can use this command if some extraordinary circumstance hangs LPD, but they - can't start a printer stopped with either the <tt/stop/ + cannot start a printer stopped with either the <tt/stop/ or <tt/down/ commands. The <tt/restart/ command is equivalent to <tt/abort/ followed by <tt/start/. @@ -1781,7 +1780,7 @@ lpr -#3 parser.c parser.h <tag/<tt/stop <it/printer-name/// Stop the printer. The printer will finish the current - job and won't print anything else in its queue. Even + job and will not print anything else in its queue. Even though the printer is stopped, users can still submit jobs to an enabled queue. @@ -1790,7 +1789,7 @@ lpr -#3 parser.c parser.h Rearrange the queue for <it/printer-name/ by placing the jobs with the listed <it/job/ numbers or the jobs belonging to <it/username/ at the top of the queue. For - this command, you can't use <tt/all/ as the + this command, you cannot use <tt/all/ as the <it/printer-name/. <tag/<tt/up <it/printer-name/// @@ -1802,7 +1801,7 @@ lpr -#3 parser.c parser.h </descrip> <tt/lpc/ accepts the above commands on the command line. If - you don't enter any commands, <tt/lpc/ enters an interactive + you do not enter any commands, <tt/lpc/ enters an interactive mode, where you can enter commands until you type <tt/exit/, <tt/quit/, or end-of-file. @@ -1832,22 +1831,22 @@ lpr -#3 parser.c parser.h the filter's responsibility to handle these aspects. And the bad news is that most of the time <em/you/ have to provide filters yourself. The good news is that many are generally - available; when they're not, they're usually easy to write. + available; when they are not, they are usually easy to write. Also, FreeBSD comes with one, <tt>/usr/libexec/lpr/lpf</tt>, that works with many printers that can print plain text. (It handles backspacing and tabs in the file, and does - accounting, but that's about all it does.) There are also + accounting, but that is about all it does.) There are also several filters and filter components in the FreeBSD ports collection. - Here's what you'll find in this section: + Here is what you will find in this section: <itemize> <item>Section <ref id="printing:advanced:filters" name="How Fitlers Work">, tries to give an overview of a filter's role in the printing process. You should read - this section to get an understanding of what's happening + this section to get an understanding of what is happening ``under the hood'' when LPD uses filters. This knowledge could help you anticipate and debug problems you might encounter as you install more and more filters @@ -1855,7 +1854,7 @@ lpr -#3 parser.c parser.h <item>LPD expects every printer to be able to print plain text by default. This presents a problem for PostScript - (or other language-based printers) which can't directly + (or other language-based printers) which cannot directly print plain text. Section <ref id="printing:advanced:if-conversion" name="Accommodating Plain Text Jobs on PostScript Printers"> tells you what @@ -1870,7 +1869,7 @@ lpr -#3 parser.c parser.h tells how you can further modify a printer's text filter to accept and print PostScript data on a <em/non-PostScript/ printer. I recommend reading this - section if you don't have a PostScript printer. + section if you do not have a PostScript printer. <item>Section <ref id="printing:advanced:convfilters" name="Conversion Filters"> tells about a way you can @@ -1885,7 +1884,7 @@ lpr -#3 parser.c parser.h <item>Section <ref id="printing:advanced:of" name="Output Filters"> tells all about a not often used feature of - LPD: output filters. Unless you're printing header + LPD: output filters. Unless you are printing header pages (see <ref id="printing:advanced:header-pages" name="Header Pages">), you can probably skip that section altogether. @@ -1915,7 +1914,7 @@ lpr -#3 parser.c parser.h <tt>/dev/console</tt> by default). Which filter LPD starts and the filter's arguments depend - on what's listed in the <tt>/etc/printcap</tt> file and + on what is listed in the <tt>/etc/printcap</tt> file and what arguments the user specified for the job on the <tt/lpr/ command line. For example, if the user typed <tt/lpr -t/, LPD would start the troff filter, listed in @@ -1932,11 +1931,11 @@ lpr -#3 parser.c parser.h <em/input filter/ in LPD documentation, handles regular text printing. Think of it as the default filter. LPD expects every printer to be able to print - plain text by default, and it's the text filter's job + plain text by default, and it is the text filter's job to make sure backspaces, tabs, or other special - characters don't confuse the printer. + characters do not confuse the printer. - If you're in an environment where you have to account + If you are in an environment where you have to account for printer usage, the text filter must also account for pages printed, usually by counting the number of lines printed and comparing that to the number of @@ -1986,7 +1985,7 @@ lpr -#3 parser.c parser.h <item>A <em/conversion filter/ converts a specific file format into one the printer can render onto paper. - For example, ditroff typesetting data can't be + For example, ditroff typesetting data cannot be directly printed, but you can install a conversion filter for ditroff files to convert the ditroff data into a form the printer can digest and print. Section @@ -2004,7 +2003,7 @@ lpr -#3 parser.c parser.h capability (default 0) and <it/pixel-height/ is the value from the <tt/py/ capability (default 0). - <item>The <em/output filter/ is used only if there's no + <item>The <em/output filter/ is used only if there is no text filter, or if header pages are enabled. In my experience, output filters are rarely used. Section <ref id="printing:advanced:of" name="Output Filters"> @@ -2032,7 +2031,7 @@ lpr -#3 parser.c parser.h <tag/exit 2/ - If the filter failed to print the file and doesn't + If the filter failed to print the file and does not want LPD to try again. LPD will throw out the file. </descrip> @@ -2043,7 +2042,7 @@ lpr -#3 parser.c parser.h the login, host, and accounting file arguments to make the accounting entries. - If you're shopping for filters, see if they're + If you are shopping for filters, see if they are LPD-compatible. If they are, they must support the argument lists described above. If you plan on writing filters for general use, then have them support the same @@ -2052,28 +2051,28 @@ lpr -#3 parser.c parser.h <sect2><heading>Accommodating Plain Text Jobs on PostScript Printers <label id="printing:advanced:if-conversion"></heading> - <p> If you're the only user of your computer and PostScript + <p> If you are the only user of your computer and PostScript (or other language-based) printer, and you promise to never send plain text to your printer and to never use features of various programs that will want to send plain - text to your printer, then you don't need to worry about + text to your printer, then you do not need to worry about this section at all. But, if you would like to send both PostScript and plain - text jobs to the printer, then you're urged to augment + text jobs to the printer, then you are urged to augment your printer setup. To do so, we have the text filter detect if the arriving job is plain text or PostScript. All PostScript jobs must start with <tt/%!/ (for other printer languages, see your printer documentation). If those are the first two characters in the job, we have PostScript, and can pass the rest of the job directly. If - those aren't the first two characters in the file, then + those are not the first two characters in the file, then the filter will convert the text into PostScript and print the result. How do we do this? - If you've got a serial printer, a great way to do it is to + If you have got a serial printer, a great way to do it is to install <tt/lprps/. <tt/lprps/ is a PostScript printer filter which performs two-way communication with the printer. It updates the printer's status file with @@ -2090,7 +2089,7 @@ lpr -#3 parser.c parser.h (see <ref id="ports" name="The Ports Collection">); if not, it should be shortly. You can fetch, build and install it yourself, of course. After installing <tt/lprps/, just - specify the pathname to the <tt/psif/ program that's part + specify the pathname to the <tt/psif/ program that is part of <tt/lprps/. If you installed <tt/lprps/ from the ports collection, use the following in the serial PostScript printer's entry in <tt>/etc/printcap</tt>: @@ -2101,7 +2100,7 @@ lpr -#3 parser.c parser.h LPD to open the printer in read-write mode. If you have a parallel PostScript printer (and therefore - can't use two-way communication with the printer, which + cannot use two-way communication with the printer, which <tt/lprps/ needs), you can use the following shell script as the text filter: <code> @@ -2153,16 +2152,16 @@ fi printer. Ghostscript should be in the FreeBSD ports collection, if - you'd like to install it from there. You can fetch, + you would like to install it from there. You can fetch, build, and install it quite easily yourself, as well. To simulate PostScript, we have the text filter detect if - it's printing a PostScript file. If it's not, then the + it is printing a PostScript file. If it is not, then the filter will pass the file directly to the printer; otherwise, it will use Ghostscript to first convert the file into a format the printer will understand. - Here's an example: the following script is a text filter + Here is an example: the following script is a text filter for Hewlett Packard DeskJet 500 printers. For other printers, substitute the <tt/-sDEVICE/ argument to the <tt/gs/ (Ghostscript) command. (Type <tt/gs -h/ to get a @@ -2187,7 +2186,7 @@ first_two_chars=`expr "$first_line" : '\(..\)'` if [ "$first_two_chars" = "%!" ]; then # - # It's PostScript; use Ghostscript to scan-convert and print it + # It is PostScript; use Ghostscript to scan-convert and print it # /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \ &ero;&ero; exit 0 @@ -2207,7 +2206,7 @@ exit 2 <tscreen><verb> :if=/usr/local/libexec/hpif: </verb></tscreen> - That's it. You can type <tt/lpr plain.text/ and <tt/lpr + That is it. You can type <tt/lpr plain.text/ and <tt/lpr whatever.ps/ and both should print successfully. @@ -2216,7 +2215,7 @@ exit 2 <p> After completing the simple setup described in <ref name="Simple Printer Setup" id="printing:simple">, the - first thing you'll probably want to do is install + first thing you will probably want to do is install conversion filters for your favorite file formats (besides plain ASCII text). @@ -2226,7 +2225,7 @@ exit 2 files easy. As an example, suppose we do a lot of work with the TeX typesetting system, and we have a PostScript printer. Every time we generate a DVI file - from TeX, we can't print it directly until we convert + from TeX, we cannot print it directly until we convert the DVI file into PostScript. The command sequence goes like this: <tscreen><verb> @@ -2235,7 +2234,7 @@ lpr seaweed-analysis.ps </verb></tscreen> By installing a conversion filter for DVI files, we can skip the hand conversion step each time by having LPD do - it for us. Now, each time we get a DVI file, we're just + it for us. Now, each time we get a DVI file, we are just one step away from printing it: <tscreen><verb> lpr -d seaweed-analysis.dvi @@ -2259,7 +2258,7 @@ lpr -d seaweed-analysis.dvi <p> You should install the conversion filters you expect to use. If you print a lot of DVI data, then a DVI - conversion filter is in order. If you've got plenty of + conversion filter is in order. If you have got plenty of troff to print out, then you probably want a troff filter. @@ -2289,7 +2288,7 @@ plain text if none, -p, or -l text and plot are probably obsolete. At your site, you can give new meanings to these or any of the formatting options just by installing custom filters. For example, - suppose you'd like to directly print Printerleaf files + suppose you would like to directly print Printerleaf files (files from the Interleaf desktop publishing program), but will never print plot files. You could install a Printerleaf conversion filter under the <tt/gf/ @@ -2302,15 +2301,15 @@ plain text if none, -p, or -l outside of the base FreeBSD installation, they should probably go under <tt>/usr/local</tt>. The directory <tt>/usr/local/libexec</tt> is a popular location, since - they they're specialized programs that only LPD will - run; regular users shouldn't ever need to run them. + they they are specialized programs that only LPD will + run; regular users should not ever need to run them. To enable a conversion filter, specify its pathname under the appropriate capability for the destination printer in <tt>/etc/printcap</tt>. - In our example, we'll add the DVI conversion filter to - the entry for the printer named <tt/bamboo/. Here's the + In our example, we will add the DVI conversion filter to + the entry for the printer named <tt/bamboo/. Here is the example <tt>/etc/printcap</tt> file again, with the new <tt/df/ capability for the printer <tt/bamboo/ <code> @@ -2329,7 +2328,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :df=/usr/local/libexec/psdf: </code> The DVI filter is a shell script named - <tt>/usr/local/libexec/psdf</tt>. Here's that script: + <tt>/usr/local/libexec/psdf</tt>. Here is that script: <code> #!bin/sh # @@ -2351,7 +2350,7 @@ exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@" <sect3><heading>More Conversion Filter Examples</heading> - <p> Since there's no fixed set of steps to install + <p> Since there is no fixed set of steps to install conversion filters, let me instead provide more examples. Use these as guidance to making your own filters. Use them directly, if appropriate. @@ -2376,7 +2375,7 @@ giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ converting that into a portable bitmap, and converting that into LaserJet/PCL-compatible data. - Here's the <tt>/etc/printcap</tt> file with an entry for + Here is the <tt>/etc/printcap</tt> file with an entry for a printer using the above filter: <code> # @@ -2401,7 +2400,7 @@ exec grops | /usr/local/libexec/lprps "$@" </code> The above script makes use of <tt/lprps/ again to handle the communication with the printer. If the printer were - on a parallel port, we'd use this script instead: + on a parallel port, we would use this script instead: <code> #!/bin/sh # @@ -2410,15 +2409,15 @@ exec grops | /usr/local/libexec/lprps "$@" # exec grops </code> - That's it. Here's the entry we need to add to + That is it. Here is the entry we need to add to <tt>/etc/printcap</tt> to enable the filter: <tscreen><verb> :tf=/usr/local/libexec/pstf: </verb></tscreen> - Here's an example that might make old hands at FORTRAN - blush. It's a FORTRAN-text filter for any printer that - can directly print plain text. We'll install it for the + Here is an example that might make old hands at FORTRAN + blush. It is a FORTRAN-text filter for any printer that + can directly print plain text. We will install it for the printer <tt/teak/: <code> #!/bin/sh @@ -2430,13 +2429,13 @@ exec grops printf "\033&ero;k2G" &ero;&ero; fpr &ero;&ero; printf "\f" &ero;&ero; exit 0 exit 2 </code> - And we'll add this line to the <tt>/etc/printcap</tt> + And we will add this line to the <tt>/etc/printcap</tt> for the printer <tt/teak/ to enable this filter: <tscreen><verb> :rf=/usr/local/libexec/hprf: </verb></tscreen> - Here's one final, somewhat complex example. We'll add a + Here is one final, somewhat complex example. We will add a DVI filter to the LaserJet printer <tt/teak/ introduced earlier. First, the easy part: updating <tt>/etc/printcap</tt> with the location of the DVI @@ -2455,8 +2454,8 @@ exit 2 codes. <tt/dvilj2p/ makes the filter <tt/hpdf/ quite complex - since <tt/dvilj2p/ can't read from standard input. It - wants to work with a filename. What's worse, the + since <tt/dvilj2p/ cannot read from standard input. It + wants to work with a filename. What iss worse, the filename has to end in <tt/.dvi/ so using <tt>/dev/fd/0</tt> for standard input is problematic. We can get around that problem by linking (symbolically) @@ -2465,18 +2464,18 @@ exit 2 from standard input. The only other fly in the ointment is the fact that we - can't use /tmp for the temporary link. Symbolic links + cannot use /tmp for the temporary link. Symbolic links are owned by user and group <tt/bin/. The filter runs as user <tt/daemon/. And the <tt>/tmp</tt> directory has the sticky bit set. The filter can create the link, - but it won't be able clean up when done and remove it + but it will not be able clean up when done and remove it since the link will belong to a different user. Instead, the filter will make the symbolic link in the current working directory, which is the spooling directory (specified by the <tt/sd/ capability in <tt>/etc/printcap</tt>). This is a perfect place for - filters to do their work, especially since there's + filters to do their work, especially since there is (sometimes) more free disk space in the spooling directory than under <tt>/tmp</tt>. @@ -2500,7 +2499,7 @@ cleanup() { # # Define a function to handle fatal errors: print the given message -# and exit 2. Exiting with 2 tells LPD to don't try to reprint the +# and exit 2. Exiting with 2 tells LPD to do not try to reprint the # job. # fatal() { @@ -2516,7 +2515,7 @@ fatal() { trap cleanup 1 2 15 # -# Make sure we're not colliding with any existing files. +# Make sure we are not colliding with any existing files. # cleanup @@ -2531,7 +2530,7 @@ ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" printf "\033&ero;k2G" || fatal "Cannot initialize printer" # -# Convert and print. Return value from dvilj2p doesn't seem to be +# Convert and print. Return value from dvilj2p does not seem to be # reliable, so we ignore it. # dvilj2p -M1 -q -e- dfhp$$.dvi @@ -2549,19 +2548,19 @@ exit 0 <p> All these conversion filters accomplish a lot for your printing environment, but at the cost forcing the user to specify (on the <tt/lpr/ command line) which one to - use. If your users aren't particularly computer + use. If your users are not particularly computer literate, having to specify a filter option will become - annoying. What's worse, though, is that an incorrectly + annoying. What is worse, though, is that an incorrectly specified filter option may run a filter on the wrong type of file and cause your printer to spew out hundreds of sheets of paper. Rather than install conversion filters at all, you might - want to try having the text filter (since it's the - default filter) detect the type of file it's asked to + want to try having the text filter (since it is the + default filter) detect the type of file it has been asked to print and then automatically run the right conversion filter. Tools such as <tt/file/ can be of help here. - Of course, it'll be hard to determine the differences + Of course, it will be hard to determine the differences between <em/some/ file types---and, of course, you can still provide conversion filters just for them. @@ -2574,20 +2573,20 @@ exit 0 id="printing:advanced:of"></heading> <p> The LPD spooling system supports one other type of - filter that we've not yet explored: an output filter. An + filter that we have not yet explored: an output filter. An output filter is intended for printing plain text only, like the text filter, but with many simplifications. If - you're using an output filter but no text filter, then + you are using an output filter but no text filter, then <itemize> <item>LPD starts an output filter once for the entire job instead of once for each file in the job. - <item>LPD doesn't make any provision to identify the + <item>LPD does not make any provision to identify the start or the end of files within the job for the output filter. - <item>LPD doesn't pass the user's login or host to - the filter, so it's not intended to do accounting. In + <item>LPD does not pass the user's login or host to + the filter, so it is not intended to do accounting. In fact, it gets only two arguments: <tscreen> <tt>-w<it/width/ -l<it/length/</tt> @@ -2597,9 +2596,9 @@ exit 0 printer in question. </itemize> - Don't be seduced by an output filter's simplicity. If - you'd like each file in a job to start on a different page - an output filter <em/won't work/. Use a text filter (also + Do not be seduced by an output filter's simplicity. If + you would like each file in a job to start on a different page + an output filter <em/will not work/. Use a text filter (also known as an input filter); see section <ref id="printing:textfilter" name="Installing the Text Filter">. Furthermore, an output filter is actually @@ -2610,9 +2609,9 @@ exit 0 However, an output filter is <em/necessary/ if you want header pages and need to send escape sequences or other initialization strings to be able to print the header - page. (But it's also <em/futile/ if you want to charge + page. (But it is also <em/futile/ if you want to charge header pages to the requesting user's account, since LPD - doesn't give any user or host information to the output + does not give any user or host information to the output filter.) On a single printer, LPD allows both an output filter and @@ -2623,10 +2622,10 @@ exit 0 itself/ by sending two bytes to the filter: ASCII 031 followed by ASCII 001. When an output filter sees these two bytes (031, 001), it should stop by sending SIGSTOP to - itself. When LPD's done running other filters, it'll + itself. When LPD's done running other filters, it will restart the output filter by sending SIGCONT to it. - If there's an output filter but <em/no/ text filter and + If there is an output filter but <em/no/ text filter and LPD is working on a plain text job, LPD uses the output filter to do the job. As stated before, the output filter will print each file of the job in sequence with no @@ -2636,7 +2635,7 @@ exit 0 The program <tt/lpf/, which we introduced earlier as a text filter, can also run as an output filter. If you need a - quick-and-dirty output filter but don't want to write the + quick-and-dirty output filter but do not want to write the byte detection and signal sending code, try <tt/lpf/. You can also wrap <tt/lpf/ in a shell script to handle any initialization codes the printer might require. @@ -2654,7 +2653,7 @@ exit 0 <tt/lpf/ is suitable for many printing environments. And although it has no capability to send initialization - sequences to a printer, it's easy to write a shell script + sequences to a printer, it is easy to write a shell script to do the needed initialization and then execute <tt/lpf/. In order for <tt/lpf/ to do page accounting correctly, it @@ -2669,17 +2668,17 @@ exit 0 <sect1><heading>Header Pages<label id="printing:advanced:header-pages"></heading> - <p> If you've got <em/lots/ of users, all of them using + <p> If you have <em/lots/ of users, all of them using various printers, then you probably want to consider <em/header pages/ as a necessary evil. Header pages, also known as <em/banner/ or <em/burst pages/ - identify to whom jobs belong after they're printed. They're + identify to whom jobs belong after they are printed. They are usually printed in large, bold letters, perhaps with decorative borders, so that in a stack of printouts they stand out from the real documents that comprise users' jobs. They enable users to locate their jobs quickly. The obvious - drawback to a header page is that it's yet one more sheet + drawback to a header page is that it is yet one more sheet that has to be printed for every job, their ephemeral usefulness lasting not more than a few minutes, ultimately finding themselves in a recycling bin or rubbish heap. @@ -2688,7 +2687,7 @@ exit 0 The LPD system can provide header pages automatically for your printouts <em/if/ your printer can directly print plain - text. If you've got a PostScript printer, you'll need an + text. If you have a PostScript printer, you will need an external program to generate the header page; see <ref id="printing:advanced:header-pages:ps" name="Header Pages on PostScript Printers">. @@ -2704,9 +2703,9 @@ exit 0 Sounds too easy, right? - You're right. You <em/might/ have to provide an output + You are right. You <em/might/ have to provide an output filter to send initialization strings to the printer. - Here's an example output filter for Hewlett Packard + Here is an example output filter for Hewlett Packard PCL-compatible printers: <code> #!/bin/sh @@ -2722,7 +2721,7 @@ exec /usr/libexec/lpr/lpf capability. See <ref id="printing:advanced:of" name="Output Filters"> for more information. - Here's an example <tt>/etc/printcap</tt> file for the printer + Here is an example <tt>/etc/printcap</tt> file for the printer <tt/teak/ that we introduced earlier; we enabled header pages and added the above output filter: <code> @@ -2752,7 +2751,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ <p> By enabling header pages, LPD will produce a <em/long header/, a full page of large letters identifying the - user, host, and job. Here's an example (kelly printed + user, host, and job. Here is an example (kelly printed the job named outline from host rose): <tscreen><verb> k ll ll @@ -2804,7 +2803,7 @@ r oooo ssss eeee Date: Sun Sep 17 11:04:58 1995 </verb></tscreen> LPD appends a form feed after this text so the job starts - on a new page (unless you've got <tt/sf/ (suppress form + on a new page (unless you have <tt/sf/ (suppress form feeds) in the destination printer's entry in <tt>/etc/printcap</tt>). @@ -2829,18 +2828,18 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 Because the output filter is the only external program that will have control when the header page is printed - that could do accounting, and it isn't provided with any + that could do accounting, and it is not provided with any <em/user or host/ information or an accounting file, so it - has no idea whom to charge for printer use. It's also not + has no idea whom to charge for printer use. It is also not enough to just ``add one page'' to the text filter or any of the conversion filters (which do have user and host information) since users can suppress header pages with <tt/lpr -h/. They could still be charged for header pages - they didn't print. Basically, <tt/lpr -h/ will be the + they did not print. Basically, <tt/lpr -h/ will be the preferred option of environmentally-minded users, but you - can't offer any incentive to use it. + cannot offer any incentive to use it. - It's <em/still not enough/ to have each of the filters + It is <em/still not enough/ to have each of the filters generate their own header pages (thereby being able to charge for them). If users wanted the option of suppressing the header pages with <tt/lpr -h/, they will @@ -2861,10 +2860,10 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 LPD. <item>Write a <em/smart/ output filter. Normally, an - output filter isn't meant to do anything more than + output filter is not meant to do anything more than initialize a printer or do some simple character - conversion. It's suited for header pages and plain - text jobs (when there's no text (input) filter). + conversion. It is suited for header pages and plain + text jobs (when there is no text (input) filter). But, if there is a text filter for the plain text jobs, then LPD will start the output filter only for @@ -2872,8 +2871,8 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 header page text that LPD generates to determine what user and host to charge for the header page. The only other problem with this method is that the output - filter still doesn't know what accounting file to use - (it's not passed the name of the file from the <tt/af/ + filter still does not know what accounting file to use + (it is not passed the name of the file from the <tt/af/ capability), but if you have a well-known accounting file, you can hard-code that into the output filter. @@ -2890,7 +2889,7 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 <p> As described above, LPD can generate a plain text header page suitable for many printers. Of course, PostScript - can't directly print plain text, so the header page + cannot directly print plain text, so the header page feature of LPD is useless---or mostly so. One obvious way to get header pages is to have every @@ -2900,7 +2899,7 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 drawback of this method is that users will always get a header page, even if they submit jobs with <tt/lpr -h/. - Let's explore this method. The following script takes + Let us explore this method. The following script takes three arguments (user login name, host name, and job name) and makes a simple PostScript header page: <code> @@ -2912,7 +2911,7 @@ rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 # # These are PostScript units (72 to the inch). Modify for A4 or -# whatever size paper you're using: +# whatever size paper you are using: # page_width=612 page_height=792 @@ -2941,7 +2940,7 @@ exec cat <<EOF %!PS % -% Make sure we don't interfere with user's job that will follow +% Make sure we do not interfere with user's job that will follow % save @@ -2978,7 +2977,7 @@ $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto } forall % -% That's it +% That is it % restore showpage @@ -2986,7 +2985,7 @@ EOF </code> Now, each of the conversion filters and the text filter can call this script to first generate the header page, - and then print the user's job. Here's the DVI conversion + and then print the user's job. Here is the DVI conversion filter from earlier in this document, modified to make a header page: <code> @@ -3029,29 +3028,29 @@ done (see section <ref id="printing:advanced:filters" name="How Filters Work">). - As we've mentioned before, the above scheme, though fairly + As we have mentioned before, the above scheme, though fairly simple, disables the ``suppress header page'' option (the <tt/-h/ option) to <tt/lpr/. If users wanted to save a tree (or a few pennies, if you charge for header pages), - they wouldn't be able to do so, since every filter's going + they would not be able to do so, since every filter's going to print a header page with every job. To allow users to shut off header pages on a per-job - basis, you'll need to use the trick introduced in section + basis, you will need to use the trick introduced in section <ref id="printing:advanced:header-pages:accounting" name="Accounting for Header Pages">: write an output filter that parses the LPD-generated header page and produces a PostScript version. If the user submits the - job with <tt/lpr -h/, then LPD won't generate a header + job with <tt/lpr -h/, then LPD will not generate a header page, and neither will your output filter. Otherwise, your output filter will read the text from LPD and send the appropriate header page PostScript code to the printer. - If you've got a PostScript printer on a serial line, you + If you have a PostScript printer on a serial line, you can make use of <tt/lprps/, which comes with an output filter, <tt/psof/, which does the above. Note that - <tt/psof/ doesn't charge for header pages. + <tt/psof/ does not charge for header pages. <sect1><heading>Networked Printing<label id="printing:advanced:network-printers"></heading> @@ -3110,9 +3109,9 @@ done advanced setup in <ref id="printing:advanced" name="Advanced Printer Setup"> that you need. Make sure to test the printer and see if it works with the features - of LPD you've enabled. + of LPD you have enabled. - If you're using a printer with a network interface that's + If you are using a printer with a network interface that is compatible with LPD, then the <em/printer host/ in the discussion below is the printer itself, and the <em/printer name/ is the name you configured for the @@ -3140,17 +3139,17 @@ done <item>Place the printer name on the <em/printer host/ in the <tt/rp/ capability. </enum> - That's it. You don't need to list conversion filters, + That is it. You do not need to list conversion filters, page dimensions, or anything else in the <tt>/etc/printcap</tt> file. - Here's an example. The host rose has two printers, - <tt/bamboo/ and <tt/rattan/. We'll enable users on the - host orchid to print to those printers. Here's the + Here is an example. The host rose has two printers, + <tt/bamboo/ and <tt/rattan/. We will enable users on the + host orchid to print to those printers. Here is the <tt>/etc/printcap</tt> file for orchid (back from section <ref id="printing:advanced:header-pages:enabling" name="Enabling Header Pages">). It already had the entry - for the printer <tt/teak/; we've added entries for the two + for the printer <tt/teak/; we have added entries for the two printers on the host rose: <code> # @@ -3158,7 +3157,7 @@ done # # -# teak is local; it's connected directly to orchid: +# teak is local; it is connected directly to orchid: # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ @@ -3208,20 +3207,20 @@ lpr -P bamboo -d sushi-review.dvi lets you send data to it as if you were using a serial or parallel port (the cheaper version). This section tells how to use the cheaper version. For the more expensive - version, see the previous section <ref name="Printers + one, see the previous section <ref name="Printers Installed on Remote Hosts" id="printing:advanced:network:rm">. The format of the <tt>/etc/printcap</tt> file lets you specify what serial or parallel interface to use, and (if - you're using a serial interface), what baud rate, whether + you are using a serial interface), what baud rate, whether to use flow control, delays for tabs, conversion of - newlines, and more. But there's no way to specify a - connection to a printer that's listening on a TCP/IP or + newlines, and more. But there is no way to specify a + connection to a printer that is listening on a TCP/IP or other network port. To send data to a networked printer, you need to develop a communications program that can be called by the text and - conversion filters. Here's one such example: the script + conversion filters. Here is one such example: the script <tt/netprint/ takes all data on standard input and sends it to a network-attached printer. We specify the hostname of the printer as the first argument and the port number @@ -3260,7 +3259,7 @@ exit 0; We can then use this script in various filters. Suppose we had a Diablo 750-N line printer connected to the network. The printer accepts data to print on port number - 5100. The host name of the printer is scrivener. Here's + 5100. The host name of the printer is scrivener. Here is the text filter for the printer: <code> #!/bin/sh @@ -3294,22 +3293,22 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100 tear on your printers, you can disable the <tt/-#/ option to <tt/lpr/ by adding the <tt/sc/ capability to the <tt>/etc/printcap</tt> file. When users submit jobs - with the <tt/-#/ option, they'll see + with the <tt/-#/ option, they will see <tscreen><verb> lpr: multiple copies are not allowed </verb></tscreen> - Note that if you've set up access to a printer remotely + Note that if you have set up access to a printer remotely (see section <ref name="Printers Installed on Remote Hosts" id="printing:advanced:network:rm">), you need the <tt/sc/ capability on the remote <tt>/etc/printcap</tt> files as well, or else users will still be able to submit multiple-copy jobs by using another host. - Here's an example. This is the <tt>/etc/printcap</tt> + Here is an example. This is the <tt>/etc/printcap</tt> file for the host rose. The printer <tt/rattan/ is quite - hearty, so we'll allow multiple copies, but the laser - printer <tt/bamboo/'s a bit more delicate, so we'll + hearty, so we will allow multiple copies, but the laser + printer <tt/bamboo/'s a bit more delicate, so we will disable multiple copies by adding the <tt/sc/ capability: <code> # @@ -3327,8 +3326,8 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :df=/usr/local/libexec/psdf: </code> Now, we also need to add the <tt/sc/ capability on the - host orchid's <tt>/etc/printcap</tt> (and while we're at - it, let's disable multiple copies for the printer + host orchid's <tt>/etc/printcap</tt> (and while we are at + it, let us disable multiple copies for the printer <tt/teak/): <code> # @@ -3348,7 +3347,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc: </code> By using the <tt/sc/ capability, we prevent the use of - <tt/lpr -#/, but that still doesn't prevent users from + <tt/lpr -#/, but that still does not prevent users from running <tt/lpr/ multiple times, or from submitting the same file multiple times in one job like this: <tscreen><verb> @@ -3375,13 +3374,13 @@ lpr: Not a member of the restricted group As with the <tt/sc/ (suppress multiple copies) capability, you need to specify <tt/rg/ on remote hosts that also have - access to your printers, if you feel it's appropriate (see + access to your printers, if you feel it is appropriate (see section <ref name="Printers Installed on Remote Hosts" id="printing:advanced:network:rm">). - For example, we'll let anyone access the printer + For example, we will let anyone access the printer <tt/rattan/, but only those in group <tt/artists/ can use - <tt/bamboo/. Here's the familiar <tt>/etc/printcap</tt> + <tt/bamboo/. Here is the familiar <tt>/etc/printcap</tt> for host rose: <code> # @@ -3398,7 +3397,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: </code> - Let's leave the other example <tt>/etc/printcap</tt> file + Let us leave the other example <tt>/etc/printcap</tt> file (for the host orchid) alone. Of course, anyone on orchid can print to <tt/bamboo/. It might be the case that we only allow certain logins on orchid anyway, and want them @@ -3412,27 +3411,27 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <p> If you have many users accessing the printers, you probably need to put an upper limit on the sizes of the - files users can submit to print. After all, there's only + files users can submit to print. After all, there is only so much free space on the filesystem that houses the spooling directories, and you also need to make sure - there's room for the jobs of other users. + there is room for the jobs of other users. LPD enables you to limit the maximum byte size a file in a job can be with the <tt/mx/ capability. The units are in BUFSIZ blocks, which are 1024 bytes. If you put a zero - for this capability, there'll be no limit on file size. + for this capability, there will be no limit on file size. Note that the limit applies to <em/files/ in a job, and <em/not/ the total job size. - LPD won't refuse a file that's larger than the limit you - place on a printer. Instead, it'll queue as much of the + LPD will not refuse a file that is larger than the limit you + place on a printer. Instead, it will queue as much of the file up to the limit, which will then get printed. The rest will be discarded. Whether this is correct behavior is up for debate. - Let's add limits to our example printers <tt/rattan/ and + Let us add limits to our example printers <tt/rattan/ and <tt/bamboo/. Since those artists' PostScript files tend - to be large, we'll limit them to five megabytes. We'll + to be large, we will limit them to five megabytes. We will put no limit on the plain text line printer: <code> # @@ -3457,14 +3456,14 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :df=/usr/local/libexec/psdf: </code> Again, the limits apply to the local users only. If - you've set up access to your printers remotely, remote - users won't get those limits. You'll need to specify the + you have set up access to your printers remotely, remote + users will not get those limits. You will need to specify the <tt/mx/ capability in the remote <tt>/etc/printcap</tt> files as well. See section <ref name="Printers Installed on Remote Hosts" id="printing:advanced:network:rm"> for more information on remote printing. - There's another specialized way to limit job sizes from + There is another specialized way to limit job sizes from remote printers; see section <ref id="printing:advanced:restricting:remote" name="Restricting Jobs from Remote Printers">. @@ -3490,7 +3489,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ also used by the ruserok(3) protocol, and affects programs like <tt/rsh/ and <tt/rcp/, so be careful. - For example, here's the <tt>/etc/hosts.lpd</tt> file + For example, here is the <tt>/etc/hosts.lpd</tt> file on the host rose: <code> orchid @@ -3512,16 +3511,16 @@ madrigal.fishbaum.de (512 bytes) of free space there has to be for a remote job to be accepted. - This lets you insure that remote users won't fill your + This lets you insure that remote users will not fill your filesystem. You can also use it to give a certain - priority to local users: they'll be able to queue jobs + priority to local users: they will be able to queue jobs long after the free disk space has fallen below the amount specified in the <tt/minfree/ file. - For example, let's add a <tt/minfree/ file for the + For example, let us add a <tt/minfree/ file for the printer <tt/bamboo/. We examine <tt>/etc/printcap</tt> to find the spooling directory - for this printer; here's <tt/bamboo/'s entry: + for this printer; here is <tt/bamboo/'s entry: <tscreen><verb> bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ @@ -3530,7 +3529,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :df=/usr/local/libexec/psdf: </verb></tscreen> The spooling directory is the given in the <tt/sd/ - capability. We'll make three megabytes (which is 6144 + capability. We will make three megabytes (which is 6144 disk blocks) the amount of free disk space that must exist on the filesystem for LPD to accept remote jobs: <tscreen><verb> @@ -3551,7 +3550,7 @@ echo 6144 > /var/spool/lpd/bamboo/minfree departments sharing a network, and some users transcend departmental boundaries. By giving them accounts on your systems, they can use your printers - from their own departmental systems. If you'd rather + from their own departmental systems. If you would rather allow them to use <em/only/ your printers and not your compute resources, you can give them ``token'' accounts, with no home directory and a useless shell @@ -3564,12 +3563,12 @@ echo 6144 > /var/spool/lpd/bamboo/minfree <p> So, you need to charge for printouts. And why not? Paper and ink cost money. And then there are maintenance costs---printers are loaded with moving parts and tend to - break down. You've examined your printers, usage patterns, + break down. You have examined your printers, usage patterns, and maintenance fees and have come up with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, how do you actually start accounting for printouts? - Well, the bad news is the LPD spooling system doesn't + Well, the bad news is the LPD spooling system does not provide much help in this department. Accounting is highly dependent on the kind of printer in use, the formats being printed, and <em/your/ requirements in charging for printer @@ -3578,7 +3577,7 @@ echo 6144 > /var/spool/lpd/bamboo/minfree To implement accounting, you have to modify a printer's text filter (to charge for plain text jobs) and the conversion filters (to charge for other file formats), to count pages - or query the printer for pages printed. You can't get away + or query the printer for pages printed. You cannot get away with using the simple output filter, since it cannot do accounting. See section <ref name="Filters" id="printing:advanced:filter-intro">. @@ -3586,7 +3585,7 @@ echo 6144 > /var/spool/lpd/bamboo/minfree Generally, there are two ways to do accounting: <itemize> <item><em/Periodic accounting/ is the more common way, - possibly because it's easier. Whenever someone prints a + possibly because it is easier. Whenever someone prints a job, the filter logs the user, host, and number of pages to an accounting file. Every month, semester, year, or whatever time period you prefer, you collect the @@ -3596,7 +3595,7 @@ echo 6144 > /var/spool/lpd/bamboo/minfree slate for the next period. <item><em/Timely accounting/ is less common, probably - because it's more difficult. This method has the + because it is more difficult. This method has the filters charge users for printouts as soon as they use the printers. Like disk quotas, the accounting is immediate. You can prevent users from printing when @@ -3658,10 +3657,10 @@ echo 6144 > /var/spool/lpd/bamboo/minfree Then, each accounting file will be in the spooling directory for a printer, in a file named <tt/acct/. - When you're ready to charge users for printouts, run the + When you are ready to charge users for printouts, run the <tt/pac/ program. Just change to the spooling directory for the printer you want to collect on and type <tt/pac/. - You'll get a dollar-centric summary like the following: + You will get a dollar-centric summary like the following: <code> Login pages/feet runs price orchid:kelly 5.00 1 $ 0.10 @@ -3679,7 +3678,7 @@ total 337.00 154 $ 6.74 <tag/<tt/-P<it/printer/// Which <it/printer/ to summarize. This option works - only if there's an absolute path in the <tt/af/ + only if there is an absolute path in the <tt/af/ capability in <tt>/etc/printcap</tt>. <tag/<tt/-c// @@ -3691,7 +3690,7 @@ total 337.00 154 $ 6.74 Ignore host name in the accounting files. With this option, user smith on host alpha is the same user - smith on host gamma. Without, they're different users. + smith on host gamma. Without, they are different users. <tag/<tt/-p<it/price/// @@ -3718,7 +3717,7 @@ total 337.00 154 $ 6.74 In the default summary that <tt/pac/ produces, you see the number of pages printed by each user from various hosts. - If, at your site, host doesn't matter (because users can + If, at your site, host does not matter (because users can use any host), run <tt/pac -m/, to produce the following summary: <code> @@ -3763,7 +3762,7 @@ pac -p1.50 For plain text jobs, the problem's not that hard to solve: you count how many lines are in a job and compare it to - how many lines per page your printer supports. Don't + how many lines per page your printer supports. Do not forget to take into account backspaces in the file which overprint lines, or long logical lines that wrap onto one or more additional physical lines. @@ -3771,7 +3770,7 @@ pac -p1.50 The text filter <tt/lpf/ (introduced in <ref id="printing:advanced:lpf" name="lpf: a Text Filter">) takes into account these things when it does accounting. - If you're writing a text filter which needs to do + If you are writing a text filter which needs to do accounting, you might want to examine <tt/lpf/'s source code. @@ -3798,7 +3797,7 @@ pac -p1.50 (networked Imagen laser printers, for example). Modify the filters for these printers to get the page usage after they print each job and have them log accounting - information based on that value <em/only/. There's no + information based on that value <em/only/. There is no line counting nor error-prone file examination required. Of course, you can always be generous and make all @@ -3807,15 +3806,15 @@ pac -p1.50 <sect><heading>Alternatives to the Standard Spooler<label id="printing:lpd-alternatives"></heading> - <p> If you've been reading straight through this manual, by now - you've learned just about everything there is to know about + <p> If you have been reading straight through this manual, by now + you have learned just about everything there is to know about the LPD spooling system that comes with FreeBSD. You can probably appreciate many of its shortcomings, which naturally leads to the question: ``What other spooling systems are out there (and work with FreeBSD)?'' - Unfortunately, I've located only <em/two/ alternatives---and - they're almost identical to each other! They are + Unfortunately, I have located only <em/two/ alternatives---and + they are almost identical to each other! They are: <descrip> <tag/PLP, the Portable Line Printer Spooler System/ @@ -3823,11 +3822,11 @@ pac -p1.50 then maintained by an Internet-wide group of developers. The main site for the software is at <htmlurl url="ftp://ftp.iona.ie/pub/plp" - name="ftp://ftp.iona.ie/pub/plp">. There's also a <htmlurl + name="ftp://ftp.iona.ie/pub/plp">. There is also a <htmlurl url="http://www.iona.ie:8000/www/hyplan/jmason/plp.html" name="web page">. - It's quite similar to the BSD LPD spooler, but boasts a + It is quite similar to the BSD LPD spooler, but boasts a host of features, including: <itemize> <item>Better network support, including built-in support @@ -3858,7 +3857,7 @@ pac -p1.50 <sect><heading>Acknowledgments</heading> - <p> I'd like to thank the following people who have assisted in + <p> I would like to thank the following people who have assisted in the development of this document: <descrip> diff --git a/handbook/relnotes.sgml b/handbook/relnotes.sgml index 1eef6cc562..a6ea3759dc 100644 --- a/handbook/relnotes.sgml +++ b/handbook/relnotes.sgml @@ -1,11 +1,11 @@ -<!-- $Id: relnotes.sgml,v 1.4.2.5 1996-01-31 14:32:28 mpp Exp $ --> +<!-- $Id: relnotes.sgml,v 1.4.2.6 1996-06-19 20:28:14 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> <linuxdoc><book><chapt>foo --> - <sect><heading>About this release<label id="relnotes"></heading> + <sect><heading>About the current release<label id="relnotes"></heading> <p>FreeBSD is a freely available, full source 4.4 BSD Lite based release for Intel i386/i486/Pentium (or @@ -28,7 +28,7 @@ the Adaptec 2940 (WIDE and narrow) and many hundreds of bug fixes. - We've also taken the comments and suggestions of many + We have also taken the comments and suggestions of many of our users to heart and have attempted to provide what we hope is a more sane and easily understood installation process. Your feedback on this @@ -57,7 +57,8 @@ A number of additional documents which you may find very helpful in the process of installing and using FreeBSD may now also be found in the - <bf>/usr/share/doc</bf> directory. You may view the + <bf>/usr/share/doc</bf> directory on any machine running + FreeBSD 2.1 or later. You may view the manuals with any HTML capable browser with the following URLs: @@ -92,7 +93,7 @@ security may be all you require! We feel that our default security model is more than a match for DES, and without any messy export issues to deal with. If - you're outside (or even inside) the U.S., give it a + you are outside (or even inside) the U.S., give it a try! <![ IGNORE [ @@ -119,7 +120,7 @@ Ethernet adapters, improved support for the Adaptec 2940 and hundreds of bug fixes. - We've also taken the comments and suggestions of many + We have also taken the comments and suggestions of many of our users to heart and have attempted to provide what we hope is a more sane and easily understood installation process. Your feedback on this constantly @@ -523,7 +524,7 @@ <tag>UNIONFS and LFS</tag> The unionfs and LFS file systems are known to be severely broken in FreeBSD 2.0.5. This is in part due to old bugs that we - haven't had time to resolve yet and the need to + have not had time to resolve yet and the need to update these file systems to deal with the new VM system. We hope to address these issues in a later release of FreeBSD. @@ -539,7 +540,7 @@ way for ELF and XOUT loaders, and most of the svr4 syscall wrappers are written. - Owner: Soren Schmidt (sos) and Sean Eric Fagan (sef) + Owner: Søren Schmidt (sos) and Sean Eric Fagan (sef) Sources involved: <tt>sys/i386/ibcs2/*</tt> and misc kernel changes. @@ -556,7 +557,7 @@ The preferred method to submit bug reports from a machine with Internet mail connectivity is to use the send-pr command. Bug reports will be dutifully filed by our - faithful bug-filer program and you can be sure that we'll + faithful bug-filer program and you can be sure that we will do our best to respond to all reported bugs as soon as possible. @@ -580,8 +581,8 @@ subscribe to: <tscreen>announce@FreeBSD.org</tscreen> All but the freebsd-bugs groups can be freely joined by - anyone wishing to do so. Send mail to - MajorDomo@FreeBSD.org and include the keyword `help' on a + anyone wishing to do so. Send mail to &a.majordomo + and include the keyword `help' on a line by itself somewhere in the body of the message. This will give you more information on joining the various lists, accessing archives, etc. There are a diff --git a/handbook/routing.sgml b/handbook/routing.sgml index 30067d5a1f..3eba5d6d24 100644 --- a/handbook/routing.sgml +++ b/handbook/routing.sgml @@ -1,4 +1,4 @@ -<!-- $Id: routing.sgml,v 1.1.2.1 1996-01-31 14:32:28 mpp Exp $ --> +<!-- $Id: routing.sgml,v 1.1.2.2 1996-06-19 20:28:16 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> --> @@ -68,7 +68,7 @@ host2.foobar.com link#1 UC 0 0 (<tt>10.20.30.255</tt> is the broadcast address for the subnet <tt>10.20.30</tt>, and <tt>foobar.com</tt> is the domain name associated with that subnet). The designation <tt>link#1</tt> - refers to the first ethernet card in the machine. You'll + refers to the first ethernet card in the machine. You will notice no additional interface is specified for those. Both of these groups (local network hosts and local @@ -150,7 +150,7 @@ host2.foobar.com link#1 UC 0 0 world, then the default route will be the gateway machine at your Internet Service Provider's (ISP) site. - Let's look at an example of default routes. This is a + Let us look at an example of default routes. This is a common configuration: <tscreen><verb> [Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] diff --git a/handbook/scsi.sgml b/handbook/scsi.sgml index 9713c9e4a8..b564a54ecc 100644 --- a/handbook/scsi.sgml +++ b/handbook/scsi.sgml @@ -1,4 +1,4 @@ -<!-- $Id: scsi.sgml,v 1.1.1.1.4.4 1996-01-31 14:32:29 mpp Exp $ --> +<!-- $Id: scsi.sgml,v 1.1.1.1.4.5 1996-06-19 20:28:17 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- @@ -13,7 +13,7 @@ </abstract> --> - <sect><heading>SCSI<label id="scsi"></heading> + <sect1><heading>What is SCSI?<label id="scsi"></heading> <p><em>Copyright © 1995, &a.wilko;.<newline>3 September 1995.</em> @@ -42,8 +42,8 @@ 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 + single-ended signals, carried on 50 wires. (If you do not know what + single-ended means, do not worry, that is what this document is all about.) Modern designs also use 16 bit wide buses, with differential signals. This allows transfer speeds of 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 @@ -67,29 +67,29 @@ Elaborate caching schemes, automatic bad block replacement etc are all made possible by this 'intelligent device' approach. - On a SCSI bus, each possible pair of devices can communicate. If + On a SCSI bus, each possible pair of devices can communicate. Whether 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 standardization 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><heading>Components of SCSI</heading> + old SCSI-1 device should normally work on a SCSI-2 bus. I say + 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 standardization 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. + + <sect2><heading>Components of SCSI</heading> <p> -<!-- <sect2><heading>A <it>smart</it> interface</heading> +<!-- <sect3><heading>A <it>smart</it> interface</heading> <p> --> As said before, SCSI devices are smart. The idea is to put the knowledge about intimate hardware details onto the SCSI device @@ -104,7 +104,7 @@ there is no longer a need to change (and qualify!) drivers for every odd new device that is introduced. -<!-- <sect2><heading>Do's and don't's on interconnections</heading> +<!-- <sect3><heading>Do's and don't's on interconnections</heading> <p> --> For cabling and connectors there is a golden rule: get good stuff. With bus speeds going up all the time you will save @@ -112,9 +112,9 @@ 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 + rule: do no 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 + shortening the SCSI bus by 1 meter solved the problem. And the original bus length was well within the SCSI specification. <sect2><heading>SCSI bus types</heading> @@ -196,12 +196,12 @@ 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 + each bus signal has its 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..). + not relevant (do not 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 @@ -217,7 +217,7 @@ AH1740 as a single ended board, whereas the AH1744 was differential. The software interface to the host is identical for both. - <sect2><heading>Terminators</heading> + <sect3><heading>Terminators</heading> <p> Terminators in SCSI terminology are resistor networks that are used to get a correct impedance matching. Impedance matching @@ -225,26 +225,26 @@ 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 traveling over your SCSI bus, you - don't want signals echoing back. + do not 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 + carefully store them. 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 built-in terminator. There are special terminators you can stick onto a flat cable - bus. Others look like external connectors, so a connector hood + bus. Others look like external connectors, or 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 + terminators. Active terminators contain slightly more elaborate + circuit to give cleaner bus signals. The general consensus seems to be that the usefulness 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 @@ -278,13 +278,13 @@ for the internal flat cable connectors. This makes reconfiguration much easier. - <sect2><heading>Terminator power</heading> + <sect3><heading>Terminator power</heading> <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 + Not so. Each device can provide its 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 @@ -307,8 +307,8 @@ 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. + In newer designs auto-restoring fuses that 'reset' + themselves after some time are sometimes used. On modern devices, sometimes integrated terminators are used. These things are special purpose integrated circuits that @@ -318,7 +318,7 @@ configurable, using some sort of setup tool. Consult you documentation! - <sect2><heading>Device addressing</heading> + <sect3><heading>Device addressing</heading> <p> Because the SCSI bus is, ehh, a bus there must be a way to distinguish or address the different devices connected to it. @@ -350,7 +350,7 @@ tape changer. In this way, the host system can address each of the parts of the tape unit as desired. - <sect2><heading>Bus layout</heading> + <sect3><heading>Bus layout</heading> <p> SCSI buses are linear. So, not shaped like Y-junctions, star topologies, cobwebs or whatever else people might want to @@ -359,22 +359,22 @@ 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 + The electrical characteristics, its 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><heading>Using SCSI with FreeBSD</heading> + <sect2><heading>Using SCSI with FreeBSD</heading> <p> - <sect2><heading>About translations, BIOSes and magic...</heading> + <sect3><heading>About translations, BIOSes and magic...</heading> <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 + its first incarnation used a low level physical interface to the hard disk. So, you had to tell the BIOS (using a setup tool or a BIOS built-in setup) how your disk physically looked like. This involved stating number of heads, number of cylinders, number of @@ -384,10 +384,11 @@ 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. + SCSI disk with the head/cyl/sector method in order to load the + FreeBSD kernel during boot. 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 + AT/EISA/PCI/whatever bus to connect your disk therefore has its own on-board BIOS. During system startup, the SCSI BIOS takes over the hard disk interface routines from the system BIOS. To fool the system BIOS, the system setup is normally set to No hard disk @@ -397,13 +398,13 @@ <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 + with 64 heads and 32 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 + Right.. All is well now?! No, it is not. The system BIOS has another quirk you might run into. The number of cylinders of a bootable hard disk cannot be greater than 1024. Using the translation above, this is a show-stopper for disks greater than @@ -417,25 +418,32 @@ 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. + 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 each others partitions. Using fdisk - you should be able to see all partitions. + Failing to observe the translation issue might lead to + un-bootable systems or operating systems overwriting each + others 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 + You might have heard some talk of 'lying' devices? + Older FreeBSD kernels used to report 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 + aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> + sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512 </verb> + Newer kernels usually do not report this information.. e.g. + <verb> + (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 + sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors) + </verb> + + Why has this changed? This info is retrieved from the SCSI disk itself. Newer disks often use a technique called zone bit recording. The idea is that @@ -444,15 +452,19 @@ Feb 9 19:33:46 yedi /386bsd: sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 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. + now becomes suspect at best, and nearly always misleading. When + asked for a geometry , it is nearly always better to supply the + geometry used by the BIOS, or <em>if the BIOS is never going to know + about this disk</em>, (e.g. it is not a booting disk) to supply a + fictitious geometry that is convenient. - <sect2><heading>SCSI subsystem design</heading> + <sect3><heading>SCSI subsystem design</heading> <p> FreeBSD uses a layered SCSI subsystem. For each different controller card a 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 + SCSI subsystem through which it receives its commands and reports back any status. On top of the card drivers there are a number of more generic @@ -466,7 +478,7 @@ Feb 9 19:33:46 yedi /386bsd: sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, banging and more high level stuff. Adding support for another piece of hardware is a much more manageable problem. - <sect2><heading>Kernel configuration</heading> + <sect3><heading>Kernel configuration</heading> <p> Dependent on your hardware, the kernel configuration file must contain one or more lines describing your host adapter(s). @@ -533,8 +545,20 @@ device cd0 at scbus? [the first ever CDROM found, no wiring] <em>only</em> attach them when they match the target ID and LUN specified on the corresponding bus. - So, if you had a SCSI tape at target ID 2 it would not be - configured, but it will attach when it is at target ID 6. + Wired down devices get 'first shot' at the unit numbers + so the first non 'wired down' device, is allocated the unit number + one greater than the highest 'wired down' unit number + for that kind of device. + So, if you had a SCSI tape at target ID 2 it would be + configured as st2, as the tape at target ID 6 is wired down + to unit number 1. Note that <em>wired down devices need not + be found</em> + to get their unit number. The unit number for a wired down device + is reserved for that device, even if it is turned off at boot + time. This allows the device to be turned on and brought + on-line at a later time, without rebooting. Notice that a device's + unit number has <em>no</em> relationship with its target ID on + the SCSI bus. Below is another example of a kernel config file as used by FreeBSD version < 2.0.5. The difference with the first example is @@ -545,7 +569,7 @@ device cd0 at scbus? [the first ever CDROM found, no wiring] the first SCSI disk it finds to sd0, the second disk to sd1 etc. If you ever removed or added a disk, all other devices of the same type (disk in this case) would 'move around'. - This implies you have to change /etc/fstab each time. + This implies you have to change <tt>/etc/fstab</tt> each time. Although the old style still works, you are <em>strongly</em> recommended to use this new feature. @@ -555,45 +579,46 @@ device cd0 at scbus? [the first ever CDROM found, no wiring] pre-FreeBSD2.0.5.R system check this out. <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] +[driver for Adaptec 174x] +controller ahb0 at isa? bio irq 11 vector ahbintr +[for Adaptec 154x] +controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr +[for Seagate ST01/02] +controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr 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] +[for the cdrom] +device cd0 #Only need one of these, the code dynamically grows </verb> - Both examples support 4 SCSI disks. If during boot more + + Both examples support 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. + configured in the booting kernel, the system will simply allocate + more devices, incrementing the unit number starting at the last + number 'wired down'. If there are no 'wired down' devices + then counting starts at unit 0. Use <tt>man 4 scsi</tt> to check for the latest info on the SCSI subsystem. For more detailed info on host adapter drivers use eg <tt>man 4 aha</tt> for info on the Adaptec 154x driver. - <sect2><heading>Tuning your SCSI kernel setup</heading> + <sect3><heading>Tuning your SCSI kernel setup</heading> <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. + commands after a SCSI bus reset (which happens at Boot time). + 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 - delay time in your kernel configuration file using a line like: + 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 delay time in your kernel configuration file + using a line like: <verb> options "SCSI_DELAY=15" #Be pessimistic about Joe SCSI device @@ -604,7 +629,7 @@ options "SCSI_DELAY=15" #Be pessimistic about Joe SCSI device with device recognition. If this helps, tune it back until it just stays working. - <sect2><heading>Rogue SCSI devices</heading> + <sect3><heading>Rogue SCSI devices</heading> <p> Although the SCSI standard tries to be complete and concise, it is a complex standard and implementing things correctly is no easy task. @@ -627,7 +652,7 @@ Mar 29 21:16:37 yedi /386bsd: st1: Archive Viper 150 is a known rogue 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. + confusion this causes is left as an exercise to the reader. The SCSI subsystem of FreeBSD recognizes devices with bad habits by looking at the INQUIRY response they send when probed. Because the @@ -640,7 +665,7 @@ Mar 29 21:16:37 yedi /386bsd: st1: Archive Viper 150 is a known rogue to connect your bogus Mumbletech SCSI cdrom you might be the one that has to define which workaround is needed. - <sect2><heading>Busmaster host adapters</heading> + <sect3><heading>Busmaster host adapters</heading> <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 @@ -671,7 +696,7 @@ options "TUNE_1542" #dynamic tune of bus DMA speed Check the man pages for the host adapter that you use. Or better still, use the ultimate documentation (read: driver source). - <sect1><heading>Tracking down problems</heading> + <sect2><heading>Tracking down problems</heading> <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 @@ -688,16 +713,27 @@ options "TUNE_1542" #dynamic tune of bus DMA speed <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 host adapter to use slow bus speeds. + <item> + If you can compile a kernel, make one with the SCSIDEBUG option, + and try accessing the device with debugging turned on for + that device. If your device does not even probe at startup, + you may have to define the address of the device that + is failing, and the desired debug level in + <tt>/sys/scsi/scsidebug.h</tt>. + If it probes but just does not work, you can use the + <tt>scsi(8)</tt> command to dynamically set a debug level to + it in a running kernel (if SCSIDEBUG is defined). + This will give you COPIOUS debugging output with which to confuse + the gurus. see <tt>man 4 scsi</tt> for more exact information. + Also look at <tt>man 8 scsi</tt>. </itemize> - <sect1><heading>Further reading<label id="scsi:further-reading"></heading> + <sect2><heading>Further reading<label id="scsi:further-reading"></heading> <p> If you intend to do some serious SCSI hacking, you might want to have the official standard at hand: diff --git a/handbook/sections.sgml b/handbook/sections.sgml index 6a53a08b7a..ef1bcd31de 100644 --- a/handbook/sections.sgml +++ b/handbook/sections.sgml @@ -1,4 +1,4 @@ -<!-- $Id: sections.sgml,v 1.1.2.2 1995-10-14 21:55:34 jfieber Exp $ --> +<!-- $Id: sections.sgml,v 1.1.2.3 1996-06-19 20:28:18 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- Entities containing all the pieces of the handbook are --> @@ -10,6 +10,7 @@ <!ENTITY contrib SYSTEM "contrib.sgml"> <!ENTITY ctm SYSTEM "ctm.sgml"> <!ENTITY current SYSTEM "current.sgml"> +<!ENTITY stable SYSTEM "stable.sgml"> <!ENTITY crypt SYSTEM "crypt.sgml"> <!ENTITY dialup SYSTEM "dialup.sgml"> <!ENTITY diskless SYSTEM "diskless.sgml"> @@ -17,6 +18,7 @@ <!ENTITY eresources SYSTEM "eresources.sgml"> <!ENTITY esdi SYSTEM "esdi.sgml"> <!ENTITY firewalls SYSTEM "firewalls.sgml"> +<!ENTITY goals SYSTEM "goals.sgml"> <!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY history SYSTEM "history.sgml"> <!ENTITY hw SYSTEM "hw.sgml"> @@ -24,22 +26,28 @@ <!ENTITY kerberos SYSTEM "kerberos.sgml"> <!ENTITY kernelconfig SYSTEM "kernelconfig.sgml"> <!ENTITY kerneldebug SYSTEM "kerneldebug.sgml"> +<!ENTITY linuxemu SYSTEM "linuxemu.sgml"> <!ENTITY memoryuse SYSTEM "memoryuse.sgml"> <!ENTITY mirrors SYSTEM "mirrors.sgml"> <!ENTITY nfs SYSTEM "nfs.sgml"> <!ENTITY nutshell SYSTEM "nutshell.sgml"> +<!ENTITY pgpkeys SYSTEM "pgpkeys.sgml"> <!ENTITY porting SYSTEM "porting.sgml"> <!ENTITY ports SYSTEM "ports.sgml"> <!ENTITY ppp SYSTEM "ppp.sgml"> <!ENTITY printing SYSTEM "printing.sgml"> +<!ENTITY quotas SYSTEM "quotas.sgml"> <!ENTITY relnotes SYSTEM "relnotes.sgml"> <!ENTITY routing SYSTEM "routing.sgml"> <!ENTITY scsi SYSTEM "scsi.sgml"> +<!ENTITY sio SYSTEM "sio.sgml"> +<!ENTITY cy SYSTEM "cyclades.sgml"> <!ENTITY skey SYSTEM "skey.sgml"> <!ENTITY slipc SYSTEM "slipc.sgml"> <!ENTITY slips SYSTEM "slips.sgml"> <!ENTITY submitters SYSTEM "submitters.sgml"> <!ENTITY sup SYSTEM "sup.sgml"> +<!ENTITY synching SYSTEM "synching.sgml"> <!ENTITY troubleshooting SYSTEM "troubleshooting.sgml"> +<!ENTITY uart SYSTEM "uart.sgml"> <!ENTITY userppp SYSTEM "userppp.sgml"> - diff --git a/handbook/skey.sgml b/handbook/skey.sgml index 441a925164..d75eff42d7 100644 --- a/handbook/skey.sgml +++ b/handbook/skey.sgml @@ -1,4 +1,4 @@ -<!-- $Id: skey.sgml,v 1.3.2.1 1996-01-31 14:32:30 mpp Exp $ --> +<!-- $Id: skey.sgml,v 1.3.2.2 1996-06-19 20:28:19 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- Copyright 1995 Massachusetts Institute of Technology @@ -43,12 +43,12 @@ of Bell Communications Research, Inc. <!-- XXX - is there a better word to use than UNIX? --> <p>There are three different sorts of passwords which we will talk about in the discussion below. The first is your usual UNIX-style or Kerberos -password; we'll call this a ``UNIX password''. The second sort is the +password; we will call this a ``UNIX password''. The second sort is the one-time password which is generated by the S/Key `<tt/key/' program and -accepted by the `<tt/keyinit/' program and the login prompt; we'll call +accepted by the `<tt/keyinit/' program and the login prompt; we will call this a ``one-time password''. The final sort of password is the secret password which you give to the `<tt/key/' program (and sometimes the -`<tt/keyinit/' program) which it uses to generate one-time passwords; we'll +`<tt/keyinit/' program) which it uses to generate one-time passwords; we will call it a ``secret password'' or just unqualified ``password''. <p>The secret password does not necessarily have anything to do with your @@ -73,7 +73,7 @@ one-way hash function is used, it is not possible to generate future one-time passwords having overheard one which was successfully used; the iteration count is decremented after each successful login to keep the user and login program in sync. (When you get the iteration count -down to 1, it's time to reinitialize S/Key.) +down to 1, it is time to reinitialize S/Key.) <p>There are four programs involved in the S/Key system which we will discuss below. The `<tt/key/' program accepts an iteration count, a @@ -125,7 +125,7 @@ minimum seven words) which will be needed to generate login keys. The line starting `ID' gives the parameters of your particular S/Key instance: your login name, the iteration count, and seed. When logging in with S/Key, the system will remember these parameters and -present them back to you so you don't have to remember them. The last +present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use. @@ -136,7 +136,7 @@ immediately, this one-time password is the one you would use. connection, you will need to already have a secure connection to some place where you can run the `<tt/key/' program; this might be in the form of a desk accessory on a Macintosh, or a shell prompt on a machine you -trust (we'll show the latter). You will also need to make up an +trust (we will show the latter). You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the `<tt/keyinit -s/' @@ -253,7 +253,7 @@ Enter secret password: The `<tt/-n 25/' requests twenty-five keys in sequence; the `<tt/57/' indicates the <em/ending/ iteration number; and the rest is as before. Note that -these are printed out in <em/reverse/ order of eventual use. If you're +these are printed out in <em/reverse/ order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into `<tt/lpr/'. Note that each line shows both the iteration count and the one-time password; you may still find diff --git a/handbook/slipc.sgml b/handbook/slipc.sgml index 1987dcc16c..665a9ea9d2 100644 --- a/handbook/slipc.sgml +++ b/handbook/slipc.sgml @@ -1,4 +1,4 @@ -<!-- $Id: slipc.sgml,v 1.1.1.1.4.3 1995-10-12 03:16:35 jfieber Exp $ --> +<!-- $Id: slipc.sgml,v 1.1.1.1.4.4 1996-06-19 20:28:20 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>Setting up a SLIP client<label id="slipc"></heading> @@ -11,8 +11,8 @@ 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 +This is just "what I did, and it worked for me". I am sharing this +just for your reference, I am no expert in SLIP nor networking so your mileage may vary. --> @@ -27,13 +27,13 @@ Make sure you have pseudo-device sl 1 </verb> in your kernel's config file. It is included in the GENERIC kernel, -so this won't be a problem unless you deleted it. +so this will not 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: + <tt>/etc/hosts</tt> file. Mine looks like this: <verb> 127.0.0.1 localhost loghost 136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia @@ -43,12 +43,12 @@ so this won't be a problem unless you deleted it. 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.). + back in Japan (it is called 2?0SX here in U.S.). -<item>Make sure you have "hosts" before "bind" in your /etc/host.conf. +<item>Make sure you have "hosts" before "bind" in your <tt>/etc/host.conf</tt>. Otherwise, funny things may happen. -<item>Edit the file /etc/sysconfig. +<item>Edit the file <tt>/etc/sysconfig</tt>. <enum> <item>Set your hostname by editing the line that says: <verb> @@ -81,7 +81,7 @@ defaultrouter=slip-gateway </verb> </enum> -<item>Make a file /etc/resolv.conf which contains: +<item>Make a file <tt>/etc/resolv.conf</tt> which contains: <verb> domain HIP.Berkeley.EDU nameserver 128.32.136.9 @@ -91,8 +91,8 @@ nameserver 128.32.136.12 actual domain names and 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! + does not have a password). Use passwd, do not edit the <tt>/etc/passwd</tt> + or <tt>/etc/master.passwd</tt> files! <item>Reboot your machine and make sure it comes up with the correct hostname. @@ -123,8 +123,8 @@ output ***\x0d, echo \x0aCONNECTED\x0a 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 + <bf>Note</bf>: leaving your password in plain text anywhere in the + filesystem is generally a BAD idea. Do it at your own risk. I am just too lazy. <item>Leave the kermit there (you can suspend it by "z") and as root, @@ -133,7 +133,7 @@ output ***\x0d, echo \x0aCONNECTED\x0a slattach -h -c -s 115200 /dev/modem </verb> if you are able to "ping" hosts on the other side of the router, - you are connected! If it doesn't work, you might want to try "-a" + you are connected! If it does not work, you might want to try "-a" instead of "-c" as an argument to slattach. </enum> @@ -144,7 +144,7 @@ slattach -h -c -s 115200 /dev/modem 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 + mark the interface down, but this does not seem to make any difference for me. ("ifconfig sl0" reports the same thing.) Some times, your modem might refuse to drop the carrier (mine @@ -153,7 +153,7 @@ slattach -h -c -s 115200 /dev/modem <sect1><heading>Troubleshooting</heading> -<p>If it doesn't work, feel free to ask me. The things that people +<p>If it does not 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 @@ -170,8 +170,8 @@ 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: +<item>Also, <tt>netstat -r</tt> 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 diff --git a/handbook/slips.sgml b/handbook/slips.sgml index eea138c0b8..3156e98b46 100644 --- a/handbook/slips.sgml +++ b/handbook/slips.sgml @@ -27,13 +27,10 @@ suggestions here. This guide was originally written for SLIP Server services on a FreeBSD 1.x system. It has been modified to reflect changes in the pathnames and the removal of the SLIP interface compression flags in -FreeBSD 2.x, which appear to be the only major changes between -FreeBSD versions. If you do run encounter mistakes in this document, -please email the author with enough information to help correct the -problem. - -For FreeBSD 1.x users, all of the files referenced in the directory -<tt>/etc/sliphome</tt> are actually in the <tt>/etc</tt> directory. +early versions of FreeBSD 2.X, which appear to be the only major +changes between FreeBSD versions. If you do encounter mistakes in +this document, please email the author with enough information to +help correct the problem. <sect1><heading>Prerequisites<label id="slips:prereqs"></> @@ -49,9 +46,9 @@ Administration</em> published by O'Reilly & Associates, Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books on the TCP/IP protocol. -It's further assumed that you have already setup your modem(s) and +It is further assumed that you have already setup your modem(s) and configured the appropriate system files to allow logins through your -modems. If you haven't prepared your system for this yet, please see +modems. If you have not prepared your system for this yet, please see the tutorial for configuring dialup services; if you have a World-Wide Web browser available, browse the list of tutorials at <tt>http://www.freebsd.org/</tt>; otherwise, check the place @@ -119,7 +116,7 @@ goes into <tt>/var/log/messages</tt> (see the manual pages for <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. +OK, enough of the examples -- let us dive into setting up the system. <sect1><heading>Kernel Configuration</heading> <p> @@ -151,24 +148,14 @@ Internet RFC requirements for Internet hosts (see RFC's 1009 [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: +router, you will have to add the line +<verb> +sysctl -w net.inet.ip.forwarding = 0 +</verb> +to your rc.local file. + +You will notice that near the end of the default kernel configuration +file (<tt>/sys/i386/conf/GENERIC</tt>) is a line that reads: <tscreen><verb> pseudo-device sl 2 @@ -178,9 +165,8 @@ 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. +Please refer to <ref id="kernelconfig" name="Configuring the FreeBSD Kernel"> +for help in reconfiguring your kernel. <sect1><heading>Sliplogin Configuration</heading> @@ -237,17 +223,17 @@ At the end of the line is one or more of the options. dropped instead of using up your bandwidth) </itemize> -It appears that <tt/sliplogin/ under FreeBSD 2.x ignores the options -that FreeBSD 1.x recognized, so the options <tt/normal/, -<tt/compress/, <tt/autocomp/, and <tt/noicmp/ will have no effect -under FreeBSD 2.x unless your <tt/slip.login/ script includes code to -make use of the flags. +Note that <tt/sliplogin/ under early releases of FreeBSD 2 ignored +the options that FreeBSD 1.x recognized, so the options +<tt/normal/, <tt/compress/, <tt/autocomp/, and <tt/noicmp/ had no effect +until support was added in FreeBSD 2.2 (unless your <tt/slip.login/ script +included code to make use of the flags). 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'' +going to use ``proxy ARP'' on your SLIP server (it is not ``true'' proxy ARP, but that is the terminology used in this document to -describe it). If you're not sure which method to select or how to +describe it). If you are not sure which method to select or how to assign IP addresses, please refer to the TCP/IP books referenced in the <ref id="slips:prereqs"> section and/or consult your IP network manager. @@ -263,7 +249,7 @@ 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 +Ethernet subnet, and you will also need to adjust your <tt>/etc/sliphome/slip.login</tt> and <tt>/etc/sliphome/slip.logout</tt> scripts to use <tt>arp(8)</tt> to manage the proxy-ARP entries in the SLIP server's ARP table. @@ -351,7 +337,7 @@ will be unable to execute it. <p> -<tt>/etc/sliphome/slip.logout</tt> isn't strictly needed (unless you +<tt>/etc/sliphome/slip.logout</tt> is not 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: @@ -371,7 +357,7 @@ is an example of a basic <tt>slip.logout</tt> script: ----- end /etc/sliphome/slip.logout ----- </verb></tscreen> -If you are using ``proxy ARP'', you'll want to have +If you are using ``proxy ARP'', you will want to have <tt>/etc/sliphome/slip.logout</tt> remove the ARP entry for the SLIP client: @@ -415,7 +401,7 @@ routers via appropriate routing protocols about your SLIP subnet. <p> Adding static routes to your nearest default routers can be -troublesome (or impossible, if you don't have authority to do so...). +troublesome (or impossible, if you do not have authority to do so...). If you have a multiple-router network in your organization, some routers, such as Cisco and Proteon, may not only need to be configured with the static route to the SLIP subnet, but also need to be told @@ -437,7 +423,7 @@ 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 the author used on a FreeBSD SLIP +here is a sample, similar to what the author used on a FreeBSD SLIP server: <tscreen><verb> @@ -486,17 +472,17 @@ import proto rip interface ed { 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/ +<tt/ed/ driver, you will 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. You'll need to change the +<tt>gated</tt> works OK for you. You will 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 +configuration file for it, you will 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 diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml index 677b054828..5b2bb8b425 100644 --- a/handbook/submitters.sgml +++ b/handbook/submitters.sgml @@ -1,46 +1,247 @@ -<!-- $Id: submitters.sgml,v 1.2.4.2 1995-10-12 03:16:37 jfieber Exp $ --> +<!-- $Id: submitters.sgml,v 1.2.4.3 1996-06-19 20:28:25 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Contributing to FreeBSD<label id="submitters"></heading> <p><em>Contributed by &a.jkh;.</em> -This guide is intended for those who are moderately familiar with -FreeBSD and have reached a point where they have some locally -developed customizations or fixes to the system which they'd like to -incorporate back into the mainstream sources. Submitting something to -the FreeBSD project ensures that you won't have to continually -reintegrate it with each subsequent release and is also an excellent -way of getting your code seriously <em>tested</em>! Many people have -seen an original concept develop far beyond what they might have -originally envisioned simply 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, 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 document! - -Submissions to FreeBSD can generally be classified into four categories: +<p>So you want to contribute something to FreeBSD? That is great! +We can always use the help, and FreeBSD is one of those systems +that <em>relies</em> on the contributions of its user base in order +to survive. Your contributions are not only appreciated, they are +vital to FreeBSD's continued growth! + +<p>Contrary to what some people might also have you believe, you do not +need to be a hot-shot programmer or a close personal friend of the +FreeBSD core team in order to have your contributions accepted. The +FreeBSD Project's development is done by a large and growing number of +international contributors who's ages and areas of technical expertise +vary greatly, and there is always more work to be done than there are +people available to do it. + +<p>Since the FreeBSD project is responsible for an entire operating +system environment (and its installation) rather than just a kernel or +a few scattered utilities, our "TODO" list also spans a very wide +range of tasks, from documentation, beta testing and presentation to +highly specialized types of kernel development. No matter what your +skill level, there is almost certainly something you can do to help the +project! + +<p>Commercial entities engaged in FreeBSD-related enterprises are +also encouraged to contact us. Need a special extension to make your +product work? You will find us receptive to your requests, given that +they are not too outlandish. Working on a value-added product? Please +let us know! We may be able to work cooperatively on some aspect of +it. The free software world is challenging a lot of existing +assumptions about how software is developed, sold, and maintained +throughout its life cycle, and we urge you to at least give it a +second look. + +<sect><heading>What is needed</heading> + +<p>The following list of tasks and sub-projects represents something +of an amalgam of the various core team TODO lists and user requests +we have collected over the last couple of months. Where possible, tasks +have been ranked by degree of urgency. If you are interested in +working on one of the tasks you see here, send mail to the coordinator +listed by clicking on their names. If no coordinator has been +appointed, maybe you would like to volunteer? + +<sect1><heading>High priority tasks</heading> +<p>The following tasks are considered to be urgent, usually because +they represent something that is badly broken or sorely needed: +<enum> +<item>3-stage boot issues. Overall coordination: +&a.hackers +<p><itemize> +<item>Autodetect memory over 64MB properly. +<item>Move userconfig (-c) into 3rd stage boot. +<item>Do WinNT compatible drive tagging so that the 3rd stage can +provide an accurate mapping of BIOS geometries for disks. +</itemize> +<item>Filesystem problems. Overall coordination: +&a.fs +<itemize> +<item>Fix the MSDOS file system. +<item>Clean up and document the nullfs filesystem code. Coordinator: &a.gibbs +<item>Fix the union file system. Coordinator: &a.dyson +<item>Fix the LFS file system. Coordinator: &a.dyson +</itemize> +<item>Implement kernel and user vm86 support. Coordinator: &a.hackers +<item>Implement Int13 vm86 disk driver. Coordinator: &a.hackers +<item>SCSI driver issues. Overall coordination: &a.hackers +<p><itemize> +<item>Support tagged queuing generically. Requires a rewrite of how we do +our command queing, but we need this anyway to for prioritized I/O +(CD-R writers/scanners). +<item>Better error handling (Busy status and retries). +<item>Merged Scatter-Gather list creation code. +</itemize> +<item>Kernel issues. Overall coordination: +&a.hackers +<p><itemize> +<item>Complete the eisaconf conversion of all existing drivers. +<item>Change all interrupt routines to take a (void *) instead of +using unit numbers. +<item>Merge EISA/PCI/ISA interrupt registration code. +<item>Split PCI/EISA/ISA probes out from drivers like bt742a.c (WIP) +<item>Fix the syscons ALT-TAB/vt switching hangs. Coordinator: &a.sos +<item>Mouse support for syscons. +<item>Merged keyboard code for all console drivers. +<item>Rewrite the Intel Etherexpress 16 driver. +<item>Merge the 3c509 and 3c590 drivers (essentially provide a PCI probe for +ep.c). +<item>Support Adaptec 3985 (first as a simple 3 channel SCSI card) +Coordinator: &a.gibbs +<item>Support Advansys SCSI controller products. Coordinator: &a.gibbs +</itemize> +</enum> + +<sect1><heading>Medium priority tasks</heading> +<p>The following tasks need to be done, but not with any particular +urgency: <enum> -<item>Ideas, general suggestions, bug reports. -<item>Changes to existing sources. -<item>Significant contribution of a large body of independent work. -<item>Porting of freely available software. +<item>DOS emulator (for DOS executables) Coordinator: <tt><htmlurl +url="mailto:jr@jrw.org" name="J.R. Westmoreland"></tt> +<item>Port AFS (Andrew File System) to FreeBSD Coordinator: <tt><htmlurl +url="mailto:ajones@ctron.com" name="Alexander Seth Jones"></tt> + +<item>MCA support? This should be finalized one way or the other. +<item>Full LKM based driver support/Configuration Manager. +<p><itemize> +<item>Devise a way to do all LKM registration without ld. This means +some kind of symbol table in the kernel. +<item>Write a configuration manager (in the 3rd stage boot?) that probes +your hardware in a sane manner, keeps only the LKMs required for +your hardware, etc. +</itemize> +<item>PCMCIA/PCCARD. Coordinator: &a.phk +<itemize> +<item>Reliable operation of the pcic driver. +<item>Recognizer and handler for sio.c +<item>Recognizer and handler for ed.c +<item>Recognizer and handler for ep.c +<item>User-mode recognizer and handler. +</itemize> +<item>Advanced Power Management. Coordinator: &a.phk +<itemize> +<item>APM sub-driver. +<item>IDE/ATA disk sub-driver. +<item>syscons/pcvt sub-driver. +</itemize> +</enum> + +<sect1><heading>Low priority tasks</heading> +<p>The following tasks are purely cosmetic or represent such an +investment of work that it is not likely that anyone will get them done +anytime soon: + +<p>The first 20 items are from Terry Lambert <terry@lambert.org> +<enum> +<item>Ability to make BIOS calls from protected mode using V86 mode +on the processor and return the results via a mapped interrupt +IPC mechanism to the protected mode caller. + +<item>Drivers built into the kernel that use the BIOS call mechanism +to allow them to be independent of the actual underlying hardware +the same way that DOS is independent of the underlying hardware. +This includes NetWork and ASPI drivers loaded in DOS prior to +BSD being loaded by a DOS-based loader program, which means +potential polling, which means DOS-not-busy interrupt generation +for V86 machines by the protected mode kernel. + +<item>An image format that allows tagging of such drivers data and +text areas in the default kernel executable so that that portion +of the kernel address space may be recovered at a later time, +after hardware specific protected mode drivers have been loaded +and activated. This includes separation of BIOS based drivers +from each other, since it is better to run with a BIOS based +driver in all cases than to not run at all. + +<item>Abstraction of the bus interface mechanism. Currently, PCMCIA, +EISA, and PCI busses are assumed to be bridged from ISA. This +is not something which should be assumed. + +<item>A configuration manager that knows about PNP events, including +power management events, insertion, extraction, and bus (PNP ISA +and PCMCIA bridging chips) vs. card level event management. + +<item>A topological sort mechanism for assigning reassignable addresses +that do not collide with other reassignable and non-reassignable +device space resource usage by fixed devices. + +<item>A registration based mechanism for hardware services registration. +Specifically, a device centric registration mechanism for timer +and sound and other system critical service providers. Consider +Timer2 and Timer0 and speaker services as one example of a single +monolithic service provider. + +<item>A kernel exported symbol space in the kernel data space accessible +by an LKM loader mechanism that does relocation and symbol space +manipulation. The intent of this interface is to support the +ability to demand load and unload kernel modules. + +<item>NetWare Server (protected mode ODI driver) loader and subservices +to allow the use of ODI card drivers supplied with network cards. +The same thing for NDIS drivers and NetWare SCSI drivers. + +<item>An "upgrade system" option that works on Linux boxes instead +of just previous rev FreeBSD boxes. + +<item>Splitting of the console driver into abstraction layers, both to +make it easier to port and to kill the X and ThinkPad and PS/2 +mouse and LED and console switching and bouncing NumLock problems +once and for all. + +<item>Other kernel emulation environments for other foreign drivers +as opportunity permits. SCO and Solaris are good candidates, +followed by UnixWare, etc. + +<item>Processor emulation environments for execution of foreign binaries. +This is easier than it sounds if the system call interface does not +change much. + +<item>Streams to allow the use of commercial streams drivers. + +<item>Kernel multithreading (requires kernel preemption). + +<item>Symmetric Multiprocessing with kernel preemption (requires kernel +preemption). + +<item>A concerted effort at support for portable computers. This is +somewhat handled by changing PCMCIA bridging rules and power +management event handling. But there are things like detecting +internal vs. external display and picking a different screen +resolution based on that fact, not spinning down the disk if +the machine is in dock, and allowing dock-based cards to disappear +without affecting the machines ability to boot (same issue for +PCMCIA). + +<item>Reorganization of the source tree for multiple platform ports. + +<item>A "make world" that "makes the world" (rename the current one +to "make regress" if that is all it is good for). + +<item>A 4M (preferably smaller!) memory footprint. + </enum> -A submission in <em>any</em> of these categories is highly welcomed as they -are each, in their own way, quite significant to the project. +<sect><heading>How to contribute</heading> -<sect><heading>Ideas and suggestions</heading> +<p>Contributions to the system generally fall into one or more of +the following 6 categories: + +<sect1><heading>Bug reports and general commentary</heading> +<p>If you have a bug to report or a suggestion to make: -<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 <tt><hackers@freebsd.org></tt>. + mailed to the &a.hackers;. Likewise, people with an interest in such things (and a tolerance for a <em>high</em> volume of mail!) may subscribe to the hackers mailing list by sending mail to - <tt><majordomo@freebsd.org></tt>. + &a.majordomo;. See <ref id="eresources:mail" name="mailing lists"> for more information about this and other mailing lists. @@ -49,17 +250,23 @@ are each, in their own way, quite significant to the project. you for various fields to fill in. Simply go to the fields surrounded by <tt><></tt>'s and fill in your own information in place of - what's suggested there. You should receive confirmation of your + what is suggested there. You should receive confirmation of your bug report and a tracking number. Keep this tracking number and use it 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 <tt>send-pr(1)</tt> command, - then you may also file a bug report by sending mail to - <tt><bugs@freebsd.org></tt>. + then you may also file a bug report by sending mail to the &a.bugs;. </itemize> -<sect><heading>Changes to the existing code</heading> +<sect1><heading>Changes to the documentation</heading> + +<p>Changes to the documentation are overseen by the &a.doc;. +This does not generally include +changes to manual pages, which should be considered under the category +of "changes to existing source code." + +<sect1><heading>Changes to existing source 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 @@ -73,8 +280,7 @@ are each, in their own way, quite significant to the project. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the - <tt><announce@freebsd.org></tt> and - <tt><current@freebsd.org></tt> mailing lists, where discussions + &a.announce and the &a.current lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base @@ -95,38 +301,38 @@ diff -c -r olddir newdir Once you have a set of diffs (which you may test with the <tt>patch(1)</tt> command), you should bundle them up in an email message and send it, along with a brief description of - what the diffs are for, to - <tt><hackers@freebsd.org></tt>. Someone will very + what the diffs are for, to the &a.hackers;. + 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) + If your changes do not express themselves well as diffs alone + (e.g. you have perhaps added, deleted or renamed files as well) then you may be better off bundling any new files, diffs and instructions for deleting/renaming others into a <tt>tar</tt> file and running the <tt>uuencode(1)</tt> program on it before - sending the output of that to <tt><hackers@freebsd.org></tt>. + sending the output of that to the &a.hackers;. See the man pages on <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more information on bundling files 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 <tt><core@freebsd.org></tt> rather than - <tt><hackers@freebsd.org></tt>. The core mailing list + you are unsure of copyright issues governing its further distribution + or you are simply not ready to release it without a tighter review first, + then you should send it to <tt><htmlurl url="mailto:core@FreeBSD.ORG" + name="<core@FreeBSD.ORG>"></tt> rather than the &a.hackers + 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 <em>very busy</em> and so you should only send mail to them in cases where mailing to hackers is truly impractical. - -<sect><heading>Contributions of new code</heading> +<sect1><heading>New code or major value-added packages</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 or upload them to our ftp site <url - url="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">. + url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming">. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights @@ -141,7 +347,7 @@ diff -c -r olddir newdir who might eventually be inclined to invest something of their own into FreeBSD. - <item>The GNU Public License, or ``GPL''. This license isn't quite + <item>The GNU Public License, or ``GPL''. This license is not quite as popular with us due to the amount of extra effort demanded of anyone using the code for commercial purposes, but given the sheer quantity of GPL'd code we currently require (compiler, @@ -193,30 +399,121 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: submitters.sgml,v 1.2.4.2 1995-10-12 03:16:37 jfieber Exp $ + $Id: submitters.sgml,v 1.2.4.3 1996-06-19 20:28:25 jkh Exp $ </verb></tscreen> For your convenience, a copy of this text can be found in <tt>/usr/share/examples/etc/bsd-style-copyright</tt>. + &porting; + +<sect1><heading>Money, Hardware or Internet access</heading> +<p>We are always very happy to accept donations to further the cause of +the FreeBSD Project and, in a volunteer effort like ours, a little can go +a long way! Donations of hardware are also very important to expanding +our list of supported peripherals since we generally lack the funds to +buy such items ourselves. -<sect><heading>Porting of software</heading> - -<p>The porting of freely available software, while perhaps not as -gratifying as developing your own 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 carefully organized hierarchy know as ``the ports collection''. -The collection enables a new user to get a quick and complete overview -of what's available for FreeBSD in an easy-to-compile form. It also -saves considerable space by not actually containing the the majority -of the sources being ported, but merely those differences required for -running under FreeBSD. See <ref id="ports" name="The ports -collection"> for more information on using the ports collection and -<ref id="porting" name="Porting applications"> for guidelines on -creating new ports. You may also send mail to -<tt><ports@freebsd.org></tt>. - -Whichever way you decide to contribute, we hope you'll find it an -enjoyable and rewarding process. Such contributions are also very -valuable to FreeBSD's continued progress, and as a free software -effort, the more we all put in the more we all get back out of it! +<sect2><heading>Donating funds</heading> +<p>While the FreeBSD Project is not a 501(C3) (non-profit) corporation and +hence cannot offer special tax incentives for any donations made, any such +donations will be gratefully accepted on behalf of the project by +FreeBSD, Inc. + +<p>FreeBSD, Inc. was founded in early 1995 by &a.jkh and &a.davidg with the +goal of furthering the aims of the FreeBSD Project and giving it a minimal +corporate presence. Any and all funds donated (as well as any profits +that may eventually be realized by FreeBSD, Inc.) will be used exclusively +to further the project's goals. + +Please make any checks payable to FreeBSD, Inc., sent in care of the +following address: + +<tscreen><verb> +FreeBSD, Inc. +c/o Jordan Hubbard +4041 Pike Lane, suite #D. +Concord CA, 94520 + +[temporarily using the Walnut Creek CDROM address until a PO box can be +opened] +</verb></tscreen> + +Wire transfers may also be sent directly to: + +<tscreen><verb> +Bank Of America +Concord Main Office +P.O. Box 37176 +San Francisco CA, 94137-5176 + +Routing #: 121-000-358 +Account #: 01411-07441 (FreeBSD, Inc.) +</verb></tscreen> + +If you do not wish to be listed in our <ref id="donors" name="donors"> +section, please specify this when making your donation. Thanks! + +<sect2><heading>Donating hardware</heading> + +<p>Donations of hardware in any of the 3 following categories are also gladly +accepted by the FreeBSD Project: + +<itemize> +<item>General purpose hardware such as disk drives, memory or complete +systems should be sent to the FreeBSD, Inc. address listed in the +<em>donating funds</em> section. + +<item>Hardware for which ongoing compliance testing is desired. +We are currently trying to put together a testing lab of all components +that FreeBSD supports so that proper regression testing can be done with +each new release. We are still lacking many important pieces (network cards, +motherboards, etc) and if you would like to make such a donation, please contact +&a.davidg for information on which items are still required. + +<item>Hardware currently unsupported by FreeBSD for which you would like to +see such support added. Please contact the <htmlurl +url="mailto:core@FreeBSD.ORG" name="FreeBSD Core Team"> before sending +such items as we will need to find a developer willing to take on the task +before we can accept delivery of them. +</itemize> + +<sect2><heading>Donating Internet access</heading> + +<p>We can always use new mirror sites for FTP, WWW or sup. +If you would like to be such a mirror, please contact +<htmlurl url="mailto:admin@FreeBSD.ORG" name="the FreeBSD project +administrators"> for more information. + +<sect><heading>Donors Gallery<label id="donors"></heading> + +<p>The FreeBSD Project is indebted to the following donors and would +like to publically thank them here! + +<itemize> + <item><htmlurl url="mailto:ANDRSN@HOOVER.STANFORD.EDU" + name="Annelise Anderson"> + + has generously donated funding to the further development of FreeBSD + </item> + + <item><htmlurl url="http://www.epilogue.com/" name="Epilogue + Technology Corporation">has generously donated funding to FreeBSD. + </item> + + <item><htmlurl url="http://www.iijnet.or.jp/laser5/" name="Laser5"> + in Japan has graciously donated a portion of their profits from the + sale of their <em>FreeBSD for PC98'ers</em> CD, a port of FreeBSD to + the NEC PC98. + </item> + + <item><htmlurl url="http://www.cdrom.com" name="Walnut Creek CDROM"> + has donated almost more than we can say (see the + <ref id="history" name="history"> document for more details). + In particular, we would like to thank them for the hardware used for + <em>freefall.FreeBSD.ORG</em>, our primary development machine, + and for <em>thud.FreeBSD.ORG</em>, our testing and build box. + We are also indebted to them for funding various contributors over + the years and providing us with unrestricted use of their T1 + connection to the Internet. + </item> +</itemize> diff --git a/handbook/sup.sgml b/handbook/sup.sgml index aaa4b17df7..7e09772b8a 100644 --- a/handbook/sup.sgml +++ b/handbook/sup.sgml @@ -1,4 +1,4 @@ -<!-- $Id: sup.sgml,v 1.2.4.3 1995-10-12 03:16:39 jfieber Exp $ --> +<!-- $Id: sup.sgml,v 1.2.4.4 1996-06-19 20:28:26 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> @@ -11,33 +11,41 @@ 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 (if it doesn't already exist): -<verb> - supfilesrv 871/tcp # for SUP -</verb> +<p>Starting with FreeBSD 2.1, sup is supplied as part of the base +system and no separate installation is required. 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 separating -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 <em>but</em> 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. +called a supfile. This file should be found in +<tt>/usr/share/examples/sup/standard-supfile</tt> for the standard +distributions. +This file tells sup what collections it will be updating +and/or installing and where they go. This supfile will sup the current source +collection. For ports please have a look at +<tt>/usr/share/examples/sup/ports-supfile</tt>. If you are interested +in obtaining the cvs files that make up the source tree, refer to +<tt>/usr/share/examples/sup/cvs-supfile</tt>. If you would rather +track changes to the -stable release, refer to +<tt>/usr/share/examples/sup/stable-supfile</tt> +instead. -Any other distributions you do not wish to receive can be commented out +If you are inside the United States, you may also uncomment +the `secure' and `eBones' collection lines to grab the DES code. +If you are outside the +U.S., you should NOT sup this code from sup.FreeBSD.ORG as this will +violate U.S. export restrictions. Instead you should use the +<tt>secure-supfile</tt> found within the above directory. This will +connect you to the international sup site that contains a secure distribution. +Any distributions you do not wish to receive can be commented out with a # at the beginning of the distribution line. -Once this is setup, you're ready to go. To start sup type: +Please consult the file +<tt>/usr/share/examples/sup/README</tt> +for a list of alternate sup servers. The default sup server (sup.FreeBSD.ORG) +listed in the above example files is currently overloaded and any traffic +that can be transfered to a different host will help relieve some of +the strain. + +Once this is setup, you are ready to go. To start sup type: <verb> sup supfile </verb> @@ -46,46 +54,79 @@ 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 <ref id="current" -name="Staying current with FreeBSD"> +Thats all there is to it! Remember that if you are running current, +which is what you will have if you sup with the standard-supfile, please +join the &a.current mailing list. You should also be sure to read +<ref id="current" name="Staying current with FreeBSD"> for important information on just what we can and cannot do for you as -a -current user. +a -current user. If you are using the stable-supfile, please +join the &a.stable mailing list and read +<ref id="stable" name="Staying stable with FreeBSD"> +. <sect1><heading>Description of FreeBSD SUP distributions</heading> -<p>For the main FreeBSD distribution: +<p>For the main FreeBSD distribution using the standard-supfile: +<verb> +src-base: /usr/src/... misc files at the top of /usr/src +src-bin: /usr/src/bin user and system binaries +src-secure: /usr/src/secure DES Sources (US/Canada ONLY) +src-eBones: /usr/src/eBones Kerberos and DES (US/Canada ONLY) +src-etc: /usr/src/etc system files +src-games: /usr/src/games games +src-gnu: /usr/src/gnu sources under the GNU Public License +src-include: /usr/src/include include files +src-sys: /usr/src/sys kernel sources +src-lib: /usr/src/lib libraries +src-libexec: /usr/src/libexec system binaries +src-share: /usr/src/share various shared resources +src-sbin: /usr/src/sbin single user system binaries +src-usrbin: /usr/src/usr.bin user binaries +src-usrsbin: /usr/src/usr.sbin system binaries +</verb> + +<p>For the international FreeBSD distribution using the secure-supfile: +<verb> +src-secure: /usr/src/secure DES Sources +src-eBones: /usr/src/eBones Kerberos and DES +</verb> + +<p>And for the ports collection: <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 +ports-base: /usr/ports/... misc files at the top of /usr/ports +ports-archivers: /usr/ports/archivers archiving tools +ports-audio: /usr/ports/audio sound support +ports-benchmarks: /usr/ports/benchmarks benchmarks +ports-cad: /usr/ports/cad CAD tools +ports-comms: /usr/ports/comms communication software +ports-databases: /usr/ports/databases databases +ports-devel: /usr/ports/devel development utilities +ports-editors: /usr/ports/editors editors +ports-emulators: /usr/ports/emulators emulators for other OSes +ports-games: /usr/ports/games games +ports-graphics: /usr/ports/graphics various graphics utilities +ports-japanese: /usr/ports/japanese Japanese software. +ports-lang: /usr/ports/lang programming languages +ports-mail: /usr/ports/mail mail software +ports-math: /usr/ports/math numerical computation software +ports-misc: /usr/ports/misc miscellaneous utilities +ports-net: /usr/ports/net networking software +ports-news: /usr/ports/news USENET news software +ports-plan9: /usr/ports/plan9 various programs from Plan9 +ports-print: /usr/ports/print printing software +ports-russian: /usr/ports/russian Russian software +ports-security: /usr/ports/security ``security'' utilities, for better or for worse +ports-shells: /usr/ports/shells various UN*X shells +ports-sysutils: /usr/ports/sysutils system utilities +ports-www: /usr/ports/www software related to the world wide web +ports-x11: /usr/ports/x11 X11 software </verb> -And for the ports collection: +<p>If you want to keep updated on the original source of the ports, +you can also add this to your supfile. But note that this collection +is <em>enormous</em>, and unless you are an ftp site mirroring the +entire FreeBSD tree (but cannot use ``mirror'' for some reason), you +(and us) are much better off not using sup to collect these: <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-russian: /usr/ports/russian russian software -ports-shells: /usr/ports/shells various UN*X shells -ports-utils: /usr/ports/utils miscellaneous utilities -ports-x11: /usr/ports/x11 X11 software +ports-distfiles: /usr/ports/distfiles original tarballs </verb> diff --git a/handbook/troubleshooting.sgml b/handbook/troubleshooting.sgml index 342bc2677f..02cafd5f94 100644 --- a/handbook/troubleshooting.sgml +++ b/handbook/troubleshooting.sgml @@ -1,4 +1,4 @@ -<!-- $Id: troubleshooting.sgml,v 1.1.1.1.4.2 1995-10-12 03:16:40 jfieber Exp $ --> +<!-- $Id: troubleshooting.sgml,v 1.1.1.1.4.3 1996-06-19 20:28:28 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Troubleshooting<label id="troubleshooting"></heading> @@ -13,16 +13,16 @@ <p><descrip> <tag>Problem:</tag> A device is conflicting with - another or doesn't match the kernel's compiled-in IRQ or + another or does not 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 + compiled in (and matched by the hardware) before they will + work. We are working hard to eliminate as many of these + last hold-outs as we can, but it is not always as easy as it looks. <tag>Solution:</tag> There are several possible @@ -40,16 +40,16 @@ 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 + entirely if it is causing problems for other devices you would much rather have work. 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 + you are 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. + original hardware configuration that did not work. </descrip> @@ -62,8 +62,8 @@ 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 + This will not 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 + If you are installing for the first time, do not forget to (W)rite out your new boot blocks! :-) diff --git a/handbook/userppp.sgml b/handbook/userppp.sgml index 9f8525fbb4..b99f17d869 100644 --- a/handbook/userppp.sgml +++ b/handbook/userppp.sgml @@ -1,4 +1,4 @@ -<!-- $Id: userppp.sgml,v 1.3.2.1 1996-01-31 14:32:32 mpp Exp $ --> +<!-- $Id: userppp.sgml,v 1.3.2.2 1996-06-19 20:28:30 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <sect>Setting up user PPP<label id="userppp"> @@ -11,11 +11,11 @@ (and above). I hope this document turns into a collaborative effort, largely - because I am not really much of an authority on PPP. I've got + because I am not really much of an authority on PPP. I have got it working, and want to pass on details of what I did so that - other people can get it working. But I'm not 100% clear on some + other people can get it working. But I am not 100% clear on some details, so I hope that by writing this and having others - flesh out some of the information I'm going to learn something + flesh out some of the information I am going to learn something as well. --> @@ -27,7 +27,7 @@ <quote> This is a user process PPP software package. Normally, PPP is implemented as a part of the kernel (e.g. as managed by pppd) and - it's thus somewhat hard to debug and/or modify its behavior. However, + it is thus somewhat hard to debug and/or modify its behavior. However, in this implementation PPP is done as a user process with the help of the tunnel device driver (tun). </quote> @@ -50,7 +50,7 @@ <sect1><heading>Before you start</heading> -<p>This document assumes you're in roughly this position: +<p>This document assumes you are in roughly this position: You have an account with an Internet Service Provider (ISP) which lets you use PPP. Further, you have a modem (or other device) connected and @@ -77,7 +77,7 @@ your kernel. Check <ref id="kernelconfig" name="Kernel Configuration"> for more information on how to acquire these. - In addition, I've assumed that because your connection to the Internet is + In addition, I have assumed that because your connection to the Internet is not full time you are not running a name server (<tt>named(8)</tt>). <sect1><heading>Building a ppp ready kernel</heading> @@ -92,10 +92,13 @@ pseudo-device tun 1 </verb></tscreen> in it somewhere. The stock GENERIC kernel has this as standard, so if you - have not installed a custom kernel you don't have to change anything. + have not installed a custom kernel you do not have to change anything. If your kernel configuration file does not have this line in it then you should add the line, re-compile and then re-install the kernel. Boot from - this new kernel. + this new kernel. Please refer to the + <ref id="kernelconfig" name="Configuring the FreeBSD Kernel"> + section for more information on kernel configuration. + <sect1><heading>Check the tun device</heading> @@ -105,7 +108,7 @@ pseudo-device tun 1 below to reflect whichever device number you are using. The easiest way to make sure that the tun0 device is configured correctly is - to re-make it. To this end, execute the following commands, + to re-make it. To this end, execute the following commands: <tscreen><verb> # cd /dev # ./MAKEDEV tun0 @@ -118,7 +121,7 @@ pseudo-device tun 1 Confusingly, it appears that both user ppp and pppd (the kernel level implementation of PPP) both assume configuration files kept in /etc/ppp. However, the sample configuration files provided are good for - user ppp, so keep them around for reference. The easiest way to do this is, + user ppp, so keep them around for reference. The easiest way to do this is: <tscreen><verb> # cd /etc # mv ppp ppp.orig @@ -140,14 +143,14 @@ pseudo-device tun 1 into hostnames. It can be configured to look for maps that describe IP to hostname mappings in one of two places. - The first is a file called /etc/hosts (``hosts'' in section 5 of the - manual). The second is the Internet Domain Name Service, a distributed + The first is a file called <tt>/etc/hosts</tt> (<tt>man 5 hosts</tt>). + The second is the Internet Domain Name Service, a distributed data base, the discussion of which is beyond the realm of this document. The resolver is a set of system calls that do the mappings, and you have to tell them where to get their information - from. You do this by editing the file /etc/host.conf. Do - <bf>not</bf> call this file /etc/hosts.conf (note the extra + from. You do this by editing the file <tt>/etc/host.conf</tt>. Do + <bf>not</bf> call this file <tt>/etc/hosts.conf</tt> (note the extra ``s'') as the results can be confusing. This file should contain the following two lines, @@ -155,12 +158,13 @@ pseudo-device tun 1 hosts bind </verb></tscreen> - which instruct the resolver to look in the file /etc/hosts first, and - then to consult the DNS if the name was not found in the /etc/hosts file. + which instruct the resolver to look in the file <tt>/etc/hosts</tt> first, + and then to consult the DNS if the name was not found in the + <tt>/etc/hosts</tt> file. - It's probably a good idea to make sure you are not running the ``named'' - service. Check your /etc/sysconfig file for the line that refers to - ``namedflags'', and make sure the line reads + It is probably a good idea to make sure you are not running the ``named'' + service. Check your <tt>/etc/sysconfig</tt> file for the line that refers + to ``namedflags'', and make sure the line reads <tscreen><verb> namedflags="NO" </verb></tscreen> @@ -169,10 +173,11 @@ namedflags="NO" <p>This file should contain the IP addresses and names of machines on your network. At a bare minimum it should contain entries for the machine - which will be running ppp. Assuming that you're machine is called - foo.bar.com with the IP address 10.0.0.1, /etc/hosts should contain + which will be running ppp. Assuming that your machine is called + foo.bar.com with the IP address 10.0.0.1, <tt>/etc/hosts</tt> should + contain: <tscreen><verb> -127.0.0.0 localhost +127.0.0.1 localhost 10.0.0.1 foo.bar.com foo </verb></tscreen> The first line defines the alias ``localhost'' as a synonym for the @@ -188,13 +193,13 @@ namedflags="NO" <sect2><heading>Create the /etc/resolv.conf file</heading> -<p>/etc/resolv.conf contains some extra information required when you are - not running a nameserver. It points the resolver routines at real +<p><tt>/etc/resolv.conf</tt> contains some extra information required when + you are not running a nameserver. It points the resolver routines at real nameservers, and specifies some other information. - At the very least, /etc/resolv.conf should contain one line with a - nameserver which can be queried. You should enter this as an IP - address. My /etc/resolv.conf contains + At the very least, <tt>/etc/resolv.conf</tt> should contain one line with + a nameserver which can be queried. You should enter this as an IP + address. My <tt>/etc/resolv.conf</tt> contains: <tscreen><verb> nameserver 158.152.1.193 nameserver 158.152.1.65 @@ -205,13 +210,13 @@ nameserver 158.152.1.65 <sect1><heading>PPP and static IP addresses</heading> <p>Probably the easiest to configure for. You will need to create three files - in the /etc/ppp directory. + in the <tt>/etc/ppp</tt> directory. - The first of these is ppp.conf. It should look similar to the example - below. Note that lines that end in a ``:'' start in column 1, all other - lines should be indented as shown. + The first of these is <tt>ppp.conf</tt>. It should look similar to the + example below. Note that lines that end in a ``:'' start in column 1, all + other lines should be indented as shown. - /etc/ppp/ppp.conf + <tt>/etc/ppp/ppp.conf</tt> <tscreen><verb> 1 default: 2 set device /dev/cuaa0 @@ -226,29 +231,29 @@ nameserver 158.152.1.65 10 set timeout 120 11 set ifaddr x.x.x.x y.y.y.y </verb></tscreen> - Don't include the line numbers, they're just for this discussion. + Do not include the line numbers, they are just for this discussion. <descrip> <tag/Line 1:/ Identifies the default entry. Commands in this entry are executed automatically when ppp is run. <tag/Line 2:/ Identifies the device that has the modem hanging from it. - COM1: is /dev/cuaa0 and COM2: is /dev/cuaa1 + COM1: is <tt>/dev/cuaa0</tt> and COM2: is <tt>/dev/cuaa1</tt>. <tag/Line 3:/ Sets the speed you want to connect at. -<tag/* Lines 4 and 5:/ Don't know exactly what effect these lines have +<tag/* Lines 4 and 5:/ Do not know exactly what effect these lines have -<tag/Line 6:/ Dial string commands. user ppp uses the chat(8) language. Check - the manual page for information on the features of this - language. +<tag/Line 6:/ Dial string commands. user ppp uses the <tt>chat(8)</tt> + language. Check the manual page for information on the features + of this language. <tag/Line 7:/ Identifies an entry for a provider called ``provider''. -<tag/Line 8:/ Sets the phone number for this provider. Don't include any +<tag/Line 8:/ Sets the phone number for this provider. Do not include any spaces in the phone number. -<tag/Line 9:/ Set's the login string sequence. In this example, the string is +<tag/Line 9:/ Sets the login string sequence. In this example, the string is for a service who's login session looks like <tscreen><verb> J. Random Provider @@ -257,7 +262,7 @@ password: bar protocol: ppp </verb></tscreen> You will need to alter this script to suit your own needs. It is - written in the chat(8) language. + written in the <tt>chat(8)</tt> language. <tag/Line 10:/ Sets the default timeout (in seconds) for the connection. So the connection will be closed automatically after 120 seconds @@ -269,7 +274,7 @@ protocol: ppp ISP indicated for their gateway. </descrip> - Now you have to edit the file /etc/ppp/ppp.linkup: + Now you have to edit the file <tt>/etc/ppp/ppp.linkup</tt>: <tscreen><verb> x.x.x.x: add 0 0 HISADDR @@ -278,10 +283,10 @@ x.x.x.x: automatically add a default route from your ISP (who's address is automatically inserted with the HISADDR macro) to you. - Finally, you can create the file /etc/ppp/ppp.secret, which sets some - passwords to prevent people messing around with ppp on your system. You - may or may not want to do this, depending on how many people have access - to your ppp system. + Finally, you can create the file <tt>/etc/ppp/ppp.secret</tt>, which sets + some passwords to prevent people messing around with ppp on your system. + You may or may not want to do this, depending on how many people have + access to your ppp system. <sect1><heading>PPP and Dynamic IP configuration</heading> @@ -296,8 +301,9 @@ set ifaddr 0 0 <sect1><heading>Final system configuration</heading> -<p>You now have PPP configured, but there's a few more things to do before - it's ready to work. They all involve editing the /etc/sysconfig file. +<p>You now have PPP configured, but there are a few more things to do before + it is ready to work. They all involve editing the <tt>/etc/sysconfig</tt> + file. Working from the top down in this file, make sure the ``hostname='' line is set, e.g., @@ -327,7 +333,7 @@ ifconfig_tun0="inet foo.bar.com y.y.y.y netmask 0xffffffff" <tscreen><verb> routedflags=-s </verb></tscreen> - It's probably worth your while ensuring that the ``sendmail_flags'' line + It is probably worth your while ensuring that the ``sendmail_flags'' line does not include the ``-q'' option, otherwise sendmail will attempt to do a network lookup every now and then, possibly causing your machine to dial out. My sendmail line looks like @@ -340,7 +346,7 @@ sendmail_flags="-bd" # /usr/sbin/sendmail -q </verb></tscreen> That should be about all you need to do to get PPP working with a static - IP address. All that's left is to reboot the machine. During startup the + IP address. All that is left is to reboot the machine. During startup the tun0 device should be detected, and two lines like the following should be printed, <tscreen><verb> @@ -356,5 +362,5 @@ inet x.x.x.x --> y.y.y.y netmask 0xffffffff <tscreen><verb> # ppp -auto provider </verb></tscreen> - This line could be added to your /etc/rc.local file. + This line could be added to your <tt>/etc/rc.local</tt> file. |