diff options
| author | Doc Manager <doceng@FreeBSD.org> | 2000-11-21 10:28:00 +0000 |
|---|---|---|
| committer | Doc Manager <doceng@FreeBSD.org> | 2000-11-21 10:28:00 +0000 |
| commit | 49bcfc06a6ff4c91ddca135602a37eb1c2bdc059 (patch) | |
| tree | 27ff750a22725cc0b66e947fdb457ed1b127b2d5 /en_US.ISO8859-1 | |
| parent | a1548d0e3a573552e48642427219bb11815e0618 (diff) | |
| download | doc-49bcfc06a6ff4c91ddca135602a37eb1c2bdc059.tar.gz doc-49bcfc06a6ff4c91ddca135602a37eb1c2bdc059.zip | |
Create tag '4.2.0'.release/4.2.0
Notes
Notes:
svn path=/head/; revision=8401
svn path=/release/4.2.0/; revision=8402; tag=release/4.2.0
Diffstat (limited to 'en_US.ISO8859-1')
116 files changed, 0 insertions, 103784 deletions
diff --git a/en_US.ISO8859-1/Makefile b/en_US.ISO8859-1/Makefile deleted file mode 100644 index 0b2210c098..0000000000 --- a/en_US.ISO8859-1/Makefile +++ /dev/null @@ -1,9 +0,0 @@ -# $FreeBSD$ - -SUBDIR = articles -SUBDIR+= books - -COMPAT_SYMLINK = en - -DOC_PREFIX?= ${.CURDIR}/.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile deleted file mode 100644 index e1c5b47597..0000000000 --- a/en_US.ISO8859-1/articles/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/Makefile,v 1.7 2000/06/07 23:24:18 nik Exp $ - -SUBDIR = committers-guide -SUBDIR+= dialup-firewall -SUBDIR+= diskless-x -SUBDIR+= fonts -SUBDIR+= formatting-media -SUBDIR+= ipsec-must -SUBDIR+= mh -SUBDIR+= multi-os -SUBDIR+= new-users -SUBDIR+= programming-tools -SUBDIR+= zip-drive - -# ROOT_SYMLINKS+= new-users - -DOC_PREFIX?= ${.CURDIR}/../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/Makefile.inc b/en_US.ISO8859-1/articles/Makefile.inc deleted file mode 100644 index 68161e6d79..0000000000 --- a/en_US.ISO8859-1/articles/Makefile.inc +++ /dev/null @@ -1,5 +0,0 @@ -# -# $FreeBSD$ -# - -DESTDIR?= ${DOCDIR}/en_US.ISO_8859-1/articles/${.CURDIR:T} diff --git a/en_US.ISO8859-1/articles/committers-guide/Makefile b/en_US.ISO8859-1/articles/committers-guide/Makefile deleted file mode 100644 index a623572f3e..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/Makefile +++ /dev/null @@ -1,25 +0,0 @@ -# -# $FreeBSD$ -# -# Build the FreeBSD New Committers Guide -# - -MAINTAINER=jhb@FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml deleted file mode 100644 index deaec4435a..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ /dev/null @@ -1,2017 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> -%authors; -]> - -<article> - <artheader> - <title>Committer Guide</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.43 2000/11/03 19:01:27 sobomax Exp $</pubdate> - - <copyright> - <year>1999</year> - <year>2000</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - <abstract> - <para>This document provides information for the FreeBSD committer - community. All new committers should read this document before they - start, and existing committers are strongly encouraged to review it - from time to time.</para> - </abstract> - </artheader> - - <sect1 id="admin"> - <title>Administrative Details</title> - - <informaltable frame="none" orient="port"> - <tgroup cols="2"> - <tbody> - <row> - <entry><emphasis>Main Repository Host</emphasis></entry> - <entry><hostid>freefall.FreeBSD.org</hostid></entry> - </row> - - <row> - <entry><emphasis>Login Methods</emphasis></entry> - <entry>&man.ssh.1;</entry> - </row> - - <row> - <entry><emphasis>Main CVSROOT</emphasis></entry> - <entry>/home/ncvs</entry> - </row> - - <row> - <entry><emphasis>Main CVS Repository Meisters</emphasis></entry> - <entry>&a.jdp; and &a.peter; as well as &a.asami; for - <filename>ports/</filename></entry> - </row> - - <row> - <entry><emphasis>Mailing List</emphasis></entry> - <entry><email>developers@FreeBSD.org</email></entry> - <entry><email>cvs-committers@FreeBSD.org</email></entry> - </row> - - <row> - <entry><emphasis>Noteworthy CVS Tags</emphasis></entry> - <entry>RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>It is required that you use &man.ssh.1; or &man.telnet.1; - with Kerberos 5 to connect to the repository hosts. These are - generally more secure than plain &man.telnet.1; or - &man.rlogin.1; since credential negotiation will always be - encrypted. All traffic is encrypted by default with &man.ssh.1;. - With utilities like &man.ssh-agent.1; and &man.scp.1; also - available, &man.ssh.1; is also far more convenient. If you do - not know anything about &man.ssh.1;, please see - <xref linkend="ssh.guide">.</para> - </sect1> - - <sect1 id="cvs.operations"> - <title>CVS Operations</title> - - <para>It is assumed that you are already familiar with the basic operation - of CVS.</para> - - <para>The CVS Repository Meisters (Peter Wemm and John Polstra) - are the <quote>owners</quote> of the CVS repository and are - responsible for any and <emphasis>all</emphasis> direct - modification of it for the purposes of cleanup or fixing some - grievous abuse of CVS by a committer. No one else should - attempt to touch the repository directly. Should you cause some - repository accident, say a bad cvs import or tag operation, do - <emphasis role="bold">not</emphasis> attempt to fix it yourself! - Mail or call John or Peter immediately and report the problem to - one of them instead. The only ones allowed to directly fiddle - the repository bits are the repomeisters. Satoshi Asami is also a - repomeister for the <filename>ports/</filename> portion of the - tree.</para> - - <para>CVS operations are usually done by logging into - <hostid>freefall</hostid>, making sure the - <envar>CVSROOT</envar> environment variable is set to - <filename>/home/ncvs</filename>, and then doing the appropriate - check-out/check-in operations. If you wish to add - something which is wholly new (like contrib-ified - sources, etc), a script called <quote>easy-import</quote> is - also provided for making the process easier. It automatically - adds the new module entry, does the appropriate thing with - <command>cvs import</command>, etc. – just run it without - arguments and it will prompt you for everything it needs to - know.</para> - - <para>Note that when you use CVS on <hostid>freefall</hostid>, you - should set your <literal>umask</literal> to <literal>2</literal>, - as well as setting the <literal>CVSUMASK</literal> environmenet - variable to <literal>2</literal>. This ensures that any new - files created by <command>cvs add</command> will have the correct - permissions. If you add a file or directory and discover that the - file in the repository has incorrect permissions (specifically, - all files in the repository should be group writable by group - <literal>ncvs</literal>), contact one of the repository meisters - as described below.</para> - - <para>If you are familiar with remote CVS and consider yourself - pretty studly with CVS in general, you can also do CVS - operations directly from your own machine and local working - sources. Just remember to set <envar>CVS_RSH</envar> to - <wordasword>ssh</wordasword> so that you are using a relatively - secure and reliable transport. If you have no idea what any of - the above even means, on the other hand, then please stick with - logging into <hostid>freefall</hostid> and applying your diffs - with &man.patch.1;.</para> - - <para>If you need to use CVS <command>add</command> and - <command>delete</command> operations in a manner that is - effectively a <quote>mv</quote> operation, then a repository - copy is in order rather than your CVS <command>add</command> and - <command>delete</command>. In a repository copy, a <link - linkend="conventions">CVS Meister</link> will copy the file(s) - to their new name and/or location and let you know when it is - done. The purpose of a repository copy is to preserve file - change history, or logs. We in the FreeBSD Project greatly - value the change history CVS gives to the project.</para> - - <para>CVS reference information, tutorials, and FAQs can also be found at: - <ulink - url="http://www.cyclic.com/CVS/support">http://www.cyclic.com/CVS/support</ulink></para> - - <para>&a.des; also supplied the following <quote>mini primer</quote> for - CVS.</para> - - <orderedlist> - <listitem> - <para>Check out a module with the <literal>co</literal> or - <literal>checkout</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen> - - <para>This checks out a copy of the <filename>shazam</filename> module. If - there is no <filename>shazam</filename> module in the modules file, looks for a - top-level directory named <filename>shazam</filename> instead.</para> - - <para>Useful options:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-P</option></entry> - <entry>Don't create empty directories</entry> - </row> - - <row> - <entry><option>-l</option></entry> - <entry>Check out a single level, no subdirectories</entry> - </row> - - <row> - <entry><option>-r<replaceable>rev</replaceable></option></entry> - <entry>Check out revision, branch or tag - <replaceable>rev</replaceable></entry> - </row> - - <row> - <entry><option>-D<replaceable>date</replaceable></option></entry> - <entry>Check out the sources as they were on date - <replaceable>data</replaceable></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Practical FreeBSD examples:</para> - - <itemizedlist> - <listitem> - <para>Check out the <filename>miscfs</filename> module, - which corresponds to <filename>src/sys/miscfs</filename>:</para> - - <screen>&prompt.user; <userinput>cvs co miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with subdirectories <filename>CVS</filename>, - <filename>deadfs</filename>, <filename>devfs</filename>, and so - on. One of these (<filename>linprocfs</filename>) is - empty.</para> - </listitem> - - <listitem> - <para>Check out the same files, but with full path:</para> - - <screen>&prompt.user; <userinput>cvs co src/sys/miscfs</userinput></screen> - - <para>You now have a directory named <filename>src</filename>, - with subdirectories <filename>CVS</filename> and - <filename>sys</filename>. <filename>src/sys</filename> has - subdirectories <filename>CVS</filename> and - <filename>miscfs</filename>, etc.</para> - </listitem> - - <listitem> - <para>Check out the same files, but prunes empty - directories:</para> - - <screen>&prompt.user; <userinput>cvs co -P miscfs</userinput></screen> - - <para>You now have a directory named - <filename>miscfs</filename> with subdirectories - <filename>CVS</filename>, <filename>deadfs</filename>, - <filename>devfs</filename>... but note that there is no - <filename>linprocfs</filename> subdirectory, because there - are no files in it.</para> - </listitem> - - <listitem> - <para>Check out the directory <filename>miscfs</filename>, but - none of the subdirectories:</para> - - <screen>&prompt.root; <userinput>cvs co -l miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with just one subdirectory named - <filename>CVS</filename>.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it is in the 4.x branch:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 miscfs</userinput></screen> - - <para>You can modify the sources and commit along this - branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it was in 3.4-RELEASE.</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_3_4_0_RELEASE miscfs</userinput></screen> - - <para>You will not be able to commit modifications, since - RELENG_3_4_0_RELEASE is a point in time, not a branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - on Jan 15 2000.</para> - - <screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - one week agao.</para> - - <screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - </itemizedlist> - - <para>Note that cvs stores metadata in subdirectories named - <filename>CVS</filename>.</para> - - <para>Arguments to <option>-D</option> and <option>-r</option> - are sticky, which means cvs will remember them later, e.g. - when you do a <command>cvs update</command>.</para> - </listitem> - - <listitem> - <para>Check the status of checked-out files with the - <literal>status</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs status shazam</userinput></screen> - - <para>This displays the status of the - <filename>shazam</filename> file or of every file in the - <filename>shazam</filename> directory. For every file, the - status is given as one of:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry>Up-to-date</entry> - <entry>File is up-to-date and unmodified.</entry> - </row> - - <row> - <entry>Needs Patch</entry> - <entry>File is unmodified, but there's a newer revision in - the repository.</entry> - </row> - - <row> - <entry>Locally Modified</entry> - <entry>File is up-to-date, but modified.</entry> - </row> - - <row> - <entry>Needs Merge</entry> - <entry>File is modified, and there's a newer revision in the - repository.</entry> - </row> - - <row> - <entry>File had conflicts on merge</entry> - <entry>There were conflicts the last time this file was - updated, and they haven't been resolved yet.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>You'll also see the local revision and date, - the revision number of the newest applicable version - (<quote>newest applicable</quote> because if you have a - sticky date, tag or branch, it may not be the actual newest - revision), and any sticky tags, dates or options.</para> - </listitem> - - <listitem> - <para>Once you've checked something out, update it with the - <literal>update</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs update shazam</userinput></screen> - - <para>This updates the <filename>shazam</filename> file or the - contents of the <filename>shazam</filename> directory to the - latest version along the branch you checked out. If you - checked out a <quote>point in time</quote>, does nothing - unless the tags have moved in the repo or some other weird - stuff is going on.</para> - - <para>Useful options, in addition to those listed above for - <literal>checkout</literal>:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-d</option></entry> - <entry>Check out any additional missing directories.</entry> - </row> - - <row> - <entry><option>-A</option></entry> - <entry>Update to head of main branch.</entry> - </row> - - <row> - <entry><option>-j<replaceable>rev</replaceable></option></entry> - <entry>More magic (see below).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If you checked out a module with <option>-r</option> or - <option>-D</option>, running <command>cvs update</command> - with a different <option>-r</option> or <option>-D</option> - argument or with <option>-A</option> will select a new branch, - revision or date. The <option>-A</option> option clears all - sticky tags, dates or revisions whereas <option>-r</option> - and <option>-D</option> set new ones.</para> - - <para>Theoretically, specifying <literal>HEAD</literal> as - argument to <option>-r</option> will give you the same result - as <option>-A</option>, but that's just theory.</para> - - <para>The <option>-d</option> option is useful if:</para> - - <itemizedlist> - <listitem> - <para>somebody has added subdirectories to the module - you've checked out after you checked it out.</para> - </listitem> - - <listitem> - <para>you checked out with <option>-l</option>, and later - change your mind and want to check out the subdirectories - as well.</para> - </listitem> - - <listitem> - <para>you deleted some subdirectories and want to check - them all back out.</para> - </listitem> - </itemizedlist> - - <para><emphasis>Watch the output of the <command>cvs - update</command> with care.</emphasis> The letter in front of - each file name indicates what was done with it:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry><literal>U</literal></entry> - <entry>The file was updated with no trouble.</entry> - </row> - - <row> - <entry><literal>P</literal></entry> - <entry>The file was updated with no trouble (you'll only see - this when working against a remote repo).</entry> - </row> - - <row> - <entry><literal>M</literal></entry> - <entry>The file had been modified, and was merged with no - conflicts.</entry> - </row> - - <row> - <entry><literal>C</literal></entry> - <entry>The file had been modified, and was merged with - conflicts.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Merging is what happens if you check out a copy of - some source code, modify it, then someone else commits a - change, and you run <command>cvs update</command>. CVS notices - that you've made local changes, and tries to merge your - changes with the changes between the version you originally - checked out and the one you updated to. If the changed are to - separate portions of the file, it'll almost always work fine - (though the result might not be syntactically or semantically - correct).</para> - - <para>CVS will print an 'M' in front of every locally modified - file even if there is no newer version in the repository, so - <command>cvs update</command> is handy for getting a summary - of what you've changed locally.</para> - - <para>If you get a <literal>C</literal>, then your changes - conflicted with the changes in the repository (the changes - were to the same lines, or neighboring lines, or you changed - the local file so much that <command>cvs</command> can't - figure out how to apply the repository's changes). You'll have - to go through the file manually and resolve the conflicts; - they'll be marked with rows of <literal><</literal>, - <literal>=</literal> and <literal>></literal> signs. For - every conflict, there'll be a marker line with seven - <literal><</literal> signs and the name of the file, - followed by a chunk of what your local file contained, - followed by a separator line with seven <literal>=</literal> - signs, followed by the corresponding chunk in the - repository version, followed by a marker line with seven - <literal>></literal> signs and the revision number you - updated to.</para> - - <para>The <option>-j</option> option is slightly voodoo. It - updates the local file to the specified revision as if you - used <option>-r</option>, but it does not change the recorded - revision number or branch of the local file. It's not really - useful except when used twice, in which case it will merge the - changes between the two specified versions into the working - copy.</para> - - <para>For instance, say you commit a change to - <filename>shazam/shazam.c</filename> in -CURRENT and later - want to MFC it. The change you want to MFC was revision - 1.15:</para> - - <itemizedlist> - <listitem> - <para>Check out the -STABLE version of the - <filename>shazam</filename> module:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 shazam</userinput></screen> - </listitem> - - <listitem> - <para>Apply the changes between rev 1.14 and 1.15:</para> - - <screen>&prompt.user; <userinput>cvs update -j1.14 -j1.15 shazam/shazam.c</userinput></screen> - </listitem> - </itemizedlist> - - <para>You'll almost certainly get a conflict because - of the <literal>$Id: article.sgml,v 1.44 2000-11-14 11:11:56 demon Exp $</literal> (or in FreeBSD's case, - <literal>$FreeBSD<!-- stop expansion -->$</literal>) lines, so you'll have to edit - the file to resolve the conflict (remove the marker lines and - the second <literal>$Id: article.sgml,v 1.44 2000-11-14 11:11:56 demon Exp $</literal> line, leaving the original - <literal>$Id: article.sgml,v 1.44 2000-11-14 11:11:56 demon Exp $</literal> line intact).</para> - </listitem> - - <listitem> - <para>View differences between the local version and the - repository version with the <literal>diff</literal> - command.</para> - - <screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen> - - <para>shows you every modification you've made to the - <filename>shazam</filename> file or module.</para> - - <para>Useful options:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-u</option></entry> - <entry>Uses the unified diff format.</entry> - </row> - - <row> - <entry><option>-N</option></entry> - <entry>Shows missing or added files.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>You always want to use <option>-u</option>, since - unified diffs are much easier to read than almost any other - diff format (in some circumstances, context diffs may be - better, but they're much bulkier). A unified diff consists of - a series of hunks. Each hunk begins with a line that starts - with two <literal>@</literal> signs and specifies where in the - file the differences are and how many lines they span. This - is followed by a number of lines; some (preceded by a blank) - are context; some (preceded by a <literal>-</literal> sign) - are outtakes and some (preceded by a <literal>+</literal>) are - additions.</para> - - <para>You can also diff against a different version - than the one you checked out by specifying a version - with <option>-r</option> or <option>-D</option> as in - <literal>checkout</literal> or <literal>update</literal>, - or even view the diffs between two arbitrary versions - (with no regard for what you have locally) by specifying - <emphasis>two</emphasis> versions with <option>-r</option> or - <option>-D</option>.</para> - </listitem> - - <listitem> - <para>View log entries with the <literal>log</literal> - command.</para> - - <!-- XXX needs more details --> - <screen>&prompt.user; <userinput>cvs log shazam</userinput></screen> - </listitem> - - <listitem> - <para>See who did what with the <literal>annotate</literal> command. - This command shows you each line of the specified file or - files, along with which user most recently changed that - line.</para> - - <screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen> - </listitem> - - <listitem> - <para>Add new files with the <literal>add</literal> command.</para> - - <para>Create the file, <command>cvs add</command> it, then - <command>cvs commit</command> it.</para> - - <para>Similarly, you can add new directories by creating them - and then <command>cvs add</command>ing them. Note that you - don't need to commit directories.</para> - </listitem> - - <listitem> - <para>Remove obsolete files with the <literal>remove</literal> command.</para> - - <para>Remove the file, then <command>cvs rm</command> it, then - <command>cvs commit</command> it.</para> - </listitem> - - <listitem> - <para>Commit with the <literal>commit</literal> or - <literal>checkin</literal> command.</para> - - <para>Useful options:</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-f</option></entry> - <entry>Force a commit of an unmodified file.</entry> - </row> - - <row> - <entry><option>-m<replaceable>msg</replaceable></option></entry> - <entry>Specify a commit message on the command line rather - than invoking an editor.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Use the <option>-f</option> option if you realize that - you left out important information from the commit message.</para> - - <para>Good commit messages are important. They tell others - why you did the changes you did, not just right here and now, - but months or years from now when someone wonders why some - seemingly illogical or inefficient piece of code snuck into - your source file. It's also an invaluable aid to deciding - which changes to MFC and which not to MFC.</para> - - <para>Don't waste space in the commit messages explaining - <emphasis>what</emphasis> you did. That's what - <command>cvs diff</command> is for. Instead, tell us - <emphasis>why</emphasis> you did it.</para> - - <para>Avoid committing several unrelated changes in one go. It - makes merging difficult, and also makes it harder to determine - which change is the culprit if a bug crops up.</para> - - <para>Avoid committing style or whitespace fixes and - functionality fixes in one go. It makes merging difficult, - and also makes it harder to understand just what functional - changes were made.</para> - - <para>Avoid committing changes to multiple files in one go - with a generic, vague message. Instead, commit each file (or - small groups of files) with tailored commit messages.</para> - - <para>Before committing, <emphasis>always</emphasis>:</para> - - <itemizedlist> - <listitem> - <para>verify which branch you're committing to, using - <command>cvs status</command>.</para> - </listitem> - - <listitem> - <para>review your diffs, using - <command>cvs diff</command></para> - </listitem> - </itemizedlist> - - <para>Also, ALWAYS specify which files to commit explicitly on - the command line, so you don't accidentally commit other files - than the ones you intended - <command>cvs commit</command> - with no arguments will commit every modification in your - current working directory and every subdirectory.</para> - </listitem> - </orderedlist> - - <para>Additional tips and tricks:</para> - - <orderedlist> - <listitem> - - <para>You can place commonly used options in your - <filename>~/.cvsrc</filename>, like this:</para> - - <programlisting>cvs -z3 -diff -Nu -update -Pd -checkout -P</programlisting> - - <para>This example says:</para> - - <itemizedlist> - <listitem> - <para>always use compression level 3 when talking to a - remote server. This is a life-saver when working over a - slow connection.</para> - </listitem> - - <listitem> - <para>always use the <option>-N</option> (show added or - removed files) and <option>-u</option> (unified diff - format) options to &man.diff.1;.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) and <option>-d</option> (check out new - directories) options when updating.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) option when checking out.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Use Eivind Eklund's <command>cdiff</command> script to - view unidiffs. It's a wrapper for &man.less.1; that adds ANSI - color codes to make hunk headers, outtakes and additions stand - out; context and garbage are unmodified. It also expands tabs - properly (tabs often look wrong in diffs because of the extra - character in front of each line).</para> - -<para><ulink url="http://people.freebsd.org/~eivind/cdiff">http://people.freebsd.org/~eivind/cdiff</ulink></para> - - <para>Simply use instead of &man.more.1; or &man.less.1;:</para> - - <screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen> - - <para>Alternatively some editors like &man.vim.1; - (ports/editors/vim5) have color support and when used as - a pager with color syntax highlighting switched on will - highlight many types of file, including diffs, patches, - and cvs/rcs logs. </para> - - <screen>&prompt.user; <userinput> echo "syn on" >> ~/.vimrc </userinput> -&prompt.user; <userinput> cvs diff -Nu shazam | vim -</userinput> -&prompt.user; <userinput> cvs log shazam | vim -</userinput> </screen> - </listitem> - - <listitem> - <para>CVS is old, arcane, crufty and buggy, and sometimes - exhibits non-deterministic behavior which some claim as proof - that it's actually merely the newtonian manifestation of a - sentient transdimensional entity. It's not humanly possible - to know its every quirk inside out, so don't be afraid to ask - the resident AI (<email>cvs@FreeBSD.org</email>) for help when - you screw up.</para> - </listitem> - - <listitem> - <para>Don't leave the <command>cvs commit</command> command in commit - message editing mode for too long (more than 2-3 minutes). It - locks the directory you are working with and will prevent other - developers from committing into the same directory. If you have - to type a long commit message, type it before executing - <command>cvs commit</command>, and insert it into the commit - message.</para> - </listitem> - </orderedlist> - - </sect1> - - <sect1 id="conventions"> - <title>Conventions and Traditions</title> - - <para>As a new committer there are a number of things you should do - first.</para> - - <itemizedlist> - <listitem> - <para>Add yourself to the <quote>Developers</quote> section of the - Handbook and remove yourself from the <quote>Additional - Contributors</quote> section.</para> - - <para>This is a relatively easy task, but remains a good first test of - your CVS skills.</para> - </listitem> - - <listitem> - <para>Add an entry for yourself to - <filename>www/en/news/newsflash.sgml</filename>. Look for the other - entries that look like <quote>A new committer</quote> and follow the - format.</para> - </listitem> - - <listitem> - <para>Some people also add an entry for themselves to - <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para> - </listitem> - - <listitem> - <para>Introduce yourself to the other committers, otherwise no one - will have any idea who you are or what you are working on. You do - not have to write a comprehensive biography, just write a paragraph - or two about who you are and what you plan to be working on as a - committer in FreeBSD. Email this to - <email>developers@FreeBSD.org</email> and you will be on your - way!</para> - </listitem> - - <listitem> - <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a - <filename>/var/forward/<replaceable>user</replaceable></filename> - (where <replaceable>user</replaceable> is your username) file - containing the e-mail address where you want mail addressed to - <replaceable>yourusername</replaceable>@FreeBSD.org to be forwarded. - This includes all of the commit messages as well as any other mail - addressed to <email>cvs-committers@FreeBSD.org</email> and - <email>developers@FreeBSD.org</email>. Really - large mailboxes which have taken up permanent residence on - <hostid>hub</hostid> often get <quote>accidently</quote> truncated - without warning, so forward it or read it and you will not lose - it.</para> - </listitem> - </itemizedlist> - - <para>All new committers also have a mentor assigned to them for - the first few months. Your mentor is more or less responsible for - explaining anything which is confusing to you and is also - responsible for your actions during this initial period. If you - make a bogus commit, it is only going to embarrass your mentor - and you should probably make it a policy to pass at least your - first few commits by your mentor before committing it to the - repository.</para> - - <para>All commits should go to <literal>-CURRENT</literal> first - before being merged to <literal>-STABLE</literal>. No major new - features or high-risk modifications should be made to the - <literal>-STABLE</literal> branch.</para> - </sect1> - - <sect1 id="developer.relations"> - <title>Developer Relations</title> - - <para>If you are working directly on your own code or on code - which is already well established as your responsibility, then - there is probably little need to check with other committers - before jumping in with a commit. If you see a bug in an area of - the system which is clearly orphaned (and there are a few such - areas, to our shame), the same applies. If, however, you are - about to modify something which is clearly being actively - maintained by someone else (and it is only by watching the - <literal>cvs-committers</literal> mailing list that you can - really get a feel for just what is and is not) then consider - sending the change to them instead, just as you would have - before becoming a committer. For ports, you should contact the - listed <makevar>MAINTAINER</makevar> in the - <filename>Makefile</filename>. For other parts of the - repository, if you are unsure who the active maintainer might - be, it may help to scan the output of <command>cvs log</command> - to see who has committed changes in the past. &a.fenner; has - written a nice shell script that can help determine who the - active maintainer might be. It lists each person who has - committed to a given file along with the number of commits each - person has made. It can be found on <hostid>freefall</hostid> - at <filename>~fenner/bin/whodid</filename>. If your queries go - unanswered or the committer otherwise indicates a lack of - proprietary interest in the area affected, go ahead and commit - it.</para> - - <para>If you are unsure about a commit for any reason at - all, have it reviewed by <literal>-hackers</literal> - before committing. Better to have it flamed then and there - rather than when it is part of the CVS repository. If you do - happen to commit something which results in controversy - erupting, you may also wish to consider backing the change out - again until the matter is settled. Remember – with CVS we - can always change it back.</para> - </sect1> - - <sect1 id="gnats"> - <title>GNATS</title> - - <para>The FreeBSD Project utilizes - <application>GNATS</application> for tracking bugs and change - requests. Be sure that if you commit a fix or suggestion found - in a <application>GNATS</application> PR, you use - <command>edit-pr <replaceable>pr-number</replaceable></command> - on <hostid>freefall</hostid> to close it. It is also considered - nice if you take time to close any PRs associated with your - commits, if appropriate. Your can also make use of - &man.send-pr.1; yourself for proposing any change which you feel - should probably be made, pending a more extensive peer-review - first.</para> - - <para>You can find out more about <application>GNATS</application> - at:</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para> - </listitem> - - <listitem> - <para>&man.send-pr.1;</para> - </listitem> - </itemizedlist> - - <para>You can run a local copy of GNATS, and then integrate the FreeBSD - GNATS tree in to it using CVSup. Then you can run GNATS commands - locally, or use other interfaces, such as <command>tkgnats</command>. - This lets you query the PR database without needing to be connected to - the Internet.</para> - - <procedure> - <title>Using a local GNATS tree</title> - - <step> - <para>If you are not already downloading the GNATS tree, add this line - to your <filename>supfile</filename>, and re-sup. Note that since - GNATS is not under CVS control it has no tag, so if you are adding - it to your existing <filename>supfile</filename> it should appear - before any <quote>tag=</quote> entry as these remain active once set. - </para> - - <programlisting>gnats release=current prefix=/usr</programlisting> - - <para>This will place the FreeBSD GNATS tree in - <filename>/usr/gnats</filename>. You can use a - <emphasis>refuse</emphasis> file to control which categories to - receive. For example, to only receive <literal>docs</literal> PRs, - put this line in - <filename>/usr/local/etc/cvsup/sup/refuse</filename><footnote> - <para>The precise path depends on the <literal>*default - base</literal> setting in your - <filename>supfile</filename>.</para> - </footnote>.</para> - - <programlisting>gnats/[a-ce-z]*</programlisting> - - <para>The rest of these examples assume you have only supped the - <literal>docs</literal> category. Adjust them as necessary, - depending on the categories you are synching.</para> - </step> - - <step> - <para>Install the GNATS port from - <filename>ports/databases/gnats</filename>. This will place the - various GNATS directories under - <filename>$PREFIX/share/gnats</filename>.</para> - </step> - - <step> - <para>Symlink the GNATS directories you are supping under the version - of GNATS you have installed.</para> - - <screen>&prompt.root; <userinput>cd /usr/local/share/gnats/gnats-db</userinput> -&prompt.root; <userinput>ln -s /usr/gnats/docs</userinput></screen> - - <para>Repeat as necessary, depending on how many GNATS categories you - are synching.</para> - </step> - - <step> - <para>Update the GNATS <filename>categories</filename> file with these - cageories. The file is - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/categories</filename>.</para> - - <programlisting># This category is mandatory -pending:Category for faulty PRs:gnats-admin: -# -# FreeBSD categories -# -docs:Documentation Bug:nik:</programlisting> - </step> - - <step> - <para>Run <filename>$PREFIX/libexec/gnats/gen-index</filename> to - recreate the GNATS index. The output has to be redirected to - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/index</filename>. - You can do this periodically from &man.cron.8;, or run &man.cvsup.1; - from a shell script that does this as well.</para> - - <screen>&prompt.root; <userinput>/usr/local/libexec/gnats/gen-index \ - > /usr/local/share/gnats/gnats-db/gnats-adm/index</userinput></screen> - </step> - - <step> - <para>Test the configuration by querying the PR database. This - command shows open <literal>docs</literal> PRs.</para> - - <screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen> - - <para>Other interfaces, like - <filename>ports/databases/tkgnats</filename> should also work - nicely.</para> - </step> - - <step> - <para>Pick a PR and close it.</para> - </step> - </procedure> - - <note> - <para>This procedure only works to allow you to view and query the PRs - locally. To edit or close them you will still have to log in to - <hostid>freefall</hostid> and do it from there.</para> - </note> - </sect1> - - <sect1 id="people"> - <title>Who's Who</title> - - <para>Besides Peter Wemm and John Polstra, the repository - meisters, there are other FreeBSD project members whom you will - probably get to know in your role as a committer. Briefly, - and by no means all-inclusively, these are:</para> - - <variablelist> - <varlistentry> - <term>&a.asami;</term> - - <listitem> - <para>Satoshi is the Ports Wraith, meaning that he has - ultimate authority over any modifications to the ports - collection or the ports skeleton makefiles. He is also - the one responsible for administering ports freezes before - the releases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.bde;</term> - - <listitem> - <para>Bruce is the Obersturmbahnfuhrer of the Style Police. - When you do a commit that could have been done better, - Bruce will be there to tell you. Be thankful that someone - is.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dg;</term> - - <listitem> - <para>David is the overseer of the - VM system. If you have a VM system change in mind, - coordinate it with David.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jkh;</term> - - <listitem> - <para>Jordan is the release engineer. He is responsible for - setting release deadlines and controlling the release - process. During code freezes, he also has final authority - on all changes to the system for whichever branch is - pending release status. If there is something you want - merged from <literal>-CURRENT</literal> to - <literal>-STABLE</literal> (whatever values those may have - at any given time), he is also the one to talk to about - it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.steve;</term> - - <listitem> - <para>Steve is the unofficial maintainer of - <filename>src/bin</filename>. If you have something - significant you'd like to do there, you should probably - coordinate it with Steve first. He is also a Problem - Report-meister, along with &a.phk;.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.brian;</term> - - <listitem> - <para>Official maintainer of - <filename>/usr/bin/ppp</filename> and LPD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.wollman;</term> - - <listitem> - <para>If you need advice on obscure network internals or - aren't sure of some potential change to the networking - subsystem you have in mind, Garrett is someone to talk - to.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="ssh.guide"> - <title>SSH Quick-Start Guide</title> - - <procedure> - <step> - <para>If you are using FreeBSD 4.0 or later, - OpenSSH is included in the base system. - If you are using an earlier release, - update and install one of the SSH ports. In general, - you will probably want to get OpenSSH from the port in - <filename>/usr/ports/security/openssh</filename>. You - may also wish to check out the original ssh1 in - <filename>/usr/ports/security/ssh</filename>, but make - certain you pay attention to its license. Note that both - of these ports cannot be installed at the same time.</para> - </step> - - <step> - <para>If you do not wish to type your password in every - time you use &man.ssh.1;, and you use RSA keys to - authenticate, &man.ssh-agent.1; is there for your - convenience. If you want to use &man.ssh-agent.1;, make - sure that you run it before running other applications. X - users, for example, usually do this from their - <filename>.xsession</filename> or - <filename>.xinitrc</filename> file. See &man.ssh-agent.1; - for details.</para> - </step> - - <step> - <para>Generate a key pair using &man.ssh-keygen.1;. The key - pair will wind up in the - <filename><envar>$HOME</envar>/.ssh</filename> - directory.</para> - </step> - - <step> - <para>Send your public key - (<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>) - to the person setting you up as a committer so it can be put - into your <filename>authorized_keys</filename> file in your - home directory on <hostid>freefall</hostid> - (i.e. - <filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>). - </para> - </step> - </procedure> - - <para>Now you should be able to use &man.ssh-add.1; for - authentication once per session. This will prompt you for - your private key's pass phrase, and then store it in your - authentication agent (&man.ssh-agent.1;). If you no longer - wish to have your key stored in the agent, issuing - <command>ssh-add -d</command> will remove it.</para> - - <para>Test by doing something such as <command>ssh - freefall.FreeBSD.org ls /usr</command>.</para> - - <para>For more information, see - <filename>/usr/ports/security/openssh</filename>, &man.ssh.1;, - &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and - &man.scp.1;.</para> - </sect1> - - <sect1> - <title>The FreeBSD Committers' Big List of Rules</title> - - <orderedlist> - <listitem> - <para>Respect other committers.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - </listitem> - - <listitem> - <para>Respect existing maintainers if listed in the - (<makevar>MAINTAINER</makevar> field in - <filename>Makefile</filename> or in the - <filename>MAINTAINER</filename> file in the top-level - directory).</para> - </listitem> - - <listitem> - <para>Never touch the repository directly. Ask a - Repomeister.</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - </listitem> - - <listitem> - <para>Changes go to <literal>-CURRENT</literal> before - <literal>-STABLE</literal> unless specifically permitted by - the release engineer or unless they're not applicable to - <literal>-CURRENT</literal>. Any non-trivial or non-urgent - change which is applicable should also be allowed to sit in - <literal>-CURRENT</literal> for at least 3 days before - merging so that it can be given sufficient testing. The - release engineer has the same authority over the - <literal>-STABLE</literal> branch as outlined for the - maintainer in rule #5.</para> - </listitem> - - <listitem> - <para>Don't fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> mailing list on a timely basis - so you know when a code freeze is in effect.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - </listitem> - </orderedlist> - - <para>As noted, breaking some of these rules can be grounds for - suspension or, upon repeated offense, permanent removal of - commit privileges. Three or more members of core - acting in unison, - have the power to temporarily suspend commit privileges until - <literal>-core</literal> as a whole has the chance to review the - issue. In case of an <quote>emergency</quote> (a committer - doing damage to the repository), a temporary suspension may also - be done by the repository meisters or any other member of core - who may happen to be awake at the time. Only core as a whole - has the authority to suspend commit privileges for any - significant length of time or to remove them permanently, the - latter generally only being done after consultation with - committers. This rule does not exist to set core up as a bunch - of cruel dictators who can dispose of committers as casually as - empty soda cans, but to give the project a kind of safety fuse. - If someone is seriously out of control, it's important to be - able to deal with this immediately rather than be paralyzed by - debate. In all cases, a committer whose privileges are - suspended or revoked is entitled to a <quote>hearing</quote>, - the total duration of the suspension being determined at that - time. A committer whose privileges are suspended may also - request a review of the decision after 30 days and every 30 days - thereafter (unless the total suspension period is less than 30 - days). A committer whose privileges have been revoked entirely - may request a review after a period of 6 months have elapsed. - This review policy is <emphasis>strictly informal</emphasis> - and, in all cases, core reserves the right to either act on or - disregard requests for review if they feel their original - decision to be the right one.</para> - - <para>In all other aspects of project operation, core is a subset - of committers and is bound by the <emphasis>same - rules</emphasis>. Just because someone is in core doesn't mean - that they have special dispensation to step outside of any of - the lines painted here; core's <quote>special powers</quote> - only kick in when it acts as a group, not on an individual - basis. As individuals, we are all committers first and core - second.</para> - - <sect2> - <title>Details</title> - - <orderedlist> - <listitem> - <para>Respect other committers.</para> - - <para>This means that you need to treat other committers as - the peer-group developers that they are. Despite our - occasional attempts to prove the contrary, one doesn't get - into committers by being stupid and nothing rankles more - than being treated that way by one of your peers. Whether - we always feel respect for one another or not (and - everyone has off days), we still have to - <emphasis>treat</emphasis> other committers with respect - at all times or the whole team structure rapidly breaks - down.</para> - - <para>Being able to work together long term is this project's - greatest asset, one far more important than any set of - changes to the code, and turning arguments about code into - issues that affect our long-term ability to work - harmoniously together is just not worth the trade-off by - any conceivable stretch of the imagination.</para> - - <para>To comply with this rule, don't send email when you're - angry or otherwise behave in a manner which is likely to - strike others as needlessly confrontational. First calm - down, then think about how to communicate in the most - effective fashion for convincing the other person(s) that - your side of the argument is correct, don't just blow off - some steam so you can feel better in the short term at the - cost of a long-term flame war. Not only is this very bad - <quote>energy economics</quote>, but repeated displays of - public aggression which impair our ability to work well - together will be dealt with severely by the project - leadership and may result in suspension or termination of - your commit privileges. That's never an option which the - project's leadership enjoys in the slightest, but unity - comes first. No amount of code or good advice is worth - trading that away.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - - <para>The CVS repository is not where changes should be - initially submitted for correctness or argued over, that - should happen first in the mailing lists and then - committed only once something resembling consensus has - been reached. This doesn't mean that you have to ask - permission before correcting every obvious syntax error or - man page misspelling, simply that you should try to - develop a feel for when a proposed change isn't quite such - a no-brainer and requires some feedback first. People - really don't mind sweeping changes if the result is - something clearly better than what they had before, they - just don't like being <emphasis>surprised</emphasis> by - those changes. The very best way of making sure that - you're on the right track is to have your code reviewed by - one or more other committers.</para> - - <para>When in doubt, ask for review!</para> - </listitem> - - <listitem> - <para>Respect existing maintainers if listed.</para> - - <para>Many parts of FreeBSD aren't <quote>owned</quote> in - the sense that any specific individual will jump up and - yell if you commit a change to <quote>their</quote> area, - but it still pays to check first. One convention we use - is to put a maintainer line in the - <filename>Makefile</filename> for any package or subtree - which is being actively maintained by one or more people; - see <ulink - url="http://www.FreeBSD.org/handbook/policies.html">http://www.FreeBSD.org/handbook/policies.html</ulink> - for documentation on this. Where sections of code have - several maintainers, commits to affected areas by one - maintainer need to be reviewed by at least one other - maintainer. In cases where the - <quote>maintainer-ship</quote> of something isn't clear, - you can also look at the CVS logs for the file(s) in - question and see if someone has been working recently or - predominantly in that area.</para> - - <para>Other areas of FreeBSD fall under the control of - someone who manages an overall category of FreeBSD - evolution, such as internationalization or networking. - See <ulink url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</ulink> - for more information on this.</para> - </listitem> - - <listitem> - <para>Never touch the repository directly. Ask a - Repomeister.</para> - - <para>This is pretty clear - you're not allowed to make - direct modifications to the CVS repository, period. In - case of difficulty, ask one of the repository meisters by - sending mail to <email>cvs@FreeBSD.org</email> and simply - wait for them to fix the problem and get back to you. Do - not attempt to fix the problem yourself!</para> - - <para>If you're thinking about putting down a tag or doing a - new import of code on a vendor branch, you might also find - it useful to ask for advice first. A lot of people get - this wrong the first few times and the consequences are - expensive in terms of files touched and angry CVSup/CTM - folks who are suddenly getting a lot of changes sent over - unnecessarily.</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - - <para>This may be hard to swallow in times of conflict (when - each side is convinced that they're in the right, of - course) but CVS makes it unnecessary to have an ongoing - dispute raging when it's far easier to simply reverse the - disputed change, get everyone calmed down again and then - try and figure out how best to proceed. If the change - turns out to be the best thing after all, it can be easily - brought back. If it turns out not to be, then the users - didn't have to live with the bogus change in the tree - while everyone was busily debating its merits. People - very very rarely call for back-outs in the repository - since discussion generally exposes bad or controversial - changes before the commit even happens, but on such rare - occasions the back-out should be done without argument so - that we can get immediately on to the topic of figuring - out whether it was bogus or not.</para> - </listitem> - - <listitem> - <para>Changes go to <literal>-CURRENT</literal> before - <literal>-STABLE</literal> unless specifically permitted - by the release engineer or unless they're not applicable - to <literal>-CURRENT</literal>. Any non-trivial or - non-urgent change which is applicable should also be - allowed to sit in <literal>-CURRENT</literal> for at least - 3 days before merging so that it can be given sufficient - testing. The release engineer has the same authority over - the <literal>-STABLE</literal> branch as outlined in rule - #5.</para> - - <para>This is another <quote>don't argue about it</quote> - issue since it's the release engineer who is ultimately - responsible (and gets beaten up) if a change turns out to - be bad. Please respect this and give the release engineer - your full cooperation when it comes to the - <literal>-STABLE</literal> branch. The management of - <literal>-STABLE</literal> may frequently seem to be - overly conservative to the casual observer, but also bear - in mind the fact that conservatism is supposed to be the - hallmark of <literal>-STABLE</literal> and different rules - apply there than in <literal>-CURRENT</literal>. There's - also really no point in having <literal>-CURRENT</literal> - be a testing ground if changes are merged over to - <literal>-STABLE</literal> immediately. Changes need a - chance to be tested by the <literal>-CURRENT</literal> - developers, so allow some time to elapse before merging - unless the <literal>-STABLE</literal> fix is critical, - time sensitive or so obvious as to make further testing - unnecessary (spelling fixes to manpages, obvious bug/typo - fixes, etc.) In other words, apply common sense.</para> - </listitem> - - <listitem> - <para>Don't fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - - <para>This project has a public image to uphold and that - image is very important to all of us, especially if we are - to continue to attract new members. There will be - occasions when, despite everyone's very best attempts at - self-control, tempers are lost and angry words are - exchanged, and the best we can do is try and minimize the - effects of this until everyone has cooled back down. That - means that you should not air your angry words in public - and you should not forward private correspondence to - public mailing lists or aliases. What people say - one-to-one is often much less sugar-coated than what they - would say in public, and such communications therefore - have no place there - they only serve to inflame an - already bad situation. If the person sending you a - flame-o-gram at least had the grace to send it privately, - then have the grace to keep it private yourself. If you - feel you are being unfairly treated by another developer, - and it is causing you anguish, bring the matter up with - core rather than taking it public. We will do our best to - play peace makers and get things back to sanity. In cases - where the dispute involves a change to the codebase and - the participants do not appear to be reaching an amicable - agreement, core may appoint a mutually-agreeable 3rd party - to resolve the dispute. All parties involved must then - agree to be bound by the decision reached by this 3rd - party.</para> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> mailing list on a timely - basis so you know when they are.</para> - - <para>Committing changes during a code freeze is a really - big mistake and committers are expected to keep up-to-date - on what's going on before jumping in after a long absence - and committing 10 megabytes worth of accumulated stuff. - People who abuse this on a regular basis will have their - commit privileges suspended until they get back from the - FreeBSD Happy Reeducation Camp we run in Greenland.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - - <para>Many mistakes are made because someone is in a hurry - and just assumes they know the right way of doing - something. If you have not done it before, chances are - good that you do not actually know the way we do things - and really need to ask first or you are going to - completely embarrass yourself in public. There's no shame - in asking <quote>how in the heck do I do this?</quote> We - already know you are an intelligent person; otherwise, you - would not be a committer.</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - - <para>This may sound obvious, but if it really were so - obvious then we probably wouldn't see so many cases of - people clearly not doing this. If your changes are to the - kernel, make sure you can still compile both GENERIC and - LINT. If your changes are anywhere else, make sure you - can still make world. If your changes are to a branch, - make sure your testing occurs with a machine which is - running that code. If you have a change which also may - break another architecture, be sure and test on all - supported architectures. Currently, this is only the x86 - and the Alpha so it's pretty easy to do. If you need to - test on the AXP, your account on <hostid - role="fqdn">beast.FreeBSD.org</hostid> will let you - compile and test Alpha binaries/kernels/etc. As other - architectures are added to the FreeBSD supported platforms - list, the appropriate shared testing resources will be - made available.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Other Suggestions</title> - - <para>When committing documentation changes, use a spell checker - before committing. :) For all SGML docs, you should also - verify that your formatting directives are correct by running - <command>make lint</command>.</para> - - <para>For all on-line manual pages, run <command>manck</command> - (from ports) over the man page to verify the all of the cross - references and file references are correct and that the man - page has all of the appropriate <makevar>MLINK</makevar>s - installed.</para> - - <para>Do not mix style fixes with new functionality. A style - fix is any change which does not modify the functionality of - the code. Mixing the changes obfuscates the functionality - change when using <command>cvs diff</command>, which can hide - any new bugs. Do not include whitespace changes with content - changes in commits to <filename>doc/</filename> or - <filename>www/</filename>. The extra clutter in the diffs - makes the translators' job much more difficult. Instead, make - any style or whitespace changes in seperate commits that are - clearly labeled as such in the commit message.</para> - </sect2> - </sect1> - - <sect1> - <title>Ports Specific FAQ</title> - - <qandaset> - <qandadiv> - <title>Importing a New Port</title> - - <qandaentry> - <question> - <para>How do I import a new port?</para> - </question> - - <answer> - <para>First, please read the section about repository - copy.</para> - - <para>The easiest way to import a new port is to use the - <command>addport</command> script on - <hostid>freefall</hostid>. It will import a port from the - directory you specify, determining the category automatically - from the port <filename>Makefile</filename>. - It will also add an entry to the - <filename>CVSROOT/modules</filename> file and the port's - category <filename>Makefile</filename>. It was - written by &a.mharo; and &a.will;, but Will is the current - maintainer so please send questions/patches about - <command>addport</command> to him.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Any other things I need to know when I import a new - port?</para> - </question> - - <answer> - <para>Check the port, preferably to make sure it compiles - and packages correctly. This is the recommended - sequence:</para> - - <screen>&prompt.root; <userinput>make install</userinput> -&prompt.root; <userinput>make package</userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>make reinstall</userinput> -&prompt.root; <userinput>make package</userinput> - </screen> - - <para>The - <ulink url="http://www.freebsd.org/porters-handbook/index.html">Porters - Handbook</ulink> contains more detailed - instructions.</para> - - <para>Use &man.portlint.1; to check the syntax of the port. - You don't necessarily have to eliminate all warnings but - make sure you have fixed the simple ones.</para> - - <para>If the port came from a submitter who has not - contributed to the project before, add that person's - name to the Handbook's <citetitle - pubwork="section">Additional Contributors</citetitle> - section.</para> - - <para>Close the PR if the port came in as a PR. To close - a PR, just do - <userinput>edit-pr <replaceable>PR#</replaceable></userinput> - on <hostid>freefall</hostid> and change the - <varname>state</varname> from <constant>open</constant> - to <constant>closed</constant>. You will be asked to - enter a log message and then you are done.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Repository Copies</title> - - <qandaentry> - <question> - <para>When do we need a repository copy?</para> - </question> - - <answer> - <para>When you want to import a port that is related to - any port that is already in the tree in a separate - directory, please send mail to the ports manager asking - about it. Here <wordasword>related</wordasword> means - it is a different version or a slightly modified - version. Examples are - <filename>print/ghostscript*</filename> (different - versions) and <filename>x11-wm/windowmaker*</filename> - (English-only and internationalized version).</para> - - <para>Another example is when a port is moved from one - subdirectory to another, or when you want to change the - name of a directory because the author(s) renamed their - software even though it is a - descendant of a port already in a tree.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When do we <emphasis>not</emphasis> need a - repository copy?</para> - </question> - - <answer> - <para>When there is no history to preserve. If a port is - imported into a wrong category and is moved immediately, - it suffices to simply <command>cvs remove</command> the - old one and <command>cvs import</command> the new - one.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do I need to do?</para> - </question> - - <answer> - <para>Send mail to the ports manager, who will do a copy - from the old location/name to the new location/name. - You will then get a notice, at which point you are - expected to perform the following:</para> - - <procedure> - <step> - <para><command>cvs remove</command> the old port (if - necessary)</para> - </step> - - <step> - <para>Adjust the parent (category) - <filename>Makefile</filename></para> - </step> - - <step> - <para>Update <filename>CVSROOT/modules</filename></para> - </step> - - <step> - <para>If other ports depend on the updated port, - change their <filename>Makefile</filename>s' - dependency lines</para> - </step> - - <step> - <para>If the port changed categories, modify the - <makevar>CATEGORIES</makevar> line of the port's - <filename>Makefile</filename> accordingly</para> - </step> - </procedure> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Ports Freeze</title> - - <qandaentry> - <question> - <para>What is a <quote>ports freeze</quote>?</para> - </question> - - <answer> - <para>Before a release, it is necessary to restrict - commits to the ports tree for a short period of time - while the packages and the release itself are being - built. This is to ensure consistency among the various - parts of the release, and is called the <quote>ports - freeze</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How long is a ports freeze?</para> - </question> - - <answer> - <para>Usually an hour or two.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What does it mean to me?</para> - </question> - - <answer> - <para>During the ports freeze, you are not allowed to - commit anything to the tree without explicit approval - from the ports manager. <quote>Explicit - approval</quote> here means either of the - following:</para> - - <itemizedlist> - <listitem> - <para>You asked the ports manager and got a reply - saying, <quote>Go ahead and commit - it.</quote></para> - </listitem> - - <listitem> - <para>The ports manager sent a mail to you or the - mailing lists during the ports freeze pointing out - that the port is broken and has to be fixed.</para> - </listitem> - </itemizedlist> - - <para>Note that you do not have implicit permission to fix - a port during the freeze just because it is - broken.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze starts?</para> - </question> - - <answer> - <para>The ports manager will send out warning messages to - the <email>freebsd-ports@FreeBSD.org</email> and - <email>cvs-committers@FreeBSD.org</email> mailing lists - announcing the start of the impending release, usually - two or three weeks in advance. The exact starting time - will not be determined until a few days before the - actual release. This is because the ports freeze has to - be synchronized with the release, and it is usually not - known until then when exactly the release will be - rolled.</para> - - <para>When the freeze starts, there will be another - announcement to the - <email>cvs-committers@FreeBSD.org</email> list, of - course.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze ends?</para> - </question> - - <answer> - <para>A few hours after the release, the ports manager - will send out a mail to the - <email>freebsd-ports@FreeBSD.org</email> and - <email>cvs-committers@FreeBSD.org</email> mailing lists - announcing the end of the ports freeze. Note that the - release being cut does not automatically end the freeze. - We have to make sure there will not be any last minute - snafus that result in an immediate re-rolling of the - release.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Miscellaneous Questions</title> - - <qandaentry> - <question> - <para>How do I know if my port is building correctly or - not?</para> - </question> - - <answer> - <para>First, go check - <ulink url="http://bento.FreeBSD.org/~asami/errorlogs/">http://bento.FreeBSD.org/~asami/errorlogs/</ulink>. - - There you will find error logs from the latest package - building runs on 3-stable, 4-stable and 5-current.</para> - - <para>However, just because the port doesn't show up there - doesn't mean it's building correctly. (One of the - dependencies may have failed, for instance.) Here are - the relevant directories on bento, so feel free to dig - around.</para> - - <programlisting> /a/asami/portbuild/3/errors error logs from latest 3-stable run - /logs all logs from latest 3-stable run - /packages packages from latest 3-stable run - /bak/errors error logs from last complete 3-stable run - /bak/logs all logs from last complete 3-stable run - /bak/packages packages from last complete 3-stable run - /4/errors error logs from latest 4-stable run - /logs all logs from latest 4-stable run - /packages packages from latest 4-stable run - /bak/errors error logs from last complete 4-stable run - /bak/logs all logs from last complete 4-stable run - /bak/packages packages from last complete 4-stable run - /5/errors error logs from latest 5-current run - /logs all logs from latest 5-current run - /packages packages from latest 5-current run - /bak/errors error logs from last complete 5-current run - /bak/logs all logs from last complete 5-current run - /bak/packages packages from last complete 5-current run - </programlisting> - - <para>Basically, if the port shows up in - <filename>packages</filename>, or it is in - <filename>logs</filename> but not in - <filename>errors</filename>, it built fine. (The - <filename>errors</filename> directories are what you get - from the web page.)</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I added a new port. Do I need to add it to the - <filename>INDEX</filename>?</para> - </question> - - <answer> - <para>No. The ports manager will regenerate the - <filename>INDEX</filename> and commit it every few - days.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are there any other files I'm not allowed to - touch?</para> - </question> - - <answer> - <para>Any file directly under <filename>ports/</filename>, or - any file under a subdirectory that starts with an - uppercase letter (<filename>Mk/</filename>, - <filename>Tools/</filename>, etc.). In particular, the - ports manager is very protective of - <filename>ports/Mk/bsd.port*.mk</filename> so don't - commit changes to those files unless you want to face his - wra(i)th.</para> - </answer> - </qandaentry> - </qandadiv> - </qandaset> - </sect1> - - <sect1> - <title>Miscellaneous Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>Why are trivial or cosmetic changes to files on a vendor - branch a bad idea?</para> - </question> - - <answer> - <para>The RCS file format is quite braindead and certain - operations to achieve things for CVS are hideously - expensive for the repository. Making changes to files on - a vendor branch, thereby pulling the file off that branch, - is one example of this.</para> - - <para>Suppose you have a file which was first imported on a - vendor branch, and was then re-imported three times (still - on the vendor branch) as the vendor makes updates to the - file.</para> - - <segmentedlist> - <seglistitem> - <seg>1.1.1.1</seg> - <seg>vendor import</seg> - </seglistitem> - - <seglistitem> - <seg>1.1.1.2</seg> - <seg>vendor import, +1000, -500 lines</seg> - </seglistitem> - - <seglistitem> - <seg>1.1.1.3</seg> - <seg>vendor import, +2000, -500 lines</seg> - </seglistitem> - - <seglistitem> - <seg>1.1.1.4</seg> - <seg>vendor import, +1000, -1000 lines</seg> - </seglistitem> - </segmentedlist> - - <para>Now suppose that one of the FreeBSD committers makes a - one line change to this file, causing it to go to version - 1.2. This causes it to leave the branch, resulting in - 4,001 lines being added to the file's history, and 2,001 - lines being deleted.</para> - - <para>This is because the 1.2 delta is stored relative to - 1.1.1.1, <emphasis>not</emphasis> 1.1.1.4, and so the - entire vendor history is duplicated in the 1.2 delta. - Now, repeat this for 2000 files in a large directory, it - adds up a lot.</para> - - <para><emphasis>This</emphasis> is why we have such - <quote>hands off</quote> policies for - <filename>src/contrib</filename> and other things that - track the vendor releases. This is why <quote>typo - fixes</quote> in man pages and spelling - <quote>corrections</quote> are so strongly discouraged for - vendor code.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I add a new file to a CVS branch?</para> - </question> - - <answer> - <para>To add a file onto a branch, simply checkout or update - to the branch you want to add to and then add the file using - <command>cvs add</command> as you normally would. For - example, if you wanted to MFC the file - <filename>src/sys/alpha/include/smp.h</filename> from HEAD - to RELENG_4 and it does not exist in RELENG_4 yet, you would - use the following steps:</para> - - <example> - <title>MFC'ing a New File</title> - - <screen>&prompt.user; <userinput>cd sys/alpha/include</userinput> -&prompt.user; <userinput>cvs update -rRELENG_4</userinput> -cvs update: Updating . -U clockvar.h -U console.h -... -&prompt.user; <userinput>cvs update -kk -Ap smp.h > smp.h</userinput> -=================================================================== -Checking out smp.h -RCS: /usr/cvs/src/sys/alpha/include/smp.h,v -VERS: 1.1 -*************** -&prompt.user; <userinput>cvs add smp.h</userinput> -cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' -cvs add: use 'cvs commit' to add this file permanently -&prompt.user; <userinput>cvs commit</userinput> - </screen> - </example> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml deleted file mode 100644 index 7144714cd4..0000000000 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ /dev/null @@ -1,6224 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml,v 1.337 2000/11/13 19:22:53 okazaki Exp $ ---> - -<chapter id="contrib"> - <title>Contributing to FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>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 - <emphasis>relies</emphasis> 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!</para> - - <para>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 whose 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.</para> - - <para>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 <filename>TODO</filename> 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!</para> - - <para>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.</para> - - <sect1 id="contrib-what"> - <title>What is Needed</title> - - <para>The following list of tasks and sub-projects represents something of - an amalgam of the various core team <filename>TODO</filename> 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?</para> - - <sect2> - <title>High priority tasks</title> - - <para>The following tasks are considered to be urgent, usually because - they represent something that is badly broken or sorely needed:</para> - - <orderedlist> - <listitem> - <para>3-stage boot issues. Overall coordination: &a.hackers;</para> - - <itemizedlist> - <listitem> - <para>Do WinNT compatible drive tagging so that the 3rd stage - can provide an accurate mapping of BIOS geometries for - disks.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Filesystem problems. Overall coordination: &a.fs;</para> - - <itemizedlist> - <listitem> - <para>Clean up and document the nullfs filesystem code. - Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Fix the union file system. Coordinator: &a.dg;</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Implement Int13 vm86 disk driver. Coordinator: - &a.hackers;</para> - </listitem> - - <listitem> - <para>New bus architecture. Coordinator: &a.newbus;</para> - - <itemizedlist> - <listitem> - <para>Port existing ISA drivers to new architecture.</para> - </listitem> - - <listitem> - <para>Move all interrupt-management code to appropriate parts of - the bus drivers.</para> - </listitem> - - <listitem> - <para>Port PCI subsystem to new architecture. Coordinator: - &a.dfr;</para> - </listitem> - - <listitem> - <para>Figure out the right way to handle removable devices and - then use that as a substrate on which PC-Card and CardBus - support can be implemented.</para> - </listitem> - - <listitem> - <para>Resolve the probe/attach priority issue once and for - all.</para> - </listitem> - - <listitem> - <para>Move any remaining buses over to the new - architecture.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Kernel issues. Overall coordination: &a.hackers;</para> - </listitem> - - <listitem> - <para>Add more pro-active security infrastructure. Overall - coordination: &a.security;</para> - - <itemizedlist> - <listitem> - <para>Build something like Tripwire(TM) into the kernel, with a - remote and local part. There are a number of cryptographic - issues to getting this right; contact the coordinator for - details. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make the entire kernel use <literal>suser()</literal> - instead of comparing to 0. It is presently using about half - of each. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Split securelevels into different parts, to allow an - administrator to throw away those privileges he can throw - away. Setting the overall securelevel needs to have the same - effect as now, obviously. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make it possible to upload a list of <quote>allowed - program</quote> to BPF, and then block BPF from accepting other - programs. This would allow BPF to be used e.g. for DHCP, - without allowing an attacker to start snooping the local - network.</para> - </listitem> - - <listitem> - <para>Update the security checker script. We should at least - grab all the checks from the other BSD derivatives, and add - checks that a system with securelevel increased also have - reasonable flags on the relevant parts. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add authorization infrastructure to the kernel, to allow - different authorization policies. Part of this could be done - by modifying <literal>suser()</literal>. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add code to the NFS layer so that you cannot - <literal>chdir("..")</literal> out of an NFS partition. E.g., - <filename>/usr</filename> is a UFS partition with - <filename>/usr/src</filename> NFS exported. Now it is - possible to use the NFS filehandle for - <filename>/usr/src</filename> to get access to - <filename>/usr</filename>.</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Medium priority tasks</title> - - <para>The following tasks need to be done, but not with any particular - urgency:</para> - - <orderedlist> - <listitem> - <para>Full KLD based driver support/Configuration Manager.</para> - - <itemizedlist> - <listitem> - <para>Write a configuration manager (in the 3rd stage boot?) - that probes your hardware in a sane manner, keeps only the - KLDs required for your hardware, etc.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.imp;</para> - - <itemizedlist> - <listitem> - <para>Documentation!</para> - </listitem> - - <listitem> - <para>Reliable operation of the pcic driver (needs - testing).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>sio.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ed.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ep.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>User-mode recognizer and handler (partially done).</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Advanced Power Management. Coordinators: &a.msmith; and - &a.phk;</para> - - <itemizedlist> - <listitem> - <para>APM sub-driver (mostly done).</para> - </listitem> - - <listitem> - <para>IDE/ATA disk sub-driver (partially done).</para> - </listitem> - - <listitem> - <para>syscons/pcvt sub-driver.</para> - </listitem> - - <listitem> - <para>Integration with the PCMCIA/PCCARD drivers - (suspend/resume).</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Low priority tasks</title> - - <para>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:</para> - - <para>The first N items are from Terry Lambert - <email>terry@lambert.org</email></para> - - <orderedlist> - <listitem> - <para>NetWare Server (protected mode ODI driver) loader and - sub-services to allow the use of ODI card drivers supplied with - network cards. The same thing for NDIS drivers and NetWare SCSI - drivers.</para> - </listitem> - - <listitem> - <para>An "upgrade system" option that works on Linux boxes instead - of just previous rev FreeBSD boxes.</para> - </listitem> - - <listitem> - <para>Symmetric Multiprocessing with kernel preemption (requires - kernel preemption).</para> - </listitem> - - <listitem> - <para>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 v.s.. 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).</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Smaller tasks</title> - - <para>Most of the tasks listed in the previous sections require either a - considerable investment of time or an in-depth knowledge of the - FreeBSD kernel (or both). However, there are also many useful tasks - which are suitable for "weekend hackers", or people without - programming skills.</para> - - <orderedlist> - <listitem> - <para>If you run FreeBSD-current and have a good Internet - connection, there is a machine <hostid - role="fqdn">current.FreeBSD.org</hostid> which builds a full - release once a day — every now and again, try and install - the latest release from it and report any failures in the - process.</para> - </listitem> - - <listitem> - <para>Read the freebsd-bugs mailing list. There might be a - problem you can comment constructively on or with patches you - can test. Or you could even try to fix one of the problems - yourself.</para> - </listitem> - - <listitem> - <para>Read through the FAQ and Handbook periodically. If anything - is badly explained, out of date or even just completely wrong, let - us know. Even better, send us a fix (SGML is not difficult to - learn, but there is no objection to ASCII submissions).</para> - </listitem> - - <listitem> - <para>Help translate FreeBSD documentation into your native language - (if not already available) — just send an email to &a.doc; - asking if anyone is working on it. Note that you are not - committing yourself to translating every single FreeBSD document - by doing this — in fact, the documentation most in need of - translation is the installation instructions.</para> - </listitem> - - <listitem> - <para>Read the freebsd-questions mailing list and &ng.misc - occasionally (or even regularly). It can be very satisfying to - share your expertise and help people solve their problems; - sometimes you may even learn something new yourself! These forums - can also be a source of ideas for things to work on.</para> - </listitem> - - <listitem> - <para>If you know of any bug fixes which have been successfully - applied to -current but have not been merged into -stable after a - decent interval (normally a couple of weeks), send the committer a - polite reminder.</para> - </listitem> - - <listitem> - <para>Move contributed software to <filename>src/contrib</filename> - in the source tree.</para> - </listitem> - - <listitem> - <para>Make sure code in <filename>src/contrib</filename> is up to - date.</para> - </listitem> - - <listitem> - <para>Look for year 2000 bugs (and fix any you find!)</para> - </listitem> - - <listitem> - <para>Build the source tree (or just part of it) with extra warnings - enabled and clean up the warnings.</para> - </listitem> - - <listitem> - <para>Fix warnings for ports which do deprecated things like using - gets() or including malloc.h.</para> - </listitem> - - <listitem> - <para>If you have contributed any ports, send your patches back to - the original author (this will make your life easier when they - bring out the next version)</para> - </listitem> - - <listitem> - <para>Suggest further tasks for this list!</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Work through the PR database</title> - - <para>The <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD PR - list</ulink> shows all the current active problem reports and - requests for enhancement that have been submitted by FreeBSD users. - Look through the open PRs, and see if anything there takes your - interest. Some of these might be very simple tasks, that just need an - extra pair of eyes to look over them and confirm that the fix in the - PR is a good one. Others might be much more complex.</para> - - <para>Start with the PRs that have not been assigned to anyone else, but - if one them is assigned to someone else, but it looks like something - you can handle, e-mail the person it is assigned to and ask if you can - work on it—they might already have a patch ready to be tested, - or further ideas that you can discuss with them.</para> - </sect2> - </sect1> - - <sect1 id="contrib-how"> - <title>How to Contribute</title> - - <para>Contributions to the system generally fall into one or more of the - following 6 categories:</para> - - <sect2 id="contrib-general"> - <title>Bug reports and general commentary</title> - - <para>An idea or suggestion of <emphasis>general</emphasis> technical - interest should be mailed to the &a.hackers;. Likewise, people with - an interest in such things (and a tolerance for a - <emphasis>high</emphasis> volume of mail!) may subscribe to the - hackers mailing list by sending mail to &a.majordomo;. See <link - linkend="eresources-mail">mailing lists</link> for more information - about this and other mailing lists.</para> - - <para>If you find a bug or are submitting a specific change, please - report it using the &man.send-pr.1; program or its <ulink - url="http://www.FreeBSD.org/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug report. - Unless they exceed 65KB, include any patches directly in the report. - When including patches, <emphasis>do not</emphasis> use cut-and-paste - because cut-and-paste turns tabs into spaces and makes them unusable. - Consider compressing patches and using &man.uuencode.1; if they exceed - 20KB. Upload very large submissions to <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp.FreeBSD.org:/pub/FreeBSD/incoming/</ulink>.</para> - - <para>After filing a report, you should receive confirmation along with - a tracking number. Keep this tracking number so that you can update - us with details about the problem by sending mail to - <email>bug-followup@FreeBSD.org</email>. Use the number as the - message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional - information for any bug report should be submitted this way.</para> - - <para>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 &man.send-pr.1; command, then you may ask - someone to file it for you by sending mail to the &a.bugs;.</para> - </sect2> - - <sect2> - <title>Changes to the documentation</title> - - <para>Changes to the documentation are overseen by the &a.doc;. Send - submissions and changes (even small ones are welcome!) using - <command>send-pr</command> as described in <link - linkend="contrib-general">Bug Reports and General - Commentary</link>.</para> - </sect2> - - <sect2> - <title>Changes to existing source code</title> - - <para>An addition or change to the existing source code is a somewhat - trickier affair and depends a lot on how far out of date you are with - the current state of the core FreeBSD development. There is a special - on-going release of FreeBSD known as <quote>FreeBSD-current</quote> - which is made available in a variety of ways for the convenience of - developers working actively on the system. See <link - linkend="current">Staying current with FreeBSD</link> for more - information about getting and using FreeBSD-current.</para> - - <para>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 &a.announce; and the &a.current; lists, where - discussions on the current state of the system take place.</para> - - <para>Assuming that you can manage to secure fairly up-to-date sources - to base your changes on, the next step is to produce a set of diffs to - send to the FreeBSD maintainers. This is done with the &man.diff.1; - command, with the <quote>context diff</quote> form - being preferred. For example:</para> - - <para> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - - or - - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - - would generate such a set of context diffs for the given source file - or directory hierarchy. See the man page for &man.diff.1; for more - details.</para> - - <para>Once you have a set of diffs (which you may test with the - &man.patch.1; command), you should submit them for inclusion with - FreeBSD. Use the &man.send-pr.1; program as described in <link - linkend="contrib-general">Bug Reports and General Commentary</link>. - <emphasis>Do not</emphasis> just send the diffs to the &a.hackers; or - they will get lost! We greatly appreciate your submission (this is a - volunteer project!); because we are busy, we may not be able to - address it immediately, but it will remain in the pr database until we - do.</para> - - <para>If you feel it appropriate (e.g. you have added, deleted, or - renamed files), bundle your changes into a <command>tar</command> file - and run the &man.uuencode.1; program on it. Shar archives are also - welcome.</para> - - <para>If your change is of a potentially sensitive nature, e.g. 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 &a.core; directly rather than submitting it - with &man.send-pr.1;. 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 <emphasis>very busy</emphasis> and so you - should only send mail to them where it is truly necessary.</para> - - <para>Please refer to <command>man 9 intro</command> and <command>man 9 - style</command> for some information on coding style. We would - appreciate it if you were at least aware of this information before - submitting code.</para> - </sect2> - - <sect2> - <title>New code or major value-added packages</title> - - <para>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 a web or FTP site for other people to - access. If you do not have access to a web or FTP site, ask on an - appropriate FreeBSD mailing list for someone to host the changes for - you.</para> - - <para>When working with large amounts of code, the touchy subject of - copyrights also invariably comes up. Acceptable copyrights for code - included in FreeBSD are:</para> - - <orderedlist> - <listitem> - <para>The BSD copyright. This copyright is most preferred due to - its <quote>no strings attached</quote> nature and general - attractiveness to commercial enterprises. Far from discouraging - such commercial use, the FreeBSD Project actively encourages such - participation by commercial interests who might eventually be - inclined to invest something of their own into FreeBSD.</para> - </listitem> - - <listitem> - <para>The GNU Public License, or <quote>GPL</quote>. 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, assembler, text formatter, etc) it would be silly to - refuse additional contributions under this license. Code under - the GPL also goes into a different part of the tree, that being - <filename>/sys/gnu</filename> or - <filename>/usr/src/gnu</filename>, and is therefore easily - identifiable to anyone for whom the GPL presents a problem.</para> - </listitem> - </orderedlist> - - <para>Contributions coming under any other type of copyright must be - carefully reviewed before their inclusion into FreeBSD will be - considered. Contributions for which particularly restrictive - commercial copyrights apply are generally rejected, though the authors - are always encouraged to make such changes available through their own - channels.</para> - - <para>To place a <quote>BSD-style</quote> copyright on your work, include - the following text at the very beginning of every source code file you - wish to protect, replacing the text between the <literal>%%</literal> - with the appropriate information.</para> - - <programlisting> -Copyright (c) %%proper_years_here%% - %%your_name_here%%, %%your_state%% %%your_zip%%. - All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -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$</programlisting> - - <para>For your convenience, a copy of this text can be found in - <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> - </sect2> - - <sect2> - <title>Money, Hardware or Internet access</title> - - <para>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.</para> - - <sect3> - <title><anchor id="donations">Donating funds</title> - - <para>While the FreeBSD Project is not a 501(c)(3) (charitable) - 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.</para> - - <para>FreeBSD, Inc. was founded in early 1995 by &a.jkh; and &a.dg; - 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.</para> - - <para>Please make any checks payable to FreeBSD, Inc., sent in care of - the following address:</para> - - <address> - <otheraddr>FreeBSD, Inc.</otheraddr> - <otheraddr>c/o Jordan Hubbard</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city> - <state>CA</state>, <postcode>94520</postcode> - </address> - - <para>(currently using the BSDi address until a PO box - can be opened)</para> - - <para>Wire transfers may also be sent directly to:</para> - - <address> - <otheraddr>Bank Of America</otheraddr> - <otheraddr>Concord Main Office</otheraddr> - <pob>P.O. Box 37176</pob> - <city>San Francisco</city> - <state>CA</state>, <postcode>94137-5176</postcode> - - <otheraddr>Routing #: 121-000-358</otheraddr> - <otheraddr>Account #: 01411-07441 (FreeBSD, Inc.)</otheraddr> - </address> - - <para>Any correspondence related to donations should be sent to &a.jkh, - either via email or to the FreeBSD, Inc. postal address given above. - </para> - - <para>If you do not wish to be listed in our <link - linkend="donors">donors</link> section, please specify this when - making your donation. Thanks!</para> - </sect3> - - <sect3> - <title>Donating hardware</title> - - <para>Donations of hardware in any of the 3 following categories are - also gladly accepted by the FreeBSD Project:</para> - - <itemizedlist> - <listitem> - <para>General purpose hardware such as disk drives, memory or - complete systems should be sent to the FreeBSD, Inc. address - listed in the <emphasis>donating funds</emphasis> - section.</para> - </listitem> - - <listitem> - <para>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.dg; - for information on which items are still required.</para> - </listitem> - - <listitem> - <para>Hardware currently unsupported by FreeBSD for which you - would like to see such support added. Please contact the - &a.core; before sending such items as we will need to find a - developer willing to take on the task before we can accept - delivery of new hardware.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Donating Internet access</title> - - <para>We can always use new mirror sites for FTP, WWW or - <command>cvsup</command>. If you would like to be such a mirror, - please contact the FreeBSD project administrators - <email>hubs@FreeBSD.org</email> for more information.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="donors"> - <title>Donors Gallery</title> - - <para>The FreeBSD Project is indebted to the following donors and would - like to publicly thank them here!</para> - - <itemizedlist> - <listitem> - <para><emphasis>Contributors to the central server - project:</emphasis></para> - - <para>The following individuals and businesses made it possible for - the FreeBSD Project to build a new central server machine to - eventually replace <hostid role="fqdn">freefall.FreeBSD.org</hostid> - by donating the following items:</para> - - <itemizedlist> - <listitem> - <para>&a.mbarkah and his employer, <ulink url="http://www.hemi.com/"> - Hemisphere Online</ulink>, donated a <emphasis>Pentium Pro - (P6) 200Mhz CPU</emphasis></para> - </listitem> - - <listitem> - <para><ulink url="http://www.asacomputers.com/">ASA - Computers</ulink> donated a <emphasis>Tyan 1662 - motherboard</emphasis>.</para> - </listitem> - - <listitem> - <para>Joe McGuckin <email>joe@via.net</email> of <ulink - url="http://www.via.net/">ViaNet Communications</ulink> donated - a <emphasis>Kingston ethernet controller.</emphasis></para> - </listitem> - - <listitem> - <para>Jack O'Neill <email>jack@diamond.xtalwind.net</email> - donated an <emphasis>NCR 53C875 SCSI controller - card</emphasis>.</para> - </listitem> - - <listitem> - <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink - url="http://www.Alameda.net/">Alameda Networks</ulink> donated - <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk - drive and the case.</emphasis></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Direct funding:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed direct funding to the project:</para> - - <itemizedlist> - <listitem> - <para>Annelise Anderson - <email>ANDRSN@HOOVER.STANFORD.EDU</email></para> - </listitem> - - <listitem> - <para>&a.dillon</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bluemountain.com/">Blue Mountain - Arts</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.epilogue.com/">Epilogue Technology - Corporation</ulink></para> - </listitem> - - <listitem> - <para>&a.sef</para> - </listitem> - - <listitem> - <para><ulink url="http://www.gta.com/">Global Technology - Associates, Inc</ulink></para> - </listitem> - - <listitem> - <para>Don Scott Wilde</para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@masternet.it</email></para> - </listitem> - - <listitem> - <para>Josef C. Grosch <email>joeg@truenorth.org</email></para> - </listitem> - - <listitem> - <para>Robert T. Morris</para> - </listitem> - - <listitem> - <para>&a.chuckr</para> - </listitem> - - <listitem> - <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of - <ulink url="http://www.imagescape.com/">Imaginary Landscape, - LLC.</ulink></para> - </listitem> - - <listitem> - <para>Dmitry S. Kohmanyuk <email>dk@dog.farm.org</email></para> - </listitem> - - <listitem> - <para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan - (a portion of the profits from sales of their various FreeBSD - CDROMs).</para> - </listitem> - - <listitem> - <para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan - Publishing Co.</ulink> donated a portion of their profits from - <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting - started) to the FreeBSD and XFree86 projects.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink> - donated a portion of their profits from several FreeBSD-related - books to the FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric - Corp</ulink> has generously donated significant funding to the - FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.pacificsolutions.com/">Pacific - Solutions</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.siemens.de/">Siemens AG</ulink> - via <ulink url="mailto:andre.albsmeier@mchp.siemens.de">Andre - Albsmeier</ulink></para> - </listitem> - - <listitem> - <para><ulink url="mailto:ras@interaccess.com">Chris Silva</ulink> - </para> - </listitem> - - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Hardware contributors:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support:</para> - - <itemizedlist> - <listitem> - <para>BSDi for providing the Pentium P5-90 and - 486/DX2-66 EISA/VL systems that are being used for our - development work, to say nothing of the network access and other - donations of hardware resources.</para> - </listitem> - - <listitem> - <para>TRW Financial Systems, Inc. provided 130 PCs, three 68 GB - fileservers, twelve Ethernets, two routers and an ATM switch for - debugging the diskless code.</para> - </listitem> - - <listitem> - <para>Dermot McDonnell donated the Toshiba XM3401B CDROM drive - currently used in freefall.</para> - </listitem> - - <listitem> - <para>&a.chuck; contributed his floppy tape streamer for - experimental work.</para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;, - provided Wangtek and Archive QIC-02 tape drives in order to - improve the <devicename>wt</devicename> driver.</para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed - a 2.88 MB floppy drive to the project. This will hopefully - increase the pressure for rewriting the floppy disk driver. - <!-- smiley -->;-)</para> - </listitem> - - <listitem> - <para><ulink url="http://www.tekram.com/">Tekram - Technologies</ulink> sent one each of their DC-390, DC-390U - and DC-390F FAST and ULTRA SCSI host adapter cards for - regression testing of the NCR and AMD drivers with their cards. - They are also to be applauded for making driver sources for free - operating systems available from their FTP server <ulink - url="ftp://ftp.tekram.com/scsi/FreeBSD/">ftp://ftp.tekram.com/scsi/FreeBSD/</ulink>.</para> - </listitem> - - <listitem> - <para>Larry M. Augustin contributed not only a - Symbios Sym8751S SCSI card, but also a set of data books, - including one about the forthcoming Sym53c895 chip with Ultra-2 - and LVD support, and the latest programming manual with - information on how to safely use the advanced features of the - latest Symbios SCSI chips. Thanks a lot!</para> - </listitem> - - <listitem> - <para>Christoph Kukulies <email>kuku@FreeBSD.org</email> donated - an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver - development.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Special contributors:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM) - has donated almost more than we can say (see the <link - linkend="history">history</link> document for more details). - In particular, we would like to thank them for the original - hardware used for <hostid - role="fqdn">freefall.FreeBSD.org</hostid>, our primary - development machine, and for <hostid - role="fqdn">thud.FreeBSD.org</hostid>, a 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.</para> - </listitem> - - <listitem> - <para>The <ulink url="http://www.interface-business.de/">interface - business GmbH, Dresden</ulink> has been patiently supporting - &a.joerg; who has often preferred FreeBSD work over paid work, and - used to fall back to their (quite expensive) EUnet Internet - connection whenever his private connection became too slow or - flaky to work with it...</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bsdi.com/">Berkeley Software Design, - Inc.</ulink> has contributed their DOS emulator code to the - remaining BSD world, which is used in the - <emphasis>doscmd</emphasis> command.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-corealumni"> - <title>Core Team Alumni</title> - - <para>The following people were members of the FreeBSD core team during - the periods indicated. We thank them for their past efforts in the - service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - <itemizedlist> - <listitem> - <para>&a.ache (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jmb (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.bde (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gibbs (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.rich (1994 - 2000)</para> - </listitem> - - <listitem> - <para>&a.phk (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gpalmer (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.sos (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.wollman (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.joerg (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jdp (1997 - 2000)</para> - </listitem> - - <listitem> - <para>&a.guido (1995 - 1999)</para> - </listitem> - - <listitem> - <para>&a.dyson (1993 - 1998)</para> - </listitem> - - <listitem> - <para>&a.nate (1992 - 1996)</para> - </listitem> - - <listitem> - <para>&a.rgrimes (1992 - 1995)</para> - </listitem> - - <listitem> - <para>Andreas Schulz (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.csgr (1993 - 1995)</para> - </listitem> - - <listitem> - <para>&a.paul (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.smace (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Andrew Moore (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Christoph Robitschko (1993 - 1994)</para> - </listitem> - - <listitem> - <para>J. T. Conklin (1992 - 1993)</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-develalumni"> - <title>Development Team Alumni</title> - - <para>The following people were members of the FreeBSD development team - during the periods indicated. We thank them for their past efforts - in the service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - <itemizedlist> - <listitem> - <para>&a.tedm (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.karl (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.gclarkii (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.jraynard (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.jgreco (???? - 1999)</para> - </listitem> - <listitem> - <para>&a.ats (???? - 1999)</para> - </listitem> - <listitem> - <para>Jamil Weatherby (1997 - 1999)</para> - </listitem> - <listitem> - <para>meganm (???? - 1998)</para> - </listitem> - <listitem> - <para>&a.dyson (???? - 1998)</para> - </listitem> - <listitem> - <para>Amancio Hasty (1997 - 1998)</para> - </listitem> - <listitem> - <para>Drew Derbyshire (1997 - 1998)</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-derived"> - <title>Derived Software Contributors</title> - - <para>This software was originally derived from William F. Jolitz's 386BSD - release 0.1, though almost none of the original 386BSD specific code - remains. This software has been essentially re-implemented from the - 4.4BSD-Lite release provided by the Computer Science Research Group - (CSRG) at the University of California, Berkeley and associated academic - contributors.</para> - - <para>There are also portions of NetBSD and OpenBSD that have been - integrated into FreeBSD as well, and we would therefore like to thank - all the contributors to NetBSD and OpenBSD for their work.</para> - </sect1> - - <sect1 id="contrib-additional"> - <title>Additional FreeBSD Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>AMAGAI Yoshiji <email>amagai@nue.org</email></para> - </listitem> - - <listitem> - <para>Aaron Bornstein <email>aaronb@j51.com</email></para> - </listitem> - - <listitem> - <para>Aaron Smith <email>aaron@mutex.org</email></para> - </listitem> - - <listitem> - <para>Achim Patzner <email>ap@noses.com</email></para> - </listitem> - - <listitem> - <para>Ada T Lim <email>ada@bsd.org</email></para> - </listitem> - - <listitem> - <para>Adam Baran <email>badam@mw.mil.pl</email></para> - </listitem> - - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adam McDougall <email>mcdouga9@egr.msu.edu</email></para> - </listitem> - - <listitem> - <para>Adam Strohl <email>troll@digitalspark.net</email></para> - </listitem> - - <listitem> - <para>Adoal Xu <email>adoal@iname.com</email></para> - </listitem> - - <listitem> - <para>Adrian Colley <email>aecolley@ois.ie</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Adrian Mariano <email>adrian@cam.cornell.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Steinmann <email>ast@marabu.ch</email></para> - </listitem> - - <listitem> - <para>Adrian T. Filipi-Martin - <email>atf3r@agate.cs.virginia.edu</email></para> - </listitem> - - <listitem> - <para>Ajit Thyagarajan <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akio Morita - <email>amorita@meadow.scphys.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akira SAWADA <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akira Watanabe - <email>akira@myaw.ei.meisei-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akito Fujita <email>fujita@zoo.ncl.omron.co.jp</email></para> - </listitem> - - <listitem> - <para>Alain Kalker - <email>A.C.P.M.Kalker@student.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Alan Bawden <email>alan@curry.epilogue.com</email></para> - </listitem> - - <listitem> - <para>Alec Wolman <email>wolman@cs.washington.edu</email></para> - </listitem> - - <listitem> - <para>Aled Morris <email>aledm@routers.co.uk</email></para> - </listitem> - - <listitem> - <para>Aleksandr A Babaylov <email>.@babolo.ru</email></para> - </listitem> - - <listitem> - <para>Alex G. Bulushev <email>bag@demos.su</email></para> - </listitem> - - <listitem> - <para>Alex D. Chen - <email>dhchen@Canvas.dorm7.nccu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Alex Le Heux <email>alexlh@funk.org</email></para> - </listitem> - - <listitem> - <para>Alex Kapranoff <email>kappa@zombie.antar.bryansk.ru</email></para> - </listitem> - - <listitem> - <para>Alex Perel <email>veers@disturbed.net</email></para> - </listitem> - - <listitem> - <para>Alex Varju <email>varju@webct.com</email></para> - </listitem> - - <listitem> - <para>Alex Zepeda <email>garbanzo@hooked.net</email></para> - </listitem> - - <listitem> - <para>Alexander B. Povolotsky <email>tarkhil@mgt.msk.ru</email></para> - </listitem> - - <listitem> - <para>Alexander Gelfenbain <email>mail@gelf.com</email></para> - </listitem> - - <listitem> - <para>Alexander Leidinger - <email>netchild@wurzelausix.CS.Uni-SB.DE</email></para> - </listitem> - - <listitem> - <para>Alexandre Snarskii <email>snar@paranoia.ru</email></para> - </listitem> - - <listitem> - <para>Alistair G. Crooks <email>agc@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Allan Bowhill <email>bowhill@bowhill.vservers.com</email></para> - </listitem> - - <listitem> - <para>Allan Saddi <email>asaddi@philosophysw.com</email></para> - </listitem> - - <listitem> - <para>Allen Campbell <email>allenc@verinet.com</email></para> - </listitem> - - <listitem> - <para>Amakawa Shuhei <email>amakawa@hoh.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Amancio Hasty <email>hasty@star-gate.com</email></para> - </listitem> - - <listitem> - <para>Amir Farah <email>amir@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Amy Baron <email>amee@beer.org</email></para> - </listitem> - - <listitem> - <para>Anatoly A. Orehovsky <email>tolik@mpeks.tomsk.su</email></para> - </listitem> - - <listitem> - <para>Anatoly Vorobey <email>mellon@pobox.com</email></para> - </listitem> - - <listitem> - <para>Anders Nordby <email>anders@fix.no</email></para> - </listitem> - - <listitem> - <para>Anders Thulin <email>Anders.X.Thulin@telia.se</email></para> - </listitem> - - <listitem> - <para>Andras Olah <email>olah@cs.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Andre Albsmeier - <email>Andre.Albsmeier@mchp.siemens.de</email></para> - </listitem> - - <listitem> - <para>Andre Oppermann <email>andre@pipeline.ch</email></para> - </listitem> - - <listitem> - <para>Andreas Haakh <email>ah@alman.robin.de</email></para> - </listitem> - - <listitem> - <para>Andreas Kohout <email>shanee@rabbit.augusta.de</email></para> - </listitem> - - <listitem> - <para>Andreas Lohr <email>andreas@marvin.RoBIN.de</email></para> - </listitem> - - <listitem> - <para>Andreas Schulz <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andreas Wetzel <email>mickey@deadline.snafu.de</email></para> - </listitem> - - <listitem> - <para>Andreas Wrede <email>andreas@planix.com</email></para> - </listitem> - - <listitem> - <para>Andres Vega Garcia <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andrew Atrens <email>atreand@statcan.ca</email></para> - </listitem> - - <listitem> - <para>Andrew Boothman <email>andrew@cream.org</email></para> - </listitem> - - <listitem> - <para>Andrew Gillham <email>gillham@andrews.edu</email></para> - </listitem> - - <listitem> - <para>Andrew Gordon <email>andrew.gordon@net-tel.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew J. Korty <email>ajk@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Andrew L. Moore <email>alm@mclink.com</email></para> - </listitem> - - <listitem> - <para>Andrew L. Neporada <email>andrew@chg.ru</email></para> - </listitem> - - <listitem> - <para>Andrew McRae <email>amcrae@cisco.com</email></para> - </listitem> - - <listitem> - <para>Andrew Stevenson <email>andrew@ugh.net.au</email></para> - </listitem> - - <listitem> - <para>Andrew Timonin <email>tim@pool1.convey.ru</email></para> - </listitem> - - <listitem> - <para>Andrew V. Stesin <email>stesin@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrew Webster <email>awebster@dataradio.com</email></para> - </listitem> - - <listitem> - <para>Andrey Novikov <email>andrey@novikov.com</email></para> - </listitem> - - <listitem> - <para>Andrey Tchoritch <email>andy@venus.sympad.net</email></para> - </listitem> - - <listitem> - <para>Andy Farkas <email>andyf@speednet.com.au</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email></para> - </listitem> - - <listitem> - <para>Andy Whitcroft <email>andy@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Angelo Turetta <email>ATuretta@stylo.it</email></para> - </listitem> - - <listitem> - <para>Anthony C. Chavez <email>magus@xmission.com</email></para> - </listitem> - - <listitem> - <para>Anthony Yee-Hang Chan <email>yeehang@netcom.com</email></para> - </listitem> - - <listitem> - <para>Anton Berezin <email>tobez@plab.ku.dk</email></para> - </listitem> - - <listitem> - <para>Anton N. Bruesov <email>antonz@library.ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Antti Kaipila <email>anttik@iki.fi</email></para> - </listitem> - - <listitem> - <para>arci <email>vega@sophia.inria.fr</email></para> - </listitem> - - <listitem> - <para>Are Bryne <email>are.bryne@communique.no</email></para> - </listitem> - - <listitem> - <para>Ari Suutari <email>ari@suutari.iki.fi</email></para> - </listitem> - - <listitem> - <para>Arindum Mukerji <email>rmukerji@execpc.com</email></para> - </listitem> - - <listitem> - <para>Arjan de Vet <email>devet@IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Arun Sharma <email>adsharma@sharmas.dhs.org</email></para> - </listitem> - - <listitem> - <para>Ask Bjoern Hansen <email>ask@valueclick.com</email></para> - </listitem> - - <listitem> - <para>Atsushi Furuta <email>furuta@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Atsushi Murai <email>amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Bierbauch <email>pivrnec@vszbr.cz</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para> - </listitem> - - <listitem> - <para>Ben Jackson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ben Walter <email>bwalter@itachi.swcp.com</email></para> - </listitem> - - <listitem> - <para>Benjamin Lewis <email>bhlewis@gte.net</email></para> - </listitem> - - <listitem> - <para>Berend de Boer <email>berend@pobox.com</email></para> - </listitem> - - <listitem> - <para>Bernd Rosauer <email>br@schiele-ct.de</email></para> - </listitem> - - <listitem> - <para>Bill Kish <email>kish@osf.org</email></para> - </listitem> - - <listitem> - <para>Bill Trost <email>trost@cloud.rain.com</email></para> - </listitem> - - <listitem> - <para>Blaz Zupan <email>blaz@amis.net</email></para> - </listitem> - - <listitem> - <para>Bob Van Valzah <email>Bob@whitebarn.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Bob Willcox <email>bob@luke.pmr.com</email></para> - </listitem> - - <listitem> - <para>Boris Staeblow <email>balu@dva.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Boyd Faulkner <email>faulkner@mpd.tandem.com</email></para> - </listitem> - - <listitem> - <para>Boyd R. Faulkner <email>faulkner@asgard.bga.com</email></para> - </listitem> - - <listitem> - <para>Brad Chapman <email>chapmanb@arches.uga.edu</email></para> - </listitem> - - <listitem> - <para>Brad Hendrickse <email>bradh@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Brad Karp <email>karp@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>Bradley Dunn <email>bradley@dunn.org</email></para> - </listitem> - - <listitem> - <para>Brandon Fosdick <email>bfoz@glue.umd.edu</email></para> - </listitem> - - <listitem> - <para>Brandon Gillespie <email>brandon@roguetrader.com</email></para> - </listitem> - - <listitem> - <para>&a.wlloyd</para> - </listitem> - - <listitem> - <para>Brent J. Nordquist <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Brett Taylor - <email>brett@peloton.runet.edu</email></para> - </listitem> - - <listitem> - <para>Brian Campbell <email>brianc@pobox.com</email></para> - </listitem> - - <listitem> - <para>Brian Clapper <email>bmc@willscreek.com</email></para> - </listitem> - - <listitem> - <para>Brian Cully <email>shmit@kublai.com</email></para> - </listitem> - - <listitem> - <para>Brian Handy - <email>handy@lambic.space.lockheed.com</email></para> - </listitem> - - <listitem> - <para>Brian Litzinger <email>brian@MediaCity.com</email></para> - </listitem> - - <listitem> - <para>Brian McGovern <email>bmcgover@cisco.com</email></para> - </listitem> - - <listitem> - <para>Brian Moore <email>ziff@houdini.eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Brian R. Haug <email>haug@conterra.com</email></para> - </listitem> - - <listitem> - <para>Brian Tao <email>taob@risc.org</email></para> - </listitem> - - <listitem> - <para>Brion Moss <email>brion@queeg.com</email></para> - </listitem> - - <listitem> - <para>Bruce Albrecht <email>bruce@zuhause.mn.org</email></para> - </listitem> - - <listitem> - <para>Bruce Gingery <email>bgingery@gtcs.com</email></para> - </listitem> - - <listitem> - <para>Bruce J. Keeler <email>loodvrij@gridpoint.com</email></para> - </listitem> - - <listitem> - <para>Bruce Murphy <email>packrat@iinet.net.au</email></para> - </listitem> - - <listitem> - <para>Bruce Walter <email>walter@fortean.com</email></para> - </listitem> - - <listitem> - <para>Carey Jones <email>mcj@acquiesce.org</email></para> - </listitem> - - <listitem> - <para>Carl Fongheiser <email>cmf@netins.net</email></para> - </listitem> - - <listitem> - <para>Carl Mascott <email>cmascott@world.std.com</email></para> - </listitem> - - <listitem> - <para>Casper <email>casper@acc.am</email></para> - </listitem> - - <listitem> - <para>Castor Fu <email>castor@geocast.com</email></para> - </listitem> - - <listitem> - <para>Chain Lee <email>chain@110.net</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Charles Henrich <email>henrich@msu.edu</email></para> - </listitem> - - <listitem> - <para>Charles Mott <email>cmott@scientech.com</email></para> - </listitem> - - <listitem> - <para>Charles Owens <email>owensc@enc.edu</email></para> - </listitem> - - <listitem> - <para>Chet Ramey <email>chet@odin.INS.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Chia-liang Kao <email>clkao@CirX.ORG</email></para> - </listitem> - - <listitem> - <para>Chiharu Shibata <email>chi@bd.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Chip Norkus <email>unknown</email></para> - </listitem> - - <listitem> - <para>Chris Csanady <email>cc@tarsier.ca.sandia.gov</email></para> - </listitem> - - <listitem> - <para>Chris Dabrowski <email>chris@vader.org</email></para> - </listitem> - - <listitem> - <para>Chris Dillon <email>cdillon@wolves.k12.mo.us</email></para> - </listitem> - - <listitem> - <para>Chris Shenton - <email>cshenton@angst.it.hq.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Chris Stenton <email>jacs@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>Chris Timmons <email>skynyrd@opus.cts.cwu.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christian Gusenbauer - <email>cg@fimp01.fim.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christian Haury <email>Christian.Haury@sagem.fr</email></para> - </listitem> - - <listitem> - <para>Christian Weisgerber - <email>naddy@mips.inka.de</email></para> - </listitem> - - <listitem> - <para>Christoph P. Kukulies <email>kuku@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christoph Weber-Fahr - <email>wefa@callcenter.systemhaus.net</email></para> - </listitem> - - <listitem> - <para>Christopher G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Christopher N. Harrell <email>cnh@ivmg.net</email></para> - </listitem> - - <listitem> - <para>Christopher T. Johnson - <email>cjohnson@neunacht.netgsi.com</email></para> - </listitem> - - <listitem> - <para>Chrisy Luke <email>chrisy@flix.net</email></para> - </listitem> - - <listitem> - <para>Chuck Hein <email>chein@cisco.com</email></para> - </listitem> - - <listitem> - <para>Cliff Rowley <email>dozprompt@onsea.com</email></para> - </listitem> - - <listitem> - <para>Clive Lin <email>clive@CiRX.ORG</email></para> - </listitem> - - <listitem> - <para>Colman Reilly <email>careilly@tcd.ie</email></para> - </listitem> - - <listitem> - <para>Conrad Sabatier <email>conrads@neosoft.com</email></para> - </listitem> - - <listitem> - <para>Coranth Gryphon <email>gryphon@healer.com</email></para> - </listitem> - - <listitem> - <para>Cornelis van der Laan - <email>nils@guru.ims.uni-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Cove Schneider <email>cove@brazil.nbn.com</email></para> - </listitem> - - <listitem> - <para>Craig Leres <email>leres@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Craig Loomis <email>unknown</email></para> - </listitem> - - <listitem> - <para>Craig Metz <email>cmetz@inner.net</email></para> - </listitem> - - <listitem> - <para>Craig Spannring <email>cts@internetcds.com</email></para> - </listitem> - - <listitem> - <para>Craig Struble <email>cstruble@vt.edu</email></para> - </listitem> - - <listitem> - <para>Cristian Ferretti <email>cfs@riemann.mat.puc.cl</email></para> - </listitem> - - <listitem> - <para>Curt Mayer <email>curt@toad.com</email></para> - </listitem> - - <listitem> - <para>Cy Schubert <email>cschuber@uumail.gov.bc.ca</email></para> - </listitem> - - <listitem> - <para>Cyrille Lefevre <email>clefevre@citeweb.net</email></para> - </listitem> - - <listitem> - <para>Cyrus Rahman <email>cr@jcmax.com</email></para> - </listitem> - - <listitem> - <para>Dai Ishijima <email>ishijima@tri.pref.osaka.jp</email></para> - </listitem> - - <listitem> - <para>Daisuke Watanabe <email>NU7D-WTNB@asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Damian Hamill <email>damian@cablenet.net</email></para> - </listitem> - - <listitem> - <para>Dan Cross <email>tenser@spitfire.ecsel.psu.edu</email></para> - </listitem> - - <listitem> - <para>Dan Lukes <email>dan@obluda.cz</email></para> - </listitem> - - <listitem> - <para>Dan Nelson <email>dnelson@emsphone.com</email></para> - </listitem> - - <listitem> - <para>Dan Papasian <email>bugg@bugg.strangled.net</email></para> - </listitem> - - <listitem> - <para>Dan Piponi <email>wmtop@tanelorn.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dan Walters <email>hannibal@cyberstation.net</email></para> - </listitem> - - <listitem> - <para>Daniel Hagan - <email>dhagan@cs.vt.edu</email></para> - </listitem> - - <listitem> - <para>Daniel M. Eischen - <email>deischen@iworks.InterWorks.org</email></para> - </listitem> - - <listitem> - <para>Daniel O'Connor <email>doconnor@gsoft.com.au</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Daniel Rock <email>rock@cs.uni-sb.de</email></para> - </listitem> - - <listitem> - <para>Danny Egen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Danny J. Zerkel <email>dzerkel@phofarm.com</email></para> - </listitem> - - <listitem> - <para>Darren Reed <email>avalon@coombs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Dave Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>Dave Andersen <email>angio@aros.net</email></para> - </listitem> - - <listitem> - <para>Dave Blizzard <email>dblizzar@sprynet.com</email></para> - </listitem> - - <listitem> - <para>Dave Bodenstab <email>imdave@synet.net</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Chapeskie <email>dchapes@ddm.on.ca</email></para> - </listitem> - - <listitem> - <para>Dave Cornejo <email>dave@dogwood.com</email></para> - </listitem> - - <listitem> - <para>Dave Edmondson <email>davided@sco.com</email></para> - </listitem> - - <listitem> - <para>Dave Glowacki <email>dglo@ssec.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Dave Marquardt <email>marquard@austin.ibm.com</email></para> - </listitem> - - <listitem> - <para>Dave Tweten <email>tweten@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>David A. Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>David A. Bader <email>dbader@eece.unm.edu</email></para> - </listitem> - - <listitem> - <para>David Borman <email>dab@bsdi.com</email></para> - </listitem> - - <listitem> - <para>David W. Chapman Jr. <email>dwcjr@inethouston.net</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@XFree86.org</email></para> - </listitem> - - <listitem> - <para>David Filo <email>unknown</email></para> - </listitem> - - <listitem> - <para>David Holland <email>dholland@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>David Holloway <email>daveh@gwythaint.tamis.com</email></para> - </listitem> - - <listitem> - <para>David Horwitt <email>dhorwitt@ucsd.edu</email></para> - </listitem> - - <listitem> - <para>David Hovemeyer <email>daveho@infocom.com</email></para> - </listitem> - - <listitem> - <para>David Jones <email>dej@qpoint.torfree.net</email></para> - </listitem> - - <listitem> - <para>David Kelly <email>dkelly@tomcat1.tbe.com</email></para> - </listitem> - - <listitem> - <para>David Kulp <email>dkulp@neomorphic.com</email></para> - </listitem> - - <listitem> - <para>David L. Nugent <email>davidn@blaze.net.au</email></para> - </listitem> - - <listitem> - <para>David Leonard <email>d@scry.dstc.edu.au</email></para> - </listitem> - - <listitem> - <para>David Muir Sharnoff <email>muir@idiom.com</email></para> - </listitem> - - <listitem> - <para>David S. Miller <email>davem@jenolan.rutgers.edu</email></para> - </listitem> - - <listitem> - <para>David Sugar <email>dyfet@gnu.org</email></para> - </listitem> - - <listitem> - <para>David Wolfskill <email>dhw@whistle.com</email></para> - </listitem> - - <listitem> - <para>Dean Gaudet <email>dgaudet@arctic.org</email></para> - </listitem> - - <listitem> - <para>Dean Huxley <email>dean@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Denis Fortin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Denis Shaposhnikov <email>dsh@vlink.ru</email></para> - </listitem> - - <listitem> - <para>Dennis Glatting - <email>dennis.glatting@software-munitions.com</email></para> - </listitem> - - <listitem> - <para>Denton Gentry <email>denny1@home.com</email></para> - </listitem> - - <listitem> - <para>der Mouse <email>mouse@Collatz.McRCIM.McGill.EDU</email></para> - </listitem> - - <listitem> - <para>Derek Inksetter <email>derek@saidev.com</email></para> - </listitem> - - <listitem> - <para>DI. Christian Gusenbauer - <email>cg@scotty.edvz.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Dirk Keunecke <email>dk@panda.rhein-main.de</email></para> - </listitem> - - <listitem> - <para>Dirk Meyer <email>dirk.meyer@dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Dirk Nehrling <email>nerle@pdv.de</email></para> - </listitem> - - <listitem> - <para>Dishanker Rajakulendren <email>draj@oceanfree.net</email></para> - </listitem> - - <listitem> - <para>Dmitry Khrustalev <email>dima@xyzzy.machaon.ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Kohmanyuk <email>dk@farm.org</email></para> - </listitem> - - <listitem> - <para>Dom Mitchell <email>dom@myrddin.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Domas Mituzas <email>midom@dammit.lt</email></para> - </listitem> - - <listitem> - <para>Dominik Brettnacher <email>domi@saargate.de</email></para> - </listitem> - - <listitem> - <para>Dominik Rothert <email>dr@domix.de</email></para> - </listitem> - - <listitem> - <para>Don Croyle <email>croyle@gelemna.ft-wayne.in.us</email></para> - </listitem> - - <listitem> - <para>Donn Miller <email>dmmiller@cvzoom.net</email></para> - </listitem> - - <listitem> - <para>Dan Pelleg <email>dpelleg+unison@cs.cmu.edu</email></para> - </listitem> - - <listitem> - <para>&a.whiteside;</para> - </listitem> - - <listitem> - <para>Don Morrison <email>dmorrisn@u.washington.edu</email></para> - </listitem> - - <listitem> - <para>Don Yuniskis <email>dgy@rtd.com</email></para> - </listitem> - - <listitem> - <para>Donald Maddox <email>dmaddox@conterra.com</email></para> - </listitem> - - <listitem> - <para>Douglas Ambrisko <email>ambrisko@whistle.com</email></para> - </listitem> - - <listitem> - <para>Douglas Carmichael <email>dcarmich@mcs.com</email></para> - </listitem> - - <listitem> - <para>Douglas Crosher <email>dtc@scrooge.ee.swin.oz.au</email></para> - </listitem> - - <listitem> - <para>Drew Derbyshire <email>ahd@kew.com</email></para> - </listitem> - - <listitem> - <para>Duncan Barclay <email>dmlb@ragnet.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dustin Sallings <email>dustin@spy.net</email></para> - </listitem> - - <listitem> - <para>Eckart "Isegrim" Hofmann - <email>Isegrim@Wunder-Nett.org</email></para> - </listitem> - - <listitem> - <para>Ed Gold - <email>vegold01@starbase.spd.louisville.edu</email></para> - </listitem> - - <listitem> - <para>Ed Hudson <email>elh@p5.spnet.com</email></para> - </listitem> - - <listitem> - <para>Edward Chuang <email>edwardc@firebird.org.tw</email></para> - </listitem> - - <listitem> - <para>Edward Wang <email>edward@edcom.com</email></para> - </listitem> - - <listitem> - <para>Edwin Groothus <email>edwin@nwm.wan.philips.com</email></para> - </listitem> - - <listitem> - <para>Edwin Mons <email>e@ik.nu</email></para> - </listitem> - - <listitem> - <para>Ege Rekk <email>aagero@aage.priv.no</email></para> - </listitem> - - <listitem> - <para>Eiji-usagi-MATSUmoto <email>usagi@clave.gr.jp</email></para> - </listitem> - - <listitem> - <para>Eike Bernhardt <email>eike.bernhardt@gmx.de</email></para> - </listitem> - - <listitem> - <para>ELISA Font Project</para> - </listitem> - - <listitem> - <para>Elmar Bartel - <email>bartel@informatik.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Eoin Lawless <email>eoin@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Eric A. Griff <email>eagriff@global2000.net</email></para> - </listitem> - - <listitem> - <para>Eric Melville <email>eric@osd.bsdi.com</email></para> - </listitem> - - <listitem> - <para>Eric Blood <email>eblood@cs.unr.edu</email></para> - </listitem> - - <listitem> - <para>Eric D. Futch <email>efutch@nyct.net</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Schwertfeger <email>eric@cybernut.com</email></para> - </listitem> - - <listitem> - <para>Eric L. Hernes <email>erich@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>Eric P. Scott <email>eps@sirius.com</email></para> - </listitem> - - <listitem> - <para>Eric Sprinkle <email>eric@ennovatenetworks.com</email></para> - </listitem> - - <listitem> - <para>Erich Stefan Boleyn <email>erich@uruk.org</email></para> - </listitem> - - <listitem> - <para>Erich Zigler <email>erich@tacni.net</email></para> - </listitem> - - <listitem> - <para>Erik H. Bakke <email>erikhb@bgnett.no</email></para> - </listitem> - - <listitem> - <para>Erik E. Rantapaa <email>rantapaa@math.umn.edu</email></para> - </listitem> - - <listitem> - <para>Erik H. Moe <email>ehm@cris.com</email></para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email></para> - </listitem> - - <listitem> - <para>Espen Skoglund <email>esk@ira.uka.de</email></para> - </listitem> - - <listitem> - <para>Eugene M. Kim <email>astralblue@usa.net</email></para> - </listitem> - - <listitem> - <para>Eugene Radchenko <email>genie@qsar.chem.msu.su</email></para> - </listitem> - - <listitem> - <para>Eugeny Kuzakov <email>CoreDumped@coredumped.null.ru</email></para> - </listitem> - - <listitem> - <para>Evan Champion <email>evanc@synapse.net</email></para> - </listitem> - - <listitem> - <para>Faried Nawaz <email>fn@Hungry.COM</email></para> - </listitem> - - <listitem> - <para>Flemming Jacobsen <email>fj@tfs.com</email></para> - </listitem> - - <listitem> - <para>Fong-Ching Liaw <email>fong@juniper.net</email></para> - </listitem> - - <listitem> - <para>Francis M J Hsieh <email>mjshieh@life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Bartels <email>knarf@camelot.de</email></para> - </listitem> - - <listitem> - <para>Frank Chen Hsiung Chan - <email>frankch@waru.life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Durda IV <email>uhclem@nemesis.lonestar.org</email></para> - </listitem> - - <listitem> - <para>Frank MacLachlan <email>fpm@n2.net</email></para> - </listitem> - - <listitem> - <para>Frank Nobis <email>fn@Radio-do.de</email></para> - </listitem> - - <listitem> - <para>Frank ten Wolde <email>franky@pinewood.nl</email></para> - </listitem> - - <listitem> - <para>Frank van der Linden <email>frank@fwi.uva.nl</email></para> - </listitem> - - <listitem> - <para>Frank Volf <email>volf@oasis.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Fred Cawthorne <email>fcawth@jjarray.umn.edu</email></para> - </listitem> - - <listitem> - <para>Fred Gilham <email>gilham@csl.sri.com</email></para> - </listitem> - - <listitem> - <para>Fred Templin <email>templin@erg.sri.com</email></para> - </listitem> - - <listitem> - <para>Frederick Earl Gray <email>fgray@rice.edu</email></para> - </listitem> - - <listitem> - <para>FUJIMOTO Kensaku - <email>fujimoto@oscar.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>FUJISHIMA Satsuki <email>k5@respo.or.jp</email></para> - </listitem> - - <listitem> - <para>FURUSAWA Kazuhisa - <email>furusawa@com.cs.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>G. Adam Stanislav<email>adam@whizkidtech.net</email></para> - </listitem> - - <listitem> - <para>Gabor Kincses <email>gabor@acm.org</email></para> - </listitem> - - <listitem> - <para>Gabor Zahemszky <email>zgabor@CoDe.hu</email></para> - </listitem> - - <listitem> - <para>Gareth McCaughan <email>gjm11@dpmms.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Gary J. <email>garyj@rks32.pcs.dec.com</email></para> - </listitem> - - <listitem> - <para>Gary Kline <email>kline@thought.org</email></para> - </listitem> - - <listitem> - <para>Gaspar Chilingarov <email>nightmar@lemming.acc.am</email></para> - </listitem> - - <listitem> - <para>Gea-Suan Lin <email>gsl@tpts4.seed.net.tw</email></para> - </listitem> - - <listitem> - <para>Gene Raytsin <email>pal@paladin7.net</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Georg Wagner <email>georg.wagner@ubs.com</email></para> - </listitem> - - <listitem> - <para>George Reid <email>services@nevernet.net</email></para> - </listitem> - - <listitem> - <para>Gianlorenzo Masini <email>masini@uniroma3.it</email></para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@giovannelli.it</email></para> - </listitem> - - <listitem> - <para>Gil Kloepfer Jr. <email>gil@limbic.ssdl.com</email></para> - </listitem> - - <listitem> - <para>Gilad Rom <email>rom_glsa@ein-hashofet.co.il</email></para> - </listitem> - - <listitem> - <para>Giles Lean <email>giles@nemeton.com.au</email></para> - </listitem> - - <listitem> - <para>Ginga Kawaguti - <email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Giorgos Keramidas <email>keramida@ceid.upatras.gr</email></para> - </listitem> - - <listitem> - <para>Glen Foster <email>gfoster@gfoster.com</email></para> - </listitem> - - <listitem> - <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>Godmar Back <email>gback@facility.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Gord Matzigkeit <email>gord@enci.ucalgary.ca</email></para> - </listitem> - - <listitem> - <para>Gordon Greeff <email>gvg@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Graham Wheeler <email>gram@cdsec.com</email></para> - </listitem> - - <listitem> - <para>Greg A. Woods <email>woods@zeus.leitch.com</email></para> - </listitem> - - <listitem> - <para>Greg Ansley <email>gja@ansley.com</email></para> - </listitem> - - <listitem> - <para>Greg Robinson <email>greg@rosevale.com.au</email></para> - </listitem> - - <listitem> - <para>Greg Troxel <email>gdt@ir.bbn.com</email></para> - </listitem> - - <listitem> - <para>Greg Ungerer <email>gerg@stallion.oz.au</email></para> - </listitem> - - <listitem> - <para>Gregory Bond <email>gnb@itga.com.au</email></para> - </listitem> - - <listitem> - <para>Gregory D. Moncreaff - <email>moncrg@bt340707.res.ray.com</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@netapp.com</email></para> - </listitem> - - <listitem> - <para>Guy Helmer <email>ghelmer@cs.iastate.edu</email></para> - </listitem> - - <listitem> - <para>HAMADA Naoki <email>hamada@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>Hannu Savolainen <email>hannu@voxware.pp.fi</email></para> - </listitem> - - <listitem> - <para>Hans Huebner <email>hans@artcom.de</email></para> - </listitem> - - <listitem> - <para>Hans Petter Bieker <email>zerium@webindex.no</email></para> - </listitem> - - <listitem> - <para>Hans Zuidam <email>hans@brandinnovators.com</email></para> - </listitem> - - <listitem> - <para>Harlan Stenn <email>Harlan.Stenn@pfcs.com</email></para> - </listitem> - - <listitem> - <para>Harold Barker <email>hbarker@dsms.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Heikki Suonsivu <email>hsu@cs.hut.fi</email></para> - </listitem> - - <listitem> - <para>Heiko W. Rupp <email>unknown</email></para> - </listitem> - - <listitem> - <para>Helmut F. Wirth <email>hfwirth@ping.at</email></para> - </listitem> - - <listitem> - <para>Henrik Vestergaard Draboel - <email>hvd@terry.ping.dk</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Hideaki Ohmon <email>ohmon@tom.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidekazu Kuroki <email>hidekazu@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hideki Yamamoto <email>hyama@acm.org</email></para> - </listitem> - - <listitem> - <para>Hideyuki Suzuki - <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hirayama Issei <email>iss@mail.wbs.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroaki Sakai <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hiroharu Tamaru <email>tamaru@ap.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hironori Ikura <email>hikura@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Hiroshi Nishikawa <email>nis@pluto.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroya Tsubakimoto <email>unknown</email></para> - </listitem> - - <listitem> - <para>Holger Lamm <email>holger@eit.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Holm Tiffe <email>holm@geophysik.tu-freiberg.de</email></para> - </listitem> - - <listitem> - <para>HONDA Yasuhiro - <email>honda@kashio.info.mie-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Horance Chou - <email>horance@freedom.ie.cycu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Horihiro Kumagai <email>kuma@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>HOSOBUCHI Noriyuki <email>hoso@buchi.tama.or.jp</email></para> - </listitem> - - <listitem> - <para>HOTARU-YA <email>hotaru@tail.net</email></para> - </listitem> - - <listitem> - <para>Hr.Ladavac <email>lada@ws2301.gud.siemens.co.at</email></para> - </listitem> - - <listitem> - <para>Hubert Feyrer <email>hubertf@NetBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Hugh F. Mahon <email>hugh@nsmdserv.cnd.hp.com</email></para> - </listitem> - - <listitem> - <para>Hugh Mahon <email>h_mahon@fc.hp.com</email></para> - </listitem> - - <listitem> - <para>Hung-Chi Chu <email>hcchu@r350.ee.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ian Dowse <email>iedowse@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Ian Holland <email>ianh@tortuga.com.au</email></para> - </listitem> - - <listitem> - <para>Ian Struble <email>ian@broken.net</email></para> - </listitem> - - <listitem> - <para>Ian Vaudrey <email>i.vaudrey@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Igor Khasilev <email>igor@jabber.paco.odessa.ua</email></para> - </listitem> - - <listitem> - <para>Igor Roshchin <email>str@giganda.komkon.org</email></para> - </listitem> - - <listitem> - <para>Igor Sviridov <email>siac@ua.net</email></para> - </listitem> - - <listitem> - <para>Igor Vinokurov <email>igor@zynaps.ru</email></para> - </listitem> - - <listitem> - <para>Ikuo Nakagawa <email>ikuo@isl.intec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ilia Chipitsine <email>ilia@jane.cgu.chel.su</email></para> - </listitem> - - <listitem> - <para>Ilya V. Komarov <email>mur@lynx.ru</email></para> - </listitem> - - <listitem> - <para>IMAI Takeshi <email>take-i@ceres.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>IMAMURA Tomoaki - <email>tomoak-i@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>Itsuro Saito <email>saito@miv.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>IWASHITA Yoji <email>shuna@pop16.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>J. Bryant <email>jbryant@argus.flash.net</email></para> - </listitem> - - <listitem> - <para>J. David Lowe <email>lowe@saturn5.com</email></para> - </listitem> - - <listitem> - <para>J. Han <email>hjh@photino.com</email></para> - </listitem> - - <listitem> - <para>J. Hawk <email>jhawk@MIT.EDU</email></para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jack <email>jack@zeus.xtalwind.net</email></para> - </listitem> - - <listitem> - <para>Jacob Bohn Lorensen <email>jacob@jblhome.ping.mk</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>Jake Hamby <email>jehamby@lightside.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James D. Stewart <email>jds@c4systm.com</email></para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James Raynard - <email>fhackers@jraynard.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>James T. Liu <email>jtliu@phlebas.rockefeller.edu</email></para> - </listitem> - - <listitem> - <para>Jamie Heckford <email>jamie@jamiesdomain.co.uk</email></para> - </listitem> - - <listitem> - <para>Jan Conard - <email>charly@fachschaften.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Jan Koum <email>jkb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Janick Taillandier - <email>Janick.Taillandier@ratp.fr</email></para> - </listitem> - - <listitem> - <para>Janusz Kokot <email>janek@gaja.ipan.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Jarle Greipsland <email>jarle@idt.unit.no</email></para> - </listitem> - - <listitem> - <para>Jason Garman <email>init@risen.org</email></para> - </listitem> - - <listitem> - <para>Jason Thorpe <email>thorpej@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Wright <email>jason@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Young - <email>doogie@forbidden-donut.anet-stl.com</email></para> - </listitem> - - <listitem> - <para>Javier Martin Rueda <email>jmrueda@diatel.upm.es</email></para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jay Krell <email>jay.krell@cornell.edu</email></para> - </listitem> - - <listitem> - <para>Jaye Mathisen <email>mrcpu@cdsnet.net</email></para> - </listitem> - - <listitem> - <para>Jeff Bartig <email>jeffb@doit.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Jeff Brown <email>jabrown@caida.org</email></para> - </listitem> - - <listitem> - <para>Jeff Forys <email>jeff@forys.cranbury.nj.us</email></para> - </listitem> - - <listitem> - <para>Jeff Kletsky <email>Jeff@Wagsky.com</email></para> - </listitem> - - <listitem> - <para>Jeff Palmer <email>jeff@isni.net</email></para> - </listitem> - - <listitem> - <para>Jeffrey Evans <email>evans@scnc.k12.mi.us</email></para> - </listitem> - - <listitem> - <para>Jeffrey Wheat <email>jeff@cetlink.net</email></para> - </listitem> - - <listitem> - <para>Jens Schweikhardt <email>schweikh@noc.dfn.d</email></para> - </listitem> - - <listitem> - <para>Jeremy Allison <email>jallison@whistle.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chadwick <email>yoshi@parodius.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chatfield <email>jdc@xinside.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Karlson <email>karlj000@unbc.ca</email></para> - </listitem> - - <listitem> - <para>Jeremy Prior <email>unknown</email></para> - </listitem> - - <listitem> - <para>Jeremy Shaffner <email>jeremy@external.org</email></para> - </listitem> - - <listitem> - <para>Jesse McConnell <email>jesse@cylant.com</email></para> - </listitem> - - <listitem> - <para>Jesse Rosenstock <email>jmr@ugcs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Jian-Da Li <email>jdli@csie.nctu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Jim Babb <email>babb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Jim Binkley <email>jrb@cs.pdx.edu</email></para> - </listitem> - - <listitem> - <para>Jim Bloom <email>bloom@acm.org</email></para> - </listitem> - - <listitem> - <para>Jim Carroll <email>jim@carroll.com</email></para> - </listitem> - - <listitem> - <para>Jim Flowers <email>jflowers@ezo.net</email></para> - </listitem> - - <listitem> - <para>Jim Leppek <email>jleppek@harris.com</email></para> - </listitem> - - <listitem> - <para>Jim Lowe <email>james@cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>Jim Mattson <email>jmattson@sonic.net</email></para> - </listitem> - - <listitem> - <para>Jim Mercer <email>jim@komodo.reptiles.org</email></para> - </listitem> - - <listitem> - <para>Jim Sloan <email>odinn@atlantabiker.net</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jimbo Bahooli - <email>griffin@blackhole.iceworld.org</email></para> - </listitem> - - <listitem> - <para>Jimmy Olgeni - <email>olgeni@uli.it</email></para> - </listitem> - - <listitem> - <para>Jin Guojun <email>jin@george.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Joachim Kuebart <email>kuebart@mathematik.uni-ulm.de</email></para> - </listitem> - - <listitem> - <para>Joao Carlos Mendes Luis <email>jonny@jonny.eng.br</email></para> - </listitem> - - <listitem> - <para>Jochen Pohl <email>jpo.drs@sni.de</email></para> - </listitem> - - <listitem> - <para>Joe "Marcus" Clarke <email>marcus@miami.edu</email></para> - </listitem> - - <listitem> - <para>Joe Abley <email>jabley@clear.co.nz</email></para> - </listitem> - - <listitem> - <para>Joe Jih-Shian Lu <email>jslu@dns.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Joe Orthoefer <email>j_orthoefer@tia.net</email></para> - </listitem> - - <listitem> - <para>Joe Traister <email>traister@mojozone.org</email></para> - </listitem> - - <listitem> - <para>Joel Faedi <email>Joel.Faedi@esial.u-nancy.fr</email></para> - </listitem> - - <listitem> - <para>Joel Ray Holveck <email>joelh@gnu.org</email></para> - </listitem> - - <listitem> - <para>Joel Sutton <email>jsutton@bbcon.com.au</email></para> - </listitem> - - <listitem> - <para>Joseph Scott <email>joseph.scott@owp.csus.edu</email></para> - </listitem> - - <listitem> - <para>Johan Granlund <email>johan@granlund.nu</email></para> - </listitem> - - <listitem> - <para>Johan Karlsson <email>k@numeri.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johan Larsson <email>johan@moon.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johann Tonsing <email>jtonsing@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Johannes Helander <email>unknown</email></para> - </listitem> - - <listitem> - <para>Johannes Stille <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Beckett <email>jbeckett@southern.edu</email></para> - </listitem> - - <listitem> - <para>John Beukema <email>jbeukema@hk.super.net</email></para> - </listitem> - - <listitem> - <para>John Brezak <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Capo <email>jc@irbs.com</email></para> - </listitem> - - <listitem> - <para>John F. Woods <email>jfw@jfwhome.funhouse.com</email></para> - </listitem> - - <listitem> - <para>John Goerzen - <email>jgoerzen@alexanderwohl.complete.org</email></para> - </listitem> - - <listitem> - <para>John Hay <email>jhay@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>John Heidemann <email>johnh@isi.edu</email></para> - </listitem> - - <listitem> - <para>John Hood <email>cgull@owl.org</email></para> - </listitem> - - <listitem> - <para>John Kohl <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Lind <email>john@starfire.mn.org</email></para> - </listitem> - - <listitem> - <para>John Mackin <email>john@physiol.su.oz.au</email></para> - </listitem> - - <listitem> - <para>John P <email>johnp@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>John Perry <email>perry@vishnu.alias.net</email></para> - </listitem> - - <listitem> - <para>John Preisler <email>john@vapornet.com</email></para> - </listitem> - - <listitem> - <para>John Rochester <email>jr@cs.mun.ca</email></para> - </listitem> - - <listitem> - <para>John Sadler <email>john_sadler@alum.mit.edu</email></para> - </listitem> - - <listitem> - <para>John Saunders <email>john@pacer.nlc.net.au</email></para> - </listitem> - - <listitem> - <para>John Wehle <email>john@feith.com</email></para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jon Morgan <email>morgan@terminus.trailblazer.com</email></para> - </listitem> - - <listitem> - <para>Jonathan H N Chin <email>jc254@newton.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Jonathan Hanna - <email>jh@pc-21490.bc.rogers.wave.ca</email></para> - </listitem> - - <listitem> - <para>Jorge Goncalves <email>j@bug.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jorge M. Goncalves <email>ee96199@tom.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jos Backus <email>jbackus@plex.nl</email></para> - </listitem> - - <listitem> - <para>Jose M. Alcaide <email>jose@we.lc.ehu.es</email></para> - </listitem> - - <listitem> - <para>Jose Marques <email>jose@nobody.org</email></para> - </listitem> - - <listitem> - <para>Josef Grosch - <email>jgrosch@superior.mooseriver.com</email></para> - </listitem> - - <listitem> - <para>Joseph Stein <email>joes@wstein.com</email></para> - </listitem> - - <listitem> - <para>Josh Gilliam <email>josh@quick.net</email></para> - </listitem> - - <listitem> - <para>Josh Tiefenbach <email>josh@ican.net</email></para> - </listitem> - - <listitem> - <para>Juergen Lock <email>nox@jelal.hb.north.de</email></para> - </listitem> - - <listitem> - <para>Juha Inkari <email>inkari@cc.hut.fi</email></para> - </listitem> - - <listitem> - <para>Jukka A. Ukkonen <email>jau@iki.fi</email></para> - </listitem> - - <listitem> - <para>Julian Assange <email>proff@suburbia.net</email></para> - </listitem> - - <listitem> - <para>Julian Coleman <email>j.d.coleman@ncl.ac.uk</email></para> - </listitem> - - <listitem> - <para>&a.jhs</para> - </listitem> - - <listitem> - <para>Julian Jenkins <email>kaveman@magna.com.au</email></para> - </listitem> - - <listitem> - <para>Junichi Satoh <email>junichi@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junji SAKAI <email>sakai@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junya WATANABE <email>junya-w@remus.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Justas <email>justas@mbank.lv</email></para> - </listitem> - - <listitem> - <para>Justin Stanford <email>jus@security.za.net</email></para> - </listitem> - - <listitem> - <para>K.Higashino <email>a00303@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kai Vorma <email>vode@snakemail.hut.fi</email></para> - </listitem> - - <listitem> - <para>Kaleb S. Keithley <email>kaleb@ics.com</email></para> - </listitem> - - <listitem> - <para>Kaneda Hiloshi <email>vanitas@ma3.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kapil Chowksey <email>kchowksey@hss.hns.com</email></para> - </listitem> - - <listitem> - <para>Karl Denninger <email>karl@mcs.com</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>KATO Tsuguru <email>tkato@prontomail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kawanobe Koh <email>kawanobe@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Kees Jan Koster <email>kjk1@ukc.ac.uk</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@bostic.com</email></para> - </listitem> - - <listitem> - <para>Keith E. Walker <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Moore <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Sklower <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Hornstein <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Key <email>key@cs.utk.edu</email></para> - </listitem> - - <listitem> - <para>Ken Mayer <email>kmayer@freegate.com</email></para> - </listitem> - - <listitem> - <para>Kenji Saito <email>marukun@mx2.nisiq.net</email></para> - </listitem> - - <listitem> - <para>Kenji Tomita <email>tommyk@da2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Kenneth Furge <email>kenneth.furge@us.endress.com</email></para> - </listitem> - - <listitem> - <para>Kenneth Monville <email>desmo@bandwidth.org</email></para> - </listitem> - - <listitem> - <para>Kenneth R. Westerback <email>krw@tcn.net</email></para> - </listitem> - - <listitem> - <para>Kenneth Stailey <email>kstailey@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kent Vander Velden <email>graphix@iastate.edu</email></para> - </listitem> - - <listitem> - <para>Kentaro Inagaki <email>JBD01226@niftyserve.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kevin Bracey <email>kbracey@art.acorn.co.uk</email></para> - </listitem> - - <listitem> - <para>Kevin Day <email>toasty@dragondata.com</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml@nas.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Kevin Meltzer <email>perlguy@perlguy.com</email></para> - </listitem> - - <listitem> - <para>Kevin Street <email>street@iname.com</email></para> - </listitem> - - <listitem> - <para>Kevin Van Maren <email>vanmaren@fast.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Kim Scarborough <email>sluggo@unknown.nu</email></para> - </listitem> - - <listitem> - <para>Kiril Mitev <email>kiril@ideaglobal.com</email></para> - </listitem> - - <listitem> - <para>Kiroh HARADA <email>kiroh@kh.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Klaus Herrmann <email>klaus.herrmann@gmx.net</email></para> - </listitem> - - <listitem> - <para>Klaus Klein <email>kleink@layla.inka.de</email></para> - </listitem> - - <listitem> - <para>Klaus-J. Wolf <email>Yanestra@t-online.de</email></para> - </listitem> - - <listitem> - <para>Koichi Sato <email>copan@ppp.fastnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Konstantin Chuguev <email>Konstantin.Chuguev@dante.org.uk</email></para> - </listitem> - - <listitem> - <para>Kostya Lukin <email>lukin@okbmei.msk.su</email></para> - </listitem> - - <listitem> - <para>Kouichi Hirabayashi <email>kh@mogami-wire.co.jp</email></para> - </listitem> - - <listitem> - <para>Kris Dow <email>kris@vilnya.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>KUNISHIMA Takeo <email>kunishi@c.oka-pu.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kurt D. Zeilenga <email>Kurt@Boolean.NET</email></para> - </listitem> - - <listitem> - <para>Kurt Olsen <email>kurto@tiny.mcs.usu.edu</email></para> - </listitem> - - <listitem> - <para>L. Jonas Olsson - <email>ljo@ljo-slip.DIALIN.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email></para> - </listitem> - - <listitem> - <para>Lars Köller - <email>Lars.Koeller@Uni-Bielefeld.DE</email></para> - </listitem> - - <listitem> - <para>Laurence Lopez <email>lopez@mv.mv.com</email></para> - </listitem> - - <listitem> - <para>Lee Cremeans <email>lcremean@tidalwave.net</email></para> - </listitem> - - <listitem> - <para>Leo Kim <email>leo@florida.sarang.net</email></para> - </listitem> - - <listitem> - <para>Liang Tai-hwa - <email>avatar@www.mmlab.cse.yzu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Lon Willett <email>lon%softt.uucp@math.utah.edu</email></para> - </listitem> - - <listitem> - <para>Louis A. Mamakos <email>louie@TransSys.COM</email></para> - </listitem> - - <listitem> - <para>Louis Mamakos <email>loiue@TransSys.com</email></para> - </listitem> - - <listitem> - <para>Lowell Gilbert <email>lowell@world.std.com</email></para> - </listitem> - - <listitem> - <para>Lucas James <email>Lucas.James@ldjpc.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Lyndon Nerenberg <email>lyndon@orthanc.ab.ca</email></para> - </listitem> - - <listitem> - <para>M. L. Dodson <email>bdodson@scms.utmb.EDU</email></para> - </listitem> - - <listitem> - <para>M.C. Wong <email>unknown</email></para> - </listitem> - - <listitem> - <para>Magnus Enbom <email>dot@tinto.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mahesh Neelakanta <email>mahesh@gcomm.com</email></para> - </listitem> - - <listitem> - <para>Makoto MATSUSHITA <email>matusita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Makoto WATANABE - <email>watanabe@zlab.phys.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Makoto YAMAKURA <email>makoto@pinpott.spnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>Malte Lance <email>malte.lance@gmx.net</email></para> - </listitem> - - <listitem> - <para>MANTANI Nobutaka <email>nobutaka@nobutaka.com</email></para> - </listitem> - - <listitem> - <para>Manu Iyengar - <email>iyengar@grunthos.pscwa.psca.com</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Marc Ramirez <email>mrami@mramirez.sy.yale.edu</email></para> - </listitem> - - <listitem> - <para>Marc Slemko <email>marcs@znep.com</email></para> - </listitem> - - <listitem> - <para>Marc van Kempen <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>Marc van Woerkom <email>van.woerkom@netcologne.de</email></para> - </listitem> - - <listitem> - <para>Marcin Cieslak <email>saper@system.pl</email></para> - </listitem> - - <listitem> - <para>Mark Andrews <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Cammidge <email>mark@gmtunx.ee.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Mark Diekhans <email>markd@grizzly.com</email></para> - </listitem> - - <listitem> - <para>Mark Huizer <email>xaa@stack.nl</email></para> - </listitem> - - <listitem> - <para>Mark J. Taylor <email>mtaylor@cybernet.com</email></para> - </listitem> - - <listitem> - <para>Mark Knight <email>markk@knigma.org</email></para> - </listitem> - - <listitem> - <para>Mark Krentel <email>krentel@rice.edu</email></para> - </listitem> - - <listitem> - <para>Mark Mayo <email>markm@vmunix.com</email></para> - </listitem> - - <listitem> - <para>Mark Thompson <email>thompson@tgsoft.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email></para> - </listitem> - - <listitem> - <para>Mark Treacy <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Valentine <email>mark@linus.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Markus Holmberg <email>saska@acc.umu.se</email></para> - </listitem> - - <listitem> - <para>Martin Birgmeier</para> - </listitem> - - <listitem> - <para>Martin Blapp <email>blapp@attic.ch</email></para> - </listitem> - - <listitem> - <para>Martin Hinner <email>mhi@linux.gyarab.cz</email></para> - </listitem> - - <listitem> - <para>Martin Ibert <email>mib@ppe.bb-data.de</email></para> - </listitem> - - <listitem> - <para>Martin Kammerhofer <email>dada@sbox.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Martin Minkus <email>diskiller@cnbinc.com</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Martti Kuparinen - <email>martti.kuparinen@ericsson.com</email></para> - </listitem> - - <listitem> - <para>Masachika ISHIZUKA - <email>ishizuka@isis.min.ntt.jp</email></para> - </listitem> - - <listitem> - <para>Masafumi NAKANE <email>max@wide.ad.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro Sekiguchi - <email>seki@sysrap.cs.fujitsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro TAKEMURA - <email>mastake@msel.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanobu Saitoh <email>msaitoh@spa.is.uec.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kanaoka <email>kana@saijo.mke.mei.co.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kiriake <email>seiken@ARGV.AC</email></para> - </listitem> - - <listitem> - <para>Masatoshi TAMURA - <email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mats Lofkvist <email>mal@algonet.se</email></para> - </listitem> - - <listitem> - <para>Matt Bartley <email>mbartley@lear35.cytex.com</email></para> - </listitem> - - <listitem> - <para>Matt Heckaman <email>matt@LUCIDA.QC.CA</email></para> - </listitem> - - <listitem> - <para>Matt Thomas <email>matt@3am-software.com</email></para> - </listitem> - - <listitem> - <para>Matt White <email>mwhite+@CMU.EDU</email></para> - </listitem> - - <listitem> - <para>Matthew C. Mead <email>mmead@Glock.COM</email></para> - </listitem> - - <listitem> - <para>Matthew Cashdollar <email>mattc@rfcnet.com</email></para> - </listitem> - - <listitem> - <para>Matthew Emmerton <email>root@gabby.gsicomp.on.ca</email></para> - </listitem> - - <listitem> - <para>Matthew Flatt <email>mflatt@cs.rice.edu</email></para> - </listitem> - - <listitem> - <para>Matthew Fuller <email>fullermd@futuresouth.com</email></para> - </listitem> - - <listitem> - <para>Matthew Stein <email>matt@bdd.net</email></para> - </listitem> - - <listitem> - <para>Matthew West <email>mwest@uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Matthias Pfaller <email>leo@dachau.marco.de</email></para> - </listitem> - - <listitem> - <para>Matthias Scheler <email>tron@netbsd.org</email></para> - </listitem> - - <listitem> - <para>Mattias Gronlund - <email>Mattias.Gronlund@sa.erisoft.se</email></para> - </listitem> - - <listitem> - <para>Mattias Pantzare <email>pantzer@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Maurice Castro - <email>maurice@planet.serc.rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Max Euston <email>meuston@jmrodgers.com</email></para> - </listitem> - - <listitem> - <para>Max Khon <email>fjoe@husky.iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxim Bolotin <email>max@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxime Henrion <email>mhenrion@cybercable.fr</email></para> - </listitem> - - <listitem> - <para>Micha Class - <email>michael_class@hpbbse.bbn.hp.com</email></para> - </listitem> - - <listitem> - <para>Michael Lucas <email>mwlucas@blackhelicopters.org</email></para> - </listitem> - - <listitem> - <para>Michael Butler <email>imb@scgt.oz.au</email></para> - </listitem> - - <listitem> - <para>Michael Butschky <email>butsch@computi.erols.com</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Elbel <email>me@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Michael Hancock <email>michaelh@cet.co.jp</email></para> - </listitem> - - <listitem> - <para>Michael Hohmuth <email>hohmuth@inf.tu-dresden.de</email></para> - </listitem> - - <listitem> - <para>Michael Perlman <email>canuck@caam.rice.edu</email></para> - </listitem> - - <listitem> - <para>Michael Petry <email>petry@netwolf.NetMasters.com</email></para> - </listitem> - - <listitem> - <para>Michael Reifenberger <email>root@totum.plaut.de</email></para> - </listitem> - - <listitem> - <para>Michael Sardo <email>jaeger16@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Michael Searle <email>searle@longacre.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Michael Urban <email>murban@tznet.com</email></para> - </listitem> - - <listitem> - <para>Michael Vasilenko <email>acid@stu.cn.ua</email></para> - </listitem> - - <listitem> - <para>Michal Listos <email>mcl@Amnesiac.123.org</email></para> - </listitem> - - <listitem> - <para>Michio Karl Jinbo - <email>karl@marcer.nagaokaut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Miguel Angel Sagreras - <email>msagre@cactus.fi.uba.ar</email></para> - </listitem> - - <listitem> - <para>Mihoko Tanaka <email>m_tonaka@pa.yokogawa.co.jp</email></para> - </listitem> - - <listitem> - <para>Mika Nystrom <email>mika@cs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Mikael Hybsch <email>micke@dynas.se</email></para> - </listitem> - - <listitem> - <para>Mikael Karpberg - <email>karpen@ocean.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mike Barcroft <email>mike@q9media.com</email></para> - </listitem> - - <listitem> - <para>Mike Del <email>repenting@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Mike Durian <email>durian@plutotech.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Mike E. Matsnev <email>mike@azog.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Mike Evans <email>mevans@candle.com</email></para> - </listitem> - - <listitem> - <para>Mike Grupenhoff <email>kashmir@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Mike Harding <email>mvh@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Mike Hibler <email>mike@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Mike Karels <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mike McGaughey <email>mmcg@cs.monash.edu.au</email></para> - </listitem> - - <listitem> - <para>Mike Meyer <email>mwm@mired.org</email></para> - </listitem> - - <listitem> - <para>Mike Mitchell <email>mitchell@ref.tfs.com</email></para> - </listitem> - - <listitem> - <para>Mike Murphy <email>mrm@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Mike Peck <email>mike@binghamton.edu</email></para> - </listitem> - - <listitem> - <para>Mike Sherwood <email>mike@fate.com</email></para> - </listitem> - - <listitem> - <para>Mike Spengler <email>mks@msc.edu</email></para> - </listitem> - - <listitem> - <para>Mikhail A. Sokolov <email>mishania@demos.su</email></para> - </listitem> - - <listitem> - <para>Mikhail Teterin <email>mi@aldan.algebra.com</email></para> - </listitem> - - <listitem> - <para>Ming-I Hseh <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>MITA Yoshio <email>mita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Mitsuru Yoshida <email>mitsuru@riken.go.jp</email></para> - </listitem> - - <listitem> - <para>Monte Mitzelfelt <email>monte@gonefishing.org</email></para> - </listitem> - - <listitem> - <para>Morgan Davis <email>root@io.cts.com</email></para> - </listitem> - - <listitem> - <para>MOROHOSHI Akihiko <email>moro@race.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mostyn Lewis <email>mostyn@mrl.com</email></para> - </listitem> - - <listitem> - <para>Motomichi Matsuzaki <email>mzaki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Motoyuki Kasahara <email>m-kasahr@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>N.G.Smith <email>ngs@sesame.hensa.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nadav Eiron <email>nadav@barcode.co.il</email></para> - </listitem> - - <listitem> - <para>NAGAO Tadaaki <email>nagao@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAJI Hiroyuki - <email>nakaji@tutrp.tut.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Kazushi <email>nkazushi@highway.or.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Motonori - <email>motonori@econ.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Nanbor Wang <email>nw1@cs.wustl.edu</email></para> - </listitem> - - <listitem> - <para>Naofumi Honda - <email>honda@Kururu.math.sci.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Narvi <email>narvi@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Nathan Ahlstrom <email>nrahlstr@winternet.com</email></para> - </listitem> - - <listitem> - <para>Nathan Dorfman <email>nathan@rtfm.net</email></para> - </listitem> - - <listitem> - <para>Neal Fachan <email>kneel@ishiboo.com</email></para> - </listitem> - - <listitem> - <para>Niall Smart <email>rotel@indigo.ie</email></para> - </listitem> - - <listitem> - <para>Nicholas Esborn <email>nick@netdot.net</email></para> - </listitem> - - <listitem> - <para>Nick Barnes <email>Nick.Barnes@pobox.com</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Nick Hilliard <email>nick@foobar.org</email></para> - </listitem> - - <listitem> - <para>Nick Johnson <email>freebsd@spatula.net</email></para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>Nick Williams <email>njw@cs.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nickolay N. Dudorov <email>nnd@itfs.nsk.su</email></para> - </listitem> - - <listitem> - <para>NIIMI Satoshi <email>sa2c@and.or.jp</email></para> - </listitem> - - <listitem> - <para>Niklas Hallqvist <email>niklas@filippa.appli.se</email></para> - </listitem> - - <listitem> - <para>Nisha Talagala <email>nisha@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>adrian@virginia.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>alex@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>anto@netscape.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>bobson@egg.ics.nitch.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>bovynf@awe.be</email></para> - </listitem> - - <listitem> - <para>No Name <email>burg@is.ge.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>chris@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>No Name <email>colsen@usa.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>coredump@nervosa.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>dannyman@arh0300.urh.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>davids@SECNET.COM</email></para> - </listitem> - - <listitem> - <para>No Name <email>derek@free.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>devet@adv.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>djv@bedford.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>dvv@sprint.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>enami@ba2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@eru.tubank.msk.su</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@hway.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>fn@pain.csrv.uidaho.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>frf@xocolatl.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gclarkii@netport.neosoft.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gordon@sheaky.lonestar.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>graaf@iae.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>greg@greg.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>grossman@cygnus.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gusw@fub46.zedat.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>No Name <email>hfir@math.rochester.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>hnokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iaint@css.tuu.utas.edu.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>invis@visi.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>ishisone@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iverson@lionheart.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>jpt@magic.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>No Name <email>k-sugyou@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kenji@reseau.toyonaka.osaka.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kfurge@worldnet.att.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>lh@aus.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>lhecking@nmrc.ucc.ie</email></para> - </listitem> - - <listitem> - <para>No Name <email>mrgreen@mame.mu.oz.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>nakagawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>owaki@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>pechter@shell.monmouth.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pete@pelican.pelican.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pritc003@maroon.tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>risner@stdio.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>roman@rpd.univ.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@ns2.redline.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@uglabgw.ug.cs.sunysb.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>stephen.ma@jtec.com.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>sumii@is.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>takas-su@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>tamone@eig.unige.ch</email></para> - </listitem> - - <listitem> - <para>No Name <email>tjevans@raleigh.ibm.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>tony-o@iij.ad.jp amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>torii@tcd.hitachi.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uenami@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uhlar@netlab.sk</email></para> - </listitem> - - <listitem> - <para>No Name <email>vode@hut.fi</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlloyd@mpd.ca</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlr@furball.wellsfargo.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>yamagata@nwgpc.kek.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>ziggy@ryan.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>ZW6T-KND@j.asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Nobuhiro Yasutomi <email>nobu@psrc.isac.co.jp</email></para> - </listitem> - - <listitem> - <para>Nobuyuki Koganemaru - <email>kogane@koganemaru.co.jp</email></para> - </listitem> - - <listitem> - <para>NOKUBI Hirotaka <email>h-nokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>Norio Suzuki <email>nosuzuki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Noritaka Ishizumi <email>graphite@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Noriyuki Soda <email>soda@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Oddbjorn Steffenson <email>oddbjorn@tricknology.org</email</para> - </listitem> - - <listitem> - <para>Oh Junseon <email>hollywar@mail.holywar.net</email></para> - </listitem> - - <listitem> - <para>Olaf Wagner <email>wagner@luthien.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Oleg Semyonov <email>os@altavista.net</email></para> - </listitem> - - <listitem> - <para>Oleg Sharoiko <email>os@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Oleg V. Volkov <email>rover@lglobus.ru</email></para> - </listitem> - - <listitem> - <para>Oliver Breuninger <email>ob@seicom.NET</email></para> - </listitem> - - <listitem> - <para>Oliver Friedrichs <email>oliver@secnet.com</email></para> - </listitem> - - <listitem> - <para>Oliver Fromme - <email>oliver.fromme@heim3.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Oliver Helmling - <email>oliver.helmling@stud.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Oliver Laumann - <email>net@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Oliver Oberdorf <email>oly@world.std.com</email></para> - </listitem> - - <listitem> - <para>Olof Johansson <email>offe@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Osokin Sergey aka oZZ <email>ozz@FreeBSD.org.ru</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paco Rosich <email>rosich@modico.eleinf.uv.es</email></para> - </listitem> - - <listitem> - <para>Palle Girgensohn <email>girgen@partitur.se</email></para> - </listitem> - - <listitem> - <para>Parag Patel <email>parag@cgt.com</email></para> - </listitem> - - <listitem> - <para>Pascal Pederiva <email>pascal@zuo.dec.com</email></para> - </listitem> - - <listitem> - <para>Pasvorn Boonmark <email>boonmark@juniper.net</email></para> - </listitem> - - <listitem> - <para>Patrick Bihan-Faou <email>patrick@mindstep.com</email></para> - </listitem> - - <listitem> - <para>Patrick Hausen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Patrick Seal <email>patseal@hyperhost.net</email></para> - </listitem> - - <listitem> - <para>Paul Antonov <email>apg@demos.su</email></para> - </listitem> - - <listitem> - <para>Paul F. Werkowski <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Fox <email>pgf@foxharp.boston.ma.us</email></para> - </listitem> - - <listitem> - <para>Paul Koch <email>koch@thehub.com.au</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Paul M. Lambert <email>plambert@plambert.net</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Paul S. LaFollette, Jr. <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Sandys <email>myj@nyct.net</email></para> - </listitem> - - <listitem> - <para>Paul T. Root <email>proot@horton.iaces.com</email></para> - </listitem> - - <listitem> - <para>Paul Vixie <email>paul@vix.com</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>paulo@isr.uc.pt</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>pm@dee.uc.pt</email></para> - </listitem> - - <listitem> - <para>Pedro A M Vazquez <email>vazquez@IQM.Unicamp.BR</email></para> - </listitem> - - <listitem> - <para>Pedro Giffuni <email>giffunip@asme.org</email></para> - </listitem> - - <listitem> - <para>Per Wigren <email>wigren@home.se</email></para> - </listitem> - - <listitem> - <para>Pete Bentley <email>pete@demon.net</email></para> - </listitem> - - <listitem> - <para>Peter Childs <email>pjchilds@imforei.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Peter Cornelius <email>pc@inr.fzk.de</email></para> - </listitem> - - <listitem> - <para>Peter Haight <email>peterh@prognet.com</email></para> - </listitem> - - <listitem> - <para>Peter Jeremy <email>perer.jeremy@alcatel.com.au</email></para> - </listitem> - - <listitem> - <para>Peter M. Chen <email>pmchen@eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Peter Much <email>peter@citylink.dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Peter Olsson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Peter Pentchev <email>roam@orbitel.bg</email></para> - </listitem> - - <listitem> - <para>Peter Philipp <email>pjp@bsd-daemon.net</email></para> - </listitem> - - <listitem> - <para>Peter Stubbs <email>PETERS@staidan.qld.edu.au</email></para> - </listitem> - - <listitem> - <para>Peter van Heusden <email>pvh@egenetics.com</email></para> - </listitem> - - <listitem> - <para>Phil Maker <email>pjm@cs.ntu.edu.au</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Phil Taylor <email>phil@zipmail.co.uk</email></para> - </listitem> - - <listitem> - <para>Philip Musumeci <email>philip@rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Philippe Lefebvre <email>nemesis@balistik.net</email></para> - </listitem> - - <listitem> - <para>Pierre Y. Dampure <email>pierre.dampure@k2c.co.uk</email></para> - </listitem> - - <listitem> - <para>Pius Fischer <email>pius@ienet.com</email></para> - </listitem> - - <listitem> - <para>Pomegranate <email>daver@flag.blackened.net</email></para> - </listitem> - - <listitem> - <para>Powerdog Industries - <email>kevin.ruddy@powerdog.com</email></para> - </listitem> - - <listitem> - <para>Priit Järv <email>priit@cc.ttu.ee</email></para> - </listitem> - - <listitem> - <para>R Joseph Wright <email>rjoseph@mammalia.org</email></para> - </listitem> - - <listitem> - <para>R. Kym Horsell</para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Randal S. Masutani <email>randal@comtest.com</email></para> - </listitem> - - <listitem> - <para>Randall Hopper <email>rhh@ct.picker.com</email></para> - </listitem> - - <listitem> - <para>Randall W. Dean <email>rwd@osf.org</email></para> - </listitem> - - <listitem> - <para>Randy Bush <email>rbush@bainbridge.verio.net</email></para> - </listitem> - - <listitem> - <para>Rasmus Kaj <email>kaj@Raditex.se</email></para> - </listitem> - - <listitem> - <para>Reinier Bezuidenhout - <email>rbezuide@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Remy Card <email>Remy.Card@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Ricardas Cepas <email>rch@richard.eu.org</email></para> - </listitem> - - <listitem> - <para>Riccardo Veraldi <email>veraldi@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Rich Wood <email>rich@FreeBSD.org.uk</email></para> - </listitem> - - <listitem> - <para>Richard Henderson <email>richard@atheist.tamu.edu</email></para> - </listitem> - - <listitem> - <para>Richard Hwang <email>rhwang@bigpanda.com</email></para> - </listitem> - - <listitem> - <para>Richard Kiss <email>richard@homemail.com</email></para> - </listitem> - - <listitem> - <para>Richard J Kuhns <email>rjk@watson.grauel.com</email></para> - </listitem> - - <listitem> - <para>Richard M. Neswold - <email>rneswold@enteract.com</email></para> - </listitem> - - <listitem> - <para>Richard Seaman, Jr. <email>dick@tar.com</email></para> - </listitem> - - <listitem> - <para>Richard Stallman <email>rms@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Richard Straka <email>straka@user1.inficad.com</email></para> - </listitem> - - <listitem> - <para>Richard Tobin <email>richard@cogsci.ed.ac.uk</email></para> - </listitem> - - <listitem> - <para>Richard Wackerbarth <email>rkw@Dataplex.NET</email></para> - </listitem> - - <listitem> - <para>Richard Winkel <email>rich@math.missouri.edu</email></para> - </listitem> - - <listitem> - <para>Richard Wiwatowski <email>rjwiwat@adelaide.on.net</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>rick@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Rick Macklin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Rob Austein <email>sra@epilogue.com</email></para> - </listitem> - - <listitem> - <para>Rob Mallory <email>rmallory@qualcomm.com</email></para> - </listitem> - - <listitem> - <para>Rob Snow <email>rsnow@txdirect.net</email></para> - </listitem> - - <listitem> - <para>Robert Crowe <email>bob@speakez.com</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Robert Eckardt - <email>roberte@MEP.Ruhr-Uni-Bochum.de</email></para> - </listitem> - - <listitem> - <para>Robert Sanders <email>rsanders@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Robert Sexton <email>robert@kudra.com</email></para> - </listitem> - - <listitem> - <para>Robert Shady <email>rls@id.net</email></para> - </listitem> - - <listitem> - <para>Robert Swindells <email>swindellsr@genrad.co.uk</email></para> - </listitem> - - <listitem> - <para>Robert Withrow <email>witr@rwwa.com</email></para> - </listitem> - - <listitem> - <para>Robert Yoder <email>unknown</email></para> - </listitem> - - <listitem> - <para>Robin Carey - <email>robin@mailgate.dtc.rankxerox.co.uk</email></para> - </listitem> - - <listitem> - <para>Rod Taylor <email>rod@idiotswitch.org</email></para> - </listitem> - - <listitem> - <para>Roger Hardiman <email>roger@cs.strath.ac.uk</email></para> - </listitem> - - <listitem> - <para>Roland Jesse <email>jesse@cs.uni-magdeburg.de</email></para> - </listitem> - - <listitem> - <para>Roman Shterenzon <email>roman@xpert.com</email></para> - </listitem> - - <listitem> - <para>Ron Bickers <email>rbickers@intercenter.net</email></para> - </listitem> - - <listitem> - <para>Ron Lenk <email>rlenk@widget.xmission.com</email></para> - </listitem> - - <listitem> - <para>Ronald Kuehn <email>kuehn@rz.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Rudolf Cejka <email>cejkar@dcse.fee.vutbr.cz</email></para> - </listitem> - - <listitem> - <para>Ruslan Belkin <email>rus@home2.UA.net</email></para> - </listitem> - - <listitem> - <para>Ruslan Shevchenko <email>rssh@cam.grad.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Russell L. Carter <email>rcarter@pinyon.org</email></para> - </listitem> - - <listitem> - <para>Russell Vincent <email>rv@groa.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Ryan Younce <email>ryany@pobox.com</email></para> - </listitem> - - <listitem> - <para>Ryuichiro IMURA <email>imura@af.airnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>Sakai Hiroaki <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakari Jalovaara <email>sja@tekla.fi</email></para> - </listitem> - - <listitem> - <para>Sam Hartman <email>hartmans@mit.edu</email></para> - </listitem> - - <listitem> - <para>Samuel Lam <email>skl@ScalableNetwork.com</email></para> - </listitem> - - <listitem> - <para>Samuel Tardieu <email>sam@inf.enst.fr</email></para> - </listitem> - - <listitem> - <para>Samuele Zannoli <email>zannoli@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Sander Janssen <email>janssen@rendo.dekooi.nl</email></para> - </listitem> - - <listitem> - <para>Sander Vesik <email>sander@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Sandro Sigala <email>ssigala@globalnet.it</email></para> - </listitem> - - <listitem> - <para>SANETO Takanori <email>sanewo@strg.sony.co.jp</email></para> - </listitem> - - <listitem> - <para>SASAKI Shunsuke <email>ele@pop17.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>Sascha Blank <email>blank@fox.uni-trier.de</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Satoh Junichi <email>junichi@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>SAWADA Mizuki <email>miz@qb3.so-net.ne.jp</email></para> - </listitem> - - <listitem> - <para>Scot Elliott <email>scot@poptart.org</email></para> - </listitem> - - <listitem> - <para>Scot W. Hetzel <email>hetzels@westbend.net</email></para> - </listitem> - - <listitem> - <para>Scott A. Kenney <email>saken@rmta.ml.org</email></para> - </listitem> - - <listitem> - <para>Scott A. Moberly <email>smoberly@xavier.dyndns.org</email></para> - </listitem> - - <listitem> - <para>Scott Blachowicz - <email>scott.blachowicz@seaslug.org</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Hazen Mueller <email>scott@zorch.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Scott Michel <email>scottm@cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Mitchel <email>scott@uk.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sebastian Strollo <email>seb@erix.ericsson.se</email></para> - </listitem> - - <listitem> - <para>Serge V. Vakulenko <email>vak@zebub.msk.su</email></para> - </listitem> - - <listitem> - <para>Sergei Chechetkin <email>csl@whale.sunbay.crimea.ua</email></para> - </listitem> - - <listitem> - <para>Sergei S. Laskavy <email>laskavy@pc759.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Sergey Gershtein <email>sg@mplik.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Kosyakov <email>ks@itp.ac.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Potapov <email>sp@alkor.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Samoyloff <email>gonza@techline.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Shkonda <email>serg@bcs.zp.ua</email></para> - </listitem> - - <listitem> - <para>Sergey V.Dorokhov <email>svd@kbtelecom.nalnet.ru</email></para> - </listitem> - - <listitem> - <para>Sergio Lenzi <email>lenzi@bsi.com.br</email></para> - </listitem> - - <listitem> - <para>Shaun Courtney <email>shaun@emma.eng.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Shawn M. Carey <email>smcarey@mailbox.syr.edu</email></para> - </listitem> - - <listitem> - <para>Shigio Yamaguchi <email>shigio@tamacom.com</email></para> - </listitem> - - <listitem> - <para>Shinya Esu <email>esu@yk.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Shinya FUJIE <email>fujie@tk.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>Shuichi Tanaka <email>stanaka@bb.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Simon <email>simon@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Simon Burge <email>simonb@telstra.com.au</email></para> - </listitem> - - <listitem> - <para>Simon Dick <email>simond@irrelevant.org</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email></para> - </listitem> - - <listitem> - <para>Simon Marlow <email>simonm@dcs.gla.ac.uk</email></para> - </listitem> - - <listitem> - <para>Simon Shapiro <email>shimon@simon-shapiro.org</email></para> - </listitem> - - <listitem> - <para>Sin'ichiro MIYATANI <email>siu@phaseone.co.jp</email></para> - </listitem> - - <listitem> - <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Soochon Radee <email>slr@mitre.org</email></para> - </listitem> - - <listitem> - <para>Soren Dayton <email>csdayton@midway.uchicago.edu</email></para> - </listitem> - - <listitem> - <para>Soren Dossing <email>sauber@netcom.com</email></para> - </listitem> - - <listitem> - <para>Soren S. Jorvang <email>soren@dt.dk</email></para> - </listitem> - - <listitem> - <para>Stefan Bethke <email>stb@hanse.de</email></para> - </listitem> - - <listitem> - <para>Stefan Eggers <email>seggers@semyam.dinoco.de</email></para> - </listitem> - - <listitem> - <para>Stefan Moeding <email>s.moeding@ndh.net</email></para> - </listitem> - - <listitem> - <para>Stefan Petri <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stefan `Sec` Zehl <email>sec@42.org</email></para> - </listitem> - - <listitem> - <para>Steinar Haug <email>sthaug@nethelp.no</email></para> - </listitem> - - <listitem> - <para>Stephane E. Potvin <email>sepotvin@videotron.ca</email></para> - </listitem> - - <listitem> - <para>Stephane Legrand <email>stephane@lituus.fr</email></para> - </listitem> - - <listitem> - <para>Stephen Clawson - <email>sclawson@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Stephen F. Combs <email>combssf@salem.ge.com</email></para> - </listitem> - - <listitem> - <para>Stephen Farrell <email>stephen@farrell.org</email></para> - </listitem> - - <listitem> - <para>Stephen Hocking <email>sysseh@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen J. Roznowski <email>sjr@home.net</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen Melvin <email>melvin@zytek.com</email></para> - </listitem> - - <listitem> - <para>Steve Bauer <email>sbauer@rock.sdsmt.edu</email></para> - </listitem> - - <listitem> - <para>Steve Coltrin <email>spcoltri@unm.edu</email></para> - </listitem> - - <listitem> - <para>Steve Deering <email>unknown</email></para> - </listitem> - - <listitem> - <para>Steve Gerakines <email>steve2@genesis.tiac.net</email></para> - </listitem> - - <listitem> - <para>Steve Gericke <email>steveg@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Steve Piette <email>steve@simon.chi.il.US</email></para> - </listitem> - - <listitem> - <para>Steve Schwarz <email>schwarz@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Steven G. Kargl - <email>kargl@troutmask.apl.washington.edu</email></para> - </listitem> - - <listitem> - <para>Steven H. Samorodin <email>samorodi@NUXI.com</email></para> - </listitem> - - <listitem> - <para>Steven McCanne <email>mccanne@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Steven Plite <email>splite@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Steven Wallace <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stijn Hoop <email>stijn@win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Stuart Henderson - <email>stuart@internationalschool.co.uk</email></para> - </listitem> - - <listitem> - <para>Sue Blake <email>sue@welearn.com.au</email></para> - </listitem> - - <listitem> - <para>Sugimoto Sadahiro <email>ixtl@komaba.utmc.or.jp</email></para> - </listitem> - - <listitem> - <para>SUGIMURA Takashi <email>sugimura@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Sugiura Shiro <email>ssugiura@duo.co.jp</email></para> - </listitem> - - <listitem> - <para>Sujal Patel <email>smpatel@wam.umd.edu</email></para> - </listitem> - - <listitem> - <para>Sungman Cho <email>smcho@tsp.korea.ac.kr</email></para> - </listitem> - - <listitem> - <para>Sune Stjerneby <email>stjerneby@usa.net</email></para> - </listitem> - - <listitem> - <para>SURANYI Peter - <email>suranyip@jks.is.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>Suzuki Yoshiaki - <email>zensyo@ann.tama.kawasaki.jp</email></para> - </listitem> - - <listitem> - <para>Tadashi Kumano <email>kumano@strl.nhk.or.jp</email></para> - </listitem> - - <listitem> - <para>Taguchi Takeshi <email>taguchi@tohoku.iij.ad.jp</email></para> - </listitem> - - <listitem> - <para>TAKAHASHI Kaoru <email>kaoru@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Takahiro Yugawa <email>yugawa@orleans.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Takashi Mega <email>mega@minz.org</email></para> - </listitem> - - <listitem> - <para>Takashi Uozu <email>j1594016@ed.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Ariga <email>a00821@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeru NAIKI <email>naiki@bfd.es.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Amaike <email>amaike@iri.co.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi MUTOH <email>mutoh@info.nara-k.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Ohashi - <email>ohashi@mickey.ai.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi WATANABE - <email>watanabe@crayon.earth.s.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takuya SHIOZAKI - <email>tshiozak@makino.ise.chuo-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatoku Ogaito <email>tacha@tera.fukui-med.ac.jp</email></para> - </listitem> - - <listitem> - <para>Ted Buswell <email>tbuswell@mediaone.net</email></para> - </listitem> - - <listitem> - <para>Ted Faber <email>faber@isi.edu</email></para> - </listitem> - - <listitem> - <para>Ted Lemon <email>mellon@isc.org</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@lambert.org</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tetsuya Furukawa <email>tetsuya@secom-sis.co.jp</email></para> - </listitem> - - <listitem> - <para>Theo de Raadt <email>deraadt@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Thomas <email>thomas@mathematik.uni-Bremen.de</email></para> - </listitem> - - <listitem> - <para>Thomas D. Dean <email>tomdean@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas David Rivers <email>rivers@dignus.com</email></para> - </listitem> - - <listitem> - <para>Thomas G. McWilliams <email>tgm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas Graichen - <email>graichen@omega.physik.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Thomas König - <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para> - </listitem> - - <listitem> - <para>Thomas Ptacek <email>unknown</email></para> - </listitem> - - <listitem> - <para>Thomas Quinot <email>thomas@cuivre.fr.eu.org</email></para> - </listitem> - - <listitem> - <para>Thomas A. Stephens <email>tas@stephens.org</email></para> - </listitem> - - <listitem> - <para>Thomas Stromberg <email>tstrombe@rtci.com</email></para> - </listitem> - - <listitem> - <para>Thomas Valentino Crimi - <email>tcrimi+@andrew.cmu.edu</email></para> - </listitem> - - <listitem> - <para>Thomas Wintergerst <email>thomas@lemur.nord.de</email></para> - </listitem> - - <listitem> - <para>Þórður Ívarsson - <email>totii@est.is</email></para> - </listitem> - - <listitem> - <para>Timothy Jensen <email>toast@blackened.com</email></para> - </listitem> - - <listitem> - <para>Tim Kientzle <email>kientzle@netcom.com</email></para> - </listitem> - - <listitem> - <para>Tim Singletary - <email>tsingle@sunland.gsfc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Tim Wilkinson <email>tim@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Timo J. Rinne <email>tri@iki.fi</email></para> - </listitem> - - <listitem> - <para>Tobias Reifenberger <email>treif@mayn.de</email></para> - </listitem> - - <listitem> - <para>Todd Miller <email>millert@openbsd.org</email></para> - </listitem> - - <listitem> - <para>Tom <email>root@majestix.cmr.no</email></para> - </listitem> - - <listitem> - <para>Tom <email>tom@sdf.com</email></para> - </listitem> - - <listitem> - <para>Tom Gray - DCA <email>dcasba@rain.org</email></para> - </listitem> - - <listitem> - <para>Tom Jobbins <email>tom@tom.tj</email></para> - </listitem> - - <listitem> - <para>Tom Pusateri <email>pusateri@juniper.net</email></para> - </listitem> - - <listitem> - <para>Tom Rush <email>tarush@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Tom Samplonius <email>tom@misery.sdf.com</email></para> - </listitem> - - <listitem> - <para>Tomohiko Kurahashi - <email>kura@melchior.q.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tony Kimball <email>alk@Think.COM</email></para> - </listitem> - - <listitem> - <para>Tony Li <email>tli@jnx.com</email></para> - </listitem> - - <listitem> - <para>Tony Lynn <email>wing@cc.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Tony Maher <email>Tony.Maher@eBioinformatics.com</email></para> - </listitem> - - <listitem> - <para>Torbjorn Granlund <email>tege@matematik.su.se</email></para> - </listitem> - - <listitem> - <para>Toshihiko SHIMOKAWA <email>toshi@tea.forus.or.jp</email></para> - </listitem> - - <listitem> - <para>Toshihiro Kanda <email>candy@kgc.co.jp</email></para> - </listitem> - - <listitem> - <para>Toshiomi Moriki - <email>Toshiomi.Moriki@ma1.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Trefor S. <email>trefor@flevel.co.uk</email></para> - </listitem> - - <listitem> - <para>Trevor Blackwell <email>tlb@viaweb.com</email></para> - </listitem> - - <listitem> - <para>Udo Schweigert <email>ust@cert.siemens.de</email></para> - </listitem> - - <listitem> - <para>Ugo Paternostro <email>paterno@dsi.unifi.it</email></para> - </listitem> - - <listitem> - <para>Ulf Kieber <email>kieber@sax.de</email></para> - </listitem> - - <listitem> - <para>Ulli Linzen <email>ulli@perceval.camelot.de</email></para> - </listitem> - - <listitem> - <para>URATA Shuichiro <email>s-urata@nmit.tmg.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ustimenko Semen <email>semen@iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Uwe Arndt <email>arndt@mailhost.uni-koblenz.de</email></para> - </listitem> - - <listitem> - <para>Vadim Chekan <email>vadim@gc.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Vadim Kolontsov <email>vadim@tversu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vadim Mikhailov <email>mvp@braz.ru</email></para> - </listitem> - - <listitem> - <para>Valentin Nechayev <email>netch@lucky.net</email></para> - </listitem> - - <listitem> - <para>Van Jacobson <email>van@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Vasily V. Grechishnikov - <email>bazilio@ns1.ied-vorstu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vasim Valejev <email>vasim@uddias.diaspro.com</email></para> - </listitem> - - <listitem> - <para>Vernon J. Schryver <email>vjs@mica.denver.sgi.com</email></para> - </listitem> - - <listitem> - <para>Vic Abell <email>abe@cc.purdue.edu</email></para> - </listitem> - - <listitem> - <para>Ville Eerola <email>ve@sci.fi</email></para> - </listitem> - - <listitem> - <para>Vince Valenti <email>vince@blue-box.net</email></para> - </listitem> - - <listitem> - <para>Vincent Poy <email>vince@venus.gaianet.net</email></para> - </listitem> - - <listitem> - <para>Vincenzo Capuano - <email>VCAPUANO@vmprofs.esoc.esa.de</email></para> - </listitem> - - <listitem> - <para>Virgil Champlin <email>champlin@pa.dec.com</email></para> - </listitem> - - <listitem> - <para>Vladimir A. Jakovenko - <email>vovik@ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Vladimir Kushnir <email>kushn@mail.kar.net</email></para> - </listitem> - - <listitem> - <para>Vsevolod Lobko <email>seva@alex-ua.com</email></para> - </listitem> - - <listitem> - <para>W. Gerald Hicks <email>wghicks@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>W. Richard Stevens <email>rstevens@noao.edu</email></para> - </listitem> - - <listitem> - <para>Walt Howard <email>howard@ee.utah.edu</email></para> - </listitem> - - <listitem> - <para>Walt M. Shandruk <email>walt@erudition.net</email</para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wayne Scott <email>wscott@ichips.intel.com</email></para> - </listitem> - - <listitem> - <para>Werner Griessl - <email>werner@btp1da.phy.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Wes Santee <email>wsantee@wsantee.oz.net</email></para> - </listitem> - - <listitem> - <para>Wietse Venema <email>wietse@wzv.win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>Willem Jan Withagen <email>wjw@surf.IAE.nl</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>William Liao <email>william@tale.net</email></para> - </listitem> - - <listitem> - <para>Wojtek Pilorz - <email>wpilorz@celebris.bdk.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Wolfgang Helbig <email>helbig@ba-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Wu Ching-hong <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Yarema <email>yds@ingress.com</email></para> - </listitem> - - <listitem> - <para>Yaroslav Terletsky <email>ts@polynet.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Yasuhiro Fukama <email>yasuf@big.or.jp</email></para> - </listitem> - - <listitem> - <para>Yasuhito FUTATSUKI <email>futatuki@fureai.or.jp</email></para> - </listitem> - - <listitem> - <para>Yen-Ming Lee <email>leeym@bsd.ce.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yin-Jieh Chen <email>yinjieh@Crazyman.Dorm13.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yixin Jin <email>yjin@rain.cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Yoichi Asai <email>yatt@msc.biglobe.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihiko SARUMRU <email>mistral@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihisa NAKAGAWA - <email>y-nakaga@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshikazu Goto <email>gotoh@ae.anritsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshimasa Ohnishi - <email>ohnishi@isc.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yoshishige Arai <email>ryo2@on.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yuichi MATSUTAKA <email>matutaka@osa.att.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yujiro MIYATA - <email>miyata@bioele.nuee.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yu-Shun Wang <email>yushunwa@isi.edu</email></para> - </listitem> - - <listitem> - <para>Yusuke Nawano <email>azuki@azkey.org</email></para> - </listitem> - - <listitem> - <para>Yuu Yashiki <email>s974123@cc.matsuyama-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuuki SAWADA <email>mami@whale.cc.muroran-it.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuuichi Narahara <email>aconitum@po.teleway.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@cpcoup5.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@dutncp8.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Zach Heilig <email>zach@gaffaneys.com</email></para> - </listitem> - - <listitem> - <para>Zach Zurflu <email>zach@pabst.bendnet.com</email></para> - </listitem> - - <listitem> - <para>Zahemszhky Gabor <email>zgabor@code.hu</email></para> - </listitem> - - <listitem> - <para>Zhong Ming-Xun <email>zmx@mail.CDPA.nsysu.edu.tw</email></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-386bsd"> - <title>386BSD Patch Kit Patch Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Andrey A. Chernov <email>ache@astral.msk.su</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew Moore <email>alm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email> - <email>jtk@netcom.com</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Branko Lankester</para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Rivers <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Greenman <email>dg@Root.COM</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Felix Gaehtgens - <email>felix@escape.vsse.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Guido van Rooij <email>guido@gvr.org</email></para> - </listitem> - - <listitem> - <para>Guy Antony Halse <email>guy@rucus.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@auspex.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@novatel.cuc.ab.ca</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro, R. Kym Horsell</para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James W. Dolter</para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jörg Lohse - <email>lohse@tech7.informatik.uni-hamburg.de</email></para> - </listitem> - - <listitem> - <para>Jörg Wunsch - <email>joerg_wunsch@uriah.heep.sax.de</email></para> - </listitem> - - <listitem> - <para>John Dyson</para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jordan K. Hubbard <email>jkh@whisker.hubbard.ie</email></para> - </listitem> - - <listitem> - <para>Julian Elischer <email>julian@dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Julian Stacey <email>jhs@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email> - <email>karl@one.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@toe.CS.Berkeley.EDU</email></para> - </listitem> - - <listitem> - <para>Ken Hughes</para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml%rokkaku.UUCP@mathcs.emory.edu</email> - <email>kml@mosquito.cis.ufl.edu</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email> - <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Nate Williams <email>nate@bsd.coe.montana.edu</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email> - <email>nick@madhouse.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Peter da Silva <email>peter@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Poul-Henning Kamp<email>phk@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>root@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Rodney W. Grimes <email>rgrimes@cdrom.com</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan <email>sef@kithrup.com</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email> - <email>sjg@zen.void.oz.au</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@icarus.weber.edu</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tor Egge <email>Tor.Egge@idi.ntnu.no</email></para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@dentaro.GUN.de</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/articles/dialup-firewall/Makefile b/en_US.ISO8859-1/articles/dialup-firewall/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/dialup-firewall/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml deleted file mode 100644 index 85d4a159b6..0000000000 --- a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml +++ /dev/null @@ -1,299 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/articles/dialup-firewall/article.sgml,v 1.3 2000/07/11 10:21:49 nbm Exp $ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <artheader> - <title>Dialup firewalling with FreeBSD</title> - - <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - - <affiliation> - <address><email>marcs@draenor.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$Date: 2000-08-19 20:51:20 $</pubdate> - - <abstract> - <para>This article documents how to setup a firewall using a PPP - dialup with FreeBSD and IPFW, and specifically with firewalling over - a dialup with a dynamically assigned IP address. This document does - not cover setting up your PPP connection in the first place.</para> - </abstract> - </artheader> - - <sect1 id="preface"> - <title>Preface</title> - - <para>Dialup Firewalling with FreeBSD</para> - - <para>This document aims to cover the process that is required in - order to setup firewalling with FreeBSD when are dynamically - assigned an IP address by your ISP. While every effort has been - made to make this document as informative and correct as possible, - you are welcome to mail your comments/suggestions to the - <ulink URL="mailto:marcs@draenor.org">maintainer</ulink>.</para> - </sect1> - - <sect1 id="kernel"> - <title>Kernel Options</title> - - <para>The first thing you'll need to do is recompile your kernel in - FreeBSD. If you need more information on how to recompile the kernel, - then the best place to start is the <ulink - URL="http://www.freebsd.org/handbook/kernelconfig.html">kernel - configuration section in the Handbook</ulink>. You need to compile the - following options into the kernel: </para> - - <variablelist> - <varlistentry> - <term><literal>options IPFIREWALL</literal></term> - - <listitem> - <para>Enables the kernel's firewall code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE</literal></term> - - <listitem> - <para>Sends logged packets to the system logger.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options - IPFIREWALL_VERBOSE_LIMIT=<replaceable>100</replaceable></literal></term> - - <listitem> - <para>Limits the number of times a matching entry is logged. This - stops your log files filling up with lots of repetitive entries. - <replaceable>100</replaceable> is a reasonable number to use, but - you can adjust it based on your requirements.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPDIVERT</literal></term> - - <listitem> - <para>Enables <emphasis>divert</emphasis> sockets, which will be - shown later.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>There are also some other OPTIONAL items that you can compile - into the kernel for some added security. These are not required in - order to get firewalling to work, but some more paranoid users may - want to use them.</para> - - <variablelist> - <varlistentry> - <term><literal>options TCP_RESTRICT_RST</literal></term> - - <listitem> - <para>This option blocks all TCP RST packets. This is - best used for systems that might be exposed to SYN - flooding (IRC Servers are a good example) or for those who - do not want to be easily portscannable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options TCP_DROP_SYNFIN</literal></term> - - <listitem> - <para>This option ignores TCP packets with SYN and FIN. This - prevents tools such as nmap etc from identifying the TCP/IP - stack of the machine, but breaks support for RFC1644 - extensions. This is NOT recommended if the machine will be - running web server.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Don't reboot once you have recompiled the kernel. Hopefully, we will - need to reboot just once in order to complete the installing of the - firewall.</para> - </sect1> - - <sect1 id="rcconf"> - <title>Changing <filename>/etc/rc.conf</filename> to load the - firewall</title> - - <para>We now need to make some changes to - <filename>/etc/rc.conf</filename> in order to tell it about the - firewall. Simply add the following lines:</para> - - <programlisting>firewall_enable="YES" -firewall_script="/etc/firewall/fwrules" -natd_enable="YES" -natd_interface="tun0" -natd_flags="-dynamic"</programlisting> - - <para>For more information on what the above do take a look at - <filename>/etc/defaults/rc.conf</filename> and read - &man.rc.conf.5;</para> - </sect1> - - <sect1> - <title>Disable PPP's network address translation</title> - - <para>You may already be using PPP's built in network address - translation (NAT). If that is the case you will have to disable it, - as these examples use &man.natd.8; to do the same.</para> - - <para>If you already have a block of entries to - automatically start PPP it probably looks like this:</para> - - <programlisting>ppp_enable="YES" -ppp_mode="auto" -ppp_nat="YES" -ppp_profile="<replaceable>profile</replaceable>"</programlisting> - - <para>If so, remove the <literal>ppp_nat="YES"</literal> line. You will - also need to remove any <literal>nat enable yes</literal> or - <literal>alias enable yes</literal> in - <filename>/etc/ppp/ppp.conf</filename>.</para> - </sect1> - - <sect1 id="rules"> - <title>The ruleset for the firewall</title> - - <para>We're nearly done now. All that remains now is to define the - firewall rules and then we can reboot and the firewall should be up and - running. I realise that everyone will want something slightly different - when it comes to their rulebase. What I've tried to do is write a - rulebase that suits most dialup users. You can obviously modify it to - your needs by simply using the following rules as the foundation for - your own rulebase. First, let's start with the basics of closed - firewalling. What you want to do is deny everything by default and then - only open up for the things you really need. Rules should be in the - order of allow first and then deny. The premis is that you add the - rules for your allows, and then everything else is denied. :)</para> - - <para>Now, let's make the dir /etc/firewall. Change into the directory and - edit the file fwrules as we specified in rc.conf. Please note that you - can change this filename to be anything you wish. This guide just gives - an example of a filename. </para> - - <para>Now, let's look at a sample firewall file, and we'll detail - everything in it. </para> - - <programlisting># Firewall rules -# Written by Marc Silver (marcs@draenor.org) -# http://draenor.org/ipfw -# Freely distributable - - -# Define the firewall command (as in /etc/rc.firewall) for easy -# reference. Helps to make it easier to read. -fwcmd="/sbin/ipfw" - -# Force a flushing of the current rules before we reload. -$fwcmd -f flush - -# Divert all packets through the tunnel interface. -$fwcmd add divert natd all from any to any via tun0 - -# Allow all data from my network card and localhost. Make sure you -# change your network card (mine was fxp0) before you reboot. :) -$fwcmd add allow ip from any to any via lo0 -$fwcmd add allow ip from any to any via fxp0 - -# Allow all connections that I initiate. -$fwcmd add allow tcp from any to any out xmit tun0 setup - -# Once connections are made, allow them to stay open. -$fwcmd add allow tcp from any to any via tun0 established - -# Everyone on the internet is allowed to connect to the following -# services on the machine. This example shows that people may connect -# to ssh and apache. -$fwcmd add allow tcp from any to any 80 setup -$fwcmd add allow tcp from any to any 22 setup - -# This sends a RESET to all ident packets. -$fwcmd add reset log tcp from any to any 113 in recv tun0 - -# Allow outgoing DNS queries ONLY to the specified servers. -$fwcmd add allow udp from any to <replaceable>x.x.x.x</replaceable> 53 out xmit tun0 - -# Allow them back in with the answers... :) -$fwcmd add allow udp from <replaceable>x.x.x.x</replaceable> 53 to any in recv tun0 - -# Allow ICMP (for ping and traceroute to work). You may wish to -# disallow this, but I feel it suits my needs to keep them in. -$fwcmd add 65435 allow icmp from any to any - -# Deny all the rest. -$fwcmd add 65435 deny log ip from any to any</programlisting> - - <para>You now have a fully functional firewall that will allow on - connections to ports 80 and 22 and will log any other connection - attempts. Now, you should be able to safely reboot and your firewall - should come up fine. If you find this incorrect in anyway or experience - any problems, or have any suggestions to improve this page, please - email me.</para> - </sect1> - - <sect1> - <title>Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>Why are you using natd and ipfw when you could be using - the built in ppp-filters?</para> - </question> - - <answer> - <para>I'll have to be honest and say there's no definitive reason - why I use ipfw and natd instead of the built in ppp filters. From - the discussions I've had with people the consensus seems to be - that while ipfw is certainly more powerful and more configurable - than the ppp filters, what it makes up for in functionality it - loses in being easy to customise. One of the reasons I use it is - because I prefer firewalling to be done at a kernel level rather - than by a userland program.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>If I'm using private addresses internally, such as in the - 192.168.0.0 range, Could I add a command like <literal>$fwcmd add - deny all from any to 192.168.0.0:255.255.0.0 via tun0</literal> - to the firewall rules to prevent outside attempts to connect to - internal machines?</para> - </question> - - <answer> - <para>The simple answer is no. The reason for this is that natd is - doing address translation for <emphasis>anything</emphasis> being - diverted through the tun0 device. As far as it's concerned - incoming packets will speak only to the dynamically assigned IP - address and NOT to the internal network. Note though that you can - add a rule like <literal>$fwcmd add deny all from - 192.168.0.4:255.255.0.0 to any via tun0</literal> which would - limit a host on your internal network from going out via the - firewall.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/diskless-x/Makefile b/en_US.ISO8859-1/articles/diskless-x/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/diskless-x/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/diskless-x/article.sgml b/en_US.ISO8859-1/articles/diskless-x/article.sgml deleted file mode 100644 index 1ca1a15061..0000000000 --- a/en_US.ISO8859-1/articles/diskless-x/article.sgml +++ /dev/null @@ -1,349 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/articles/diskless-x/article.sgml,v 1.2 1999/09/06 06:52:36 peter Exp $ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <artheader> - <title>Diskless X Server: a how to guide</title> - - <authorgroup> - <author> - <firstname> Jerry</firstname> - <surname>Kendall</surname> - <affiliation> - <address> - <email>jerry@kcis.com</email> - </address> - </affiliation> - </author></authorgroup> - - <pubdate>28-December-1996</pubdate> - - <copyright> - <year>1996</year> - <holder>Jerry Kendall</holder> - </copyright> - - <abstract> - <para>With the help of some friends on the FreeBSD-hackers list, I have - been able to create a diskless X terminal. The creation of the X - terminal required first creating a diskless system with minimal - utilities mounted via NFS. These same steps were used to create 2 - separate diskless systems. The first is <hostid - role="fqdn">altair.kcis.com</hostid>. A diskless X terminal that I - run on my old 386DX-40. It has a 340Meg hard disk but, I did not want - to change it. So, it boots from <hostid - role="fqdn">antares.kcis.com</hostid> across a Ethernet. The second - system is a 486DX2-66. I setup a diskless FreeBSD (complete) that - uses no local disk. The server in that case is a Sun 670MP running - SunOS 4.1.3. The same setup configuration was needed for both.</para> - - <para>I am sure that there is stuff that needs to be added - to this. Please send me any comments.</para> - </abstract> - </artheader> - - <sect1> - <title>Creating the boot floppy (On the diskless system)</title> - - <para>Since the network boot loaders will not work with some of the TSR's - and such that MS-DOS uses, it is best to create a dedicated boot floppy - or, if you can, create an MS-DOS menu that will (via the - <filename>config.sys</filename>/<filename>autoexec.bat</filename> files) - ask what configuration to load when the system starts. The later is the - method that I use and it works great. My MS-DOS (6.x) menu is - below.</para> - - <example> - <title><filename>config.sys</filename></title> - - <programlisting>[menu] -menuitem=normal, normal -menuitem=unix, unix -[normal] -.... -normal config.sys stuff -... -[unix]</programlisting> - </example> - - <example> - <title><filename>autoexec.bat</filename></title> - - <programlisting>@ECHO OFF -goto %config% - -:normal -... -normal autoexec.bat stuff -... -goto end - -:unix -cd \netboot -nb8390.com - -:end</programlisting> - </example> - </sect1> - - <sect1> - <title>Getting the network boot programs (On the server)</title> - - <para>Compile the 'net-boot' programs that are located in - <filename>/usr/src/sys/i386/boot/netboot</filename>. You should read - the comments at the top of the <filename>Makefile</filename>. Adjust as - required. Make a backup of the original in case it gets foobar'd. When - the build is done, there should be 2 MS-DOS executables, - <filename>nb8390.com</filename> and <filename>nb3c509.com</filename>. - One of these two programs will be what you need to run on the diskless - server. It will load the kernel from the boot server. At this point, - put both programs on the MS-DOS boot floppy created earlier.</para> - </sect1> - - <sect1> - <title>Determine which program to run (On the diskless system)</title> - - <para>If you know the chipset that your Ethernet adapter uses, this is - easy. If you have the NS8390 chipset, or a NS8390 based chipset, use - <filename>nb8390.com</filename>. If you have a 3Com 509 based chipset, - use the <filename>nb3C509.com</filename> boot program. If you are not - sure which you have, try using one, if it says <errorname>No adapter - found</errorname>, try the other. Beyond that, you are pretty much on - your own.</para> - </sect1> - - <sect1> - <title>Booting across the network</title> - - <para>Boot the diskless system with out any config.sys/autoexec.bat - files. try running the boot program for your Ethernet adapter.</para> - - <para>My Ethernet adapter is running in WD8013 16bit mode so I run - <filename>nb8390.com</filename></para> - - <screen><prompt>C:></prompt> <userinput>cd \netboot</userinput> -<prompt>C:></prompt> <userinput>nb8390</userinput> - -<prompt>Boot from Network (Y/N) ?</prompt> <userinput>Y</userinput> - -BOOTP/TFTP/NFS bootstrap loader ESC for menu - -Searching for adapter.. -WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 - -Searching for server...</screen> - - <para>At this point, my diskless system is trying to find a machine to act - as a boot server. Make note of the <literal>addr</literal> line above, - you will need this number later. Reset the diskless system and modify - your <filename>config.sys</filename> and - <filename>autoexec.bat</filename> files to do these steps automatically - for you. Perhaps in a menu. If you had to run - <command>nb3c509.com</command> instead of <command>nb8390.com</command> - the output is the same as above. If you got <errorname>No adapter - found</errorname> at the <literal>Searching for adapter...</literal> - message, verify that you did indeed set the compile time defines in the - <filename>Makefile</filename> correctly.</para> - </sect1> - - <sect1> - <title>Allowing systems to boot across the network (On the server)</title> - - <para>Make sure the <filename>/etc/inetd.conf</filename> file has entries - for tftp and bootps. Mine are listed below:</para> - - <programlisting>tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot -# -# Additions by who ever you are -bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab</programlisting> - - <para>If you have to change the <filename>/etc/inetd.conf</filename> file, - send a <literal>HUP</literal> signal to inetd. To do this, get the - process ID of inetd with <command>ps -ax | grep inetd | grep -v - grep</command>. Once you have it, send it a HUP signal. Do this by - <command>kill -HUP <pid></command>. This will force inetd to - re-read its config file.</para> - - <para>Did you remember to note the <literal>addr</literal> line from the - output of the boot loader on the diskless system? Guess what, here is - where you need it.</para> - - <para>Add an entry to <literal>/etc/bootptab</literal> (maybe creating the - file). It should be laid out identical to this:</para> - - <programlisting>altair:\ - :ht=ether:\ - :ha=004001432666:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=199.246.76.1:\ - :ip=199.246.76.2:\ - :gw=199.246.76.1:\ - :vm=rfc1048:</programlisting> - - <para>The lines are as follows:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>altair</literal></entry> - <entry>the diskless systems name without the domain name.</entry> - </row> - - <row> - <entry><literal>ht=ether</literal></entry> - <entry>the hardware type of 'ethernet'.</entry> - </row> - - <row> - <entry><literal>ha=004001432666</literal></entry> - <entry>the hardware address (the number noted above).</entry> - </row> - - <row> - <entry><literal>sm=255.255.255.0</literal></entry> - <entry>the subnet mask.</entry> - </row> - - <row> - <entry><literal>hn</literal></entry> - <entry>tells server to send client's hostname to the - client.</entry> - </row> - - <row> - <entry><literal>ds=199.246.76.1</literal></entry> - <entry>tells the client who the domain server is.</entry> - </row> - - <row> - <entry><literal>ip=199.246.76.2</literal></entry> - <entry>tells the client what it's IP address is.</entry> - </row> - - <row> - <entry><literal>gw=199.246.76.1</literal></entry> - <entry>tells the client what the default gateway is.</entry> - </row> - - <row> - <entry><literal>vm=...</literal></entry> - <entry>just leave it there.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>Be sure to setup the IP addresses correctly, the addresses above - are my own.</para> - </note> - - <para>Create the directory '/tftpboot' on the server it will contain the - configuration files for the diskless systems that the server will serve. - These files will be named 'cfg.<ip>' where <ip> is the IP - address of the diskless system. The config file for 'altair' is - /tftpboot/cfg.199.246.76.2. The contents is:</para> - - <programlisting>rootfs 199.246.76.1:/DiskLess/rootfs/altair -hostname altair.kcis.com</programlisting> - - <para>The line <literal>hostname altair.kcis.com</literal> simply tells - the diskless system what its fully qualified domain name is.</para> - - <para>The line <literal>rootfs - 199.246.76.1:/DiskLess/rootfs/altair</literal> tells the diskless - system where its NFS mountable root filesystem is located.</para> - - <note> - <para>The NFS mounted root filesystem will be mounted <emphasis>read - only</emphasis>.</para> - </note> - - <para>The hierarchy for the diskless system can be re-mounted allowing - read-write operations if required.</para> - - <para>I use my spare 386DX-40 as a dedicated X terminal.</para> - - <para>The hierarchy for 'altair' is:</para> - - <literallayout>/ -/bin -/etc -/tmp -/sbin -/dev -/dev/fd -/usr -/var -/var/run</literallayout> - - <para>The actual list of files is:</para> - - <screen>-r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel --r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh --rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc --rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys --rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts --rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair --r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init --r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig --r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs --r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot --r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount --r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local --r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV</screen> - - <para>Don't forget to run <command>MAKEDEV all</command> in the - <filename>dev</filename> directory.</para> - - <para>My <filename>/etc/rc</filename> for <hostid>altair</hostid> - is:</para> - -<programlisting>#!/bin/sh -# -PATH=/bin:/ -export PATH -# -# configure the localhost -/sbin/ifconfig lo0 127.0.0.1 -# -# configure the ethernet card -/sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 -# -# mount the root filesystem via NFS -/sbin/mount antares:/DiskLess/rootfs/altair / -# -# mount the /usr filesystem via NFS -/sbin/mount antares:/DiskLess/usr /usr -# -/usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 -# -# Reboot after X exits -/sbin/reboot -# -# We blew up.... -exit 1</programlisting> - - <para>Any comments and all questions welcome.</para> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/fonts/Makefile b/en_US.ISO8859-1/articles/fonts/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml deleted file mode 100644 index b1629c70c7..0000000000 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,980 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/fonts/article.sgml,v 1.8 2000/06/20 11:30:11 alex Exp $ --> -<!-- The FreeBSD Documentation Project --> -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<!-- Recently, I wanted to figure out how to use some additional fonts that - I had accumulated. I finally figured out *how to do it* from the various - man pages and documentation. Since it might be of use to other users, - and I didn't see any reference to this topic in the FAQ or handbook, I - thought I'd try my hand at a simple cookbook tutorial addressing the - use of fonts. I have included my unanswered questions at the end of - the document. - - Anyway, here's what I put together. This is my present understanding of - fonts and how to use them with FreeBSD. I am sure that there are errors or - misunderstandings, but it contains enough valid information to allow the - use of additional fonts with Ghostscript, X11 and Groff. This is my first - attempt to write anything along the lines of a tutorial/FAQ, so I am sure - it is pretty raw. There are probably better ways to do some of this stuff, - and I would welcome being corrected. - --> - -<!-- The section "Setting a virtual console to 80x60 line mode" was - updated to reflect changes in FreeBSD system configuration - files by Mark Ovens <mark@ukug.uk.freebsd.org> 27/5/00 - --> - -<article> - <artheader> - <title>Fonts and FreeBSD</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Dave</firstname> - - <surname>Bodenstab</surname> - - <affiliation> - <address> - <email>imdave@synet.net</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>Wed Aug 7, 1996</pubdate> - - <abstract> - <para>This document contains a description of the various font - files that may be used with FreeBSD and the syscons driver, - X11, Ghostscript and Groff. Cookbook examples are provided - for switching the syscons display to 80x60 mode, and for using - type 1 fonts with the above application programs.</para> - </abstract> - </artheader> - - <sect1> - <title>Introduction</title> - - <para>There are many sources of fonts available, and one might ask - how they might be used with FreeBSD. The answer can be found by - carefully searching the documentation for the component that one - would like to use. This is very time consuming, so this - tutorial is an attempt to provide a shortcut for others who - might be interested.</para> - </sect1> - - <sect1> - <title>Basic terminology</title> - - <para>There are many different font formats and associated font - file suffixes. A few that will be addressed here are:</para> - - <variablelist> - <varlistentry> - <term><filename>.pfa</filename>, <filename>.pfb</filename></term> - - <listitem> - <para>Postscript type 1 fonts. The - <filename>.pfa</filename> is the - <emphasis>A</emphasis>scii form and - <filename>.pfb</filename> the <emphasis>B</emphasis>inary - form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.afm</filename></term> - - <listitem> - <para>The font metrics associated with a type 1 font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.pfm</filename></term> - - <listitem> - <para>The printer font metrics associated with a type 1 - font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.ttf</filename></term> - - <listitem> - <para>A TrueType font</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fot</filename></term> - - <listitem> - <para>An indirect reference to a TrueType font (not an - actual font)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fon</filename>, <filename>.fnt</filename></term> - - <listitem> - <para>Bitmapped screen fonts</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fot</filename> file is used by Windows as - sort of a symbolic link to the actual TrueType font - (<filename>.ttf</filename>) file. The <filename>.fon</filename> - font files are also used by Windows. I know of no way to use - this font format with FreeBSD.</para> - </sect1> - - <sect1> - <title>What font formats can I use?</title> - - <para>Which font file format is useful depends on the application - being used. FreeBSD by itself uses no fonts. Application - programs and/or drivers may make use of the font files. Here is - a small cross reference of application/driver to the font type - suffixes:</para> - - <variablelist> - <varlistentry> - <term>Driver</term> - - <listitem> - <variablelist> - <varlistentry> - <term>syscons</term> - - <listitem> - <para><filename>.fnt</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Application</term> - - <listitem> - <variablelist> - <varlistentry> - <term>Ghostscript</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename>, - <filename>.ttf</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>X11</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Groff</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.afm</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Povray</term> - - <listitem> - <para><filename>.ttf</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fnt</filename> suffix is used quite - frequently. I suspect that whenever someone wanted to create a - specialized font file for their application, more often than not - they chose this suffix. Therefore, it is likely that files with - this suffix are not all the same format; specifically, the - <filename>.fnt</filename> files used by syscons under FreeBSD - may not be the same format as a <filename>.fnt</filename> file - one encounters in the MSDOS/Windows environment. I have not - made any attempt at using other <filename>.fnt</filename> files - other than those provided with FreeBSD.</para> - </sect1> - - <sect1> - <title>Setting a virtual console to 80x60 line mode</title> - - <para>First, an 8x8 font must be loaded. To do this, - <filename>/etc/rc.conf</filename> should contain the - line (change the font name to an appropriate one for - your locale):</para> - - <informalexample> - <programlisting>font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO). - </programlisting> - </informalexample> - - <para>The command to actually switch the mode is - &man.vidcontrol.1:</para> - - <informalexample> - <screen>bash$ <userinput>vidcontrol VGA_80x60</userinput> - </screen> - </informalexample> - - <para>Various screen orientated programs, such as &man.vi.1, must - be able to determine the current screen dimensions. As this is - achieved this through <command>ioctl</command> calls to the console - driver (such as &man.syscons.4) they will correctly determine the new - screen dimensions.</para> - - <para>To make this more seamless, one can embed these commands in - the startup scripts so it takes place when the system boots. - To do this is add this line to <filename>/etc/rc.conf</filename> - </para> - - <informalexample> - <programlisting>allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens - </programlisting> - </informalexample> - - <para>References: &man.rc.conf.5;, &man.vidcontrol.1;.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with X11</title> - - <para>X11 can use either the <filename>.pfa</filename> or the - <filename>.pfb</filename> format fonts. The X11 fonts are - located in various subdirectories under - <filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file - is cross referenced to its X11 name by the contents of the - <filename>fonts.dir</filename> file in each directory.</para> - - <para>There is already a directory named <filename>Type1</filename>. The - most straight forward way to add a new font is to put it into - this directory. A better way is to keep all new fonts in a - separate directory and use a symbolic link to the additional - font. This allows one to more easily keep track of ones fonts - without confusing them with the fonts that were originally - provided. For example:</para> - - <informalexample> - <screen><lineannotation>Create a directory to contain the font files</> -bash$ <userinput>mkdir -p /usr/local/share/fonts/type1</> -bash$ <userinput>cd /usr/local/share/fonts/type1</> - -<lineannotation>Place the .pfa, .pfb and .afm files here</> -<lineannotation>One might want to keep readme files, and other documentation</> -<lineannotation>for the fonts here also</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</> -bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</> - -<lineannotation>Maintain an index to cross reference the fonts</> -bash$ <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX</> - </screen> - </informalexample> - - <para>Now, to use a new font with X11, one must make the font file - available and update the font name files. The X11 font names - look like:</para> - - <informalexample> - <screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style - </screen> - </informalexample> - - <para>A new name needs to be created for each new font. If you - have some information from the documentation that accompanied - the font, then it could serve as the basis for creating the - name. If there is no information, then you can get some idea by - using &man.strings.1; on the font file. For example:</para> - - <informalexample> - <screen>bash$ <userinput>strings showboat.pfb | more</> -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin-- - </screen> - </informalexample> - - <para>Using this information, a possible name might be:</para> - - <informalexample> - <screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - </screen> - </informalexample> - - <para>The components of our name are:</para> - - <variablelist> - <varlistentry> - <term>Foundry</term> - - <listitem> - <para>Lets just name all the new fonts - <literal>type1</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Family</term> - - <listitem> - <para>The name of the font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Weight</term> - - <listitem> - <para>Normal, bold, medium, semibold, etc. From the - <citerefentry><refentrytitle>strings</refentrytitle><manvolnum>1</manvolnum></citerefentry> - output above, it appears that this font has a weight of - <emphasis>medium</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slant</term> - - <listitem> - <para><emphasis remap=bf>r</emphasis>oman, <emphasis - remap=bf>i</emphasis>talic, <emphasis - remap=bf>o</emphasis>blique, etc. Since the - <emphasis>ItalicAngle</emphasis> is zero, - <emphasis>roman</emphasis> will be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Width</term> - - <listitem> - <para>Normal, wide, condensed, extended, etc. Until it can - be examined, the assumption will be - <emphasis>normal</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Additional style</term> - - <listitem> - <para>Usually omitted, but this will indicate that the font - contains decorative capital letters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Spacing</term> - - <listitem> - <para>proportional or monospaced. - <emphasis>Proportional</emphasis> is used since - <emphasis>isFixedPitch</emphasis> is false.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>All of these names are arbitrary, but one should strive to - be compatible with the existing conventions. A font is - referenced by name with possible wild cards by an X11 program, - so the name chosen should make some sense. One might begin by - simply using - - <informalexample> - <screen>…-normal-r-normal-…-p-… - </screen> - </informalexample> - - as the name, and then use - <citerefentry><refentrytitle>xfontsel</refentrytitle><manvolnum>1</manvolnum></citerefentry> to - examine it and adjust the name based on the appearance of the - font.</para> - - <para>So, to complete our example:</para> - - <informalexample> - <screen><lineannotation>Make the font accessible to X11</> -bash$ <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line.</> -bash$ <userinput>ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq</> - -<lineannotation><filename>fonts.scale</> seems to be identical to <filename>fonts.dir</>…</> -bash$ <userinput>cp fonts.dir fonts.scale</> - -<lineannotation>Tell X11 that things have changed</> -bash$ <userinput>xset fp rehash</> - -<lineannotation>Examine the new font</> -bash$ <userinput>xfontsel -pattern -type1-*</> - </screen> - </informalexample> - - <para>References: &man.xfontsel.1;, &man.xset.1;, <citetitle>The X - Windows System in a Nutshell</citetitle>, <ulink - URL="http://www.ora.com/">O'Reilly & - Associates</ulink>.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Ghostscript</title> - - <para>Ghostscript references a font via its <filename>Fontmap</filename> - file. This must be modified in a similar way to the X11 - <filename>fonts.dir</filename> file. Ghostscript can use either - the <filename>.pfa</filename> or the <filename>.pfb</filename> - format fonts. Using the font from the previous example, here is - how to use it with Ghostscript:</para> - - <informalexample> - <screen><lineannotation>Put the font in Ghostscript's font directory</> -bash$ <userinput>cd /usr/local/share/ghostscript/fonts</> -bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</> - -<lineannotation>Edit Fontmap so Ghostscript knows about the font</> -bash$ <userinput>cd /usr/local/share/ghostscript/4.01</> -bash$ <userinput>ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq</> - -<lineannotation>Use Ghostscript to examine the font</> -bash$ <userinput>gs prfont.ps</> -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS><userinput>Showboat DoFont</> -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS><userinput>quit</> - </screen> - </informalexample> - - <para>References: <filename>fonts.txt</filename> in the - Ghostscript 4.01 distribution</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Groff</title> - - <para>Now that the new font can be used by both X11 and - Ghostscript, how can one use the new font with groff? First of - all, since we are dealing with type 1 postscript fonts, the - groff device that is applicable is the <emphasis>ps</emphasis> - device. A font file must be created for each font that groff - can use. A groff font name is just a file in - <filename>/usr/share/groff_font/devps</filename>. With our - example, the font file could be - <filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The - file must be created using tools provided by groff.</para> - - <para>The first tool is <command>afmtodit</command>. This is not - normally installed, so it must be retrieved from the source - distribution. I found I had to change the first line of the - file, so I did:</para> - - <informalexample> - <screen>bash$ <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</> -bash$ <userinput>ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq</> - </screen> - </informalexample> - - <para>This tool will create the groff font file from the metrics - file (<filename>.afm</filename> suffix.) Continuing with our - example:</para> - - <informalexample> - <screen><lineannotation>Many <filename>.afm</> files are in Mac format&hellip ^M delimited lines -We need to convert them to unix style ^J delimited lines</> -bash$ <userinput>cd /tmp</> -bash$ <userinput>cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm</> - -<lineannotation>Now create the groff font file</> -bash$ <userinput>cd /usr/share/groff_font/devps</> -bash$ <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</> - </screen> - </informalexample> - - <para>The font can now be referenced with the name - SHOWBOAT.</para> - - <para>If ghostscript is used to drive the printers on the system, - then nothing more needs to be done. However, if true postscript - printers are used, then the font must be down loaded to the - printer in order for the font to be used (unless the printer - happens to have the showboat font built in or on an accessible - font disk.) The final step is to create a down loadable font. - The <command>pfbtops</command> tool is used to create the - <filename>.pfa</filename> format of the font, and the - <filename>download</filename> file is modified to reference the new - font. The <filename>download</filename> file must reference the - internal name of the font. This can easily be determined from - the groff font file as illustrated:</para> - - <informalexample> - <screen><lineannotation>Create the <filename>.pfa</> font file</> -bash$ <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</> - </screen> - </informalexample> - - <para>Of course, if the <filename>.pfa</filename> file is already - available, just use a symbolic link to reference it.</para> - - <informalexample> - <screen><lineannotation>Get the internal font name</> -bash$ <userinput>fgrep internalname SHOWBOAT</> -internalname Showboat - -<lineannotation>Tell groff that the font must be down loaded</> -bash$ <userinput>ex download -:$a -Showboat showboat.pfa -. -:wq</> - </screen> - </informalexample> - - <para>To test the font:</para> - - <informalexample> - <screen>bash$ <userinput>cd /tmp</> -bash$ <userinput>cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF</> -bash$ <userinput>groff -Tps example.t >example.ps</> - -<lineannotation>To use ghostscript/ghostview</> -bash$ <userinput>ghostview example.ps</> - -<lineannotation>To print it</> -bash$ <userinput>lpr -Ppostscript example.ps</> - </screen> - </informalexample> - - <para>References: - <filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>, - &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;.</para> - </sect1> - - <sect1> - <title>Converting TrueType fonts to a groff/postscript format for - groff</title> - - <para>This potentially requires a bit of work, simply because it - depends on some utilities that are not installed as part of the - base system. They are:</para> - - <variablelist> - <varlistentry> - <term><command>ttf2pf</command></term> - - <listitem> - <para>TrueType to postscript convertsion utilities. This - allows conversion of a TrueType font to an ascii font - metric (<filename>.afm</filename>) file.</para> - - <para>Currently available at <ulink - url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf</ulink>. - Note: These files are postscript programs and must be - downloaded to disk by holding down the - <keycap>Shift</keycap> key when clicking on the link. - Otherwise, your browser may try to launch - <application>ghostview</application> to view them.</para> - - <para>The files of interest are:</para> - - <itemizedlist> - <listitem> - <para><filename>GS_TTF.PS</filename></para> - </listitem> - - <listitem> - <para><filename>PF2AFM.PS</filename></para> - </listitem> - - <listitem> - <para><filename>ttf2pf.ps</filename></para> - </listitem> - </itemizedlist> - - <para>The funny upper/lower case is due to their being - intended also for DOS shells. - <filename>ttf2pf.ps</filename> makes use of the others as - upper case, so any renaming must be consistent with this. - (Actually, <filename>GS_TTF.PS</filename> and - <filename>PFS2AFM.PS</filename> are supposedly part of the - ghostscript distribution, but it's just as easy to use - these as an isolated utility. FreeBSD doesn't seem to - include the latter.) You also may want to have these - installed to - <filename>/usr/local/share/groff_font/devps</filename>(?).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>afmtodit</command></term> - - <listitem> - <para>Creates font files for use with groff from ascii font - metrics file. This usually resides in the directory, - <filename>/usr/src/contrib/groff/afmtodit</filename>, and - requires some work to get going.</para> - - <note> - <para> If you're paranoid about working in the - <filename>/usr/src</filename> tree, simply copy the - contents of the above directory to a work - location.</para> - </note> - - <para>In the work area, you'll need to make the utility. - Just type:</para> - - <screen><prompt>#</prompt> <userinput>make -f Makefile.sub afmtodit</userinput> - </screen> - - <para>You may also need to copy - <filename>/usr/contrib/groff/devps/generate/textmap</filename> - to - <filename>/usr/share/groff_font/devps/generate</filename> - if it doesn't already exist.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once all these utilities are in place, you're ready to - commence:</para> - - <orderedlist> - <listitem> - <para>Create the <filename>.afm</filename> file by - typing:</para> - - <screen><prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput> - </screen> - - <para>Where, <replaceable>TTF_name</replaceable> is your - TrueType font file, <replaceable>PS_font_name</replaceable> - is the file name for the <filename>.pfa</filename> file, - <replaceable>AFM_name</replaceable> is the name you wish for - the <filename>.afm</filename> file. If you do not specify - output file names for the <filename>.pfa</filename> or - <filename>.afm</filename> files, then default names will be - generated from the TrueType font file name.</para> - - <para>This also produces a <filename>.pfa</filename> file, the - ascii postscript font metrics file - (<filename>.pfb</filename> is for the binrary form). This - won't be needed, but could (I think) be useful for a - fontserver.</para> - - <para>For example, to convert the 30f9 Barcode font using the - default file names, use the following command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to 3of9.pfa and 3of9.afm. - </screen> - - <para>If you want the converted fonts to be stored in - <filename>A.pfa</filename> and <filename>B.afm</filename>, - then use this command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to A.pfa and B.afm. - </screen> - </listitem> - - <listitem> - <para>Create the groff postscript file:</para> - - <para>Change directories to - <filename>/usr/share/groff_font/devps</filename> so as to - make the following command easier to execute. You'll - probably need root priviledges for this. (Or, if you're - paranoid about working there, make sure you reference the - files <filename>DESC</filename>, - <filename>text.enc</filename> and - <filename>generate/textmap</filename> as being in this - directory.)</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \ - generate/textmap <replaceable>PS_font_name</replaceable></userinput> - </screen> - - <para>Where, <filename>file.afm</filename> is the - <replaceable>AFM_name</replaceable> created by - <command>ttf2pf.ps</command> above, and - <replaceable>PS_font_name</replaceable> is the font name - used from that command, as well as the name that - &man.groff.1; will use for references to this font. For - example, assuming you used the first - <command>tiff2pf.ps</command> command above, then the 3of9 - Barcode font can be created using the command:</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc 3of9.afm \ - generate/textmap 3of9</userinput> - </screen> - - <para>Ensure that the resulting - <replaceable>PS_font_name</replaceable> file (e.g., - <filename>3of9</filename> in the example above) is located - in the directory - <filename>/usr/share/groff_font/devps</filename> by copying - or moving it there.</para> - - <para>Note that if <filename>ttf2pf.ps</filename> assigns a - font name using the one it finds in the TrueType font file - and you want to use a different name, you must edit the - <filename>.afm</filename> file prior to running - <command>afmtodit</command>. This name must also match the - one used in the Fontmap file if you wish to pipe - &man.groff.1; into &man.gs.1;.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Can TrueType fonts be used with other programs?</title> - - <para>The TrueType font format is used by Windows, Windows 95, and - Mac's. It is quite popular and there are a great number of - fonts available in this format.</para> - - <para>Unfortunately, there are few applications that I am aware of - that can use this format: Ghostscript and Povray come to mind. - Ghostscript's support, according to the documentation, is - rudimentary and the results are likely to be inferior to type 1 - fonts. Povray version 3 also has the ability to use TrueType - fonts, but I rather doubt many people will be creating documents - as a series of raytraced pages :-).</para> - - <para>This rather dismal situation may soon change. The <ulink - url="http://www.freetype.org/">FreeType Project</ulink> is - currently developing a useful set of FreeType tools:</para> - - <itemizedlist> - <listitem> - <para>The <command>xfsft</command> font server for X11 can - serve TrueType fonts in addition to regular fonts. Though - currently in beta, it is said to be quite useable. See - <ulink - url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz - Chroboczek's page</ulink> for further information. - Porting instructions for FreeBSD can be found at <ulink - url="http://math.missouri.edu/~stephen/software/">Stephen - Montgomery's software page</ulink>.</para> - </listitem> - - <listitem> - <para><command>xfstt</command> is another font server for X11, - available under <ulink url=" - ftp://sunsite.unc.edu/pub/Linux/X11/fonts"> - ftp://sunsite.unc.edu/pub/Linux/X11/fonts</ulink>.</para> - </listitem> - - <listitem> - <para>A program called <command>ttf2bdf</command> can produce - BDF files suitable for use in an X environment from TrueType - files. Linux binaries are said to be available from <ulink - url="ftp://crl.nmsu.edu/CLR/multiling/General">ftp://crl.nmsu.edu/CLR/multiling/General/</ulink>.</para> - </listitem> - - <listitem> - <para>For people requiring the use of Asian TrueType fonts, - the <command>XTT</command> font server may be worth a look. - Information about <command>XTT</command> can be found at - URL: <ulink - url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html">http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html</ulink>.</para> - </listitem> - - <listitem> - <para>and others …</para> - </listitem> - </itemizedlist> - - <para>The <ulink - url="http://www.freetype.org/projects.htm">FreeType Projects - page </ulink> is a good starting point for information on - these and other free TrueType projects.</para> - </sect1> - - <sect1> - <title>Where can additional fonts be obtained?</title> - - <para>Many fonts are available on the Internet. They are either - entirely free, or are share-ware. In addition, there are many - inexpensive CDROMs available that contain many fonts. Some - Internet locations (as of August 1996) are:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> - (Formerly CICA)</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.simtel.net/simcgi-bin/dosfind.cgi">http://www.simtel.net/simcgi-bin/dosfind.cgi</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Additional questions</title> - - <itemizedlist> - <listitem> - <para>What use are the <filename>.pfm</filename> files?</para> - </listitem> - - <listitem> - <para>Can one generate the <filename>.afm</filename> file from - a <filename>.pfa</filename> or - <filename>.pfb</filename>?</para> - </listitem> - - <listitem> - <para>How to generate the groff character mapping files for - postscript fonts with non-standard character names?</para> - </listitem> - - <listitem> - <para>Can xditview and devX?? devices be setup to access all - the new fonts?</para> - </listitem> - - <listitem> - <para>It would be good to have examples of using TrueType - fonts with povray and ghostscript.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/formatting-media/Makefile b/en_US.ISO8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index 6708d35396..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,603 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/formatting-media/article.sgml,v 1.13 1999/10/30 18:10:14 dwhite Exp $ --> -<article> - <artheader> - <title>Formatting Media For Use With FreeBSD 2.2-RELEASE</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Doug</firstname> - - <surname>White</surname> - - <affiliation> - <address> - <email>dwhite@resnet.uoregon.edu</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>March 1997</pubdate> - - <abstract> - <para>This document describes how to slice, partition, and - format hard disk drives and similar media for use with - FreeBSD. The examples given have been tested under FreeBSD - 2.2-GAMMA and may work for other releases.</para> - </abstract> - </artheader> - - <sect1> - <title>Introduction & Definitions</title> - - <sect2> - <title>Overview</title> - - <para>Successfully adding disks to an existing system is the - mark of an experienced system administrator. Slicing, - partitioning, and adding disks requires a careful dance of - proper command and name syntax. One slipped finger and an - entire disk could disappear in seconds. This document is - written in an attempt to simplify this process and avoid - accidents. Thankfully, enhancements to existing tools - (notably sysinstall) have greatly improved this process in - recent releases of FreeBSD.</para> - - <para>There are two possible modes of disk formatting:</para> - - <itemizedlist> - <listitem> - <para><firstterm>compatibility mode</firstterm>: Arranging a - disk so that it has a slice table for use with other - operating systems.</para> - </listitem> - - <listitem> - <para><firstterm>dangerously dedicated mode</firstterm>: - Formatting a disk with no slice table. This makes the - process of adding disks easier, however non-FreeBSD - operating systems may not accept the disk.</para> - </listitem> - </itemizedlist> - - <para>For most cases, dedicated mode is the easiest to set up - and use in existing systems, as a new disk is usually - dedicated entirely to FreeBSD. However, compatibility mode - insures optimum interoperability with future installations at - a cost of increased complexity.</para> - - <para>In addition to selecting the mode, two methods of slicing - the disk are available. One is using the system installation - tool <command>/stand/sysinstall</command>. 2.1.7-RELEASE and - later versions of <command>sysinstall</command> contain code - to ease setup of disks during normal system operation, mainly - allowing access to the Label and Partition editors and a Write - feature which will update just the selected disk and slice - without affecting other disks. The other method is running - the tools manually from a root command line. For dangerously - dedicated mode, only three or four commands are involved while - <command>sysinstall</command> requires some - manipulation.</para> - </sect2> - - <sect2> - <title>Definitions</title> - - <para>UNIX disk management over the centuries has invented many - new definitions for old words. The following glossary covers - the definitions used in this document and (hopefully) for - FreeBSD in general.</para> - -<!-- I'm tempted to use GLOSSARY here but will resort to a list for -now. --> - - <itemizedlist> - <listitem> - <para>compatibility mode: Arranging a disk so that it has a - slice table for use with other operating systems. Oppose - dangerously dedicated mode.</para> - </listitem> - - <listitem> - <para>dangerously dedicated mode: Formatting a disk with no - slice table. This makes the process of adding disks - easier, however non-FreeBSD operating systems may not - accept the disk. Oppose compatibility mode.</para> - </listitem> - - <listitem> - <para>disk: A circular disc, covered with magnetic or - similarly manipulable material, spun by a motor under a - head. Data is stored on the disk by changing the pattern - of magnetism on the disc, which can be later read. Hard - disks, CD-ROMs, Magneto-optical,and Zip/Jaz removables are - examples of disks.</para> - </listitem> - - <listitem> - <para>slice: A division of a disk. Up to four slices are - permitted on one disk in the PC standard. Slices are - composed of contiguous sectors. Slices are recorded in a - <quote>slice table</quote> used by the system BIOS to - locate bootable partitions. The slice table is usually - called the Partition Table in DOS parlance. Maintained by - the fdisk utility.</para> - </listitem> - - <listitem> - <para>partition: A division of a slice. Usually used in - reference to divisions of the FreeBSD slice of a disk. - Each filesystem and swap area on a disk resides in a - partition. Maintained using the disklabel utility.</para> - </listitem> - - <listitem> - <para>sector: Smallest subdivision of a disk. One sector - usually represents 512 bytes of data.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Warnings & Pitfalls</title> - - <para>Building disks is not something to take lightly. It is - quite possible to destroy the contents of other disks in your - system if the proper precautions are not taken.</para> - - <para><emphasis>Check your work carefully.</emphasis> It is very simple - to destroy the incorrect disk when working with these - commands. When in doubt consult the kernel boot output for - the proper device.</para> - - <para>Needless to say, we are not responsible for any damage to - any data or hardware that you may experience. You work at - your own risk!</para> - </sect2> - - <sect2> - <title>Zip, Jaz, and Other Removables</title> - - <para>Removable disks can be formatted in the same way as normal - hard disks. It is essential to have the disk drive connected - to the system and a disk placed in the drive during startup, - so the kernel can determine the drive's geometry. Check the - <command>dmesg</command> output and make sure your device and - the disk's size is listed. If the kernel reports - - <informalexample> - <screen>Can't get the size - </screen> - </informalexample> - - then the disk was not in the drive. In this case, you will - need to restart the machine before attempting to format - disks.</para> - </sect2> - </sect1> - - <sect1> - <title>Formatting Disks in Dedicated Mode</title> - - <sect2> - <title>Introduction</title> - - <para>This section details how to make disks that are totally - dedicated to FreeBSD. Remember, dedicated mode disks cannot - be booted by the PC architecture.</para> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks using Sysinstall</title> - - <para><command>/stand/sysinstall</command>, the system - installation utility, has been expanded in recent versions to - make the process of dividing disks properly a less tiring - affair. The fdisk and disklabel editors built into sysinstall - are GUI tools that remove much of the confusion from slicing - disks. For FreeBSD versions 2.1.7 and later, this is perhaps - the simplest way to slice disks.</para> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</userinput> - </screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - </screen> - </informalexample> - - answer <command>No</command>.</para> - </step> - - <step> - <para>When asked if you still want to do this, answer - <command>Yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When warned about Writing on installed systems, answer - <command>Yes</command>.</para> - </step> - - <step> - <para><command>Quit</command>the FDISK Editor and - <keycap>ESCAPE</keycap> back to the Index menu.</para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, enter - <command>C</command> to Create a partition, accept the - default size, partition type Filesystem, and a mountpoint - (which isn't used).</para> - </step> - - <step> - <para>Enter <command>W</command> when done and confirm to - continue. The filesystem will be newfs'd for you, unless - you select otherwise (for news partitions you'll want to - do this!). You'll get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - </screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks Using the Command Line</title> - - <para>Execute the following commands, replacing wd2 with the - disk name.</para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rwd2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/rwd2 | disklabel -B -R -r wd2 /dev/stdin</userinput> -<lineannotation>We only want one partition, so using slice 'c' should be fine:</lineannotation> -&prompt.root; <userinput>newfs /dev/rwd2c</userinput> - </screen> - </informalexample> - - <para>If you need to edit the disklabel to create multiple - partitions (such as swap), use the following: </para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rwd2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/r$d > /tmp/label</userinput> -<lineannotation>Edit disklabel to add partitions:</lineannotation> -&prompt.root; <userinput>vi /tmp/label</userinput> -&prompt.root; <userinput>disklabel -B -R -r wd2 /tmp/label</userinput> -<lineannotation>newfs partitions appropriately</lineannotation> - </screen> - </informalexample> - - <para>Your disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Making Compatibility Mode Disks</title> - - <sect2> - <title>Introduction</title> - - <para>The command line is the easiest way to make dedicated - disks, and the worst way to make compatibility disks. The - command-line fdisk utility requires higher math skills and an - in-depth understanding of the slice table, which is more than - most people want to deal with. Use sysinstall for - compatibility disks, as described below.</para> - </sect2> - - <sect2> - <title>Making Compatibility Mode Disks Using Sysinstall</title> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</> - </screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - </screen> - </informalexample> - - answer <command>yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When asked to install the boot manager, select None - with <keycap>SPACE</keycap> then hit - <keycap>ENTER</keycap> for OK.</para> - </step> - - <step> - <para><command>Quit</command> the FDISK Editor.</para> - </step> - - <step> - <para>You'll be asked about the boot manager, select - <command>None</command> again. </para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, accept the - default size, type filesystem, and a mountpoint (which - isn't used).</para> - </step> - - <step> - <para>The filesystem will be newfs'd for you, unless you - select otherwise (for news partitions you'll want to do - this!). You'll get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/wd2s1e on /mnt/blah : No such file or directory - </screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - - <para>Your new disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Other Disk Operations</title> - - <sect2> - <title>Adding Swap Space</title> - - <para>As a system grows, it's need for swap space can also grow. - Although adding swap space to existing disks is very - difficult, a new disk can be partitioned with additional swap - space.</para> - - <para>To add swap space when adding a disk to a system:</para> - - <procedure> - <step> - <para>When partitioning the disk, edit the disklabel and - allocate the amount of swap space to add in partition `b' - and the remainder in another partition, such as `a' or - `e'. The size is given in 512 byte blocks.</para> - </step> - - <step> - <para>When newfsing the drive, do NOT newfs the `c' - partition. Instead, newfs the partition where the - non-swap space lies.</para> - </step> - - <step> - <para>Add an entry to <filename>/etc/fstab</filename> as - follows:</para> - - <informalexample> - <programlisting>/dev/wd0b none swap sw 0 0 - </programlisting> - </informalexample> - - <para>Change /dev/wd0b to the device of the newly added - space.</para> - </step> - - <step> - <para>To make the new space immediately available, use the - <command>swapon</command> command. - - <informalexample> - <screen>&prompt.root; <userinput>swapon /dev/sd0b</userinput> -swapon: added /dev/sd0b as swap space - </screen> - </informalexample> - </para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Copying the Contents of Disks</title> -<!-- Should have specific tag --> - - <para>Submitted By: Renaud Waldura - (<email>renaud@softway.com</email>) </para> - - <para>To move file from your original base disk to the fresh new - one, do: - - <informalexample> - <screen>&prompt.root; <userinput>mount /dev/wd2 /mnt</userinput> -&prompt.root; <userinput>pax -r -w -p e /usr/home /mnt</userinput> -&prompt.root; <userinput>umount /mnt</userinput> -&prompt.root; <userinput>rm -rf /usr/home/*</userinput> -&prompt.root; <userinput>mount /dev/wd2 /usr/home</userinput> - </screen> - </informalexample> - </para> - </sect2> - - <sect2> - <title>Creating Striped Disks using CCD</title> - - <para>Commands Submitted By: Stan Brown - (<email>stanb@awod.com</email>) </para> - - <para>The Concatenated Disk Driver, or CCD, allows you to treat - several identical disks as a single disk. Striping can result - in increased disk performance by distributing reads and writes - across the disks. See the &man.ccd.4; and &man.ccdconfig.8; - man pages or the <ulink - URL="http://stampede.cs.berkeley.edu/ccd/">CCD - Homepage</ulink> for further details.</para> - - <para>To create a new CCD, execute the following commands. This - describes how to add three disks together; simply add or - remove devices as necessary. Remember that the disks to be - striped must be <emphasis>identical.</emphasis></para> - - <para>Before executing these commands, make sure you add the line - - <userinput>pseudo-device ccd 4</userinput> - - to your kernel.</para> - - <informalexample> - <screen>&prompt.root; <userinput>cd /dev ; sh MAKDEV ccd0</userinput> - -&prompt.root; <userinput>disklabel -r -w sd0 auto</userinput> -&prompt.root; <userinput>disklabel -r -w sd1 auto</userinput> -&prompt.root; <userinput>disklabel -r -w sd2 auto</userinput> - -&prompt.root; <userinput>disklabel -e sd0c</userinput> -<lineannotation>change type to 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e sd1c</userinput> -<lineannotation>change type to 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e sd2c</userinput> -<lineannotation>change type to 4.2BSD</lineannotation> - -&prompt.root; <userinput>ccdconfig ccd0 32 0 /dev/sd0c /dev/sd1c /dev/sd2c</userinput> - -&prompt.root; <userinput>newfs /dev/rccd0c</userinput> - </screen> - </informalexample> - - <para>Now you can mount and use your CCD by referencing device - /dev/ccd0c.</para> - </sect2> - </sect1> - - <sect1> - <title>Credits</title> - - <para>The author would like to thank the following individuals for - their contributions to this project:</para> - - <itemizedlist> - <listitem> - <para>Darryl Okahata - (<email>darrylo@hpnmhjw.sr.hp.com</email>) for his simple - dedicated mode setup documentation which I have used - repeatedly on freebsd-questions.</para> - </listitem> - - <listitem> - <para>Jordan Hubbard (<email>jkh@FreeBSD.org</email>) for - making sysinstall useful for this type of task.</para> - </listitem> - - <listitem> - <para>John Fieber (<email>jfieber@indiana.edu</email>) for - making information and examples of the DocBook DTD on which - this document is based.</para> - </listitem> - - <listitem> - <para>Greg Lehey (<email>grog@FreeBSD.org</email>) for - checking my work and pointing out inaccuracies, as well as - miscellaneous support.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/ipsec-must/Makefile b/en_US.ISO8859-1/articles/ipsec-must/Makefile deleted file mode 100644 index 0647dfada3..0000000000 --- a/en_US.ISO8859-1/articles/ipsec-must/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -DOCFORMAT= html - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/ipsec-must/article.sgml b/en_US.ISO8859-1/articles/ipsec-must/article.sgml deleted file mode 100644 index 716ce5df5b..0000000000 --- a/en_US.ISO8859-1/articles/ipsec-must/article.sgml +++ /dev/null @@ -1,297 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>Independent Verification of IPSec Functionality in FreeBSD</title> - </head> - - <body text="#000000" bgcolor="#FFFFFF"> - - <h1>Independent Verification of IPsec Functionality Under FreeBSD 3.0</h1> - - <p align="center"><i>You installed IPsec and it seems to be working. - How do you know? I describe a method for experimentally verifying - that IPsec is working</i></p> - - <h2>The Problem</h2> - - <p>First, let's assume you have <a href="#Installing IPsec">installed - <i>IPsec</i></a>. How do you know its <a href="#Caveat">working</a>? - Sure, your connection won't work if its misconfigured, and it will work - when you finally get it right. <i>Netstat</i> will list it. But can you - independently confirm it?</p> - - <h2>The Solution</h2> - - <p>First, some crypto-relevent info theory:</p> - - <ol> - <li> - <p>Encrypted data is uniformly distributed, ie, has maximal entropy - per symbol.</p> - </li> - - <li> - <p>Raw, uncompressed data is typically redundant, i.e., has - sub-maximal entropy.</p> - </li> - </ol> - - <p>Suppose you could measure the entropy of the data to- and from- your - network interface. Then you could see the difference between unencrypted - data and encrypted data. This would be true even if some of the data - in "encrypted mode" was not encrypted ---as the outermost IP header must - be, if the packet is to be routable.</p> - - <h4><a name="MUST"></a>MUST</h4> - - <p>Ueli Maurer's "Universal Statistical Test for Random Bit Generators" - ("MUST") quickly measures the entropy of a sample. It uses a - compression-like algorithm. <a href="#Maurer's Universal Statistical - Test">The code is given below for a variant which measures successive - (~quarter megabyte) chunks of a file</a>.</p> - - <h4><a NAME="Tcpdump"></a>Tcpdump</h4> - - <p>We also need a way to capture the raw network data. A program called - "<i>tcpdump</i>" lets you do this, if you have enabled the <i>Berkeley - Packet Filter</i> interface in your <a - href="#usr/src/sys/i386/conf/KERNELNAME">kernel's config file</a>.</p> - - <p>The command</p> - - <blockquote><b>tcpdump</b> <b>-c</b> 4000 <b>-s</b> 10000 <b>-w</b> - <i>dumpfile.bin</i></blockquote> - - <p>will capture 4000 raw packets to <i>dumpfile.bin</i>. Up to 10,000 - bytes per packet will be captured in this example.</p> - - <h2>The Experiment</h2> - - <p>Here's the experiment. Open a window to an IPsec host and another - window to an insecure host.</p> - - <p>Now start <a href="#Tcpdump">capturing packets</a>.</p> - - <p>In the "secure" window, run the unix command "yes", which will stream - the "y" character. After a while, stop this. Switch to the insecure - window, and repeat. After a while, stop.</p> - - <p>Now run <a href="#Maurer's Universal Statistical Test">MUST</a> on the - captured packets. You should see something like the the following. - The important thing to note is that the secure connection has 93% (6.7) - of the expected value (7.18), and the "normal" connection has 29% (2.1) - of the expected value.</p> - - - <pre>% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin -% uliscan ipsecdemo.bin - -Uliscan 21 Dec 98 -L=8 256 258560 -Measuring file ipsecdemo.bin -Init done -Expected value for L=8 is 7.1836656 -6.9396 -------------------------------------------------------- -6.6177 ----------------------------------------------------- -6.4100 --------------------------------------------------- -2.1101 ----------------- -2.0838 ----------------- -2.0983 -----------------</pre> - - <h2><a NAME="Caveat"></a>Caveat</h2> - - <p>This experiment shows that IPsec <i>does</i> seem to be distributing the - payload data <i>uniformly</i>, as encryption should. However, the - experiment described here <i>can not </i>detect many possible flaws in a - system (none of which do I have any evidence for). These include poor - key generation or exchange, data or keys being visible to others, use of - weak algorithms, kernel subversion, etc. Study the source; know the - code.</p> - - <h2><a NAME="IPsec"></a>IPsec -Definition</h2> - - <p>Internet Protocol security extensions to IP v 4; required for IP v6. A - protocol for negotiating encryption and authentication at the IP - (host-to-host) level. SSL secures only one application socket; SSH - secures only a login; PGP secures only a specified file or - message. IPsec encrypts everything between two hosts.</p> - - <h2><a NAME="Installing IPsec"></a>Installing IPsec</h2> - - <p>Starting from the BSD 3.0 stable release,</p> - - <ol> - <li> - <p>install IPsec v0.04, rebuild, reinstall</p> - </li> - - <li> - <p>run the administration tools (e.g, <i>ipsecadm</i>) and distribute - keys (or use <i>Photuris</i> for key exchange)</p> - </li> - - <li> - <p>set the routes (<i>rt</i>) up appropriately</p> - </li> - </ol> - - <p>You may want to make an "ipsec_setup" script containing the - <i>ipsecadm</i> and <i>rt</i> commands which establish your IPsec - tunnel. You can run this script automatically at boottime from your - <i>/etc/rc.local</i> The ipsec_setup script will have to contain at - least two <i>ipsecadm</i> commands and one <i>rt</i> command to be - useful.</p> - - <h2><a NAME="KERNELNAME"></a>usr/src/sys/i386/conf/KERNELNAME</h2> - - <p>This needs to be present in the kernel config file in order to run - IPsec. After adding it, run <i>config</i>, etc. and rebuild and - reinstall.</p> - - <pre># The `bpfilter' pseudo-device enables the Berkeley Packet Filter. Be -# aware of the legal and administrative consequences of enabling this -# option. Heh heh. The number of devices determines the maximum number of -# simultaneous BPF clients programs runnable. -pseudo-device bpfilter 2 #Berkeley packet filter - -# IPSEC -options IPSEC -options "MD5" -pseudo-device enc 1</pre> - - <h2><a name="must"></a>Maurer's Universal Statistical Test (for block - size=8 bits)</h2> - - <pre><![ CDATA [/* - ULISCAN.c ---blocksize of 8 - - 1 Oct 98 - 1 Dec 98 - 21 Dec 98 uliscan.c derived from ueli8.c - - This version has // comments removed for Sun cc - - This implements Ueli M Maurer's "Universal Statistical Test for Random - Bit Generators" using L=8 - - Accepts a filename on the command line; writes its results, with other - info, to stdout. - - Handles input file exhaustion gracefully. - - Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 - also on the web somewhere, which is where I found it. - - -David Honig - honig@sprynet.com - - Usage: - ULISCAN filename - outputs to stdout -*/ - -#define L 8 -#define V (1<<L) -#define Q (10*V) -#define K (100 *Q) -#define MAXSAMP (Q + K) - -#include <stdio.h> -#include <math.h> - -int main(argc, argv) -int argc; -char **argv; -{ - FILE *fptr; - int i,j; - int b, c; - int table[V]; - double sum = 0.0; - int iproduct = 1; - int run; - - extern double log(/* double x */); - - printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); - - if (argc < 2) { - printf("Usage: Uliscan filename\n"); - exit(-1); - } else { - printf("Measuring file %s\n", argv[1]); - } - - fptr = fopen(argv[1],"rb"); - - if (fptr == NULL) { - printf("Can't find %s\n", argv[1]); - exit(-1); - } - - for (i = 0; i < V; i++) { - table[i] = 0; - } - - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - table[b] = i; - } - - printf("Init done\n"); - - printf("Expected value for L=8 is 7.1836656\n"); - - run = 1; - - while (run) { - sum = 0.0; - iproduct = 1; - - if (run) - for (i = Q; run && i < Q + K; i++) { - j = i; - b = fgetc(fptr); - - if (b < 0) - run = 0; - - if (run) { - if (table[b] > j) - j += K; - - sum += log((double)(j-table[b])); - - table[b] = i; - } - } - - if (!run) - printf("Premature end of file; read %d blocks.\n", i - Q); - - sum = (sum/((double)(i - Q))) / log(2.0); - printf("%4.4f ", sum); - - for (i = 0; i < (int)(sum*8.0 + 0.50); i++) - printf("-"); - - printf("\n"); - - /* refill initial table */ - if (0) { - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - if (b < 0) { - run = 0; - } else { - table[b] = i; - } - } - } - } -}]]></pre> - </body> -</html> - - diff --git a/en_US.ISO8859-1/articles/mh/Makefile b/en_US.ISO8859-1/articles/mh/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/mh/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml deleted file mode 100644 index fef11739c2..0000000000 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,782 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/mh/article.sgml,v 1.7 1999/10/10 20:20:38 jhb Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> -<article> - <artheader> - <title>An MH Primer</title> - - <authorgroup> - <author> - <firstname>Matt</firstname> - - <surname>Midboe</surname> - - <affiliation> - <address> - <email>matt@garply.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>v1.0, 16 January 1996</pubdate> - - <abstract> - <para>This document contains an introduction to using MH on - FreeBSD</para> - </abstract> - </artheader> - - <sect1 id="mhintro"> - <title>Introduction</title> - - <para>MH started back in 1977 at the RAND Corporation, where the - initial philosophies behind MH were developed. MH isn't so much - a monolithic email program but a philosophy about how best to - develop tools for reading email. The MH developers have done a - great job adhering to the <acronym>KISS</acronym> principle: Keep It - Simple Stupid. Rather than have one large program for reading, - sending and handling email they have written specialized - programs for each part of your email life. One might liken MH to - the specialization that one finds in insects and nature. Each - tool in MH does one thing, and does it very well.</para> - - <para>Beyond just the various tools that one uses to handle their - email MH has done an excellent job keeping the configuration of - each of these tools consistent and uniform. In fact, if you are - not quite sure how something is supposed to work or what the - arguments for some command are supposed to be then you can - generally guess and be right. Each MH command is consistent - about how it handles reading the configuration files and how it - takes arguments on the command line. One useful thing to - remember is that you can always add a <option>-help</option> to - the command to have it display the options for that - command.</para> - - <para>The first thing that you need to do is to make sure that you - have installed the MH package on your FreeBSD machine. If you - installed from CDROM you should be able to execute the following - to load mh: - - <informalexample> - <screen>&prompt.root; <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</> - </screen> - </informalexample> - - You will notice that it created a <filename>/usr/local/lib/mh</filename> - directory for you as well as adding several binaries to the - <filename>/usr/local/bin</filename> directory. If you would prefer to - compile it yourself then you can anonymous ftp it from <ulink - URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink - URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> - - <para>This primer is not a full comprehensive explanation of how - MH works. This is just intended to get you started on the road - to happier, faster mail reading. You should read the man pages - for the various commands. Also you might want to read the <ulink - URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also - you can read the <ulink - URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ - for MH</ulink>. The best resource for MH is the O'Reilly and - Associates book written by Jerry Peek.</para> - </sect1> - - <sect1> - <title>Reading Mail</title> - - <para>This section covers how to use <command>inc</command>, - <command>show</command>, <command>scan</command>, <command>next</command>, - <command>prev</command>, <command>rmm</command>, <command>rmf</command>, and - <command>msgchk</command>. One of the best things about MH is the - consistent interface between programs. A few things to keep in - mind when using these commands is how to specify message lists. - In the case of <command>inc</command> this doesn't really make any - sense but with commands like <command>show</command> it is useful to - know. </para> - - <para>A message list can consist of something like <parameter>23 - 20 16</parameter> which will act on messages 23, 20 and 16. This is - fairly simple but you can do more useful things like - <parameter>23-30</parameter> which will act on all the messages between - 23 and 30. You can also specify something like - <parameter>cur:10</parameter> which will act on the current message and - the next 9 messages. The <parameter>cur</parameter>, <parameter>last</parameter>, - and <parameter>first</parameter> messages are special messages that refer - to the current, last or first message in the folder.</para> - - <sect2 id="inc"> - <title><command>inc</command>, <command>msgchk</command>—read in your - new email or check it</title> - - <para>If you just type in <userinput>inc</userinput> and hit - <keycap>return</keycap> you will be well on your way to getting - started with MH. The first time you run <command>inc</command> it - will setup your account to use all the MH defaults and ask you - about creating a Mail directory. If you have mail waiting to - be downloaded you will see something that looks like:</para> - - <informalexample> - <screen> 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - </screen> - </informalexample> - - <para>This is the same thing you will see from a - <command>scan</command> (see <xref linkend="scan">). If you just run - <command>inc</command> with no arguments it will look on your - computer for email that is supposed to be coming to - you.</para> - - <para>A lot of people like to use POP for grabbing their email. - MH can do POP to grab your email. You will need to give - <command>inc</command> a few command line arguments.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</> -norpop</> - </screen> - </informalexample> - - <para>That tells <command>inc</command> to go to - <parameter>mail.pop.org</parameter> to download your email, and that - your username on their system is <replaceable>username</replaceable>. The - <option>-norpop</option> option tells <command>inc</command> to use - plain POP3 for downloading your email. MH has support for a - few different dialects of POP. More than likely you will never - ever need to use them though. While you can do more complex - things with inc such as audit files and scan format files this - will get you going.</para> - - <para>The <command>msgchk</command> command is used to get information - on whether or not you have new email. <command>msgchk</command> takes - the same <option>-host</option> and <option>-user</option> - options that <command>inc</command> takes.</para> - </sect2> - - <sect2 id="show"> - <title><command>show</command>, <command>next</command> and - <command>prev</command>—displaying and moving through - email</title> - - <para><command>show</command> is to show a letter in your current - folder. Like <command>inc</command>, <command>show</command> is a fairly - straightforward command. If you just type <userinput>show</userinput> - and hit <keycap>return</keycap> then it displays the current - message. You can also give specific message numbers to - show:</para> - - <informalexample> - <screen>&prompt.user; <userinput>show 32 45 56</> - </screen> - </informalexample> - - <para>This would display message numbers 32, 45 and 56 right - after each other. Unless you change the default behavior - <command>show</command> basically just does a <command>more</command> on the - email message.</para> - - <para><command>next</command> is used to move onto the next message and - <command>prev</command> will go to the previous message. Both - commands have an implied <command>show</command> command so that when - you go to the next message it automatically displays - it.</para> - </sect2> - - <sect2 id="scan"> - <title><command>scan</command>—shows you a scan of your - messages</title> - - <para><command>scan</command> will display a brief listing of the - messages in your current folder. This is an example of what - the <command>scan</command> command will give you.</para> - - <informalexample> - <screen> 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - </screen> - </informalexample> - - <para>Like just about everything in MH this display is very - configurable. This is the typical default display. It gives - you the message number, the date on the email, the sender, the - subject line, and a sentence fragment from the very beginning - of the email if it can fit it. The <literal>+</literal> means that - message is the current message, so if you do a - <command>show</command> it will display that message.</para> - - <para>One useful option for scan is the - <option>-reverse</option> option. This will list your messages - with the highest message number first and lowest message - number last. Another useful option with <command>scan</command> is to - have it read from a file. If you want to scan your incoming - mailbox on FreeBSD without having to <command>inc</command> it you - can do <command>scan -file - /var/mail/<replaceable>username</replaceable></command>. This can be used - with any file that is in the <database>mbox</database> format.</para> - </sect2> - - <sect2 id="rmm"> - <title><command>rmm</command> and <command>rmf</command>—remove the - current message or folder</title> - - <para><command>rmm</command> is used to remove a mail message. The - default is typically to not actually remove the message but to - rename the file to one that is ignored by the MH commands. You - will need to through periodically and physically delete the - <quote>removed</quote> messages.</para> - - <para>The <command>rmf</command> command is used to remove folders. - This doesn't just rename the files but actually removes the - from the hard drive so you should be careful when you use this - command.</para> - </sect2> - - <sect2 id="samplereading"> - <title>A typical session of reading with MH</title> - - <para>The first thing that you will want to do is - <command>inc</command> your new mail. So at a shell prompt just type - in <command>inc</command> and hit <keycap>return</keycap>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc</> -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user; - </screen> - </informalexample> - - <para>This shows you the new email that has been added to your - mailbox. So the next thing to do is <command>show</command> the email - and move around.</para> - - <informalexample> - <screen>&prompt.user; <userinput>show</> -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -&prompt.user; <userinput>rmm</> -&prompt.user; <userinput>next</> -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party). - </screen> - </informalexample> - - <para>The <command>rmm</command> removed the current message and the - <command>next</command> command moved me on to the next message. Now - if I wanted to look at ten most recent messages so I could - read one of them here is what I would do:</para> - - <informalexample> - <screen>&prompt.user; <userinput>scan last:10</> - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user; - </screen> - </informalexample> - - <para>Then if I wanted to read message number 27 I would do a - <userinput>show 27</userinput> and it would be displayed. As you can - probably tell from this sample session MH is pretty easy to - use and looking through emails and displaying them is fairly - intuitive and easy.</para> - </sect2> - </sect1> - - <sect1> - <title>Folders and Mail Searching</title> - - <para>Anybody who gets lots of email definitely wants to be able - to prioritize, stamp, brief, de-brief, and number their emails - in a variety of different ways. MH can do this better than just - about anything. One thing that we haven't really talked about is - the concept of folders. You have undoubtedly come across the - folders concept using other email programs. MH has folders too. - MH can even do sub-folders of a folder. One thing you should - keep in mind with MH is that when you ran <command>inc</command> for - the first time and it asked you if it could create a - <filename>Mail</filename> directory it began storing everything in that - directory. If you look at that directory you will find a - directory named <filename>inbox</filename>. The <filename>inbox</filename> - directory houses all of your incoming mail that hasn't been - thrown anywhere else.</para> - - <para>Whenever you create a new folder a new directory is going to - be created underneath your MH <filename>Mail</filename> directory, and - messages in that folder are going to be stored in that - directory. When new email comes in that new email is thrown - into your <filename>inbox</filename> directory with a file name that is - equivalent to the message number. So even if you didn't have - any of the MH tools to read your email you could still use - standard UNIX commands to munge around in those directories and - just more your files. It's this simplicity that really gives you - a lot of power with what you can do with your email.</para> - - <para>Just as you can use message lists like <parameter>23 16 - 42</parameter> with most MH commands there is a folder option you can - specify with just about every MH command. If you do a - <command>scan +freebsd</command> it will scan your <filename>freebsd</filename> - folder, and your current folder will be changed to - <filename>freebsd</filename>. If you do a <command>show +freebsd 23 16 - 42</command>, <command>show</command> is going to switch to your - <filename>freebsd</filename> folder and display messages 23, 16 and 42. - So remember that <option>+<replaceable>folder</replaceable></option> syntax. You - will need to make sure you use it to make commands process - different folders. Remember you default folder for mail is - <filename>inbox</filename> so doing a <command>folder +inbox</command> should - always get you back to your mail. Of course, in MH's infinite - flexibility this can be changed but most places have probably - left it as <command>inbox</command>.</para> - - <sect2> - <title><command>pick</command>—search email that matches certain - criteria</title> - - <para><command>pick</command> is one of the more complex commands in - the MH system. So you might want to read the - <citerefentry><refentrytitle>pick</refentrytitle><manvolnum>1</manvolnum></citerefentry> man - page for a more thorough understanding. At its simplest level - you can do something like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci</> -15 -42 -55 -56 -57 - </screen> - </informalexample> - - <para>This will tell <command>pick</command> to look through every - single line in every message in your current folder and tell - you which message numbers it found the word <literal>pci</literal> - in. You can then <command>show</command> those messages and read them - if you wish or <command>rmm</command> them. You would have to specify - something like <command>show 15 42 55-57</command> to display them - though. A slightly more useful thing to do is this:</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci -seq pick</> -5 hits -&prompt.user; <userinput>show pick</> - </screen> - </informalexample> - - <para>This will show you the same messages you just didn't have - to work as hard to do it. The <option>-seq</option> option is - really an abbreviation of <option>-sequence</option> and - <command>pick</command> is just a sequence which contains the message - numbers that matched. You can use sequences with just about - any MH command. So you could have done an <command>rmm pick</command> - and all those messages would be removed instead. You sequence - can be named anything. If you run pick again it will overwrite - the old sequence if you use the same name.</para> - - <para>Doing a <command>pick -search</command> can be a bit more - time consuming than just searching for message from someone, - or to someone. So <command>pick</command> allows you to use the - following predefined search criteria:</para> - - <variablelist> - <varlistentry> - <term><option>-to</option></term> - - <listitem> - <para>search based upon who the message is to</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-cc</option></term> - - <listitem> - <para>search based on who is in the cc list</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-from</option></term> - - <listitem> - <para>search for who sent the message</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-subject</option></term> - - <listitem> - <para>search for emails with this subject</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-date</option></term> - - <listitem> - <para>find emails with a matching dat</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--<replaceable>component</replaceable></option></term> - - <listitem> - <para>search for any other component in the header. (i.e. - <option>--reply-to</option> to find all emails with a certain - reply-to in the header)</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This allows you to do things like - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers@FreeBSD.org -seq hackers</> - </screen> - </informalexample> - - to get a list of all the email send to the FreeBSD hackers - mailing list. <command>pick</command> also allows you to group these - criteria in different ways using the following options:</para> - - <itemizedlist> - <listitem> - <para>… <option>-and</option> …</para> - </listitem> - - <listitem> - <para>… <option>-or</option> &hellip</para> - </listitem> - - <listitem> - <para><option>-not</option> …</para> - </listitem> - - <listitem> - <para><option>-lbrace</option> … - <option>-rbrace</option></para> - </listitem> - </itemizedlist> - - <para>These commands allow you to do things like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers -and -cc freebsd-hackers</> - </screen> - </informalexample> - - <para>That will grab all the email in your inbox that was sent - to freebsd-hackers or cc'd to that list. The brace options - allow you to group search criteria together. This is sometimes - very necessary as in the following example</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci</> - </screen> - </informalexample> - - <para>Basically this says <quote>pick (to freebsd-hackers and - not cc'd on freebsd-questions) and the subject is - pci</quote>. It should look through your folder and find - all messages sent to the freebsd-hackers list that aren't cc'd - to the freebsd-questions list that contain something on pci in - the subject line. Ordinarily you might have to worry about - something called operator precedence. Remember in math how you - evaluate from left to right and you do multiplication and - division first and addition and subtraction second? MH has the - same type of rules for <command>pick</command>. It's fairly complex - so you might want to study the man page. This document is just - to help you get acquainted with MH.</para> - </sect2> - - <sect2> - <title><command>folder</command>, <command>folders</command>, - <command>refile</command>—three useful programs for folder - maintenance</title> - - <para>There are three programs which are primarily just for - manipulating your folders. The <command>folder</command> program is - used to switch between folders, pack them, and list them. At - its simplest level you can do a <command>folder - +<replaceable>newfolder</replaceable></command> and you will be switched into - <replaceable>newfolder</replaceable>. From there on out all your MH - commands like <command>comp</command>, <command>repl</command>, - <command>scan</command>, and <command>show</command> will act on that - <command>newfolder</command> folder.</para> - - <para>Sometimes when you are reading and deleting messages you - will develop <quote>holes</quote> in your folders. If you do a - <command>scan</command> you might just see messages 34, 35, 36, 43, - 55, 56, 57, 80. If you do a <command>folder -pack</command> - this will renumber all your messages so that there are no - holes. It doesn't actually delete any messages though. So you - may need to periodically go through and physically delete - <command>rmm</command>'d messages.</para> - - <para>If you need statistics on your folders you can do a - <command>folders</command> or <command>folder -all</command> to list - all your folders, how many messages they have, what the - current message is in each one and so on. This line of stats - it displays for all your folders is the same one you get when - you change to a folder with <command>folder +foldername</command>. A - <command>folders</command> command looks like this:</para> - - <informalexample> - <screen> Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. - </screen> - </informalexample> - - <para>The <command>refile</command> command is what you use to move - messages between folders. When you do something like - <command>refile 23 +netfuture</command> message number 23 is moved - into the <filename>netfuture</filename> folder. You could also do - something like <command>refile 23 +netfuture/latest</command> which - would put message number 23 in a subfolder called - <filename>latest</filename> under the <filename>netfuture</filename> folder. - If you want to keep a message in the current folder and link - it you can do a <command>refile -link 23 +netfuture</command> - which would keep 23 in your current <filename>inbox</filename> but - also list in your <filename>netfuture</filename> folder. You are - probably beginning to realize some of the really powerful - things you can do with MH.</para> - </sect2> - </sect1> - - <sect1> - <title>Sending Mail</title> - - <para>Email is a two way street for most people so you want to be - able to send something back. The way MH handles sending mail can - be a bit difficult to follow at first, but it allows for - incredible flexibility. The first thing MH does is to copy a - components file into your outgoing email. A components file is - basically a skeleton email letter with stuff like the To: and - Subject: headers already in it. You are then sent into your - editor where you fill in the header information and then type - the body of your message below the dashed lines in the message. - Then to the <command>whatnow</command> program. When you are at the - <prompt>What now?</prompt> prompt you can tell it to - <command>send</command>, <command>list</command>, <command>edit</command>, - <command>edit</command>, <command>push</command>, and <command>quit</command>. Most - of these commands are self-explanatory. So the message sending - process involves copying a component file, editing your email, - and then telling the <command>whatnow</command> program what to do with - your email.</para> - - <sect2> - <title><command>comp</command>, <command>forw</command>, - <command>reply</command>—compose, forward or reply to a message - to someone</title> - - <para>The <command>comp</command> program has a few useful command line - options. The most important one to know right now is the - <option>-editor</option> option. When MH is installed the - default editor is usually a program called - <command>prompter</command> which comes with MH. It's not a very - exciting editor and basically just gets the job done. So when - you go to compose a message to someone you might want to use - <command>comp -editor /usr/bin/vi/</command> or <command>comp -editor - /usr/local/bin/pico/</command> instead. Once you have run - <emphasis>comp</emphasis> you are in your editor and you see - something that looks like this:</para> - - <informalexample> - <screen>To: -cc: -Subject: --------- - </screen> - </informalexample> - - <para>You need to put the person you are sending the mail to - after the <literal>To:</literal> line. It works the same way for the - other headers also, so you would need to put your subject - after the <literal>Subject:</literal> line. Then you would just put - the body of your message after the dashed lines. It may seem a - bit simplistic since a lot of email programs have special - requesters that ask you for this information but there really - isn't any point to that. Plus this really gives you excellent - flexibility.</para> - - <informalexample> - <screen>To:<userinput>freebsd-rave@FreeBSD.org</> -cc: -Subject:<userinput>And on the 8th day God created the FreeBSD core team</> --------- -<userinput>Wow this is an amazing operating system. Thanks!</> - </screen> - </informalexample> - - <para>You can now save this message and exit your editor. You - will see the <prompt>What now?</prompt> prompt and you can type in - <userinput>send</userinput> or <userinput>s</userinput> and hit - <keycap>return</keycap>. Then the FreeBSD core team will receive - their just rewards. As I mentioned earlier you can also use - other commands, for example <command>quit</command> if you don't want - to send the message.</para> - - <para>The <command>forw</command> command is stunningly similar. The - big difference being that the message you are forwarding is - automatically included in the outgoing message. When you run - <command>forw</command> it will forward your current message. You can - always tell it to forward something else by doing something - like <command>forw 23</command> and then message number 23 will be - put in your outgoing message instead of the current message. - Beyond those small differences <command>forw</command> functions - exactly the same as <command>comp</command>. You go through the exact - same message sending process.</para> - - <para>The <command>repl</command> command will reply to whatever your - current message is, unless you give it a different message to - reply to. <command>repl</command> will do its best to go ahead and - fill in some of the email headers already. So you will notice - that the <literal>To:</literal> header already has the address of the - recipient in there. Also the <literal>Subject:</literal> line will - already be filled in. You then go about the normal message - composition process and you are done. One useful command line - option to know here is the <option>-cc</option> option. You - can use <parameter>all</parameter>, <parameter>to</parameter>, <parameter>cc</parameter>, - <parameter>me</parameter> after the <option>-cc</option> option to have - <command>repl</command> automatically add the various addresses to - the cc list in the message. You have probably noticed that the - original message isn't included. This is because most MH - setups are configured to do this from the start.</para> - </sect2> - - <sect2> - <title><filename>components</filename>, and - <filename>replcomps</filename>—components files for - <command>comp</command> and <command>repl</command></title> - - <para>The <filename>components</filename> file is usually in - <filename>/usr/local/lib/mh</filename>. You can copy that file - into your MH Mail directory and edit to contain what you want - it to contain. It is a fairly basic file. You have various - email headers at the top, a dashed line and then nothing. The - <command>comp</command> command just copies this - <filename>components</filename> file and then edits it. You can add - any kind of valid RFC822 header you want. For instance you - could have something like this in your <filename>components</filename> - file:</para> - - <informalexample> - <screen>To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.FreeBSD.org/ -------- - </screen> - </informalexample> - - <para>MH would then copy this components file and throw you into - your editor. The <filename>components</filename> file is fairly - simple. If you wanted to have a signature on those messages - you would just put your signature in that - <filename>components</filename> file.</para> - - <para>The <filename>replcomps</filename> file is a bit more complex. The - default <filename>replcomps</filename> looks like this:</para> - - <informalexample> - <screen>%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- - </screen> - </informalexample> - - <para>It's in the same basic format as the - <filename>components</filename> file but it contains quite a few extra - formatting codes. The <literal>%(lit)</literal> command makes room - for the address. The <literal>%(formataddr</literal> is a function - that returns a proper email address. The next part is - <literal>%<</literal> which means if and the - <literal>{reply-to}</literal> means the reply-to field in the - original message. So that might be translated this way:</para> - - <informalexample> - <screen>%<<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> -then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the -from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %? -<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original -message</emphasis>, %> <emphasis remap=bf>endif</emphasis>. - </screen> - </informalexample> - - <para>As you can tell MH formatting can get rather involved. You - can probably decipher what most of the other functions and - variables mean. All of the information on writing these format - strings is in the MH-Format man page. The really nice thing is - that once you have built your customized - <filename>replcomps</filename> file you won't need to touch it again. - No other email program really gives you the power and - flexibility that MH gives you.</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/multi-os/Makefile b/en_US.ISO8859-1/articles/multi-os/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml deleted file mode 100644 index f7ee999f88..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,743 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/multi-os/article.sgml,v 1.12 2000/05/30 22:48:47 nik Exp $ --> -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> -<article> - <artheader> - <title>Installing and Using FreeBSD With Other Operating Systems</title> - - <authorgroup> - <author> - <firstname>Jay</firstname> - - <surname>Richmond</surname> - - <affiliation> - <address> - <email>jayrich@sysc.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>6 August 1996</pubdate> - - <abstract> - <para>This document discusses how to make FreeBSD coexist nicely - with other popular operating systems such as Linux, MS-DOS, - OS/2, and Windows 95. Special thanks to: Annelise Anderson - <email>andrsn@stanford.edu</email>, Randall Hopper - <email>rhh@ct.picker.com</email>, and Jordan K. Hubbard - <email>jkh@time.cdrom.com</email></para> - </abstract> - </artheader> - - <sect1> - <title>Overview</title> - - <para>Most people can't fit these operating systems together - comfortably without having a larger hard disk, so special - information on large EIDE drives is included. Because there are - so many combinations of possible operating systems and hard disk - configurations, the <xref linkend="ch5"> section may be of the - most use to you. It contains descriptions of specific working - computer setups that use multiple operating systems.</para> - - <para>This document assumes that you have already made room on - your hard disk for an additional operating system. Any time you - repartition your hard drive, you run the risk of destroying the - data on the original partitions. However, if your hard drive is - completely occupied by DOS, you might find the FIPS utility - (included on the FreeBSD CD-ROM in the - <filename>\TOOLS</filename> directory or via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>) - useful. It lets you repartition your hard disk without - destroying the data already on it. There is also a commercial - program available called Partition Magic, which lets you size - and delete partitions without consequence.</para> - </sect1> - - <sect1 id="ch2"> - <title>Overview of Boot Managers</title> - - <para>These are just brief descriptions of some of the different - boot managers you may encounter. Depending on your computer - setup, you may find it useful to use more than one of them on - the same system.</para> - - <variablelist> - <varlistentry> - <term>Boot Easy</term> - - <listitem> - <para>This is the default boot manager used with FreeBSD. - It has the ability to boot most anything, including BSD, - OS/2 (HPFS), Windows 95 (FAT and FAT32), and Linux. - Partitions are selected with the function keys.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>OS/2 Boot Manager</term> - - <listitem> - <para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 - (Linux). It will also boot FAT32 partitions. Partitions - are selected using arrow keys. The OS/2 Boot Manager is - the only one to use its own separate partition, unlike the - others which use the master boot record (MBR). Therefore, - it must be installed below the 1024th cylinder to avoid - booting problems. It can boot Linux using LILO when it is - part of the boot sector, not the MBR. Go to <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOWTOs</ulink> on the World Wide Web for more - information on booting Linux with OS/2's boot - manager.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>OS-BS</term> - - <listitem> - <para>This is an alternative to Boot Easy. It gives you more - control over the booting process, with the ability to set - the default partition to boot and the booting timeout. - The beta version of this programs allows you to boot by - selecting the OS with your arrow keys. It is included on - the FreeBSD CD in the <filename>\TOOLS</filename> - directory, and via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LILO, or LInux LOader</term> - - <listitem> - <para>This is a limited boot manager. It will boot FreeBSD, - though some customization work is required in the LILO - configuration file.</para> - </listitem> - </varlistentry> - </variablelist> - - <note id="fat32"> - <title>About FAT32</title> - - <para>FAT32 is the replacement to the FAT filesystem included in - Microsoft's OEM SR2 Beta release, which is expected to be - utilitized on computers pre-loaded with Windows 95 towards the - end of 1996. It converts the normal FAT file system and - allows you to use smaller cluster sizes for larger hard - drives. FAT32 also modifies the traditional FAT boot sector - and allocation table, making it incompatible with some boot - managers.</para> - </note> - </sect1> - - <sect1 id="ch3"> - <title>A Typical Installation</title> - - <para>Let's say I have two large EIDE hard drives, and I want to - install FreeBSD, Linux, and Windows 95 on them.</para> - - <para>Here's how I might do it using these hard disks:</para> - - <itemizedlist> - <listitem> - <para><filename>/dev/wd0</filename> (first physical hard disk)</para> - </listitem> - - <listitem> - <para><filename>/dev/wd1</filename> (second hard disk)</para> - </listitem> - </itemizedlist> - - <para>Both disks have 1416 cylinders.</para> - - <procedure> - <step> - <para>I boot from a MS-DOS or Windows 95 boot disk that - contains the <filename>FDISK.EXE</filename> utility and make a small - 50 meg primary partition (35-40 for Windows 95, plus a - little breathing room) on the first disk. Also create a - larger partition on the second hard disk for my Windows - applications and data.</para> - </step> - - <step> - <para>I reboot and install Windows 95 (easier said than done) - on the <filename>C:</filename> partition.</para> - </step> - - <step> - <para>The next thing I do is install Linux. I'm not sure - about all the distributions of Linux, but slackware includes - LILO (see <xref linkend="ch2">). When I am partitioning out - my hard disk with Linux <command>fdisk</command>, I would - put all of Linux on the first drive (maybe 300 megs for a - nice root partition and some swap space).</para> - </step> - - <step> - <para>After I install Linux, and are prompted about installing - LILO, make SURE that I install it on the boot sector of my - root Linux partition, not in the MBR (master boot - record).</para> - </step> - - <step> - <para>The remaining hard disk space can go to FreeBSD. I also - make sure that my FreeBSD root slice does not go beyond the - 1024th cylinder. (The 1024th cylinder is 528 megs into the - disk with our hypothetical 720MB disks). I will use the - rest of the hard drive (about 270 megs) for the - <filename>/usr</filename> and <filename>/</filename> slices if I wish. The - rest of the second hard disk (size depends on the amount of - my Windows application/data partition that I created in step - 1 can go to the <filename>/usr/src</filename> slice and swap - space.</para> - </step> - - <step> - <para>When viewed with the Windows 95 <command>fdisk</command> - utility, my hard drives should now look something like this: - - <screen> ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - </screen> - ** May say FAT16 or FAT32 if you are using the OEM SR2 - update. See <xref linkend="ch2">).</para> - </step> - - <step> - <para>Install FreeBSD. I make sure to boot with my first hard - disk set at <quote>NORMAL</quote> in the BIOS. If it is not, - I'll have the enter my true disk geometry at boot time (to - get this, boot Windows 95 and consult Microsoft Diagnostics - (<filename>MSD.EXE</filename>), or check your BIOS) with the - parameter <literal>hd0=1416,16,63</literal> where - <replaceable>1416</replaceable> is the number of cylinders on my hard - disk, <replaceable>16</replaceable> is the number of heads per track, - and <replaceable>63</replaceable> is the number of sectors per track on - the drive.</para> - </step> - - <step> - <para>When partitioning out the hard disk, I make sure to - install Boot Easy on the first disk. I don't worry about - the second disk, nothing is booting off of it.</para> - </step> - - <step> - <para>When I reboot, Boot Easy should recognize my three - bootable partitions as DOS (Windows 95), Linux, and BSD - (FreeBSD).</para> - </step> - </procedure> - </sect1> - - <sect1 id="ch4"> - <title>Special Considerations</title> - - <para>Most operating systems are very picky about where and how - they are placed on the hard disk. Windows 95 and DOS need to be - on the first primary partitiin on the first hard disk. OS/2 is - the exception. It can be installed on the first or second disk - in a primary or extended partition. If you are not sure, keep - the beginning of the bootable partitions below the 1024th - cylinder.</para> - - <para>If you install Windows 95 on an existing BSD system, it will - <quote>destroy</quote> the MBR, and you will have to reinstall your - previous boot manager. Boot Easy can be reinstalled by using - the BOOTINST.EXE utility included in the \TOOLS directory on the - CD-ROM, and via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>. - You can also re-start the installation process and go to the - partition editor. From there, mark the FreeBSD partition as - bootable, select Boot Manager, and then type W to (W)rite out - the information to the MBR. You can now reboot, and Boot Easy - should then recognize Windows 95 as DOS.</para> - - <para>Please keep in mind that OS/2 can read FAT and HPFS - partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. - Likewise, Windows 95 can only read and write to FAT and FAT32 - (see <xref linkend="ch2">) partitions. FreeBSD can read most - file systems, but currently cannot read HPFS partitions. Linux - can read HPFS partitions, but can't write to them. Recent - versions of the Linux kernel (2.x) can read and write to Windows - 95 VFAT partitions (VFAT is what gives Windows 95 long file - names - it's pretty much the same as FAT). Linux can read and - write to most file systems. Got that? I hope so.</para> - </sect1> - - <sect1 id="ch5"> - <title>Examples</title> - - <para><emphasis>(section needs work, please send your example to - <email>jayrich@sysc.com</email>)</emphasis>.</para> - - <para>FreeBSD+Win95: If you installed FreeBSD after Windows 95, - you should see <literal>DOS</literal> on the Boot Easy menu. This is - Windows 95. If you installed Windows 95 after FreeBSD, read - <xref linkend="ch4"> above. As long as your hard disk does not - have 1024 cylinders you should not have a problem booting. If - one of your partitions goes beyond the 1024th cylinder however, - and you get messages like <errorname>invalid system disk</errorname> - under DOS (Windows 95) and FreeBSD will not boot, try looking - for a setting in your BIOS called <quote>> 1024 cylinder - support</quote> or <quote>NORMAL/LBA</quote> mode. DOS may need LBA - (Logical Block Addressing) in order to boot correctly. If the - idea of switching BIOS settings every time you boot up doesn't - appeal to you, you can boot FreeBSD through DOS via the - <filename>FBSDBOOT.EXE</filename> utility on the CD (It should find your - FreeBSD partition and boot it.)</para> - - <para>FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger - can boot all of these operating systems, so that shouldn't be a - problem.</para> - - <para>FreeBSD+Linux: You can also use Boot Easy to boot both - operating systems.</para> - - <para>FreeBSD+Linux+Win95: (see <xref linkend="ch3">)</para> - </sect1> - - <sect1 id="sources"> - <title>Other Sources of Help</title> - - <para>There are many <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOW-TOs</ulink> that deal with multiple operating systems on - the same hard disk.</para> - - <para>The <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 - mini-HOWTO</ulink> offers help on configuring the OS/2 boot - manager, and the <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD - mini-HOWTO</ulink> might be interesting as well. The <ulink - URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> - is also helpful.</para> - - <para>The <ulink - URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT - Loader Hacking Guide</ulink> provides good information on - multibooting Windows NT, '95, and DOS with other operating - systems.</para> - - <para>And Hale Landis's "How It Works" document pack contains some - good info on all sorts of disk geometry and booting related - topics. You can find it at - <ulink - URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>.</para> - - <para>Finally, don't overlook FreeBSD's kernel documentation on - the booting procedure, available in the kernel source - distribution (it unpacks to <ulink - URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para> - </sect1> - - <sect1> - <title>Technical Details</title> - - <para><emphasis>(Contributed by Randall Hopper, - <email>rhh@ct.picker.com</email>)</emphasis></para> - - <para>This section attempts to give you enough basic information - about your hard disks and the disk booting process so that you - can troubleshoot most problems you might encounter when getting - set up to boot several operating systems. It starts in pretty - basic terms, so you may want to skim down in this section until - it begins to look unfamiliar and then start reading.</para> - - <sect2> - <title>Disk Primer</title> - - <para>Three fundamental terms are used to describe the location - of data on your hard disk: Cylinders, Heads, and Sectors. - It's not particularly important to know what these terms - relate to except to know that, together, they identify where - data is physically on your disk.</para> - - <para>Your disk has a particular number of cylinders, number of - heads, and number of sectors per cylinder-head (a - cylinder-head also known nown as a track). Collectively this - information defines the "physical disk geometry" for your hard - disk. There are typically 512 bytes per sector, and 63 - sectors per track, with the number of cylinders and heads - varying widely from disk to disk. Thus you can figure the - number of bytes of data that'll fit on your own disk by - calculating:</para> - - <informalexample> - <para>(# of cylinders) × (# heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>For example, on my 1.6 Gig Western Digital AC31600 EIDE hard - disk,that's:</para> - - <informalexample> - <para>(3148 cyl) × (16 heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para> - - <para>You can find out the physical disk geometry (number of - cylinders, heads, and sectors/track counts) for your hard - disks using ATAID or other programs off the net. Your hard - disk probably came with this information as well. Be careful - though: if you're using BIOS LBA (see <xref - linkend="limits">), you can't use just any program to get - the physical geometry. This is because many programs (e.g. - <filename>MSD.EXE</filename> or FreeBSD fdisk) don't identify the - physical disk geometry; they instead report the - <firstterm>translated geometry</firstterm> (virtual numbers from using - LBA). Stay tuned for what that means.</para> - - <para>One other useful thing about these terms. Given 3 - numbers—a cylinder number, a head number, and a - sector-within-track number—you identify a specific - absolute sector (a 512 byte block of data) on your disk. - Cylinders and Heads are numbered up from 0, and Sectors are - numbered up from 1.</para> - - <para>For those that are interested in more technical details, - information on disk geometry, boot sectors, BIOSes, etc. can - be found all over the net. Query Lycos, Yahoo, etc. for - <literal>boot sector</literal> or <literal>master boot record</literal>. - Among the useful info you'll find are Hale Landis's - <citetitle>How It Works</citetitle> document pack. See the <xref - linkend="sources"> section for a few pointers to this - pack.</para> - - <para>Ok, enough terminology. We're talking about booting - here.</para> - </sect2> - - <sect2 id="booting"> - <title>The Booting Process</title> - - <para>On the first sector of your disk (Cyl 0, Head 0, Sector 1) - lives the Master Boot Record (MBR). It contains a map of your - disk. It identifies up to 4 <firstterm>partitions</firstterm>, each of - which is a contiguous chunk of that disk. FreeBSD calls - partitions <firstterm>slices</firstterm> to avoid confusion with it's - own partitions, but we won't do that here. Each partition can - contain its own operating system.</para> - - <para>Each partition entry in the MBR has a <firstterm>Partition - ID</firstterm>, a <firstterm>Start Cylinder/Head/Sector</firstterm>, and an - <firstterm>End Cylinder/Head/Sector</firstterm>. The Partition ID - tells what type of partition it is (what OS) and the Start/End - tells where it is. <xref linkend="tbl-pid"> lists a - smattering of some common Partition IDs.</para> - - <table id="tbl-pid"> - <title>Partition IDs</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>ID (hex)</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>01</entry> - <entry>Primary DOS12 (12-bit FAT)</entry> - </row> - - <row> - <entry>04</entry> - <entry>Primary DOS16 (16-bit FAT)</entry> - </row> - - <row> - <entry>05</entry> - <entry>Extended DOS</entry> - </row> - - <row> - <entry>06</entry> - <entry>Primary big DOS (> 32MB)</entry> - </row> - - <row> - <entry>0A</entry> - <entry>OS/2</entry> - </row> - - <row> - <entry>83</entry> - <entry>Linux (EXT2FS)</entry> - </row> - - <row> - <entry>A5</entry> - <entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note that not all partitions are bootable (e.g. Extended - DOS). Some are—some aren't. What makes a partition - bootable is the configuration of the <firstterm>Partition Boot - Sector</firstterm> that exists at the beginning of each - partition.</para> - - <para>When you configure your favorite boot manager, it looks up - the entries in the MBR partition tables of all your hard disks - and lets you name the entries in that list. Then when you - boot, the boot manager is invoked by special code in the - Master Boot Sector of the first probed hard disk on your - system. It looks at the MBR partition table entry - corresponding to the partition choice you made, uses the Start - Cylinder/Head/Sector information for that partition, loads up - the Partition Boot Sector for that partition, and gives it - control. That Boot Sector for the partition itself contains - enough information to start loading the operating system on - that partition.</para> - - <para>One thing we just brushed past that's important to know. - All of your hard disks have MBRs. However, the one that's - important is the one on the disk that's first probed by the - BIOS. If you have only IDE hard disks, its the first IDE disk - (e.g. primary disk on first controller). Similarly for SCSI - only systems. If you have both IDE and SCSI hard disks - though, the IDE disk is typically probed first by the BIOS, so - the first IDE disk is the first probed disk. The boot manager - you will install will be hooked into the MBR on this first - probed hard disk that we've just described.</para> - </sect2> - - <sect2 id="limits"> - <title>Booting Limitations and Warnings</title> - - <para>Now the interesting stuff that you need to watch out - for.</para> - - <sect3> - <title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title> - - <para>The first part of the booting process is all done - through the BIOS, (if that's a new term to you, the BIOS is - a software chip on your system motherboard which provides - startup code for your computer). As such, this first part - of the process is subject to the limitations of the BIOS - interface.</para> - - <para>The BIOS interface used to read the hard disk during - this period (INT 13H, Subfunction 2) allocates 10 bits to - the Cylinder Number, 8 bits to the Head Number, and 6 bits - to the Sector Number. This restricts users of this - interface (i.e. boot managers hooked into your disk's MBR as - well as OS loaders hooked into the Boot Sectors) to the - following limits:</para> - - <itemizedlist> - <listitem> - <para>1024 cylinders, max</para> - </listitem> - - <listitem> - <para>256 heads, max</para> - </listitem> - - <listitem> - <para>64 sectors/track, max (actually 63, <literal>0</literal> - isn't available)</para> - </listitem> - </itemizedlist> - - <para>Now big hard disks have lots of cylinders but not a lot - of heads, so invariably with big hard disks the number of - cylinders is greater than 1024. Given this and the BIOS - interface as is, you can't boot off just anywhere on your - hard disk. The boot code (the boot manager and the OS - loader hooked into all bootable partitions' Boot Sectors) - has to reside below cylinder 1024. In fact, if your hard - disk is typical and has 16 heads, this equates to:</para> - - <informalexample> - <para>1024 cyl/disk × 16 heads/disk × 63 - sect/(cyl-head) × 512 bytes/sector</para> - </informalexample> - - <para>which is around the often-mentioned 528MB limit.</para> - - <para>This is where BIOS LBA (Logical Block Addressing) comes - in. BIOS LBA gives the user of the BIOS API calls access to - physical cylinders above 1024 though the BIOS interfaces by - redefining a cylinder. That is, it remaps your cylinders - and heads, making it appear through the BIOS as though the - disk has fewer cylinders and more heads than it actually - does. In other words, it takes advantage of the fact that - hard disks have relatively few heads and lots of cylinders - by shifting the balance between number of cylinders and - number of heads so that both numbers lie below the - above-mentioned limits (1024 cylinders, 256 heads).</para> - - <para>With BIOS LBA, the hard disk size limitation is - virtually removed (well, pushed up to 8 Gigabytes anyway). - If you have an LBA BIOS, you can put FreeBSD or any OS - anywhere you want and not hit the 1024 cylinder - limit.</para> - - <para>To use my 1.6 Gig Western Digital as an example again, - it's physical geometry is:</para> - - <informalexample> - <para>(3148 cyl, 16 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>However, my BIOS LBA remaps this to:</para> - - <informalexample> - <para>(787 cyl, 64 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>giving the same effective size disk, but with cylinder - and head counts within the BIOS API's range (Incidentally, I - have both Linux and FreeBSD existing on one of my hard disks - above the 1024th physical cylinder, and both operating - systems boot fine, thanks to BIOS LBA).</para> - </sect3> - - <sect3> - <title>Boot Managers and Disk Allocation</title> - - <para>Another gotcha to watch out when installing boot - managers is allocating space for your boot manager. It's - best to be aware of this issue up front to save yourself - from having to reinstall one or more of your OSs.</para> - - <para>If you followed the discussion in <xref - linkend="booting"> about the Master Boot Sector (where the - MBR is), Partition Boot Sectors, and the booting process, - you may have been wondering just exactly where on your hard - disk that nifty boot manager is going to live. Well, some - boot managers are small enough to fit entirely within the - Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with - the partition table. Others need a bit more room and - actually extend a few sectors past the Master Boot Sector in - the Cylinder 0 Head 0 track, since that's typically - free…typically.</para> - - <para>That's the catch. Some operating systems (FreeBSD - included) let you start their partitions right after the - Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you - want. In fact, if you give FreeBSD's sysinstall a disk with - an empty chunk up front or the whole disk empty, that's - where it'll start the FreeBSD partition by default (at least - it did when I fell into this trap). Then when you go to - install your boot manager, if it's one that occupies a few - extra sectors after the MBR, it'll overwrite the front of - the first partition's data. In the case of FreeBSD, this - overwrites the disk label, and renders your FreeBSD - partition unbootable.</para> - - <para>The easy way to avoid this problem (and leave yourself - the flexibility to try different boot managers later) is - just to always leave the first full track on your disk - unallocated when you partition your disk. That is, leave - the space from Cylinder 0, Head 0, Sector 2 through Cylinder - 0, Head 0, Sector 63 unallocated, and start your first - partition at Cylinder 0, Head 1, Sector 1. For what it's - worth, when you create a DOS partition at the front of your - disk, DOS leaves this space open by default (this is why - some boot managers assume it's free). So creating a DOS - partition up at the front of your disk avoids this problem - altogether. I like to do this myself, creating 1 Meg DOS - partition up front, because it also avoids my primary DOS - drive letters shifting later when I repartition.</para> - - <para>For reference, the following boot managers use the - Master Boot Sector to store their code and data:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 1.35</para> - </listitem> - - <listitem> - <para>Boot Easy</para> - </listitem> - - <listitem> - <para>LILO</para> - </listitem> - </itemizedlist> - - <para>These boot managers use a few additional sectors after - the Master Boot Sector:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 2.0 Beta 8 (sectors 2-5)</para> - </listitem> - - <listitem> - <para>OS/2's boot manager</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>What if your machine won't boot?</title> - - <para>At some point when installing boot managers, you might - leave the MBR in a state such that your machine won't boot. - This is unlikely, but possible when re-FDISKing underneath - an already-installed boot manager.</para> - - <para>If you have a bootable DOS partition on your disk, you - can boot off a DOS floppy, and run:</para> - - <informalexample> - <screen>A:\> <userinput>FDISK /MBR</> - </screen> - </informalexample> - - <para>to put the original, simple DOS boot code back into the - system. You can then boot DOS (and DOS only) off the hard - drive. Alternatively, just re-run your boot manager - installation program off a bootable floppy.</para> - </sect3> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/new-users/Makefile b/en_US.ISO8859-1/articles/new-users/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml deleted file mode 100644 index 11fb19fccc..0000000000 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,1053 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/new-users/article.sgml,v 1.14 2000/07/26 18:24:50 jim Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> -<article> - <artheader> - <title>For People New to Both FreeBSD and Unix</title> - - <authorgroup> - <author> - <firstname>Annelise</firstname> - - <surname>Anderson</surname> - - <affiliation> - <address><email>andrsn@andrsn.stanford.edu</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 15, 1997</pubdate> - - <abstract> - <para>Congratulations on installing FreeBSD! This introduction - is for people new to both FreeBSD <emphasis>and</emphasis> - Un*x—so it starts with basics. It assumes you're using - version 2.0.5 or later of FreeBSD as distributed by BSDi - or FreeBSD.org, your system (for now) has a single user - (you)—and you're probably pretty good with DOS/Windows - or OS/2.</para> - </abstract> - </artheader> - - <sect1> - <title>Logging in and Getting Out</title> - - <para>Log in (when you see <systemitem - class=prompt>login:</systemitem>) as a user you created during - installation or as <firstterm>root</firstterm>. (Your FreeBSD - installation will already have an account for root; root can go - anywhere and do anything, including deleting essential files, so - be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the - prompt (yours may be different), with &prompt.user; indicating an ordinary - user and &prompt.root; indicating root.</para> - - <para>To log out (and get a new <systemitem - class=prompt>login:</systemitem> prompt) type</para> - - <informalexample> - <screen>&prompt.root; <userinput>exit</userinput> - </screen> - </informalexample> - - <para>as often as necessary. Yes, press <keysym>enter</keysym> - after commands, and remember that Unix is - case-sensitive—<command>exit</command>, not - <command>EXIT</command>.</para> - - <para>To shut down the machine type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -h now</userinput> - </screen> - </informalexample> - - <para>Or to reboot type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -r now</userinput> - </screen> - </informalexample> - - <para>or</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/reboot</userinput> - </screen> - </informalexample> - - <para>You can also reboot with - <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. - Give it a little time to do its work. This is equivalent to - <command>/sbin/reboot</command> in recent releases of FreeBSD - and is much, much better than hitting the reset button. You - don't want to have to reinstall this thing, do you?</para> - </sect1> - - <sect1> - <title>Adding A User with Root Privileges</title> - - <para>If you didn't create any users when you installed the system - and are thus logged in as root, you should probably create a - user now with</para> - - <informalexample> - <screen>&prompt.root; <userinput>adduser</userinput> - </screen> - </informalexample> - - <para>The first time you use adduser, it might ask for some - defaults to save. You might want to make the default shell csh - instead of sh, if it suggests sh as the default. Otherwise just - press enter to accept each default. These defaults are saved in - <filename>/etc/adduser.conf</filename>, an editable file.</para> - - <para>Suppose you create a user <emphasis>jack</emphasis> with - full name <emphasis>Jack Benimble</emphasis>. Give jack a - password if security (even kids around who might pound on the - keyboard) is an issue. When it asks you if you want to invite - jack into other groups, type <userinput>wheel</userinput></para> - - <informalexample> - <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput> - </screen> - </informalexample> - - <para>This will make it possible to log in as - <emphasis>jack</emphasis> and use the <command>su</command> - command to become root. Then you won't get scolded any more for - logging in as root.</para> - - <para>You can quit <command>adduser</command> any time by typing - <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, - and at the end you'll have a chance to approve your new user or - simply type <keycap>n</keycap> for no. You might want to create - a second new user (jill?) so that when you edit jack's login - files, you'll have a hot spare in case something goes - wrong.</para> - - <para>Once you've done this, use <command>exit</command> to get - back to a login prompt and log in as <emphasis>jack</emphasis>. - In general, it's a good idea to do as much work as possible as - an ordinary user who doesn't have the power—and - risk—of root.</para> - - <para>If you already created a user and you want the user to be - able to <command>su</command> to root, you can log in as root - and edit the file <filename>/etc/group</filename>, adding jack - to the first line (the group wheel). But first you need to - practice <command>vi</command>, the text editor--or use the - simpler text editor, <command>ee</command>, installed on recent - version of FreeBSD.</para> - - <para>To delete a user, use the <command>rmuser</command> - command.</para> - </sect1> - - <sect1> - <title>Looking Around</title> - - <para>Logged in as an ordinary user, look around and try out some - commands that will access the sources of help and information - within FreeBSD.</para> - - <para>Here are some commands and what they do:</para> - - <variablelist> - <varlistentry> - <term><command>id</command></term> - - <listitem> - <para>Tells you who you are!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>pwd</command></term> - - <listitem> - <para>Shows you where you are—the current working - directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls</command></term> - - <listitem> - <para>Lists the files in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-F</option></command></term> - - <listitem> - <para>Lists the files in the current directory with a - <literal>*</literal> after executables, a - <literal>/</literal> after directories, and an - <literal>@</literal> after symbolic links.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-l</option></command></term> - - <listitem> - <para>Lists the files in long format—size, date, - permissions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-a</option></command></term> - - <listitem> - <para>Lists hidden <quote>dot</quote> files with the others. - If you're root, the <quote>dot</quote> files show up - without the <option>-a</option> switch.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cd</command></term> - - <listitem> - <para>Changes directories. <command>cd - <parameter>..</parameter></command> backs up one level; - note the space after <command>cd</command>. <command>cd - <parameter>/usr/local</parameter></command> goes there. - <command>cd <parameter>~</parameter></command> goes to - the home directory of the person logged in—e.g., - <filename>/usr/home/jack</filename>. Try <command>cd - <parameter>/cdrom</parameter></command>, and then - <command>ls</command>, to find out if your CDROM is - mounted and working.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>view - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Lets you look at a file (named - <replaceable>filename</replaceable>) without changing it. - Try <command>view - <parameter>/etc/fstab</parameter></command>. - <command>:q</command> to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cat - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Displays <replaceable>filename</replaceable> on - screen. If it's too long and you can see only the end of - it, press <keycap>ScrollLock</keycap> and use the - <keycap>up-arrow</keycap> to move backward; you can use - <keycap>ScrollLock</keycap> with man pages too. Press - <keycap>ScrollLock</keycap> again to quit scrolling. You - might want to try <command>cat</command> on some of the - dot files in your home directory—<command>cat - <parameter>.cshrc</parameter></command>, <command>cat - <parameter>.login</parameter></command>, <command>cat - <parameter>.profile</parameter></command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You'll notice aliases in <filename>.cshrc</filename> for - some of the <command>ls</command> commands (they're very - convenient). You can create other aliases by editing - <filename>.cshrc</filename>. You can make these aliases - available to all users on the system by putting them in the - system-wide csh configuration file, - <filename>/etc/csh.cshrc</filename>.</para> - </sect1> - - <sect1> - <title>Getting Help and Information</title> - - <para>Here are some useful sources of help. - <replaceable>Text</replaceable> stands for something of your - choice that you type in—usually a command or - filename.</para> - - <variablelist> - <varlistentry> - <term><command>apropos - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Everything containing string - <replaceable>text</replaceable> in the <database>whatis - database</database>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man - <replaceable>text</replaceable></command></term> - - <listitem> - <para>The man page for <replaceable>text</replaceable>. The - major source of documentation for Un*x systems. - <command>man <parameter>ls</parameter></command> will tell - you all the ways to use the <command>ls</command> command. - Press <keycap>Enter</keycap> to move through text, - <keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> - to go back a page, - <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo> - to go forward, <keycap>q</keycap> or - <keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo> - to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>which - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you where in the user's path the command - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>locate - <replaceable>text</replaceable></command></term> - - <listitem> - <para>All the paths where the string - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whatis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you what the command - <replaceable>text</replaceable> does and its man page. - Typing <command>whatis *</command> will tell you about all - the binaries in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whereis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Finds the file <replaceable>text</replaceable>, giving - its full path.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You might want to try using <command>whatis</command> on - some common useful commands like <command>cat</command>, - <command>more</command>, <command>grep</command>, - <command>mv</command>, <command>find</command>, - <command>tar</command>, <command>chmod</command>, - <command>chown</command>, <command>date</command>, and - <command>script</command>. <command>more</command> lets you - read a page at a time as it does in DOS, e.g., <command>ls -l | - more</command> or <command>more - <replaceable>filename</replaceable></command>. The - <literal>*</literal> works as a wildcard—e.g., <command>ls - w*</command> will show you files beginning with - <literal>w</literal>.</para> - - <para>Are some of these not working very well? Both - <command>locate</command> and <command>whatis</command> depend - on a database that's rebuilt weekly. If your machine isn't - going to be left on over the weekend (and running FreeBSD), you - might want to run the commands for daily, weekly, and monthly - maintenance now and then. Run them as root and give each one - time to finish before you start the next one, for now.</para> - - <informalexample> - <screen>&prompt.root; <userinput>periodic daily</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic weekly</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic monthly</userinput> -<lineannotation>output omitted</lineannotation> - </screen> - </informalexample> - - <para>If you get tired of waiting, press - <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to - get another <firstterm>virtual console</firstterm>, and log in - again. After all, it's a multi-user, multi-tasking system. - Nevertheless these commands will probably flash messages on your - screen while they're running; you can type - <command>clear</command> at the prompt to clear the screen. - Once they've run, you might want to look at - <filename>/var/mail/root</filename> and - <filename>/var/log/messages</filename>.</para> - - <para>Running such commands is part of system - administration—and as a single user of a Unix system, - you're your own system administrator. Virtually everything you - need to be root to do is system administration. Such - responsibilities aren't covered very well even in those big fat - books on Unix, which seem to devote a lot of space to pulling - down menus in windows managers. You might want to get one of - the two leading books on systems administration, either Evi - Nemeth et.al.'s <citetitle>UNIX System Administration - Handbook</citetitle> (Prentice-Hall, 1995, ISBN - 0-13-15051-7)—the second edition with the red cover; or - Æleen Frisch's <citetitle>Essential System - Administration</citetitle> (O'Reilly & Associates, 1993, - ISBN 0-937175-80-3). I used Nemeth.</para> - </sect1> - - <sect1> - <title>Editing Text</title> - - <para>To configure your system, you need to edit text files. Most - of them will be in the <filename>/etc</filename> directory; and - you'll need to <command>su</command> to root to be able to - change them. You can use the easy <command>ee</command>, but in - the long run the text editor <command>vi</command> is worth - learning. There's an excellent tutorial on vi in - <filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you - have that installed; otherwise you can get it by ftp to - <hostid>ftp.cdrom.com</hostid> in the directory - FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para> - - <para>Before you edit a file, you should probably back it up. - Suppose you want to edit <filename>/etc/rc.conf</filename>. You - could just use <command>cd /etc</command> to get to the - <filename>/etc</filename> directory and do:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp rc.conf rc.conf.orig</userinput> - </screen> - </informalexample> - - <para>This would copy <filename>rc.conf</filename> to - <filename>rc.conf.orig</filename>, and you could later copy - <filename>rc.conf.orig</filename> to - <filename>rc.conf</filename> to recover the original. But even - better would be moving (renaming) and then copying back:</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf rc.conf.orig</userinput> -&prompt.root; <userinput>cp rc.conf.orig rc.conf</userinput> - </screen> - </informalexample> - - <para>because the <command>mv</command> command preserves the - original date and owner of the file. You can now edit - <filename>rc.conf</filename>. If you want the original back, - you'd then <userinput>mv rc.conf rc.conf.myedit</userinput> - (assuming you want to preserve your edited version) and - then</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf.orig rc.conf</userinput></screen> - </informalexample> - - <para>to put things back the way they were.</para> - - <para>To edit a file, type</para> - - <informalexample> - <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput> - </screen> - </informalexample> - - <para>Move through the text with the arrow keys. - <keycap>Esc</keycap> (the escape key) puts <command>vi</command> - in command mode. Here are some commands:</para> - - <variablelist> - <varlistentry> - <term><command>x</command></term> - - <listitem> - <para>delete letter the cursor is on</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>dd</command></term> - - <listitem> - <para>delete the entire line (even if it wraps on the - screen)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>i</command></term> - - <listitem> - <para>insert text at the cursor</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>a</command></term> - - <listitem> - <para>insert text after the cursor</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once you type <command>i</command> or <command>a</command>, - you can enter text. <command>Esc</command> puts you back in - command mode where you can type</para> - - <variablelist> - <varlistentry> - <term><command>:w</command></term> - - <listitem> - <para>to write your changes to disk and continue - editing</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:wq</command></term> - - <listitem> - <para>to write and quit</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:q!</command></term> - - <listitem> - <para>to quit without saving changes</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>/<replaceable>text</replaceable></command></term> - - <listitem> - <para>to move the cursor to <replaceable>text</replaceable>; - <command>/<keycap>Enter</keycap></command> (the enter key) - to find the next instance of - <replaceable>text</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>G</command></term> - - <listitem> - <para>to go to the end of the file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command><replaceable>n</replaceable>G</command></term> - - <listitem> - <para>to go to line <replaceable>n</replaceable> in the - file, where <replaceable>n</replaceable> is a - number</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo></term> - - <listitem> - <para>to redraw the screen</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> and - <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo></term> - - <listitem> - <para>go back and forward a screen, as they do with - <command>more</command> and <command>view</command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Practice with <command>vi</command> in your home directory by - creating a new file with <command>vi <replaceable>filename</replaceable></command> - and adding and deleting text, saving the file, and calling it up - again. <command>vi</command> delivers some surprises because it's - really quite complex, and sometimes you'll inadvertently issue a - command that will do something you don't expect. (Some people - actually like <command>vi</command>—it's more powerful than DOS - EDIT—find out about the <command>:r</command> command.) Use - <keycap>Esc</keycap> one or more times to be sure you're in command - mode and proceed from there when it gives you trouble, save - often with <command>:w</command>, and use <command>:q!</command> to get out - and start over (from your last <command>:w</command>) when you need - to.</para> - - <para>Now you can <command>cd</command> to <filename>/etc</filename>, - <command>su</command> to root, use <command>vi</command> to edit the file - <filename>/etc/group</filename>, and add a user to wheel so the - user has root privileges. Just add a comma and the user's login - name to the end of the first line in the file, press - <keycap>Esc</keycap>, and use <command>:wq</command> to write the file to - disk and quit. Instantly effective. (You didn't put a space - after the comma, did you?)</para> - </sect1> - - <sect1> - <title>Printing Files from DOS</title> - - <para>At this point you probably don't have the printer working, - so here's a way to create a file from a man page, move it to a - floppy, and then print it from DOS. Suppose you want to read - carefully about changing permissions on files (pretty - important). You can use the command man chmod to read about it. - The command</para> - - <informalexample> - <screen>&prompt.user; <userinput>man chmod | col -b > chmod.txt</> - </screen> - </informalexample> - - <para>will remove formatting codes and send the man page to the - <filename>chmod.txt</filename> file instead of showing it on - your screen. Now put a dos-formatted diskette in your floppy - drive a, <command>su</command> to root, and type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</> - </screen> - </informalexample> - - <para>to mount the floppy drive on - <filename>/mnt</filename>.</para> - - <para>Now (you no longer need to be root, and you can type - <command>exit</command> to get back to being user jack) you can go to - the directory where you created chmod.txt and copy the file to - the floppy with:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cp chmod.txt /mnt</> - </screen> - </informalexample> - - <para>and use <command>ls /mnt</command> to get a directory - listing of <filename>/mnt</filename>, which should show the file - <filename>chmod.txt</filename>.</para> - - <para>You might especially want to make a file from - <filename>/sbin/dmesg</filename> by typing</para> - - <informalexample> - <screen>&prompt.user; <userinput>/sbin/dmesg > dmesg.txt</> - </screen> - </informalexample> - - <para>and copying <filename>dmesg.txt</filename> to the floppy. - <command>/sbin/dmesg</command> is the boot log record, and it's - useful to understand it because it shows what FreeBSD found when - it booted up. If you ask questions on - <email>freebsd-questions@FreeBSD.org</email> or on a USENET - group—like <quote>FreeBSD isn't finding my tape drive, - what do I do?</quote>—people will want to know what - <command>dmesg</command> has to say.</para> - - <para>You can now dismount the floppy drive (as root) to get the - disk out with</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/umount /mnt</> - </screen> - </informalexample> - - <para>and reboot to go to DOS. Copy these files to a DOS - directory, call them up with DOS EDIT, Windows Notepad or - Wordpad, or a word processor, make a minor change so the file - has to be saved, and print as you normally would from DOS or - Windows. Hope it works! man pages come out best if printed - with the dos <command>print</command> command. (Copying files from - FreeBSD to a mounted dos partition is in some cases still a - little risky.)</para> - - <para>Getting the printer printing from FreeBSD involves creating - an appropriate entry in <filename>/etc/printcap</filename> and - creating a matching spool directory in - <filename>/var/spool/output</filename>. If your printer is on - <hardware>lpt0</hardware> (what dos calls <hardware>LPT1</hardware>), you may - only need to go to <filename>/var/spool/output</filename> and - (as root) create the directory <filename>lpd</filename> by typing: - <command> mkdir lpd</command>, if it doesn't already exist. - Then the printer should respond if it's turned on when the - system is booted, and lp or lpr should send a file to the - printer. Whether or not the file actually prints depends on - configuring it, which is covered in the <ulink - URL="../../handbook/handbook.html">FreeBSD handbook.</ulink></para> - </sect1> - - <sect1> - <title>Other Useful Commands</title> - - <variablelist> - <varlistentry> - <term><command>df</command></term> - - <listitem> - <para>shows file space and mounted systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ps aux</command></term> - - <listitem> - <para>shows processes running. <command>ps ax</command> is a - narrower form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm <replaceable>filename</replaceable></command></term> - - <listitem> - <para>remove <replaceable>filename</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm -R <replaceable>dir</replaceable></command></term> - - <listitem> - <para>removes a directory <replaceable>dir</replaceable> and all - subdirectories—careful!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls -R</command></term> - - <listitem> - <para>lists files in the current directory and all - subdirectories; I used a variant, <command>ls -AFR > - where.txt</command>, to get a list of all the files in - <filename>/</filename> and (separately) - <filename>/usr</filename> before I found better ways to - find files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>passwd</command></term> - - <listitem> - <para>to change user's password (or root's password)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man hier</command></term> - - <listitem> - <para>man page on the Unix file system</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Use <command>find</command> to locate filename in - <filename>/usr</filename> or any of its subdirectories - with</para> - - <informalexample> - <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</>"</> - </screen> - </informalexample> - - <para>You can use <literal>*</literal> as a wildcard in - <parameter>"<replaceable>filename</replaceable>"</parameter> (which should be in - quotes). If you tell find to search in <filename>/</filename> - instead of <filename>/usr</filename> it will look for the - file(s) on all mounted file systems, including the CDROM and the - dos partition.</para> - - <para>An excellent book that explains Unix commands and utilities - is Abrahams & Larson, <citetitle>Unix for the - Impatient</citetitle> (2nd ed., Addison-Wesley, 1996). - There's also a lot of Unix information on the Internet. Try the - <ulink URL="http://www.eecs.nwu.edu/unix.html">Unix Reference - Desk</ulink>.</para> - </sect1> - - <sect1> - <title>Next Steps</title> - - <para>You should now have the tools you need to get around and - edit files, so you can get everything up and running. There is - a great deal of information in the FreeBSD handbook (which is - probably on your hard drive) and <ulink - URL="http://www.FreeBSD.org/">FreeBSD's web site</ulink>. A - wide variety of packages and ports are on the CDROM as well - as the web site. The handbook tells you more about how to use - them (get the package if it exists, with <command>pkg_add - /cdrom/packages/All/<replaceable>packagename</replaceable></command>, where - <replaceable>packagename</replaceable> is the filename of the - package). The cdrom has lists of the packages and ports with - brief descriptions in <filename>cdrom/packages/index</filename>, - <filename>cdrom/packages/index.txt</filename>, and - <filename>cdrom/ports/index</filename>, with fuller descriptions - in <filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the - <literal>*</literal>s represent subdirectories of kinds of - programs and program names respectively.</para> - - <para>If you find the handbook too sophisticated (what with - <command>lndir</command> and all) on installing ports from the cdrom, - here's what usually works:</para> - - <para>Find the port you want, say <command>kermit</command>. There will - be a directory for it on the cdrom. Copy the subdirectory to - <filename>/usr/local</filename> (a good place for software you - add that should be available to all users) with:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</> - </screen> - </informalexample> - - <para>This should result in a - <filename>/usr/local/kermit</filename> subdirectory that has all - the files that the <command>kermit</command> subdirectory on the - CDROM has.</para> - - <para>Next, create the directory - <filename>/usr/ports/distfiles</filename> if it doesn't already - exist using <command>mkdir</command>. Now check check - <filename>/cdrom/ports/distfiles</filename> for a file with a - name that indicates it's the port you want. Copy that file to - <filename>/usr/ports/distfiles</filename>; in recent versions - you can skip this step, as FreeBSD will do it for you. In the - case of <command>kermit</command>, there is no distfile.</para> - - <para>Then <command>cd</command> to the subdirectory of - <filename>/usr/local/kermit</filename> that has the file - <filename>Makefile</filename>. Type</para> - - <informalexample> - <screen>&prompt.root; <userinput>make all install</> - </screen> - </informalexample> - - <para>During this process the port will ftp to get any compressed - files it needs that it didn't find on the cdrom or in - <filename>/usr/ports/distfiles</filename>. If you don't have - your network running yet and there was no file for the port in - <filename>/cdrom/ports/distfiles</filename>, you will have to - get the distfile using another machine and copy it to - <filename>/usr/ports/distfiles</filename> from a floppy or your - dos partition. Read <filename>Makefile</filename> (with <command>cat</command> - or <command>more</command> or <command>view</command>) to find out where to go - (the master distribution site) to get the file and what its name - is. Its name will be truncated when downloaded to DOS, and - after you get it into <filename>/usr/ports/distfiles</filename> - you'll have to rename it (with the <command>mv</command> command) to - its original name so it can be found. (Use binary file - transfers!) Then go back to - <filename>/usr/local/kermit</filename>, find the directory with - <filename>Makefile</filename>, and type <command>make all - install</command>.</para> - - <para>The other thing that happens when installing ports or - packages is that some other program is needed. If the - installation stops with a message <errorname>can't find - unzip</errorname> or whatever, you might need to install the - package or port for unzip before you continue.</para> - - <para>Once it's installed type <command>rehash</command> to make FreeBSD - reread the files in the path so it knows what's there. (If you - get a lot of <errorname>path not found</errorname> messages when you use - <command>whereis</command> or which, you might want to make additions - to the list of directories in the path statement in - <filename>.cshrc</filename> in your home directory. The path - statement in Unix does the same kind of work it does in DOS, - except the current directory is not (by default) in the path for - security reasons; if the command you want is in the directory - you're in, you need to type <filename>./</filename> before the - command to make it work; no space after the slash.)</para> - - <para>You might want to get the most recent version of Netscape - from their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>. - (Netscape requires the X Window System.) There's now a FreeBSD - version, so look around carefully. Just use <command>gunzip - <replaceable>filename</replaceable></command> and <command>tar xvf - <replaceable>filename</replaceable></command> on it, move the binary to - <filename>/usr/local/bin</filename> or some other place binaries - are kept, <command>rehash</command>, and then put the following lines - in <filename>.cshrc</filename> in each user's home directory or - (easier) in <filename>/etc/csh.cshrc</filename>, the - system-wide csh start-up file:</para> - - <informalexample> - <programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls - </programlisting> - </informalexample> - - <para>This assumes that the file <filename>XKeysymDB</filename> and the - directory <filename>nls</filename> are in - <filename>/usr/X11R6/lib/X11</filename>; if they're not, find - them and put them there.</para> - - <para>If you originally got Netscape as a port using the CDROM (or - ftp), don't replace <filename>/usr/local/bin/netscape</filename> - with the new netscape binary; this is just a shell script that - sets up the environment variables for you. Instead rename the - new binary to <filename>netscape.bin</filename> and replace the - old binary, which is - <filename>/usr/local/netscape/netscape</filename>.</para> - </sect1> - - <sect1> - <title>Your Working Environment</title> - - <para>Your shell is the most important part of your working - environment. In DOS, the usual shell is command.com. The shell - is what interprets the commands you type on the command line, - and thus communicates with the rest of the operating system. - You can also write shell scripts, which are like DOS batch - files: a series of commands to be run without your - intervention.</para> - - <para>Two shells come installed with FreeBSD: csh and sh. csh is - good for command-line work, but scripts should be written with - sh (or bash). You can find out what shell you have by typing - <command>echo $SHELL</command>.</para> - - <para>The csh shell is okay, but tcsh does everything csh does and - more. It It allows you to recall commands with the arrow keys - and edit them. It has tab-key completion of filenames (csh uses - the escape key), and it lets you switch to the directory you - were last in with <command>cd -</command>. It's also much - easier to alter your prompt with tcsh. It makes life a lot - easier.</para> - - <para>Here are the three steps for installing a new shell:</para> - - <procedure> - <step> - <para>Install the shell as a port or a package, just as you - would any other port or package. Use - <command>rehash</command> and <command>which tcsh</command> - (assuming you're installing tcsh) to make sure it got - installed.</para> - </step> - - <step> - <para>As root, edit <filename>/etc/shells</filename>, adding a - line in the file for the new shell, in this case - /usr/local/bin/tcsh, and save the file. (Some ports may do - this for you.)</para> - </step> - - <step> - <para>Use the <command>chsh</command> command to change your - shell to tcsh permanently, or type <command>tcsh</command> - at the prompt to change your shell without logging in - again.</para> - </step> - </procedure> - - <note> - <para>It can be dangerous to change root's shell to something - other than sh or csh on early versions of FreeBSD and many - other versions of Unix; you may not have a working shell when - the system puts you into single user mode. The solution is to - use <command>su -m</command> to become root, which will give - you the tcsh as root, because the shell is part of the - environment. You can make this permanent by adding it to your - <filename>.tcshrc</filename> file as an alias with - <programlisting>alias su su -m.</programlisting></para> - </note> - - <para>When tcsh starts up, it will read the - <filename>/etc/csh.cshrc</filename> and - <filename>/etc/csh.login</filename> files, as does csh. It will - also read the <filename>.login</filename> file in your home - directory and the <filename>.cshrc</filename> file as well, - unless you provide a <filename>.tcshrc</filename> file. This - you can do by simply copying <filename>.cshrc</filename> to - <filename>.tcshrc</filename>.</para> - - <para>Now that you've installed tcsh, you can adjust your prompt. - You can find the details in the manual page for tcsh, but here - is a line to put in your <filename>.tcshrc</filename> that will - tell you how many commands you have typed, what time it is, and - what directory you are in. It also produces a - <literal>></literal> if you're an ordinary user and a - <literal>#</literal> if you're root, but tsch will do that in - any case:</para> - - <para>set prompt = "%h %t %~ %# "</para> - - <para>This should go in the same place as the existing set prompt - line if there is one, or under "if($?prompt) then" if not. - Comment out the old line; you can always switch back to it if - you prefer it. Don't forget the spaces and quotes. You can get - the <filename>.tcshrc</filename> reread by typing - <command>source .tcshrc</command>.</para> - - <para>You can get a listing of other environmental variables that - have been set by typing <command>env</command> at the prompt. - The result will show you your default editor, pager, and - terminal type, among possibly many others. A useful command if - you log in from a remote location and can't run a program - because the terminal isn't capable is <command>setenv TERM - vt100</command>.</para> - </sect1> - - <sect1> - <title>Other</title> - - <para>As root, you can dismount the CDROM with - <command>/sbin/umount /cdrom</command>, take it out of the drive, - insert another one, and mount it with - <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming - <hardware>cd0a</hardware> is the device name for your CDROM drive. The - most recent versions of FreeBSD let you mount the cdrom with - just <command>/sbin/mount /cdrom</command>.</para> - - <para>Using the live file system—the second of FreeBSD's - CDROM disks—is useful if you've got limited space. What - is on the live file system varies from release to release. You - might try playing games from the cdrom. This involves using - <command>lndir</command>, which gets installed with the X Window - System, to tell the program(s) where to find the necessary - files, because they're in the <filename>/cdrom</filename> file - system instead of in <filename>/usr</filename> and its - subdirectories, which is where they're expected to be. Read - <command>man lndir</command>.</para> - </sect1> - - <sect1> - <title>Comments Welcome</title> - - <para>If you use this guide I'd be interested in knowing where it - was unclear and what was left out that you think should be - included, and if it was helpful. My thanks to Eugene W. Stark, - professor of computer science at SUNY-Stony Brook, and John - Fieber for helpful comments.</para> - - <para>Annelise Anderson, - <email>andrsn@andrsn.stanford.edu</email></para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/programming-tools/Makefile b/en_US.ISO8859-1/articles/programming-tools/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/programming-tools/article.sgml b/en_US.ISO8859-1/articles/programming-tools/article.sgml deleted file mode 100644 index 90587c0080..0000000000 --- a/en_US.ISO8859-1/articles/programming-tools/article.sgml +++ /dev/null @@ -1,2264 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/programming-tools/article.sgml,v 1.12 2000/07/26 18:24:50 jim Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> -<article> - <artheader> - <title>A User's Guide to FreeBSD Programming Tools</title> - - <authorgroup> - <author> - <firstname>James</firstname> - - <surname>Raynard</surname> - - <affiliation> - <address> - <email>jraynard@FreeBSD.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 17, 1997</pubdate> - - <copyright> - <year>1997</year> - <holder>James Raynard</holder> - </copyright> - - <abstract> - <para>This document is an introduction to using some of the - programming tools supplied with FreeBSD, although much of it - will be applicable to many other versions of Unix. It does - <emphasis>not</emphasis> attempt to describe coding in any - detail. Most of the document assumes little or no previous - programming knowledge, although it is hoped that most - programmers will find something of value in it</para> - </abstract> - </artheader> - - <sect1> - <title>Introduction<anchor id=foo></title> - - <para>FreeBSD offers an excellent development environment. - Compilers for C, C++, and Fortran and an assembler come with the - basic system, not to mention a Perl interpreter and classic Unix - tools such as <command>sed</command> and <command>awk</command>. If that is - not enough, there are many more compilers and interpreters in - the Ports collection. FreeBSD is very compatible with standards - such as <acronym>POSIX</acronym> and <acronym>ANSI</acronym> C, as well with - its own BSD heritage, so it is possible to write applications - that will compile and run with little or no modification on a - wide range of platforms.</para> - - <para>However, all this power can be rather overwhelming at first - if you've never written programs on a Unix platform before. - This document aims to help you get up and running, without - getting too deeply into more advanced topics. The intention is - that this document should give you enough of the basics to be - able to make some sense of the documentation.</para> - - <para>Most of the document requires little or no knowledge of - programming, although it does assume a basic competence with - using Unix and a willingness to learn!</para> - </sect1> - - <sect1> - <title>Introduction to Programming</title> - - <para>A program is a set of instructions that tell the computer to - do various things; sometimes the instruction it has to perform - depends on what happened when it performed a previous - instruction. This section gives an overview of the two main - ways in which you can give these instructions, or - <quote>commands</quote> as they are usually called. One way - uses an <firstterm>interpreter</firstterm>, the other a - <firstterm>compiler</firstterm>. As human languages are too difficult for - a computer to understand in an unambiguous way, commands are - usually written in one or other languages specially designed for - the purpose.</para> - - <sect2> - <title>Interpreters</title> - - <para>With an interpreter, the language comes as an environment, - where you type in commands at a prompt and the environment - executes them for you. For more complicated programs, you can - type the commands into a file and get the interpreter to load - the file and execute the commands in it. If anything goes - wrong, many interpreters will drop you into a debugger to help - you track down the problem.</para> - - <para>The advantage of this is that you can see the results of - your commands immediately, and mistakes can be corrected - readily. The biggest disadvantage comes when you want to - share your programs with someone. They must have the same - interpreter, or you must have some way of giving it to them, - and they need to understand how to use it. Also users may not - appreciate being thrown into a debugger if they press the - wrong key! From a performance point of view, interpreters can - use up a lot of memory, and generally do not generate code as - efficiently as compilers.</para> - - <para>In my opinion, interpreted languages are the best way to - start if you have not done any programming before. This kind - of environment is typically found with languages like Lisp, - Smalltalk, Perl and Basic. It could also be argued that the - Unix shell (<command>sh</command>, <command>csh</command>) is itself an - interpreter, and many people do in fact write shell - <quote>scripts</quote> to help with various - <quote>housekeeping</quote> tasks on their machine. Indeed, part - of the original Unix philosophy was to provide lots of small - utility programs that could be linked together in shell - scripts to perform useful tasks.</para> - </sect2> - - <sect2> - <title>Interpreters available with FreeBSD</title> - - <para>Here is a list of interpreters that are available as - <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink>, with a brief discussion of some of the - more popular interpreted languages.</para> - - <para>To get one of these packages, all you need to do is to - click on the hotlink for the package, then run</para> - - <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput> - </screen> - - <para>as root. Obviously, you will need to have a fully - functional FreeBSD 2.1.0 or later system for the package to - work!</para> - - <variablelist> - <varlistentry> - <term><acronym>BASIC</acronym></term> - - <listitem> - <para>Short for Beginner's All-purpose Symbolic - Instruction Code. Developed in the 1950s for teaching - University students to program and provided with every - self-respecting personal computer in the 1980s, - <acronym>BASIC</acronym> has been the first programming - language for many programmers. It's also the foundation - for Visual Basic.</para> - - <para>The <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater - Basic Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil - Cockroft's Basic Interpreter</ulink> (formerly Rabbit - Basic) are available as FreeBSD <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Lisp</term> - - <listitem> - <para>A language that was developed in the late 1950s as - an alternative to the <quote>number-crunching</quote> - languages that were popular at the time. Instead of - being based on numbers, Lisp is based on lists; in fact - the name is short for <quote>List Processing</quote>. - Very popular in AI (Artificial Intelligence) - circles.</para> - - <para>Lisp is an extremely powerful and sophisticated - language, but can be rather large and unwieldy.</para> - - <para>FreeBSD has <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU - Common Lisp</ulink> available as a package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Perl</term> - - <listitem> - <para>Very popular with system administrators for writing - scripts; also often used on World Wide Web servers for - writing <acronym>CGI</acronym> scripts.</para> - - <para>The latest version (version 5) comes with FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Scheme</term> - - <listitem> - <para>A dialect of Lisp that is rather more compact and - cleaner than Common Lisp. Popular in Universities as it - is simple enough to teach to undergraduates as a first - language, while it has a high enough level of - abstraction to be used in research work.</para> - - <para>FreeBSD has packages of the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk - Scheme Interpreter</ulink>, the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT - Scheme Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM - Scheme Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Icon</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The - Icon Programming Language</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Logo</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian - Harvey's LOGO Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Python</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/python-1.2">The - Python Object-Oriented Programming - Language</ulink></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Compilers</title> - - <para>Compilers are rather different. First of all, you write - your code in a file (or files) using an editor. You then run - the compiler and see if it accepts your program. If it did - not compile, grit your teeth and go back to the editor; if it - did compile and gave you a program, you can run it either at a - shell command prompt or in a debugger to see if it works - properly. - - <footnote> - <para>If you run it in the shell, you may get a core - dump.</para> - </footnote></para> - - <para>Obviously, this is not quite as direct as using an - interpreter. However it allows you to do a lot of things - which are very difficult or even impossible with an - interpreter, such as writing code which interacts closely with - the operating system—or even writing your own operating - system! It's also useful if you need to write very efficient - code, as the compiler can take its time and optimise the code, - which would not be acceptable in an interpreter. And - distributing a program written for a compiler is usually more - straightforward than one written for an interpreter—you - can just give them a copy of the executable, assuming they - have the same operating system as you.</para> - - <para>Compiled languages include Pascal, C and C++. C and C++ - are rather unforgiving languages, and best suited to more - experienced programmers; Pascal, on the other hand, was - designed as an educational language, and is quite a good - language to start with. Unfortunately, FreeBSD doesn't have - any Pascal support, except for a Pascal-to-C converter in the - ports.</para> - - <para>As the edit-compile-run-debug cycle is rather tedious when - using separate programs, many commercial compiler makers have - produced Integrated Development Environments - (<acronym>IDE</acronym>s for short). FreeBSD does not have an - <acronym>IDE</acronym> as such; however it is possible to use Emacs - for this purpose. This is discussed in <xref - linkend="emacs">.</para> - </sect2> - </sect1> - - <sect1> - <title>Compiling with <command>cc</command></title> - - <para>This section deals only with the GNU compiler for C and C++, - since that comes with the base FreeBSD system. It can be - invoked by either <command>cc</command> or <command>gcc</command>. The - details of producing a program with an interpreter vary - considerably between interpreters, and are usually well covered - in the documentation and on-line help for the - interpreter.</para> - - <para>Once you've written your masterpiece, the next step is to - convert it into something that will (hopefully!) run on FreeBSD. - This usually involves several steps, each of which is done by a - separate program.</para> - - <procedure> - <step> - <para>Pre-process your source code to remove comments and do - other tricks like expanding macros in C.</para> - </step> - - <step> - <para>Check the syntax of your code to see if you have obeyed - the rules of the language. If you have not, it will - complain!</para> - </step> - - <step> - <para>Convert the source code into assembly - language—this is very close to machine code, but still - understandable by humans. Allegedly. - - <footnote> - <para>To be strictly accurate, <command>cc</command> converts the - source code into its own, machine-independent - <firstterm>p-code</firstterm> instead of assembly language at - this stage.</para> - </footnote></para> - </step> - - <step> - <para>Convert the assembly language into machine - code—yep, we are talking bits and bytes, ones and - zeros here.</para> - </step> - - <step> - <para>Check that you have used things like functions and - global variables in a consistent way. For example, if you - have called a non-existent function, it will - complain.</para> - </step> - - <step> - <para>If you are trying to produce an executable from several - source code files, work out how to fit them all - together.</para> - </step> - - <step> - <para>Work out how to produce something that the system's - run-time loader will be able to load into memory and - run.</para> - </step> - - <step> - <para>Finally, write the executable on the file system.</para> - </step> - </procedure> - - <para>The word <firstterm>compiling</firstterm> is often used to refer to - just steps 1 to 4—the others are referred to as - <firstterm>linking</firstterm>. Sometimes step 1 is referred to as - <firstterm>pre-processing</firstterm> and steps 3-4 as - <firstterm>assembling</firstterm>.</para> - - <para>Fortunately, almost all this detail is hidden from you, as - <command>cc</command> is a front end that manages calling all these - programs with the right arguments for you; simply typing</para> - - <screen>&prompt.user; <userinput>cc foobar.c</> - </screen> - - <para>will cause <filename>foobar.c</filename> to be compiled by all the - steps above. If you have more than one file to compile, just do - something like</para> - - <screen>&prompt.user; <userinput>cc foo.c bar.c</> - </screen> - - <para>Note that the syntax checking is just that—checking - the syntax. It will not check for any logical mistakes you may - have made, like putting the program into an infinite loop, or - using a bubble sort when you meant to use a binary - sort. - - <footnote> - <para>In case you didn't know, a binary sort is an efficient - way of sorting things into order and a bubble sort - isn't.</para> - </footnote></para> - - <para>There are lots and lots of options for <command>cc</command>, which - are all in the man page. Here are a few of the most important - ones, with examples of how to use them.</para> - - <variablelist> - <varlistentry> - <term><option>-o <replaceable>filename</replaceable></option></term> - - <listitem> - <para>The output name of the file. If you do not use this - option, <command>cc</command> will produce an executable called - <filename>a.out</filename>. - - <footnote> - <para>The reasons for this are buried in the mists of - history.</para> - </footnote></para> - - <informalexample> - <screen>&prompt.user; <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -&prompt.user; <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></> - </screen> - </informalexample> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Just compile the file, do not link it. Useful for toy - programs where you just want to check the syntax, or if - you are using a <filename>Makefile</filename>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -c foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an <firstterm>object file</firstterm> (not an - executable) called <filename>foobar.o</filename>. This - can be linked together with other object files into an - executable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Create a debug version of the executable. This makes - the compiler put information into the executable about - which line of which source file corresponds to which - function call. A debugger can use this information to show - the source code as you step through the program, which is - <emphasis>very</emphasis> useful; the disadvantage is that - all this extra information makes the program much bigger. - Normally, you compile with <option>-g</option> while you - are developing a program and then compile a <quote>release - version</quote> without <option>-g</option> when you're - satisfied it works properly.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -g foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce a debug version of the - program. - - <footnote> - <para>Note, we didn't use the <option>-o</option> flag - to specify the executable name, so we will get an - executable called <filename>a.out</filename>. - Producing a debug version called - <filename>foobar</filename> is left as an exercise for - the reader!</para> - </footnote></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-O</option></term> - - <listitem> - <para>Create an optimised version of the executable. The - compiler performs various clever tricks to try and produce - an executable that runs faster than normal. You can add a - number after the <option>-O</option> to specify a higher - level of optimisation, but this often exposes bugs in the - compiler's optimiser. For instance, the version of - <command>cc</command> that comes with the 2.1.0 release of - FreeBSD is known to produce bad code with the - <option>-O2</option> option in some circumstances.</para> - - <para>Optimisation is usually only turned on when compiling - a release version.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an optimised version of - <filename>foobar</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following three flags will force <command>cc</command> - to check that your code complies to the relevant international - standard, often referred to as the <acronym>ANSI</acronym> - standard, though strictly speaking it is an - <acronym>ISO</acronym> standard.</para> - - <variablelist> - <varlistentry> - <term><option>-Wall</option></term> - - <listitem> - <para>Enable all the warnings which the authors of - <command>cc</command> believe are worthwhile. Despite the - name, it will not enable all the warnings - <command>cc</command> is capable of.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ansi</option></term> - - <listitem> - <para>Turn off most, but not all, of the - non-<acronym>ANSI</acronym> C features provided by - <command>cc</command>. Despite the name, it does not - guarantee strictly that your code will comply to the - standard.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-pedantic</option></term> - - <listitem> - <para>Turn off <emphasis>all</emphasis> - <command>cc</command>'s non-<acronym>ANSI</acronym> C - features.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Without these flags, <command>cc</command> will allow you to - use some of its non-standard extensions to the standard. Some - of these are very useful, but will not work with other - compilers—in fact, one of the main aims of the standard is - to allow people to write code that will work with any compiler - on any system. This is known as <firstterm>portable - code</firstterm>.</para> - - <para>Generally, you should try to make your code as portable as - possible, as otherwise you may have to completely re-write the - program later to get it to work somewhere else—and who - knows what you may be using in a few years time?</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an executable <filename>foobar</filename> - after checking <filename>foobar.c</filename> for standard - compliance.</para> - - <variablelist> - <varlistentry> - <term><option>-l<replaceable>library</replaceable></option></term> - - <listitem> - <para>Specify a function library to be used during when - linking.</para> - - <para>The most common example of this is when compiling a - program that uses some of the mathematical functions in C. - Unlike most other platforms, these are in a separate - library from the standard C one and you have to tell the - compiler to add it.</para> - - <para>The rule is that if the library is called - <filename>lib<replaceable>something</replaceable>.a</filename>, - you give <command>cc</command> the argument - <option>-l<replaceable>something</replaceable></option>. - For example, the math library is - <filename>libm.a</filename>, so you give - <command>cc</command> the argument <option>-lm</option>. - A common <quote>gotcha</quote> with the math library is - that it has to be the last library on the command - line.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - - <para>This will link the math library functions into - <filename>foobar</filename>.</para> - - <para>If you are compiling C++ code, you need to add - <option>-lg++</option>, or <option>-lstdc++</option> if - you are using FreeBSD 2.2 or later, to the command line - argument to link the C++ library functions. - Alternatively, you can run <command>c++</command> instead - of <command>cc</command>, which does this for you. - <command>c++</command> can also be invoked as - <command>g++</command> on FreeBSD.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -&prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput> - </screen> - </informalexample> - - <para>Each of these will both produce an executable - <filename>foobar</filename> from the C++ source file - <filename>foobar.cc</filename>. Note that, on Unix - systems, C++ source files traditionally end in - <filename>.C</filename>, <filename>.cxx</filename> or - <filename>.cc</filename>, rather than the - MS-DOS style - <filename>.cpp</filename> (which was already used for - something else). <command>gcc</command> used to rely on - this to work out what kind of compiler to use on the - source file; however, this restriction no longer applies, - so you may now call your C++ files - <filename>.cpp</filename> with impunity!</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Common <command>cc</command> Queries and Problems</title> - - <qandaset> - <qandaentry> - <question> - <para>I am trying to write a program which uses the - <function>sin()</function> function and I get an error - like this. What does it mean?</para> - - <informalexample> - <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - </screen> - </informalexample> - </question> - - <answer> - <para>When using mathematical functions like - <function>sin()</function>, you have to tell - <command>cc</command> to link in the math library, like - so:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>All right, I wrote this simple program to practice - using <option>-lm</option>. All it does is raise 2.1 to - the power of 6.</para> - - <informalexample> - <programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - </programlisting> - </informalexample> - - <para>and I compiled it as:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc temp.c -lm</userinput> - </screen> - </informalexample> - - <para>like you said I should, but I get this when I run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000 - </screen> - </informalexample> - - <para>This is <emphasis>not</emphasis> the right answer! - What is going on?</para> - </question> - - <answer> - <para>When the compiler sees you call a function, it - checks if it has already seen a prototype for it. If it - has not, it assumes the function returns an - <type>int</type>, which is definitely not what you want - here.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>So how do I fix this?</para> - </question> - - <answer> - <para>The prototypes for the mathematical functions are in - <filename>math.h</filename>. If you include this file, - the compiler will be able to find the prototype and it - will stop doing strange things to your - calculation!</para> - - <informalexample> - <programlisting>#include <math.h> -#include <stdio.h> - -int main() { -... - </programlisting> - </informalexample> - - <para>After recompiling it as you did before, run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121 - </screen> - </informalexample> - - <para>If you are using any of the mathematical functions, - <emphasis>always</emphasis> include - <filename>math.h</filename> and remember to link in the - math library.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled a file called - <filename>foobar.c</filename> and I cannot find an - executable called <filename>foobar</filename>. Where's - it gone?</para> - </question> - - <answer> - <para>Remember, <command>cc</command> will call the - executable <filename>a.out</filename> unless you tell it - differently. Use the - <option>-o <replaceable>filename</replaceable></option> - option:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, I have an executable called - <filename>foobar</filename>, I can see it when I run - <command>ls</command>, but when I type in - <command>foobar</command> at the command prompt it tells - me there is no such file. Why can it not find - it?</para> - </question> - - <answer> - <para>Unlike MS-DOS, Unix does not - look in the current directory when it is trying to find - out which executable you want it to run, unless you tell - it to. Either type <command>./foobar</command>, which - means <quote>run the file called - <filename>foobar</filename> in the current - directory</quote>, or change your <systemitem - class=environvar>PATH</systemitem> environment - variable so that it looks something like</para> - - <informalexample> - <screen>bin:/usr/bin:/usr/local/bin:. - </screen> - </informalexample> - - <para>The dot at the end means <quote>look in the current - directory if it is not in any of the - others</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I called my executable <filename>test</filename>, - but nothing happens when I run it. What is going - on?</para> - </question> - - <answer> - <para>Most Unix systems have a program called - <command>test</command> in <filename>/usr/bin</filename> - and the shell is picking that one up before it gets to - checking the current directory. Either type:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./test</userinput> - </screen> - </informalexample> - - <para>or choose a better name for your program!</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled my program and it seemed to run all right - at first, then there was an error and it said something - about <errorname>core dumped</errorname>. What does that - mean?</para> - </question> - - <answer> - <para>The name <firstterm>core dump</firstterm> dates back - to the very early days of Unix, when the machines used - core memory for storing data. Basically, if the program - failed under certain conditions, the system would write - the contents of core memory to disk in a file called - <filename>core</filename>, which the programmer could - then pore over to find out what went wrong.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Fascinating stuff, but what I am supposed to do - now?</para> - </question> - - <answer> - <para>Use <command>gdb</command> to analyse the core (see - <xref linkend="debugging">).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When my program dumped core, it said something about - a <errorname>segmentation fault</errorname>. What's - that?</para> - </question> - - <answer> - <para>This basically means that your program tried to - perform some sort of illegal operation on memory; Unix - is designed to protect the operating system and other - programs from rogue programs.</para> - - <para>Common causes for this are:</para> - - <itemizedlist> - <listitem> - <para>Trying to write to a <symbol>NULL</symbol> - pointer, eg</para> - - <programlisting>char *foo = NULL; -strcpy(foo, "bang!"); - </programlisting> - </listitem> - - <listitem> - <para>Using a pointer that hasn't been initialised, - eg</para> - - <programlisting>char *foo; -strcpy(foo, "bang!"); - </programlisting> - - <para>The pointer will have some random value that, - with luck, will point into an area of memory that - isn't available to your program and the kernel will - kill your program before it can do any damage. If - you're unlucky, it'll point somewhere inside your - own program and corrupt one of your data structures, - causing the program to fail mysteriously.</para> - </listitem> - - <listitem> - <para>Trying to access past the end of an array, - eg</para> - - <programlisting>int bar[20]; -bar[27] = 6; - </programlisting> - </listitem> - - <listitem> - <para>Trying to store something in read-only memory, - eg</para> - - <programlisting>char *foo = "My string"; -strcpy(foo, "bang!"); - </programlisting> - - <para>Unix compilers often put string literals like - <literal>"My string"</literal> into read-only areas - of memory.</para> - </listitem> - - <listitem> - <para>Doing naughty things with - <function>malloc()</function> and - <function>free()</function>, eg</para> - - <programlisting>char bar[80]; -free(bar); - </programlisting> - - <para>or</para> - - <programlisting>char *foo = malloc(27); -free(foo); -free(foo); - </programlisting> - </listitem> - </itemizedlist> - - <para>Making one of these mistakes will not always lead to - an error, but they are always bad practice. Some - systems and compilers are more tolerant than others, - which is why programs that ran well on one system can - crash when you try them on an another.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Sometimes when I get a core dump it says - <errorname>bus error</errorname>. It says in my Unix - book that this means a hardware problem, but the - computer still seems to be working. Is this - true?</para> - </question> - - <answer> - <para>No, fortunately not (unless of course you really do - have a hardware problem…). This is usually - another way of saying that you accessed memory in a way - you shouldn't have.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>This dumping core business sounds as though it could - be quite useful, if I can make it happen when I want to. - Can I do this, or do I have to wait until there's an - error?</para> - </question> - - <answer> - <para>Yes, just go to another console or xterm, do</para> - - <screen>&prompt.user; <userinput>ps</userinput> - </screen> - - <para>to find out the process ID of your program, and - do</para> - - <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput> - </screen> - - <para>where - <parameter><replaceable>pid</replaceable></parameter> is - the process ID you looked up.</para> - - <para>This is useful if your program has got stuck in an - infinite loop, for instance. If your program happens to - trap <symbol>SIGABRT</symbol>, there are several other - signals which have a similar effect.</para> - </answer> - </qandaentry> - </qandaset> - </sect2> - </sect1> - - <sect1> - <title>Make</title> - - <sect2> - <title>What is <command>make</command>?</title> - - <para>When you're working on a simple program with only one or - two source files, typing in</para> - - <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput> - </screen> - - <para>is not too bad, but it quickly becomes very tedious when - there are several files—and it can take a while to - compile, too.</para> - - <para>One way to get around this is to use object files and only - recompile the source file if the source code has changed. So - we could have something like:</para> - - <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip - </screen> - - <para>if we'd changed <filename>file37.c</filename>, but not any - of the others, since the last time we compiled. This may - speed up the compilation quite a bit, but doesn't solve the - typing problem.</para> - - <para>Or we could write a shell script to solve the typing - problem, but it would have to re-compile everything, making it - very inefficient on a large project.</para> - - <para>What happens if we have hundreds of source files lying - about? What if we're working in a team with other people who - forget to tell us when they've changed one of their source - files that we use?</para> - - <para>Perhaps we could put the two solutions together and write - something like a shell script that would contain some kind of - magic rule saying when a source file needs compiling. Now all - we need now is a program that can understand these rules, as - it's a bit too complicated for the shell.</para> - - <para>This program is called <command>make</command>. It reads - in a file, called a <firstterm>makefile</firstterm>, that - tells it how different files depend on each other, and works - out which files need to be re-compiled and which ones don't. - For example, a rule could say something like <quote>if - <filename>fromboz.o</filename> is older than - <filename>fromboz.c</filename>, that means someone must have - changed <filename>fromboz.c</filename>, so it needs to be - re-compiled.</quote> The makefile also has rules telling - make <emphasis>how</emphasis> to re-compile the source file, - making it a much more powerful tool.</para> - - <para>Makefiles are typically kept in the same directory as the - source they apply to, and can be called - <filename>makefile</filename>, <filename>Makefile</filename> - or <filename>MAKEFILE</filename>. Most programmers use the - name <filename>Makefile</filename>, as this puts it near the - top of a directory listing, where it can easily be - seen. - - <footnote> - <para>They don't use the <filename>MAKEFILE</filename> form - as block capitals are often used for documentation files - like <filename>README</filename>.</para> - </footnote></para> - </sect2> - - <sect2> - <title>Example of using <command>make</command></title> - - <para>Here's a very simple make file:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - </programlisting> - - <para>It consists of two lines, a dependency line and a creation - line.</para> - - <para>The dependency line here consists of the name of the - program (known as the <firstterm>target</firstterm>), followed - by a colon, then whitespace, then the name of the source file. - When <command>make</command> reads this line, it looks to see - if <filename>foo</filename> exists; if it exists, it compares - the time <filename>foo</filename> was last modified to the - time <filename>foo.c</filename> was last modified. If - <filename>foo</filename> does not exist, or is older than - <filename>foo.c</filename>, it then looks at the creation line - to find out what to do. In other words, this is the rule for - working out when <filename>foo.c</filename> needs to be - re-compiled.</para> - - <para>The creation line starts with a <token>tab</token> (press - the <keycap>tab</keycap> key) and then the command you would - type to create <filename>foo</filename> if you were doing it - at a command prompt. If <filename>foo</filename> is out of - date, or does not exist, <command>make</command> then executes - this command to create it. In other words, this is the rule - which tells make how to re-compile - <filename>foo.c</filename>.</para> - - <para>So, when you type <userinput>make</userinput>, it will - make sure that <filename>foo</filename> is up to date with - respect to your latest changes to <filename>foo.c</filename>. - This principle can be extended to - <filename>Makefile</filename>s with hundreds of - targets—in fact, on FreeBSD, it is possible to compile - the entire operating system just by typing <userinput>make - world</userinput> in the appropriate directory!</para> - - <para>Another useful property of makefiles is that the targets - don't have to be programs. For instance, we could have a make - file that looks like this:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - </programlisting> - - <para>We can tell make which target we want to make by - typing:</para> - - <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput> - </screen> - - <para><command>make</command> will then only look at that target - and ignore any others. For example, if we type - <userinput>make foo</userinput> with the makefile above, make - will ignore the <action>install</action> target.</para> - - <para>If we just type <userinput>make</userinput> on its own, - make will always look at the first target and then stop - without looking at any others. So if we typed - <userinput>make</userinput> here, it will just go to the - <action>foo</action> target, re-compile - <filename>foo</filename> if necessary, and then stop without - going on to the <action>install</action> target.</para> - - <para>Notice that the <action>install</action> target doesn't - actually depend on anything! This means that the command on - the following line is always executed when we try to make that - target by typing <userinput>make install</userinput>. In this - case, it will copy <filename>foo</filename> into the user's - home directory. This is often used by application makefiles, - so that the application can be installed in the correct - directory when it has been correctly compiled.</para> - - <para>This is a slightly confusing subject to try and explain. - If you don't quite understand how <command>make</command> - works, the best thing to do is to write a simple program like - <quote>hello world</quote> and a make file like the one above - and experiment. Then progress to using more than one source - file, or having the source file include a header file. The - <command>touch</command> command is very useful here—it - changes the date on a file without you having to edit - it.</para> - </sect2> - - <sect2> - <title>FreeBSD Makefiles</title> - - <para>Makefiles can be rather complicated to write. Fortunately, - BSD-based systems like FreeBSD come with some very powerful - ones as part of the system. One very good example of this is - the FreeBSD ports system. Here's the essential part of a - typical ports <filename>Makefile</filename>:</para> - - <programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - </programlisting> - - <para>Now, if we go to the directory for this port and type - <userinput>make</userinput>, the following happens:</para> - - <procedure> - <step> - <para>A check is made to see if the source code for this - port is already on the system.</para> - </step> - - <step> - <para>If it isn't, an FTP connection to the URL in - <symbol>MASTER_SITES</symbol> is set up to download the - source.</para> - </step> - - <step> - <para>The checksum for the source is calculated and compared - it with one for a known, good, copy of the source. This - is to make sure that the source was not corrupted while in - transit.</para> - </step> - - <step> - <para>Any changes required to make the source work on - FreeBSD are applied—this is known as - <firstterm>patching</firstterm>.</para> - </step> - - <step> - <para>Any special configuration needed for the source is - done. (Many Unix program distributions try to work out - which version of Unix they are being compiled on and which - optional Unix features are present—this is where - they are given the information in the FreeBSD ports - scenario).</para> - </step> - - <step> - <para>The source code for the program is compiled. In - effect, we change to the directory where the source was - unpacked and do <command>make</command>—the - program's own make file has the necessary information to - build the program.</para> - </step> - - <step> - <para>We now have a compiled version of the program. If we - wish, we can test it now; when we feel confident about the - program, we can type <userinput>make install</userinput>. - This will cause the program and any supporting files it - needs to be copied into the correct location; an entry is - also made into a <database>package database</database>, so - that the port can easily be uninstalled later if we change - our mind about it.</para> - </step> - </procedure> - - <para>Now I think you'll agree that's rather impressive for a - four line script!</para> - - <para>The secret lies in the last line, which tells - <command>make</command> to look in the system makefile called - <filename>bsd.port.mk</filename>. It's easy to overlook this - line, but this is where all the clever stuff comes - from—someone has written a makefile that tells - <command>make</command> to do all the things above (plus a - couple of other things I didn't mention, including handling - any errors that may occur) and anyone can get access to that - just by putting a single line in their own make file!</para> - - <para>If you want to have a look at these system makefiles, - they're in <filename>/usr/share/mk</filename>, but it's - probably best to wait until you've had a bit of practice with - makefiles, as they are very complicated (and if you do look at - them, make sure you have a flask of strong coffee - handy!)</para> - </sect2> - - <sect2> - <title>More advanced uses of <command>make</command></title> - - <para><command>Make</command> is a very powerful tool, and can - do much more than the simple example above shows. - Unfortunately, there are several different versions of - <command>make</command>, and they all differ considerably. - The best way to learn what they can do is probably to read the - documentation—hopefully this introduction will have - given you a base from which you can do this.</para> - - <para>The version of make that comes with FreeBSD is the - <application>Berkeley make</application>; there is a tutorial - for it in <filename>/usr/share/doc/psd/12.make</filename>. To - view it, do</para> - - <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput> - </screen> - - <para>in that directory.</para> - - <para>Many applications in the ports use <application>GNU - make</application>, which has a very good set of - <quote>info</quote> pages. If you have installed any of these - ports, <application>GNU make</application> will automatically - have been installed as <command>gmake</command>. It's also - available as a port and package in its own right.</para> - - <para>To view the info pages for <application>GNU - make</application>, you will have to edit the - <filename>dir</filename> file in the - <filename>/usr/local/info</filename> directory to add an entry - for it. This involves adding a line like</para> - - <programlisting> * Make: (make). The GNU Make utility. - </programlisting> - - <para>to the file. Once you have done this, you can type - <userinput>info</userinput> and then select - <guimenuitem>make</guimenuitem> from the menu (or in - <application>Emacs</application>, do <userinput>C-h - i</userinput>).</para> - </sect2> - </sect1> - - <sect1 id="debugging"> - <title>Debugging</title> - - <sect2> - <title>The Debugger</title> - - <para>The debugger that comes with FreeBSD is called - <command>gdb</command> (<application>GNU - debugger</application>). You start it up by typing</para> - - <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput> - </screen> - - <para>although most people prefer to run it inside - <application>Emacs</application>. You can do this by:</para> - - <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput> - </screen> - - <para>Using a debugger allows you to run the program under more - controlled circumstances. Typically, you can step through the - program a line at a time, inspect the value of variables, - change them, tell the debugger to run up to a certain point - and then stop, and so on. You can even attach to a program - that's already running, or load a core file to investigate why - the program crashed. It's even possible to debug the kernel, - though that's a little trickier than the user applications - we'll be discussing in this section.</para> - - <para><command>gdb</command> has quite good on-line help, as - well as a set of info pages, so this section will concentrate - on a few of the basic commands.</para> - - <para>Finally, if you find its text-based command-prompt style - off-putting, there's a graphical front-end for it <ulink - URL="../../ports/devel.html">xxgdb</ulink> in the ports - collection.</para> - - <para>This section is intended to be an introduction to using - <command>gdb</command> and does not cover specialised topics - such as debugging the kernel.</para> - </sect2> - - <sect2> - <title>Running a program in the debugger</title> - - <para>You'll need to have compiled the program with the - <option>-g</option> option to get the most out of using - <command>gdb</command>. It will work without, but you'll only - see the name of the function you're in, instead of the source - code. If you see a line like:</para> - - <screen>… (no debugging symbols found) … - </screen> - - <para>when <command>gdb</command> starts up, you'll know that - the program wasn't compiled with the <option>-g</option> - option.</para> - - <para>At the <command>gdb</command> prompt, type - <userinput>break main</userinput>. This will tell the - debugger to skip over the preliminary set-up code in the - program and start at the beginning of your code. Now type - <userinput>run</userinput> to start the program—it will - start at the beginning of the set-up code and then get stopped - by the debugger when it calls <function>main()</function>. - (If you've ever wondered where <function>main()</function> - gets called from, now you know!).</para> - - <para>You can now step through the program, a line at a time, by - pressing <command>n</command>. If you get to a function call, - you can step into it by pressing <command>s</command>. Once - you're in a function call, you can return from stepping into a - function call by pressing <command>f</command>. You can also - use <command>up</command> and <command>down</command> to take - a quick look at the caller.</para> - - <para>Here's a simple example of how to spot a mistake in a - program with <command>gdb</command>. This is our program - (with a deliberate mistake):</para> - - <programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - </programlisting> - - <para>This program sets <symbol>i</symbol> to be - <literal>5</literal> and passes it to a function - <function>bazz()</function> which prints out the number we - gave it.</para> - - <para>When we compile and run the program we get</para> - - <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput> -&prompt.user; <userinput>./temp</userinput> -This is my program -anint = 4231 - </screen> - - <para>That wasn't what we expected! Time to see what's going - on!</para> - - <screen>&prompt.user; <userinput>gdb temp</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) - </screen> - - <para>Hang on a minute! How did <symbol>anint</symbol> get to be - <literal>4231</literal>? Didn't we set it to be - <literal>5</literal> in <function>main()</function>? Let's - move up to <function>main()</function> and have a look.</para> - - <screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></> - </screen> - - <para>Oh dear! Looking at the code, we forgot to initialise - <symbol>i</symbol>. We meant to put</para> - - <programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</> - </programlisting> - - <para>but we left the <literal>i=5;</literal> line out. As we - didn't initialise <symbol>i</symbol>, it had whatever number - happened to be in that area of memory when the program ran, - which in this case happened to be - <literal>4231</literal>.</para> - - <note> - <para><command>gdb</command> displays the stack frame every - time we go into or out of a function, even if we're using - <command>up</command> and <command>down</command> to move - around the call stack. This shows the name of the function - and the values of its arguments, which helps us keep track - of where we are and what's going on. (The stack is a - storage area where the program stores information about the - arguments passed to functions and where to go when it - returns from a function call).</para> - </note> - </sect2> - - <sect2> - <title>Examining a core file</title> - - <para>A core file is basically a file which contains the - complete state of the process when it crashed. In <quote>the - good old days</quote>, programmers had to print out hex - listings of core files and sweat over machine code manuals, - but now life is a bit easier. Incidentally, under FreeBSD and - other 4.4BSD systems, a core file is called - <filename><replaceable>progname</replaceable>.core</filename> instead of just - <filename>core</filename>, to make it clearer which program a - core file belongs to.</para> - - <para>To examine a core file, start up <command>gdb</command> in - the usual way. Instead of typing <command>break</command> or - <command>run</command>, type</para> - - <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput> - </screen> - - <para>If you're not in the same directory as the core file, - you'll have to do <userinput>dir - /path/to/core/file</userinput> first.</para> - - <para>You should see something like this:</para> - - <screen>&prompt.user; <userinput>gdb a.out</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - </screen> - - <para>In this case, the program was called - <filename>a.out</filename>, so the core file is called - <filename>a.out.core</filename>. We can see that the program - crashed due to trying to access an area in memory that was not - available to it in a function called - <function>bazz</function>.</para> - - <para>Sometimes it's useful to be able to see how a function was - called, as the problem could have occurred a long way up the - call stack in a complex program. The <command>bt</command> - command causes <command>gdb</command> to print out a - back-trace of the call stack:</para> - - <screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb) - </screen> - - <para>The <function>end()</function> function is called when a - program crashes; in this case, the <function>bazz()</function> - function was called from <function>main()</function>.</para> - </sect2> - - <sect2> - <title>Attaching to a running program</title> - - <para>One of the neatest features about <command>gdb</command> - is that it can attach to a program that's already running. Of - course, that assumes you have sufficient permissions to do so. - A common problem is when you are stepping through a program - that forks, and you want to trace the child, but the debugger - will only let you trace the parent.</para> - - <para>What you do is start up another <command>gdb</command>, - use <command>ps</command> to find the process ID for the - child, and do</para> - - <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput> - </screen> - - <para>in <command>gdb</command>, and then debug as usual.</para> - - <para><quote>That's all very well,</quote> you're probably - thinking, <quote>but by the time I've done that, the child - process will be over the hill and far away</quote>. Fear - not, gentle reader, here's how to do it (courtesy of the - <command>gdb</command> info pages):</para> - - <screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation> - </screen> - - <para>Now all you have to do is attach to the child, set - <symbol>PauseMode</symbol> to <literal>0</literal>, and wait - for the <function>sleep()</function> call to return!</para> - </sect2> - </sect1> - - <sect1 id="emacs"> - <title>Using Emacs as a Development Environment</title> - - <sect2> - <title>Emacs</title> - - <para>Unfortunately, Unix systems don't come with the kind of - everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package - integrated development environments that other systems - have. - - <footnote> - <para>At least, not unless you pay out very large sums of - money.</para> - </footnote> - - However, it is possible to set up your own environment. It - may not be as pretty, and it may not be quite as integrated, - but you can set it up the way you want it. And it's free. - And you have the source to it.</para> - - <para>The key to it all is Emacs. Now there are some people who - loathe it, but many who love it. If you're one of the former, - I'm afraid this section will hold little of interest to you. - Also, you'll need a fair amount of memory to run it—I'd - recommend 8MB in text mode and 16MB in X as the bare minimum - to get reasonable performance.</para> - - <para>Emacs is basically a highly customisable - editor—indeed, it has been customised to the point where - it's more like an operating system than an editor! Many - developers and sysadmins do in fact spend practically all - their time working inside Emacs, leaving it only to log - out.</para> - - <para>It's impossible even to summarise everything Emacs can do - here, but here are some of the features of interest to - developers:</para> - - <itemizedlist> - <listitem> - <para>Very powerful editor, allowing search-and-replace on - both strings and regular expressions (patterns), jumping - to start/end of block expression, etc, etc.</para> - </listitem> - - <listitem> - <para>Pull-down menus and online help.</para> - </listitem> - - <listitem> - <para>Language-dependent syntax highlighting and - indentation.</para> - </listitem> - - <listitem> - <para>Completely customisable.</para> - </listitem> - - <listitem> - <para>You can compile and debug programs within - Emacs.</para> - </listitem> - - <listitem> - <para>On a compilation error, you can jump to the offending - line of source code.</para> - </listitem> - - <listitem> - <para>Friendly-ish front-end to the <command>info</command> - program used for reading GNU hypertext documentation, - including the documentation on Emacs itself.</para> - </listitem> - - <listitem> - <para>Friendly front-end to <command>gdb</command>, allowing - you to look at the source code as you step through your - program.</para> - </listitem> - - <listitem> - <para>You can read Usenet news and mail while your program - is compiling.</para> - </listitem> - </itemizedlist> - - <para>And doubtless many more that I've overlooked.</para> - - <para>Emacs can be installed on FreeBSD using <ulink - URL="../../ports/editors.html">the Emacs - port</ulink>.</para> - - <para>Once it's installed, start it up and do <userinput>C-h - t</userinput> to read an Emacs tutorial—that means - hold down the <keycap>control</keycap> key, press - <keycap>h</keycap>, let go of the <keycap>control</keycap> - key, and then press <keycap>t</keycap>. (Alternatively, you - can you use the mouse to select <guimenuitem>Emacs - Tutorial</guimenuitem> from the <guimenu>Help</guimenu> - menu).</para> - - <para>Although Emacs does have menus, it's well worth learning - the key bindings, as it's much quicker when you're editing - something to press a couple of keys than to try and find the - mouse and then click on the right place. And, when you're - talking to seasoned Emacs users, you'll find they often - casually throw around expressions like <quote><literal>M-x - replace-s RET foo RET bar RET</literal></quote> so it's - useful to know what they mean. And in any case, Emacs has far - too many useful functions for them to all fit on the menu - bars.</para> - - <para>Fortunately, it's quite easy to pick up the key-bindings, - as they're displayed next to the menu item. My advice is to - use the menu item for, say, opening a file until you - understand how it works and feel confident with it, then try - doing C-x C-f. When you're happy with that, move on to - another menu command.</para> - - <para>If you can't remember what a particular combination of - keys does, select <guimenuitem>Describe Key</guimenuitem> from - the <guimenu>Help</guimenu> menu and type it in—Emacs - will tell you what it does. You can also use the - <guimenuitem>Command Apropos</guimenuitem> menu item to find - out all the commands which contain a particular word in them, - with the key binding next to it.</para> - - <para>By the way, the expression above means hold down the - <keysym>Meta</keysym> key, press <keysym>x</keysym>, release - the <keysym>Meta</keysym> key, type - <userinput>replace-s</userinput> (short for - <literal>replace-string</literal>—another feature of - Emacs is that you can abbreviate commands), press the - <keysym>return</keysym> key, type <userinput>foo</userinput> - (the string you want replaced), press the - <keysym>return</keysym> key, type bar (the string you want to - replace <literal>foo</literal> with) and press - <keysym>return</keysym> again. Emacs will then do the - search-and-replace operation you've just requested.</para> - - <para>If you're wondering what on earth the - <keysym>Meta</keysym> key is, it's a special key that many - Unix workstations have. Unfortunately, PC's don't have one, - so it's usually the <keycap>alt</keycap> key (or if you're - unlucky, the <keysym>escape</keysym> key).</para> - - <para>Oh, and to get out of Emacs, do <command>C-x C-c</command> - (that means hold down the <keysym>control</keysym> key, press - <keysym>x</keysym>, press <keysym>c</keysym> and release the - <keysym>control</keysym> key). If you have any unsaved files - open, Emacs will ask you if you want to save them. (Ignore - the bit in the documentation where it says - <command>C-z</command> is the usual way to leave - Emacs—that leaves Emacs hanging around in the - background, and is only really useful if you're on a system - which doesn't have virtual terminals).</para> - </sect2> - - <sect2> - <title>Configuring Emacs</title> - - <para>Emacs does many wonderful things; some of them are built - in, some of them need to be configured.</para> - - <para>Instead of using a proprietary macro language for - configuration, Emacs uses a version of Lisp specially adapted - for editors, known as Emacs Lisp. This can be quite useful if - you want to go on and learn something like Common Lisp, as - it's considerably smaller than Common Lisp (although still - quite big!).</para> - - <para>The best way to learn Emacs Lisp is to download the <ulink - URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs - Tutorial</ulink></para> - - <para>However, there's no need to actually know any Lisp to get - started with configuring Emacs, as I've included a sample - <filename>.emacs</filename> file, which should be enough to - get you started. Just copy it into your home directory and - restart Emacs if it's already running; it will read the - commands from the file and (hopefully) give you a useful basic - setup.</para> - </sect2> - - <sect2> - <title>A sample <filename>.emacs</filename> file</title> - - <para>Unfortunately, there's far too much here to explain it in - detail; however there are one or two points worth - mentioning.</para> - - <itemizedlist> - <listitem> - <para>Everything beginning with a <literal>;</literal> is a comment - and is ignored by Emacs.</para> - </listitem> - - <listitem> - <para>In the first line, the - <literal>-*- Emacs-Lisp -*-</literal> is so that - we can edit the <filename>.emacs</filename> file itself - within Emacs and get all the fancy features for editing - Emacs Lisp. Emacs usually tries to guess this based on - the filename, and may not get it right for - <filename>.emacs</filename>.</para> - </listitem> - - <listitem> - <para>The <keysym>tab</keysym> key is bound to an - indentation function in some modes, so when you press the - tab key, it will indent the current line of code. If you - want to put a <token>tab</token> character in whatever - you're writing, hold the <keysym>control</keysym> key down - while you're pressing the <keysym>tab</keysym> key.</para> - </listitem> - - <listitem> - <para>This file supports syntax highlighting for C, C++, - Perl, Lisp and Scheme, by guessing the language from the - filename.</para> - </listitem> - - <listitem> - <para>Emacs already has a pre-defined function called - <function>next-error</function>. In a compilation output - window, this allows you to move from one compilation error - to the next by doing <command>M-n</command>; we define a - complementary function, - <function>previous-error</function>, that allows you to go - to a previous error by doing <command>M-p</command>. The - nicest feature of all is that <command>C-c C-c</command> - will open up the source file in which the error occurred - and jump to the appropriate line.</para> - </listitem> - - <listitem> - <para>We enable Emacs's ability to act as a server, so that - if you're doing something outside Emacs and you want to - edit a file, you can just type in</para> - - <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput> - </screen> - - <para>and then you can edit the file in your - Emacs! - - <footnote> - <para>Many Emacs users set their <systemitem - class=environvar>EDITOR</systemitem> environment to - <literal>emacsclient</literal> so this happens every - time they need to edit a file.</para> - </footnote></para> - </listitem> - </itemizedlist> - - <example> - <title>A sample <filename>.emacs</filename> file</title> - - <programlisting>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - </programlisting> - </example> - </sect2> - - <sect2> - <title>Extending the Range of Languages Emacs Understands</title> - - <para>Now, this is all very well if you only want to program in - the languages already catered for in the - <filename>.emacs</filename> file (C, C++, Perl, Lisp and - Scheme), but what happens if a new language called - <quote>whizbang</quote> comes out, full of exciting - features?</para> - - <para>The first thing to do is find out if whizbang comes with - any files that tell Emacs about the language. These usually - end in <filename>.el</filename>, short for <quote>Emacs - Lisp</quote>. For example, if whizbang is a FreeBSD port, we - can locate these files by doing</para> - - <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput> - </screen> - - <para>and install them by copying them into the Emacs site Lisp - directory. On FreeBSD 2.1.0-RELEASE, this is - <filename>/usr/local/share/emacs/site-lisp</filename>.</para> - - <para>So for example, if the output from the find command - was</para> - - <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el - </screen> - - <para>we would do</para> - - <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput> - </screen> - - <para>Next, we need to decide what extension whizbang source - files have. Let's say for the sake of argument that they all - end in <filename>.wiz</filename>. We need to add an entry to - our <filename>.emacs</filename> file to make sure Emacs will - be able to use the information in - <filename>whizbang.el</filename>.</para> - - <para>Find the <symbol>auto-mode-alist entry</symbol> in - <filename>.emacs</filename> and add a line for whizbang, such - as:</para> - - <programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</> - </programlisting> - - <para>This means that Emacs will automatically go into - <function>whizbang-mode</function> when you edit a file ending - in <filename>.wiz</filename>.</para> - - <para>Just below this, you'll find the - <symbol>font-lock-auto-mode-list</symbol> entry. Add - <function>whizbang-mode</function> to it like so:</para> - - <programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - </programlisting> - - <para>This means that Emacs will always enable - <function>font-lock-mode</function> (ie syntax highlighting) - when editing a <filename>.wiz</filename> file.</para> - - <para>And that's all that's needed. If there's anything else - you want done automatically when you open up a - <filename>.wiz</filename> file, you can add a - <function>whizbang-mode hook</function> (see - <function>my-scheme-mode-hook</function> for a simple example - that adds <function>auto-indent</function>).</para> - </sect2> - </sect1> - - <sect1> - <title>Further Reading</title> - - <itemizedlist> - <listitem> - <para>Brian Harvey and Matthew Wright - <emphasis>Simply Scheme</emphasis> - MIT 1994.<!-- <br> --> - ISBN 0-262-08226-8</para> - </listitem> - - <listitem> - <para>Randall Schwartz - <emphasis>Learning Perl</emphasis> - O'Reilly 1993<!-- <br> --> - ISBN 1-56592-042-2</para> - </listitem> - - <listitem> - <para>Patrick Henry Winston and Berthold Klaus Paul Horn - <emphasis>Lisp (3rd Edition)</emphasis> - Addison-Wesley 1989<!-- <br> --> - ISBN 0-201-08319-1</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Rob Pike - <emphasis>The Unix Programming Environment</emphasis> - Prentice-Hall 1984<!-- <br> --> - ISBN 0-13-937681-X</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Dennis M. Ritchie - <emphasis>The C Programming Language (2nd Edition)</emphasis> - Prentice-Hall 1988<!-- <br> --> - ISBN 0-13-110362-8</para> - </listitem> - - <listitem> - <para>Bjarne Stroustrup - <emphasis>The C++ Programming Language</emphasis> - Addison-Wesley 1991<!-- <br> --> - ISBN 0-201-53992-6</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Advanced Programming in the Unix Environment</emphasis> - Addison-Wesley 1992<!-- <br> --> - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Unix Network Programming</emphasis> - Prentice-Hall 1990<!-- <br> --> - ISBN 0-13-949876-1</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/vm-design/Makefile b/en_US.ISO8859-1/articles/vm-design/Makefile deleted file mode 100644 index 6758b4073a..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/mh/Makefile,v 1.8 1999/09/06 06:52:37 peter Exp $ - -DOC?= article - -FORMATS?= html - -IMAGES= fig1.eps fig2.eps fig3.eps fig4.eps - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/vm-design/article.sgml b/en_US.ISO8859-1/articles/vm-design/article.sgml deleted file mode 100644 index 8a436e5dcf..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/article.sgml +++ /dev/null @@ -1,838 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/vm-design/article.sgml,v 1.1 2000/10/08 19:23:10 nik Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <artheader> - <title>Design elements of the FreeBSD VM system</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - - <surname>Dillon</surname> - - <affiliation> - <address> - <email>dillon@apollo.backplane.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <abstract> - <para>The title is really just a fancy way of saying that I am going to - attempt to describe the whole VM enchilada, hopefully in a way that - everyone can follow. For the last year I have concentrated on a number - of major kernel subsystems within FreeBSD, with the VM and Swap - subsystems being the most interesting and NFS being ‘a necessary - chore’. I rewrote only small portions of the code. In the VM - arena the only major rewrite I have done is to the swap subsystem. - Most of my work was cleanup and maintenance, with only moderate code - rewriting and no major algorithmic adjustments within the VM - subsystem. The bulk of the VM subsystem's theoretical base remains - unchanged and a lot of the credit for the modernization effort in the - last few years belongs to John Dyson and David Greenman. Not being a - historian like Kirk I will not attempt to tag all the various features - with peoples names, since I will invariably get it wrong.</para> - </abstract> - - <legalnotice> - <para>This article was originally published in the January 2000 issue of - <ulink url="http://www.daemonnews.org/">DaemonNews</ulink>. This - version of the article may include updates from Matt and other authors - to reflect changes in FreeBSD's VM implementation.</para> - </legalnotice> - </artheader> - - <sect1> - <title>Introduction</title> - - <para>Before moving along to the actual design let's spend a little time - on the necessity of maintaining and modernizing any long-living - codebase. In the programming world, algorithms tend to be more - important than code and it is precisely due to BSD's academic roots that - a great deal of attention was paid to algorithm design from the - beginning. More attention paid to the design generally leads to a clean - and flexible codebase that can be fairly easily modified, extended, or - replaced over time. While BSD is considered an ‘old’ - operating system by some people, those of us who work on it tend to view - it more as a ‘mature’ codebase which has various components - modified, extended, or replaced with modern code. It has evolved, and - FreeBSD is at the bleeding edge no matter how old some of the code might - be. This is an important distinction to make and one that is - unfortunately lost to many people. The biggest error a programmer can - make is to not learn from history, and this is precisely the error that - many other modern operating systems have made. NT is the best example - of this, and the consequences have been dire. Linux also makes this - mistake to some degree—enough that we BSD folk can make small - jokes about it every once in a while, anyway. Linux's problem is simply - one of a lack of experience and history to compare ideas against, a - problem that is easily and rapidly being addressed by the Linux - community in the same way it has been addressed in the BSD - community—by continuous code development. The NT folk, on the - other hand, repeatedly make the same mistakes solved by UNIX decades ago - and then spend years fixing them. Over and over again. They have a - severe case of ‘not designed here’ and ‘we are always - right because our marketing department says so’. I have little - tolerance for anyone who cannot learn from history.</para> - - <para>Much of the apparent complexity of the FreeBSD design, especially in - the VM/Swap subsystem, is a direct result of having to solve serious - performance issues that occur under various conditions. These issues - are not due to bad algorithmic design but instead rise from - environmental factors. In any direct comparison between platforms, - these issues become most apparent when system resources begin to get - stressed. As I describe FreeBSD's VM/Swap subsystem the reader should - always keep two points in mind. First, the most important aspect of - performance design is what is known as “Optimizing the Critical - Path”. It is often the case that performance optimizations add a - little bloat to the code in order to make the critical path perform - better. Second, a solid, generalized design outperforms a - heavily-optimized design over the long run. While a generalized design - may end up being slower than an heavily-optimized design when they are - first implemented, the generalized design tends to be easier to adapt to - changing conditions and the heavily-optimized design winds up having to - be thrown away. Any codebase that will survive and be maintainable for - years must therefore be designed properly from the beginning even if it - costs some performance. Twenty years ago people were still arguing that - programming in assembly was better than programming in a high-level - language because it produced code that was ten times as fast. Today, - the fallibility of that argument is obvious—as are the parallels - to algorithmic design and code generalization.</para> - </sect1> - - <sect1> - <title>VM Objects</title> - - <para>The best way to begin describing the FreeBSD VM system is to look at - it from the perspective of a user-level process. Each user process sees - a single, private, contiguous VM address space containing several types - of memory objects. These objects have various characteristics. Program - code and program data are effectively a single memory-mapped file (the - binary file being run), but program code is read-only while program data - is copy-on-write. Program BSS is just memory allocated and filled with - zeros on demand, called demand zero page fill. Arbitrary files can be - memory-mapped into the address space as well, which is how the shared - library mechanism works. Such mappings can require modifications to - remain private to the process making them. The fork system call adds an - entirely new dimension to the VM management problem on top of the - complexity already given.</para> - - <para>A program binary data page (which is a basic copy-on-write page) - illustrates the complexity. A program binary contains a preinitialized - data section which is initially mapped directly from the program file. - When a program is loaded into a process's VM space, this area is - initially memory-mapped and backed by the program binary itself, - allowing the VM system to free/reuse the page and later load it back in - from the binary. The moment a process modifies this data, however, the - VM system must make a private copy of the page for that process. Since - the private copy has been modified, the VM system may no longer free it, - because there is no longer any way to restore it later on.</para> - - <para>You will notice immediately that what was originally a simple file - mapping has become much more complex. Data may be modified on a - page-by-page basis whereas the file mapping encompasses many pages at - once. The complexity further increases when a process forks. When a - process forks, the result is two processes—each with their own - private address spaces, including any modifications made by the original - process prior to the call to <function>fork()</function>. It would be - silly for the VM system to make a complete copy of the data at the time - of the <function>fork()</function> because it is quite possible that at - least one of the two processes will only need to read from that page - from then on, allowing the original page to continue to be used. What - was a private page is made copy-on-write again, since each process - (parent and child) expects their own personal post-fork modifications to - remain private to themselves and not effect the other.</para> - - <para>FreeBSD manages all of this with a layered VM Object model. The - original binary program file winds up being the lowest VM Object layer. - A copy-on-write layer is pushed on top of that to hold those pages which - had to be copied from the original file. If the program modifies a data - page belonging to the original file the VM system takes a fault and - makes a copy of the page in the higher layer. When a process forks, - additional VM Object layers are pushed on. This might make a little - more sense with a fairly basic example. A <function>fork()</function> - is a common operation for any *BSD system, so this example will consider - a program that starts up, and forks. When the process starts, the VM - system creates an object layer, let's call this A:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig1"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> - </textobject> - </mediaobject> - - <para>A represents the file—pages may be paged in and out of the - file's physical media as necessary. Paging in from the disk is - reasonable for a program, but we really don't want to page back out and - overwrite the executable. The VM system therefore creates a second - layer, B, that will be physically backed by swap space:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig2"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>On the first write to a page after this, a new page is created in B, - and its contents are initialized from A. All pages in B can be paged in - or out to a swap device. When the program forks, the VM system creates - two new object layers—C1 for the parent, and C2 for the - child—that rest on top of B:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig3"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+-------+ -| C1 | C2 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, let's say a page in B is modified by the original - parent process. The process will take a copy-on-write fault and - duplicate the page in C1, leaving the original page in B untouched. - Now, let's say the same page in B is modified by the child process. The - process will take a copy-on-write fault and duplicate the page in C2. - The original page in B is now completely hidden since both C1 and C2 - have a copy and B could theoretically be destroyed if it does not - represent a 'real' file). However, this sort of optimization is not - trivial to make because it is so fine-grained. FreeBSD does not make - this optimization. Now, suppose (as is often the case) that the child - process does an <function>exec()</function>. Its current address space - is usually replaced by a new address space representing a new file. In - this case, the C2 layer is destroyed:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig4"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+ -| C1 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, the number of children of B drops to one, and all - accesses to B now go through C1. This means that B and C1 can be - collapsed together. Any pages in B that also exist in C1 are deleted - from B during the collapse. Thus, even though the optimization in the - previous step could not be made, we can recover the dead pages when - either of the processes exit or <function>exec()</function>.</para> - - <para>This model creates a number of potential problems. The first is that - you can wind up with a relatively deep stack of layered VM Objects which - can cost scanning time and memory when you when you take a fault. Deep - layering can occur when processes fork and then fork again (either - parent or child). The second problem is that you can wind up with dead, - inaccessible pages deep in the stack of VM Objects. In our last example - if both the parent and child processes modify the same page, they both - get their own private copies of the page and the original page in B is - no longer accessible by anyone. That page in B can be freed.</para> - - <para>FreeBSD solves the deep layering problem with a special optimization - called the “All Shadowed Case”. This case occurs if either - C1 or C2 take sufficient COW faults to completely shadow all pages in B. - Lets say that C1 achieves this. C1 can now bypass B entirely, so rather - then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But - look what also happened—now B has only one reference (C2), so we - can collapse B and C2 together. The end result is that B is deleted - entirely and we have C1->A and C2->A. It is often the case that B will - contain a large number of pages and neither C1 nor C2 will be able to - completely overshadow it. If we fork again and create a set of D - layers, however, it is much more likely that one of the D layers will - eventually be able to completely overshadow the much smaller dataset - reprsented by C1 or C2. The same optimization will work at any point in - the graph and the grand result of this is that even on a heavily forked - machine VM Object stacks tend to not get much deeper then 4. This is - true of both the parent and the children and true whether the parent is - doing the forking or whether the children cascade forks.</para> - - <para>The dead page problem still exists in the case where C1 or C2 do not - completely overshadow B. Due to our other optimizations this case does - not represent much of a problem and we simply allow the pages to be - dead. If the system runs low on memory it will swap them out, eating a - little swap, but that's it.</para> - - <para>The advantage to the VM Object model is that - <function>fork()</function> is extremely fast, since no real data - copying need take place. The disadvantage is that you can build a - relatively complex VM Object layering that slows page fault handling - down a little, and you spend memory managing the VM Object structures. - The optimizations FreeBSD makes proves to reduce the problems enough - that they can be ignored, leaving no real disadvantage.</para> - </sect1> - - <sect1> - <title>SWAP Layers</title> - - <para>Private data pages are initially either copy-on-write or zero-fill - pages. When a change, and therefore a copy, is made, the original - backing object (usually a file) can no longer be used to save a copy of - the page when the VM system needs to reuse it for other purposes. This - is where SWAP comes in. SWAP is allocated to create backing store for - memory that does not otherwise have it. FreeBSD allocates the swap - management structure for a VM Object only when it is actually needed. - However, the swap management structure has had problems - historically.</para> - - <para>Under FreeBSD 3.x the swap management structure preallocates an - array that encompasses the entire object requiring swap backing - store—even if only a few pages of that object are swap-backed. - This creates a kernel memory fragmentation problem when large objects - are mapped, or processes with large runsizes (RSS) fork. Also, in order - to keep track of swap space, a ‘list of holes’ is kept in - kernel memory, and this tends to get severely fragmented as well. Since - the 'list of holes' is a linear list, the swap allocation and freeing - performance is a non-optimal O(n)-per-page. It also requires kernel - memory allocations to take place during the swap freeing process, and - that creates low memory deadlock problems. The problem is further - exacerbated by holes created due to the interleaving algorithm. Also, - the swap block map can become fragmented fairly easily resulting in - non-contiguous allocations. Kernel memory must also be allocated on the - fly for additional swap management structures when a swapout occurs. It - is evident that there was plenty of room for improvement.</para> - - <para>For FreeBSD 4.x, I completely rewrote the swap subsystem. With this - rewrite, swap management structures are allocated through a hash table - rather than a linear array giving them a fixed allocation size and much - finer granularity. Rather then using a linearly linked list to keep - track of swap space reservations, it now uses a bitmap of swap blocks - arranged in a radix tree structure with free-space hinting in the radix - node structures. This effectively makes swap allocation and freeing an - O(1) operation. The entire radix tree bitmap is also preallocated in - order to avoid having to allocate kernel memory during critical low - memory swapping operations. After all, the system tends to swap when it - is low on memory so we should avoid allocating kernel memory at such - times in order to avoid potential deadlocks. Finally, to reduce - fragmentation the radix tree is capable of allocating large contiguous - chunks at once, skipping over smaller fragmented chunks. I did not take - the final step of having an 'allocating hint pointer' that would trundle - through a portion of swap as allocations were made in order to further - guarantee contiguous allocations or at least locality of reference, but - I ensured that such an addition could be made.</para> - </sect1> - - <sect1> - <title>When to free a page</title> - - <para>Since the VM system uses all available memory for disk caching, - there are usually very few truly-free pages. The VM system depends on - being able to properly choose pages which are not in use to reuse for - new allocations. Selecting the optimal pages to free is possibly the - single-most important function any VM system can perform because if it - makes a poor selection, the VM system may be forced to unnecessarily - retrieve pages from disk, seriously degrading system performance.</para> - - <para>How much overhead are we willing to suffer in the critical path to - avoid freeing the wrong page? Each wrong choice we make will cost us - hundreds of thousands of CPU cycles and a noticeable stall of the - affected processes, so we are willing to endure a significant amount of - overhead in order to be sure that the right page is chosen. This is why - FreeBSD tends to outperform other systems when memory resources become - stressed.</para> - - <para>The free page determination algorithm is built upon a history of the - use of memory pages. To acquire this history, the system takes advantage - of a page-used bit feature that most hardware page tables have.</para> - - <para>In any case, the page-used bit is cleared and at some later point - the VM system comes across the page again and sees that the page-used - bit has been set. This indicates that the page is still being actively - used. If the bit is still clear it is an indication that the page is not - being actively used. By testing this bit periodically, a use history (in - the form of a counter) for the physical page is developed. When the VM - system later needs to free up some pages, checking this history becomes - the cornerstone of determining the best candidate page to reuse.</para> - - <sidebar> - <title>What if the hardware has no page-used bit?</title> - - <para>For those platforms that do not have this feature, the system - actually emulates a page-used bit. It unmaps or protects a page, - forcing a page fault if the page is accessed again. When the page - fault is taken, the system simply marks the page as having been used - and unprotects the page so that it may be used. While taking such page - faults just to determine if a page is being used appears to be an - expensive proposition, it is much less expensive than reusing the page - for some other purpose only to find that a process needs it back and - then have to go to disk.</para> - </sidebar> - - <para>FreeBSD makes use of several page queues to further refine the - selection of pages to reuse as well as to determine when dirty pages - must be flushed to their backing store. Since page tables are dynamic - entities under FreeBSD, it costs virtually nothing to unmap a page from - the address space of any processes using it. When a page candidate has - been chosen based on the page-use counter, this is precisely what is - done. The system must make a distinction between clean pages which can - theoretically be freed up at any time, and dirty pages which must first - be written to their backing store before being reusable. When a page - candidate has been found it is moved to the inactive queue if it is - dirty, or the cache queue if it is clean. A separate algorithm based on - the dirty-to-clean page ratio determines when dirty pages in the - inactive queue must be flushed to disk. Once this is accomplished, the - flushed pages are moved from the inactive queue to the cache queue. At - this point, pages in the cache queue can still be reactivated by a VM - fault at relatively low cost. However, pages in the cache queue are - considered to be ‘immediately freeable’ and will be reused - in an LRU (least-recently used) fashion when the system needs to - allocate new memory.</para> - - <para>It is important to note that the FreeBSD VM system attempts to - separate clean and dirty pages for the express reason of avoiding - unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does - it move pages between the various page queues gratuitously when the - memory subsystem is not being stressed. This is why you will see some - systems with very low cache queue counts and high active queue counts - when doing a <command>systat -vm</command> command. As the VM system - becomes more stressed, it makes a greater effort to maintain the various - page queues at the levels determined to be the most effective. An urban - myth has circulated for years that Linux did a better job avoiding - swapouts than FreeBSD, but this in fact is not true. What was actually - occurring was that FreeBSD was proactively paging out unused pages in - order to make room for more disk cache while Linux was keeping unused - pages in core and leaving less memory available for cache and process - pages. I don't know whether this is still true today.</para> - </sect1> - - <sect1> - <title>Pre-Faulting and Zeroing Optimizations</title> - - <para>Taking a VM fault is not expensive if the underlying page is already - in core and can simply be mapped into the process, but it can become - expensive if you take a whole lot of them on a regular basis. A good - example of this is running a program such as &man.ls.1; or &man.ps.1; - over and over again. If the program binary is mapped into memory but - not mapped into the page table, then all the pages that will be accessed - by the program will have to be faulted in every time the program is run. - This is unnecessary when the pages in question are already in the VM - Cache, so FreeBSD will attempt to pre-populate a process's page tables - with those pages that are already in the VM Cache. One thing that - FreeBSD does not yet do is pre-copy-on-write certain pages on exec. For - example, if you run the &man.ls.1; program while running <command>vmstat - 1</command> you will notice that it always takes a certain number of - page faults, even when you run it over and over again. These are - zero-fill faults, not program code faults (which were pre-faulted in - already). Pre-copying pages on exec or fork is an area that could use - more study.</para> - - <para>A large percentage of page faults that occur are zero-fill faults. - You can usually see this by observing the <command>vmstat -s</command> - output. These occur when a process accesses pages in its BSS area. The - BSS area is expected to be initially zero but the VM system does not - bother to allocate any memory at all until the process actually accesses - it. When a fault occurs the VM system must not only allocate a new page, - it must zero it as well. To optimize the zeroing operation the VM system - has the ability to pre-zero pages and mark them as such, and to request - pre-zeroed pages when zero-fill faults occur. The pre-zeroing occurs - whenever the CPU is idle but the number of pages the system pre-zeros is - limited in order to avoid blowing away the memory caches. This is an - excellent example of adding complexity to the VM system in order to - optimize the critical path.</para> - </sect1> - - <sect1> - <title>Page Table Optimizations</title> - - <para>The page table optimizations make up the most contentious part of - the FreeBSD VM design and they have shown some strain with the advent of - serious use of <function>mmap()</function>. I think this is actually a - feature of most BSDs though I am not sure when it was first introduced. - There are two major optimizations. The first is that hardware page - tables do not contain persistent state but instead can be thrown away at - any time with only a minor amount of management overhead. The second is - that every active page table entry in the system has a governing - <literal>pv_entry</literal> structure which is tied into the - <literal>vm_page</literal> structure. FreeBSD can simply iterate - through those mappings that are known to exist while Linux must check - all page tables that <emphasis>might</emphasis> contain a specific - mapping to see if it does, which can achieve O(n^2) overhead in certain - situations. It is because of this that FreeBSD tends to make better - choices on which pages to reuse or swap when memory is stressed, giving - it better performance under load. However, FreeBSD requires kernel - tuning to accommodate large-shared-address-space situations such as - those that can occur in a news system because it may run out of - <literal>pv_entry</literal> structures.</para> - - <para>Both Linux and FreeBSD need work in this area. FreeBSD is trying to - maximize the advantage of a potentially sparse active-mapping model (not - all processes need to map all pages of a shared library, for example), - whereas Linux is trying to simplify its algorithms. FreeBSD generally - has the performance advantage here at the cost of wasting a little extra - memory, but FreeBSD breaks down in the case where a large file is - massively shared across hundreds of processes. Linux, on the other hand, - breaks down in the case where many processes are sparsely-mapping the - same shared library and also runs non-optimally when trying to determine - whether a page can be reused or not.</para> - </sect1> - - <sect1> - <title>Page Coloring</title> - - <para>We'll end with the page coloring optimizations. Page coloring is a - performance optimization designed to ensure that accesses to contiguous - pages in virtual memory make the best use of the processor cache. In - ancient times (i.e. 10+ years ago) processor caches tended to map - virtual memory rather than physical memory. This led to a huge number of - problems including having to clear the cache on every context switch in - some cases, and problems with data aliasing in the cache. Modern - processor caches map physical memory precisely to solve those problems. - This means that two side-by-side pages in a processes address space may - not correspond to two side-by-side pages in the cache. In fact, if you - aren't careful side-by-side pages in virtual memory could wind up using - the same page in the processor cache—leading to cacheable data - being thrown away prematurely and reducing CPU performance. This is true - even with multi-way set-associative caches (though the effect is - mitigated somewhat).</para> - - <para>FreeBSD's memory allocation code implements page coloring - optimizations, which means that the memory allocation code will attempt - to locate free pages that are contiguous from the point of view of the - cache. For example, if page 16 of physical memory is assigned to page 0 - of a process's virtual memory and the cache can hold 4 pages, the page - coloring code will not assign page 20 of physical memory to page 1 of a - process's virtual memory. It would, instead, assign page 21 of physical - memory. The page coloring code attempts to avoid assigning page 20 - because this maps over the same cache memory as page 16 and would result - in non-optimal caching. This code adds a significant amount of - complexity to the VM memory allocation subsystem as you can well - imagine, but the result is well worth the effort. Page Coloring makes VM - memory as deterministic as physical memory in regards to cache - performance.</para> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>Virtual memory in modern operating systems must address a number of - different issues efficiently and for many different usage patterns. The - modular and algorithmic approach that BSD has historically taken allows - us to study and understand the current implementation as well as - relatively cleanly replace large sections of the code. There have been a - number of improvements to the FreeBSD VM system in the last several - years, and work is ongoing.</para> - </sect1> - - <sect1> - <title>Bonus QA session by Allen Briggs - <email>briggs@ninthwonder.com</email></title> - - <qandaset> - <qandaentry> - <question> - <para>What is “the interleaving algorithm” that you - refer to in your listing of the ills of the FreeBSD 3.x swap - arrangments?</para> - </question> - - <answer> - <para>FreeBSD uses a fixed swap interleave which defaults to 4. This - means that FreeBSD reserves space for four swap areas even if you - only have one, two, or three. Since swap is interleaved the linear - address space representing the ‘four swap areas’ will be - fragmented if you don't actually have four swap areas. For - example, if you have two swap areas A and B FreeBSD's address - space representation for that swap area will be interleaved in - blocks of 16 pages:</para> - - <literallayout>A B C D A B C D A B C D A B C D</literallayout> - - <para>FreeBSD 3.x uses a ‘sequential list of free - regions’ approach to accounting for the free swap areas. - The idea is that large blocks of free linear space can be - represented with a single list node - (<filename>kern/subr_rlist.c</filename>). But due to the - fragmentation the sequential list winds up being insanely - fragmented. In the above example, completely unused swap will - have A and B shown as ‘free’ and C and D shown as - ‘all allocated’. Each A-B sequence requires a list - node to account for because C and D are holes, so the list node - cannot be combined with the next A-B sequence.</para> - - <para>Why do we interleave our swap space instead of just tack swap - areas onto the end and do something fancier? Because it's a whole - lot easier to allocate linear swaths of an address space and have - the result automatically be interleaved across multiple disks than - it is to try to put that sophistication elsewhere.</para> - - <para>The fragmentation causes other problems. Being a linear list - under 3.x, and having such a huge amount of inherent - fragmentation, allocating and freeing swap winds up being an O(N) - algorithm instead of an O(1) algorithm. Combined with other - factors (heavy swapping) and you start getting into O(N^2) and - O(N^3) levels of overhead, which is bad. The 3.x system may also - need to allocate KVM during a swap operation to create a new list - node which can lead to a deadlock if the system is trying to - pageout pages in a low-memory situation.</para> - - <para>Under 4.x we do not use a sequential list. Instead we use a - radix tree and bitmaps of swap blocks rather than ranged list - nodes. We take the hit of preallocating all the bitmaps required - for the entire swap area up front but it winds up wasting less - memory due to the use of a bitmap (one bit per block) instead of a - linked list of nodes. The use of a radix tree instead of a - sequential list gives us nearly O(1) performance no matter how - fragmented the tree becomes.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I don't get the following:</para> - - <blockquote> - <para>It is important to note that the FreeBSD VM system attempts - to separate clean and dirty pages for the express reason of - avoiding unnecessary flushes of dirty pages (which eats I/O - bandwidth), nor does it move pages between the various page - queues gratitously when the memory subsystem is not being - stressed. This is why you will see some systems with very low - cache queue counts and high active queue counts when doing a - <command>systat -vm</command> command.</para> - </blockquote> - - <para>How is the separation of clean and dirty (inactive) pages - related to the situation where you see low cache queue counts and - high active queue counts in <command>systat -vm</command>? Do the - systat stats roll the active and dirty pages together for the - active queue count?</para> - </question> - - <answer> - <para>Yes, that is confusing. The relationship is - “goal” verses “reality”. Our goal is to - separate the pages but the reality is that if we are not in a - memory crunch, we don't really have to.</para> - - <para>What this means is that FreeBSD will not try very hard to - separate out dirty pages (inactive queue) from clean pages (cache - queue) when the system is not being stressed, nor will it try to - deactivate pages (active queue -> inactive queue) when the system - is not being stressed, even if they aren't being used.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> In the &man.ls.1; / <command>vmstat 1</command> example, - wouldn't some of the page faults be data page faults (COW from - executable file to private page)? I.e., I would expect the page - faults to be some zero-fill and some program data. Or are you - implying that FreeBSD does do pre-COW for the program data?</para> - </question> - - <answer> - <para>A COW fault can be either zero-fill or program-data. The - mechanism is the same either way because the backing program-data - is almost certainly already in the cache. I am indeed lumping the - two together. FreeBSD does not pre-COW program data or zero-fill, - but it <emphasis>does</emphasis> pre-map pages that exist in its - cache.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>In your section on page table optimizations, can you give a - little more detail about <literal>pv_entry</literal> and - <literal>vm_page</literal> (or should vm_page be - <literal>vm_pmap</literal>—as in 4.4, cf. pp. 180-181 of - McKusick, Bostic, Karel, Quarterman)? Specifically, what kind of - operation/reaction would require scanning the mappings?</para> - - <para>How does Linux do in the case where FreeBSD breaks down - (sharing a large file mapping over many processes)?</para> - </question> - - <answer> - <para>A <literal>vm_page</literal> represents an (object,index#) - tuple. A <literal>pv_entry</literal> represents a hardware page - table entry (pte). If you have five processes sharing the same - physical page, and three of those processes's page tables actually - map the page, that page will be represented by a single - <literal>vm_page</literal> structure and three - <literal>pv_entry</literal> structures.</para> - - <para><literal>pv_entry</literal> structures only represent pages - mapped by the MMU (one <literal>pv_entry</literal> represnts one - pte). This means that when we need to remove all hardware - references to a <literal>vm_page</literal> (in order to reuse the - page for something else, page it out, clear it, dirty it, and so - forth) we can simply scan the linked list of - <literal>pv_entry</literal>'s associated with that - <literal>vm_page</literal> to remove or modify the pte's from - their page tables.</para> - - <para>Under Linux there is no such linked list. In order to remove - all the hardware page table mappings for a - <literal>vm_page</literal> linux must index into every VM object - that <emphasis>might</emphasis> have mapped the page. For - example, if you have 50 processes all mapping the same shared - library and want to get rid of page X in that library, you need to - index into the page table for each of those 50 processes even if - only 10 of them have actually mapped the page. So Linux is - trading off the simplicity of its design against performance. - Many VM algorithms which are O(1) or (small N) under FreeBSD wind - up being O(N), O(N^2), or worse under Linux. Since the pte's - representing a particular page in an object tend to be at the same - offset in all the page tables they are mapped in, reducing the - number of accesses into the page tables at the same pte offset - will often avoid blowing away the L1 cache line for that offset, - which can lead to better performance.</para> - - <para>FreeBSD has added complexity (the <literal>pv_entry</literal> - scheme) in order to increase performance (to limit page table - accesses to <emphasis>only</emphasis> those pte's that need to be - modified).</para> - - <para>But FreeBSD has a scaling problem that Linux does not in that - there are a limited number of <literal>pv_entry</literal> - structures and this causes problems when you have massive sharing - of data. In this case you may run out of - <literal>pv_entry</literal> structures even though there is plenty - of free memory available. This can be fixed easily enough by - bumping up the number of <literal>pv_entry</literal> structures in - the kernel config, but we really need to find a better way to do - it.</para> - - <para>In regards to the memory overhead of a page table verses the - <literal>pv_entry</literal> scheme: Linux uses - ‘permanent’ page tables that are not throw away, but - does not need a <literal>pv_entry</literal> for each potentially - mapped pte. FreeBSD uses ‘throw away’ page tables but - adds in a <literal>pv_entry</literal> structure for each - actually-mapped pte. I think memory utilization winds up being - about the same, giving FreeBSD an algorithmic advantage with its - ability to throw away page tables at will with very low - overhead.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Finally, in the page coloring section, it might help to have a - little more description of what you mean here. I didn't quite - follow it.</para> - </question> - - <answer> - <para>Do you know how an L1 hardware memory cache works? I'll - explain: Consider a machine with 16MB of main memory but only 128K - of L1 cache. Generally the way this cache works is that each 128K - block of main memory uses the <emphasis>same</emphasis> 128K of - cache. If you access offset 0 in main memory and then offset - offset 128K in main memory you can wind up throwing away the - cached data you read from offset 0!</para> - - <para>Now, I am simplifying things greatly. What I just described - is what is called a ‘direct mapped’ hardware memory - cache. Most modern caches are what are called - 2-way-set-associative or 4-way-set-associative caches. The - set-associatively allows you to access up to N different memory - regions that overlap the same cache memory without destroying the - previously cached data. But only N.</para> - - <para>So if I have a 4-way set associative cache I can access offset - 0, offset 128K, 256K and offset 384K and still be able to access - offset 0 again and have it come from the L1 cache. If I then - access offset 512K, however, one of the four previously cached - data objects will be thrown away by the cache.</para> - - <para>It is extremely important… - <emphasis>extremely</emphasis> important for most of a processor's - memory accesses to be able to come from the L1 cache, because the - L1 cache operates at the processor frequency. The moment you have - an L1 cahe miss and have to go to the L2 cache or to main memory, - the processor will stall and potentially sit twidling its fingers - for <emphasis>hundreds</emphasis> of instructions worth of time - waiting for a read from main memory to complete. Main memory (the - dynamic ram you stuff into a computer) is - <emphasis>slow</emphasis>, when compared to the speed of a modern - processor core.</para> - - <para>Ok, so now onto page coloring: All modern memory caches are - what are known as <emphasis>physical</emphasis> caches. They - cache physical memory addresses, not virtual memory addresses. - This allows the cache to be left alone across a process context - switch, which is very important.</para> - - <para>But in the UNIX world you are dealing with virtual address - spaces, not physical address spaces. Any program you write will - see the virtual address space given to it. The actual - <emphasis>physical</emphasis> pages underlying that virtual - address space are not necessarily physically contiguous! In fact, - you might have two pages that are side by side in a processes - address space which wind up being at offset 0 and offset 128K in - <emphasis>physical</emphasis> memory.</para> - - <para>A program normally assumes that two side-by-side pages will be - optimally cached. That is, that you can access data objects in - both pages without having them blow away each other's cache entry. - But this is only true if the physical pages underlying the virtual - address space are contiguous (insofar as the cache is - concerned).</para> - - <para>This is what Page coloring does. Instead of assigning - <emphasis>random</emphasis> physical pages to virtual addresses, - which may result in non-optimal cache performance , Page coloring - assigns <emphasis>reasonably-contiguous</emphasis> physical pages - to virtual addresses. Thus programs can be written under the - assumption that the characteristics of the underlying hardware - cache are the same for their virtual address space as they would - be if the program had been run directly in a physical address - space.</para> - - <para>Note that I say ‘reasonably’ contiguous rather - than simply ‘contiguous’. From the point of view of a - 128K direct mapped cache, the physical address 0 is the same as - the physical address 128K. So two side-by-side pages in your - virtual address space may wind up being offset 128K and offset - 132K in physical memory, but could also easily be offset 128K and - offset 4K in physical memory and still retain the same cache - performance characteristics. So page-coloring does - <emphasis>not</emphasis> have to assign truly contiguous pages of - physical memory to contiguous pages of virtual memory, it just - needs to make sure it assigns contiguous pages from the point of - view of cache performance and operation.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/vm-design/fig1.eps b/en_US.ISO8859-1/articles/vm-design/fig1.eps deleted file mode 100644 index 49d2c05a56..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/fig1.eps +++ /dev/null @@ -1,104 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig1.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:54:25 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 119 65 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 65 moveto 0 0 lineto 119 0 lineto 119 65 lineto closepath clip newpath --143.0 298.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -% Polyline -7.500 slw -n 2400 4200 m 4050 4200 l 4050 4950 l 2400 4950 l - cp gs col0 s gr -% Polyline -n 4050 4200 m - 4350 3900 l gs col0 s gr -% Polyline -n 2400 4200 m 2700 3900 l 4350 3900 l 4350 4650 l - 4050 4950 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3225 4650 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -$F2psEnd -rs diff --git a/en_US.ISO8859-1/articles/vm-design/fig2.eps b/en_US.ISO8859-1/articles/vm-design/fig2.eps deleted file mode 100644 index fcb8bd41ad..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/fig2.eps +++ /dev/null @@ -1,115 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig2.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:55:31 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 110 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 110 moveto 0 0 lineto 120 0 lineto 120 110 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 2925 4650 m 3225 4350 l 4875 4350 l 4875 5100 l - 4575 5400 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO8859-1/articles/vm-design/fig3.eps b/en_US.ISO8859-1/articles/vm-design/fig3.eps deleted file mode 100644 index 0e3138b2ed..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/fig3.eps +++ /dev/null @@ -1,133 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig3.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:53:51 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 155 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 155 moveto 0 0 lineto 120 0 lineto 120 155 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -4125 4350 m -gs 1 -1 sc (C2) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 4875 3600 m 4875 5100 l - 4575 5400 l gs col0 s gr -% Polyline -n 2925 4650 m 2925 3900 l 3225 3600 l - 4875 3600 l gs col0 s gr -% Polyline -n 2925 3900 m 4425 3900 l 4575 3900 l - 4875 3600 l gs col0 s gr -% Polyline -n 4575 4650 m - 4575 3900 l gs col0 s gr -% Polyline -n 3750 4650 m 3750 3900 l - 4050 3600 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3375 4350 m -gs 1 -1 sc (C1) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO8859-1/articles/vm-design/fig4.eps b/en_US.ISO8859-1/articles/vm-design/fig4.eps deleted file mode 100644 index 24fc1b5add..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/fig4.eps +++ /dev/null @@ -1,133 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig4.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:55:53 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 155 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 155 moveto 0 0 lineto 120 0 lineto 120 155 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -3375 4350 m -gs 1 -1 sc (C1) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 4875 4350 m 4875 5100 l - 4575 5400 l gs col0 s gr -% Polyline -n 2925 4650 m 2925 3900 l 3225 3600 l - 4050 3600 l gs col0 s gr -% Polyline -n 3750 4650 m 3750 3900 l - 4050 3600 l gs col0 s gr -% Polyline -n 2925 3900 m - 3750 3900 l gs col0 s gr -% Polyline -n 3750 4650 m 4050 4350 l - 4875 4350 l gs col0 s gr -% Polyline -n 4050 4350 m - 4050 3600 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO8859-1/articles/zip-drive/Makefile b/en_US.ISO8859-1/articles/zip-drive/Makefile deleted file mode 100644 index 60f4a450ea..0000000000 --- a/en_US.ISO8859-1/articles/zip-drive/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/programming-tools/Makefile,v 1.8 1999/09/06 06:52:38 peter Exp $ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/zip-drive/article.sgml b/en_US.ISO8859-1/articles/zip-drive/article.sgml deleted file mode 100644 index 3a2fe2db78..0000000000 --- a/en_US.ISO8859-1/articles/zip-drive/article.sgml +++ /dev/null @@ -1,267 +0,0 @@ -<!-- $FreeBSD --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <artheader> - <title>ZIP Drives</title> - - <authorgroup> - <author> - <firstname>Jason</firstname> - <surname>Bacon</surname> - - <affiliation> - <address><email>acadix@execpc.com</email></address> - </affiliation> - </author> - </authorgroup> - </artheader> - - <sect1> - <title>ZIP Drive Basics</title> - - <para>ZIP disks are high capacity, removable, magnetic disks, which can be - read or written by ZIP drives from iomega corporation. ZIP disks are - similar to floppy disks, except that they are much faster, and have a - much greater capacity. While floppy disks typically hold 1.44 - megabytes, ZIP disks are available in two sizes, namely 100 megabytes - and 250 megabytes. ZIP drives should not be confused with the - super-floppy, a 120 megabyte floppy drive which also handles traditional - 1.44 megabyte floppies.</para> - - <para>IOMEGA also sells a higher capacity, higher performance drive - called the JAZZ drive. JAZZ drives come in 1 gigabyte and - 2 gigabyte sizes.</para> - - <para>ZIP drives are available as internal or external units, using one - of three interfaces:</para> - - <orderedlist> - <listitem> - <para>The SCSI (Small Computer Standard Interface) interface is the - fastest, most sophisticated, most expandable, and most expensive - interface. The SCSI interface is used by all types of computers - from PC's to RISC workstations to minicomputers, to connect all - types of peripherals such as disk drives, tape drives, scanners, and - so on. SCSI ZIP drives may be internal or external, assuming your - host adapter has an external connector.</para> - - <note> - <para>If you are using an external SCSI device, it is important - never to connect or disconnect it from the SCSI bus while the - computer is running. Doing so may cause file-system damage on the - disks that remain connected.</para> - </note> - - <para>If you want maximum performance and easy setup, the SCSI - interface is the best choice. This will probably require adding a - SCSI host adapter, since most PC's (except for high-performance - servers) don't have built-in SCSI support. Each SCSI host adapter - can support either 7 or 15 SCSI devices, depending on the - model.</para> - - <para>Each SCSI device has it's own controller, and these - controllers are fairly intelligent and well standardized, (the - second `S' in SCSI is for Standard) so from the operating system's - point of view, all SCSI disk drives look about the same, as do all - SCSI tape drives, etc. To support SCSI devices, the operating - system need only have a driver for the particular host adapter, and - a generic driver for each type of device, i.e. a SCSI disk driver, - SCSI tape driver, and so on. There are some SCSI devices that can - be better utilized with specialized drivers (e.g. DAT tape drives), - but they tend to work OK with the generic driver, too. It's just - that the generic drivers may not support some of the special - features.</para> - - <para>Using a SCSI zip drive is simply a matter of determining which - device file in the <filename>/dev</filename> directory represents - the ZIP drive. This can be determined by looking at the boot - messages while FreeBSD is booting (or in - <filename>/var/log/messages</filename> after booting), where you'll - see a line something like this:</para> - - <programlisting>da1: <IOMEGA ZIP 100 D.13> Removable Direct Access SCSI-2 Device</programlisting> - - <para>This means that the ZIP drive is represented by the file - <filename>/dev/da1</filename>.</para> - </listitem> - - <listitem> - <para>The IDE (Integrated Drive Electronics) interface is a low-cost - disk drive interface used by many desktop PC's. Most IDE devices - are strictly internal.</para> - - <para>Performance of IDE ZIP drives is comparable to SCSI ZIP drives. - (The IDE interface is not as fast as SCSI, but ZIP drives - performance is limited mainly by the mechanics of the drive, not by - the bus interface.)</para> - - <para>The drawback of the IDE interface is the limitations it imposes. - Most IDE adapters can only support 2 devices, and IDE interfaces are - not typically designed for the long term. For example, the original - IDE interface would not support hard disks with more than 1024 - cylinders, which forced a lot of people to upgrade their hardware - prematurely. If you have plans to expand your PC by adding another - disk, a tape drive, or scanner, you may want to invest in a SCSI - host adapter and a SCSI ZIP drive to avoid problems in the - future.</para> - - <para>IDE devices in FreeBSD are prefixed with a <literal>w</literal>. - For example, an IDE hard disk might be - <filename>/dev/wd0</filename>, an IDE (ATAPI) cdrom might be - <filename>/dev/wcd1</filename>, and so on.</para> - </listitem> - - <listitem> - <para>The parallel port interface is popular for portable external - devices such as external ZIP drives and scanners, because virtually - every computer has a standard parallel port (usually used for - printers). This makes things easy for people to transfer data - between multiple computers by toting around their ZIP drive.</para> - - <para>Performance will generally be slower than a SCSI or IDE ZIP - drive, since it is limited by the speed of the parallel port. - Parallel port speed varies considerably between various computers, - and can often be configured in the system BIOS. Some machines - will also require BIOS configuration to operate the parallel - port in bidirectional mode. (Parallel ports were originally - designed only for output to printers)</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Parallel ZIP: The <devicename>vpo</devicename> Driver</title> - - <para>To use a parallel-port ZIP drive under FreeBSD, the - <devicename>vpo</devicename> driver must be configured into the kernel. - Parallel port ZIP drives also have a built-in SCSI controller. The vpo - driver allows the FreeBSD kernel to communicate with the ZIP drive's - SCSI controller through the parallel port.</para> - - <para>Since the vpo driver is not a standard part of the kernel (as of - FreeBSD 3.2), you will need to rebuild the kernel to enable this device. - The process of building a kernel is outlined in detail in another - section. The following steps outline the process in brief for the - purpose of enabling the vpo driver:</para> - - <orderedlist> - <listitem> - <para>Run <command>/stand/sysinstall</command>, and install the kernel - source code on your system.</para> - - <screen>&prompt.root; <userinput>cd /sys/i386/conf</userinput> -&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - - <para>Edit <filename>MYKERNEL</filename>, change the - <literal>ident</literal> line to <literal>MYKERNEL</literal>, and - uncomment the line describing the vpo driver.</para> - - <para>If you have a second parallel port, you may need to copy the - section for <literal>ppc0</literal> to create a - <literal>ppc1</literal> device. The second parallel port usually - uses IRQ 5 and address 378. Only the IRQ is required in the config - file.</para> - - <para>If you're root hard disk is a SCSI disk, you might run into a - problem with probing order, which will cause the system to attempt - to use the ZIP drive as the root device. This will cause a boot - failure, unless you happen to have a FreeBSD root file-system on - your ZIP disk! In this case, you will need to <quote>wire - down</quote> the root disk, i.e. force the kernel to bind a - specific device to <filename>/dev/da0</filename>, the root SCSI - disk. It will then assign the ZIP disk to the next available SCSI - disk, e.g. <literal>/dev/da1</literal>. To wire down your SCSI hard - drive as <literal>da0</literal>, change the line - - <programlisting>device da0</programlisting> - - to - - <programlisting>disk da0 at scbus0 target 0 unit 0</programlisting></para> - - <para>You may need to change the target above to match the SCSI ID of - your disk drive. You should also wire down the scbus0 entry to your - controller. For example, if you have an Adaptec 15xx controller, - you would change - - <programlisting>controller scbus0</programlisting> - - to - - <programlisting>controller scbus0 at aha0</programlisting></para> - - <para>Lastly, as long as you're editing the kernel config, you - can take the opportunity to remove all the unnecessary drivers. This - should be done with a great deal of caution, and only if you feel - confident about making kernel modifications. Removing unnecessary - drivers will reduce the kernel size, leaving more memory available - for your applications. To determine which drivers are not needed, - go to the end of the file <filename>/var/log/messages</filename>, and look for lines - reading "not found". Then, comment out these devices in your config - file. You can also change other options to reduce the size and - increase the speed of your kernel. Read the section on rebuilding - your kernel for more complete information.</para> - </listitem> - - <listitem> - <para>Now it's time to compile the kernel:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput> -&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput> -&prompt.root; <userinput>make clean depend && make all install</userinput></screen> - </listitem> - </orderedlist> - - <para>After the kernel is rebuilt, you'll need to reboot. Make sure the - ZIP drive is connected to the parallel port before the boot begins. You - should see the ZIP drive show up in the boot messages as device vpo0 or - vpo1, depending on which parallel port the drive is attached to. It - should also show which device file the ZIP drive has been bound to. This - will be <filename>/dev/da0</filename> if you have no other SCSI disks in - the system, or <filename>/dev/da1</filename> if you have a SCSI hard - disk wired down as the root device.</para> - </sect1> - - <sect1> - <title>Mounting ZIP disks</title> - - <para>To access the ZIP disk, you simply mount it like any other disk - device. The file-system is represented as slice 4 on the device, so for - SCSI or parallel ZIP disks, you would use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/da1s4 /mnt</userinput></screen> - - <para>For IDE ZIP drives, use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/wd1s4 /mnt</userinput></screen> - - <para>It will also be helpful to update <filename>/etc/fstab</filename> to - make mounting easier. Add a line like the following, edited to suit your - system: - - <programlisting>/dev/da1s4 /zip msdos rw,noauto 0 0</programlisting> - - and create the directory <filename>/zip</filename>.</para> - - <para>Then, you can mount simply by typing - - <screen>&prompt.root; <userinput>mount /zip</userinput></screen> - - and unmount by typing - - <screen>&prompt.root; <userinput>umount /zip</userinput></screen></para> - - <para>For more information on the format of - <filename>/etc/fstab</filename>, see &man.fstab.5;.</para> - - <para>You can also create a FreeBSD file-system on the ZIP disk - using &man.newfs.8;. However, the disk will only be usable on a FreeBSD - system, or perhaps a few other Unix clones that recognize FreeBSD - file-systems. (Definitely not DOS or Windows.)</para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/books/Makefile b/en_US.ISO8859-1/books/Makefile deleted file mode 100644 index 55d37bcff9..0000000000 --- a/en_US.ISO8859-1/books/Makefile +++ /dev/null @@ -1,12 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/books/Makefile,v 1.6 1999/09/17 23:45:03 nik Exp $ - -SUBDIR = faq -SUBDIR+= fdp-primer -SUBDIR+= handbook -SUBDIR+= porters-handbook -SUBDIR+= ppp-primer - -ROOT_SYMLINKS= faq handbook - -DOC_PREFIX?= ${.CURDIR}/../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/Makefile.inc b/en_US.ISO8859-1/books/Makefile.inc deleted file mode 100644 index b9219d69af..0000000000 --- a/en_US.ISO8859-1/books/Makefile.inc +++ /dev/null @@ -1,5 +0,0 @@ -# -# $FreeBSD$ -# - -DESTDIR?= ${DOCDIR}/en_US.ISO_8859-1/books/${.CURDIR:T} diff --git a/en_US.ISO8859-1/books/arch-handbook/Makefile b/en_US.ISO8859-1/books/arch-handbook/Makefile deleted file mode 100644 index d9d7ad1454..0000000000 --- a/en_US.ISO8859-1/books/arch-handbook/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# -# $FreeBSD$ -# -# Build the FreeBSD Developers' Handbook. -# - -MAINTAINER=asmodai@FreeBSD.org - -DOC?= book - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml - -# Entities - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml deleted file mode 100644 index bd58d4a25a..0000000000 --- a/en_US.ISO8859-1/books/arch-handbook/book.sgml +++ /dev/null @@ -1,3751 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.5 2000/11/06 13:52:26 murray Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; -]> - -<book> - <bookinfo> - <title>FreeBSD Developers' Handbook</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - <affiliation> - <address> - <email>doc@FreeBSD.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 2000</pubdate> - - <copyright> - <year>2000</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - &bookinfo.legalnotice; - - <abstract> - <para>Welcome to the Developers' Handbook.</para> - </abstract> - </bookinfo> - - <part id="introduction"> - <title>Introduction</title> - - <chapter id="developmentplatform"> - <title>Developing on FreeBSD</title> - - <para>This will need to discuss FreeBSD as a development - platform, the vision of BSD, architectural overview, layout of - /usr/src, history, etc.</para> - - <para>Thank you for considering FreeBSD as your development - platform! We hope it will not let you down.</para> - </chapter> - - <chapter id="bsdvision"> - <title>The BSD Vision</title> - - <para></para> - </chapter> - - <chapter id="archoverview"> - <title>Architectural Overview</title> - - <para></para> - </chapter> - - <chapter id="sourcelayout"> - <title>The Layout of /usr/src</title> - - <para>The complete source code to FreeBSD is available from our - public CVS repository. The source code is normally installed in - <filename class=directory>/usr/src</filename> which contains the - following subdirectories.</para> - - <para> - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Directory</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename class=directory>bin/</filename></entry> - <entry>Source for files in - <filename>/bin</filename></entry> - </row> - - <row> - <entry><filename class=directory>contrib/</filename></entry> - <entry>Source for files from contribued software.</entry> - </row> - - <row> - <entry><filename class=directory>crypto/</filename></entry> - <entry>DES source</entry> - </row> - - <row> - <entry><filename class=directory>etc/</filename></entry> - <entry>Source for files in <filename - class=directory>/etc</filename></entry> - </row> - - <row> - <entry><filename class=directory>games/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/games</filename></entry> - </row> - - <row> - <entry><filename class=directory>gnu/</filename></entry> - <entry>Utilities covered by the GNU Public License</entry> - </row> - - <row> - <entry><filename class=directory>include/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/include</filename></entry> - </row> - - <row> - <entry><filename - class=directory>kerberosIV/</filename></entry> - <entry>Source for Kerbereros version IV</entry> - </row> - - <row> - <entry><filename - class=directory>kerberos5/</filename></entry> - <entry>Source for Kerbereros version 5</entry> - </row> - - <row> - <entry><filename class=directory>lib/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/lib</filename></entry> - </row> - - <row> - <entry><filename class=directory>libexec/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/libexec</filename></entry> - </row> - - <row> - <entry><filename - class=directory>release/</filename></entry> - <entry>Files required to produce a FreeBSD release</entry> - </row> - - <row> - <entry><filename class=directory>sbin/</filename></entry> - <entry>Source for files in <filename - class=directory>/sbin</filename></entry> - </row> - - <row> - <entry><filename class=directory>secure/</filename></entry> - <entry>FreeSec sources</entry> - </row> - - <row> - <entry><filename class=directory>share/</filename></entry> - <entry>Source for files in <filename - class=directory>/sbin</filename></entry> - </row> - - <row> - <entry><filename class=directory>sys/</filename></entry> - <entry>Kernel source files</entry> - </row> - - <row> - <entry><filename class=directory>tools/</filename></entry> - <entry>Tools used for maintenance and testing of - FreeBSD</entry> - </row> - - <row> - <entry><filename - class=directory>usr.bin/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/bin</filename></entry> - </row> - - <row> - <entry><filename - class=directory>usr.sbin/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/sbin</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - </para> - - </chapter> - </part> - - <part id="Basics"> - <title>Basics</title> - - <chapter id="programming-tools"> - <title>Programming Tools</title> - - <para><emphasis>This chapter was written by James Raynard. - Modifications for the Developer's Handbook by Murray Stokely. - </emphasis></para> - - <sect1><title>Synopsis</title> - - <para>This document is an introduction to using some of the - programming tools supplied with FreeBSD, although much of it - will be applicable to many other versions of Unix. It does - <emphasis>not</emphasis> attempt to describe coding in any - detail. Most of the document assumes little or no previous - programming knowledge, although it is hoped that most - programmers will find something of value in it</para> - - </sect1> - - <sect1><title>Introduction</title> - - <para>FreeBSD offers an excellent development environment. - Compilers for C, C++, and Fortran and an assembler come with the - basic system, not to mention a Perl interpreter and classic Unix - tools such as <command>sed</command> and <command>awk</command>. - If that is not enough, there are many more compilers and - interpreters in the Ports collection. FreeBSD is very - compatible with standards such as <acronym>POSIX</acronym> and - <acronym>ANSI</acronym> C, as well with its own BSD heritage, so - it is possible to write applications that will compile and run - with little or no modification on a wide range of - platforms.</para> - - <para>However, all this power can be rather overwhelming at - first if you've never written programs on a Unix platform - before. This document aims to help you get up and running, - without getting too deeply into more advanced topics. The - intention is that this document should give you enough of the - basics to be able to make some sense of the - documentation.</para> - - <para>Most of the document requires little or no knowledge of - programming, although it does assume a basic competence with - using Unix and a willingness to learn!</para> - - </sect1> - - <sect1> - <title>Introduction to Programming</title> - - <para>A program is a set of instructions that tell the computer - to do various things; sometimes the instruction it has to - perform depends on what happened when it performed a previous - instruction. This section gives an overview of the two main - ways in which you can give these instructions, or - <quote>commands</quote> as they are usually called. One way - uses an <firstterm>interpreter</firstterm>, the other a - <firstterm>compiler</firstterm>. As human languages are too - difficult for a computer to understand in an unambiguous way, - commands are usually written in one or other languages specially - designed for the purpose.</para> - - <sect2> - <title>Interpreters</title> - - <para>With an interpreter, the language comes as an environment, - where you type in commands at a prompt and the environment - executes them for you. For more complicated programs, you can - type the commands into a file and get the interpreter to load - the file and execute the commands in it. If anything goes - wrong, many interpreters will drop you into a debugger to help - you track down the problem.</para> - - <para>The advantage of this is that you can see the results of - your commands immediately, and mistakes can be corrected - readily. The biggest disadvantage comes when you want to - share your programs with someone. They must have the same - interpreter, or you must have some way of giving it to them, - and they need to understand how to use it. Also users may not - appreciate being thrown into a debugger if they press the - wrong key! From a performance point of view, interpreters can - use up a lot of memory, and generally do not generate code as - efficiently as compilers.</para> - - <para>In my opinion, interpreted languages are the best way to - start if you have not done any programming before. This kind - of environment is typically found with languages like Lisp, - Smalltalk, Perl and Basic. It could also be argued that the - Unix shell (<command>sh</command>, <command>csh</command>) is itself an - interpreter, and many people do in fact write shell - <quote>scripts</quote> to help with various - <quote>housekeeping</quote> tasks on their machine. Indeed, part - of the original Unix philosophy was to provide lots of small - utility programs that could be linked together in shell - scripts to perform useful tasks.</para> - </sect2> - - <sect2> - <title>Interpreters available with FreeBSD</title> - - <para>Here is a list of interpreters that are available as - <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink>, with a brief discussion of some of the - more popular interpreted languages.</para> - - <para>To get one of these packages, all you need to do is to - click on the hotlink for the package, then run</para> - - <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput> - </screen> - - <para>as root. Obviously, you will need to have a fully - functional FreeBSD 2.1.0 or later system for the package to - work!</para> - - <variablelist> - <varlistentry> - <term><acronym>BASIC</acronym></term> - - <listitem> - <para>Short for Beginner's All-purpose Symbolic - Instruction Code. Developed in the 1950s for teaching - University students to program and provided with every - self-respecting personal computer in the 1980s, - <acronym>BASIC</acronym> has been the first programming - language for many programmers. It's also the foundation - for Visual Basic.</para> - - <para>The <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater - Basic Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil - Cockroft's Basic Interpreter</ulink> (formerly Rabbit - Basic) are available as FreeBSD <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Lisp</term> - - <listitem> - <para>A language that was developed in the late 1950s as - an alternative to the <quote>number-crunching</quote> - languages that were popular at the time. Instead of - being based on numbers, Lisp is based on lists; in fact - the name is short for <quote>List Processing</quote>. - Very popular in AI (Artificial Intelligence) - circles.</para> - - <para>Lisp is an extremely powerful and sophisticated - language, but can be rather large and unwieldy.</para> - - <para>FreeBSD has <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU - Common Lisp</ulink> available as a package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Perl</term> - - <listitem> - <para>Very popular with system administrators for writing - scripts; also often used on World Wide Web servers for - writing <acronym>CGI</acronym> scripts.</para> - - <para>The latest version (version 5) comes with FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Scheme</term> - - <listitem> - <para>A dialect of Lisp that is rather more compact and - cleaner than Common Lisp. Popular in Universities as it - is simple enough to teach to undergraduates as a first - language, while it has a high enough level of - abstraction to be used in research work.</para> - - <para>FreeBSD has packages of the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk - Scheme Interpreter</ulink>, the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT - Scheme Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM - Scheme Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Icon</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The - Icon Programming Language</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Logo</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian - Harvey's LOGO Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Python</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/python-1.2">The - Python Object-Oriented Programming - Language</ulink></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Compilers</title> - - <para>Compilers are rather different. First of all, you write - your code in a file (or files) using an editor. You then run - the compiler and see if it accepts your program. If it did - not compile, grit your teeth and go back to the editor; if it - did compile and gave you a program, you can run it either at a - shell command prompt or in a debugger to see if it works - properly. - - <footnote> - <para>If you run it in the shell, you may get a core - dump.</para> - </footnote></para> - - <para>Obviously, this is not quite as direct as using an - interpreter. However it allows you to do a lot of things - which are very difficult or even impossible with an - interpreter, such as writing code which interacts closely with - the operating system—or even writing your own operating - system! It's also useful if you need to write very efficient - code, as the compiler can take its time and optimise the code, - which would not be acceptable in an interpreter. And - distributing a program written for a compiler is usually more - straightforward than one written for an interpreter—you - can just give them a copy of the executable, assuming they - have the same operating system as you.</para> - - <para>Compiled languages include Pascal, C and C++. C and C++ - are rather unforgiving languages, and best suited to more - experienced programmers; Pascal, on the other hand, was - designed as an educational language, and is quite a good - language to start with. Unfortunately, FreeBSD doesn't have - any Pascal support, except for a Pascal-to-C converter in the - ports.</para> - - <para>As the edit-compile-run-debug cycle is rather tedious when - using separate programs, many commercial compiler makers have - produced Integrated Development Environments - - (<acronym>IDE</acronym>s for short). FreeBSD does not have an - <acronym>IDE</acronym> as such; however it is possible to use Emacs - for this purpose. This is discussed in <xref - linkend="emacs">.</para> - </sect2> - - - </sect1> - - - <sect1> - <title>Compiling with <command>cc</command></title> - - <para>This section deals only with the GNU compiler for C and C++, - since that comes with the base FreeBSD system. It can be - invoked by either <command>cc</command> or <command>gcc</command>. The - details of producing a program with an interpreter vary - considerably between interpreters, and are usually well covered - in the documentation and on-line help for the - interpreter.</para> - - <para>Once you've written your masterpiece, the next step is to - convert it into something that will (hopefully!) run on FreeBSD. - This usually involves several steps, each of which is done by a - separate program.</para> - - <procedure> - <step> - <para>Pre-process your source code to remove comments and do - other tricks like expanding macros in C.</para> - </step> - - <step> - <para>Check the syntax of your code to see if you have obeyed - the rules of the language. If you have not, it will - complain!</para> - </step> - - <step> - <para>Convert the source code into assembly - language—this is very close to machine code, but still - understandable by humans. Allegedly. - - <footnote> - <para>To be strictly accurate, <command>cc</command> converts the - source code into its own, machine-independent - <firstterm>p-code</firstterm> instead of assembly language at - this stage.</para> - </footnote></para> - </step> - - <step> - <para>Convert the assembly language into machine - code—yep, we are talking bits and bytes, ones and - zeros here.</para> - </step> - - <step> - <para>Check that you have used things like functions and - global variables in a consistent way. For example, if you - have called a non-existent function, it will - complain.</para> - </step> - - <step> - <para>If you are trying to produce an executable from several - source code files, work out how to fit them all - together.</para> - </step> - - <step> - <para>Work out how to produce something that the system's - run-time loader will be able to load into memory and - run.</para> - </step> - - <step> - <para>Finally, write the executable on the file system.</para> - </step> - </procedure> - - <para>The word <firstterm>compiling</firstterm> is often used to refer to - just steps 1 to 4—the others are referred to as - <firstterm>linking</firstterm>. Sometimes step 1 is referred to as - <firstterm>pre-processing</firstterm> and steps 3-4 as - <firstterm>assembling</firstterm>.</para> - - <para>Fortunately, almost all this detail is hidden from you, as - <command>cc</command> is a front end that manages calling all these - programs with the right arguments for you; simply typing</para> - - <screen>&prompt.user; <userinput>cc foobar.c</> - </screen> - - <para>will cause <filename>foobar.c</filename> to be compiled by all the - steps above. If you have more than one file to compile, just do - something like</para> - - <screen>&prompt.user; <userinput>cc foo.c bar.c</> - </screen> - - <para>Note that the syntax checking is just that—checking - the syntax. It will not check for any logical mistakes you may - have made, like putting the program into an infinite loop, or - using a bubble sort when you meant to use a binary - sort. - - <footnote> - <para>In case you didn't know, a binary sort is an efficient - way of sorting things into order and a bubble sort - isn't.</para> - </footnote></para> - - <para>There are lots and lots of options for <command>cc</command>, which - are all in the man page. Here are a few of the most important - ones, with examples of how to use them.</para> - - <variablelist> - <varlistentry> - <term><option>-o <replaceable>filename</replaceable></option></term> - - <listitem> - <para>The output name of the file. If you do not use this - option, <command>cc</command> will produce an executable called - <filename>a.out</filename>. - - <footnote> - <para>The reasons for this are buried in the mists of - history.</para> - </footnote></para> - - <informalexample> - <screen>&prompt.user; <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -&prompt.user; <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></> - </screen> - </informalexample> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Just compile the file, do not link it. Useful for toy - programs where you just want to check the syntax, or if - you are using a <filename>Makefile</filename>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -c foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an <firstterm>object file</firstterm> (not an - executable) called <filename>foobar.o</filename>. This - can be linked together with other object files into an - executable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Create a debug version of the executable. This makes - the compiler put information into the executable about - which line of which source file corresponds to which - function call. A debugger can use this information to show - the source code as you step through the program, which is - <emphasis>very</emphasis> useful; the disadvantage is that - all this extra information makes the program much bigger. - Normally, you compile with <option>-g</option> while you - are developing a program and then compile a <quote>release - version</quote> without <option>-g</option> when you're - satisfied it works properly.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -g foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce a debug version of the - program. - - <footnote> - <para>Note, we didn't use the <option>-o</option> flag - to specify the executable name, so we will get an - executable called <filename>a.out</filename>. - Producing a debug version called - <filename>foobar</filename> is left as an exercise for - the reader!</para> - </footnote></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-O</option></term> - - <listitem> - <para>Create an optimised version of the executable. The - compiler performs various clever tricks to try and produce - an executable that runs faster than normal. You can add a - number after the <option>-O</option> to specify a higher - level of optimisation, but this often exposes bugs in the - compiler's optimiser. For instance, the version of - <command>cc</command> that comes with the 2.1.0 release of - FreeBSD is known to produce bad code with the - <option>-O2</option> option in some circumstances.</para> - - <para>Optimisation is usually only turned on when compiling - a release version.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an optimised version of - <filename>foobar</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following three flags will force <command>cc</command> - to check that your code complies to the relevant international - standard, often referred to as the <acronym>ANSI</acronym> - standard, though strictly speaking it is an - <acronym>ISO</acronym> standard.</para> - - <variablelist> - <varlistentry> - <term><option>-Wall</option></term> - - <listitem> - <para>Enable all the warnings which the authors of - <command>cc</command> believe are worthwhile. Despite the - name, it will not enable all the warnings - <command>cc</command> is capable of.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ansi</option></term> - - <listitem> - <para>Turn off most, but not all, of the - non-<acronym>ANSI</acronym> C features provided by - <command>cc</command>. Despite the name, it does not - guarantee strictly that your code will comply to the - standard.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-pedantic</option></term> - - <listitem> - <para>Turn off <emphasis>all</emphasis> - <command>cc</command>'s non-<acronym>ANSI</acronym> C - features.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Without these flags, <command>cc</command> will allow you to - use some of its non-standard extensions to the standard. Some - of these are very useful, but will not work with other - compilers—in fact, one of the main aims of the standard is - to allow people to write code that will work with any compiler - on any system. This is known as <firstterm>portable - code</firstterm>.</para> - - <para>Generally, you should try to make your code as portable as - possible, as otherwise you may have to completely re-write the - program later to get it to work somewhere else—and who - knows what you may be using in a few years time?</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an executable <filename>foobar</filename> - after checking <filename>foobar.c</filename> for standard - compliance.</para> - - <variablelist> - <varlistentry> - <term><option>-l<replaceable>library</replaceable></option></term> - - <listitem> - <para>Specify a function library to be used during when - linking.</para> - - <para>The most common example of this is when compiling a - program that uses some of the mathematical functions in C. - Unlike most other platforms, these are in a separate - library from the standard C one and you have to tell the - compiler to add it.</para> - - <para>The rule is that if the library is called - <filename>lib<replaceable>something</replaceable>.a</filename>, - you give <command>cc</command> the argument - <option>-l<replaceable>something</replaceable></option>. - For example, the math library is - <filename>libm.a</filename>, so you give - <command>cc</command> the argument <option>-lm</option>. - A common <quote>gotcha</quote> with the math library is - that it has to be the last library on the command - line.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - - <para>This will link the math library functions into - <filename>foobar</filename>.</para> - - <para>If you are compiling C++ code, you need to add - <option>-lg++</option>, or <option>-lstdc++</option> if - you are using FreeBSD 2.2 or later, to the command line - argument to link the C++ library functions. - Alternatively, you can run <command>c++</command> instead - of <command>cc</command>, which does this for you. - <command>c++</command> can also be invoked as - <command>g++</command> on FreeBSD.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -&prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput> - </screen> - </informalexample> - - <para>Each of these will both produce an executable - <filename>foobar</filename> from the C++ source file - <filename>foobar.cc</filename>. Note that, on Unix - systems, C++ source files traditionally end in - <filename>.C</filename>, <filename>.cxx</filename> or - <filename>.cc</filename>, rather than the - MS-DOS style - <filename>.cpp</filename> (which was already used for - something else). <command>gcc</command> used to rely on - this to work out what kind of compiler to use on the - source file; however, this restriction no longer applies, - so you may now call your C++ files - <filename>.cpp</filename> with impunity!</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Common <command>cc</command> Queries and Problems</title> - - <qandaset> - <qandaentry> - <question> - <para>I am trying to write a program which uses the - <function>sin()</function> function and I get an error - like this. What does it mean?</para> - - <informalexample> - <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - </screen> - </informalexample> - </question> - - <answer> - <para>When using mathematical functions like - <function>sin()</function>, you have to tell - <command>cc</command> to link in the math library, like - so:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>All right, I wrote this simple program to practice - using <option>-lm</option>. All it does is raise 2.1 to - the power of 6.</para> - - <informalexample> - <programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - </programlisting> - </informalexample> - - <para>and I compiled it as:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc temp.c -lm</userinput> - </screen> - </informalexample> - - <para>like you said I should, but I get this when I run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000 - </screen> - </informalexample> - - <para>This is <emphasis>not</emphasis> the right answer! - What is going on?</para> - </question> - - <answer> - <para>When the compiler sees you call a function, it - checks if it has already seen a prototype for it. If it - has not, it assumes the function returns an - <type>int</type>, which is definitely not what you want - here.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>So how do I fix this?</para> - </question> - - <answer> - <para>The prototypes for the mathematical functions are in - <filename>math.h</filename>. If you include this file, - the compiler will be able to find the prototype and it - will stop doing strange things to your - calculation!</para> - - <informalexample> - <programlisting>#include <math.h> -#include <stdio.h> - -int main() { -... - </programlisting> - </informalexample> - - <para>After recompiling it as you did before, run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121 - </screen> - </informalexample> - - <para>If you are using any of the mathematical functions, - <emphasis>always</emphasis> include - <filename>math.h</filename> and remember to link in the - math library.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled a file called - <filename>foobar.c</filename> and I cannot find an - executable called <filename>foobar</filename>. Where's - it gone?</para> - </question> - - <answer> - <para>Remember, <command>cc</command> will call the - executable <filename>a.out</filename> unless you tell it - differently. Use the - <option>-o <replaceable>filename</replaceable></option> - option:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, I have an executable called - <filename>foobar</filename>, I can see it when I run - <command>ls</command>, but when I type in - <command>foobar</command> at the command prompt it tells - me there is no such file. Why can it not find - it?</para> - </question> - - <answer> - <para>Unlike MS-DOS, Unix does not - look in the current directory when it is trying to find - out which executable you want it to run, unless you tell - it to. Either type <command>./foobar</command>, which - means <quote>run the file called - <filename>foobar</filename> in the current - directory</quote>, or change your <systemitem - class=environvar>PATH</systemitem> environment - variable so that it looks something like</para> - - <informalexample> - <screen>bin:/usr/bin:/usr/local/bin:. - </screen> - </informalexample> - - <para>The dot at the end means <quote>look in the current - directory if it is not in any of the - others</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I called my executable <filename>test</filename>, - but nothing happens when I run it. What is going - on?</para> - </question> - - <answer> - <para>Most Unix systems have a program called - <command>test</command> in <filename>/usr/bin</filename> - and the shell is picking that one up before it gets to - checking the current directory. Either type:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./test</userinput> - </screen> - </informalexample> - - <para>or choose a better name for your program!</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled my program and it seemed to run all right - at first, then there was an error and it said something - about <errorname>core dumped</errorname>. What does that - mean?</para> - </question> - - <answer> - <para>The name <firstterm>core dump</firstterm> dates back - to the very early days of Unix, when the machines used - core memory for storing data. Basically, if the program - failed under certain conditions, the system would write - the contents of core memory to disk in a file called - <filename>core</filename>, which the programmer could - then pore over to find out what went wrong.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Fascinating stuff, but what I am supposed to do - now?</para> - </question> - - <answer> - <para>Use <command>gdb</command> to analyse the core (see - <xref linkend="debugging">).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When my program dumped core, it said something about - a <errorname>segmentation fault</errorname>. What's - that?</para> - </question> - - <answer> - <para>This basically means that your program tried to - perform some sort of illegal operation on memory; Unix - is designed to protect the operating system and other - programs from rogue programs.</para> - - <para>Common causes for this are:</para> - - <itemizedlist> - <listitem> - <para>Trying to write to a <symbol>NULL</symbol> - pointer, eg</para> - - <programlisting>char *foo = NULL; -strcpy(foo, "bang!"); - </programlisting> - </listitem> - - <listitem> - <para>Using a pointer that hasn't been initialised, - eg</para> - - <programlisting>char *foo; -strcpy(foo, "bang!"); - </programlisting> - - <para>The pointer will have some random value that, - with luck, will point into an area of memory that - isn't available to your program and the kernel will - kill your program before it can do any damage. If - you're unlucky, it'll point somewhere inside your - own program and corrupt one of your data structures, - causing the program to fail mysteriously.</para> - </listitem> - - <listitem> - <para>Trying to access past the end of an array, - eg</para> - - <programlisting>int bar[20]; -bar[27] = 6; - </programlisting> - </listitem> - - <listitem> - <para>Trying to store something in read-only memory, - eg</para> - - <programlisting>char *foo = "My string"; -strcpy(foo, "bang!"); - </programlisting> - - <para>Unix compilers often put string literals like - <literal>"My string"</literal> into read-only areas - of memory.</para> - </listitem> - - <listitem> - <para>Doing naughty things with - <function>malloc()</function> and - <function>free()</function>, eg</para> - - <programlisting>char bar[80]; -free(bar); - </programlisting> - - <para>or</para> - - <programlisting>char *foo = malloc(27); -free(foo); -free(foo); - </programlisting> - </listitem> - </itemizedlist> - - <para>Making one of these mistakes will not always lead to - an error, but they are always bad practice. Some - systems and compilers are more tolerant than others, - which is why programs that ran well on one system can - crash when you try them on an another.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Sometimes when I get a core dump it says - <errorname>bus error</errorname>. It says in my Unix - book that this means a hardware problem, but the - computer still seems to be working. Is this - true?</para> - </question> - - <answer> - <para>No, fortunately not (unless of course you really do - have a hardware problem…). This is usually - another way of saying that you accessed memory in a way - you shouldn't have.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>This dumping core business sounds as though it could - be quite useful, if I can make it happen when I want to. - Can I do this, or do I have to wait until there's an - error?</para> - </question> - - <answer> - <para>Yes, just go to another console or xterm, do</para> - - <screen>&prompt.user; <userinput>ps</userinput> - </screen> - - <para>to find out the process ID of your program, and - do</para> - - <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput> - </screen> - - <para>where - <parameter><replaceable>pid</replaceable></parameter> is - the process ID you looked up.</para> - - <para>This is useful if your program has got stuck in an - infinite loop, for instance. If your program happens to - trap <symbol>SIGABRT</symbol>, there are several other - signals which have a similar effect.</para> - </answer> - </qandaentry> - </qandaset> - </sect2> - </sect1> - - <sect1> - <title>Make</title> - - <sect2> - <title>What is <command>make</command>?</title> - - <para>When you're working on a simple program with only one or - two source files, typing in</para> - - <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput> - </screen> - - <para>is not too bad, but it quickly becomes very tedious when - there are several files—and it can take a while to - compile, too.</para> - - <para>One way to get around this is to use object files and only - recompile the source file if the source code has changed. So - we could have something like:</para> - - <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip - </screen> - - <para>if we'd changed <filename>file37.c</filename>, but not any - of the others, since the last time we compiled. This may - speed up the compilation quite a bit, but doesn't solve the - typing problem.</para> - - <para>Or we could write a shell script to solve the typing - problem, but it would have to re-compile everything, making it - very inefficient on a large project.</para> - - <para>What happens if we have hundreds of source files lying - about? What if we're working in a team with other people who - forget to tell us when they've changed one of their source - files that we use?</para> - - <para>Perhaps we could put the two solutions together and write - something like a shell script that would contain some kind of - magic rule saying when a source file needs compiling. Now all - we need now is a program that can understand these rules, as - it's a bit too complicated for the shell.</para> - - <para>This program is called <command>make</command>. It reads - in a file, called a <firstterm>makefile</firstterm>, that - tells it how different files depend on each other, and works - out which files need to be re-compiled and which ones don't. - For example, a rule could say something like <quote>if - <filename>fromboz.o</filename> is older than - <filename>fromboz.c</filename>, that means someone must have - changed <filename>fromboz.c</filename>, so it needs to be - re-compiled.</quote> The makefile also has rules telling - make <emphasis>how</emphasis> to re-compile the source file, - making it a much more powerful tool.</para> - - <para>Makefiles are typically kept in the same directory as the - source they apply to, and can be called - <filename>makefile</filename>, <filename>Makefile</filename> - or <filename>MAKEFILE</filename>. Most programmers use the - name <filename>Makefile</filename>, as this puts it near the - top of a directory listing, where it can easily be - seen. - - <footnote> - <para>They don't use the <filename>MAKEFILE</filename> form - as block capitals are often used for documentation files - like <filename>README</filename>.</para> - </footnote></para> - </sect2> - - <sect2> - <title>Example of using <command>make</command></title> - - <para>Here's a very simple make file:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - </programlisting> - - <para>It consists of two lines, a dependency line and a creation - line.</para> - - <para>The dependency line here consists of the name of the - program (known as the <firstterm>target</firstterm>), followed - by a colon, then whitespace, then the name of the source file. - When <command>make</command> reads this line, it looks to see - if <filename>foo</filename> exists; if it exists, it compares - the time <filename>foo</filename> was last modified to the - time <filename>foo.c</filename> was last modified. If - <filename>foo</filename> does not exist, or is older than - <filename>foo.c</filename>, it then looks at the creation line - to find out what to do. In other words, this is the rule for - working out when <filename>foo.c</filename> needs to be - re-compiled.</para> - - <para>The creation line starts with a <token>tab</token> (press - the <keycap>tab</keycap> key) and then the command you would - type to create <filename>foo</filename> if you were doing it - at a command prompt. If <filename>foo</filename> is out of - date, or does not exist, <command>make</command> then executes - this command to create it. In other words, this is the rule - which tells make how to re-compile - <filename>foo.c</filename>.</para> - - <para>So, when you type <userinput>make</userinput>, it will - make sure that <filename>foo</filename> is up to date with - respect to your latest changes to <filename>foo.c</filename>. - This principle can be extended to - <filename>Makefile</filename>s with hundreds of - targets—in fact, on FreeBSD, it is possible to compile - the entire operating system just by typing <userinput>make - world</userinput> in the appropriate directory!</para> - - <para>Another useful property of makefiles is that the targets - don't have to be programs. For instance, we could have a make - file that looks like this:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - </programlisting> - - <para>We can tell make which target we want to make by - typing:</para> - - <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput> - </screen> - - <para><command>make</command> will then only look at that target - and ignore any others. For example, if we type - <userinput>make foo</userinput> with the makefile above, make - will ignore the <action>install</action> target.</para> - - <para>If we just type <userinput>make</userinput> on its own, - make will always look at the first target and then stop - without looking at any others. So if we typed - <userinput>make</userinput> here, it will just go to the - <action>foo</action> target, re-compile - <filename>foo</filename> if necessary, and then stop without - going on to the <action>install</action> target.</para> - - <para>Notice that the <action>install</action> target doesn't - actually depend on anything! This means that the command on - the following line is always executed when we try to make that - target by typing <userinput>make install</userinput>. In this - case, it will copy <filename>foo</filename> into the user's - home directory. This is often used by application makefiles, - so that the application can be installed in the correct - directory when it has been correctly compiled.</para> - - <para>This is a slightly confusing subject to try and explain. - If you don't quite understand how <command>make</command> - works, the best thing to do is to write a simple program like - <quote>hello world</quote> and a make file like the one above - and experiment. Then progress to using more than one source - file, or having the source file include a header file. The - <command>touch</command> command is very useful here—it - changes the date on a file without you having to edit - it.</para> - </sect2> - - <sect2> - <title>FreeBSD Makefiles</title> - - <para>Makefiles can be rather complicated to write. Fortunately, - BSD-based systems like FreeBSD come with some very powerful - ones as part of the system. One very good example of this is - the FreeBSD ports system. Here's the essential part of a - typical ports <filename>Makefile</filename>:</para> - - <programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - </programlisting> - - <para>Now, if we go to the directory for this port and type - <userinput>make</userinput>, the following happens:</para> - - <procedure> - <step> - <para>A check is made to see if the source code for this - port is already on the system.</para> - </step> - - <step> - <para>If it isn't, an FTP connection to the URL in - <symbol>MASTER_SITES</symbol> is set up to download the - source.</para> - </step> - - <step> - <para>The checksum for the source is calculated and compared - it with one for a known, good, copy of the source. This - is to make sure that the source was not corrupted while in - transit.</para> - </step> - - <step> - <para>Any changes required to make the source work on - FreeBSD are applied—this is known as - <firstterm>patching</firstterm>.</para> - </step> - - <step> - <para>Any special configuration needed for the source is - done. (Many Unix program distributions try to work out - which version of Unix they are being compiled on and which - optional Unix features are present—this is where - they are given the information in the FreeBSD ports - scenario).</para> - </step> - - <step> - <para>The source code for the program is compiled. In - effect, we change to the directory where the source was - unpacked and do <command>make</command>—the - program's own make file has the necessary information to - build the program.</para> - </step> - - <step> - <para>We now have a compiled version of the program. If we - wish, we can test it now; when we feel confident about the - program, we can type <userinput>make install</userinput>. - This will cause the program and any supporting files it - needs to be copied into the correct location; an entry is - also made into a <database>package database</database>, so - that the port can easily be uninstalled later if we change - our mind about it.</para> - </step> - </procedure> - - <para>Now I think you'll agree that's rather impressive for a - four line script!</para> - - <para>The secret lies in the last line, which tells - <command>make</command> to look in the system makefile called - <filename>bsd.port.mk</filename>. It's easy to overlook this - line, but this is where all the clever stuff comes - from—someone has written a makefile that tells - <command>make</command> to do all the things above (plus a - couple of other things I didn't mention, including handling - any errors that may occur) and anyone can get access to that - just by putting a single line in their own make file!</para> - - <para>If you want to have a look at these system makefiles, - they're in <filename>/usr/share/mk</filename>, but it's - probably best to wait until you've had a bit of practice with - makefiles, as they are very complicated (and if you do look at - them, make sure you have a flask of strong coffee - handy!)</para> - </sect2> - - <sect2> - <title>More advanced uses of <command>make</command></title> - - <para><command>Make</command> is a very powerful tool, and can - do much more than the simple example above shows. - Unfortunately, there are several different versions of - <command>make</command>, and they all differ considerably. - The best way to learn what they can do is probably to read the - documentation—hopefully this introduction will have - given you a base from which you can do this.</para> - - <para>The version of make that comes with FreeBSD is the - <application>Berkeley make</application>; there is a tutorial - for it in <filename>/usr/share/doc/psd/12.make</filename>. To - view it, do</para> - - <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput> - </screen> - - <para>in that directory.</para> - - <para>Many applications in the ports use <application>GNU - make</application>, which has a very good set of - <quote>info</quote> pages. If you have installed any of these - ports, <application>GNU make</application> will automatically - have been installed as <command>gmake</command>. It's also - available as a port and package in its own right.</para> - - <para>To view the info pages for <application>GNU - make</application>, you will have to edit the - <filename>dir</filename> file in the - <filename>/usr/local/info</filename> directory to add an entry - for it. This involves adding a line like</para> - - <programlisting> * Make: (make). The GNU Make utility. - </programlisting> - - <para>to the file. Once you have done this, you can type - <userinput>info</userinput> and then select - <guimenuitem>make</guimenuitem> from the menu (or in - <application>Emacs</application>, do <userinput>C-h - i</userinput>).</para> - </sect2> - </sect1> - - <sect1 id="debugging"> - <title>Debugging</title> - - <sect2> - <title>The Debugger</title> - - <para>The debugger that comes with FreeBSD is called - <command>gdb</command> (<application>GNU - debugger</application>). You start it up by typing</para> - - <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput> - </screen> - - <para>although most people prefer to run it inside - <application>Emacs</application>. You can do this by:</para> - - <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput> - </screen> - - <para>Using a debugger allows you to run the program under more - controlled circumstances. Typically, you can step through the - program a line at a time, inspect the value of variables, - change them, tell the debugger to run up to a certain point - and then stop, and so on. You can even attach to a program - that's already running, or load a core file to investigate why - the program crashed. It's even possible to debug the kernel, - though that's a little trickier than the user applications - we'll be discussing in this section.</para> - - <para><command>gdb</command> has quite good on-line help, as - well as a set of info pages, so this section will concentrate - on a few of the basic commands.</para> - - <para>Finally, if you find its text-based command-prompt style - off-putting, there's a graphical front-end for it <ulink - URL="../../ports/devel.html">xxgdb</ulink> in the ports - collection.</para> - - <para>This section is intended to be an introduction to using - <command>gdb</command> and does not cover specialised topics - such as debugging the kernel.</para> - </sect2> - - <sect2> - <title>Running a program in the debugger</title> - - <para>You'll need to have compiled the program with the - <option>-g</option> option to get the most out of using - <command>gdb</command>. It will work without, but you'll only - see the name of the function you're in, instead of the source - code. If you see a line like:</para> - - <screen>… (no debugging symbols found) … - </screen> - - <para>when <command>gdb</command> starts up, you'll know that - the program wasn't compiled with the <option>-g</option> - option.</para> - - <para>At the <command>gdb</command> prompt, type - <userinput>break main</userinput>. This will tell the - debugger to skip over the preliminary set-up code in the - program and start at the beginning of your code. Now type - <userinput>run</userinput> to start the program—it will - start at the beginning of the set-up code and then get stopped - by the debugger when it calls <function>main()</function>. - (If you've ever wondered where <function>main()</function> - gets called from, now you know!).</para> - - <para>You can now step through the program, a line at a time, by - pressing <command>n</command>. If you get to a function call, - you can step into it by pressing <command>s</command>. Once - you're in a function call, you can return from stepping into a - function call by pressing <command>f</command>. You can also - use <command>up</command> and <command>down</command> to take - a quick look at the caller.</para> - - <para>Here's a simple example of how to spot a mistake in a - program with <command>gdb</command>. This is our program - (with a deliberate mistake):</para> - - <programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - </programlisting> - - <para>This program sets <symbol>i</symbol> to be - <literal>5</literal> and passes it to a function - <function>bazz()</function> which prints out the number we - gave it.</para> - - <para>When we compile and run the program we get</para> - - <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput> -&prompt.user; <userinput>./temp</userinput> -This is my program -anint = 4231 - </screen> - - <para>That wasn't what we expected! Time to see what's going - on!</para> - - <screen>&prompt.user; <userinput>gdb temp</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) - </screen> - - <para>Hang on a minute! How did <symbol>anint</symbol> get to be - <literal>4231</literal>? Didn't we set it to be - <literal>5</literal> in <function>main()</function>? Let's - move up to <function>main()</function> and have a look.</para> - - <screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></> - </screen> - - <para>Oh dear! Looking at the code, we forgot to initialise - <symbol>i</symbol>. We meant to put</para> - - <programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</> - </programlisting> - - <para>but we left the <literal>i=5;</literal> line out. As we - didn't initialise <symbol>i</symbol>, it had whatever number - happened to be in that area of memory when the program ran, - which in this case happened to be - <literal>4231</literal>.</para> - - <note> - <para><command>gdb</command> displays the stack frame every - time we go into or out of a function, even if we're using - <command>up</command> and <command>down</command> to move - around the call stack. This shows the name of the function - and the values of its arguments, which helps us keep track - of where we are and what's going on. (The stack is a - storage area where the program stores information about the - arguments passed to functions and where to go when it - returns from a function call).</para> - </note> - </sect2> - - <sect2> - <title>Examining a core file</title> - - <para>A core file is basically a file which contains the - complete state of the process when it crashed. In <quote>the - good old days</quote>, programmers had to print out hex - listings of core files and sweat over machine code manuals, - but now life is a bit easier. Incidentally, under FreeBSD and - other 4.4BSD systems, a core file is called - <filename><replaceable>progname</replaceable>.core</filename> instead of just - <filename>core</filename>, to make it clearer which program a - core file belongs to.</para> - - <para>To examine a core file, start up <command>gdb</command> in - the usual way. Instead of typing <command>break</command> or - <command>run</command>, type</para> - - <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput> - </screen> - - <para>If you're not in the same directory as the core file, - you'll have to do <userinput>dir - /path/to/core/file</userinput> first.</para> - - <para>You should see something like this:</para> - - <screen>&prompt.user; <userinput>gdb a.out</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - </screen> - - <para>In this case, the program was called - <filename>a.out</filename>, so the core file is called - <filename>a.out.core</filename>. We can see that the program - crashed due to trying to access an area in memory that was not - available to it in a function called - <function>bazz</function>.</para> - - <para>Sometimes it's useful to be able to see how a function was - called, as the problem could have occurred a long way up the - call stack in a complex program. The <command>bt</command> - command causes <command>gdb</command> to print out a - back-trace of the call stack:</para> - - <screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb) - </screen> - - <para>The <function>end()</function> function is called when a - program crashes; in this case, the <function>bazz()</function> - function was called from <function>main()</function>.</para> - </sect2> - - <sect2> - <title>Attaching to a running program</title> - - <para>One of the neatest features about <command>gdb</command> - is that it can attach to a program that's already running. Of - course, that assumes you have sufficient permissions to do so. - A common problem is when you are stepping through a program - that forks, and you want to trace the child, but the debugger - will only let you trace the parent.</para> - - <para>What you do is start up another <command>gdb</command>, - use <command>ps</command> to find the process ID for the - child, and do</para> - - <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput> - </screen> - - <para>in <command>gdb</command>, and then debug as usual.</para> - - <para><quote>That's all very well,</quote> you're probably - thinking, <quote>but by the time I've done that, the child - process will be over the hill and far away</quote>. Fear - not, gentle reader, here's how to do it (courtesy of the - <command>gdb</command> info pages):</para> - - <screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation> - </screen> - - <para>Now all you have to do is attach to the child, set - <symbol>PauseMode</symbol> to <literal>0</literal>, and wait - for the <function>sleep()</function> call to return!</para> - </sect2> - </sect1> - - <sect1 id="emacs"> - <title>Using Emacs as a Development Environment</title> - - <sect2> - <title>Emacs</title> - - <para>Unfortunately, Unix systems don't come with the kind of - everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package - integrated development environments that other systems - have. - - <footnote> - <para>At least, not unless you pay out very large sums of - money.</para> - </footnote> - - However, it is possible to set up your own environment. It - may not be as pretty, and it may not be quite as integrated, - but you can set it up the way you want it. And it's free. - And you have the source to it.</para> - - <para>The key to it all is Emacs. Now there are some people who - loathe it, but many who love it. If you're one of the former, - I'm afraid this section will hold little of interest to you. - Also, you'll need a fair amount of memory to run it—I'd - recommend 8MB in text mode and 16MB in X as the bare minimum - to get reasonable performance.</para> - - <para>Emacs is basically a highly customisable - editor—indeed, it has been customised to the point where - it's more like an operating system than an editor! Many - developers and sysadmins do in fact spend practically all - their time working inside Emacs, leaving it only to log - out.</para> - - <para>It's impossible even to summarise everything Emacs can do - here, but here are some of the features of interest to - developers:</para> - - <itemizedlist> - <listitem> - <para>Very powerful editor, allowing search-and-replace on - both strings and regular expressions (patterns), jumping - to start/end of block expression, etc, etc.</para> - </listitem> - - <listitem> - <para>Pull-down menus and online help.</para> - </listitem> - - <listitem> - <para>Language-dependent syntax highlighting and - indentation.</para> - </listitem> - - <listitem> - <para>Completely customisable.</para> - </listitem> - - <listitem> - <para>You can compile and debug programs within - Emacs.</para> - </listitem> - - <listitem> - <para>On a compilation error, you can jump to the offending - line of source code.</para> - </listitem> - - <listitem> - <para>Friendly-ish front-end to the <command>info</command> - program used for reading GNU hypertext documentation, - including the documentation on Emacs itself.</para> - </listitem> - - <listitem> - <para>Friendly front-end to <command>gdb</command>, allowing - you to look at the source code as you step through your - program.</para> - </listitem> - - <listitem> - <para>You can read Usenet news and mail while your program - is compiling.</para> - </listitem> - </itemizedlist> - - <para>And doubtless many more that I've overlooked.</para> - - <para>Emacs can be installed on FreeBSD using <ulink - URL="../../ports/editors.html">the Emacs - port</ulink>.</para> - - <para>Once it's installed, start it up and do <userinput>C-h - t</userinput> to read an Emacs tutorial—that means - hold down the <keycap>control</keycap> key, press - <keycap>h</keycap>, let go of the <keycap>control</keycap> - key, and then press <keycap>t</keycap>. (Alternatively, you - can you use the mouse to select <guimenuitem>Emacs - Tutorial</guimenuitem> from the <guimenu>Help</guimenu> - menu).</para> - - <para>Although Emacs does have menus, it's well worth learning - the key bindings, as it's much quicker when you're editing - something to press a couple of keys than to try and find the - mouse and then click on the right place. And, when you're - talking to seasoned Emacs users, you'll find they often - casually throw around expressions like <quote><literal>M-x - replace-s RET foo RET bar RET</literal></quote> so it's - useful to know what they mean. And in any case, Emacs has far - too many useful functions for them to all fit on the menu - bars.</para> - - <para>Fortunately, it's quite easy to pick up the key-bindings, - as they're displayed next to the menu item. My advice is to - use the menu item for, say, opening a file until you - understand how it works and feel confident with it, then try - doing C-x C-f. When you're happy with that, move on to - another menu command.</para> - - <para>If you can't remember what a particular combination of - keys does, select <guimenuitem>Describe Key</guimenuitem> from - the <guimenu>Help</guimenu> menu and type it in—Emacs - will tell you what it does. You can also use the - <guimenuitem>Command Apropos</guimenuitem> menu item to find - out all the commands which contain a particular word in them, - with the key binding next to it.</para> - - <para>By the way, the expression above means hold down the - <keysym>Meta</keysym> key, press <keysym>x</keysym>, release - the <keysym>Meta</keysym> key, type - <userinput>replace-s</userinput> (short for - <literal>replace-string</literal>—another feature of - Emacs is that you can abbreviate commands), press the - <keysym>return</keysym> key, type <userinput>foo</userinput> - (the string you want replaced), press the - <keysym>return</keysym> key, type bar (the string you want to - replace <literal>foo</literal> with) and press - <keysym>return</keysym> again. Emacs will then do the - search-and-replace operation you've just requested.</para> - - <para>If you're wondering what on earth the - <keysym>Meta</keysym> key is, it's a special key that many - Unix workstations have. Unfortunately, PC's don't have one, - so it's usually the <keycap>alt</keycap> key (or if you're - unlucky, the <keysym>escape</keysym> key).</para> - - <para>Oh, and to get out of Emacs, do <command>C-x C-c</command> - (that means hold down the <keysym>control</keysym> key, press - <keysym>x</keysym>, press <keysym>c</keysym> and release the - <keysym>control</keysym> key). If you have any unsaved files - open, Emacs will ask you if you want to save them. (Ignore - the bit in the documentation where it says - <command>C-z</command> is the usual way to leave - Emacs—that leaves Emacs hanging around in the - background, and is only really useful if you're on a system - which doesn't have virtual terminals).</para> - </sect2> - - <sect2> - <title>Configuring Emacs</title> - - <para>Emacs does many wonderful things; some of them are built - in, some of them need to be configured.</para> - - <para>Instead of using a proprietary macro language for - configuration, Emacs uses a version of Lisp specially adapted - for editors, known as Emacs Lisp. This can be quite useful if - you want to go on and learn something like Common Lisp, as - it's considerably smaller than Common Lisp (although still - quite big!).</para> - - <para>The best way to learn Emacs Lisp is to download the <ulink - URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs - Tutorial</ulink></para> - - <para>However, there's no need to actually know any Lisp to get - started with configuring Emacs, as I've included a sample - <filename>.emacs</filename> file, which should be enough to - get you started. Just copy it into your home directory and - restart Emacs if it's already running; it will read the - commands from the file and (hopefully) give you a useful basic - setup.</para> - </sect2> - - <sect2> - <title>A sample <filename>.emacs</filename> file</title> - - <para>Unfortunately, there's far too much here to explain it in - detail; however there are one or two points worth - mentioning.</para> - - <itemizedlist> - <listitem> - <para>Everything beginning with a <literal>;</literal> is a comment - and is ignored by Emacs.</para> - </listitem> - - <listitem> - <para>In the first line, the - <literal>-*- Emacs-Lisp -*-</literal> is so that - we can edit the <filename>.emacs</filename> file itself - within Emacs and get all the fancy features for editing - Emacs Lisp. Emacs usually tries to guess this based on - the filename, and may not get it right for - <filename>.emacs</filename>.</para> - </listitem> - - <listitem> - <para>The <keysym>tab</keysym> key is bound to an - indentation function in some modes, so when you press the - tab key, it will indent the current line of code. If you - want to put a <token>tab</token> character in whatever - you're writing, hold the <keysym>control</keysym> key down - while you're pressing the <keysym>tab</keysym> key.</para> - </listitem> - - <listitem> - <para>This file supports syntax highlighting for C, C++, - Perl, Lisp and Scheme, by guessing the language from the - filename.</para> - </listitem> - - <listitem> - <para>Emacs already has a pre-defined function called - <function>next-error</function>. In a compilation output - window, this allows you to move from one compilation error - to the next by doing <command>M-n</command>; we define a - complementary function, - <function>previous-error</function>, that allows you to go - to a previous error by doing <command>M-p</command>. The - nicest feature of all is that <command>C-c C-c</command> - will open up the source file in which the error occurred - and jump to the appropriate line.</para> - </listitem> - - <listitem> - <para>We enable Emacs's ability to act as a server, so that - if you're doing something outside Emacs and you want to - edit a file, you can just type in</para> - - <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput> - </screen> - - <para>and then you can edit the file in your - Emacs! - - <footnote> - <para>Many Emacs users set their <systemitem - class=environvar>EDITOR</systemitem> environment to - <literal>emacsclient</literal> so this happens every - time they need to edit a file.</para> - </footnote></para> - </listitem> - </itemizedlist> - - <example> - <title>A sample <filename>.emacs</filename> file</title> - - <programlisting>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - </programlisting> - </example> - </sect2> - - <sect2> - <title>Extending the Range of Languages Emacs Understands</title> - - <para>Now, this is all very well if you only want to program in - the languages already catered for in the - <filename>.emacs</filename> file (C, C++, Perl, Lisp and - Scheme), but what happens if a new language called - <quote>whizbang</quote> comes out, full of exciting - features?</para> - - <para>The first thing to do is find out if whizbang comes with - any files that tell Emacs about the language. These usually - end in <filename>.el</filename>, short for <quote>Emacs - Lisp</quote>. For example, if whizbang is a FreeBSD port, we - can locate these files by doing</para> - - <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput> - </screen> - - <para>and install them by copying them into the Emacs site Lisp - directory. On FreeBSD 2.1.0-RELEASE, this is - <filename>/usr/local/share/emacs/site-lisp</filename>.</para> - - <para>So for example, if the output from the find command - was</para> - - <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el - </screen> - - <para>we would do</para> - - <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput> - </screen> - - <para>Next, we need to decide what extension whizbang source - files have. Let's say for the sake of argument that they all - end in <filename>.wiz</filename>. We need to add an entry to - our <filename>.emacs</filename> file to make sure Emacs will - be able to use the information in - <filename>whizbang.el</filename>.</para> - - <para>Find the <symbol>auto-mode-alist entry</symbol> in - <filename>.emacs</filename> and add a line for whizbang, such - as:</para> - - <programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</> - </programlisting> - - <para>This means that Emacs will automatically go into - <function>whizbang-mode</function> when you edit a file ending - in <filename>.wiz</filename>.</para> - - <para>Just below this, you'll find the - <symbol>font-lock-auto-mode-list</symbol> entry. Add - <function>whizbang-mode</function> to it like so:</para> - - <programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - </programlisting> - - <para>This means that Emacs will always enable - <function>font-lock-mode</function> (ie syntax highlighting) - when editing a <filename>.wiz</filename> file.</para> - - <para>And that's all that's needed. If there's anything else - you want done automatically when you open up a - <filename>.wiz</filename> file, you can add a - <function>whizbang-mode hook</function> (see - <function>my-scheme-mode-hook</function> for a simple example - that adds <function>auto-indent</function>).</para> - </sect2> - </sect1> - - <sect1> - <title>Further Reading</title> - - <itemizedlist> - <listitem> - <para>Brian Harvey and Matthew Wright - <emphasis>Simply Scheme</emphasis> - MIT 1994.<!-- <br> --> - ISBN 0-262-08226-8</para> - </listitem> - - <listitem> - <para>Randall Schwartz - <emphasis>Learning Perl</emphasis> - O'Reilly 1993<!-- <br> --> - ISBN 1-56592-042-2</para> - </listitem> - - <listitem> - <para>Patrick Henry Winston and Berthold Klaus Paul Horn - <emphasis>Lisp (3rd Edition)</emphasis> - Addison-Wesley 1989<!-- <br> --> - ISBN 0-201-08319-1</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Rob Pike - <emphasis>The Unix Programming Environment</emphasis> - Prentice-Hall 1984<!-- <br> --> - ISBN 0-13-937681-X</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Dennis M. Ritchie - <emphasis>The C Programming Language (2nd Edition)</emphasis> - Prentice-Hall 1988<!-- <br> --> - ISBN 0-13-110362-8</para> - </listitem> - - <listitem> - <para>Bjarne Stroustrup - <emphasis>The C++ Programming Language</emphasis> - Addison-Wesley 1991<!-- <br> --> - ISBN 0-201-53992-6</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Advanced Programming in the Unix Environment</emphasis> - Addison-Wesley 1992<!-- <br> --> - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Unix Network Programming</emphasis> - Prentice-Hall 1990<!-- <br> --> - ISBN 0-13-949876-1</para> - </listitem> - </itemizedlist> - </sect1> - - </chapter> - - <chapter id="secure-programming"> - <title>Secure Programming</title> - - <para>This chapter was written by Murray Stokely.</para> - - <sect1><title>Synopsis</title> - - <para>This chapter describes some of the security issues that - have plagued Unix programmers for decades and some of the new - tools available to help programmers avoid writing exploitable - code.</para> - </sect1> - - <sect1 id="secure-philosophy"><title>Secure Design - Methodology</title> - - <para>Writing secure applications takes a very scrutinous and - pessimistic outlook on life. Applications should be run with - the principle of <quote>least privilege</quote> so that no - process is ever running than more with the bare minimum access - that it needs to accomplish its function. Previously tested - code should be reused whenever possible to avoid common - mistakes that others may have already fixed.</para> - - <para>One of the pitfalls of the Unix environment is how easy it - is to make assumptions about the sanity of the environment. - Applications should never trust user input (in all its forms), - system resources, inter-process communication, or the timing of - events. Unix processes do not execute synchronously so logical - operations are rarely atomic.</para> - </sect1> - - <sect1><title>Buffer Overflows</title> - - <para>Buffer Overflows have been around since the very - beginnings of the Von-Neuman <xref linkend="COD"> architecture. - They first gained widespread notoriety in 1988 with the Moorse - Internet worm. Unfortunately, the same basic attack remains - effective today. Of the 17 CERT security advisories of 1999, 10 - of them were directly caused by buffer-overflow software bugs. - By far the most common type of buffer overflow attack is based - on corrupting the stack.</para> - - <para>Most modern computer systems use a stack to pass arguments - to procedures and to store local variables. A stack is a last - in first out (LIFO) buffer in the high memory area of a process - image. When a program invokes a function a new "stack frame" is - created. This stack frame consists of the arguments passed to - the function as well as a dynamic amount of local variable - space. The "stack pointer" is a register that holds the current - location of the top of the stack. Since this value is - constantly changing as new values are pushed onto the top of the - stack, many implementations also provide a "frame pointer" that - is located near the beginning of a stack frame so that local - variables can more easily be addressed relative to this - value. <xref linkend="COD"> The return address for function - calls is also stored on the stack, and this is the cause of - stack-overflow exploits since overflowing a local variable in a - function can overwrite the return address of that function, - potentially allowing a malicious user to execute any code he or - she wants.</para> - - <para>Although stack-based attacks are by far the most common, - it would also be possible to overrun the stack with a heap-based - (malloc/free) attack.</para> - - <para>The C programming language does not perform automatic - bounds checking on arrays or pointers as many other languages - do. In addition, the standard C library is filled with a - handful of very dangerous functions.</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row><entry><function>strcpy</function>(char *dest, const char - *src)</entry> - <entry><simpara>May overflow the dest buffer</simpara></entry> - </row> - - <row><entry><function>strcat</function>(char *dest, const char - *src)</entry> - <entry><simpara>May overflow the dest buffer</simpara></entry> - </row> - - <row><entry><function>getwd</function>(char *buf)</entry> - <entry><simpara>May overflow the buf buffer</simpara></entry> - </row> - - <row><entry><function>gets</function>(char *s)</entry> - <entry><simpara>May overflow the s buffer</simpara></entry> - </row> - - <row><entry><function>[vf]scanf</function>(const char *format, - ...)</entry> - <entry><simpara>May overflow its arguments.</simpara></entry> - </row> - - <row><entry><function>realpath</function>(char *path, char - resolved_path[])</entry> - <entry><simpara>May overflow the path buffer</simpara></entry> - </row> - - <row><entry><function>[v]sprintf</function>(char *str, const char - *format, ...)</entry> - <entry><simpara>May overflow the str buffer.</simpara></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <sect2><title>Example Buffer Overflow</title> - - <para>The following example code contains a buffer overflow - designed to overwrite the return address and skip the - instruction immediately following the function call. (Inspired - by <xref linkend="Phrack">)</para> - -<programlisting> -#include <sgmltag>stdio.h</sgmltag> - -void manipulate(char *buffer) { - char newbuffer[80]; - strcpy(newbuffer,buffer); -} - -int main() { - char ch,buffer[4096]; - int i=0; - - while ((buffer[i++] = getchar()) != '\n') {}; - - i=1; - manipulate(buffer); - i=2; - printf("The value of i is : %d\n",i); - return 0; -} -</programlisting> - - <para>Let us examine what the memory image of this process would - look like if we were to input 160 spaces into our little program - before hitting return.</para> - - <para>[XXX figure here!]</para> - - <para>Obviously more malicious input can be devised to execute - actual compiled instructions (such as exec(/bin/sh)).</para> - </sect2> - - <sect2><title>Avoiding Buffer Overflows</title> - - <para>The most straightforward solution to the problem of - stack-overflows is to always use length restricted memory and - string copy functions. <function>strncpy</function> and - <function>strncat</function> are part of the standard C library. - These functions accept a length value as a parameter which - should be no larger than the size of the destination buffer. - These functions will then copy up to `length' bytes from the - source to the destination. However there are a number of - problems with these functions. Neither function guarantees NUL - termination if the size of the input buffer is as large as the - destination. The length parameter is also used inconsistently - between strncpy and strncat so it is easy for programmers to get - confused as to their proper usage. There is also a significant - performance loss compared to <function>strcpy</function> when - copying a short string into a large buffer since - <function>strncpy</function> NUL fills up the the size - specified.</para> - - <para>In OpenBSD, another memory copy implementation has been - created to get around these problem. The - <function>strlcpy</function> and <function>strlcat</function> - functions guarantee that they will always null terminate the - destination string when given a non-zero length argument. For - more information about these functions see <xref - linkend="OpenBSD">. The OpenBSD <function>strlcpy</function> and - <function>strlcat</function> instructions have been in FreeBSD - since 3.5.</para> - - <sect3><title>Compiler based run-time bounds checking</title> - - <para>Unfortunately there is still a very large assortment of - code in public use which blindly copies memory around without - using any of the bounded copy routines we just discussed. - Fortunately, there is another solution. Several compiler - add-ons and libraries exist to do Run-time bounds checking in - C/C++.</para> - - <para>StackGuard is one such add-on that is implemented as a - small patch to the gcc code generator. From the StackGuard - website, http://immunix.org/stackguard.html : - <blockquote><para>"StackGuard detects and defeats stack - smashing attacks by protecting the return address on the stack - from being altered. StackGuard places a "canary" word next to - the return address when a function is called. If the canary - word has been altered when the function returns, then a stack - smashing attack has been attempted, and the program responds - by emitting an intruder alert into syslog, and then - halts."</para></blockquote> - - <blockquote><para>"StackGuard is implemented as a small patch - to the gcc code generator, specifically the function_prolog() - and function_epilog() routines. function_prolog() has been - enhanced to lay down canaries on the stack when functions - start, and function_epilog() checks canary integrity when the - function exits. Any attempt at corrupting the return address - is thus detected before the function - returns."</para></blockquote> - </para> - - <para>Recompiling your application with StackGuard is an - effective means of stopping most buffer-overflow attacks, but - it can still be compromised.</para> - - </sect3> - - <sect3><title>Library based run-time bounds checking</title> - - <para>Compiler-based mechanisms are completely useless for - binary-only software for which you cannot recompile. For - these situations there are a number of libraries which - re-implement the unsafe functions of the C-library - (<function>strcpy</function>, <function>fscanf</function>, - <function>getwd</function>, etc..) and ensure that these - functions can never write past the stack pointer.</para> - - <itemizedlist> - <listitem><simpara>libsafe</simpara></listitem> - <listitem><simpara>libverify</simpara></listitem> - <listitem><simpara>libparnoia</simpara></listitem> - </itemizedlist> - - <para>Unfortunately these library-based defenses have a number - of shortcomings. These libraries only protect against a very - small set of security related issues and they neglect to fix - the actual problem. These defenses may fail if the - application was compiled with -fomit-frame-pointer. Also, the - LD_PRELOAD and LD_LIBRARY_PATH environment variables can be - overwritten/unset by the user.</para> - </sect3> - - </sect2> - </sect1> - - <sect1><title>SetUID issues</title> - - <para>There are at least 6 different IDs associated with any - given process. Because of this you have to be very careful with - the access that your process has at any given time. In - particular, all seteuid applications should give up their - privileges as soon as it is no longer required.</para> - - <para>The real user ID can only be changed by a superuser - process. The <application>login</application> program sets this - when a user initially logs in and it is seldom changed.</para> - - <para>The effective user ID is set by the - <function>exec()</function> functions if a program has its - seteuid bit set. An application can call - <function>seteuid()</function> at any time to set the effective - user ID to either the real user ID or the saved set-user-ID. - When the effective user ID is set by <function>exec()</function> - functions, the previous value is saved in the saved set-user-ID.</para> - - </sect1> - - <sect1 id="chroot"><title>Limiting your program's environment</title> - - <para>The traditional method of restricting access to a process - is with the <function>chroot()</function> system call. This - system call changes the root directory from which all other - paths are referenced for a process and any child processes. For - this call to succeed the process must have execute (search) - permission on the directory being referenced. The new - environment does not actually take affect until you - <function>chdir()</function> into your new environment. It - should also be noted that a process can easily break out of a - chroot environment if it has root privilege. This could be - accomplished by creating device nodes to read kernel memory, - attaching a debugger to a process outside of the jail, or in - many other creative ways.</para> - - <para>The behavior of the <function>chroot()</function> system - call can be controlled somewhat with the - kern.chroot_allow_open_directories <command>sysctl</command> - variable. When this value is set to 0, - <function>chroot()</function> will fail with EPERM if there are - any directories open. If set to the default value of 1, then - <function>chroot()</function> will fail with EPERM if there are - any directories open and the process is already subject to a - <function>chroot()</function> call. For any other value, the - check for open directories will be bypassed completely.</para> - - <sect2><title>FreeBSD's jail functionality</title> - - <para>The concept of a Jail extends upon the - <function>chroot()</function> by limiting the powers of the - superuser to create a true `virtual server'. Once a prison is - setup all network communication must take place through the - specified IP address, and the power of "root privilege" in this - jail is severely constrained.</para> - - <para>While in a prison, any tests of superuser power within the - kernel using the <function>suser()</function> call will fail. - However, some calls to <function>suser()</function> have been - changed to a new interface <function>suser_xxx()</function>. - This function is responsible for recognizing or denying access - to superuser power for imprisoned processes.</para> - - <para>A superuser process within a jailed environment has the - power to : </para> - <itemizedlist> - <listitem><simpara>Manipulate credential with - <function>setuid</function>, <function>seteuid</function>, - <function>setgid</function>, <function>setegid</function>, - <function>setgroups</function>, <function>setreuid</function>, - <function>setregid</function>, <function>setlogin</function></simpara></listitem> - <listitem><simpara>Set resource limits with <function>setrlimit</function></simpara></listitem> - <listitem><simpara>Modify some sysctl nodes - (kern.hostname)</simpara></listitem> - <listitem><simpara><function>chroot()</function></simpara></listitem> - <listitem><simpara>Set flags on a vnode: - <function>chflags</function>, - <function>fchflags</function></simpara></listitem> - <listitem><simpara>Set attributes of a vnode such as file - permission, owner, group, size, access time, and modification - time.</simpara></listitem> - <listitem><simpara>Bind to privileged ports in the Internet - domain (ports < 1024)</simpara></listitem> - </itemizedlist> - - <para><function>Jail</function> is a very useful tool for - running applications in a secure environment but it does have - some shortcomings. Currently, the IPC mechanisms have not been - converted to the <function>suser_xxx</function> so applications - such as MySQL can not be run within a jail. Superuser access - may have a very limited meaning within a jail, but there is - no way to specify exactly what "very limited" means.</para> - </sect2> - - <sect2><title>POSIX.1e Process Capabilities</title> - - <para>Posix has released a working draft that adds event - auditing, access control lists, fine grained privileges, - information labeling, and mandatory access control.</para> - <para>This is a work in progress and is the focus of the <ulink - url="http://www.trustedbsd.org">TrustedBSD</ulink> project. Some - of the initial work has been committed to FreeBSD-current - (cap_set_proc(3)).</para> - - </sect2> - - </sect1> - - <sect1><title>Trust</title> - - <para>An application should never assume that anything about the - users environment is sane. This includes (but is certainly not - limited to) : user input, signals, environment variables, - resources, IPC, mmaps, the file system working directory, file - descriptors, the # of open files, etc.</para> - - <para>You should never assume that you can catch all forms of - invalid input that a user might supply. Instead, your - application should use positive filtering to only allow a - specific subset of inputs that you deem safe. Improper data - validation has been the cause of many exploits, especially with - CGI scripts on the world wide web. For filenames you need to be - extra careful about paths ("../", "/"), symbolic links, and - shell escape characters.</para> - - <para>Perl has a really cool feature called "Taint" mode which - can be used to prevent scripts for using data derived outside - the program in an unsafe way. This mode will check command line - arguments, environment variables, locale information, the - results of certain syscalls (<function>readdir()</function>, - <function>readlink()</function>, - <function>getpwxxx()</function>, and all file input.</para> - - </sect1> - - <sect1><title>Race Conditions</title> - - <para>A race condition is anomalous behavior caused by the - unexpected dependence on the relative timing of events. In - other words, a programmer incorrectly assumed that a particular - event would always happen before another.</para> - - <para>Some of the common causes of race conditions are signals, - access checks, and file opens. Signals are asynchronous events - by nature so special care must be taken in dealing with them. - Checking access with <function>access(2)</function> then - <function>open(2)</function> is clearly non-atomic. Users can - move files in between the two calls. Instead, privileged - applications should <function>seteuid()</function> and then call - <function>open()</function> directly. Along the same lines, an - application should always set a proper umask before - <function>open()</function> to obviate the need for spurious - <function>chmod()</function> calls.</para> - - </sect1> - - </chapter> - </part> - - <part id="kernel"> - <title>Kernel</title> - - <chapter id="kernelhistory"> - <title>History of the Unix Kernel</title> - - <para>Some history of the Unix/BSD kernel, system calls, how do - processes work, blocking, scheduling, threads (kernel), - context switching, signals, interrupts, modules, etc.</para> - - <para></para> - </chapter> - </part> - - <part id="memory"> - <title>Memory and Virtual Memory</title> - - <chapter id="virtualmemory"> - <title>Virtual Memory</title> - - <para>VM, paging, swapping, allocating memory, testing for - memory leaks, mmap, vnodes, etc.</para> - - <para></para> - </chapter> - </part> - - <part id="iosystem"> - <title>I/O System</title> - - <chapter id="ufs"> - <title>UFS</title> - - <para>UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, - locking, metadata, soft-updates, LFS, portalfs, procfs, - vnodes, memory sharing, memory objects, TLBs, caching</para> - - </chapter> - </part> - - <part id="ipc"> - <title>Interprocess Communication</title> - - <chapter id="signals"> - <title>Signals</title> - - <para>Signals, pipes, semaphores, message queues, shared memory, - ports, sockets, doors</para> - - </chapter> - </part> - - <part id="networking"> - <title>Networking</title> - - <chapter id="sockets"> - <title>Sockets</title> - - <para>Sockets, bpf, IP, TCP, UDP, ICMP, OSI, bridging, - firewalling, NAT, switching, etc</para> - - </chapter> - </part> - - <part id="networkfs"> - <title>Network Filesystems</title> - - <chapter id="afs"> - <title>AFS</title> - - <para>AFS, NFS, SANs etc]</para> - - </chapter> - </part> - - <part id="terminal"> - <title>Terminal Handling</title> - - <chapter id="syscons"> - <title>Syscons</title> - - <para>Syscons, tty, PCVT, serial console, screen savers, - etc</para> - - </chapter> - </part> - - <part id="sound"> - <title>Sound</title> - - <chapter id="oss"> - <title>OSS</title> - - <para>OSS, waveforms, etc</para> - - </chapter> - </part> - - <part id="devicedrivers"> - <title>Device Drivers</title> - - <chapter id="driverbasics"> - <title>Writing FreeBSD Device Drivers</title> - - <para>This chapter was written by Murray Stokely with selections from - a variety of sources including the intro(4) man page by Joerg - Wunsch.</para> - - <sect1> - <title>Introduction</title> - <para> - This chapter provides a brief introduction to writing device - drivers for FreeBSD. A device in this context is a term used - mostly for hardware-related stuff that belongs to the system, - like disks, printers, or a graphics display with its keyboard. - A device driver is the software component of the operating - system that controls a specific device. There are also - so-called pseudo-devices where a device driver emulates the - behaviour of a device in software without any particular - underlying hardware. Device drivers can be compiled into the - system statically or loaded on demand through the dynamic - kernel linker facility `kld'.</para> - - <para>Most devices in a Unix-like operating system are - accessed through device-nodes, sometimes also called special - files. These files are usually located under the directory - <filename>/dev</filename> in the file system hierarchy. Until - devfs is fully integrated into FreeBSD, each device node must - be created statically and independent of the existence of the - associated device driver. Most device nodes on the system are - created by running <command>MAKEDEV</command>.</para> - - <para>Device drivers can roughly be broken down into three - categories; character (unbuffered), block (buffered), and - network drivers.</para> - </sect1> - - <sect1> - <title>Dynamic Kernel Linker Facility - KLD</title> - <para>The kld interface allows system administrators to - dynamically add and remove functionality from a running - system. This allows device driver writers to load their new - changes into a running kernel without constantly rebooting to - test changes.</para> - - <para>The kld interface is used through the following - administrator commands : - <itemizedlist> - <listitem><simpara><command>kldload</command> - loads a new kernel - module</simpara></listitem> - <listitem><simpara><command>kldunload</command> - unloads a kernel - module</simpara></listitem> - <listitem><simpara><command>kldstat</command> - lists the currently loadded - modules</simpara></listitem> - </itemizedlist> - </para> - - <para>Skeleton Layout of a kernel module</para> -<programlisting> -/* - * KLD Skeleton - * Inspired by Andrew Reiter's Daemonnews article - */ - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ - -/* - * Load handler that deals with the loading and unloading of a KLD. - */ - -static int -skel_loader(struct module *m, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - uprintf("Skeleton KLD loaded.\n"); - break; - case MOD_UNLOAD: - uprintf("Skeleton KLD unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -/* Declare this module to the rest of the kernel */ - -DECLARE_MODULE(skeleton, skel_loader, SI_SUB_KLD, SI_ORDER_ANY); -</programlisting> - - - <sect2> - <title>Makefile</title> - <para>FreeBSD provides a makefile include that you can use - to quickly compile your kernel addition.</para> - <programlisting> -SRCS=skeleton.c -KMOD=skeleton - -.include <bsd.kmod.mk> -</programlisting> - - - <para>Simply running <command>make</command> with - this makefile will create a file - <filename>skeleton.ko</filename> that can be loaded into - your system by typing : -<screen> -&prompt.root kldload -v ./skeleton.ko -</screen> - </para> - </sect2> - </sect1> - - <sect1> - <title>Accessing a device driver</title> - <para>Unix provides a common set of system calls for user - applications to use. The upper layers of the kernel dispatch - these calls to the corresponding device driver when a user - accesses a device node. The <command>/dev/MAKEDEV</command> - script makes most of the device nodes for your system but if - you are doing your own driver development it may be necessary - to create your own device nodes with <command>mknod</command> - </para> - - <sect2> - <title>Creating static device nodes</title> - <para>The <command>mknod</command> command requires four - arguments to create a device node. You must specify the - name of this device node, the type of device, the major number - of the device, and the minor number of the device.</para> - </sect2> - - <sect2> - <title>Dynamic device nodes</title> - <para>The device filesystem, or devfs, provides access to the - kernel's device namespace in the global filesystem namespace. - This eliminates the problems of potentially having a device - driver without a static device node, or a device node without - an installed device driver. Unfortunately, devfs is still a - work in progress.</para> - </sect2> - - </sect1> - - <sect1> - <title>Character Devices</title> - <para>A character device driver is one that transfers data - directly to and from a user process. This is the most common - type of device driver and there are plenty of simple examples - in the source tree.</para> - <para>This simple example pseudo-device remembers whatever values you write - to it and can then supply them back to you when you read from - it.</para> -<programlisting> -/* - * Simple `echo' pseudo-device KLD - * - * Murray Stokely - */ - -#define MIN(a,b) (((a) < (b)) ? (a) : (b)) - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ -#include <sys/conf.h> /* cdevsw struct */ -#include <sys/uio.h> /* uio struct */ -#include <sys/malloc.h> - -#define BUFFERSIZE 256 - -/* Function prototypes */ -d_open_t echo_open; -d_close_t echo_close; -d_read_t echo_read; -d_write_t echo_write; - -/* Character device entry points */ -static struct cdevsw echo_cdevsw = { - echo_open, - echo_close, - echo_read, - echo_write, - noioctl, - nopoll, - nommap, - nostrategy, - "echo", - 33, /* reserved for lkms - /usr/src/sys/conf/majors */ - nodump, - nopsize, - D_TTY, - -1 -}; - -typedef struct s_echo { - char msg[BUFFERSIZE]; - int len; -} t_echo; - -/* vars */ -static dev_t sdev; -static int len; -static int count; -static t_echo *echomsg; - -MALLOC_DECLARE(M_ECHOBUF); -MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module"); - -/* - * This function acts is called by the kld[un]load(2) system calls to - * determine what actions to take when a module is loaded or unloaded. - */ - -static int -echo_loader(struct module *m, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - sdev = make_dev(<literal>&</literal>echo_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "echo"); - /* kmalloc memory for use by this driver */ - /* malloc(256,M_ECHOBUF,M_WAITOK); */ - MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK); - printf("Echo device loaded.\n"); - break; - case MOD_UNLOAD: - destroy_dev(sdev); - FREE(echomsg,M_ECHOBUF); - printf("Echo device unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -int -echo_open(dev_t dev, int oflags, int devtype, struct proc *p) -{ - int err = 0; - - uprintf("Opened device \"echo\" successfully.\n"); - return(err); -} - -int -echo_close(dev_t dev, int fflag, int devtype, struct proc *p) -{ - uprintf("Closing device \"echo.\"\n"); - return(0); -} - -/* - * The read function just takes the buf that was saved via - * echo_write() and returns it to userland for accessing. - * uio(9) - */ - -int -echo_read(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - int amt; - - /* How big is this read operation? Either as big as the user wants, - or as big as the remaining data */ - amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0); - if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) { - uprintf("uiomove failed!\n"); - } - - return err; -} - -/* - * echo_write takes in a character string and saves it - * to buf for later accessing. - */ - -int -echo_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - /* Copy the string in from user memory to kernel memory */ - err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE)); - - /* Now we need to null terminate */ - *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0; - /* Record the length */ - echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE); - - if (err != 0) { - uprintf("Write failed: bad address!\n"); - } - - count++; - return(err); -} - -DEV_MODULE(echo,echo_loader,NULL); -</programlisting> - -<para>To install this driver you will first need to make a node on - your filesystem with a command such as : </para> -<screen> - &prompt.root mknod /dev/echo c 33 0 -</screen> -<para>With this driver loaded you should now be able to type something - like :</para> -<screen> - &prompt.root echo -n "Test Data" > /dev/echo - &prompt.root cat /dev/echo - Test Data -</screen> - <para>Real hardware devices in the next chapter..</para> - - <para>Additional Resources - <itemizedlist> - <listitem><simpara><ulink - url="http://www.daemonnews.org/200010/blueprints.html">Dynamic - Kernel Linker (KLD) Facility Programming Tutorial</ulink> - - <ulink url="http://www.daemonnews.org">Daemonnews</ulink> October 2000</simpara></listitem> - <listitem><simpara><ulink - url="http://www.daemonnews.org/200007/newbus-intro.html">How - to Write Kernel Drivers with NEWBUS</ulink> - <ulink - url="http://www.daemonnews.org">Daemonnews</ulink> July - 2000</simpara></listitem> - </itemizedlist> - </para> - </sect1> - - <sect1> - <title>Block Devices</title> - <para>A block device driver transfers data to and from the - operating system's buffer cache. They are solely intended to - layer a file system on top of them. For this reason they are - normally implemented for disks and disk-like devices only.</para> - - <para>Example test data generator ... </para> - - <para>Example ramdisk device ... </para> - - <para>Real hardware devices in the next chapter..</para> - </sect1> - - <sect1> - <title>Network Drivers</title> - <para>Drivers for network devices do not use device nodes in - ord to be accessed. Their selection is based on other - decisions made inside the kernel and instead of calling - open(), use of a network device is generally introduced by - using the system call socket(2).</para> - <para>man ifnet(), loopback device, Bill Pauls drivers, etc..</para> - </sect1> - - </chapter> - - <chapter id="pci"> - <title>PCI Devices</title> - - <para>This chapter will talk about the FreeBSD mechanisms for - writing a device driver for a device on a PCI bus.</para> - - <sect1><title>Probe and Attach</title> - - <para>Information here about how the PCI bus code iterates - through the unattached devices and see if a newly loaded kld - will attach to any of them.</para> -<programlisting> -/* - * Simple KLD to play with the PCI functions. - * - * Murray Stokely - */ - -#define MIN(a,b) (((a) < (b)) ? (a) : (b)) - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ -#include <sys/conf.h> /* cdevsw struct */ -#include <sys/uio.h> /* uio struct */ -#include <sys/malloc.h> -#include <sys/bus.h> /* structs, prototypes for pci bus stuff */ - -#include <pci/pcivar.h> /* For get_pci macros! */ - -/* Function prototypes */ -d_open_t mypci_open; -d_close_t mypci_close; -d_read_t mypci_read; -d_write_t mypci_write; - -/* Character device entry points */ - -static struct cdevsw mypci_cdevsw = { - mypci_open, - mypci_close, - mypci_read, - mypci_write, - noioctl, - nopoll, - nommap, - nostrategy, - "mypci", - 36, /* reserved for lkms - /usr/src/sys/conf/majors */ - nodump, - nopsize, - D_TTY, - -1 -}; - -/* vars */ -static dev_t sdev; - -/* We're more interested in probe/attach than with - open/close/read/write at this point */ - -int -mypci_open(dev_t dev, int oflags, int devtype, struct proc *p) -{ - int err = 0; - - uprintf("Opened device \"mypci\" successfully.\n"); - return(err); -} - -int -mypci_close(dev_t dev, int fflag, int devtype, struct proc *p) -{ - int err=0; - - uprintf("Closing device \"mypci.\"\n"); - return(err); -} - -int -mypci_read(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - uprintf("mypci read!\n"); - return err; -} - -int -mypci_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - uprintf("mypci write!\n"); - return(err); -} - -/* PCI Support Functions */ - -/* - * Return identification string if this is device is ours. - */ -static int -mypci_probe(device_t dev) -{ - uprintf("MyPCI Probe\n" - "Vendor ID : 0x%x\n" - "Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev)); - - if (pci_get_vendor(dev) == 0x11c1) { - uprintf("We've got the Winmodem, probe successful!\n"); - return 0; - } - - return ENXIO; -} - -/* Attach function is only called if the probe is successful */ - -static int -mypci_attach(device_t dev) -{ - uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev)); - sdev = make_dev(<literal>&</literal>mypci_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "mypci"); - uprintf("Mypci device loaded.\n"); - return ENXIO; -} - -/* Detach device. */ - -static int -mypci_detach(device_t dev) -{ - uprintf("Mypci detach!\n"); - return 0; -} - -/* Called during system shutdown after sync. */ - -static int -mypci_shutdown(device_t dev) -{ - uprintf("Mypci shutdown!\n"); - return 0; -} - -/* - * Device suspend routine. - */ -static int -mypci_suspend(device_t dev) -{ - uprintf("Mypci suspend!\n"); - return 0; -} - -/* - * Device resume routine. - */ - -static int -mypci_resume(device_t dev) -{ - uprintf("Mypci resume!\n"); - return 0; -} - -static device_method_t mypci_methods[] = { - /* Device interface */ - DEVMETHOD(device_probe, mypci_probe), - DEVMETHOD(device_attach, mypci_attach), - DEVMETHOD(device_detach, mypci_detach), - DEVMETHOD(device_shutdown, mypci_shutdown), - DEVMETHOD(device_suspend, mypci_suspend), - DEVMETHOD(device_resume, mypci_resume), - - { 0, 0 } -}; - -static driver_t mypci_driver = { - "mypci", - mypci_methods, - 0, - /* sizeof(struct mypci_softc), */ -}; - -static devclass_t mypci_devclass; - -DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); -</programlisting> - - <para>Additional Resources - <itemizedlist> - <listitem><simpara><ulink - url="http://www.pcisig.org">PCI Special Interest - Group</ulink></simpara></listitem> - <listitem><simpara>PCI System Architecture, Fourth Edition by - Tom Shanley, et al.</simpara></listitem> - </itemizedlist> - </para> - </sect1> - </chapter> - - <chapter id="usb"> - <title>USB Devices</title> - - <para>This chapter will talk about the FreeBSD mechanisms for - writing a device driver for a device on a USB bus.</para> - </chapter> - - <chapter id="newbus"> - <title>NewBus</title> - - <para>This chapter will talk about the FreeBSD NewBus - architecture.</para> - </chapter> - - </part> - - <part id="architectures"> - <title>Architectures</title> - - <chapter id="ia32"> - <title>IA-32</title> - - <para>Talk about the architectural specifics of FreeBSD/x86.</para> - - </chapter> - - <chapter id="alpha"> - <title>Alpha</title> - - <para>Talk about the architectural specifics of - FreeBSD/alpha.</para> - - <para>Explanation of allignment errors, how to fix, how to - ignore.</para> - - <para>Example assembly language code for FreeBSD/alpha.</para> - </chapter> - - <chapter id="ia64"> - <title>IA-64</title> - - <para>Talk about the architectural specifics of - FreeBSD/ia64.</para> - - </chapter> - </part> - - <part id="debuggingpart"> - <title>Debugging</title> - - <chapter id="truss"> - <title>Truss</title> - - <para>various descriptions on how to debug certain aspects of - the system using truss, ktrace, gdb, kgdb, etc</para> - - </chapter> - </part> - - <part id="compatibility"> - <title>Compatibility Layers</title> - - <chapter id="linux"> - <title>Linux</title> - - <para>Linux, SVR4, etc</para> - - </chapter> - </part> - - <part id="appendices"> - <title>Appendices</title> - - <bibliography> - - <biblioentry id="COD" xreflabel="1"> - <authorgroup> - <author> - <firstname>Dave</firstname> - <othername role="MI">A</othername> - <surname>Patterson</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">L</othername> - <surname>Hennessy</surname> - </author> - </authorgroup> - <copyright><year>1998</year><holder>Morgan Kaufmann Publishers, - Inc.</holder></copyright> - <isbn>1-55860-428-6</isbn> - <publisher> - <publishername>Morgan Kaufmann Publishers, Inc.</publishername> - </publisher> - <title>Computer Organization and Design</title> - <subtitle>The Hardware / Software Interface</subtitle> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry xreflabel="2"> - <authorgroup> - <author> - <firstname>W.</firstname> - <othername role="Middle">Richard</othername> - <surname>Stevens</surname> - </author> - </authorgroup> - <copyright><year>1993</year><holder>Addison Wesley Longman, - Inc.</holder></copyright> - <isbn>0-201-56317-7</isbn> - <publisher> - <publishername>Addison Wesley Longman, Inc.</publishername> - </publisher> - <title>Advanced Programming in the Unix Environment</title> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry xreflabel="3"> - <authorgroup> - <author> - <firstname>Marshall</firstname> - <othername role="Middle">Kirk</othername> - <surname>McKusick</surname> - </author> - <author> - <firstname>Keith</firstname> - <surname>Bostic</surname> - </author> - <author> - <firstname>Michael</firstname> - <othername role="MI">J</othername> - <surname>Karels</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">S</othername> - <surname>Quarterman</surname> - </author> - </authorgroup> - <copyright><year>1996</year><holder>Addison-Wesley Publishing Company, - Inc.</holder></copyright> - <isbn>0-201-54979-4</isbn> - <publisher> - <publishername>Addison-Wesley Publishing Company, Inc.</publishername> - </publisher> - <title>The Design and Implementation of the 4.4 BSD Operating System</title> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry id="Phrack" xreflabel="4"> - <authorgroup> - <author> - <firstname>Aleph</firstname> - <surname>One</surname> - </author> - </authorgroup> - <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title> - </biblioentry> - - <biblioentry id="StackGuard" xreflabel="5"> - <authorgroup> - <author> - <firstname>Chrispin</firstname> - <surname>Cowan</surname> - </author> - <author> - <firstname>Calton</firstname> - <surname>Pu</surname> - </author> - <author> - <firstname>Dave</firstname> - <surname>Maier</surname> - </author> - </authorgroup> - <title>StackGuard; Automatic Adaptive Detection and Prevention of - Buffer-Overflow Attacks</title> - </biblioentry> - - <biblioentry id="OpenBSD" xreflabel="6"> - <authorgroup> - <author> - <firstname>Todd</firstname> - <surname>Miller</surname> - </author> - <author> - <firstname>Theo</firstname> - <surname>de Raadt</surname> - </author> - </authorgroup> - <title>strlcpy and strlcat -- consistent, safe string copy and - concatenation.</title> - </biblioentry> - - </bibliography> - - </part> - -</book> diff --git a/en_US.ISO8859-1/books/developers-handbook/Makefile b/en_US.ISO8859-1/books/developers-handbook/Makefile deleted file mode 100644 index d9d7ad1454..0000000000 --- a/en_US.ISO8859-1/books/developers-handbook/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# -# $FreeBSD$ -# -# Build the FreeBSD Developers' Handbook. -# - -MAINTAINER=asmodai@FreeBSD.org - -DOC?= book - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml - -# Entities - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml deleted file mode 100644 index bd58d4a25a..0000000000 --- a/en_US.ISO8859-1/books/developers-handbook/book.sgml +++ /dev/null @@ -1,3751 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/book.sgml,v 1.5 2000/11/06 13:52:26 murray Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; -]> - -<book> - <bookinfo> - <title>FreeBSD Developers' Handbook</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - <affiliation> - <address> - <email>doc@FreeBSD.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 2000</pubdate> - - <copyright> - <year>2000</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - &bookinfo.legalnotice; - - <abstract> - <para>Welcome to the Developers' Handbook.</para> - </abstract> - </bookinfo> - - <part id="introduction"> - <title>Introduction</title> - - <chapter id="developmentplatform"> - <title>Developing on FreeBSD</title> - - <para>This will need to discuss FreeBSD as a development - platform, the vision of BSD, architectural overview, layout of - /usr/src, history, etc.</para> - - <para>Thank you for considering FreeBSD as your development - platform! We hope it will not let you down.</para> - </chapter> - - <chapter id="bsdvision"> - <title>The BSD Vision</title> - - <para></para> - </chapter> - - <chapter id="archoverview"> - <title>Architectural Overview</title> - - <para></para> - </chapter> - - <chapter id="sourcelayout"> - <title>The Layout of /usr/src</title> - - <para>The complete source code to FreeBSD is available from our - public CVS repository. The source code is normally installed in - <filename class=directory>/usr/src</filename> which contains the - following subdirectories.</para> - - <para> - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Directory</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename class=directory>bin/</filename></entry> - <entry>Source for files in - <filename>/bin</filename></entry> - </row> - - <row> - <entry><filename class=directory>contrib/</filename></entry> - <entry>Source for files from contribued software.</entry> - </row> - - <row> - <entry><filename class=directory>crypto/</filename></entry> - <entry>DES source</entry> - </row> - - <row> - <entry><filename class=directory>etc/</filename></entry> - <entry>Source for files in <filename - class=directory>/etc</filename></entry> - </row> - - <row> - <entry><filename class=directory>games/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/games</filename></entry> - </row> - - <row> - <entry><filename class=directory>gnu/</filename></entry> - <entry>Utilities covered by the GNU Public License</entry> - </row> - - <row> - <entry><filename class=directory>include/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/include</filename></entry> - </row> - - <row> - <entry><filename - class=directory>kerberosIV/</filename></entry> - <entry>Source for Kerbereros version IV</entry> - </row> - - <row> - <entry><filename - class=directory>kerberos5/</filename></entry> - <entry>Source for Kerbereros version 5</entry> - </row> - - <row> - <entry><filename class=directory>lib/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/lib</filename></entry> - </row> - - <row> - <entry><filename class=directory>libexec/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/libexec</filename></entry> - </row> - - <row> - <entry><filename - class=directory>release/</filename></entry> - <entry>Files required to produce a FreeBSD release</entry> - </row> - - <row> - <entry><filename class=directory>sbin/</filename></entry> - <entry>Source for files in <filename - class=directory>/sbin</filename></entry> - </row> - - <row> - <entry><filename class=directory>secure/</filename></entry> - <entry>FreeSec sources</entry> - </row> - - <row> - <entry><filename class=directory>share/</filename></entry> - <entry>Source for files in <filename - class=directory>/sbin</filename></entry> - </row> - - <row> - <entry><filename class=directory>sys/</filename></entry> - <entry>Kernel source files</entry> - </row> - - <row> - <entry><filename class=directory>tools/</filename></entry> - <entry>Tools used for maintenance and testing of - FreeBSD</entry> - </row> - - <row> - <entry><filename - class=directory>usr.bin/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/bin</filename></entry> - </row> - - <row> - <entry><filename - class=directory>usr.sbin/</filename></entry> - <entry>Source for files in <filename - class=directory>/usr/sbin</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - </para> - - </chapter> - </part> - - <part id="Basics"> - <title>Basics</title> - - <chapter id="programming-tools"> - <title>Programming Tools</title> - - <para><emphasis>This chapter was written by James Raynard. - Modifications for the Developer's Handbook by Murray Stokely. - </emphasis></para> - - <sect1><title>Synopsis</title> - - <para>This document is an introduction to using some of the - programming tools supplied with FreeBSD, although much of it - will be applicable to many other versions of Unix. It does - <emphasis>not</emphasis> attempt to describe coding in any - detail. Most of the document assumes little or no previous - programming knowledge, although it is hoped that most - programmers will find something of value in it</para> - - </sect1> - - <sect1><title>Introduction</title> - - <para>FreeBSD offers an excellent development environment. - Compilers for C, C++, and Fortran and an assembler come with the - basic system, not to mention a Perl interpreter and classic Unix - tools such as <command>sed</command> and <command>awk</command>. - If that is not enough, there are many more compilers and - interpreters in the Ports collection. FreeBSD is very - compatible with standards such as <acronym>POSIX</acronym> and - <acronym>ANSI</acronym> C, as well with its own BSD heritage, so - it is possible to write applications that will compile and run - with little or no modification on a wide range of - platforms.</para> - - <para>However, all this power can be rather overwhelming at - first if you've never written programs on a Unix platform - before. This document aims to help you get up and running, - without getting too deeply into more advanced topics. The - intention is that this document should give you enough of the - basics to be able to make some sense of the - documentation.</para> - - <para>Most of the document requires little or no knowledge of - programming, although it does assume a basic competence with - using Unix and a willingness to learn!</para> - - </sect1> - - <sect1> - <title>Introduction to Programming</title> - - <para>A program is a set of instructions that tell the computer - to do various things; sometimes the instruction it has to - perform depends on what happened when it performed a previous - instruction. This section gives an overview of the two main - ways in which you can give these instructions, or - <quote>commands</quote> as they are usually called. One way - uses an <firstterm>interpreter</firstterm>, the other a - <firstterm>compiler</firstterm>. As human languages are too - difficult for a computer to understand in an unambiguous way, - commands are usually written in one or other languages specially - designed for the purpose.</para> - - <sect2> - <title>Interpreters</title> - - <para>With an interpreter, the language comes as an environment, - where you type in commands at a prompt and the environment - executes them for you. For more complicated programs, you can - type the commands into a file and get the interpreter to load - the file and execute the commands in it. If anything goes - wrong, many interpreters will drop you into a debugger to help - you track down the problem.</para> - - <para>The advantage of this is that you can see the results of - your commands immediately, and mistakes can be corrected - readily. The biggest disadvantage comes when you want to - share your programs with someone. They must have the same - interpreter, or you must have some way of giving it to them, - and they need to understand how to use it. Also users may not - appreciate being thrown into a debugger if they press the - wrong key! From a performance point of view, interpreters can - use up a lot of memory, and generally do not generate code as - efficiently as compilers.</para> - - <para>In my opinion, interpreted languages are the best way to - start if you have not done any programming before. This kind - of environment is typically found with languages like Lisp, - Smalltalk, Perl and Basic. It could also be argued that the - Unix shell (<command>sh</command>, <command>csh</command>) is itself an - interpreter, and many people do in fact write shell - <quote>scripts</quote> to help with various - <quote>housekeeping</quote> tasks on their machine. Indeed, part - of the original Unix philosophy was to provide lots of small - utility programs that could be linked together in shell - scripts to perform useful tasks.</para> - </sect2> - - <sect2> - <title>Interpreters available with FreeBSD</title> - - <para>Here is a list of interpreters that are available as - <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink>, with a brief discussion of some of the - more popular interpreted languages.</para> - - <para>To get one of these packages, all you need to do is to - click on the hotlink for the package, then run</para> - - <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput> - </screen> - - <para>as root. Obviously, you will need to have a fully - functional FreeBSD 2.1.0 or later system for the package to - work!</para> - - <variablelist> - <varlistentry> - <term><acronym>BASIC</acronym></term> - - <listitem> - <para>Short for Beginner's All-purpose Symbolic - Instruction Code. Developed in the 1950s for teaching - University students to program and provided with every - self-respecting personal computer in the 1980s, - <acronym>BASIC</acronym> has been the first programming - language for many programmers. It's also the foundation - for Visual Basic.</para> - - <para>The <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater - Basic Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil - Cockroft's Basic Interpreter</ulink> (formerly Rabbit - Basic) are available as FreeBSD <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Lisp</term> - - <listitem> - <para>A language that was developed in the late 1950s as - an alternative to the <quote>number-crunching</quote> - languages that were popular at the time. Instead of - being based on numbers, Lisp is based on lists; in fact - the name is short for <quote>List Processing</quote>. - Very popular in AI (Artificial Intelligence) - circles.</para> - - <para>Lisp is an extremely powerful and sophisticated - language, but can be rather large and unwieldy.</para> - - <para>FreeBSD has <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU - Common Lisp</ulink> available as a package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Perl</term> - - <listitem> - <para>Very popular with system administrators for writing - scripts; also often used on World Wide Web servers for - writing <acronym>CGI</acronym> scripts.</para> - - <para>The latest version (version 5) comes with FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Scheme</term> - - <listitem> - <para>A dialect of Lisp that is rather more compact and - cleaner than Common Lisp. Popular in Universities as it - is simple enough to teach to undergraduates as a first - language, while it has a high enough level of - abstraction to be used in research work.</para> - - <para>FreeBSD has packages of the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk - Scheme Interpreter</ulink>, the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT - Scheme Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM - Scheme Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Icon</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The - Icon Programming Language</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Logo</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian - Harvey's LOGO Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Python</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/python-1.2">The - Python Object-Oriented Programming - Language</ulink></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Compilers</title> - - <para>Compilers are rather different. First of all, you write - your code in a file (or files) using an editor. You then run - the compiler and see if it accepts your program. If it did - not compile, grit your teeth and go back to the editor; if it - did compile and gave you a program, you can run it either at a - shell command prompt or in a debugger to see if it works - properly. - - <footnote> - <para>If you run it in the shell, you may get a core - dump.</para> - </footnote></para> - - <para>Obviously, this is not quite as direct as using an - interpreter. However it allows you to do a lot of things - which are very difficult or even impossible with an - interpreter, such as writing code which interacts closely with - the operating system—or even writing your own operating - system! It's also useful if you need to write very efficient - code, as the compiler can take its time and optimise the code, - which would not be acceptable in an interpreter. And - distributing a program written for a compiler is usually more - straightforward than one written for an interpreter—you - can just give them a copy of the executable, assuming they - have the same operating system as you.</para> - - <para>Compiled languages include Pascal, C and C++. C and C++ - are rather unforgiving languages, and best suited to more - experienced programmers; Pascal, on the other hand, was - designed as an educational language, and is quite a good - language to start with. Unfortunately, FreeBSD doesn't have - any Pascal support, except for a Pascal-to-C converter in the - ports.</para> - - <para>As the edit-compile-run-debug cycle is rather tedious when - using separate programs, many commercial compiler makers have - produced Integrated Development Environments - - (<acronym>IDE</acronym>s for short). FreeBSD does not have an - <acronym>IDE</acronym> as such; however it is possible to use Emacs - for this purpose. This is discussed in <xref - linkend="emacs">.</para> - </sect2> - - - </sect1> - - - <sect1> - <title>Compiling with <command>cc</command></title> - - <para>This section deals only with the GNU compiler for C and C++, - since that comes with the base FreeBSD system. It can be - invoked by either <command>cc</command> or <command>gcc</command>. The - details of producing a program with an interpreter vary - considerably between interpreters, and are usually well covered - in the documentation and on-line help for the - interpreter.</para> - - <para>Once you've written your masterpiece, the next step is to - convert it into something that will (hopefully!) run on FreeBSD. - This usually involves several steps, each of which is done by a - separate program.</para> - - <procedure> - <step> - <para>Pre-process your source code to remove comments and do - other tricks like expanding macros in C.</para> - </step> - - <step> - <para>Check the syntax of your code to see if you have obeyed - the rules of the language. If you have not, it will - complain!</para> - </step> - - <step> - <para>Convert the source code into assembly - language—this is very close to machine code, but still - understandable by humans. Allegedly. - - <footnote> - <para>To be strictly accurate, <command>cc</command> converts the - source code into its own, machine-independent - <firstterm>p-code</firstterm> instead of assembly language at - this stage.</para> - </footnote></para> - </step> - - <step> - <para>Convert the assembly language into machine - code—yep, we are talking bits and bytes, ones and - zeros here.</para> - </step> - - <step> - <para>Check that you have used things like functions and - global variables in a consistent way. For example, if you - have called a non-existent function, it will - complain.</para> - </step> - - <step> - <para>If you are trying to produce an executable from several - source code files, work out how to fit them all - together.</para> - </step> - - <step> - <para>Work out how to produce something that the system's - run-time loader will be able to load into memory and - run.</para> - </step> - - <step> - <para>Finally, write the executable on the file system.</para> - </step> - </procedure> - - <para>The word <firstterm>compiling</firstterm> is often used to refer to - just steps 1 to 4—the others are referred to as - <firstterm>linking</firstterm>. Sometimes step 1 is referred to as - <firstterm>pre-processing</firstterm> and steps 3-4 as - <firstterm>assembling</firstterm>.</para> - - <para>Fortunately, almost all this detail is hidden from you, as - <command>cc</command> is a front end that manages calling all these - programs with the right arguments for you; simply typing</para> - - <screen>&prompt.user; <userinput>cc foobar.c</> - </screen> - - <para>will cause <filename>foobar.c</filename> to be compiled by all the - steps above. If you have more than one file to compile, just do - something like</para> - - <screen>&prompt.user; <userinput>cc foo.c bar.c</> - </screen> - - <para>Note that the syntax checking is just that—checking - the syntax. It will not check for any logical mistakes you may - have made, like putting the program into an infinite loop, or - using a bubble sort when you meant to use a binary - sort. - - <footnote> - <para>In case you didn't know, a binary sort is an efficient - way of sorting things into order and a bubble sort - isn't.</para> - </footnote></para> - - <para>There are lots and lots of options for <command>cc</command>, which - are all in the man page. Here are a few of the most important - ones, with examples of how to use them.</para> - - <variablelist> - <varlistentry> - <term><option>-o <replaceable>filename</replaceable></option></term> - - <listitem> - <para>The output name of the file. If you do not use this - option, <command>cc</command> will produce an executable called - <filename>a.out</filename>. - - <footnote> - <para>The reasons for this are buried in the mists of - history.</para> - </footnote></para> - - <informalexample> - <screen>&prompt.user; <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -&prompt.user; <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></> - </screen> - </informalexample> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Just compile the file, do not link it. Useful for toy - programs where you just want to check the syntax, or if - you are using a <filename>Makefile</filename>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -c foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an <firstterm>object file</firstterm> (not an - executable) called <filename>foobar.o</filename>. This - can be linked together with other object files into an - executable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Create a debug version of the executable. This makes - the compiler put information into the executable about - which line of which source file corresponds to which - function call. A debugger can use this information to show - the source code as you step through the program, which is - <emphasis>very</emphasis> useful; the disadvantage is that - all this extra information makes the program much bigger. - Normally, you compile with <option>-g</option> while you - are developing a program and then compile a <quote>release - version</quote> without <option>-g</option> when you're - satisfied it works properly.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -g foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce a debug version of the - program. - - <footnote> - <para>Note, we didn't use the <option>-o</option> flag - to specify the executable name, so we will get an - executable called <filename>a.out</filename>. - Producing a debug version called - <filename>foobar</filename> is left as an exercise for - the reader!</para> - </footnote></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-O</option></term> - - <listitem> - <para>Create an optimised version of the executable. The - compiler performs various clever tricks to try and produce - an executable that runs faster than normal. You can add a - number after the <option>-O</option> to specify a higher - level of optimisation, but this often exposes bugs in the - compiler's optimiser. For instance, the version of - <command>cc</command> that comes with the 2.1.0 release of - FreeBSD is known to produce bad code with the - <option>-O2</option> option in some circumstances.</para> - - <para>Optimisation is usually only turned on when compiling - a release version.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an optimised version of - <filename>foobar</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following three flags will force <command>cc</command> - to check that your code complies to the relevant international - standard, often referred to as the <acronym>ANSI</acronym> - standard, though strictly speaking it is an - <acronym>ISO</acronym> standard.</para> - - <variablelist> - <varlistentry> - <term><option>-Wall</option></term> - - <listitem> - <para>Enable all the warnings which the authors of - <command>cc</command> believe are worthwhile. Despite the - name, it will not enable all the warnings - <command>cc</command> is capable of.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ansi</option></term> - - <listitem> - <para>Turn off most, but not all, of the - non-<acronym>ANSI</acronym> C features provided by - <command>cc</command>. Despite the name, it does not - guarantee strictly that your code will comply to the - standard.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-pedantic</option></term> - - <listitem> - <para>Turn off <emphasis>all</emphasis> - <command>cc</command>'s non-<acronym>ANSI</acronym> C - features.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Without these flags, <command>cc</command> will allow you to - use some of its non-standard extensions to the standard. Some - of these are very useful, but will not work with other - compilers—in fact, one of the main aims of the standard is - to allow people to write code that will work with any compiler - on any system. This is known as <firstterm>portable - code</firstterm>.</para> - - <para>Generally, you should try to make your code as portable as - possible, as otherwise you may have to completely re-write the - program later to get it to work somewhere else—and who - knows what you may be using in a few years time?</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an executable <filename>foobar</filename> - after checking <filename>foobar.c</filename> for standard - compliance.</para> - - <variablelist> - <varlistentry> - <term><option>-l<replaceable>library</replaceable></option></term> - - <listitem> - <para>Specify a function library to be used during when - linking.</para> - - <para>The most common example of this is when compiling a - program that uses some of the mathematical functions in C. - Unlike most other platforms, these are in a separate - library from the standard C one and you have to tell the - compiler to add it.</para> - - <para>The rule is that if the library is called - <filename>lib<replaceable>something</replaceable>.a</filename>, - you give <command>cc</command> the argument - <option>-l<replaceable>something</replaceable></option>. - For example, the math library is - <filename>libm.a</filename>, so you give - <command>cc</command> the argument <option>-lm</option>. - A common <quote>gotcha</quote> with the math library is - that it has to be the last library on the command - line.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - - <para>This will link the math library functions into - <filename>foobar</filename>.</para> - - <para>If you are compiling C++ code, you need to add - <option>-lg++</option>, or <option>-lstdc++</option> if - you are using FreeBSD 2.2 or later, to the command line - argument to link the C++ library functions. - Alternatively, you can run <command>c++</command> instead - of <command>cc</command>, which does this for you. - <command>c++</command> can also be invoked as - <command>g++</command> on FreeBSD.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -&prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput> - </screen> - </informalexample> - - <para>Each of these will both produce an executable - <filename>foobar</filename> from the C++ source file - <filename>foobar.cc</filename>. Note that, on Unix - systems, C++ source files traditionally end in - <filename>.C</filename>, <filename>.cxx</filename> or - <filename>.cc</filename>, rather than the - MS-DOS style - <filename>.cpp</filename> (which was already used for - something else). <command>gcc</command> used to rely on - this to work out what kind of compiler to use on the - source file; however, this restriction no longer applies, - so you may now call your C++ files - <filename>.cpp</filename> with impunity!</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Common <command>cc</command> Queries and Problems</title> - - <qandaset> - <qandaentry> - <question> - <para>I am trying to write a program which uses the - <function>sin()</function> function and I get an error - like this. What does it mean?</para> - - <informalexample> - <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - </screen> - </informalexample> - </question> - - <answer> - <para>When using mathematical functions like - <function>sin()</function>, you have to tell - <command>cc</command> to link in the math library, like - so:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>All right, I wrote this simple program to practice - using <option>-lm</option>. All it does is raise 2.1 to - the power of 6.</para> - - <informalexample> - <programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - </programlisting> - </informalexample> - - <para>and I compiled it as:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc temp.c -lm</userinput> - </screen> - </informalexample> - - <para>like you said I should, but I get this when I run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000 - </screen> - </informalexample> - - <para>This is <emphasis>not</emphasis> the right answer! - What is going on?</para> - </question> - - <answer> - <para>When the compiler sees you call a function, it - checks if it has already seen a prototype for it. If it - has not, it assumes the function returns an - <type>int</type>, which is definitely not what you want - here.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>So how do I fix this?</para> - </question> - - <answer> - <para>The prototypes for the mathematical functions are in - <filename>math.h</filename>. If you include this file, - the compiler will be able to find the prototype and it - will stop doing strange things to your - calculation!</para> - - <informalexample> - <programlisting>#include <math.h> -#include <stdio.h> - -int main() { -... - </programlisting> - </informalexample> - - <para>After recompiling it as you did before, run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121 - </screen> - </informalexample> - - <para>If you are using any of the mathematical functions, - <emphasis>always</emphasis> include - <filename>math.h</filename> and remember to link in the - math library.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled a file called - <filename>foobar.c</filename> and I cannot find an - executable called <filename>foobar</filename>. Where's - it gone?</para> - </question> - - <answer> - <para>Remember, <command>cc</command> will call the - executable <filename>a.out</filename> unless you tell it - differently. Use the - <option>-o <replaceable>filename</replaceable></option> - option:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, I have an executable called - <filename>foobar</filename>, I can see it when I run - <command>ls</command>, but when I type in - <command>foobar</command> at the command prompt it tells - me there is no such file. Why can it not find - it?</para> - </question> - - <answer> - <para>Unlike MS-DOS, Unix does not - look in the current directory when it is trying to find - out which executable you want it to run, unless you tell - it to. Either type <command>./foobar</command>, which - means <quote>run the file called - <filename>foobar</filename> in the current - directory</quote>, or change your <systemitem - class=environvar>PATH</systemitem> environment - variable so that it looks something like</para> - - <informalexample> - <screen>bin:/usr/bin:/usr/local/bin:. - </screen> - </informalexample> - - <para>The dot at the end means <quote>look in the current - directory if it is not in any of the - others</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I called my executable <filename>test</filename>, - but nothing happens when I run it. What is going - on?</para> - </question> - - <answer> - <para>Most Unix systems have a program called - <command>test</command> in <filename>/usr/bin</filename> - and the shell is picking that one up before it gets to - checking the current directory. Either type:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./test</userinput> - </screen> - </informalexample> - - <para>or choose a better name for your program!</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled my program and it seemed to run all right - at first, then there was an error and it said something - about <errorname>core dumped</errorname>. What does that - mean?</para> - </question> - - <answer> - <para>The name <firstterm>core dump</firstterm> dates back - to the very early days of Unix, when the machines used - core memory for storing data. Basically, if the program - failed under certain conditions, the system would write - the contents of core memory to disk in a file called - <filename>core</filename>, which the programmer could - then pore over to find out what went wrong.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Fascinating stuff, but what I am supposed to do - now?</para> - </question> - - <answer> - <para>Use <command>gdb</command> to analyse the core (see - <xref linkend="debugging">).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When my program dumped core, it said something about - a <errorname>segmentation fault</errorname>. What's - that?</para> - </question> - - <answer> - <para>This basically means that your program tried to - perform some sort of illegal operation on memory; Unix - is designed to protect the operating system and other - programs from rogue programs.</para> - - <para>Common causes for this are:</para> - - <itemizedlist> - <listitem> - <para>Trying to write to a <symbol>NULL</symbol> - pointer, eg</para> - - <programlisting>char *foo = NULL; -strcpy(foo, "bang!"); - </programlisting> - </listitem> - - <listitem> - <para>Using a pointer that hasn't been initialised, - eg</para> - - <programlisting>char *foo; -strcpy(foo, "bang!"); - </programlisting> - - <para>The pointer will have some random value that, - with luck, will point into an area of memory that - isn't available to your program and the kernel will - kill your program before it can do any damage. If - you're unlucky, it'll point somewhere inside your - own program and corrupt one of your data structures, - causing the program to fail mysteriously.</para> - </listitem> - - <listitem> - <para>Trying to access past the end of an array, - eg</para> - - <programlisting>int bar[20]; -bar[27] = 6; - </programlisting> - </listitem> - - <listitem> - <para>Trying to store something in read-only memory, - eg</para> - - <programlisting>char *foo = "My string"; -strcpy(foo, "bang!"); - </programlisting> - - <para>Unix compilers often put string literals like - <literal>"My string"</literal> into read-only areas - of memory.</para> - </listitem> - - <listitem> - <para>Doing naughty things with - <function>malloc()</function> and - <function>free()</function>, eg</para> - - <programlisting>char bar[80]; -free(bar); - </programlisting> - - <para>or</para> - - <programlisting>char *foo = malloc(27); -free(foo); -free(foo); - </programlisting> - </listitem> - </itemizedlist> - - <para>Making one of these mistakes will not always lead to - an error, but they are always bad practice. Some - systems and compilers are more tolerant than others, - which is why programs that ran well on one system can - crash when you try them on an another.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Sometimes when I get a core dump it says - <errorname>bus error</errorname>. It says in my Unix - book that this means a hardware problem, but the - computer still seems to be working. Is this - true?</para> - </question> - - <answer> - <para>No, fortunately not (unless of course you really do - have a hardware problem…). This is usually - another way of saying that you accessed memory in a way - you shouldn't have.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>This dumping core business sounds as though it could - be quite useful, if I can make it happen when I want to. - Can I do this, or do I have to wait until there's an - error?</para> - </question> - - <answer> - <para>Yes, just go to another console or xterm, do</para> - - <screen>&prompt.user; <userinput>ps</userinput> - </screen> - - <para>to find out the process ID of your program, and - do</para> - - <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput> - </screen> - - <para>where - <parameter><replaceable>pid</replaceable></parameter> is - the process ID you looked up.</para> - - <para>This is useful if your program has got stuck in an - infinite loop, for instance. If your program happens to - trap <symbol>SIGABRT</symbol>, there are several other - signals which have a similar effect.</para> - </answer> - </qandaentry> - </qandaset> - </sect2> - </sect1> - - <sect1> - <title>Make</title> - - <sect2> - <title>What is <command>make</command>?</title> - - <para>When you're working on a simple program with only one or - two source files, typing in</para> - - <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput> - </screen> - - <para>is not too bad, but it quickly becomes very tedious when - there are several files—and it can take a while to - compile, too.</para> - - <para>One way to get around this is to use object files and only - recompile the source file if the source code has changed. So - we could have something like:</para> - - <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip - </screen> - - <para>if we'd changed <filename>file37.c</filename>, but not any - of the others, since the last time we compiled. This may - speed up the compilation quite a bit, but doesn't solve the - typing problem.</para> - - <para>Or we could write a shell script to solve the typing - problem, but it would have to re-compile everything, making it - very inefficient on a large project.</para> - - <para>What happens if we have hundreds of source files lying - about? What if we're working in a team with other people who - forget to tell us when they've changed one of their source - files that we use?</para> - - <para>Perhaps we could put the two solutions together and write - something like a shell script that would contain some kind of - magic rule saying when a source file needs compiling. Now all - we need now is a program that can understand these rules, as - it's a bit too complicated for the shell.</para> - - <para>This program is called <command>make</command>. It reads - in a file, called a <firstterm>makefile</firstterm>, that - tells it how different files depend on each other, and works - out which files need to be re-compiled and which ones don't. - For example, a rule could say something like <quote>if - <filename>fromboz.o</filename> is older than - <filename>fromboz.c</filename>, that means someone must have - changed <filename>fromboz.c</filename>, so it needs to be - re-compiled.</quote> The makefile also has rules telling - make <emphasis>how</emphasis> to re-compile the source file, - making it a much more powerful tool.</para> - - <para>Makefiles are typically kept in the same directory as the - source they apply to, and can be called - <filename>makefile</filename>, <filename>Makefile</filename> - or <filename>MAKEFILE</filename>. Most programmers use the - name <filename>Makefile</filename>, as this puts it near the - top of a directory listing, where it can easily be - seen. - - <footnote> - <para>They don't use the <filename>MAKEFILE</filename> form - as block capitals are often used for documentation files - like <filename>README</filename>.</para> - </footnote></para> - </sect2> - - <sect2> - <title>Example of using <command>make</command></title> - - <para>Here's a very simple make file:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - </programlisting> - - <para>It consists of two lines, a dependency line and a creation - line.</para> - - <para>The dependency line here consists of the name of the - program (known as the <firstterm>target</firstterm>), followed - by a colon, then whitespace, then the name of the source file. - When <command>make</command> reads this line, it looks to see - if <filename>foo</filename> exists; if it exists, it compares - the time <filename>foo</filename> was last modified to the - time <filename>foo.c</filename> was last modified. If - <filename>foo</filename> does not exist, or is older than - <filename>foo.c</filename>, it then looks at the creation line - to find out what to do. In other words, this is the rule for - working out when <filename>foo.c</filename> needs to be - re-compiled.</para> - - <para>The creation line starts with a <token>tab</token> (press - the <keycap>tab</keycap> key) and then the command you would - type to create <filename>foo</filename> if you were doing it - at a command prompt. If <filename>foo</filename> is out of - date, or does not exist, <command>make</command> then executes - this command to create it. In other words, this is the rule - which tells make how to re-compile - <filename>foo.c</filename>.</para> - - <para>So, when you type <userinput>make</userinput>, it will - make sure that <filename>foo</filename> is up to date with - respect to your latest changes to <filename>foo.c</filename>. - This principle can be extended to - <filename>Makefile</filename>s with hundreds of - targets—in fact, on FreeBSD, it is possible to compile - the entire operating system just by typing <userinput>make - world</userinput> in the appropriate directory!</para> - - <para>Another useful property of makefiles is that the targets - don't have to be programs. For instance, we could have a make - file that looks like this:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me - </programlisting> - - <para>We can tell make which target we want to make by - typing:</para> - - <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput> - </screen> - - <para><command>make</command> will then only look at that target - and ignore any others. For example, if we type - <userinput>make foo</userinput> with the makefile above, make - will ignore the <action>install</action> target.</para> - - <para>If we just type <userinput>make</userinput> on its own, - make will always look at the first target and then stop - without looking at any others. So if we typed - <userinput>make</userinput> here, it will just go to the - <action>foo</action> target, re-compile - <filename>foo</filename> if necessary, and then stop without - going on to the <action>install</action> target.</para> - - <para>Notice that the <action>install</action> target doesn't - actually depend on anything! This means that the command on - the following line is always executed when we try to make that - target by typing <userinput>make install</userinput>. In this - case, it will copy <filename>foo</filename> into the user's - home directory. This is often used by application makefiles, - so that the application can be installed in the correct - directory when it has been correctly compiled.</para> - - <para>This is a slightly confusing subject to try and explain. - If you don't quite understand how <command>make</command> - works, the best thing to do is to write a simple program like - <quote>hello world</quote> and a make file like the one above - and experiment. Then progress to using more than one source - file, or having the source file include a header file. The - <command>touch</command> command is very useful here—it - changes the date on a file without you having to edit - it.</para> - </sect2> - - <sect2> - <title>FreeBSD Makefiles</title> - - <para>Makefiles can be rather complicated to write. Fortunately, - BSD-based systems like FreeBSD come with some very powerful - ones as part of the system. One very good example of this is - the FreeBSD ports system. Here's the essential part of a - typical ports <filename>Makefile</filename>:</para> - - <programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk> - </programlisting> - - <para>Now, if we go to the directory for this port and type - <userinput>make</userinput>, the following happens:</para> - - <procedure> - <step> - <para>A check is made to see if the source code for this - port is already on the system.</para> - </step> - - <step> - <para>If it isn't, an FTP connection to the URL in - <symbol>MASTER_SITES</symbol> is set up to download the - source.</para> - </step> - - <step> - <para>The checksum for the source is calculated and compared - it with one for a known, good, copy of the source. This - is to make sure that the source was not corrupted while in - transit.</para> - </step> - - <step> - <para>Any changes required to make the source work on - FreeBSD are applied—this is known as - <firstterm>patching</firstterm>.</para> - </step> - - <step> - <para>Any special configuration needed for the source is - done. (Many Unix program distributions try to work out - which version of Unix they are being compiled on and which - optional Unix features are present—this is where - they are given the information in the FreeBSD ports - scenario).</para> - </step> - - <step> - <para>The source code for the program is compiled. In - effect, we change to the directory where the source was - unpacked and do <command>make</command>—the - program's own make file has the necessary information to - build the program.</para> - </step> - - <step> - <para>We now have a compiled version of the program. If we - wish, we can test it now; when we feel confident about the - program, we can type <userinput>make install</userinput>. - This will cause the program and any supporting files it - needs to be copied into the correct location; an entry is - also made into a <database>package database</database>, so - that the port can easily be uninstalled later if we change - our mind about it.</para> - </step> - </procedure> - - <para>Now I think you'll agree that's rather impressive for a - four line script!</para> - - <para>The secret lies in the last line, which tells - <command>make</command> to look in the system makefile called - <filename>bsd.port.mk</filename>. It's easy to overlook this - line, but this is where all the clever stuff comes - from—someone has written a makefile that tells - <command>make</command> to do all the things above (plus a - couple of other things I didn't mention, including handling - any errors that may occur) and anyone can get access to that - just by putting a single line in their own make file!</para> - - <para>If you want to have a look at these system makefiles, - they're in <filename>/usr/share/mk</filename>, but it's - probably best to wait until you've had a bit of practice with - makefiles, as they are very complicated (and if you do look at - them, make sure you have a flask of strong coffee - handy!)</para> - </sect2> - - <sect2> - <title>More advanced uses of <command>make</command></title> - - <para><command>Make</command> is a very powerful tool, and can - do much more than the simple example above shows. - Unfortunately, there are several different versions of - <command>make</command>, and they all differ considerably. - The best way to learn what they can do is probably to read the - documentation—hopefully this introduction will have - given you a base from which you can do this.</para> - - <para>The version of make that comes with FreeBSD is the - <application>Berkeley make</application>; there is a tutorial - for it in <filename>/usr/share/doc/psd/12.make</filename>. To - view it, do</para> - - <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput> - </screen> - - <para>in that directory.</para> - - <para>Many applications in the ports use <application>GNU - make</application>, which has a very good set of - <quote>info</quote> pages. If you have installed any of these - ports, <application>GNU make</application> will automatically - have been installed as <command>gmake</command>. It's also - available as a port and package in its own right.</para> - - <para>To view the info pages for <application>GNU - make</application>, you will have to edit the - <filename>dir</filename> file in the - <filename>/usr/local/info</filename> directory to add an entry - for it. This involves adding a line like</para> - - <programlisting> * Make: (make). The GNU Make utility. - </programlisting> - - <para>to the file. Once you have done this, you can type - <userinput>info</userinput> and then select - <guimenuitem>make</guimenuitem> from the menu (or in - <application>Emacs</application>, do <userinput>C-h - i</userinput>).</para> - </sect2> - </sect1> - - <sect1 id="debugging"> - <title>Debugging</title> - - <sect2> - <title>The Debugger</title> - - <para>The debugger that comes with FreeBSD is called - <command>gdb</command> (<application>GNU - debugger</application>). You start it up by typing</para> - - <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput> - </screen> - - <para>although most people prefer to run it inside - <application>Emacs</application>. You can do this by:</para> - - <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput> - </screen> - - <para>Using a debugger allows you to run the program under more - controlled circumstances. Typically, you can step through the - program a line at a time, inspect the value of variables, - change them, tell the debugger to run up to a certain point - and then stop, and so on. You can even attach to a program - that's already running, or load a core file to investigate why - the program crashed. It's even possible to debug the kernel, - though that's a little trickier than the user applications - we'll be discussing in this section.</para> - - <para><command>gdb</command> has quite good on-line help, as - well as a set of info pages, so this section will concentrate - on a few of the basic commands.</para> - - <para>Finally, if you find its text-based command-prompt style - off-putting, there's a graphical front-end for it <ulink - URL="../../ports/devel.html">xxgdb</ulink> in the ports - collection.</para> - - <para>This section is intended to be an introduction to using - <command>gdb</command> and does not cover specialised topics - such as debugging the kernel.</para> - </sect2> - - <sect2> - <title>Running a program in the debugger</title> - - <para>You'll need to have compiled the program with the - <option>-g</option> option to get the most out of using - <command>gdb</command>. It will work without, but you'll only - see the name of the function you're in, instead of the source - code. If you see a line like:</para> - - <screen>… (no debugging symbols found) … - </screen> - - <para>when <command>gdb</command> starts up, you'll know that - the program wasn't compiled with the <option>-g</option> - option.</para> - - <para>At the <command>gdb</command> prompt, type - <userinput>break main</userinput>. This will tell the - debugger to skip over the preliminary set-up code in the - program and start at the beginning of your code. Now type - <userinput>run</userinput> to start the program—it will - start at the beginning of the set-up code and then get stopped - by the debugger when it calls <function>main()</function>. - (If you've ever wondered where <function>main()</function> - gets called from, now you know!).</para> - - <para>You can now step through the program, a line at a time, by - pressing <command>n</command>. If you get to a function call, - you can step into it by pressing <command>s</command>. Once - you're in a function call, you can return from stepping into a - function call by pressing <command>f</command>. You can also - use <command>up</command> and <command>down</command> to take - a quick look at the caller.</para> - - <para>Here's a simple example of how to spot a mistake in a - program with <command>gdb</command>. This is our program - (with a deliberate mistake):</para> - - <programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -} - </programlisting> - - <para>This program sets <symbol>i</symbol> to be - <literal>5</literal> and passes it to a function - <function>bazz()</function> which prints out the number we - gave it.</para> - - <para>When we compile and run the program we get</para> - - <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput> -&prompt.user; <userinput>./temp</userinput> -This is my program -anint = 4231 - </screen> - - <para>That wasn't what we expected! Time to see what's going - on!</para> - - <screen>&prompt.user; <userinput>gdb temp</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) - </screen> - - <para>Hang on a minute! How did <symbol>anint</symbol> get to be - <literal>4231</literal>? Didn't we set it to be - <literal>5</literal> in <function>main()</function>? Let's - move up to <function>main()</function> and have a look.</para> - - <screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></> - </screen> - - <para>Oh dear! Looking at the code, we forgot to initialise - <symbol>i</symbol>. We meant to put</para> - - <programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</> - </programlisting> - - <para>but we left the <literal>i=5;</literal> line out. As we - didn't initialise <symbol>i</symbol>, it had whatever number - happened to be in that area of memory when the program ran, - which in this case happened to be - <literal>4231</literal>.</para> - - <note> - <para><command>gdb</command> displays the stack frame every - time we go into or out of a function, even if we're using - <command>up</command> and <command>down</command> to move - around the call stack. This shows the name of the function - and the values of its arguments, which helps us keep track - of where we are and what's going on. (The stack is a - storage area where the program stores information about the - arguments passed to functions and where to go when it - returns from a function call).</para> - </note> - </sect2> - - <sect2> - <title>Examining a core file</title> - - <para>A core file is basically a file which contains the - complete state of the process when it crashed. In <quote>the - good old days</quote>, programmers had to print out hex - listings of core files and sweat over machine code manuals, - but now life is a bit easier. Incidentally, under FreeBSD and - other 4.4BSD systems, a core file is called - <filename><replaceable>progname</replaceable>.core</filename> instead of just - <filename>core</filename>, to make it clearer which program a - core file belongs to.</para> - - <para>To examine a core file, start up <command>gdb</command> in - the usual way. Instead of typing <command>break</command> or - <command>run</command>, type</para> - - <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput> - </screen> - - <para>If you're not in the same directory as the core file, - you'll have to do <userinput>dir - /path/to/core/file</userinput> first.</para> - - <para>You should see something like this:</para> - - <screen>&prompt.user; <userinput>gdb a.out</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - </screen> - - <para>In this case, the program was called - <filename>a.out</filename>, so the core file is called - <filename>a.out.core</filename>. We can see that the program - crashed due to trying to access an area in memory that was not - available to it in a function called - <function>bazz</function>.</para> - - <para>Sometimes it's useful to be able to see how a function was - called, as the problem could have occurred a long way up the - call stack in a complex program. The <command>bt</command> - command causes <command>gdb</command> to print out a - back-trace of the call stack:</para> - - <screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb) - </screen> - - <para>The <function>end()</function> function is called when a - program crashes; in this case, the <function>bazz()</function> - function was called from <function>main()</function>.</para> - </sect2> - - <sect2> - <title>Attaching to a running program</title> - - <para>One of the neatest features about <command>gdb</command> - is that it can attach to a program that's already running. Of - course, that assumes you have sufficient permissions to do so. - A common problem is when you are stepping through a program - that forks, and you want to trace the child, but the debugger - will only let you trace the parent.</para> - - <para>What you do is start up another <command>gdb</command>, - use <command>ps</command> to find the process ID for the - child, and do</para> - - <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput> - </screen> - - <para>in <command>gdb</command>, and then debug as usual.</para> - - <para><quote>That's all very well,</quote> you're probably - thinking, <quote>but by the time I've done that, the child - process will be over the hill and far away</quote>. Fear - not, gentle reader, here's how to do it (courtesy of the - <command>gdb</command> info pages):</para> - - <screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation> - </screen> - - <para>Now all you have to do is attach to the child, set - <symbol>PauseMode</symbol> to <literal>0</literal>, and wait - for the <function>sleep()</function> call to return!</para> - </sect2> - </sect1> - - <sect1 id="emacs"> - <title>Using Emacs as a Development Environment</title> - - <sect2> - <title>Emacs</title> - - <para>Unfortunately, Unix systems don't come with the kind of - everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package - integrated development environments that other systems - have. - - <footnote> - <para>At least, not unless you pay out very large sums of - money.</para> - </footnote> - - However, it is possible to set up your own environment. It - may not be as pretty, and it may not be quite as integrated, - but you can set it up the way you want it. And it's free. - And you have the source to it.</para> - - <para>The key to it all is Emacs. Now there are some people who - loathe it, but many who love it. If you're one of the former, - I'm afraid this section will hold little of interest to you. - Also, you'll need a fair amount of memory to run it—I'd - recommend 8MB in text mode and 16MB in X as the bare minimum - to get reasonable performance.</para> - - <para>Emacs is basically a highly customisable - editor—indeed, it has been customised to the point where - it's more like an operating system than an editor! Many - developers and sysadmins do in fact spend practically all - their time working inside Emacs, leaving it only to log - out.</para> - - <para>It's impossible even to summarise everything Emacs can do - here, but here are some of the features of interest to - developers:</para> - - <itemizedlist> - <listitem> - <para>Very powerful editor, allowing search-and-replace on - both strings and regular expressions (patterns), jumping - to start/end of block expression, etc, etc.</para> - </listitem> - - <listitem> - <para>Pull-down menus and online help.</para> - </listitem> - - <listitem> - <para>Language-dependent syntax highlighting and - indentation.</para> - </listitem> - - <listitem> - <para>Completely customisable.</para> - </listitem> - - <listitem> - <para>You can compile and debug programs within - Emacs.</para> - </listitem> - - <listitem> - <para>On a compilation error, you can jump to the offending - line of source code.</para> - </listitem> - - <listitem> - <para>Friendly-ish front-end to the <command>info</command> - program used for reading GNU hypertext documentation, - including the documentation on Emacs itself.</para> - </listitem> - - <listitem> - <para>Friendly front-end to <command>gdb</command>, allowing - you to look at the source code as you step through your - program.</para> - </listitem> - - <listitem> - <para>You can read Usenet news and mail while your program - is compiling.</para> - </listitem> - </itemizedlist> - - <para>And doubtless many more that I've overlooked.</para> - - <para>Emacs can be installed on FreeBSD using <ulink - URL="../../ports/editors.html">the Emacs - port</ulink>.</para> - - <para>Once it's installed, start it up and do <userinput>C-h - t</userinput> to read an Emacs tutorial—that means - hold down the <keycap>control</keycap> key, press - <keycap>h</keycap>, let go of the <keycap>control</keycap> - key, and then press <keycap>t</keycap>. (Alternatively, you - can you use the mouse to select <guimenuitem>Emacs - Tutorial</guimenuitem> from the <guimenu>Help</guimenu> - menu).</para> - - <para>Although Emacs does have menus, it's well worth learning - the key bindings, as it's much quicker when you're editing - something to press a couple of keys than to try and find the - mouse and then click on the right place. And, when you're - talking to seasoned Emacs users, you'll find they often - casually throw around expressions like <quote><literal>M-x - replace-s RET foo RET bar RET</literal></quote> so it's - useful to know what they mean. And in any case, Emacs has far - too many useful functions for them to all fit on the menu - bars.</para> - - <para>Fortunately, it's quite easy to pick up the key-bindings, - as they're displayed next to the menu item. My advice is to - use the menu item for, say, opening a file until you - understand how it works and feel confident with it, then try - doing C-x C-f. When you're happy with that, move on to - another menu command.</para> - - <para>If you can't remember what a particular combination of - keys does, select <guimenuitem>Describe Key</guimenuitem> from - the <guimenu>Help</guimenu> menu and type it in—Emacs - will tell you what it does. You can also use the - <guimenuitem>Command Apropos</guimenuitem> menu item to find - out all the commands which contain a particular word in them, - with the key binding next to it.</para> - - <para>By the way, the expression above means hold down the - <keysym>Meta</keysym> key, press <keysym>x</keysym>, release - the <keysym>Meta</keysym> key, type - <userinput>replace-s</userinput> (short for - <literal>replace-string</literal>—another feature of - Emacs is that you can abbreviate commands), press the - <keysym>return</keysym> key, type <userinput>foo</userinput> - (the string you want replaced), press the - <keysym>return</keysym> key, type bar (the string you want to - replace <literal>foo</literal> with) and press - <keysym>return</keysym> again. Emacs will then do the - search-and-replace operation you've just requested.</para> - - <para>If you're wondering what on earth the - <keysym>Meta</keysym> key is, it's a special key that many - Unix workstations have. Unfortunately, PC's don't have one, - so it's usually the <keycap>alt</keycap> key (or if you're - unlucky, the <keysym>escape</keysym> key).</para> - - <para>Oh, and to get out of Emacs, do <command>C-x C-c</command> - (that means hold down the <keysym>control</keysym> key, press - <keysym>x</keysym>, press <keysym>c</keysym> and release the - <keysym>control</keysym> key). If you have any unsaved files - open, Emacs will ask you if you want to save them. (Ignore - the bit in the documentation where it says - <command>C-z</command> is the usual way to leave - Emacs—that leaves Emacs hanging around in the - background, and is only really useful if you're on a system - which doesn't have virtual terminals).</para> - </sect2> - - <sect2> - <title>Configuring Emacs</title> - - <para>Emacs does many wonderful things; some of them are built - in, some of them need to be configured.</para> - - <para>Instead of using a proprietary macro language for - configuration, Emacs uses a version of Lisp specially adapted - for editors, known as Emacs Lisp. This can be quite useful if - you want to go on and learn something like Common Lisp, as - it's considerably smaller than Common Lisp (although still - quite big!).</para> - - <para>The best way to learn Emacs Lisp is to download the <ulink - URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs - Tutorial</ulink></para> - - <para>However, there's no need to actually know any Lisp to get - started with configuring Emacs, as I've included a sample - <filename>.emacs</filename> file, which should be enough to - get you started. Just copy it into your home directory and - restart Emacs if it's already running; it will read the - commands from the file and (hopefully) give you a useful basic - setup.</para> - </sect2> - - <sect2> - <title>A sample <filename>.emacs</filename> file</title> - - <para>Unfortunately, there's far too much here to explain it in - detail; however there are one or two points worth - mentioning.</para> - - <itemizedlist> - <listitem> - <para>Everything beginning with a <literal>;</literal> is a comment - and is ignored by Emacs.</para> - </listitem> - - <listitem> - <para>In the first line, the - <literal>-*- Emacs-Lisp -*-</literal> is so that - we can edit the <filename>.emacs</filename> file itself - within Emacs and get all the fancy features for editing - Emacs Lisp. Emacs usually tries to guess this based on - the filename, and may not get it right for - <filename>.emacs</filename>.</para> - </listitem> - - <listitem> - <para>The <keysym>tab</keysym> key is bound to an - indentation function in some modes, so when you press the - tab key, it will indent the current line of code. If you - want to put a <token>tab</token> character in whatever - you're writing, hold the <keysym>control</keysym> key down - while you're pressing the <keysym>tab</keysym> key.</para> - </listitem> - - <listitem> - <para>This file supports syntax highlighting for C, C++, - Perl, Lisp and Scheme, by guessing the language from the - filename.</para> - </listitem> - - <listitem> - <para>Emacs already has a pre-defined function called - <function>next-error</function>. In a compilation output - window, this allows you to move from one compilation error - to the next by doing <command>M-n</command>; we define a - complementary function, - <function>previous-error</function>, that allows you to go - to a previous error by doing <command>M-p</command>. The - nicest feature of all is that <command>C-c C-c</command> - will open up the source file in which the error occurred - and jump to the appropriate line.</para> - </listitem> - - <listitem> - <para>We enable Emacs's ability to act as a server, so that - if you're doing something outside Emacs and you want to - edit a file, you can just type in</para> - - <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput> - </screen> - - <para>and then you can edit the file in your - Emacs! - - <footnote> - <para>Many Emacs users set their <systemitem - class=environvar>EDITOR</systemitem> environment to - <literal>emacsclient</literal> so this happens every - time they need to edit a file.</para> - </footnote></para> - </listitem> - </itemizedlist> - - <example> - <title>A sample <filename>.emacs</filename> file</title> - - <programlisting>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - </programlisting> - </example> - </sect2> - - <sect2> - <title>Extending the Range of Languages Emacs Understands</title> - - <para>Now, this is all very well if you only want to program in - the languages already catered for in the - <filename>.emacs</filename> file (C, C++, Perl, Lisp and - Scheme), but what happens if a new language called - <quote>whizbang</quote> comes out, full of exciting - features?</para> - - <para>The first thing to do is find out if whizbang comes with - any files that tell Emacs about the language. These usually - end in <filename>.el</filename>, short for <quote>Emacs - Lisp</quote>. For example, if whizbang is a FreeBSD port, we - can locate these files by doing</para> - - <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput> - </screen> - - <para>and install them by copying them into the Emacs site Lisp - directory. On FreeBSD 2.1.0-RELEASE, this is - <filename>/usr/local/share/emacs/site-lisp</filename>.</para> - - <para>So for example, if the output from the find command - was</para> - - <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el - </screen> - - <para>we would do</para> - - <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput> - </screen> - - <para>Next, we need to decide what extension whizbang source - files have. Let's say for the sake of argument that they all - end in <filename>.wiz</filename>. We need to add an entry to - our <filename>.emacs</filename> file to make sure Emacs will - be able to use the information in - <filename>whizbang.el</filename>.</para> - - <para>Find the <symbol>auto-mode-alist entry</symbol> in - <filename>.emacs</filename> and add a line for whizbang, such - as:</para> - - <programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</> - </programlisting> - - <para>This means that Emacs will automatically go into - <function>whizbang-mode</function> when you edit a file ending - in <filename>.wiz</filename>.</para> - - <para>Just below this, you'll find the - <symbol>font-lock-auto-mode-list</symbol> entry. Add - <function>whizbang-mode</function> to it like so:</para> - - <programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - </programlisting> - - <para>This means that Emacs will always enable - <function>font-lock-mode</function> (ie syntax highlighting) - when editing a <filename>.wiz</filename> file.</para> - - <para>And that's all that's needed. If there's anything else - you want done automatically when you open up a - <filename>.wiz</filename> file, you can add a - <function>whizbang-mode hook</function> (see - <function>my-scheme-mode-hook</function> for a simple example - that adds <function>auto-indent</function>).</para> - </sect2> - </sect1> - - <sect1> - <title>Further Reading</title> - - <itemizedlist> - <listitem> - <para>Brian Harvey and Matthew Wright - <emphasis>Simply Scheme</emphasis> - MIT 1994.<!-- <br> --> - ISBN 0-262-08226-8</para> - </listitem> - - <listitem> - <para>Randall Schwartz - <emphasis>Learning Perl</emphasis> - O'Reilly 1993<!-- <br> --> - ISBN 1-56592-042-2</para> - </listitem> - - <listitem> - <para>Patrick Henry Winston and Berthold Klaus Paul Horn - <emphasis>Lisp (3rd Edition)</emphasis> - Addison-Wesley 1989<!-- <br> --> - ISBN 0-201-08319-1</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Rob Pike - <emphasis>The Unix Programming Environment</emphasis> - Prentice-Hall 1984<!-- <br> --> - ISBN 0-13-937681-X</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Dennis M. Ritchie - <emphasis>The C Programming Language (2nd Edition)</emphasis> - Prentice-Hall 1988<!-- <br> --> - ISBN 0-13-110362-8</para> - </listitem> - - <listitem> - <para>Bjarne Stroustrup - <emphasis>The C++ Programming Language</emphasis> - Addison-Wesley 1991<!-- <br> --> - ISBN 0-201-53992-6</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Advanced Programming in the Unix Environment</emphasis> - Addison-Wesley 1992<!-- <br> --> - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Unix Network Programming</emphasis> - Prentice-Hall 1990<!-- <br> --> - ISBN 0-13-949876-1</para> - </listitem> - </itemizedlist> - </sect1> - - </chapter> - - <chapter id="secure-programming"> - <title>Secure Programming</title> - - <para>This chapter was written by Murray Stokely.</para> - - <sect1><title>Synopsis</title> - - <para>This chapter describes some of the security issues that - have plagued Unix programmers for decades and some of the new - tools available to help programmers avoid writing exploitable - code.</para> - </sect1> - - <sect1 id="secure-philosophy"><title>Secure Design - Methodology</title> - - <para>Writing secure applications takes a very scrutinous and - pessimistic outlook on life. Applications should be run with - the principle of <quote>least privilege</quote> so that no - process is ever running than more with the bare minimum access - that it needs to accomplish its function. Previously tested - code should be reused whenever possible to avoid common - mistakes that others may have already fixed.</para> - - <para>One of the pitfalls of the Unix environment is how easy it - is to make assumptions about the sanity of the environment. - Applications should never trust user input (in all its forms), - system resources, inter-process communication, or the timing of - events. Unix processes do not execute synchronously so logical - operations are rarely atomic.</para> - </sect1> - - <sect1><title>Buffer Overflows</title> - - <para>Buffer Overflows have been around since the very - beginnings of the Von-Neuman <xref linkend="COD"> architecture. - They first gained widespread notoriety in 1988 with the Moorse - Internet worm. Unfortunately, the same basic attack remains - effective today. Of the 17 CERT security advisories of 1999, 10 - of them were directly caused by buffer-overflow software bugs. - By far the most common type of buffer overflow attack is based - on corrupting the stack.</para> - - <para>Most modern computer systems use a stack to pass arguments - to procedures and to store local variables. A stack is a last - in first out (LIFO) buffer in the high memory area of a process - image. When a program invokes a function a new "stack frame" is - created. This stack frame consists of the arguments passed to - the function as well as a dynamic amount of local variable - space. The "stack pointer" is a register that holds the current - location of the top of the stack. Since this value is - constantly changing as new values are pushed onto the top of the - stack, many implementations also provide a "frame pointer" that - is located near the beginning of a stack frame so that local - variables can more easily be addressed relative to this - value. <xref linkend="COD"> The return address for function - calls is also stored on the stack, and this is the cause of - stack-overflow exploits since overflowing a local variable in a - function can overwrite the return address of that function, - potentially allowing a malicious user to execute any code he or - she wants.</para> - - <para>Although stack-based attacks are by far the most common, - it would also be possible to overrun the stack with a heap-based - (malloc/free) attack.</para> - - <para>The C programming language does not perform automatic - bounds checking on arrays or pointers as many other languages - do. In addition, the standard C library is filled with a - handful of very dangerous functions.</para> - - <informaltable> - <tgroup cols=2> - <tbody> - <row><entry><function>strcpy</function>(char *dest, const char - *src)</entry> - <entry><simpara>May overflow the dest buffer</simpara></entry> - </row> - - <row><entry><function>strcat</function>(char *dest, const char - *src)</entry> - <entry><simpara>May overflow the dest buffer</simpara></entry> - </row> - - <row><entry><function>getwd</function>(char *buf)</entry> - <entry><simpara>May overflow the buf buffer</simpara></entry> - </row> - - <row><entry><function>gets</function>(char *s)</entry> - <entry><simpara>May overflow the s buffer</simpara></entry> - </row> - - <row><entry><function>[vf]scanf</function>(const char *format, - ...)</entry> - <entry><simpara>May overflow its arguments.</simpara></entry> - </row> - - <row><entry><function>realpath</function>(char *path, char - resolved_path[])</entry> - <entry><simpara>May overflow the path buffer</simpara></entry> - </row> - - <row><entry><function>[v]sprintf</function>(char *str, const char - *format, ...)</entry> - <entry><simpara>May overflow the str buffer.</simpara></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <sect2><title>Example Buffer Overflow</title> - - <para>The following example code contains a buffer overflow - designed to overwrite the return address and skip the - instruction immediately following the function call. (Inspired - by <xref linkend="Phrack">)</para> - -<programlisting> -#include <sgmltag>stdio.h</sgmltag> - -void manipulate(char *buffer) { - char newbuffer[80]; - strcpy(newbuffer,buffer); -} - -int main() { - char ch,buffer[4096]; - int i=0; - - while ((buffer[i++] = getchar()) != '\n') {}; - - i=1; - manipulate(buffer); - i=2; - printf("The value of i is : %d\n",i); - return 0; -} -</programlisting> - - <para>Let us examine what the memory image of this process would - look like if we were to input 160 spaces into our little program - before hitting return.</para> - - <para>[XXX figure here!]</para> - - <para>Obviously more malicious input can be devised to execute - actual compiled instructions (such as exec(/bin/sh)).</para> - </sect2> - - <sect2><title>Avoiding Buffer Overflows</title> - - <para>The most straightforward solution to the problem of - stack-overflows is to always use length restricted memory and - string copy functions. <function>strncpy</function> and - <function>strncat</function> are part of the standard C library. - These functions accept a length value as a parameter which - should be no larger than the size of the destination buffer. - These functions will then copy up to `length' bytes from the - source to the destination. However there are a number of - problems with these functions. Neither function guarantees NUL - termination if the size of the input buffer is as large as the - destination. The length parameter is also used inconsistently - between strncpy and strncat so it is easy for programmers to get - confused as to their proper usage. There is also a significant - performance loss compared to <function>strcpy</function> when - copying a short string into a large buffer since - <function>strncpy</function> NUL fills up the the size - specified.</para> - - <para>In OpenBSD, another memory copy implementation has been - created to get around these problem. The - <function>strlcpy</function> and <function>strlcat</function> - functions guarantee that they will always null terminate the - destination string when given a non-zero length argument. For - more information about these functions see <xref - linkend="OpenBSD">. The OpenBSD <function>strlcpy</function> and - <function>strlcat</function> instructions have been in FreeBSD - since 3.5.</para> - - <sect3><title>Compiler based run-time bounds checking</title> - - <para>Unfortunately there is still a very large assortment of - code in public use which blindly copies memory around without - using any of the bounded copy routines we just discussed. - Fortunately, there is another solution. Several compiler - add-ons and libraries exist to do Run-time bounds checking in - C/C++.</para> - - <para>StackGuard is one such add-on that is implemented as a - small patch to the gcc code generator. From the StackGuard - website, http://immunix.org/stackguard.html : - <blockquote><para>"StackGuard detects and defeats stack - smashing attacks by protecting the return address on the stack - from being altered. StackGuard places a "canary" word next to - the return address when a function is called. If the canary - word has been altered when the function returns, then a stack - smashing attack has been attempted, and the program responds - by emitting an intruder alert into syslog, and then - halts."</para></blockquote> - - <blockquote><para>"StackGuard is implemented as a small patch - to the gcc code generator, specifically the function_prolog() - and function_epilog() routines. function_prolog() has been - enhanced to lay down canaries on the stack when functions - start, and function_epilog() checks canary integrity when the - function exits. Any attempt at corrupting the return address - is thus detected before the function - returns."</para></blockquote> - </para> - - <para>Recompiling your application with StackGuard is an - effective means of stopping most buffer-overflow attacks, but - it can still be compromised.</para> - - </sect3> - - <sect3><title>Library based run-time bounds checking</title> - - <para>Compiler-based mechanisms are completely useless for - binary-only software for which you cannot recompile. For - these situations there are a number of libraries which - re-implement the unsafe functions of the C-library - (<function>strcpy</function>, <function>fscanf</function>, - <function>getwd</function>, etc..) and ensure that these - functions can never write past the stack pointer.</para> - - <itemizedlist> - <listitem><simpara>libsafe</simpara></listitem> - <listitem><simpara>libverify</simpara></listitem> - <listitem><simpara>libparnoia</simpara></listitem> - </itemizedlist> - - <para>Unfortunately these library-based defenses have a number - of shortcomings. These libraries only protect against a very - small set of security related issues and they neglect to fix - the actual problem. These defenses may fail if the - application was compiled with -fomit-frame-pointer. Also, the - LD_PRELOAD and LD_LIBRARY_PATH environment variables can be - overwritten/unset by the user.</para> - </sect3> - - </sect2> - </sect1> - - <sect1><title>SetUID issues</title> - - <para>There are at least 6 different IDs associated with any - given process. Because of this you have to be very careful with - the access that your process has at any given time. In - particular, all seteuid applications should give up their - privileges as soon as it is no longer required.</para> - - <para>The real user ID can only be changed by a superuser - process. The <application>login</application> program sets this - when a user initially logs in and it is seldom changed.</para> - - <para>The effective user ID is set by the - <function>exec()</function> functions if a program has its - seteuid bit set. An application can call - <function>seteuid()</function> at any time to set the effective - user ID to either the real user ID or the saved set-user-ID. - When the effective user ID is set by <function>exec()</function> - functions, the previous value is saved in the saved set-user-ID.</para> - - </sect1> - - <sect1 id="chroot"><title>Limiting your program's environment</title> - - <para>The traditional method of restricting access to a process - is with the <function>chroot()</function> system call. This - system call changes the root directory from which all other - paths are referenced for a process and any child processes. For - this call to succeed the process must have execute (search) - permission on the directory being referenced. The new - environment does not actually take affect until you - <function>chdir()</function> into your new environment. It - should also be noted that a process can easily break out of a - chroot environment if it has root privilege. This could be - accomplished by creating device nodes to read kernel memory, - attaching a debugger to a process outside of the jail, or in - many other creative ways.</para> - - <para>The behavior of the <function>chroot()</function> system - call can be controlled somewhat with the - kern.chroot_allow_open_directories <command>sysctl</command> - variable. When this value is set to 0, - <function>chroot()</function> will fail with EPERM if there are - any directories open. If set to the default value of 1, then - <function>chroot()</function> will fail with EPERM if there are - any directories open and the process is already subject to a - <function>chroot()</function> call. For any other value, the - check for open directories will be bypassed completely.</para> - - <sect2><title>FreeBSD's jail functionality</title> - - <para>The concept of a Jail extends upon the - <function>chroot()</function> by limiting the powers of the - superuser to create a true `virtual server'. Once a prison is - setup all network communication must take place through the - specified IP address, and the power of "root privilege" in this - jail is severely constrained.</para> - - <para>While in a prison, any tests of superuser power within the - kernel using the <function>suser()</function> call will fail. - However, some calls to <function>suser()</function> have been - changed to a new interface <function>suser_xxx()</function>. - This function is responsible for recognizing or denying access - to superuser power for imprisoned processes.</para> - - <para>A superuser process within a jailed environment has the - power to : </para> - <itemizedlist> - <listitem><simpara>Manipulate credential with - <function>setuid</function>, <function>seteuid</function>, - <function>setgid</function>, <function>setegid</function>, - <function>setgroups</function>, <function>setreuid</function>, - <function>setregid</function>, <function>setlogin</function></simpara></listitem> - <listitem><simpara>Set resource limits with <function>setrlimit</function></simpara></listitem> - <listitem><simpara>Modify some sysctl nodes - (kern.hostname)</simpara></listitem> - <listitem><simpara><function>chroot()</function></simpara></listitem> - <listitem><simpara>Set flags on a vnode: - <function>chflags</function>, - <function>fchflags</function></simpara></listitem> - <listitem><simpara>Set attributes of a vnode such as file - permission, owner, group, size, access time, and modification - time.</simpara></listitem> - <listitem><simpara>Bind to privileged ports in the Internet - domain (ports < 1024)</simpara></listitem> - </itemizedlist> - - <para><function>Jail</function> is a very useful tool for - running applications in a secure environment but it does have - some shortcomings. Currently, the IPC mechanisms have not been - converted to the <function>suser_xxx</function> so applications - such as MySQL can not be run within a jail. Superuser access - may have a very limited meaning within a jail, but there is - no way to specify exactly what "very limited" means.</para> - </sect2> - - <sect2><title>POSIX.1e Process Capabilities</title> - - <para>Posix has released a working draft that adds event - auditing, access control lists, fine grained privileges, - information labeling, and mandatory access control.</para> - <para>This is a work in progress and is the focus of the <ulink - url="http://www.trustedbsd.org">TrustedBSD</ulink> project. Some - of the initial work has been committed to FreeBSD-current - (cap_set_proc(3)).</para> - - </sect2> - - </sect1> - - <sect1><title>Trust</title> - - <para>An application should never assume that anything about the - users environment is sane. This includes (but is certainly not - limited to) : user input, signals, environment variables, - resources, IPC, mmaps, the file system working directory, file - descriptors, the # of open files, etc.</para> - - <para>You should never assume that you can catch all forms of - invalid input that a user might supply. Instead, your - application should use positive filtering to only allow a - specific subset of inputs that you deem safe. Improper data - validation has been the cause of many exploits, especially with - CGI scripts on the world wide web. For filenames you need to be - extra careful about paths ("../", "/"), symbolic links, and - shell escape characters.</para> - - <para>Perl has a really cool feature called "Taint" mode which - can be used to prevent scripts for using data derived outside - the program in an unsafe way. This mode will check command line - arguments, environment variables, locale information, the - results of certain syscalls (<function>readdir()</function>, - <function>readlink()</function>, - <function>getpwxxx()</function>, and all file input.</para> - - </sect1> - - <sect1><title>Race Conditions</title> - - <para>A race condition is anomalous behavior caused by the - unexpected dependence on the relative timing of events. In - other words, a programmer incorrectly assumed that a particular - event would always happen before another.</para> - - <para>Some of the common causes of race conditions are signals, - access checks, and file opens. Signals are asynchronous events - by nature so special care must be taken in dealing with them. - Checking access with <function>access(2)</function> then - <function>open(2)</function> is clearly non-atomic. Users can - move files in between the two calls. Instead, privileged - applications should <function>seteuid()</function> and then call - <function>open()</function> directly. Along the same lines, an - application should always set a proper umask before - <function>open()</function> to obviate the need for spurious - <function>chmod()</function> calls.</para> - - </sect1> - - </chapter> - </part> - - <part id="kernel"> - <title>Kernel</title> - - <chapter id="kernelhistory"> - <title>History of the Unix Kernel</title> - - <para>Some history of the Unix/BSD kernel, system calls, how do - processes work, blocking, scheduling, threads (kernel), - context switching, signals, interrupts, modules, etc.</para> - - <para></para> - </chapter> - </part> - - <part id="memory"> - <title>Memory and Virtual Memory</title> - - <chapter id="virtualmemory"> - <title>Virtual Memory</title> - - <para>VM, paging, swapping, allocating memory, testing for - memory leaks, mmap, vnodes, etc.</para> - - <para></para> - </chapter> - </part> - - <part id="iosystem"> - <title>I/O System</title> - - <chapter id="ufs"> - <title>UFS</title> - - <para>UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, - locking, metadata, soft-updates, LFS, portalfs, procfs, - vnodes, memory sharing, memory objects, TLBs, caching</para> - - </chapter> - </part> - - <part id="ipc"> - <title>Interprocess Communication</title> - - <chapter id="signals"> - <title>Signals</title> - - <para>Signals, pipes, semaphores, message queues, shared memory, - ports, sockets, doors</para> - - </chapter> - </part> - - <part id="networking"> - <title>Networking</title> - - <chapter id="sockets"> - <title>Sockets</title> - - <para>Sockets, bpf, IP, TCP, UDP, ICMP, OSI, bridging, - firewalling, NAT, switching, etc</para> - - </chapter> - </part> - - <part id="networkfs"> - <title>Network Filesystems</title> - - <chapter id="afs"> - <title>AFS</title> - - <para>AFS, NFS, SANs etc]</para> - - </chapter> - </part> - - <part id="terminal"> - <title>Terminal Handling</title> - - <chapter id="syscons"> - <title>Syscons</title> - - <para>Syscons, tty, PCVT, serial console, screen savers, - etc</para> - - </chapter> - </part> - - <part id="sound"> - <title>Sound</title> - - <chapter id="oss"> - <title>OSS</title> - - <para>OSS, waveforms, etc</para> - - </chapter> - </part> - - <part id="devicedrivers"> - <title>Device Drivers</title> - - <chapter id="driverbasics"> - <title>Writing FreeBSD Device Drivers</title> - - <para>This chapter was written by Murray Stokely with selections from - a variety of sources including the intro(4) man page by Joerg - Wunsch.</para> - - <sect1> - <title>Introduction</title> - <para> - This chapter provides a brief introduction to writing device - drivers for FreeBSD. A device in this context is a term used - mostly for hardware-related stuff that belongs to the system, - like disks, printers, or a graphics display with its keyboard. - A device driver is the software component of the operating - system that controls a specific device. There are also - so-called pseudo-devices where a device driver emulates the - behaviour of a device in software without any particular - underlying hardware. Device drivers can be compiled into the - system statically or loaded on demand through the dynamic - kernel linker facility `kld'.</para> - - <para>Most devices in a Unix-like operating system are - accessed through device-nodes, sometimes also called special - files. These files are usually located under the directory - <filename>/dev</filename> in the file system hierarchy. Until - devfs is fully integrated into FreeBSD, each device node must - be created statically and independent of the existence of the - associated device driver. Most device nodes on the system are - created by running <command>MAKEDEV</command>.</para> - - <para>Device drivers can roughly be broken down into three - categories; character (unbuffered), block (buffered), and - network drivers.</para> - </sect1> - - <sect1> - <title>Dynamic Kernel Linker Facility - KLD</title> - <para>The kld interface allows system administrators to - dynamically add and remove functionality from a running - system. This allows device driver writers to load their new - changes into a running kernel without constantly rebooting to - test changes.</para> - - <para>The kld interface is used through the following - administrator commands : - <itemizedlist> - <listitem><simpara><command>kldload</command> - loads a new kernel - module</simpara></listitem> - <listitem><simpara><command>kldunload</command> - unloads a kernel - module</simpara></listitem> - <listitem><simpara><command>kldstat</command> - lists the currently loadded - modules</simpara></listitem> - </itemizedlist> - </para> - - <para>Skeleton Layout of a kernel module</para> -<programlisting> -/* - * KLD Skeleton - * Inspired by Andrew Reiter's Daemonnews article - */ - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ - -/* - * Load handler that deals with the loading and unloading of a KLD. - */ - -static int -skel_loader(struct module *m, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - uprintf("Skeleton KLD loaded.\n"); - break; - case MOD_UNLOAD: - uprintf("Skeleton KLD unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -/* Declare this module to the rest of the kernel */ - -DECLARE_MODULE(skeleton, skel_loader, SI_SUB_KLD, SI_ORDER_ANY); -</programlisting> - - - <sect2> - <title>Makefile</title> - <para>FreeBSD provides a makefile include that you can use - to quickly compile your kernel addition.</para> - <programlisting> -SRCS=skeleton.c -KMOD=skeleton - -.include <bsd.kmod.mk> -</programlisting> - - - <para>Simply running <command>make</command> with - this makefile will create a file - <filename>skeleton.ko</filename> that can be loaded into - your system by typing : -<screen> -&prompt.root kldload -v ./skeleton.ko -</screen> - </para> - </sect2> - </sect1> - - <sect1> - <title>Accessing a device driver</title> - <para>Unix provides a common set of system calls for user - applications to use. The upper layers of the kernel dispatch - these calls to the corresponding device driver when a user - accesses a device node. The <command>/dev/MAKEDEV</command> - script makes most of the device nodes for your system but if - you are doing your own driver development it may be necessary - to create your own device nodes with <command>mknod</command> - </para> - - <sect2> - <title>Creating static device nodes</title> - <para>The <command>mknod</command> command requires four - arguments to create a device node. You must specify the - name of this device node, the type of device, the major number - of the device, and the minor number of the device.</para> - </sect2> - - <sect2> - <title>Dynamic device nodes</title> - <para>The device filesystem, or devfs, provides access to the - kernel's device namespace in the global filesystem namespace. - This eliminates the problems of potentially having a device - driver without a static device node, or a device node without - an installed device driver. Unfortunately, devfs is still a - work in progress.</para> - </sect2> - - </sect1> - - <sect1> - <title>Character Devices</title> - <para>A character device driver is one that transfers data - directly to and from a user process. This is the most common - type of device driver and there are plenty of simple examples - in the source tree.</para> - <para>This simple example pseudo-device remembers whatever values you write - to it and can then supply them back to you when you read from - it.</para> -<programlisting> -/* - * Simple `echo' pseudo-device KLD - * - * Murray Stokely - */ - -#define MIN(a,b) (((a) < (b)) ? (a) : (b)) - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ -#include <sys/conf.h> /* cdevsw struct */ -#include <sys/uio.h> /* uio struct */ -#include <sys/malloc.h> - -#define BUFFERSIZE 256 - -/* Function prototypes */ -d_open_t echo_open; -d_close_t echo_close; -d_read_t echo_read; -d_write_t echo_write; - -/* Character device entry points */ -static struct cdevsw echo_cdevsw = { - echo_open, - echo_close, - echo_read, - echo_write, - noioctl, - nopoll, - nommap, - nostrategy, - "echo", - 33, /* reserved for lkms - /usr/src/sys/conf/majors */ - nodump, - nopsize, - D_TTY, - -1 -}; - -typedef struct s_echo { - char msg[BUFFERSIZE]; - int len; -} t_echo; - -/* vars */ -static dev_t sdev; -static int len; -static int count; -static t_echo *echomsg; - -MALLOC_DECLARE(M_ECHOBUF); -MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module"); - -/* - * This function acts is called by the kld[un]load(2) system calls to - * determine what actions to take when a module is loaded or unloaded. - */ - -static int -echo_loader(struct module *m, int what, void *arg) -{ - int err = 0; - - switch (what) { - case MOD_LOAD: /* kldload */ - sdev = make_dev(<literal>&</literal>echo_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "echo"); - /* kmalloc memory for use by this driver */ - /* malloc(256,M_ECHOBUF,M_WAITOK); */ - MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK); - printf("Echo device loaded.\n"); - break; - case MOD_UNLOAD: - destroy_dev(sdev); - FREE(echomsg,M_ECHOBUF); - printf("Echo device unloaded.\n"); - break; - default: - err = EINVAL; - break; - } - return(err); -} - -int -echo_open(dev_t dev, int oflags, int devtype, struct proc *p) -{ - int err = 0; - - uprintf("Opened device \"echo\" successfully.\n"); - return(err); -} - -int -echo_close(dev_t dev, int fflag, int devtype, struct proc *p) -{ - uprintf("Closing device \"echo.\"\n"); - return(0); -} - -/* - * The read function just takes the buf that was saved via - * echo_write() and returns it to userland for accessing. - * uio(9) - */ - -int -echo_read(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - int amt; - - /* How big is this read operation? Either as big as the user wants, - or as big as the remaining data */ - amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0); - if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) { - uprintf("uiomove failed!\n"); - } - - return err; -} - -/* - * echo_write takes in a character string and saves it - * to buf for later accessing. - */ - -int -echo_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - /* Copy the string in from user memory to kernel memory */ - err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE)); - - /* Now we need to null terminate */ - *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0; - /* Record the length */ - echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE); - - if (err != 0) { - uprintf("Write failed: bad address!\n"); - } - - count++; - return(err); -} - -DEV_MODULE(echo,echo_loader,NULL); -</programlisting> - -<para>To install this driver you will first need to make a node on - your filesystem with a command such as : </para> -<screen> - &prompt.root mknod /dev/echo c 33 0 -</screen> -<para>With this driver loaded you should now be able to type something - like :</para> -<screen> - &prompt.root echo -n "Test Data" > /dev/echo - &prompt.root cat /dev/echo - Test Data -</screen> - <para>Real hardware devices in the next chapter..</para> - - <para>Additional Resources - <itemizedlist> - <listitem><simpara><ulink - url="http://www.daemonnews.org/200010/blueprints.html">Dynamic - Kernel Linker (KLD) Facility Programming Tutorial</ulink> - - <ulink url="http://www.daemonnews.org">Daemonnews</ulink> October 2000</simpara></listitem> - <listitem><simpara><ulink - url="http://www.daemonnews.org/200007/newbus-intro.html">How - to Write Kernel Drivers with NEWBUS</ulink> - <ulink - url="http://www.daemonnews.org">Daemonnews</ulink> July - 2000</simpara></listitem> - </itemizedlist> - </para> - </sect1> - - <sect1> - <title>Block Devices</title> - <para>A block device driver transfers data to and from the - operating system's buffer cache. They are solely intended to - layer a file system on top of them. For this reason they are - normally implemented for disks and disk-like devices only.</para> - - <para>Example test data generator ... </para> - - <para>Example ramdisk device ... </para> - - <para>Real hardware devices in the next chapter..</para> - </sect1> - - <sect1> - <title>Network Drivers</title> - <para>Drivers for network devices do not use device nodes in - ord to be accessed. Their selection is based on other - decisions made inside the kernel and instead of calling - open(), use of a network device is generally introduced by - using the system call socket(2).</para> - <para>man ifnet(), loopback device, Bill Pauls drivers, etc..</para> - </sect1> - - </chapter> - - <chapter id="pci"> - <title>PCI Devices</title> - - <para>This chapter will talk about the FreeBSD mechanisms for - writing a device driver for a device on a PCI bus.</para> - - <sect1><title>Probe and Attach</title> - - <para>Information here about how the PCI bus code iterates - through the unattached devices and see if a newly loaded kld - will attach to any of them.</para> -<programlisting> -/* - * Simple KLD to play with the PCI functions. - * - * Murray Stokely - */ - -#define MIN(a,b) (((a) < (b)) ? (a) : (b)) - -#include <sys/types.h> -#include <sys/module.h> -#include <sys/systm.h> /* uprintf */ -#include <sys/errno.h> -#include <sys/param.h> /* defines used in kernel.h */ -#include <sys/kernel.h> /* types used in module initialization */ -#include <sys/conf.h> /* cdevsw struct */ -#include <sys/uio.h> /* uio struct */ -#include <sys/malloc.h> -#include <sys/bus.h> /* structs, prototypes for pci bus stuff */ - -#include <pci/pcivar.h> /* For get_pci macros! */ - -/* Function prototypes */ -d_open_t mypci_open; -d_close_t mypci_close; -d_read_t mypci_read; -d_write_t mypci_write; - -/* Character device entry points */ - -static struct cdevsw mypci_cdevsw = { - mypci_open, - mypci_close, - mypci_read, - mypci_write, - noioctl, - nopoll, - nommap, - nostrategy, - "mypci", - 36, /* reserved for lkms - /usr/src/sys/conf/majors */ - nodump, - nopsize, - D_TTY, - -1 -}; - -/* vars */ -static dev_t sdev; - -/* We're more interested in probe/attach than with - open/close/read/write at this point */ - -int -mypci_open(dev_t dev, int oflags, int devtype, struct proc *p) -{ - int err = 0; - - uprintf("Opened device \"mypci\" successfully.\n"); - return(err); -} - -int -mypci_close(dev_t dev, int fflag, int devtype, struct proc *p) -{ - int err=0; - - uprintf("Closing device \"mypci.\"\n"); - return(err); -} - -int -mypci_read(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - uprintf("mypci read!\n"); - return err; -} - -int -mypci_write(dev_t dev, struct uio *uio, int ioflag) -{ - int err = 0; - - uprintf("mypci write!\n"); - return(err); -} - -/* PCI Support Functions */ - -/* - * Return identification string if this is device is ours. - */ -static int -mypci_probe(device_t dev) -{ - uprintf("MyPCI Probe\n" - "Vendor ID : 0x%x\n" - "Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev)); - - if (pci_get_vendor(dev) == 0x11c1) { - uprintf("We've got the Winmodem, probe successful!\n"); - return 0; - } - - return ENXIO; -} - -/* Attach function is only called if the probe is successful */ - -static int -mypci_attach(device_t dev) -{ - uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev)); - sdev = make_dev(<literal>&</literal>mypci_cdevsw, - 0, - UID_ROOT, - GID_WHEEL, - 0600, - "mypci"); - uprintf("Mypci device loaded.\n"); - return ENXIO; -} - -/* Detach device. */ - -static int -mypci_detach(device_t dev) -{ - uprintf("Mypci detach!\n"); - return 0; -} - -/* Called during system shutdown after sync. */ - -static int -mypci_shutdown(device_t dev) -{ - uprintf("Mypci shutdown!\n"); - return 0; -} - -/* - * Device suspend routine. - */ -static int -mypci_suspend(device_t dev) -{ - uprintf("Mypci suspend!\n"); - return 0; -} - -/* - * Device resume routine. - */ - -static int -mypci_resume(device_t dev) -{ - uprintf("Mypci resume!\n"); - return 0; -} - -static device_method_t mypci_methods[] = { - /* Device interface */ - DEVMETHOD(device_probe, mypci_probe), - DEVMETHOD(device_attach, mypci_attach), - DEVMETHOD(device_detach, mypci_detach), - DEVMETHOD(device_shutdown, mypci_shutdown), - DEVMETHOD(device_suspend, mypci_suspend), - DEVMETHOD(device_resume, mypci_resume), - - { 0, 0 } -}; - -static driver_t mypci_driver = { - "mypci", - mypci_methods, - 0, - /* sizeof(struct mypci_softc), */ -}; - -static devclass_t mypci_devclass; - -DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0); -</programlisting> - - <para>Additional Resources - <itemizedlist> - <listitem><simpara><ulink - url="http://www.pcisig.org">PCI Special Interest - Group</ulink></simpara></listitem> - <listitem><simpara>PCI System Architecture, Fourth Edition by - Tom Shanley, et al.</simpara></listitem> - </itemizedlist> - </para> - </sect1> - </chapter> - - <chapter id="usb"> - <title>USB Devices</title> - - <para>This chapter will talk about the FreeBSD mechanisms for - writing a device driver for a device on a USB bus.</para> - </chapter> - - <chapter id="newbus"> - <title>NewBus</title> - - <para>This chapter will talk about the FreeBSD NewBus - architecture.</para> - </chapter> - - </part> - - <part id="architectures"> - <title>Architectures</title> - - <chapter id="ia32"> - <title>IA-32</title> - - <para>Talk about the architectural specifics of FreeBSD/x86.</para> - - </chapter> - - <chapter id="alpha"> - <title>Alpha</title> - - <para>Talk about the architectural specifics of - FreeBSD/alpha.</para> - - <para>Explanation of allignment errors, how to fix, how to - ignore.</para> - - <para>Example assembly language code for FreeBSD/alpha.</para> - </chapter> - - <chapter id="ia64"> - <title>IA-64</title> - - <para>Talk about the architectural specifics of - FreeBSD/ia64.</para> - - </chapter> - </part> - - <part id="debuggingpart"> - <title>Debugging</title> - - <chapter id="truss"> - <title>Truss</title> - - <para>various descriptions on how to debug certain aspects of - the system using truss, ktrace, gdb, kgdb, etc</para> - - </chapter> - </part> - - <part id="compatibility"> - <title>Compatibility Layers</title> - - <chapter id="linux"> - <title>Linux</title> - - <para>Linux, SVR4, etc</para> - - </chapter> - </part> - - <part id="appendices"> - <title>Appendices</title> - - <bibliography> - - <biblioentry id="COD" xreflabel="1"> - <authorgroup> - <author> - <firstname>Dave</firstname> - <othername role="MI">A</othername> - <surname>Patterson</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">L</othername> - <surname>Hennessy</surname> - </author> - </authorgroup> - <copyright><year>1998</year><holder>Morgan Kaufmann Publishers, - Inc.</holder></copyright> - <isbn>1-55860-428-6</isbn> - <publisher> - <publishername>Morgan Kaufmann Publishers, Inc.</publishername> - </publisher> - <title>Computer Organization and Design</title> - <subtitle>The Hardware / Software Interface</subtitle> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry xreflabel="2"> - <authorgroup> - <author> - <firstname>W.</firstname> - <othername role="Middle">Richard</othername> - <surname>Stevens</surname> - </author> - </authorgroup> - <copyright><year>1993</year><holder>Addison Wesley Longman, - Inc.</holder></copyright> - <isbn>0-201-56317-7</isbn> - <publisher> - <publishername>Addison Wesley Longman, Inc.</publishername> - </publisher> - <title>Advanced Programming in the Unix Environment</title> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry xreflabel="3"> - <authorgroup> - <author> - <firstname>Marshall</firstname> - <othername role="Middle">Kirk</othername> - <surname>McKusick</surname> - </author> - <author> - <firstname>Keith</firstname> - <surname>Bostic</surname> - </author> - <author> - <firstname>Michael</firstname> - <othername role="MI">J</othername> - <surname>Karels</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">S</othername> - <surname>Quarterman</surname> - </author> - </authorgroup> - <copyright><year>1996</year><holder>Addison-Wesley Publishing Company, - Inc.</holder></copyright> - <isbn>0-201-54979-4</isbn> - <publisher> - <publishername>Addison-Wesley Publishing Company, Inc.</publishername> - </publisher> - <title>The Design and Implementation of the 4.4 BSD Operating System</title> - <pagenums>1-2</pagenums> - </biblioentry> - - <biblioentry id="Phrack" xreflabel="4"> - <authorgroup> - <author> - <firstname>Aleph</firstname> - <surname>One</surname> - </author> - </authorgroup> - <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title> - </biblioentry> - - <biblioentry id="StackGuard" xreflabel="5"> - <authorgroup> - <author> - <firstname>Chrispin</firstname> - <surname>Cowan</surname> - </author> - <author> - <firstname>Calton</firstname> - <surname>Pu</surname> - </author> - <author> - <firstname>Dave</firstname> - <surname>Maier</surname> - </author> - </authorgroup> - <title>StackGuard; Automatic Adaptive Detection and Prevention of - Buffer-Overflow Attacks</title> - </biblioentry> - - <biblioentry id="OpenBSD" xreflabel="6"> - <authorgroup> - <author> - <firstname>Todd</firstname> - <surname>Miller</surname> - </author> - <author> - <firstname>Theo</firstname> - <surname>de Raadt</surname> - </author> - </authorgroup> - <title>strlcpy and strlcat -- consistent, safe string copy and - concatenation.</title> - </biblioentry> - - </bibliography> - - </part> - -</book> diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml deleted file mode 100644 index 40919d77d3..0000000000 --- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml +++ /dev/null @@ -1,647 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml,v 1.27 2000/11/15 12:40:05 des Exp $ ---> - -<chapter id="kerneldebug"> - <title>Kernel Debugging</title> - - <para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para> - - <sect1> - <title>Debugging a Kernel Crash Dump with <command>gdb</command></title> - - <para>Here are some instructions for getting kernel debugging working on a - crash dump. They assume that you have enough swap space for a crash - dump. If you have multiple swap partitions and the first one is too - small to hold the dump, you can configure your kernel to use an - alternate dump device (in the <literal>config kernel</literal> line), or - you can specify an alternate using the - &man.dumpon.8; command. The best way to use &man.dumpon.8; is to set - the <literal>dumpdev</literal> variable in - <filename>/etc/rc.conf</filename>. Typically you want to specify one of - the swap devices specified in <filename>/etc/fstab</filename>. Dumps to - non-swap devices, tapes for example, are currently not supported. Config - your kernel using <command>config <option>-g</option></command>. See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <para>Use the &man.dumpon.8; command to tell the kernel where to dump to - (note that this will have to be done after configuring the partition in - question as swap space via &man.swapon.8;). This is normally arranged - via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>. - Alternatively, you can hard-code the dump device via the - <literal>dump</literal> clause in the <literal>config</literal> line of - your kernel config file. This is deprecated and should be used only if - you want a crash dump from a kernel that crashes during booting.</para> - - <note> - <para>In the following, the term <command>gdb</command> refers to - the debugger <command>gdb</command> run in <quote>kernel debug - mode</quote>. This can be accomplished by starting the - <command>gdb</command> with the option <option>-k</option>. In - kernel debug mode, <command>gdb</command> changes its prompt to - <prompt>(kgdb)</prompt>.</para> - </note> - - <tip> - <para>If you are using FreeBSD 3 or earlier, you should make a stripped - copy of the debug kernel, rather than installing the large debug - kernel itself:</para> - - <screen>&prompt.root; <userinput>cp kernel kernel.debug</userinput> -&prompt.root; <userinput>strip -g kernel</userinput></screen> - - <para>This stage isn't necessary, but it is recommended. (In - FreeBSD 4 and later releases this step is performed automatically - at the end of the kernel <command>make</command> process.) - When the kernel has been stripped, either automatically or by - using the commands above, you may install it as usual by typing - <command>make install</command>.</para> - - <para>Note that older releases of FreeBSD (up to but not including - 3.1) used a.out kernels by default, which must have their symbol - tables permanently resident in physical memory. With the larger - symbol table in an unstripped debug kernel, this is wasteful. - Recent FreeBSD releases use ELF kernels where this is no longer a - problem.</para> - </tip> - - <para>If you are testing a new kernel, for example by typing the new - kernel's name at the boot prompt, but need to boot a different one in - order to get your system up and running again, boot it only into single - user state using the <option>-s</option> flag at the boot prompt, and - then perform the following steps:</para> - - <screen>&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable -&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput> -&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen> - - <para>This instructs &man.savecore.8; to use another kernel for symbol - name extraction. It would otherwise default to the currently running - kernel and most likely not do anything at all since the crash dump and - the kernel symbols differ.</para> - - <para>Now, after a crash dump, go to - <filename>/sys/compile/WHATEVER</filename> and run - <command>gdb <option>-k</option></command>. From <command>gdb</command> do: - - <screen><userinput>symbol-file kernel.debug</userinput> -<userinput>exec-file /var/crash/kernel.0</userinput> -<userinput>core-file /var/crash/vmcore.0</userinput></screen> - - and voila, you can debug the crash dump using the kernel sources just - like you can for any other program.</para> - - <para>Here is a script log of a <command>gdb</command> session - illustrating the procedure. Long lines have been folded to improve - readability, and the lines are numbered for reference. Despite this, it - is a real-world error trace taken during the development of the pcvt - console driver.</para> - -<screen> 1:Script started on Fri Dec 30 23:15:22 1994 - 2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput> - 3:&prompt.root; <userinput>gdb -k kernel /var/crash/vmcore.1</userinput> - 4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel -...done. - 5:IdlePTD 1f3000 - 6:panic: because you said to! - 7:current pcb at 1e3f70 - 8:Reading in symbols for ../../i386/i386/machdep.c...done. - 9:<prompt>(kgdb)</prompt> <userinput>where</userinput> -10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767) -11:#1 0xf0115159 in panic () -12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698) -13:#3 0xf010185e in db_fncall () -14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073) -15:#5 0xf0101711 in db_command_loop () -16:#6 0xf01040a0 in db_trap () -17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723) -18:#8 0xf019d2eb in trap_fatal (...) -19:#9 0xf019ce60 in trap_pfault (...) -20:#10 0xf019cb2f in trap (...) -21:#11 0xf01932a1 in exception:calltrap () -22:#12 0xf0191503 in cnopen (...) -23:#13 0xf0132c34 in spec_open () -24:#14 0xf012d014 in vn_open () -25:#15 0xf012a183 in open () -26:#16 0xf019d4eb in syscall (...) -27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput> -28:Reading in symbols for ../../i386/i386/trap.c...done. -29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\ -30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\ -31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\ -32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\ -33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\ -34:ss = -266427884}) (../../i386/i386/trap.c line 283) -35:283 (void) trap_pfault(&frame, FALSE); -36:<prompt>(kgdb)</prompt> <userinput>frame frame->tf_ebp frame->tf_eip</userinput> -37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done. -38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\ -39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403) -40:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -41:<prompt>(kgdb)</prompt> <userinput>list</userinput> -42:398 -43:399 tp->t_state |= TS_CARR_ON; -44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */ -45:401 -46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200) -47:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -48:404 #else -49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag)); -50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */ -51:407 } -52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput> -53:Reading in symbols for ../../i386/i386/cons.c...done. -54:$1 = (struct tty *) 0x1bae -55:<prompt>(kgdb)</prompt> <userinput>print tp->t_line</userinput> -56:$2 = 1767990816 -57:<prompt>(kgdb)</prompt> <userinput>up</userinput> -58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\ -59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126) -60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p)); -61:<prompt>(kgdb)</prompt> <userinput>up</userinput> -62:#2 0xf0132c34 in spec_open () -63:<prompt>(kgdb)</prompt> <userinput>up</userinput> -64:#3 0xf012d014 in vn_open () -65:<prompt>(kgdb)</prompt> <userinput>up</userinput> -66:#4 0xf012a183 in open () -67:<prompt>(kgdb)</prompt> <userinput>up</userinput> -68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\ -69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\ -70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \ -71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \ -72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673) -73:673 error = (*callp->sy_call)(p, args, rval); -74:<prompt>(kgdb)</prompt> <userinput>up</userinput> -75:Initial frame selected; you cannot go up. -76:<prompt>(kgdb)</prompt> <userinput>quit</userinput> -77:&prompt.root; <userinput>exit</userinput> -78:exit -79: -80:Script done on Fri Dec 30 23:18:04 1994</screen> - <para>Comments to the above script:</para> - - <variablelist> - <varlistentry> - <term>line 6:</term> - - <listitem> - <para>This is a dump taken from within DDB (see below), hence the - panic comment <quote>because you said to!</quote>, and a rather - long stack trace; the initial reason for going into DDB has been a - page fault trap though.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 20:</term> - - <listitem> - <para>This is the location of function <function>trap()</function> - in the stack trace.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 36:</term> - - <listitem> - <para>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 do not have a new core - dump handy <g>, my kernel has not panicked for a rather long - time.) From looking at the code in source line 403, there is a - high probability that either the pointer access for - <quote>tp</quote> was messed up, or the array access was out of - bounds.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 52:</term> - - <listitem> - <para>The pointer looks suspicious, but happens to be a valid - address.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 56:</term> - - <listitem> - <para>However, it obviously points to garbage, so we have found our - error! (For those unfamiliar with that particular piece of code: - <literal>tp->t_line</literal> refers to the line discipline of - the console device here, which must be a rather small integer - number.)</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1> - <title>Debugging a Crash Dump with DDD</title> - - <para>Examining a kernel crash dump with a graphical debugger like - <command>ddd</command> is also possible. Add the <option>-k</option> - option to the <command>ddd</command> command line you would use - normally. For example;</para> - - <screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen> - - <para>You should then be able to go about looking at the crash dump using - <command>ddd</command>'s graphical interface.</para> - </sect1> - - <sect1> - <title>Post-Mortem Analysis of a Dump</title> - - <para>What do you do if a kernel dumped core but you did not expect it, - and it is therefore not compiled using <command>config -g</command>? Not - everything is lost here. Do not panic!</para> - - <para>Of course, you still need to enable crash dumps. See above on the - options you have to specify in order to do this.</para> - - <para>Go to your kernel config directory - (<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>) - and edit your configuration file. Uncomment (or add, if it does not - exist) the following line</para> - - <programlisting> -makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting> - - <para>Rebuild the kernel. Due to the time stamp change on the Makefile, - there will be some other object files rebuild, for example - <filename>trap.o</filename>. With a bit of luck, the added - <option>-g</option> 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 &man.size.1; command. If there is a - mismatch, you probably need to give up here.</para> - - <para>Go and examine the dump as described above. The debugging symbols - might be incomplete for some places, as can be seen in the stack trace - in the example above where some functions are displayed without line - numbers and argument lists. If you need more debugging symbols, remove - the appropriate object files and repeat the <command>gdb <option>-k</option></command> - session until you know enough.</para> - - <para>All this is not guaranteed to work, but it will do it fine in most - cases.</para> - </sect1> - - <sect1> - <title>On-Line Kernel Debugging Using DDB</title> - - <para>While <command>gdb <option>-k</option></command> as an off-line debugger provides a very - high level of user interface, there are some things it cannot do. The - most important ones being breakpointing and single-stepping kernel - code.</para> - - <para>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-stepping kernel functions, examining and changing - kernel variables, etc. However, it cannot access kernel source files, - and only has access to the global and static symbols, not to the full - debug information like <command>gdb</command>.</para> - - <para>To configure your kernel to include DDB, add the option line - - <programlisting> -options DDB</programlisting> - - to your config file, and rebuild. (See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <note> - <para>Note that if you have an older version of the boot blocks, your - debugger symbols might not be loaded at all. Update the boot blocks; - the recent ones load the DDB symbols automagically.)</para> - </note> - - <para>Once your DDB kernel is running, there are several ways to enter - DDB. The first, and earliest way is to type the boot flag - <option>-d</option> right at the boot prompt. The kernel will start up - in debug mode and enter DDB prior to any device probing. Hence you can - even debug the device probe/attach functions.</para> - - <para>The second scenario is a hot-key on the keyboard, usually - Ctrl-Alt-ESC. For syscons, this can be remapped; some of the - distributed maps do this, so watch out. There is an option available - for serial consoles that allows the use of a serial line BREAK on the - console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal> - in the kernel config file). It is not the default since there are a lot - of crappy serial adapters around that gratuitously generate a BREAK - condition, for example when pulling the cable.</para> - - <para>The third way is that any panic condition will branch to DDB if the - kernel is configured to use it. For this reason, it is not wise to - configure a kernel with DDB for a machine running unattended.</para> - - <para>The DDB commands roughly resemble some <command>gdb</command> - commands. The first thing you probably need to do is to set a - breakpoint:</para> - - <screen><userinput>b function-name</userinput> -<userinput>b address</userinput></screen> - - <para>Numbers are taken hexadecimal by default, but to make them distinct - from symbol names; hexadecimal numbers starting with the letters - <literal>a-f</literal> need to be preceded with <literal>0x</literal> - (this is optional for other numbers). Simple expressions are allowed, - for example: <literal>function-name + 0x103</literal>.</para> - - <para>To continue the operation of an interrupted kernel, simply - type:</para> - - <screen><userinput>c</userinput></screen> - - <para>To get a stack trace, use:</para> - - <screen><userinput>trace</userinput></screen> - - <note> - <para>Note that when entering DDB via a hot-key, the kernel is currently - servicing an interrupt, so the stack trace might be not of much use - for you.</para> - </note> - - <para>If you want to remove a breakpoint, use</para> - - - <screen><userinput>del</userinput> -<userinput>del address-expression</userinput></screen> - - <para>The first form will be accepted immediately after a breakpoint hit, - and deletes the current breakpoint. The second form can remove any - breakpoint, but you need to specify the exact address; this can be - obtained from:</para> - - <screen><userinput>show b</userinput></screen> - - <para>To single-step the kernel, try:</para> - - <screen><userinput>s</userinput></screen> - - <para>This will step into functions, but you can make DDB trace them until - the matching return statement is reached by:</para> - - <screen><userinput>n</userinput></screen> - - <note> - <para>This is different from <command>gdb</command>'s - <command>next</command> statement; it is like <command>gdb</command>'s - <command>finish</command>.</para> - </note> - - <para>To examine data from memory, use (for example): - - <screen><userinput>x/wx 0xf0133fe0,40</userinput> -<userinput>x/hd db_symtab_space</userinput> -<userinput>x/bc termbuf,10</userinput> -<userinput>x/s stringbuf</userinput></screen> - - for word/halfword/byte access, and hexadecimal/decimal/character/ string - display. The number after the comma is the object count. To display - the next 0x10 items, simply use:</para> - - <screen><userinput>x ,10</userinput></screen> - - <para>Similarly, use - - <screen><userinput>x/ia foofunc,10</userinput></screen> - - to disassemble the first 0x10 instructions of - <function>foofunc</function>, and display them along with their offset - from the beginning of <function>foofunc</function>.</para> - - <para>To modify memory, use the write command:</para> - - <screen><userinput>w/b termbuf 0xa 0xb 0</userinput> -<userinput>w/w 0xf0010030 0 0</userinput></screen> - - <para>The command modifier - (<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) - specifies the size of the data to be written, the first following - expression is the address to write to and the remainder is interpreted - as data to write to successive memory locations.</para> - - <para>If you need to know the current registers, use:</para> - - <screen><userinput>show reg</userinput></screen> - - <para>Alternatively, you can display a single register value by e.g. - - <screen><userinput>p $eax</userinput></screen> - - and modify it by:</para> - - <screen><userinput>set $eax new-value</userinput></screen> - - <para>Should you need to call some kernel functions from DDB, simply - say:</para> - - <screen><userinput>call func(arg1, arg2, ...)</userinput></screen> - - <para>The return value will be printed.</para> - - <para>For a &man.ps.1; style summary of all running processes, use:</para> - - <screen><userinput>ps</userinput></screen> - - <para>Now you have now examined why your kernel failed, and you wish to - reboot. Remember that, depending on the severity of previous - malfunctioning, not all parts of the kernel might still be working as - expected. Perform one of the following actions to shut down and reboot - your system:</para> - - <screen><userinput>panic</userinput></screen> - - <para>This will cause your kernel to dump core and reboot, so you can - later analyze the core on a higher level with <command>gdb</command>. This command - usually must be followed by another <command>continue</command> - statement.</para> - - <screen><userinput>call boot(0)</userinput></screen> - - <para>Which might be a good way to cleanly shut down the running system, - <function>sync()</function> all disks, and finally reboot. As long as - the disk and file system interfaces of the kernel are not damaged, this - might be a good way for an almost clean shutdown.</para> - - <screen><userinput>call cpu_reset()</userinput></screen> - - <para>is the final way out of disaster and almost the same as hitting the - Big Red Button.</para> - - <para>If you need a short command summary, simply type:</para> - - <screen><userinput>help</userinput></screen> - - <para>However, it is highly recommended to have a printed copy of the - &man.ddb.4; manual page ready for a debugging - session. Remember that it is hard to read the on-line manual while - single-stepping the kernel.</para> - </sect1> - - <sect1> - <title>On-Line Kernel Debugging Using Remote GDB</title> - - <para>This feature has been supported since FreeBSD 2.2, and it is - actually a very neat one.</para> - - <para>GDB has already supported <emphasis>remote debugging</emphasis> for - a long time. This is done using a very simple protocol along a serial - line. Unlike the other methods described above, you will need two - machines for doing this. One is the host providing the debugging - environment, including all the sources, and a copy of the kernel binary - with all the symbols in it, and the other one is the target machine that - simply runs a similar copy of the very same kernel (but stripped of the - debugging information).</para> - - <para>You should configure the kernel in question with <command>config - -g</command>, include <option>DDB</option> into the configuration, and - compile it as usual. This gives a large blurb of a binary, due to the - debugging information. Copy this kernel to the target machine, strip - the debugging symbols off with <command>strip -x</command>, and boot it - using the <option>-d</option> boot option. Connect the serial line - of the target machine that has "flags 080" set on its sio device - to any serial line of the debugging host. - Now, on the debugging machine, go to the compile directory of the target - kernel, and start <command>gdb</command>:</para> - - <screen>&prompt.user; <userinput>gdb -k kernel</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-freebsd), -Copyright 1996 Free Software Foundation, Inc... -<prompt>(kgdb)</prompt> </screen> - - <para>Initialize the remote debugging session (assuming the first serial - port is being used) by:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen> - - <para>Now, on the target host (the one that entered DDB right before even - starting the device probe), type:</para> - - <screen>Debugger("Boot flags requested debugger") -Stopped at Debugger+0x35: movb $0, edata+0x51bc -<prompt>db></prompt> <userinput>gdb</userinput></screen> - - <para>DDB will respond with:</para> - - <screen>Next trap will enter GDB remote protocol mode</screen> - - <para>Every time you type <command>gdb</command>, the mode will be toggled - between remote GDB and local DDB. In order to force a next trap - immediately, simply type <command>s</command> (step). Your hosting GDB - will now gain control over the target kernel:</para> - - <screen>Remote debugging using /dev/cuaa0 -Debugger (msg=0xf01b0383 "Boot flags requested debugger") - at ../../i386/i386/db_interface.c:257 -<prompt>(kgdb)</prompt></screen> - - <para>You can use this session almost as any other GDB session, including - full access to the source, running it in gud-mode inside an Emacs window - (which gives you an automatic source code display in another Emacs - window) etc.</para> - </sect1> - - <sect1> - <title>Debugging Loadable Modules Using GDB</title> - - <para>When debugging a panic that occurred within a module, or - using remote GDB against a machine that uses dynamic modules, - you need to tell GDB how to obtain symbol information for those - modules.</para> - - <para>First, you need to build the module(s) with debugging - information:</para> - - <screen>&prompt.root; <userinput>cd /sys/modules/linux</userinput> -&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen> - - <para>If you are using remote GDB, you can run - <command>kldstat</command> on the target machine to find out - where the module was loaded:</para> - - <screen>&prompt.root; <userinput>kldstat</userinput> -Id Refs Address Size Name - 1 4 0xc0100000 1c1678 kernel - 2 1 0xc0a9e000 6000 linprocfs.ko - 3 1 0xc0ad7000 2000 warp_saver.ko - 4 1 0xc0adc000 11000 linux.ko -</screen> - - <para>If you are debugging a crash dump, you'll need to walk the - <literal>linker_files</literal> list, starting at - <literal>linker_files->tqh_first</literal> and following the - <literal>link.tqe_next</literal> pointers until you find the - entry with the <literal>filename</literal> you are looking for. - The <literal>address</literal> member of that entry is the load - address of the module.</para> - - <para>Next, you need to find out the offset of the text section - within the module:</para> - - <screen>&prompt.root; <userinput>objdump --section-headers /sys/modules/linux/linux.ko | grep text</userinput> - 3 .rel.text 000016e0 000038e0 000038e0 000038e0 2**2 - 10 .text 00007f34 000062d0 000062d0 000062d0 2**2</screen> - - <para>The one you want is the <literal>.text</literal> section, - section 10 in the above example. The fourth numerical field - (sixth field overall) is the offset in hex of the text section - within the file (0x62d0 in our example). Add this to the load - address reported by <command>kldstat</command> to obtain the - address of the module text in memory.</para> - - <para>Take the load address of the module (as reported by - <command>kldstat</command>) and add the offset of the text - section within the module (0x62d0 + 0xc0adc000 = c0ae22d0 in our - example). This is the address that the module code was - relocated to. Use the <command>add-symbol-file</command> - command in GDB to tell the debugger about the module:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0</userinput> -add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0? -(y or n) <userinput>y</userinput> -Reading symbols from /sys/modules/linux/linux.ko...done. -<prompt>(kgdb)</prompt></screen> - - <para>You should now have access to all the symbols in the - module.</para> - </sect1> - - <sect1> - <title>Debugging a Console Driver</title> - - <para>Since you need a console driver to run DDB on, things are more - complicated if the console driver itself is failing. You might remember - the use of a serial console (either with modified boot blocks, or by - specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), - and hook up a standard terminal onto your first serial port. DDB works - on any configured console driver, of course also on a serial - console.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml deleted file mode 100644 index 0b33eff446..0000000000 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml +++ /dev/null @@ -1,398 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml,v 1.17 2000/06/14 20:30:36 jim Exp $ ---> - -<chapter id="policies"> - <title>Source Tree Guidelines and Policies</title> - - <para><emphasis>Contributed by &a.phk;.</emphasis></para> - - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> - - <sect1 id="policies-maintainer"> - <title><makevar>MAINTAINER</makevar> on Makefiles</title> - - <para>June 1996.</para> - - <para>If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a - - <programlisting> -MAINTAINER= email-addresses</programlisting> - - line to the <filename>Makefile</filename>s covering this portion of the - source tree.</para> - - <para>The semantics of this are as follows:</para> - - <para>The maintainer owns and is responsible for that code. This means - that he is responsible for fixing bugs and answer problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate.</para> - - <para>Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try and have the - changes reviewed by someone else if at all possible.</para> - - <para>It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - doesn't have to be a committer and it can easily be a group of - people.</para> - </sect1> - - <sect1 id="policies-contributed"> - <title>Contributed Software</title> - - <para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para> - - <para>June 1996.</para> - - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are perl, gcc and patch.</para> - - <para>Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the <quote>official</quote> method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - <quote>official</quote> versions of the source by everyone (even without - cvs access). This will make it significantly easier to return changes - to the primary developers of the contributed software.</para> - - <para>Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions.</para> - - <note> - <para>Because of some unfortunate design limitations with the RCS file - format and CVS's use of vendor branches, minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch. <quote>Spelling - fixes</quote> are explicitly included here under the - <quote>cosmetic</quote> category and are to be avoided for files with - revision 1.1.x.x. The repository bloat impact from a single character - change can be rather dramatic.</para> - </note> - - <para>The <application>TCL</application> embedded programming - language will be used as example of how this model works:</para> - - <para><filename>src/contrib/tcl</filename> contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - <filename>mac</filename>, <filename>win</filename> and - <filename>compat</filename> subdirectories were eliminated before the - import</para> - - <para><filename>src/lib/libtcl</filename> contains only a "bmake style" - <filename>Makefile</filename> that uses the standard - <filename>bsd.lib.mk</filename> makefile rules to produce the library - and install the documentation.</para> - - <para><filename>src/usr.bin/tclsh</filename> contains only a bmake style - <filename>Makefile</filename> which will produce and install the - <command>tclsh</command> program and its associated man-pages using the - standard <filename>bsd.prog.mk</filename> rules.</para> - - <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of - shell-scripts that can be of help when the tcl software needs updating. - These are not part of the built or installed software.</para> - - <para>The important thing here is that the - <filename>src/contrib/tcl</filename> directory is created according to - the rules: It is supposed to contain the sources as distributed (on a - proper CVS vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. The 'easy-import' tool on - freefall will assist in doing the import, but if there are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it <quote>works out</quote>. CVS is not forgiving of - import accidents and a fair amount of effort is required to back out - major mistakes.</para> - - <para>Because of the previously mentioned design limitations with CVS's - vendor branches, it is required that <quote>official</quote> patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and "committed", as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts.</para> - - <para>Since many packages contain files that are meant for compatibility - with other architectures and environments that FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall <emphasis>not</emphasis> be removed.</para> - - <para>If it seems easier, the <command>bmake</command> - <filename>Makefile</filename>s can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - <filename>src/tools</filename> directory along with the port itself so - that it is available to future maintainers.</para> - - <para>In the <filename>src/contrib/tcl</filename> level directory, a file - called <filename>FREEBSD-upgrade</filename> should be added and it - should states things like:</para> - - <itemizedlist> - <listitem> - <para>Which files have been left out</para> - </listitem> - - <listitem> - <para>Where the original distribution was obtained from and/or the - official master site.</para> - </listitem> - - <listitem> - <para>Where to send patches back to the original authors</para> - </listitem> - - <listitem> - <para>Perhaps an overview of the FreeBSD-specific changes that have - been made.</para> - </listitem> - </itemizedlist> - - <para>However, please do not import <filename>FREEBSD-upgrade</filename> - with the contributed source. Rather you should <command>cvs add - FREEBSD-upgrade ; cvs ci</command> after the initial import. Example - wording from <filename>src/contrib/cpio</filename> is below:</para> - - <programlisting> -This directory contains virgin sources of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. New versions or -official-patch versions must be imported. Please remember to import with -"-ko" to prevent CVS from corrupting any vendor RCS Ids. - -For the import of GNU cpio 2.4.2, the following files were removed: - - INSTALL cpio.info mkdir.c - Makefile.in cpio.texi mkinstalldirs - -To upgrade to a newer version of cpio, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Remove the files listed above and any others that don't apply to - FreeBSD. - - 3. Use the command: - cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU cpio_<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -ko -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU cpio_2_4_2 - - 4. Follow the instructions printed out in step 3 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to cpio, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the GNU branch. - -All local changes should be submitted to "cpio@gnu.ai.mit.edu" for -inclusion in the next vendor release. - -obrien@FreeBSD.org - 30 March 1997</programlisting> - </sect1> - - <sect1 id="policies-encumbered"> - <title>Encumbered Files</title> - - <para>It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree.</para> - - <orderedlist> - <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> - </listitem> - - <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> - </listitem> - - <listitem> - <para>A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended).</para> - </listitem> - - <listitem> - <para>Any encumbered file requires specific approval from the <link - linkend="staff-core">Core team</link> before it is added to the - CVS repository.</para> - </listitem> - - <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> - </listitem> - - <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> - </listitem> - - <listitem> - <para>Object files are named - <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> - </listitem> - - <listitem> - <para>Kernel files;</para> - - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> - </listitem> - - <listitem> - <para>Should always be in <filename>LINT</filename>, but the <link - linkend="staff-core">Core team</link> decides per case if it - should be commented out or not. The <link - linkend="staff-core">Core team</link> can, of course, change - their minds later on.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides whether or not it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>User-land files;</para> - - <orderedlist> - <listitem> - <para>The <link linkend="staff-core">Core team</link> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides if it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </sect1> - - <sect1 id="policies-shlib"> - <title>Shared Libraries</title> - - <para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 - December 1996.</emphasis></para> - - <para>If you are adding shared library support to a port or other piece of - software that doesn't have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software.</para> - - <para>The three principles of shared library building are:</para> - - <itemizedlist> - <listitem> - <para>Start from <literal>1.0</literal></para> - </listitem> - - <listitem> - <para>If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number)</para> - </listitem> - - <listitem> - <para>If there is an incompatible change, bump major number</para> - </listitem> - </itemizedlist> - - <para>For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax etc. will force the major version number to change.</para> - - <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out - dynamic linker does not handle version numbers of the form - <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> - well. Any version number after the <replaceable>y</replaceable> - (ie. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the <quote>micro</quote> revision, - <command>ld.so</command> will link with the higher one. Ie: if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(highest - available)</replaceable>.</para> - - <note> - <para><command>ld.so</command> will always use the highest - <quote>minor</quote> revision. Ie: it will use - <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> - </note> - - <para>In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our <filename>Makefile</filename>s "do the right thing" - based on the type of system.</para> - - <para>For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is - our policy to change the major shared library version number only once - between major OS releases. Ie: X.0 to (X+1).0. When you make a - change to a system library that requires the version number to be - bumped, check the <filename>Makefile</filename>'s commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/faq/Makefile b/en_US.ISO8859-1/books/faq/Makefile deleted file mode 100644 index b6e3f64d37..0000000000 --- a/en_US.ISO8859-1/books/faq/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -# -# $FreeBSD$ -# -# Build the FreeBSD FAQ -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml deleted file mode 100644 index 75ef0f2d66..0000000000 --- a/en_US.ISO8859-1/books/faq/book.sgml +++ /dev/null @@ -1,11371 +0,0 @@ -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> -%authors; -]> - -<book> - <bookinfo> - <title>Frequently Asked Questions for FreeBSD 2.X, 3.X and 4.X</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.123 2000/11/12 16:22:40 nik Exp $</pubdate> - - <abstract> - <para>This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X. - All entries are assumed to be relevant to FreeBSD 2.0.5 and later, - unless otherwise noted. Any entries with a <XXX> are under - construction. If you are interested in helping with this project, - send email to the FreeBSD documentation project mailing list - <email>freebsd-doc@FreeBSD.org</email>. The latest version of this - document is always available from the <ulink - URL="http://www.FreeBSD.org/">FreeBSD World Wide Web - server</ulink>. It may also be downloaded as one large <ulink - URL="book.html">HTML</ulink> file with HTTP or as plain text, - postscript, PDF, etc. from the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP - server</ulink>. You may also want to <ulink - URL="http://www.FreeBSD.org/search/search.html">Search the - FAQ</ulink>.</para> - </abstract> - </bookinfo> - - <preface id="preface"> - <title>Preface</title> - - <para>Welcome to the FreeBSD 2.X-4.X FAQ!</para> - - <para>As is usual with Usenet FAQs, this document aims to cover the - most frequently asked questions concerning the FreeBSD operating - system (and of course answer them!). Although originally intended - to reduce bandwidth and avoid the same old questions being asked - over and over again, FAQs have become recognized as valuable - information resources.</para> - - <para>Every effort has been made to make this FAQ as informative as - possible; if you have any suggestions as to how it may be improved, - please feel free to mail them to the &a.faq;.</para> - - <qandaset> - <qandaentry> - <question id="what-is-FreeBSD"> - <para>What is FreeBSD?</para> - </question> - - <answer> - <para>Briefly, FreeBSD is a UN*X-like operating system for the - i386 and Alpha/AXP platforms based on U.C. Berkeley's - 4.4BSD-Lite release, with some 4.4BSD-Lite2 enhancements. - It is also based indirectly on William Jolitz's port of U.C. - Berkeley's Net/2 to the i386, known as 386BSD, though very - little of the 386BSD code remains. A fuller description of - what FreeBSD is and how it can work for you may be found on - the <ulink URL="http://www.FreeBSD.org/">FreeBSD home - page</ulink>.</para> - - <para>FreeBSD is used by companies, Internet Service Providers, - researchers, computer professionals, students and home users - all over the world in their work, education and recreation. - See some of them in the <ulink - URL="http://www.FreeBSD.org/gallery/gallery.html">FreeBSD - Gallery</ulink>.</para> - - <para>For more detailed information on FreeBSD, please see the - <ulink URL="../handbook/index.html">FreeBSD - Handbook</ulink>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="FreeBSD-goals"> - <para>What are the goals of FreeBSD?</para> - </question> - - <answer> - <para>The goals of the FreeBSD Project are to provide software - that may be used for any purpose and without strings attached. - Many of us have a significant investment in the code (and - project) and would certainly not mind a little financial - compensation now and then, but we're definitely not prepared - to insist on it. We believe that our first and foremost - <quote>mission</quote> is to provide code to any and all - comers, and for whatever purpose, so that the code gets the - widest possible use and provides the widest possible benefit. - This is, we believe, one of the most fundamental goals of Free - Software and one that we enthusiastically support.</para> - - <para>That code in our source tree which falls under the GNU - General Public License (GPL) or GNU Library General Public - License (LGPL) comes with slightly more strings attached, - though at least on the side of enforced access rather than the - usual opposite. Due to the additional complexities that can - evolve in the commercial use of GPL software, we do, however, - endeavor to replace such software with submissions under the - more relaxed BSD copyright whenever possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="why-called-FreeBSD"> - <para>Why is it called FreeBSD?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>It may be used free of charge, even by commercial - users.</para> - </listitem> - - <listitem> - <para>Full source for the operating system is freely - available, and the minimum possible restrictions have - been placed upon its use, distribution and incorporation - into other work (commercial or non-commercial).</para> - </listitem> - - <listitem> - <para>Anyone who has an improvement and/or bug fix is free - to submit their code and have it added to the source tree - (subject to one or two obvious provisos).</para> - </listitem> - </itemizedlist> - - <para>For those of our readers whose first language is not - English, it may be worth pointing out that the word - <quote>free</quote> is being used in two ways here, one meaning - <quote>at no cost</quote>, the other meaning <quote>you can do - whatever you like</quote>. Apart from one or two things you - <emphasis>cannot</emphasis> do with the FreeBSD code, for - example pretending you wrote it, you really can do whatever you - like with it.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="latest-version"> - <para>What is the latest version of FreeBSD?</para> - </question> - - <answer> - <para>Version <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/4.1.1-RELEASE/">4.1.1</ulink> - is the latest <emphasis>STABLE</emphasis> version; it was - released in September, 2000. This is also the latest - <emphasis>RELEASE</emphasis> version.</para> - - <para>Briefly explained, <emphasis>-STABLE</emphasis> is aimed - at the ISP or other corporate user who wants stability and a - low change count over the wizzy new features of the latest - <emphasis>-CURRENT</emphasis> snapshot. Releases can come - from either branch, but you should only use - <emphasis>-CURRENT</emphasis> if you're sure that you're - prepared for its increased volatility (relative to - <emphasis>-STABLE</emphasis>, that is).</para> - - <para>Releases are only made <link linkend="release-freq">every - few months</link>. While many people stay more up-to-date with - the FreeBSD sources (see the questions on <link - linkend="current">FreeBSD-CURRENT</link> and <link - linkend="stable">FreeBSD-STABLE</link>) than that, doing so - is more of a commitment, as the sources are a moving - target.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="current"> - <para>What is FreeBSD-CURRENT?</para> - </question> - - <answer> - <para><ulink - URL="../handbook/cutting-edge.html#CURRENT">FreeBSD-CURRENT</ulink> - is the development version of the operating system, which will - in due course become 5.0-RELEASE. As such, it is really only - of interest to developers working on the system and die-hard - hobbyists. See the <ulink - URL="../handbook/cutting-edge.html#CURRENT">relevant - section</ulink> in the <ulink - URL="../handbook/index.html">handbook</ulink> for details on - running -CURRENT.</para> - - <para>If you are not familiar with the operating system or are - not capable of identifying the difference between a real - problem and a temporary problem, you should not use - FreeBSD-CURRENT. This branch sometimes evolves quite quickly - and can be un-buildable for a number of days at a time. - People that use FreeBSD-CURRENT are expected to be able to - analyze any problems and only report them if they are deemed - to be mistakes rather than <quote>glitches</quote>. Questions - such as <quote>make world produces some error about - groups</quote> on the -CURRENT mailing list are sometimes - treated with contempt.</para> - - <para>Every day, <ulink - URL="http://www.FreeBSD.org/releases/snapshots.html">snapshot - </ulink> releases are made based on the current state of the - -CURRENT and -STABLE branches. Nowadays, distributions of the - occasional snapshot are now being made available. The goals - behind each snapshot release are:</para> - - <itemizedlist> - <listitem> - <para>To test the latest version of the installation - software.</para> - </listitem> - - <listitem> - <para>To give people who would like to run -CURRENT or - -STABLE but who don't have the time and/or bandwidth to - follow it on a day-to-day basis an easy way of - bootstrapping it onto their systems.</para> - </listitem> - - <listitem> - <para>To preserve a fixed reference point for the code in - question, just in case we break something really badly - later. (Although CVS normally prevents anything horrible - like this happening :)</para> - </listitem> - - <listitem> - <para>To ensure that any new features in need of testing - have the greatest possible number of potential - testers.</para> - </listitem> - </itemizedlist> - - <para>No claims are made that any -CURRENT snapshot can be - considered <quote>production quality</quote> for any purpose. - If you want to run a stable and fully tested system, you will - have to stick to full releases, or use the -STABLE - snaphosts.</para> - - <para>Snapshot releases are directly available from <ulink - URL="ftp://current.FreeBSD.org/pub/FreeBSD/"> - ftp://current.FreeBSD.org/pub/FreeBSD/</ulink> for 5.0-CURRENT - and <ulink URL="ftp://releng4.FreeBSD.org/pub/FreeBSD"> - releng4.FreeBSD.org</ulink> for 4-STABLE snapshots. - 3-STABLE snapshots are not being produced at the time of - this writing (May 2000).</para> - - <para>Snapshots are generated, on the average, once a day for - all actively developed branches.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="stable"> - <para>What is the FreeBSD-STABLE concept?</para> - </question> - - <answer> - <para>Back when FreeBSD 2.0.5 was released, we decided to - branch FreeBSD development into two parts. One branch was - named <ulink URL="../handbook/stable.html">-STABLE</ulink>, - with the intention that only well-tested bug fixes and small - incremental enhancements would be made to it (for Internet - Service Providers and other commercial enterprises for whom - sudden shifts or experimental features are quite - undesirable). The other branch was <ulink - URL="../handbook/cutting-edge.html#CURRENT">-CURRENT</ulink>, - which essentially has been one unbroken line leading towards - 5.0-RELEASE (and beyond) since 2.0 was released. If a little - ASCII art would help, this is how it looks:</para> - - <programlisting> 2.0 - | - | - | [2.1-STABLE] - *BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE ends] - | (Mar 1997) - | - | - | [2.2-STABLE] - *BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [end] - | (Mar 1997) (Oct 97) (Apr 98) (Jul 98) (Dec 98) - | - | - 3.0-SNAPs (started Q1 1997) - | - | - 3.0-RELEASE (Oct 1998) - | - | [3.0-STABLE] - *BRANCH* 3.1-RELEASE (Feb 1999) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1 - | (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000) - | - | [4.0-STABLE] - *BRANCH* 4.0 (Mar 2000) -> 4.1 -> 4.1.1 -> ... future 4.x releases ... - | - | (July 2000) (Sep 2000) - \|/ - + - [5.0-CURRENT continues]</programlisting> - - <para>The -CURRENT branch is slowly progressing towards 5.0 and - beyond, the previous 2.2-STABLE branch having been retired with - the release of 2.2.8. 3-STABLE replaced it, with 3.5.1 (the - final 3.X release) being released in July 2000. In May 2000 - (even though 3.5 came after that), the 3-STABLE branch was more - or less replaced by the 4-STABLE branch. 4.1.1-RELEASE was - released in September 2000. 4-STABLE is the actively developed - -STABLE branch, although some bugfixes (mostly - security-related) are still being committed to 3-STABLE. It is - expected that the 3.X branch will be officially obsoleted some - time in summer 2000. 5.0-CURRENT is now the <quote>current - branch</quote>, with the no release date planed.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="release-freq"> - <para>When are FreeBSD releases made?</para> - </question> - - <answer> - <para>As a general principle, the FreeBSD core team only release - a new version of FreeBSD when they believe that there are - sufficient new features and/or bug fixes to justify one, and - are satisfied that the changes made have settled down - sufficiently to avoid compromising the stability of the - release. Many users regard this caution as one of the best - things about FreeBSD, although it can be a little frustrating - when waiting for all the latest goodies to become - available...</para> - - <para>Releases are made about every 4 months on average.</para> - - <para>For people needing (or wanting) a little more excitement, - binary snapshots are made every day... see above.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="available-platforms"> - <para>Is FreeBSD only available for PCs ?</para> - </question> - - <answer> - <para>Since 3.x, FreeBSD has run on the <ulink - URL="http://www.FreeBSD.org/alpha/alpha.html">DEC Alpha</ulink> - as well as the x86 architecture. Some interest has also been - expressed in a SPARC port, but details on this project are not yet - clear.</para> - - <para>If your machine has a different architecture and you need - something right now, we suggest you look at <ulink - URL="http://www.netbsd.org/">NetBSD</ulink> or <ulink - URL="http://www.openbsd.org/">OpenBSD</ulink>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="responsible"> - <para> Who is responsible for FreeBSD?</para> - </question> - - <answer> - <para>The key decisions concerning the FreeBSD project, such as - the overall direction of the project and who is allowed to add - code to the source tree, are made by a <ulink - URL="../handbook/staff.html#STAFF-CORE">core team</ulink> of - 9 people. There is a much larger team of more than 200 <ulink - URL="../handbook/staff-committers.html">committers</ulink> who - are authorized to make changes directly to the FreeBSD source - tree.</para> - - <para>However, most non-trivial changes are discussed in advance - in the <link linkend="mailing">mailing lists</link>, and there - are no restrictions on who may take part in the - discussion.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="where-get"> - <para>Where can I get FreeBSD?</para> - </question> - - <answer> - <para>Every significant release of FreeBSD is available via - anonymous ftp from the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> - FreeBSD FTP site</ulink>:</para> - - <itemizedlist> - <listitem> - <para>For the current 3.X-STABLE release, 3.5.1-RELEASE, see - the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/3.5.1-RELEASE/">3.5.1-RELEASE directory</ulink>.</para> - </listitem> - - <listitem> - <para>The current 4-STABLE release, 4.1.1-RELEASE can be - found in the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/4.1.1-RELEASE/">4.1.1-RELEASE directory</ulink>.</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://releng4.FreeBSD.org/pub/FreeBSD/">4.X - snapshots</ulink> are usually made once a day.</para> - </listitem> - - <listitem> - <para><ulink - URL="ftp://current.FreeBSD.org/pub/FreeBSD/"> - 5.0 Snapshot</ulink> releases are made once a day for the - <link linkend="current">-CURRENT</link> branch, these being - of service purely to bleeding-edge testers and - developers.</para> - </listitem> - </itemizedlist> - - <para>FreeBSD is also available via CDROM, from the following - place(s):</para> - - <address>BSDi -<street>4041 Pike Lane, Suite F</street> -<city>Concord</city>, <state>CA</state> -<postcode>94520</postcode> -<country>USA</country> - -<phone>Orders: +1 800 786-9907</phone> -<phone>Questions: +1 925 674-0783</phone> -<fax>FAX: +1 925 674-0821</fax> -<otheraddr>email: <ulink URL="mailto:orders@osd.bsdi.com">BSDi Orders address</ulink></otheraddr> -<otheraddr>WWW: <ulink URL="http://www.osd.bsdi.com/">BSDi Home page</ulink></otheraddr></address> - - <para>In Australia, you may find it at:</para> - - <address>Advanced Multimedia Distributors -<street>Factory 1/1 Ovata Drive</street> -<city>Tullamarine, Melbourne</city> -<state>Victoria</state> -<country>Australia</country> -<phone>Voice: +61 3 9338 6777</phone> - -<otheraddr>CDROM Support BBS</otheraddr> -<street>17 Irvine St</street> -<city>Peppermint Grove</city>, <state>WA</state> -<postcode>6011</postcode> -<phone>Voice: +61 9 385-3793</phone> -<fax>Fax: +61 9 385-2360</fax></address> - - <para>And in the UK:</para> - - <address>The Public Domain & Shareware Library -<street>Winscombe House, Beacon Rd</street> -<city>Crowborough</city> -<state>Sussex. TN6 1UL</state> -<phone>Voice: +44 1892 663-298</phone> -<fax>Fax: +44 1892 667-473</fax></address> - </answer> - </qandaentry> - - <qandaentry> - <question id="mailing"> - <para>Where do I find info on the FreeBSD mailing lists?</para> - </question> - - <answer> - <para>You can find full information in the <ulink - URL="../handbook/eresources.html#ERESOURCES-MAIL">Handbook - entry on mailing-lists.</ulink></para> - </answer> - </qandaentry> - - <qandaentry> - <question id="y2k"> - <para>Where do I find the FreeBSD Y2K info?</para> - </question> - - <answer> - <para>You can find full information in the <ulink - URL="http://www.FreeBSD.org/y2kbug.html">FreeBSD Y2K - page.</ulink></para> - </answer> - </qandaentry> - - <qandaentry> - <question id="newsgroups"> - <para>What FreeBSD news groups are available?</para> - </question> - - <answer> - <para>You can find full information in the <ulink - URL="../handbook/eresources-news.html">Handbook entry on - newsgroups.</ulink></para> - </answer> - </qandaentry> - - <qandaentry> - <question id="irc"> - <para>Are there FreeBSD IRC (Internet Relay Chat) - channels?</para> - </question> - - <answer> - <para>Yes, most major IRC networks host a FreeBSD chat - channel:</para> - - <itemizedlist> - <listitem> - <para>Channel <literal>#FreeBSD</literal> on - EFNet is a FreeBSD forum, but don't go there for tech - support or to try and get folks there to help you avoid - the pain of reading man pages or doing your own research. - It is a chat channel, first and foremost, and topics there - are just as likely to involve sex, sports or nuclear - weapons as they are FreeBSD. You Have Been Warned! - Available at server <hostid>irc.chat.org</hostid>.</para> - </listitem> - - <listitem> - <para>Channel <emphasis>#FreeBSDhelp</emphasis> on - EFNet is a channel dedicated to helping FreeBSD users. They - are much more sympathetic to questions then - <emphasis>#FreeBSD</emphasis> is.</para> - </listitem> - - <listitem> - <para>Channel <literal>#FreeBSD</literal> on - DALNET is available at <hostid>irc.dal.net</hostid> in the - US and <hostid>irc.eu.dal.net</hostid> in Europe.</para> - </listitem> - - <listitem> - <para>Channel <literal>#FreeBSD</literal> on - UNDERNET is available at <hostid>us.undernet.org</hostid> - in the US and <hostid>eu.undernet.org</hostid> in Europe. - Since it is a help channel, be prepared to read the - documents you are referred to.</para> - </listitem> - - <listitem> - <para>Channel <literal>#FreeBSD</literal> on <ulink - url="http://www.hybnet.net/">HybNet</ulink> is available - at <hostid>irc.FreeBSD.org</hostid>. This channel - <emphasis>is</emphasis> a help channel.</para> - </listitem> - </itemizedlist> - - <para>Each of these channels are distinct and are not connected - to each other. Their chat styles also differ, so you may need - to try each to find one suited to your chat style. As with - *all* types of IRC traffic, if you're easily offended or can't - deal with lots of young people (and more than a few older - ones) doing the verbal equivalent of jello wrestling, don't - even bother with it.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="books"> - <para>Books on FreeBSD</para> - </question> - - <answer> - <para>There is a FreeBSD Documentation Project which you may - contact (or even better, join) at the - <literal>freebsd-doc</literal> mailing list: - <email>freebsd-doc@FreeBSD.org</email>. - This list is for discussion of the FreeBSD documentation. For - actual questions about FreeBSD, there is the - <literal>freebsd-questions</literal> mailing list: - <email>freebsd-questions@FreeBSD.org</email>.</para> - - <para>A FreeBSD <quote>handbook</quote> is available, and can be - found as: <ulink URL="../handbook/index.html">the FreeBSD - Handbook</ulink>. Note that this is a work in progress; some - parts may be incomplete or out-of-date.</para> - - <para>The definitive printed guide on FreeBSD is - <quote>The Complete FreeBSD</quote>, written by Greg Lehey and - published by BSDi (formerly Walnut Creek CDROM) Books. Now in its second - edition, the book contains 1,750 pages of install & system - administration guidance, program setup help, and manual pages. - The book (and current FreeBSD release) can be ordered from - <ulink URL="http://www.osd.bsdi.com/">BSDi</ulink>, - <ulink URL="http://www.cheapbytes.com/">CheapBytes</ulink>, or - at your favorite bookstore. The ISBN is 1-57176-227-2.</para> - - <para>Since FreeBSD is based upon Berkeley - 4.4BSD-Lite, most of the 4.4BSD manuals are applicable to - FreeBSD. O'Reilly and Associates publishes the following - manuals:</para> - - <itemizedlist> - <listitem> - <para>4.4BSD System Manager's Manual <!-- <br> --> - By Computer Systems Research Group, UC Berkeley <!-- <br> --> - 1st Edition June 1994, 804 pages <!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/1-56592-080-5">ISBN</ulink>: - 1-56592-080-5 <!-- <br> --></para> - </listitem> - - <listitem> - <para>4.4BSD User's Reference Manual <!-- <br> --> - By Computer Systems Research Group, UC Berkeley <!-- <br> --> - 1st Edition June 1994, 905 pages <!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/1-56592-075-9">ISBN</ulink>: - 1-56592-075-9 <!-- <br> --></para> - </listitem> - - <listitem> - <para>4.4BSD User's Supplementary Documents <!-- <br> --> - By Computer Systems Research Group, UC Berkeley <!-- <br> --> - 1st Edition July 1994, 712 pages <!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/1-56592-076-7">ISBN</ulink>: - 1-56592-076-7 <!-- <br> --></para> - </listitem> - - <listitem> - <para>4.4BSD Programmer's Reference Manual <!-- <br> --> - By Computer Systems Research Group, UC Berkeley <!-- <br> --> - 1st Edition June 1994, 886 pages <!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/1-56592-078-3">ISBN</ulink>: - 1-56592-078-3 <!-- <br> --></para> - </listitem> - - <listitem> - <para>4.4BSD Programmer's Supplementary Documents <!-- <br> --> - By Computer Systems Research Group, UC Berkeley <!-- <br> --> - 1st Edition July 1994, 596 pages <!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/1-56592-079-1">ISBN</ulink>: - 1-56592-079-1 <!-- <br> --></para> - </listitem> - </itemizedlist> - - <para>A description of these can be found via WWW as: - - <ulink - URL="http://gnn.com/gnn/bus/ora/category/bsd.html">4.4BSD - books description</ulink>. Due to poor sales, however, these - manuals may be hard to get a hold of.</para> - - <para>For a more in-depth look at the 4.4BSD kernel - organization, you can't go wrong with:</para> - - <para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, - and John Quarterman.<!-- <br> --></para> - - <para><emphasis>The Design and Implementation of the 4.4BSD - Operating System</emphasis>. Reading, Mass. : - Addison-Wesley, 1996.<!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/0-201-54979-4">ISBN</ulink> - 0-201-54979-4<!-- <br> --></para> - - <para>A good book on system administration is:</para> - - <para>Evi Nemeth, Garth Snyder, Scott Seebass & Trent R. - Hein,<!-- <br> --> - <quote>Unix System Administration Handbook</quote>, Prentice-Hall, - 1995<!-- <br> --> - <ulink - URL="http://www.amazon.com/exec/obidos/ASIN/0-13-151051-7">ISBN</ulink>: - 0-13-151051-7<!-- <br> --></para> - - <para> - <note> - <para>Make sure you get the second edition, with a red - cover, instead of the first edition.</para> - </note></para> - - <para>This book covers the basics, as well as TCP/IP, DNS, NFS, - SLIP/PPP, sendmail, INN/NNTP, printing, etc.. It's expensive - (approx. US$45-$55), but worth it. It also includes - a CDROM with the sources for various tools; most of these, - however, are also on the FreeBSD 2.2.6R CDROM (and the FreeBSD - CDROM often has newer versions).</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="access-pr"> - <para>How do I access your Problem Report database?</para> - </question> - - <answer> - <para>The Problem Report database of all user change requests - may be queried (or submitted to) by using our web-based PR - <ulink - URL="http://www.FreeBSD.org/send-pr.html">submission</ulink> - and <ulink - URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - query</ulink> - interfaces. The <command>send-pr(1)</command> command can - also be used to submit problem reports and change requests via - electronic mail.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="doc-formats"> - <para>Is the documentation available in other formats, such as plain - text (ASCII), or Postscript?</para> - </question> - - <answer> - <para>Yes. The documentation is available in a number of different - formats and compression schemes on the FreeBSD FTP site, in the - <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink> directory.</para> - - <para>The documentation is categorised in a number of different - ways. These include:</para> - - <itemizedlist> - <listitem> - <para>The document's name, such as <literal>faq</literal>, or - <literal>handbook</literal>.</para> - </listitem> - - <listitem> - <para>The document's language and encoding. These are based on - the locale names you will find under - <filename>/usr/share/locale</filename> on your FreeBSD - system. The current languages and encodings that we have for - documentation are as follows:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Name</entry> - - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>en_US.ISO_8859-1</literal></entry> - - <entry>US English</entry> - </row> - - <row> - <entry><literal>es_ES.ISO_8859-1</literal></entry> - - <entry>Spanish</entry> - </row> - - <row> - <entry><literal>fr_FR.ISO_8859-1</literal></entry> - - <entry>French</entry> - </row> - - <row> - <entry><literal>ja_JP.eucJP</literal></entry> - - <entry>Japanese (EUC encoding)</entry> - </row> - - <row> - <entry><literal>ru_RU.KOI8-R</literal></entry> - - <entry>Russian (KOI8-R encoding)</entry> - </row> - - <row> - <entry><literal>zh_TW.Big5</literal></entry> - - <entry>Chinese (Big5 encoding)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>Some documents may not be available in all - languages.</para> - </note> - </listitem> - - <listitem> - <para>The document's format. We produce the documentation in a - number of different output formats to try and make it as - flexible as possible. The current formats are;</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Format</entry> - - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>html-split</literal></entry> - - <entry>A collection of small, linked, HTML - files.</entry> - </row> - - <row> - <entry><literal>html</literal></entry> - - <entry>One large HTML file containing the entire - document</entry> - </row> - - <row> - <entry><literal>pdb</literal></entry> - - <entry>Palm Pilot database format, for use with the - <ulink URL="http://www.iSilo.com/">iSilo</ulink> - reader.</entry> - </row> - - <row> - <entry><literal>pdf</literal></entry> - - <entry>Adobe's Portable Document Format</entry> - </row> - - <row> - <entry><literal>ps</literal></entry> - - <entry>Postscript</entry> - </row> - - <row> - <entry><literal>rtf</literal></entry> - - <entry>Microsoft's Rich Text Format<footnote> - <para>Page numbers are not automatically updated - when loading this format in to Word. Press - <keycap>CTRL</keycap>+<keycap>A</keycap>, - <keycap>CTRL</keycap>+<keycap>END</keycap>, - <keycap>F9</keycap> after loading the document, to - update the page numbers.</para> - </footnote> - </entry> - </row> - - <row> - <entry><literal>txt</literal></entry> - - <entry>Plain text</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - - <listitem> - <para>The compression and packaging scheme. There are three of - these currently in use.</para> - - <orderedlist> - <listitem> - <para>Where the format is <literal>html-split</literal>, the - files are bundled up using &man.tar.1;. The resulting - <filename>.tar</filename> file is then compressed using - the compression schemes detailed in the next point.</para> - </listitem> - - <listitem> - <para>All the other formats generate one file, called - <filename>book.<replaceable>format</replaceable></filename> - (i.e., <filename>book.pdb</filename>, - <filename>book.html</filename>, and so on).</para> - - <para>These files are then compressed using three - compression schemes.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Scheme</entry> - - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>zip</literal></entry> - - <entry>The Zip format. If you want to uncompress - this on FreeBSD you will need to install the - <filename>archivers/unzip</filename> port - first.</entry> - </row> - - <row> - <entry><literal>gz</literal></entry> - - <entry>The GNU Zip format. Use &man.gunzip.1; to - uncompress these files, which is part of - FreeBSD.</entry> - </row> - - <row> - <entry><literal>bz2</literal></entry> - - <entry>The BZip2 format. Less widespread than the - others, but generally gives smaller files. - Install the <filename>archivers/bzip2</filename> - port to uncompress these files.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>So the Postscript version of the Handbook, compressed - using BZip2 will be stored in a file called - <filename>book.sgml.bz2</filename> in the - <filename>handbook/</filename> directory.</para> - </listitem> - - <listitem> - <para>The formatted documentation is also available as a - FreeBSD package, of which more later.</para> - </listitem> - </orderedlist> - </listitem> - </itemizedlist> - - <para>After choosing the format and compression mechanism that you - want to download, you must then decide whether or not you want to - download the document as a FreeBSD - <emphasis>package</emphasis>.</para> - - <para>The advantage of downloading and installing the package is - that the documentation can then be managed using the normal - FreeBSD package management comments, such as &man.pkg.add.1; and - &man.pkg.delete.1;.</para> - - <para>If you decide to download and install the package then you - must know the filename to download. The documentation-as-packages - files are stored in a directory called - <filename>packages</filename>. Each package file looks like - <filename><replaceable>document-name</replaceable>.<replaceable>lang</replaceable>.<replaceable>encoding</replaceable>.<replaceable>format</replaceable>.tgz</filename>.</para> - - <para>For example, the FAQ, in English, formatted as PDF, is in the - package called - <filename>faq.en_US.ISO_8859-1.pdf.tgz</filename>.</para> - - <para>Knowing this, you can use the following command to install the - English PDF FAQ package.</para> - - <screen>&prompt.root; <userinput>pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO_8859-1.pdf.tgz</userinput></screen> - - <para>Having done that, you can use &man.pkg.info.1; to determine - where the file has been installed.</para> - - <screen>&prompt.root; <userinput>pkg_info -f faq.en_US.ISO_8859-1.pdf</userinput> -Information for faq.en_US.ISO_8859-1.pdf: - -Packing list: - Package name: faq.en_US.ISO_8859-1.pdf - CWD to /usr/share/doc/en_US.ISO_8859-1/books/faq -File: book.pdf - CWD to . -File: +COMMENT (ignored) -File: +DESC (ignored)</screen> - - <para>As you can see, <filename>book.pdf</filename> will have been - installed in to - <filename>/usr/share/doc/en_US.ISO_8859-1/books/faq</filename>. - </para> - - <para>If you do not want to use the packages then you will have to - download the compressed files yourself, uncompress them, and then - copy the appropriate documents in to place.</para> - - <para>For example, the split HTML version of the FAQ, compressed - using &man.gzip.1;, can be found in the - <filename>en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</filename> - file. To download and uncompress that file you would have to do - this.</para> - - <screen>&prompt.root; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</userinput> -&prompt.root; <userinput>gzip -d book.html-split.tar.gz</userinput> -&prompt.root; <userinput>tar xvf book.html-split.tar</userinput></screen> - - <para>You will be left with a collection of - <filename>.html</filename> files. The main one is called - <filename>index.html</filename>, which will contain the table of - contents, introductory material, and links to the other parts of - the document. You can then copy or move these to their final - location as necessary.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="become-web-mirror"> - <para>I'd like to become a FreeBSD Web mirror!</para> - </question> - - <answer> - <para>Certainly! There are multiple ways to mirror the Web - pages.</para> - - - - <itemizedlist> - <listitem> - <para>Using <application>CVSup</application>: - You can retrieve the formatted files - using <application>CVSup</application>, and connecting to - a <application>CVSup</application> server.</para> - - <para>To retrieve the webpages, please look at the example - supfile, which can be found in - <filename>/usr/share/examples/cvsup/www-supfile</filename>. - </para> - - </listitem> - - <listitem> - <para>Using ftp mirror: You can download the FTP server's - copy of the web site sources using your favorite ftp mirror - tool. Keep in mind that you have to build these sources before - publishing them. Simply start at - ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="translation"> - <para>I'd like to translate the documentation into - Friesian.</para> - </question> - - <answer> - <para>Well, we can't pay, but we might arrange a free CD or - T-shirt and a Contributor's Handbook entry if you submit a - translation of the documentation. Before you begin translating - please contact the <emphasis>freebsd-doc</emphasis> mailing - list at <email>freebsd-doc@FreeBSD.org</email>; you may find - somebody to help with the translation effort. You may also find - out there is already a team translating the docs into your - chosen language, who surely wouldn't turn down your help. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="other-info-sources"> - <para>Other sources of information.</para> - </question> - - <answer> - <para>The following newsgroups contain pertinent discussion for - FreeBSD users:</para> - - - - <itemizedlist> - <listitem> - <para><ulink - URL="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink> - (moderated)</para> - </listitem> - - <listitem> - <para><ulink - URL="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="news:comp.unix.bsd.misc">comp.unix.bsd.misc</ulink></para> - </listitem> - </itemizedlist> - - <para>Web resources:</para> - - - - <itemizedlist> - <listitem> - <para>The <ulink - URL="http://www.FreeBSD.org/">FreeBSD Home Page</ulink>.</para> - </listitem> - - <listitem> - <para><anchor id="pao">If you have a laptop, be sure and see - <ulink URL="http://www.jp.FreeBSD.org/PAO/">Tatsumi - Hosokawa's Mobile Computing page</ulink> in Japan.</para> - </listitem> - - <listitem> - <para><anchor id="smp">For information on SMP (Symmetric - MultiProcessing), please see the <ulink - URL="http://people.FreeBSD.org/~fsmp/SMP/SMP.html">SMP support page</ulink>.</para> - </listitem> - - <listitem> - <para><anchor id="multimedia">For information on FreeBSD - multimedia applications, please see the <ulink - URL="http://people.FreeBSD.org/~faulkner/multimedia/mm.html">multimedia</ulink> - page. If you're interested specifically in the <ulink - URL="http://people.FreeBSD.org/~ahasty/Bt848.html">Bt848</ulink> - video capture chip, then follow that link.</para> - </listitem> - </itemizedlist> - - <para>The FreeBSD handbook also has a fairly complete <ulink - URL="../handbook/bibliography.html">bibliography</ulink> - section which is worth reading if you're looking for actual - books to buy.</para> - </answer> - </qandaentry> - </qandaset> - </preface> - - <chapter - id="install"> - <title>Installation</title> - - - <qandaset> - <qandaentry> - <question id="floppy-download"> - <para>Which file do I download to get FreeBSD?</para> - </question> - - <answer> - <para>Prior to release 3.1, you only needed one floppy image to - install FreeBSD, namely <filename>floppies/boot.flp</filename>. - However, since release 3.1 the Project has added base support - for a wide variety of hardware which needed more space, and - thus for 3.x and 4.x we now use two floppy images, namely - <filename>floppies/kernel.flp</filename> and - <filename>floppies/mfsroot.flp</filename>. These images need to - be copied onto floppies by tools like - <command>fdimage</command> or &man.dd.1;.</para> - - <para>If you need to download the distributions yourself (for a - DOS filesystem install, for instance), below are some - recommendations for distributions to grab:</para> - - - <itemizedlist> - <listitem> - <para> bin/<!-- <br> --></para> - </listitem> - - <listitem> - <para> manpages/<!-- <br> --></para> - </listitem> - - <listitem> - <para> compat*/<!-- <br> --></para> - </listitem> - - <listitem> - <para> doc/ <!-- <br> --></para> - </listitem> - - <listitem> - <para> src/ssys.* <!-- <br> --></para> - </listitem> - </itemizedlist> - - - <para>Full instructions on this procedure and a little bit more - about installation issues in general can be found in the - <ulink URL="../handbook/install.html">Handbook entry on - installing FreeBSD.</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="floppy-image-too-large"> - <para>Help! The boot floppy image will not fit on a single - floppy!</para> - </question> - - <answer> - <para>A 3.5 inch (1.44MB) floppy can accomodate 1474560 bytes - of data. The boot image is exactly 1474560 bytes in size.</para> - - <para>Common mistakes when preparing the boot floppy are:</para> - - <itemizedlist> - <listitem> - <para>Not downloading the floppy image in - <emphasis>binary</emphasis> mode when using - <acronym>FTP</acronym>.</para> - - - <para>Some FTP clients default their transfer mode to - <emphasis>ascii</emphasis> and attempt to change any - end-of-line characters received to match the conventions - used by the client's system. This will almost invariably - corrupt the boot image. Check the size of the downloaded - boot image: if it is not <emphasis>exactly</emphasis> that - on the server, then the download process is suspect.</para> - - <para>To workaround: type <emphasis>binary</emphasis> at the - FTP command prompt after getting connected to the server - and before starting the download of the image.</para> - </listitem> - - <listitem> - <para>Using the DOS <command>copy</command> command (or - equivalent GUI tool) to transfer the boot image to - floppy.</para> - - <para>Programs like <command>copy</command> will not work as - the boot image has been created to be booted into directly. - The image has the complete content of the floppy, track for - track, and is not meant to be placed on the floppy as a - regular file. You have to transfer it to the floppy - <quote>raw</quote>, using the low-level tools (e.g. - <command>fdimage</command> or <command>rawrite</command>) - described in the <ulink - URL="../handbook/install.html">installation guide to - FreeBSD</ulink>.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="install-instructions-location"> - <para>Where are the instructions for installing FreeBSD?</para> - </question> - - <answer> - <para>Installation instructions can be found in the - <ulink URL="../handbook/install.html">Handbook entry on installing FreeBSD.</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="need-to-run"> - <para>What do I need in order to run FreeBSD?</para> - </question> - - <answer> - <para>You'll need a 386 or better PC, with 5 MB or more of RAM - and at least 60 MB of hard disk space. It can run with a low - end MDA graphics card but to run X11R6, a VGA or better video - card is needed.</para> - - <para>See also the section on - <xref linkend="hardware" remap="Hardware compatibility"></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="four-meg-ram-install"> - <para>I have only 4 MB of RAM. Can I install FreeBSD?</para> - </question> - - <answer> - <para>FreeBSD 2.1.7 was the last version of FreeBSD that could - be installed on a 4MB system. Newer versions of FreeBSD, like - 2.2, need at least 5MB to install on a new system.</para> - - <para>All versions of FreeBSD, including 3.0, will - <emphasis>run</emphasis> in 4MB of RAM, they just can't run the - installation program in 4MB. You can add extra memory for the - install process, if you like, and then after the system is up - and running, go back to 4MB. Or you could always just swap your - disk into a system which has >4MB, install onto it and then - swap it back.</para> - - <para>There are also situations in which FreeBSD 2.1.7 will not - install in 4 MB. To be exact: it does not install with 640 kB - base + 3 MB extended memory. If your motherboard can remap some - of the <quote>lost</quote> memory out of the 640kB to 1MB - region, then you may still be able to get FreeBSD 2.1.7 - up.</para> - - <para>Try to go into your BIOS setup and look for a - <quote>remap</quote> option. Enable it. You may also have to - disable ROM shadowing.</para> - - <para>It may be easier to get 4 more MB just for the install. - Build a custom kernel with only the options you need and then - get the 4MB out again.</para> - - <para>You may also install 2.0.5 and then upgrade your system to - 2.1.7 with the <quote>upgrade</quote> option of the 2.1.7 - installation program.</para> - - <para>After the installation, if you build a custom kernel, it - will run in 4 MB. Someone has even succeeded in booting with 2 - MB (the system was almost unusable though :-))</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="custom-boot-floppy"> - <para>How can I make my own custom install floppy?</para> - </question> - - <answer> - <para>Currently there's no way to <emphasis>just</emphasis> - make a custom install floppy. You have to cut a whole new - release, which will include your install floppy.</para> - - <para>To make a custom release, follow the instructions - <link linkend="custrel">here</link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="multiboot"> - <para>Can I have more than one operating system on my PC?</para> - </question> - - <answer> - <para>Have a look at - <ulink URL="http://www.FreeBSD.org/tutorials/multi-os/"> - The multi-OS page.</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="windows-coexist"> - <para>Can Windows 95/98 co-exist with FreeBSD?</para> - </question> - - <answer> - <para>Install Windows 95/98 first, after that FreeBSD. - FreeBSD's boot manager will then manage to boot Win95/98 and - FreeBSD. If you install Windows 95/98 second, it will boorishly - overwrite your boot manager without even asking. If that - happens, see the next section.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="win95-damaged-boot-manager"> - <para>Windows 95/98 killed my boot manager! - How do I get it back?</para> - </question> - - <answer> - <para>You can reinstall the boot manager FreeBSD comes with in - one of three ways:</para> - - <itemizedlist> - <listitem> - <para>Running DOS, go into the tools/ directory of your - FreeBSD distribution and look for - <filename>bootinst.exe</filename>. You run it like - so:</para> - - <screen><prompt>...\TOOLS></prompt> <userinput>bootinst.exe boot.bin</userinput></screen> - - <para></para> - - <para>and the boot manager will be reinstalled.</para> - - <para></para> - </listitem> - - <listitem> - <para>Boot the FreeBSD boot floppy again and go to the - Custom installation menu item. Choose Partition. Select the - drive which used to contain your boot manager (likely the - first one) and when you come to the partition editor for - it, as the very first thing (e.g. do not make any changes) - select (W)rite. This will ask for confirmation, say yes, - and when you get the Boot Manager selection prompt, be - sure to select <literal>Boot Manager</literal>. This will - re-write the boot manager to disk. Now quit out of the - installation menu and reboot off the hard disk as - normal.</para> - </listitem> - - <listitem> - <para>Boot the FreeBSD boot floppy (or CD-ROM) and choose the - <quote>Fixit</quote> menu item. Select either the Fixit - floppy or CD-ROM #2 (the <quote>live</quote> file system - option) as appropriate and enter the fixit shell. Then - execute the following command:</para> - - <screen><prompt>Fixit#</prompt> <userinput>fdisk -B -b /boot/boot0 <replaceable>bootdevice</replaceable></userinput></screen> - - <para>substituting <replaceable>bootdevice</replaceable> for - your real - boot device such as <devicename>ad0</devicename> (first IDE - disk), <devicename>ad4</devicename> (first IDE disk on - auxiliary controller), <devicename>da0</devicename> (first - SCSI disk), etc.</para> - </listitem> - </itemizedlist> - - </answer> - </qandaentry> - - <qandaentry> - <question id="install-bad-blocks"> - <para>Can I install on a disk with bad blocks?</para> - </question> - - <answer> - <para>Prior to 3.0, FreeBSD included a utility known as - <command>bad144</command>, which automatically remapped bad - blocks. Because modern IDE drives perform this function - themselves, <command>bad144</command> has been removed from the - FreeBSD source tree. If you wish to install FreeBSD 3.0 or - later, we strongly suggest you purchase a newer disk drive. If - you do not wish to do this, you must run FreeBSD 2.x.</para> - <para>If you are seeing bad block errors with a modern IDE - drive, chances are the drive is going to die very soon (the - drive's internal remapping functions are no longer sufficient - to fix the bad blocks, which means the disk is heavily - corrupted); we suggest you by a new hard drive.</para> - - <para>If you have a SCSI drive with bad blocks, see - <link linkend="awre">this answer</link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="boot-floppy-strangeness"> - <para>Strange things happen when I boot the install floppy!</para> - </question> - - <answer> - <para>If you're seeing things like the machine grinding to a halt - or spontaneously rebooting when you try to boot the install - floppy, here are three questions to ask yourself:-</para> - - <orderedlist> - <listitem> - <para>Did you use a new, freshly-formatted, error-free floppy - (preferably a brand-new one straight out of the box, as - opposed to the magazine coverdisk that's been lying under - the bed for the last three years)?</para> - </listitem> - - <listitem> - <para>Did you download the floppy image in binary (or image) - mode? (don't be embarrassed, even the best of us have - accidentally downloaded a binary file in ASCII mode at - least once!)</para> - </listitem> - - <listitem> - <para>If you're using Windows95 or Win98 did you run - <command>fdimage</command> or <command>rawrite</command> in - pure DOS mode? These OS's can interfere with programs that - write directly to hardware, which the disk creation program - does; even running it inside a DOS shell in the GUI can - cause this problem.</para> - </listitem> - </orderedlist> - - <para>There have also been reports of Netscape causing problems - when downloading the boot floppy, so it's probably best to use - a different FTP client if you can.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="no-install-cdrom"> - <para>I booted from my ATAPI CD-ROM, but the install program says no - CD-ROM is found. Where did it go?</para> - </question> - - <answer> - <para>The usual cause of this problem is a mis-configured CD-ROM - drive. Many PCs now ship with the CD-ROM as the slave device on - the secondary IDE controller, with no master device on that - controller. This is illegal according to the ATAPI specification, - but Windows plays fast and loose with the specification, and the - BIOS ignores it when booting. This is why the BIOS was able to - see the CD-ROM to boot from it, but why FreeBSD can not see it to - complete the install.</para> - - <para>Reconfigure your system so that the CD-ROM is either the - master device on the IDE controller it is attached to, or make - sure that it is the slave on an IDE controller that also has a - master device.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="cannot-install-tape"> - <para>Help! I can't install from tape!</para> - </question> - - <answer> - <para>If you are installing 2.1.7R from tape, you must create - the tape using a tar blocksize of 10 (5120 bytes). The default - tar blocksize is 20 (10240 bytes), and tapes created using this - default size cannot be used to install 2.1.7R; with these - tapes, you will get an error that complains about the record - size being too big.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="parallel-connect"> - <para>Connect two FreeBSD boxes over a parallel line (PLIP)</para> - </question> - - <answer> - <para>Get a laplink cable. Make sure both computer have a kernel - with lpt driver support.</para> - - <screen>&prompt.root; <userinput>dmesg | grep lp</userinput> -lpt0 at 0x378-0x37f irq 7 on isa -lpt0: Interrupt-driven -lp0: TCP/IP capable interface</screen> - - <para>Plug in the laplink cable into the parallel interface.</para> - - <para>Configure the network interface parameters for lp0 on both - sites as root. For example, if you want connect the host max - with moritz</para> - - <programlisting> max <-----> moritz -IP Address 10.0.0.1 10.0.0.2</programlisting> - - <para>on max start</para> - - <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen> - - <para>on moritz start</para> - - <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen> - - - <para>Thats all! Please read also the manpages - &man.lp.4; and &man.lpt.4; .</para> - - <para>You should also add the hosts to - <filename>/etc/hosts</filename>.</para> - - <programlisting>127.0.0.1 localhost.my.domain localhost -10.0.0.1 max.my.domain max -10.0.0.2 moritz.my.domain</programlisting> - - - <para>To check if it works do:</para> - - <para>on max:</para> - - - <screen>&prompt.root; <userinput>ifconfig lp</userinput>0 -lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 - inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000 -&prompt.root; <userinput>netstat -r</userinput> -Routing tables - -Internet: -Destination Gateway Flags Refs Use Netif Expire -moritz max UH 4 127592 lp0 -&prompt.root; <userinput>ping -c 4 moritz</userinput> -PING moritz (10.0.0.2): 56 data bytes -64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms -64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms -64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms -64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms - ---- moritz ping statistics --- -4 packets transmitted, 4 packets received, 0% packet loss -round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen> - - - </answer> - </qandaentry> - - <qandaentry> - <question id="install-PLIP"> - <para>Can I install on my laptop over PLIP (Parallel Line - IP)?</para> - </question> - - <answer> - <para>Connect the two computers using a Laplink parallel cable - to use this feature:</para> - - <table> - <title>Wiring a parallel cable for networking</title> - - <tgroup cols="5"> - <thead> - <row> - <entry>A-name</entry> - - <entry>A-End</entry> - - <entry>B-End</entry> - - <entry>Descr.</entry> - - <entry>Post/Bit</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literallayout>DATA0 --ERROR</literallayout></entry> - - <entry><literallayout>2 -15</literallayout></entry> - - <entry><literallayout>15 -2</literallayout></entry> - - <entry>Data</entry> - - <entry><literallayout>0/0x01 -1/0x08</literallayout></entry> - </row> - - <row> - <entry><literallayout>DATA1 -+SLCT</literallayout></entry> - - <entry><literallayout>3 -13</literallayout></entry> - - <entry><literallayout>13 -3</literallayout></entry> - - <entry>Data</entry> - - <entry><literallayout>0/0x02 -1/0x10</literallayout></entry> - </row> - - <row> - <entry><literallayout>DATA2 -+PE</literallayout></entry> - - <entry><literallayout>4 -12</literallayout></entry> - - <entry><literallayout>12 -4</literallayout></entry> - - <entry>Data</entry> - - <entry><literallayout>0/0x04 -1/0x20</literallayout></entry> - </row> - - <row> - <entry><literallayout>DATA3 --ACK</literallayout></entry> - - <entry><literallayout>5 -10</literallayout></entry> - - <entry><literallayout>10 -5</literallayout></entry> - - <entry>Strobe</entry> - - <entry><literallayout>0/0x08 -1/0x40</literallayout></entry> - </row> - - <row> - <entry><literallayout>DATA4 -BUSY</literallayout></entry> - - <entry><literallayout>6 -11</literallayout></entry> - - <entry><literallayout>11 -6</literallayout></entry> - - <entry>Data</entry> - - <entry><literallayout>0/0x10 -1/0x80</literallayout></entry> - </row> - - <row> - <entry>GND</entry> - - <entry>18-25</entry> - - <entry>18-25</entry> - - <entry>GND</entry> - - <entry>-</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See also <link linkend="pao">this note</link> on the - Mobile Computing page.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="geometry"> - <para>Which geometry should I use for a disk drive?</para> - </question> - - <answer> - <para>(By the <quote>geometry</quote> of a disk, we mean the - number of cylinders, heads and sectors/track on a disk - I'll - refer to this as C/H/S for convenience. This is how the PC's - BIOS works out which area on a disk to read/write from).</para> - - <para>This seems to cause a lot of confusion for some reason. - First of all, the <emphasis>physical</emphasis> geometry of a - SCSI drive is totally irrelevant, as FreeBSD works in term of - disk blocks. In fact, there is no such thing as - <emphasis>the</emphasis> physical geometry, as the sector - density varies across the disk - what manufacturers claim is - the <emphasis>quote</emphasis> physical geometry is usually the - geometry that they've worked out results in the least wasted - space. For IDE disks, FreeBSD does work in terms of C/H/S, but - all modern drives will convert this into block references - internally as well.</para> - - <para>All that matters is the <emphasis>logical</emphasis> - geometry - the answer that the BIOS gets when it asks - <quote>what is your geometry?</quote> and then uses to access - the disk. As FreeBSD uses the BIOS when booting, it's very - important to get this right. In particular, if you have more - than one operating system on a disk, they must all agree on the - geometry, otherwise you will have serious problems - booting!</para> - - <para>For SCSI disks, the geometry to use depends on whether - extended translation support is turned on in your controller - (this is often referred to as <quote>support for DOS disks - >1GB</quote> or something similar). If it's turned off, then - use <replaceable>N</replaceable> cylinders, 64 heads and 32 - sectors/track, where <replaceable>N</replaceable> is the - capacity of the disk in MB. For example, a 2GB disk should - pretend to have 2048 cylinders, 64 heads and 32 - sectors/track.</para> - - <para>If it <emphasis>is</emphasis> turned on (it's often supplied - this way to get around certain limitations in MSDOS) and the - disk capacity is more than 1GB, use M cylinders, 63 sectors per - track (*not* 64), and 255 heads, where 'M' is the disk capacity - in MB divided by 7.844238 (!). So our example 2GB drive would - have 261 cylinders, 63 sectors per track and 255 heads.</para> - - <para>If you are not sure about this, or FreeBSD fails to detect - the geometry correctly during installation, the simplest way - around this is usually to create a small DOS partition on the - disk. The correct geometry should then be detected (and you can - always remove the DOS partition in the partition editor if you - don't want to keep it, or leave it around for programming - network cards and the like).</para> - - <para>Alternatively, there is a freely available utility - distributed with FreeBSD called <filename>pfdisk.exe</filename> - (located in the <filename>tools</filename> subdirectory on the - FreeBSD CDROM or on the various FreeBSD ftp sites) which can be - used to work out what geometry the other operating systems on - the disk are using. You can then enter this geometry in the - partition editor.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="disk-divide-restrictions"> - <para>Any restrictions on how I divide the disk up?</para> - </question> - - <answer> - <para>Yes. You must make sure that your root partition is below - 1024 - cylinders so the BIOS can boot the kernel from it. (Note that - this is a limitation in the PC's BIOS, not FreeBSD).</para> - - <para>For a SCSI drive, this will normally imply that the root - partition will be in the first 1024MB (or in the first 4096MB - if extended translation is turned on - see previous question). - For IDE, the corresponding figure is 504MB.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="disk-manager"> - <para>What about disk managers? Or, I have a large drive!</para> - </question> - - <answer> - <para>FreeBSD recognizes the Ontrack Disk Manager and makes - allowances for it. Other disk managers are not supported.</para> - - <para>If you just want to use the disk with FreeBSD you don't - need a disk manager. Just configure the disk for as much space - as the BIOS can deal with (usually 504 megabytes), and FreeBSD - should figure out how much space you really have. If you're - using an old disk with an MFM controller, you may need to - explicitly tell FreeBSD how many cylinders to use.</para> - - <para>If you want to use the disk with FreeBSD and another - operating system, you may be able to do without a disk manager: - just make sure the the FreeBSD boot partition and the slice for - the other operating system are in the first 1024 cylinders. If - you're reasonably careful, a 20 megabyte boot partition should - be plenty.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="missing-os"> - <para>When I boot FreeBSD I get <literal>Missing Operating - System</literal></para> - </question> - - <answer> - <para>This is classically a case of FreeBSD and DOS or some other - OS conflicting over their ideas of disk <link - linkend="geometry">geometry</link>. You will have to reinstall - FreeBSD, but obeying the instructions given above will almost - always get you going.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="stop-at-boot-manager"> - <para>I can't get past the boot manager's <literal>F?</literal> - prompt.</para> - </question> - - <answer> - <para>This is another symptom of the problem described in the - preceding question. Your BIOS geometry and FreeBSD geometry - settings do not agree! If your controller or BIOS supports - cylinder translation (often marked as <literal>>1GB drive - support</literal>), try toggling its setting and reinstalling - FreeBSD.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="need-complete-sources"> - <para>Do I need to install the complete sources?</para> - </question> - - <answer> - <para>In general, no. However, we would strongly recommend that - you install, at a minimum, the <literal>base</literal> source - kit, which includes several of the files mentioned here, and - the <literal>sys</literal> (kernel) source kit, which includes - sources for the kernel. There is nothing in the system which - requires the presence of the sources to operate, however, - except for the kernel-configuration program &man.config.8;. - With the exception of the kernel sources, our build structure - is set up so that you can read-only mount the sources from - elsewhere via NFS and still be able to make new binaries. - (Because of the kernel-source restriction, we recommend that - you not mount this on <filename>/usr/src</filename> directly, - but rather in some other location with appropriate symbolic - links to duplicate the top-level structure of the source - tree.)</para> - - <para>Having the sources on-line and knowing how to build a - system with them will make it much easier for you to upgrade - to future releases of FreeBSD.</para> - - <para>To actually select a subset of the sources, use the Custom - menu item when you are in the Distributions menu of the - system installation tool.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="need-kernel"> - <para>Do I need to build a kernel?</para> - </question> - - <answer> - <para>Building a new kernel was originally pretty much a required - step in a FreeBSD installation, but more recent releases have - benefited from the introduction of a much friendlier kernel - configuration tool. When at the FreeBSD boot prompt (boot:), - use the <option>-c</option> flag and you will be dropped into a - visual configuration screen which allows you to configure the - kernel's settings for most common ISA cards.</para> - - <para>It's still recommended that you eventually build a new - kernel containing just the drivers that you need, just to save a - bit of RAM, but it's no longer a strict requirement for most - systems.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="password-encryption"> - <para>Should I use DES passwords, or MD5, and how do I specify - which form my users receive?</para> - </question> - - <answer> - <para>The default password format on FreeBSD is to use - <emphasis>MD5</emphasis>-based passwords. These are believed to - be more secure than the traditional UNIX password format, which - used a scheme based on the <emphasis>DES</emphasis> algorithm. - DES passwords are still available if you need to share your - password file with legacy operating systems which still use the - less secure password format (they are available if you choose - to install the <quote>crypto</quote> distribution in - sysinstall, or by installing the crypto sources if building - from source). Which password format to use for new passwords is - controlled by the <quote>passwd_format</quote> login capability - in <filename>/etc/login.conf</filename>, which takes values of - either <quote>des</quote> (if available) or <quote>md5</quote>. - See the login.conf(5) manpage for more information about login - capabilities.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="boot-floppy-hangs"> - <para>The boot floppy starts but hangs at the - <literal>Probing Devices...</literal> screen.</para> - </question> - - <answer> - - <para>If you have a IDE Zip or Jaz drive installed, remove it - and try again. The boot floppy can get confused by the drives. - After the system is installed you can reconnect the drive. - Hopefully this will be fixed in a later release.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="panic-on-install-reboot"> - <para>I get a <literal>panic: cant mount root</literal> - error when rebooting the system after installation.</para> - </question> - - <answer> - <para>This error comes from confusion between the boot block's - and the kernel's understanding of the disk devices. The error - usually manifests on two-disk IDE systems, with the hard disks - arranged as the master or single device on separate IDE - controllers, with FreeBSD installed on the secondary IDE - controller. The boot blocks think the system is installed on - wd1 (the second BIOS disk) while the kernel assigns the first - disk on the secondary controller device wd2. After the device - probing, the kernel tries to mount what the boot blocks think - is the boot disk, wd1, while it is really wd2, and - fails.</para> - - <para>To fix the problem, do one of the following:</para> - - <para> - <orderedlist> - <listitem> - <para>For FreeBSD 3.3 and later, reboot the system and hit - <literal>Enter</literal> at the <literal>Booting kernel - in 10 seconds; hit [Enter] to interrupt</literal> prompt. - This will drop you into the boot loader.</para> - - <para>Then type - <literal> - set root_disk_unit="<replaceable>disk_number</replaceable>" - </literal>. <replaceable>disk_number</replaceable> - will be <literal>0</literal> if FreeBSD is installed on - the master drive on the first IDE controller, - <literal>1</literal> if it is installed on the slave on - the first IDE controller, <literal>2</literal> if it is - installed on the master of the second IDE controller, and - <emphasis>3</emphasis> if it is installed on the slave of - the second IDE controller.</para> - - <para>Then type <literal>boot</literal>, and your system - should boot correctly.</para> - - <para>To make this change permanent (ie so you don't have to - do this everytime you reboot or turn on your FreeBSD - machine), put the line <literal> - root_disk_unit="<replaceable>disk_number</replaceable>" - </literal> in <filename>/boot/loader.conf.local - </filename>.</para> - </listitem> - - <listitem> - <para>If using FreeBSD 3.2 or earlier, at the Boot: prompt, - enter <literal>1:wd(2,a)kernel</literal> and press Enter. - If the system starts, then run the command - <command>echo "1:wd(2,a)kernel" > /boot.config</command> - to make it the default boot string.</para> - </listitem> - - <listitem> - <para>Move the FreeBSD disk onto the primary IDE controller, - so the hard disks are consecutive.</para> - </listitem> - - <listitem> - <para><ulink URL="../handbook/kernelconfig.html">Rebuild - your kernel,</ulink> modify the wd configuration lines to - read:</para> - - <programlisting>controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr -disk wd0 at wdc0 drive 0 -# disk wd1 at wdc0 drive 1 # comment out this line - -controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr -disk wd1 at wdc1 drive 0 # change from wd2 to wd1 -disk wd2 at wdc1 drive 1 # change from wd3 to wd2</programlisting> - - <para>Install the new kernel. If you moved your disks and - wish to restore the previous configuration, replace the - disks in the desired configuration and reboot. Your - system should boot successfully.</para> - </listitem> - </orderedlist> - </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="memory-limits"> - <para>What are the limits for memory?</para> - </question> - - <answer> - <para>For memory, the limit is 4 gigabytes. This configuration - has been tested, see <ulink - URL="ftp://ftp.cdrom.com/archive-info/configuration">wcarchive's - configuration</ulink> for more details. If you plan to install - this much memory into a machine, you need to be careful. You'll - probably want to use ECC memory and to reduce capacitive - loading use 9 chip memory modules vice 18 chip memory - modules.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ffs-limits"> - <para>What are the limits for ffs filesystems?</para> - </question> - - <answer> - <para>For ffs filesystems, the maximum theoretical limit is 8 - terabytes (2G blocks), or 16TB for the default block size of - 8K. In practice, there is a soft limit of 1 terabyte, but with - modifications filesystems with 4 terabytes are possible (and - exist).</para> - - <para>The maximum size of a single ffs file is approximately 1G - blocks (4TB) if the block size is 4K.</para> - - <table> - <title>Maximum file sizes</title> - - <tgroup cols="5"> - <thead> - <row> - <entry>fs block size</entry> - - <entry>2.2.7-stable</entry> - - <entry>3.0-current</entry> - - <entry>works</entry> - - <entry>should work</entry> - </row> - </thead> - - <tbody> - <row> - <entry>4K</entry> - - <entry>4T-1</entry> - - <entry>4T-1</entry> - - <entry>4T-1</entry> - - <entry>4+t</entry> - </row> - - <row> - <entry>8K</entry> - - <entry>32+G</entry> - - <entry>8T-1</entry> - - <entry>32+G</entry> - - <entry>32T-1</entry> - </row> - - <row> - <entry>16K</entry> - - <entry>128+G</entry> - - <entry>16T-1</entry> - - <entry>128+G</entry> - - <entry>32T-1</entry> - </row> - - <row> - <entry>32K</entry> - - <entry>512+G</entry> - - <entry>32T-1</entry> - - <entry>512+G</entry> - - <entry>64T-1</entry> - </row> - - <row> - <entry>64K</entry> - - <entry>2048+G</entry> - - <entry>64T-1</entry> - - <entry>2048+G</entry> - - <entry>128T-1</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>When the fs block size is 4K, triple indirect blocks work - and everything should be limited by the maximum fs block number - that can be represented using triple indirect blocks (approx. - 1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit - of 1G-1 on fs block numbers. The limit on fs block numbers - should be 2G-1. There are some bugs for fs block numbers near - 2G-1, but such block numbers are unreachable when the fs block - size is 4K.</para> - - <para>For block sizes of 8K and larger, everything should be - limited by the 2G-1 limit on fs block numbers, but is actually - limited by the 1G-1 limit on fs block numbers, except under - -STABLE triple indirect blocks are unreachable, so the limit is - the maxiumum fs block number that can be represented using - double indirect blocks (approx. (blocksize/4)^2 + - (blocksize/4)), and under -CURRENT exceeding this limit may - cause problems. Using the correct limit of 2G-1 blocks does - cause problems.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="tb-on-floppy"> - <para>How can I put 1TB files on my floppy?</para> - </question> - - <answer> - <para>I keep several virtual ones on floppies :-). The maxiumum - file size is not closely related to the maximum disk size. The - maximum disk size is 1TB. It is a feature that the file size - can be larger than the disk size.</para> - - <para>The following example creates a file of size 8T-1 using a - whole 32K of disk space (3 indirect blocks and 1 data block) on - a small root partition. The dd command requires a dd that works - with large files.</para> - - <screen>&prompt.user; <userinput>cat foo</userinput> -df . -dd if=/dev/zero of=z bs=1 seek=`echo 2^43 - 2 | bc` count=1 -ls -l z -du z -df . -&prompt.user; <userinput>sh foo</userinput> -Filesystem 1024-blocks Used Avail Capacity Mounted on -/dev/da0a 64479 27702 31619 47% / -1+0 records in -1+0 records out -1 bytes transferred in 0.000187 secs (5346 bytes/sec) --rw-r--r-- 1 bde bin 8796093022207 Sep 7 16:04 z -32 z -Filesystem 1024-blocks Used Avail Capacity Mounted on -/dev/da0a 64479 27734 31587 47% /</screen> - - <para>Bruce Evans, September 1998</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="archsw-readin-failed-error"> - <para>I compiled a new kernel and now I get the error message - <literal>archsw.readin.failed</literal> when booting.</para> - </question> - - <answer> - <para>You can boot by specifying the kernel directly at the second - stage, pressing any key when the | shows up before loader is - started. More specifically, you have upgraded the source for - your kernel, and installed a new kernel builtin from them - <emphasis>without making world</emphasis>. This is not - supported. Make world.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="upgrade-3x-4x"> - <para>How do I upgrade from 3.X -> 4.X?</para> - </question> - - <answer> - <para>We <emphasis>strongly</emphasis> recommend that you use - binary snapshots to do this. 4-STABLE snapshots are available at - <ulink - URL="ftp://releng4.FreeBSD.org/">releng4.FreeBSD.org</ulink>.</para> - - <para>If you wish to upgrade using source, please see the <ulink - URL="http://www.FreeBSD.org/handbook/cutting-edge.html">FreeBSD - Handbook</ulink> for more information.</para> - - <para><emphasis>Upgrading via source is never recommended for new - users, and upgading from 3.X -> 4.X is even less so; make sure - you have read the instructions carefully before attempting to - upgrade via source this!</emphasis></para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter - id="hardware"> - <title>Hardware compatibility </title> - - <qandaset> - <qandaentry> - <question id="supported-hard-drives"> - <para>What kind of hard drives does FreeBSD support?</para> - </question> - - <answer> - <para>FreeBSD supports EIDE and SCSI drives (with a compatible - controller; see the next section), and all drives using the - original <quote>Western Digital</quote> interface (MFM, RLL, - ESDI, and of course IDE). A few ESDI controllers that use - proprietary interfaces may not work: stick to WD1002/3/6/7 - interfaces and clones.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="supported-scsi-controllers"> - <para>Which SCSI controllers are supported?</para> - </question> - - <answer> - <para>See the complete list in the <ulink - URL="../handbook/install.html#INSTALL-HW">Handbook</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="supported-cdrom-drives"> - <para>Which CD-ROM drives are supported by FreeBSD?</para> - </question> - - <answer> - <para>Any SCSI drive connected to a supported controller is - supported.</para> - - <para>The following proprietary CD-ROM interfaces are also - supported:</para> - - <para> - <itemizedlist> - <listitem> - <para>Mitsumi LU002 (8bit), LU005 (16bit) and FX001D - (16bit 2x Speed).</para> - </listitem> - - <listitem> - <para>Sony CDU 31/33A<!-- <br> --></para> - </listitem> - - <listitem> - <para>Sound Blaster Non-SCSI CD-ROM<!-- <br> --></para> - </listitem> - - <listitem> - <para>Matsushita/Panasonic CD-ROM<!-- <br> --></para> - </listitem> - - <listitem> - <para>ATAPI compatible IDE CD-ROMs<!-- <br> --></para> - </listitem> - </itemizedlist> - </para> - - <para>All non-SCSI cards are known to be extremely slow compared - to SCSI drives, and some ATAPI CDROMs may not work.</para> - - <para>As of 2.2 the FreeBSD CDROM from BSDi supports - booting directly from the CD.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="zip-support"> - <para>Does FreeBSD support ZIP drives?</para> - </question> - - <answer> - <para>FreeBSD supports the SCSI ZIP drive out of the box, of - course. The ZIP drive can only be set to run at SCSI target IDs - 5 or 6, but if your SCSI host adapter's BIOS supports it you - can even boot from it. I don't know which host adapters let you - boot from targets other than 0 or 1... look at your docs (and - let me know if it works out for you).</para> - - <para>ATAPI (IDE) Zip drives are supported in FreeBSD 2.2.6 and - later releases.</para> - - <para>FreeBSD has contained support for Parallel Port Zip Drives - since version 3.0. If you are using a sufficiently up to date - version, then you should check that your kernel contains the - <devicename>scbus0</devicename>, <devicename>da0</devicename>, - <devicename>ppbus0</devicename>, and - <devicename>vp0</devicename> drivers (the GENERIC kernel - contains everything except <devicename>vp0</devicename>). With - all these drivers present, the Parallel Port drive should be - available as <filename>/dev/da0s4</filename>. Disks can be - mounted using <command>mount /dev/da0s4 /mnt</command> OR (for - dos disks) <command>mount_msdos /dev/da0s4 /mnt</command> as - appropriate.</para> - - <para>Also check out <link linkend="jaz">this note on removable - drives</link>, and <link linkend="disklabel">this note on - <quote>formatting</quote></link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="jaz-zip-removable-support"> - <para>Does FreeBSD support JAZ, EZ and other removable - drives?</para> - </question> - - <answer> - <para>Apart from the IDE version of the EZ drive, these are all - SCSI devices, so the should all look like SCSI disks to - FreeBSD, and the IDE EZ should look like an IDE drive.</para> - - <para><anchor id="jaz">I'm not sure how well FreeBSD supports - changing the media out while running. You will of course need - to dismount the drive before swapping media, and make sure that - any external units are powered on when you boot the system so - FreeBSD can see them.</para> - - <para>See <link linkend="disklabel">this note on - <quote>formatting</quote></link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="multiport-serial-support"> - <para>Which multi-port serial cards are supported by - FreeBSD?</para> - </question> - - <answer> - <para>There is a list of these in the <ulink - URL="../handbook/install-hw.html#INSTALL-MISC">Miscellaneous - devices</ulink> section of the handbook.</para> - - <para>Some unnamed clone cards have also been known to work, - especially those that claim to be AST compatible.</para> - - <para>Check the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sio(4)">sio</ulink> - man page to get more information on configuring such cards.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="usbkbd"> - <para>I have a USB keyboard. Does FreeBSD support it?</para> - </question> - - <answer> - <para>USB device support was added to FreeBSD 3.1. However, it - is still in preliminary state and may not always work as of - version 3.2. If you want to experiment with the USB keyboard - support, follow the procedure described below.</para> - - <orderedlist> - <listitem> - <para>Use FreeBSD 3.2 or later.</para> - </listitem> - - <listitem> - <para>Add the following lines to your kernel configuration - file, and rebuild the kernel.</para> - - <programlisting> -device uhci -device ohci -device usb -device ukbd -options KBD_INSTALL_CDEV</programlisting> - - <para>In versions of FreeBSD before 4.0, use this - instead:</para> - - <programlisting> -controller uhci0 -controller ohci0 -controller usb0 -controller ukbd0 -options KBD_INSTALL_CDEV</programlisting> - </listitem> - - <listitem> - <para>Go to the <filename>/dev</filename> directory and create - device nodes as follows:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV kbd0 kbd1</userinput></screen> - - </listitem> - - <listitem> - <para>Edit <filename>/etc/rc.conf</filename> and add the - following lines:</para> - - <programlisting> -usbd_enable="YES" -usbd_flags=""</programlisting> - - </listitem> - </orderedlist> - - <para>After the system is rebooted, the AT keyboard becomes - <filename>/dev/kbd0</filename> and the USB keyboard becomes - <filename>/dev/kbd1</filename>, if both are connected to the - system. If there is the USB keyboard only, it will be - <filename>/dev/ukbd0</filename>.</para> - - <para>If you want to use the USB keyboard in the console, you - have to explicitly tell the console driver to use the existence - of the USB keyboard. This can be done by running the following - command as a part of system initialization.</para> - - <screen>&prompt.root; <userinput>kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/null</userinput></screen> - - <para>Note that if the USB keyboard is the only keyboard, it is - accessed as <filename>/dev/kbd0</filename>, thus, the command - should look like:</para> - - <screen>&prompt.root; <userinput>kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null</userinput></screen> - - <para><filename>/etc/rc.i386</filename> is a good place to add the - above command.</para> - - <para>Once this is done, the USB keyboard should work in the X - environment as well without any special settings.</para> - - <para>Hot-plugging and unplugging of the USB keyboard may not - work quite right yet. It is a good idea to connect the keyboard - before you start the system and leave it connected until the - system is shutdown to avoid troubles.</para> - - <para>See the &man.ukbd.4; man page for more information.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="busmouse"> - <para>I have an unusual bus mouse. How do I set it up?</para> - </question> - - <answer> - <para>FreeBSD supports the bus mouse and the InPort bus mouse - from such manufactures as Microsoft, Logitech and ATI. The bus - device driver is compiled in the GENERIC kernel by default in - FreeBSD versions 2.X, but not included in version 3.0 or later. - If you are building a custom kernel with the bus mouse driver, - make sure to add the following line to the kernel config - file</para> - - <para>In FreeBSD 3.0 or before, add:</para> - - <programlisting>device mse0 at isa? port 0x23c tty irq5 vector mseintr</programlisting> - - <para>In FreeBSD 3.X, the line should be:</para> - - <programlisting>device mse0 at isa? port 0x23c tty irq5</programlisting> - - <para>And in FreeBSD 4.X and later, the line should read:</para> - - <programlisting>device mse0 at isa? port 0x23c irq5</programlisting> - - <para>Bus mice usually comes with dedicated interface cards. - These cards may allow you to set the port address and the IRQ - number other than shown above. Refer to the manual of your - mouse and the &man.mse.4; man page for more information.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ps2mouse"> - <para>How do I use my PS/2 (<quote>mouse port</quote> or - <quote>keyboard</quote>) mouse?</para> - </question> - - <answer> - - <para>If you're running a post-2.2.5 version of FreeBSD, the - necessary driver, <devicename>psm</devicename>, is included and - enabled in the kernel. The kernel should detect your PS/2 mouse - at boot time.</para> - - <para>If you're running a previous but relatively recent version - of FreeBSD (2.1.x or better) then you can simply enable it in - the kernel configuration menu at installation time, otherwise - later with <option>-c</option> at the <command>boot:</command> - prompt. It is disabled by default, so you will need to enable - it explicitly.</para> - - <para>If you're running an older version of FreeBSD then you'll - have to add the following lines to your kernel configuration - file and compile a new kernel.</para> - - <para>In FreeBSD 3.0 or earlier, the line should be:</para> - - <programlisting>device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr</programlisting> - - <para>In FreeBSD 3.1 or later, the line should be:</para> - - <programlisting>device psm0 at isa? tty irq 12</programlisting> - - <para>In FreeBSD 4.0 or later, the line should be:</para> - - <programlisting>device psm0 at atkbdc? irq 12</programlisting> - - <para>See the <ulink - URL="../handbook/kernelconfig.html">Handbook entry on - configuring the kernel</ulink> if you've no experience with - building kernels.</para> - - <para>Once you have a kernel detecting - <devicename>psm0</devicename> correctly at boot time, make sure - that an entry for <devicename>psm0</devicename> exists in - <filename>/dev</filename>. You can do this by typing:</para> - - <screen>&prompt.root; <userinput>cd /dev; sh MAKEDEV psm0</userinput></screen> - - <para>when logged in as root.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="moused"> - <para>Is it possible to make use of a mouse in any way outside - the X Window?</para> - </question> - - <answer> - <para>If you are using the default console driver, syscons, you - can use a mouse pointer in text consoles to cut & paste - text. Run the mouse daemon, moused, and turn on the mouse - pointer in the virtual console:</para> - - <screen>&prompt.root; <userinput>moused -p /dev/<replaceable>xxxx</replaceable> -t <replaceable>yyyy</replaceable></userinput> -&prompt.root; <userinput>vidcontrol -m on</userinput></screen> - - <para>Where <replaceable>xxxx</replaceable> is the mouse device - name and <replaceable>yyyy</replaceable> is a protocol type for - the mouse. See the &man.moused.8; man page for supported - protocol types.</para> - - <para>You may wish to run the mouse daemon automatically when the - system starts. In version 2.2.1, set the following variables in - <filename>/etc/sysconfig</filename>.</para> - - <programlisting>mousedtype="yyyy" -mousedport="xxxx" -mousedflags=""</programlisting> - - <para>In versions 2.2.2 to 3.0, set the following variables in - <filename>/etc/rc.conf</filename>.</para> - - <programlisting>moused_type="yyyy" -moused_port="xxxx" -moused_flags=""</programlisting> - - <para>In 3.1 and later, assuming you have a PS/2 mouse, all you - need to is add <literal>moused_enable="YES"</literal> to - <filename>/etc/rc.conf</filename>.</para> - - <para>In addition, if you would like to be able to use the mouse - daemon on all virtual terminals instead of just console at - boot-time, add the following to - <filename>/etc/rc.conf</filename>.</para> - - <programlisting>allscreens_flags="-m on"</programlisting> - - <para>Staring from FreeBSD 2.2.6, the mouse daemon is capable of - determining the correct protocol type automatically unless the - mouse is a relatively old serial mouse model. Specify - <literal>auto</literal> the protocol to invoke automatic - detection.</para> - - <para>When the mouse daemon is running, access to the mouse - needs to be coordinated between the mouse daemon and other - programs such as the X Window. Refer to <link - linkend="x-and-moused">another section</link> on this - issue.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="text-mode-cut-paste"> - <para>How do I cut and paste text with mouse in the text - console?</para> - </question> - - <answer> - <para>Once you get the mouse daemon running (see - <link linkend="moused">previous section</link>), hold down the - button 1 (left button) and move the mouse to select a region of - text. Then, press the button 2 (middle button) or the button 3 - (right button) to paste it at the text cursor.</para> - - <para>In versions 2.2.6 and later, pressing the button 2 will - paste the text. Pressing the button 3 will - <quote>extend</quote> the selected region of text. If your - mouse does not have the middle button, you may wish to emulate - it or remap buttons using moused options. See the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?moused(8)"> - moused(8)</ulink> man page for details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="usbmouse"> - <para>I have a USB mouse. Does FreeBSD support the USB - mouse?</para> - </question> - - <answer> - <para>USB device support was added to FreeBSD 3.1. However, it - is still in a preliminary state and may not always work as of - version 3.2. If you want to experiment with the USB mouse - support, follow the procedure described below.</para> - - <orderedlist> - <listitem> - <para>Use FreeBSD 3.2 or later.</para> - </listitem> - - <listitem> - <para>Add the following lines to your kernel configuration - file, and rebuild the kernel.</para> - - <programlisting> -device uhci -device ohci -device usb -device ums</programlisting> - - <para>In versions of FreeBSD before 4.0, use this - instead:</para> - - <programlisting> -controller uhci0 -controller ohci0 -controller usb0 -device ums0</programlisting> - </listitem> - - <listitem> - <para>Go to the <filename>/dev</filename> directory and - create a device node as follows:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV ums0</userinput></screen> - </listitem> - - <listitem> - <para>Edit <filename>/etc/rc.conf</filename> and add the - following lines:</para> - - <programlisting> -moused_enable="YES" -moused_type="auto" -moused_port="/dev/ums0" -moused_flags="" -usbd_enable="YES" -usbd_flags=""</programlisting> - - <para>See the <link linkend="moused">previous section</link> - for more detailed discussion on moused.</para> - </listitem> - - <listitem> - <para>In order to use the USB mouse in the X session, edit - <filename>XF86Config</filename>. If you are using XFree86 - 3.3.2 or later, be sure to have the following lines in the - <emphasis>Pointer</emphasis> section:</para> - - <programlisting> -Device "/dev/sysmouse" -Protocol "Auto"</programlisting> - - <para>If you are using earlier versions of XFree86, be sure to - have the following lines in the <emphasis>Pointer</emphasis> - section:</para> - - <programlisting> -Device "/dev/sysmouse" -Protocol "SysMouse"</programlisting> - </listitem> - </orderedlist> - - <para>Refer to <link linkend="x-and-moused">another section</link> - on the mouse support in the X environment.</para> - - <para>Hot-plugging and unplugging of the USB mouse may not work - quite right yet. It is a good idea connect the mouse before you - start the system and leave it connected until the system is - shutdown to avoid trouble.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="mouse-wheel-buttons"> - <para>My mouse has a fancy wheel and buttons. Can I use them in - FreeBSD?</para> - </question> - - <answer> - <para>The answer is, unfortunately, <quote>It depends</quote>. - These mice with additional features require specialized driver - in most cases. Unless the mouse device driver or the user - program has specific support for the mouse, it will act just - like a standard two, or three button mouse.</para> - - <para>For the possible usage of wheels in the X Window - environment, refer to <link linkend="x-and-wheel">that - section</link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="psmerr"> - <para>My mouse does not seem working. The mouse cursor jumps - around on the screen. The mouse has a wheel and is connected - to the PS/2 mouse port.</para> - </question> - - <answer> - <para>The PS/2 mouse driver psm in FreeBSD versions 3.2 or - earlier has difficulty with some wheel mice, including Logitech - model M-S48 and its OEM siblings. Apply the following patch to - <filename>/sys/i386/isa/psm.c</filename> and rebuild the - kernel.</para> - - <programlisting> -Index: psm.c -=================================================================== -RCS file: /src/CVS/src/sys/i386/isa/Attic/psm.c,v -retrieving revision 1.60.2.1 -retrieving revision 1.60.2.2 -diff -u -r1.60.2.1 -r1.60.2.2 ---- psm.c 1999/06/03 12:41:13 1.60.2.1 -+++ psm.c 1999/07/12 13:40:52 1.60.2.2 -@@ -959,14 +959,28 @@ - sc->mode.packetsize = vendortype[i].packetsize; - - /* set mouse parameters */ -+#if 0 -+ /* -+ * A version of Logitech FirstMouse+ won't report wheel movement, -+ * if SET_DEFAULTS is sent... Don't use this command. -+ * This fix was found by Takashi Nishida. -+ */ - i = send_aux_command(sc->kbdc, PSMC_SET_DEFAULTS); - if (verbose >= 2) - printf("psm%d: SET_DEFAULTS return code:%04x\n", unit, i); -+#endif - if (sc->config & PSM_CONFIG_RESOLUTION) { - sc->mode.resolution - = set_mouse_resolution(sc->kbdc, -- (sc->config & PSM_CONFIG_RESOLUTION) - 1); -+ (sc->config & PSM_CONFIG_RESOLUTION) - 1); -+ } else if (sc->mode.resolution >= 0) { -+ sc->mode.resolution -+ = set_mouse_resolution(sc->kbdc, sc->dflt_mode.resolution); -+ } -+ if (sc->mode.rate > 0) { -+ sc->mode.rate = set_mouse_sampling_rate(sc->kbdc, sc->dflt_mode.rate); - } -+ set_mouse_scaling(sc->kbdc, 1); - - /* request a data packet and extract sync. bits */ - if (get_mouse_status(sc->kbdc, stat, 1, 3) < 3) {</programlisting> - - <para>Versions later than 3.2 should be all right.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="laptop-mouse-trackball"> - <para>How do I use the mouse/trackball/touchpad on my - laptop?</para> - </question> - - <answer> - <para>Please refer to <link linkend="ps2mouse">the answer to - the previous question</link>. And check out - <link linkend="pao">this note</link> on the Mobile Computing - page.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="tape-support"> - <para>What types of tape drives are supported?</para> - </question> - - <answer> - - <para>FreeBSD supports SCSI, QIC-36 (with a QIC-02 interface) - and QIC-40/80 (Floppy based) tape drives. This includes 8-mm - (aka Exabyte) and DAT drives. The QIC-40/80 drives are known to - be slow.</para> - - <para>Some of the early 8-mm drives are not quite compatible - with SCSI-2, and may not work well with FreeBSD.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="tape-changer-support"> - <para>Does FreeBSD support tape changers?</para> - </question> - - <answer> - <para>FreeBSD 2.2 supports SCSI changers using the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ch(4)">ch(4)</ulink> - device and the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?chio(1)">chio(1)</ulink> - command. The details of how you actually control the changer - can be found in the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?chio(4)">chio(1)</ulink> - man page.</para> - - <para>If you're not using <ulink - URL="http://www.FreeBSD.org/cgi/ports.cgi?amanda">AMANDA</ulink> - or some other product that already understands changers, - remember that they're only know how to move a tape from one - point to another, so you need to keep track of which slot a - tape is in, and which slot the tape currently in the drive - needs to go back to.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="sound-card-support"> - <para>Which sound cards are supported by FreeBSD?</para> - </question> - - <answer> - <para>FreeBSD supports the SoundBlaster, SoundBlaster Pro, - SoundBlaster 16, Pro Audio Spectrum 16, AdLib and Gravis - UltraSound sound cards. There is also limited support for - MPU-401 and compatible MIDI cards. Cards conforming to the - Microsoft Sound System specification are also supported through - the pcm driver.</para> - - <para> - <note> - <para>This is only for sound! This driver does not support - CD-ROMs, SCSI or joysticks on these cards, except for the - SoundBlaster. The SoundBlaster SCSI interface and some - non-SCSI CDROMS are supported, but you can't boot off this - device.</para> - </note></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="es1370-silent-pcm"> - <para>Workarounds for no sound from es1370 with pcm driver?</para> - </question> - - <answer> - <para>You can run the following command everytime the machine - booted up:</para> - - <screen>&prompt.root; <userinput>mixer pcm 100 vol 100 cd 100</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="network-cards"> - <para>Which network cards does FreeBSD support?</para> - </question> - - <answer> - <para>See the <ulink - URL="../handbook/install-hw.html#INSTALL-NICS"> - Ethernet cards</ulink> section of the handbook for a more - complete list. </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="no-math-coprocessor"> - <para>I don't have a math co-processor - is that bad?</para> - </question> - - <answer> - <para> - <note> - <para>This will only affect 386/486SX/486SLC owners - other - machines will have one built into the CPU.</para> - </note></para> - - <para>In general this will not cause any problems, but there are - circumstances where you will take a hit, either in performance - or accuracy of the math emulation code (see the section <link - linkend="emul">on FP emulation</link>). In particular, drawing - arcs in X will be VERY slow. It is highly recommended that you - buy a math co-processor; it's well worth it.</para> - - <para> - <note> - <para>Some math co-processors are better than others. It - pains us to say it, but nobody ever got fired for buying - Intel. Unless you're sure it works with FreeBSD, beware of - clones.</para> - </note></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="other-device-support"> - <para>What other devices does FreeBSD support?</para> - </question> - - <answer> - <para>See the <ulink - URL="../handbook/install.html#INSTALL-MISC">Handbook</ulink> - for the list of other devices supported.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="power-management-support"> - <para>Does FreeBSD support power management on my laptop?</para> - </question> - - <answer> - <para>FreeBSD supports APM on certain machines. Please look in - the <filename>LINT</filename> kernel config file, searching for - the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?apm(4)">APM</ulink> - keyword.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="micron-hang-boot"> - <para>My Micron system hangs at boot time</para> - </question> - - <answer> - <para>Certain Micron motherboards have a non-conforming PCI BIOS - implementation that causes grief when FreeBSD boots because PCI - devices don't get configured at their reported addresses.</para> - - <para>Disable the <quote>Plug and Play Operating System</quote> - flag in the BIOS to work around this problem. More information - can be found at <ulink - URL="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron"> - http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="newer-adaptec-support"> - <para>I have a newer Adaptec controller and FreeBSD can't find - it.</para> - </question> - - <answer> - <para>The newer AIC789x series Adaptec chips are supported under - the CAM SCSI framework which made it's debut in 3.0. Patches - against 2.2-STABLE are in <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/</ulink>. - A CAM-enhanced boot floppy is available at <ulink - URL="http://people.FreeBSD.org/~abial/cam-boot/"> - http://people.FreeBSD.org/~abial/cam-boot/</ulink>. - In both cases read the README before beginning. </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="internal-plugnplay-modem"> - <para>I have an internal Plug & Play modem and FreeBSD - can't find it.</para> - </question> - - <answer> - <para>You will need to add the modem's PnP ID to the PnP ID - list in the serial driver. To enable Plug & Play support, - compile a new kernel with <literal>controller pnp0</literal> in - the configuration file, then reboot the system. The kernel will - print the PnP IDs of all the devices it finds. Copy the PnP ID - from the modem to the table in - <filename>/sys/i386/isa/sio.c</filename>, at about line 2777. - Look for the string <literal>SUP1310</literal> in the structure - <literal>siopnp_ids[]</literal> to find the table. Build the - kernel again, install, reboot, and your modem should be - found.</para> - - <para>You may have to manually configure the PnP devices using - the <literal>pnp</literal> command in the boot-time - configuration with a command like - - <programlisting>pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8</programlisting> - to make the modem show.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="serial-console-prompt"> - <para>How do I get the boot: prompt to show on the serial - console?</para> - </question> - - <answer> - <para> - <orderedlist> - <listitem> - <para>Build a kernel with - <literal>options COMCONSOLE</literal>.</para> - </listitem> - - <listitem> - <para>Create /boot.config and place <option>-P</option> - as the only text in the file.</para> - </listitem> - - <listitem> - <para>Unplug the keyboard from the system.</para> - </listitem> - </orderedlist></para> - - <para>See - <filename>/usr/src/sys/i386/boot/biosboot/README.serial</filename> - for information.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="micron-3comnic-failure"> - <para>Why doesn't my 3Com PCI network card work with my Micron - computer?</para> - </question> - - <answer> - <para>Certain Micron motherboards have a non-conforming PCI BIOS - implementation that does not configure PCI devices at the - addresses reported. This causes grief when FreeBSD - boots.</para> - - <para>To work around this problem, disable the - <quote>Plug and Play Operating System</quote> flag in the - BIOS.</para> - - <para>More information on this problem is available at URL: - <ulink URL="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron">http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="smp-support"> - <para>Does FreeBSD support Symmetric Multiprocessing (SMP)?</para> - </question> - - <answer> - <para>SMP is supported in 3.0-STABLE and later releases only. - SMP is not enabled in the <emphasis>GENERIC</emphasis> kernel, - so you will have to recompile your kernel to enable SMP. Take a - look at <filename>/sys/i386/conf/LINT</filename> to figure out - what options to put in your kernel config file.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="asusk7v-boot-failure"> - <para>The boot floppy hangs on a system with an ASUS K7V - motherboard. How do I fix this?</para> - </question> - - <answer> - <para>Go in to the BIOS setup and disable the boot virus - protection.</para> - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="troubleshoot"> - <title>Troubleshooting</title> - - <qandaset> - <qandaentry> - <question id="awre"> - <para>I have bad blocks on my hard drive!</para> - </question> - - <answer> - <para>With SCSI drives, the drive should be capable of re-mapping - these automatically. However, many drives are shipped with - this feature disabled, for some mysterious reason...</para> - - <para>To enable this, you'll need to edit the first device page - mode, which can be done on FreeBSD by giving the command - (as root)</para> - - <screen>&prompt.root; <userinput>scsi -f /dev/rsd0c -m 1 -e -P 3</userinput></screen> - - <para>and changing the values of AWRE and ARRE from 0 to 1:-</para> - - <programlisting>AWRE (Auto Write Reallocation Enbld): 1 -ARRE (Auto Read Reallocation Enbld): 1</programlisting> - - <para>The following paragraphs were submitted by <ulink - URL="mailto:tedm@toybox.placo.com"> - Ted Mittelstaedt</ulink>:</para> - - <para>For IDE drives, any bad block is usually a sign of - potential trouble. All modern IDE drives come with internal - bad-block remapping turned on. All IDE hard drive manufacturers - today offer extensive warranties and will replace drives with - bad blocks on them.</para> - - <para>If you still want to attempt to rescue an IDE drive with - bad blocks, you can attempt to download the IDE drive - manufacturer's IDE diagnostic program, and run this against the - drive. Sometimes these programs can be set to force the drive - electronics to rescan the drive for bad blocks and lock them - out.</para> - - <para>For ESDI, RLL and MFM drives, bad blocks are a normal part - of the drive and are no sign of trouble, generally. With a PC, - the disk drive controller card and BIOS handle the task of - locking out bad sectors. This is fine for operating systems - like DOS that use BIOS code to access the disk. However, - FreeBSD's disk driver does not go through BIOS, therefore a - mechanism, bad144, exists that replaces this functionality. - bad144 only works with the wd driver (which means it is not - supported in FreeBSD 4.0), it is NOT able to be used with SCSI. - bad144 works by entering all bad sectors found into a special - file.</para> - - <para>One caveat with bad144 - the bad block special file is - placed on the last track of the disk. As this file may possibly - contain a listing for a bad sector that would occur near the - beginning of the disk, where the /kernel file might be located, - it therefore must be accessible to the bootstrap program that - uses BIOS calls to read the kernel file. This means that the - disk with bad144 used on it must not exceed 1024 cylinders, 16 - heads, and 63 sectors. This places an effective limit of 500MB - on a disk that is mapped with bad144.</para> - - <para>To use bad144, simply set the <quote>Bad Block</quote> - scanning to ON in the FreeBSD fdisk screen during the initial - install. This works up through FreeBSD 2.2.7. The disk must - have less than 1024 cylinders. It is generally recommended that - the disk drive has been in operation for at least 4 hours prior - to this to allow for thermal expansion and track - wandering.</para> - - <para>If the disk has more than 1024 cylinders (such as a large - ESDI drive) the ESDI controller uses a special translation mode - to make it work under DOS. The wd driver understands about - these translation modes, IF you enter the - <quote>translated</quote> geometry with the <quote>set - geometry</quote> command in fdisk. You must also NOT use the - <quote>dangerously dedicated</quote> mode of creating the - FreeBSD partition, as this ignores the geometry. Also, even - though fdisk will use your overridden geometry, it still knows - the true size of the disk, and will attempt to create a too - large FreeBSD partition. If the disk geometry is changed to the - translated geometry, the partition MUST be manually created - with the number of blocks.</para> - - <para>A quick trick to use is to set up the large ESDI disk with - the ESDI controller, boot it with a DOS disk and format it with - a DOS partition. Then, boot the FreeBSD install and in the - fdisk screen, read off and write down the blocksize and block - numbers for the DOS partition. Then, reset the geometry to the - same that DOS uses, delete the DOS partition, and create a - <quote>cooperative</quote> FreeBSD partition using the - blocksize you recorded earlier. Then, set the partition - bootable and turn on bad block scanning. During the actual - install, bad144 will run first, before any filesystems are - created. (you can view this with an Alt-F2) If it has any - trouble creating the badsector file, you have set too large a - disk geometry - reboot the system and start all over again - (including repartitioning and reformatting with DOS).</para> - - <para>If remapping is enabled and you are seeing bad blocks, - consider replacing the drive. The bad blocks will only get - worse as time goes on.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="bustek742a-eisa-scsi"> - <para>FreeBSD does not recognize my Bustek 742a EISA SCSI!</para> - </question> - - <answer> - <para>This info is specific to the 742a but may also cover - other Buslogic cards. (Bustek = Buslogic)</para> - - <para>There are 2 general <quote>versions</quote> of the 742a - card. They are hardware revisions A-G, and revisions H - - onwards. The revision letter is located after the Assembly - number on the edge of the card. The 742a has 2 ROM chips on it, - one is the BIOS chip and the other is the Firmware chip. - FreeBSD doesn't care what version of BIOS chip you have but it - does care about what version of firmware chip. Buslogic will - send upgrade ROMS out if you call their tech support dept. The - BIOS and Firmware chips are shipped as a matched pair. You must - have the most current Firmware ROM in your adapter card for - your hardware revision.</para> - - <para>The REV A-G cards can only accept BIOS/Firmware sets up to - 2.41/2.21. The REV H- up cards can accept the most current - BIOS/Firmware sets of 4.70/3.37. The difference between the - firmware sets is that the 3.37 firmware supports <quote>round - robin</quote></para> - - <para>The Buslogic cards also have a serial number on them. If - you have a old hardware revision card you can call the Buslogic - RMA department and give them the serial number and attempt to - exchange the card for a newer hardware revision. If the card is - young enough they will do so.</para> - - <para>FreeBSD 2.1 only supports Firmware revisions 2.21 onward. - If you have a Firmware revision older than this your card will - not be recognized as a Buslogic card. It may be recognized as - an Adaptec 1540, however. The early Buslogic firmware contains - an AHA1540 <quote>emulation</quote> mode. This is not a good - thing for an EISA card, however.</para> - - <para>If you have an old hardware revision card and you obtain - the 2.21 firmware for it, you will need to check the position - of jumper W1 to B-C, the default is A-B.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="hpnetserver-scsi-failure"> - <para>My HP Netserver's SCSI controller is not detected!</para> - </question> - - <answer> - <para>This is basically a known problem. The EISA on-board SCSI - controller in the HP Netserver machines occupies EISA slot - number 11, so all the <quote>true</quote> EISA slots are in - front of it. Alas, the address space for EISA slots >= 10 - collides with the address space assigned to PCI, and FreeBSD's - auto-configuration currently cannot handle this situation very - well.</para> - - <para>So now, the best you can do is to pretend there is no - address range clash :), by bumping the kernel option - <literal>EISA_SLOTS</literal> to a value of 12. Configure and - compile a kernel, as described in the <ulink - URL="../handbook/kernelconfig.html">Handbook entry on - configuring the kernel</ulink>.</para> - - <para>Of course, this does present you with a chicken-and-egg - problem when installing on such a machine. In order to work - around this problem, a special hack is available inside - <emphasis>UserConfig</emphasis>. Do not use the - <quote>visual</quote> interface, but the plain command-line - interface there. Simply type</para> - - <programlisting>eisa 12 -quit</programlisting> - - <para>at the prompt, and install your system as usual. While - it's recommended you compile and install a custom kernel - anyway,</para> - - <para>Hopefully, future versions will have a proper fix for - this problem.</para> - - <para> - <note> - <para>You can not use a - <emphasis remap=bf>dangerously dedicated</emphasis> disk - with an HP Netserver. See <link linkend="dedicate">this - note</link> for more info.</para> - </note></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cmd640-ide"> - <para>What's up with this CMD640 IDE controller?</para> - </question> - - <answer> - <para>It's broken. It cannot handle commands on both channels - simultaneously.</para> - - <para>There's a workaround available now and it is enabled - automatically if your system uses this chip. For the details - refer to the manual page of the disk driver (man 4 wd).</para> - - <para>If you're already running FreeBSD 2.2.1 or 2.2.2 with a - CMD640 IDE controller and you want to use the second channel, - build a new kernel with <literal>options "CMD640"</literal> - enabled. This is the default for 2.2.5 and later.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ed1-timeout"> - <para>I keep seeing messages like - <literal>ed1: timeout</literal>.</para> - </question> - - <answer> - <para>This is usually caused by an interrupt conflict (e.g., - two boards using the same IRQ). FreeBSD prior to 2.0.5R used to - be tolerant of this, and the network driver would still - function in the presence of IRQ conflicts. However, with 2.0.5R - and later, IRQ conflicts are no longer tolerated. Boot with the - -c option and change the ed0/de0/... entry to match your - board.</para> - - <para>If you're using the BNC connector on your network card, - you may also see device timeouts because of bad termination. To - check this, attach a terminator directly to the NIC (with no - cable) and see if the error messages go away. </para> - - <para>Some NE2000 compatible cards will give this error if there - is no link on the UTP port or if the cable is disconnected.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="mount-cd-superblock"> - <para>When I mount a CDROM, I get - <literal>Incorrect super block</literal>.</para> - </question> - - <answer> - <para>You have to tell <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?mount(8)">mount</ulink> - the type of the device that you want to mount. By default, - <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?mount(8)">mount(8)</ulink> - will assume the filesystem is of type <literal>ufs</literal>. - You want to mount a CDROM filesystem, and you do this by - specifying the <option>-t cd9660</option> option to <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?mount(8)"> - mount(8)</ulink>. This does, of course, assume that the - CDROM contains an ISO 9660 filesystem, which is what most CDROMs - have. As of 1.1R, FreeBSD automatically understands the Rock - Ridge (long filename) extensions as well.</para> - - <para>As an example, if you want to mount the CDROM device, - <filename>/dev/cd0c</filename>, under <filename>/mnt</filename>, - you would execute:</para> - - <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0c /mnt</userinput></screen> - - <para>Note that your device name (<filename>/dev/cd0c</filename> - in this example) could be different, depending on the CDROM - interface. Note that the <option>-t cd9660</option> option just - causes the <command>mount_cd9660</command> command to be - executed, and so the above example could be shortened - to:</para> - - <screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0c /mnt</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cdrom-not-configured"> - <para>When I mount a CDROM, I get - <literal>Device not configured</literal>.</para> - </question> - - <answer> - <para>This generally means that there is no CDROM in the CDROM - drive, or the drive is not visible on the bus. Feed the drive - something, and/or check its master/slave status if it is IDE - (ATAPI). It can take a couple of seconds for a CDROM drive to - notice that it's been fed, so be patient.</para> - - <para>Sometimes a SCSI CD-ROM may be missed because it hadn't - enough time to answer the bus reset. If you have a SCSI CD-ROM - please try to add the following symbol into your kernel - configuration file and recompile.</para> - - <programlisting>options "SCSI_DELAY=15"</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="printer-slow"> - <para>My printer is ridiculously slow. What can I do ?</para> - </question> - - <answer> - <para>If it's parallel, and the only problem is that it's terribly - slow, try setting your printer port into <quote>polled</quote> - mode:</para> - - <screen>&prompt.root; <userinput>lptcontrol -p</userinput></screen> - - <para>Some newer HP printers are claimed not to work correctly in - interrupt mode, apparently due to some (not yet exactly - understood) timing problem.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="signal11"> - <para>My programs occasionally die with - <literal>Signal 11</literal> errors.</para> - </question> - - <answer> - <para>Signal 11 errors are caused when your process has attempted - to access memory which the operating system has not granted it - access to. If something like this is happening at seemingly - random intervals then you need to start investigating things - very carefully.</para> - - <para>These problems can usually be attributed to either:</para> - - <orderedlist> - <listitem> - <para>If the problem is occurring only in a specific - application that you are developing yourself it is probably - a bug in your code.</para> - </listitem> - - <listitem> - <para>If it's a problem with part of the base FreeBSD system, - it may also be buggy code, but more often than not these - problems are found and fixed long before us general FAQ - readers get to use these bits of code (that's what -current - is for).</para> - </listitem> - </orderedlist> - - <para>In particular, a dead giveaway that this is *not* a FreeBSD - bug is if you see the problem when you're compiling a program, - but the activity that the compiler is carrying out changes - each time.</para> - - <para>For example, suppose you're running "make buildworld", and - the compile fails while trying to compile ls.c in to ls.o. If - you next run "make buildworld" again, and the compile fails in - the same place then this is a broken build -- try updating your - sources and try again. If the compile fails elsewhere then this - is almost certainly hardware.</para> - - <para>What you should do:</para> - - <para>In the first case you can use a debugger e.g. gdb to find - the point in the program which is attempting to access a bogus - address and then fix it.</para> - - <para>In the second case you need to verify that it's not your - hardware at fault.</para> - - <para> Common causes of this include :</para> - - <orderedlist> - <listitem> - <para>Your hard disks might be overheating: Check the fans in - your case are still working, as your disk (and perhaps - other hardware might be overheating).</para> - </listitem> - - <listitem> - <para>The processor running is overheating: This might be - because the processor has been overclocked, or the fan on - the processor might have died. In either case you need to - ensure that you have hardware running at what it's - specified to run at, at least while trying to solve this - problem. i.e. Clock it back to the default settings.</para> - - <para>If you are overclocking then note that it's far cheaper - to have a slow system than a fried system that needs - replacing! Also the wider community is not often - sympathetic to problems on overclocked systems, whether you - believe it's safe or not.</para> - </listitem> - - <listitem> - <para>Dodgy memory: If you have multiple memory SIMMS/DIMMS - installed then pull them all out and try running the - machine with each SIMM or DIMM individually and narrow the - problem down to either the problematic DIMM/SIMM or perhaps - even a combination.</para> - </listitem> - - <listitem> - <para>Over-optimistic Motherboard settings: In your BIOS - settings, and some motherboard jumpers you have options to - set various timings, mostly the defaults will be - sufficient, but sometimes, setting the wait states on RAM - too low, or setting the "RAM Speed: Turbo" option, or - similar in the BIOS will cause strange behaviour. A - possible idea is to set to BIOS defaults, but it might be - worth noting down your settings first!</para> - </listitem> - - <listitem> - <para>Unclean or insufficient power to the motherboard. If you - have any unused I/O boards, hard disks, or CDROMs in your - system, try temporarily removing them or disconnecting the - power cable from them, to see if your power supply can - manage a smaller load. Or try another power supply, - preferably one with a little more power (for instance, if - your current power supply is rated at 250 Watts try one - rated at 300 Watts).</para> - </listitem> - - </orderedlist> - - <para>You should also read the SIG11 FAQ (listed below) which has - excellent explanations of all these problems, albeit from a - Linux viewpoint. It also discusses how memory testing software - or hardware can still pass faulty memory.</para> - - <para>Finally, if none of this has helped it is possible that - you've just found a bug in FreeBSD, and you should follow the - instructions to send a problem report.</para> - - <para>There's an extensive FAQ on this at <ulink - URL="http://www.bitwizard.nl/sig11/"> - the SIG11 problem FAQ</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="screen-loses-sync"> - <para>When I boot, the screen goes black and loses sync!</para> - </question> - - <answer> - <para>This is a known problem with the ATI Mach 64 video card. - The problem is that this card uses address - <literal>2e8</literal>, and the fourth serial port does too. - Due to a bug (feature?) in the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sio(4)">sio(4)</ulink> - driver it will touch this port even if you don't have the - fourth serial port, and <emphasis remap=bf>even</emphasis> if - you disable sio3 (the fourth port) which normally uses this - address.</para> - - <para>Until the bug has been fixed, you can use this - workaround:</para> - - <para> - <orderedlist> - <listitem> - <para>Enter <option>-c</option> at the bootprompt. - (This will put the kernel into configuration mode).</para> - </listitem> - - <listitem> - <para>Disable <devicename>sio0</devicename>, - <devicename>sio1</devicename>, - <devicename>sio2</devicename> and - <devicename>sio3</devicename> (all of them). This way - the sio driver doesn't get activated -> no - problems.</para> - </listitem> - - <listitem> - <para>Type exit to continue booting.</para> - </listitem> - </orderedlist></para> - - <para>If you want to be able to use your serial ports, you'll - have to build a new kernel with the following modification: in - <filename>/usr/src/sys/i386/isa/sio.c</filename> find the one - occurrence of the string <literal>0x2e8</literal> and remove - that string and the preceding comma (keep the trailing comma). - Now follow the normal procedure of building a new - kernel.</para> - - <para>Even after applying these workarounds, you may still find - that the X Window System does not work properly. If this is the - case, make sure that the XFree86 version you are using is at - least XFree86 3.3.3 or higher. This version and upwards has - built-in support for the Mach64 cards and even a dedicated X - server for those cards.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="reallybigram"> - <para>I have 128 MB of RAM but the system only uses 64 MB.</para> - </question> - - <answer> - <para>Due to the manner in which FreeBSD gets the memory size - from the BIOS, it can only detect 16 bits worth of Kbytes in - size (65535 Kbytes = 64MB) (or less... some BIOSes peg the - memory size to 16M). If you have more than 64MB, FreeBSD will - attempt to detect it; however, the attempt may fail.</para> - - <para>To work around this problem, you need to use the kernel - option specified below. There is a way to get complete memory - information from the BIOS, but we don't have room in the - bootblocks to do it. Someday when lack of room in the - bootblocks is fixed, we'll use the extended BIOS functions to - get the full memory information...but for now we're stuck with - the kernel option.</para> - - <para><literal>options "MAXMEM=<replaceable>n</replaceable>"</literal></para> - - <para>Where <replaceable>n</replaceable> is your memory in - Kilobytes. For a 128 MB machine, you'd want to use - <literal>131072</literal>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="panic-kmemmap-too-small"> - <para>FreeBSD 2.0 panics with - <literal>kmem_map too small!</literal></para> - </question> - - <answer> - - <para> - <note> - <para>The message may also be - <literal>mb_map too small!</literal></para> - </note></para> - - <para>The panic indicates that the system ran out of virtual - memory for network buffers (specifically, mbuf clusters). You - can increase the amount of VM available for mbuf clusters by - adding:</para> - - <para><literal>options "NMBCLUSTERS=<replaceable>n</replaceable>"</literal></para> - - <para>to your kernel config file, where - <replaceable>n</replaceable> is a number in the range 512-4096, - depending on the number of concurrent TCP connections you need - to support. I'd recommend trying 2048 - this should get rid of - the panic completely. You can monitor the number of mbuf - clusters allocated/in use on the system with <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?netstat(1)">netstat - -m</ulink>. The default value for NMBCLUSTERS is <literal>512 + - MAXUSERS * 16</literal>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cmap-busy-panic"> - <para><literal>CMAP busy panic</literal> when rebooting with a - new kernel.</para> - </question> - - <answer> - <para>The logic that attempts to detect an out of date - <filename>/var/db/kvm_*.db</filename> files sometimes fails - and using a mismatched file can sometimes lead to panics.</para> - - <para>If this happens, reboot single-user and do:</para> - - <screen>&prompt.root; <userinput>rm /var/db/kvm_*.db</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="brkadrint-illegal-host-access"> - <para>ahc0: brkadrint, Illegal Host Access at seqaddr 0x0</para> - </question> - - <answer> - <para>This is a conflict with an Ultrastor SCSI Host Adapter.</para> - - <para>During the boot process enter the kernel configuration - menu and disable <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?uha(4)">uha0</ulink>, - which is causing the problem.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="mail-loopback"> - <para>Sendmail says - <literal>mail loops back to myself</literal></para> - </question> - - <answer> - <para>This is answered in the sendmail FAQ as follows:-</para> - - <para> -<literallayout> * I'm getting "Local configuration error" messages, such as: - - 553 relay.domain.net config error: mail loops back to myself - 554 <user@domain.net>... Local configuration error - - How can I solve this problem? - - You have asked mail to the domain (e.g., domain.net) to be - forwarded to a specific host (in this case, relay.domain.net) - by using an MX record, but the relay machine doesn't recognize - itself as domain.net. Add domain.net to /etc/sendmail.cw - (if you are using FEATURE(use_cw_file)) or add "Cw domain.net" - to /etc/sendmail.cf. - </literallayout></para> - - <para>The current version of the <ulink - URL="ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/sendmail-faq">sendmail - FAQ</ulink> is no longer maintained with the sendmail release. - It is however regularly posted to <ulink - URL="news:comp.mail.sendmail">comp.mail.sendmail</ulink>, - <ulink URL="news:comp.mail.misc">comp.mail.misc</ulink>, <ulink - URL="news:comp.mail.smail">comp.mail.smail</ulink>, <ulink - URL="news:comp.answers">comp.answers</ulink>, and <ulink - URL="news:news.answers">news.answers</ulink>. You can also - receive a copy via email by sending a message to - <email>mail-server@rtfm.mit.edu</email> with the command - <literal>send usenet/news.answers/mail/sendmail-faq</literal> - as the body of the message.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="remote-fullscreen"> - <para>Full screen applications on remote machines misbehave</para> - </question> - - <answer> - <para>The remote machine may be setting your terminal type - to something other than the <literal>cons25</literal> terminal - type required by the FreeBSD console.</para> - - <para>There are a number of possible work-arounds for this - problem: - <itemizedlist> - <listitem> - <para>After logging on to the remote machine, set your - TERM shell variable to <literal>ansi</literal> or - <literal>sco</literal> if the remote machine knows - about these terminal types.</para> - </listitem> - - <listitem> - <para>Use a VT100 emulator like <ulink - URL="http://www.FreeBSD.org/cgi/ports.cgi?screen-"> - screen</ulink> at the FreeBSD console. - <application>screen</application> offers you the ability - to run multiple concurrent sessions from one terminal, - and is a neat program in its own right. Each - <application>screen</application> window behaves like a - VT100 terminal, so the TERM variable at the remote end - should be set to <literal>vt100</literal>.</para> - </listitem> - - <listitem> - <para>Install the <literal>cons25</literal> terminal - database entry on the remote machine. The way to do this - depends on the operating system on the remote machine. - The system administration manuals for the remote system - should be able to help you here.</para> - </listitem> - - <listitem> - <para>Fire up an X server at the FreeBSD end and login to - the remote machine using an X based terminal emulator - such as <command>xterm</command> or - <command>rxvt</command>. The TERM variable at the remote - host should be set to <literal>xterm</literal> or - <literal>vt100</literal>.</para> - </listitem> - </itemizedlist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="calcru-negative"> - <para>My machine prints - <literal>calcru: negative time...</literal></para> - </question> - - <answer> - <para>This can be caused by various hardware and/or software - ailments relating to interrupts. It may be due to bugs but can - also happen by nature of certain devices. Running TCP/IP over - the parallel port using a large MTU is one good way to provoke - this problem. Graphics accelerators can also get you here, in - which case you should check the interrupt setting of the card - first.</para> - - <para>A side effect of this problem are dying processes with the - message <quote>SIGXCPU exceeded cpu time limit</quote>.</para> - - <para>For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the - problem cannot be fixed otherwise the solution is to set - this sysctl variable:</para> - - <screen>&prompt.root; <userinput>sysctl -w kern.timecounter.method=1</userinput></screen> - - <para> This means a performance impact, but considering the cause - of this problem, you probably will not notice. If the problem - persists, keep the sysctl set to one and set the - <literal>NTIMECOUNTER</literal> option in your kernel to - increasingly large values. If by the time you have reached - <literal>NTIMECOUNTER=20</literal> the problem isn't solved, - interrupts are too hosed on your machine for reliable - timekeeping.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="pcm0-not-found"> - <para>I see <literal>pcm0 not found</literal> or my sound card is - found as <literal>pcm1</literal> but I have - <literal>device pcm0</literal> in my kernel config file</para> - </question> - - <answer> - <para>This occurs in FreeBSD 3.x with PCI sound cards. The - <literal>pcm0</literal> device is reserved exclusively for - ISA-based cards so, if you have a PCI card, then you will see - this error, and your card will appear as <literal>pcm1</literal>. - - <note> - <para>You cannot remove the warning by simply changing the - line in the kernel config file to <literal>device - pcm1</literal> as this will result in - <literal>pcm1</literal> being reserved for ISA cards and - your PCI card being found as <literal>pcm2</literal> (along - with the warning <literal>pcm1 not found</literal>).</para> - </note> - - If you have a PCI sound card you will also have to make the - <literal>snd1</literal> device rather than - <literal>snd0</literal>:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV snd1</userinput></screen> - - <para>This situation does not arise in FreeBSD 4.x as has a lot - of work has been done to make the it more - <emphasis>PnP-centric</emphasis> and the - <literal>pcm0</literal> device is no longer reserved - exclusively fo ISA cards</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="pnp-not-found"> - <para>My PnP card is no longer found (or found as - <literal>unknown</literal>) since upgrading to FreeBSD 4.x</para> - </question> - - <answer> - <para>FreeBSD 4.x is now much more <emphasis>PnP-centric</emphasis> - and this has had the side effect of some PnP devices (e.g. sound - cards and internal modems) not working even though they worked - under FreeBSD 3.x.</para> - - <para>The reasons for this behaviour are explained by the following - e-mail, posted to the freebsd-questions mailing list by Peter - Wemm, in answer to a question about an internal modem that was - no longer found after an upgrade to FreeBSD 4.x (the comments - in <literal>[]</literal> have been added to clarify the - context.</para> - - <blockquote> - <para>The PNP bios preconfigured it [the modem] and left it - laying around in port space, so [in 3.x] the old-style ISA - probes <quote>found</quote> it there.</para> - - <para>Under 4.0, the ISA code is much more PnP-centric. It was - possible [in 3.x] for an ISA probe to find a - <quote>stray</quote> device and then for the PNP device id to - match and then fail due to resource conflicts. So, it - disables the programmable cards first so this double probing - cannot happen. It also means that it needs to know the PnP - id's for supported PnP hardware. Making this more user - tweakable is on the TODO list.</para> - </blockquote> - - <para>To get the device working again requires finding its PnP id - and adding it to the list that the ISA probes use to identify - PnP devices. This is obtained using &man.pnpinfo.8; to probe the - device, for example this is the output from &man.pnpinfo.8; for - an internal modem:</para> - - <screen>&prompt.root; <userinput>pnpinfo</userinput> -Checking for Plug-n-Play devices... - -Card assigned CSN #1 -Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff -PnP Version 1.0, Vendor Version 0 -Device Description: Pace 56 Voice Internal Plug & Play Modem - -Logical Device ID: PMC2430 0x3024a341 #0 - Device supports I/O Range Check -TAG Start DF - I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8 - [16-bit addr] - IRQ: 4 - only one type (true/edge)</screen> - - <para>[more TAG lines elided]</para> - - <screen> -TAG End DF -End Tag - -Successfully got 31 resources, 1 logical fdevs --- card select # 0x0001 - -CSN PMC2430 (0x3024a341), Serial Number 0xffffffff - -Logical device #0 -IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 -IRQ 5 0 -DMA 4 0 -IO range check 0x00 activate 0x01</screen> - - <para>The information you require is in the - <quote>Vendor ID</quote> line at the start of the output. The - hexadecimal number in parentheses (0x3024a341 in this example) - is the PnP id and the string immediately before this (PMC2430) - is a unique ASCII id. This information needs adding to the file - <filename>/usr/src/sys/isa/sio.c</filename>.</para> - - <para>You should first make a backup of <filename>sio.c</filename> - just in case things go wrong. You will also need it to make the - patch to submit with your PR (you are going to submit a PR, - aren't you?) then edit <filename>sio.c</filename> and search - for the line</para> - - <programlisting>static struct isa_pnp_id sio_ids[] = {</programlisting> - - <para>then scroll down to find the correct place to add the entry - for your device. The entries look like this, and are sorted on - the ASCII Vendor ID string which should be included in the - comment to the right of the line of code along with all (if it - will fit) or part of the <emphasis>Device Description</emphasis> - from the output of &man.pnpinfo.8;:</para> - - <programlisting> -{0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */ -{0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */ -{0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */ -{0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */ -{0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */ - </programlisting> - - <para>Add the hexadecimal Vendor ID for your device in the - correct place, save the file, rebuild your kernel, and reboot. - Your device should now be found as an <literal>sio</literal> - device as it was under FreeBSD 3.x</para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="commercial"> - <title>Commercial Applications</title> - - <para> - <note> - <para>This section is still very sparse, though we're hoping, of - course, that companies will add to it! :) The FreeBSD group has - no financial interest in any of the companies listed here but - simply lists them as a public service (and feels that commercial - interest in FreeBSD can have very positive effects on FreeBSD's - long-term viability). We encourage commercial software vendors to - send their entries here for inclusion. See <ulink - URL="http://www.FreeBSD.org/commercial/commercial.html">the - Vendors page</ulink> for a longer list.</para> - </note></para> - - <qandaset> - <qandaentry> - <question id="motif"> - <para>Where can I get Motif for FreeBSD?</para> - </question> - - <answer> - <para>Contact <link linkend="apps2go">Apps2go</link> for the - least expensive ELF Motif 2.1.20 distribution for FreeBSD - (either i386 or Alpha).<anchor id="apps2go"></para> - - <para>There are two distributions, the <quote>developement - edition</quote> and the <quote>runtime edition</quote> (for - much less). These distributions includes: - - <itemizedlist> - <listitem> - <para>OSF/Motif manager, xmbind, panner, wsm.</para> - </listitem> - - <listitem> - <para>Development kit with uil, mrm, xm, xmcxx, include - and Imake files.</para> - </listitem> - - <listitem> - <para>Static and dynamic ELF libraries (for use with - FreeBSD 3.0 and above).</para> - </listitem> - - <listitem> - <para>Demonstration applets.</para> - </listitem> - </itemizedlist></para> - - <para>Be sure to specify that you want the FreeBSD version of - Motif when ordering (don't forget to mention the architecture - you want too)! Versions for NetBSD and OpenBSD are also sold by - <emphasis>Apps2go</emphasis>. This is currently a FTP only - download.</para> - - <para> - <variablelist> - <varlistentry> - <term>More info</term> - <listitem> - <para><ulink URL="http://www.apps2go.com/"> - Apps2go WWW page</ulink></para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para><ulink URL="mailto:sales@apps2go.com"> - Sales</ulink> or <ulink - URL="mailto:support@apps2go.com">Support</ulink> - email addresses.</para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para>phone (817) 431 8775 or +1 817 431-8775</para> - </listitem> - </varlistentry> - </variablelist></para> - - <para>Contact <link linkend="metrox">Metro Link</link> - for an either ELF or a.out Motif 2.1 distribution for - FreeBSD.</para> - - <para>This distribution includes: - <itemizedlist> - <listitem> - <para>OSF/Motif manager, xmbind, panner, wsm.</para> - </listitem> - - <listitem> - <para>Development kit with uil, mrm, xm, xmcxx, include - and Imake files.</para> - </listitem> - - <listitem> - <para>Static and dynamic libraries (specify ELF for use - with FreeBSD 3.0 and later; or a.out for use with FreeBSD - 2.2.8 and eariler).</para> - </listitem> - - <listitem> - <para>Demonstration applets.</para> - </listitem> - - <listitem> - <para>Preformatted man pages.</para> - </listitem> - - </itemizedlist></para> - - <para>Be sure to specify that you want the FreeBSD version - of Motif when ordering! Versions for Linux are also sold by - <emphasis>Metro Link</emphasis>. This is available on either a - CDROM or for FTP download.</para> - - <para>Contact <link linkend="xig">Xi Graphics</link> for an - a.out Motif 2.0 distribution for FreeBSD.</para> - - <para>This distribution includes: - <itemizedlist> - <listitem> - <para>OSF/Motif manager, xmbind, panner, wsm.</para> - </listitem> - - <listitem> - <para>Development kit with uil, mrm, xm, xmcxx, include - and Imake files.</para> - </listitem> - - <listitem> - <para>Static and dynamic libraries (for use with FreeBSD - 2.2.8 and eariler).</para> - </listitem> - - <listitem> - <para>Demonstration applets.</para> - </listitem> - - <listitem> - <para>Preformatted man pages.</para> - </listitem> - </itemizedlist></para> - - <para>Be sure to specify that you want the FreeBSD version - of Motif when ordering! Versions for BSDI and Linux are also - sold by <emphasis>Xi Graphics</emphasis>. This is currently a 4 - diskette set... in the future this will change to a unified CD - distribution like their CDE.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cde"> - <para>Where can I get CDE for FreeBSD?</para> - </question> - - <answer> - <para><link linkend="xig">Xi Graphics</link> used to sell CDE - for FreeBSD, but no longer do.</para> - - <para><ulink URL="http://www.kde.org/">KDE</ulink> is an open - source X11 desktop which is similar to CDE in many respects. - You might also like the look and feel of <ulink - URL="http://www.xfce.org/">xfce</ulink>. KDE and xfce are both - in the <ulink URL="http://www.FreeBSD.org/ports/">ports - system</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="commercial-xserver"> - <para>Are there any commercial high-performance X servers?</para> - </question> - - <answer> - <para>Yes, <ulink URL="http://www.xig.com/">Xi Graphics</ulink> - and <ulink URL="http://www.metrolink.com/">Metro Link</ulink> - sells Accelerated-X product for FreeBSD and other Intel based - systems.</para> - - <para>The Metro Link offering is a high performance X Server - that offers easy configuration using the FreeBSD Package suite - of tools, support for multiple concurrent video boards and is - distributed in binary form only, in a convienent FTP download. - Not to mention the Metro Link offering is available at the very - reasonable price of $39. <anchor id="metrox"></para> - - <para>Metro Link also sells both ELF and a.out Motif for - FreeBSD (see above).</para> - - <para> - <variablelist> - <varlistentry> - <term>More info</term> - <listitem> - <para><ulink URL="http://www.metrolink.com/"> - Metro Link WWW page</ulink></para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para><ulink URL="mailto:sales@metrolink.com">Sales</ulink> - or <ulink URL="mailto:tech@metrolink.com">Support</ulink> - email addresses.</para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para>phone (954) 938-0283 or +1 954 938-0283</para> - </listitem> - </varlistentry> - </variablelist></para> - - <para>The Xi Graphics offering is a high performance X Server - that offers easy configuration, support for multiple concurrent - video boards and is distributed in binary form only, in a - unified diskette distribution for FreeBSD and Linux. Xi - Graphics also offers a high performance X Server taylored for - laptop support.<anchor id="xig"></para> - - <para>There is a free <quote>compatibility demo</quote> of - version 5.0 available.</para> - - <para>Xi Graphics also sells Motif and CDE for FreeBSD (see - above).</para> - - <para> - <variablelist> - <varlistentry> - <term>More info</term> - <listitem> - <para><ulink URL="http://www.xig.com/"> - Xi Graphics WWW page</ulink></para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para><ulink URL="mailto:sales@xig.com">Sales</ulink> - or <ulink URL="mailto:support@xig.com">Support</ulink> - email addresses.</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>or</term> - <listitem> - <para>phone (800) 946 7433 or +1 303 298-7478.</para> - </listitem> - </varlistentry> - </variablelist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="database-systems"> - <para>Are there any Database systems for FreeBSD?</para> - </question> - - <answer> - <para>Yes! See the <ulink - URL="http://www.FreeBSD.org/commercial/software_bycat.html#CATEGORY_DATABASE"> - Commercial Vendors</ulink> section of FreeBSD's Web site.</para> - - <para>Also see the <ulink - URL="http://www.FreeBSD.org/ports/databases.html"> - Databases</ulink> section of the Ports collection.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="oracle-support"> - <para>Can I run Oracle on FreeBSD?</para> - </question> - - <answer> - <para>Yes. The following pages tell you exactly how to setup - Linux-Oracle on FreeBSD:</para> - - <para> - <itemizedlist> - <listitem> - <para><ulink - URL="http://www.scc.nl/~marcel/howto-oracle.html"> - http://www.scc.nl/~marcel/howto-oracle.html</ulink></para> - </listitem> - - <listitem> - <para><ulink - URL="http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd"> - - http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd</ulink></para> - - </listitem> - </itemizedlist></para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="applications"> - <title>User Applications</title> - - <qandaset> - <qandaentry> - <question id="user-apps"> - <para>So, where are all the user applications?</para> - </question> - - <answer> - <para>Please take a look at - <ulink URL="http://www.FreeBSD.org/ports/">the ports - page</ulink> for info on software packages ported to FreeBSD. - The list currently tops 3400 and is growing daily, so come back - to check often or subscribe to the - <literal>freebsd-announce</literal> <link - linkend="mailing">mailing list</link> for periodic updates on - new entries.</para> - - <para>Most ports should be available for the 2.2, 3.x and 4.x - branches, and many of them should work on 2.1.x systems as - well. Each time a FreeBSD release is made, a snapshot of the - ports tree at the time of release in also included in the - <filename>ports/</filename> directory.</para> - - <para>We also support the concept of a <quote>package</quote>, - essentially no more than a gzipped binary distribution with a - little extra intelligence embedded in it for doing whatever - custom installation work is required. A package can be - installed and uninstalled again easily without having to know - the gory details of which files it includes.</para> - - <para>Use the package installation menu in - <filename>/stand/sysinstall</filename> (under the - post-configuration menu item) or invoke the - <command>pkg_add(1)</command> command on the specific package - files you're interested in installing. Package files can - usually be identified by their <filename>.tgz</filename> suffix - and CDROM distribution people will have a - <filename>packages/All</filename> directory on their CD which - contains such files. They can also be downloaded over the net - for various versions of FreeBSD at the following - locations:</para> - - <para> - <variablelist> - <varlistentry> - <term>for 2.2.8-RELEASE/2.2.8-STABLE</term> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/</ulink></para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>for 3.X-RELEASE/3.X-STABLE</term> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/</ulink></para> - - <para></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>for 4.1-RELEASE/4-STABLE</term> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/</ulink></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>for 5.X-CURRENT</term> - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current</ulink></para> - </listitem> - </varlistentry> - </variablelist></para> - - <para>or your nearest local mirror site.</para> - - <para>Note that all ports may not be available as packages since - new ones are constantly being added. It is always a good idea - to check back periodically to see which packages are available - at the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org</ulink> - master site.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="minimal-sh"> - <para>Why is <command>/bin/sh</command> so minimal? Why doesn't - FreeBSD use <command>bash</command> or another shell?</para> - </question> - - <answer> - <para>Because POSIX says that there shall be such a shell.</para> - - <para>The more complicated answer: many people need to write shell - scripts which will be portable across many systems. That's why - POSIX specifies the shell and utility commands in great detail. - Most scripts are written in Bourne shell, and because several - important programming interfaces (&man.make.1;, &man.system.3;, - &man.popen.3;, and analogues in higher-level scripting - languages like Perl and Tcl) are specified to use the Bourne - shell to interpret commands. Because the Bourne shell is so - often and widely used, it is important for it to be quick to - start, be deterministic in its behavior, and have a small - memory footprint.</para> - - <para>The existing implementation is our best effort at meeting as - many of these requirements simultaneously as we can. In order to - keep <command>/bin/sh</command> small, we have not provided many - of the convenience features that other shells have. That's why the - Ports Collection includes more featureful shells like bash, scsh, - tcsh, and zsh. (You can compare for yourself the memory - utilization of all these shells by looking at the - <quote>VSZ</quote> and <quote>RSS</quote> columns in a <command>ps - -u</command> listing.)</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="missing-libcso30"> - <para>Where do I find libc.so.3.0?</para> - </question> - - <answer> - <para>You are trying to run a package built on 2.2 and later on - a 2.1.x system. Please take a look at the previous section and - get the correct port/package for your system.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="missing-libcso40"> - <para>I get a message <literal>Error: can't find - libc.so.4.0</literal></para> - </question> - - <answer> - - <para>You accidently downloaded packages meant for 4.X and 5.X - systems and attempted to install them on your 2.X or 3.X - FreeBSD system. Please download the correct version of the - packages.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="emul"> - <para>ghostscript gives lots of errors with my 386/486SX.</para> - </question> - - <answer> - <para>You don't have a math co-processor, right? - You will need to add the alternative math emulator to your - kernel; you do this by adding the following to your kernel - config file and it will be compiled in.</para> - - <programlisting>options GPL_MATH_EMULATE</programlisting> - - <para> - <note> - <para>You will need to remove the - <literal>MATH_EMULATE</literal> option when you do - this.</para> - </note></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="sco-socksys"> - <para>When I run a SCO/iBCS2 application, it bombs on - <literal>socksys</literal> (FreeBSD 3.0 and older only).</para> - </question> - - <answer> - <para>You first need to edit the - <filename>/etc/sysconfig</filename> (or <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf(5)"> - /etc/rc.conf</ulink>) file in the last section to change the - following variable to <literal>YES</literal>:</para> - - <programlisting># Set to YES if you want ibcs2 (SCO) emulation loaded at startup -ibcs2=NO</programlisting> - - <para>It will load the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ibcs2(8)">ibcs2</ulink> - kernel module at startup.</para> - - <para>You'll then need to set up /compat/ibcs2/dev to look - like:</para> - - <screen>lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 X0R@ -> /dev/null -lrwxr-xr-x 1 root wheel 7 Oct 15 22:20 nfsd@ -> socksys --rw-rw-r-- 1 root wheel 0 Oct 28 12:02 null -lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 socksys@ -> /dev/null -crw-rw-rw- 1 root wheel 41, 1 Oct 15 22:14 spx</screen> - - <para>You just need socksys to go to <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?null(4)">/dev/null</ulink> - to fake the open & close. The code in -CURRENT will handle - the rest. This is much cleaner than the way it was done before. - If you want the <devicename>spx</devicename> driver for a local - socket X connection, define <literal>SPX_HACK</literal> when - you compile the system.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="configure-inn"> - <para>How do I configure INN (Internet News) for my machine?</para> - </question> - - <answer> - <para>After installing the inn package or port, an excellent - place to start is <ulink - URL="http://www.cis.ohio-state.edu/~barr/INN.html">Dave Barr's - INN Page</ulink> where you'll find the INN FAQ.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ms-frontpage"> - <para>What version of Microsoft FrontPage should I get?</para> - </question> - - <answer> - <para>Use the Port, Luke! A pre-patched version of Apache is - available in the ports tree.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="java"> - <para>Does FreeBSD support Java?</para> - </question> - - <answer> - <para>Yes. Please see <ulink - URL="http://www.FreeBSD.org/java/"> - http://www.FreeBSD.org/java/</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ports-3x"> - <para>Why can't I build this port on my 3.X-STABLE machine?</para> - </question> - - <answer> - <para>If you're running a FreeBSD version that lags - significantly behind -CURRENT or -STABLE, you may need a ports - upgrade kit from <ulink URL="http://www.FreeBSD.org/ports/"> - http://www.FreeBSD.org/ports/</ulink>. If you are up to date, - then someone might have committed a change to the port which - works for -CURRENT but which broke the port for -STABLE. Please - submit a bug report on this with the - <command>send-pr(1)</command> command, since the ports - collection is supposed to work for both the -CURRENT and - -STABLE branches.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="find-ldso"> - <para>Where do I find ld.so?</para> - </question> - - <answer> - <para>If you want to run some aout applications like - Netscape Navigator on an Elf'ened machine such as 3.1-R or - later, it would need <filename>/usr/libexec/ld.so</filename> - and some aout libs. They are included in the compat22 - distribution. Use <filename>/stand/sysinstall</filename> or - <filename>install.sh</filename> in the compat22 subdirectory - and install it. Also read ERRATAs for 3.1-R and 3.2-R.</para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="kernelconfig"> - <title>Kernel Configuration</title> - - <qandaset> - <qandaentry> - <question id="make-kernel"> - <para>I'd like to customize my kernel. Is it difficult?</para> - </question> - - <answer> - <para>Not at all! Check out the <ulink - URL="../handbook/kernelconfig.html"> - kernel config section of the Handbook</ulink>.</para> - - <para> - <note> - <para>I recommend making a dated snapshot of your kernel - in <filename>kernel.YYMMDD</filename> after you get it all - working, that way if you do something dire the next time - you play with your configuration you can boot that kernel - instead of having to go all the way back to - <filename>kernel.GENERIC</filename>. This is particularly - important if you're now booting off a controller that isn't - supported in the GENERIC kernel (yes, personal - experience).</para> - </note></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="missing-hw-float"> - <para>My kernel compiles fail because - <literal>_hw_float</literal> is missing.</para> - </question> - - <answer> - <para>Let me guess. You removed <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?npx(4)">npx0</ulink> - from your kernel configuration file because you don't have a - math co-processor, right? Wrong! :-) The - <devicename>npx0</devicename> is - <emphasis>MANDATORY</emphasis>. Even if you don't have a - mathematic co-processor, you <emphasis remap=bf>must</emphasis> - include the <devicename>npx0</devicename> device.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="why-kernel-big"> - <para>Why is my kernel so big (over 10MB)?</para> - </question> - - <answer> - <para>Chances are, you compiled your kernel in - <emphasis>debug mode</emphasis>. Kernels built in debug - mode contain many symbols that are used for debugging, thus - greatly increasing the size of the kernel. Note that if you - running a FreeBSD 3.0 or later system, there will be little - or no performance decrease from running a debug kernel, - and it is useful to keep one around in case of a system - panic.</para> - - <para>However, if you are running low on disk space, or - you simply don't want to run a debug kernel, make sure - that both of the following are true:</para> - - <itemizedlist> - <listitem> - <para>You do not have a line in your kernel - configuration file that reads:</para> - - <programlisting>makeoptions DEBUG=-g</programlisting> - </listitem> - - <listitem> - <para>You are not running <command>config</command> with - the <option>-g</option> option.</para> - </listitem> - </itemizedlist> - - <para>Both of the above situations will cause your kernel to - be built in debug mode. As long as you make sure you follow - the steps above, you can build your kernel normally, and you - should notice a fairly large size decrease; most kernels - tend to be around 1.5MB to 2MB.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="multiport-serial-interrupts"> - <para>Interrupt conflicts with multi-port serial code.</para> - </question> - - <answer> - <para><emphasis remap=bf>Q.</emphasis> When I compile a kernel - with multi-port serial code, it tells me that only the first - port is probed and the rest skipped due to interrupt conflicts. - How do I fix this?</para> - - <para><emphasis remap=bf>A.</emphasis> The problem here is that - FreeBSD has code built-in to keep the kernel from getting - trashed due to hardware or software conflicts. The way to fix - this is to leave out the IRQ settings on all but one port. Here - is a example:</para> - - <programlisting># -# Multiport high-speed serial line - 16550 UARTS -# -device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr -device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr -device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr -device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="qic-4080"> - <para>How do I enable support for QIC-40/80 drives?</para> - </question> - - <answer> - <para>You need to uncomment the following line in the generic - config file (or add it to your config file), add a - <literal>flags 0x1</literal> on the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?fdc(4)">fdc</ulink> - line and recompile.</para> - -<programlisting>controller fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 flags 0x1 vector fdintr -disk fd0 at fdc0 drive 0 ^^^^^^^^^ -disk fd1 at fdc0 drive 1 -#tape ft0 at fdc0 drive 2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</programlisting> - - <para>Next, you create a device called - <filename>/dev/ft0</filename> by going into - <filename>/dev</filename> and run the following command:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV ft0</userinput></screen> - - <para>for the first device. <devicename>ft1</devicename> for a - second one and so on.</para> - - <para>You will have a device called <filename>/dev/ft0</filename>, - which you can write to through a special program to manage it - called <command>fd</command> - see the man page on <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ft">ft</ulink> for - further details.</para> - - <para>Versions previous to <option>-CURRENT</option> also had - some trouble dealing with bad tape media; if you have trouble - where <command>ft</command> seems to go back and forth over the - same spot, try grabbing the latest version of - <command>ft</command> from - <filename>/usr/src/sbin/ft</filename> in - <option>-CURRENT</option> and try that.</para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="admin"> - <title>System Administration</title> - - <qandaset> - <qandaentry> - <question id="startup-config-files"> - <para>Where are the system start-up configuration files?</para> - </question> - - <answer> - - <para>From 2.0.5R to 2.2.1R, the primary configuration file is - <filename>/etc/sysconfig</filename>. All the options are to be - specified in this file and other files such as <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc(8)">/etc/rc</ulink> - and <filename>/etc/netstart</filename> just include it.</para> - - <para>Look in the <filename>/etc/sysconfig</filename> file and - change the value to match your system. This file is filled with - comments to show what to put in there.</para> - - <para>In post-2.2.1 and 3.0, <filename>/etc/sysconfig</filename> - was renamed to a more self-describing <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf(5)">rc.conf</ulink> - file and the syntax cleaned up a bit in the process. - <filename>/etc/netstart</filename> was also renamed to - <filename>/etc/rc.network</filename> so that all files could be - copied with a <command><ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?cp(1)">cp</ulink> - /usr/src/etc/rc* /etc</command> command.</para> - - <para>And, in 3.1 and later, <filename>/etc/rc.conf</filename> - has been moved to <filename>/etc/defaults/rc.conf</filename>. - <emphasis>Do not edit this file!</emphasis> Instead, if there - is any entry in <filename>/etc/defaults/rc.conf</filename> that - you want to change, you should copy the line into - <filename>/etc/rc.conf</filename> and change it there.</para> - - <para>For example, if you wish to start named, the DNS server - included with FreeBSD in FreeBSD 3.1 or later, all you need to - do is:</para> - <screen>&prompt.root; <userinput>echo named_enable="YES" >> /etc/rc.conf</userinput></screen> - - <para>To start up local services in FreeBSD 3.1 or later, place - shell scripts in the <filename>/usr/local/etc.rd</filename> - directory. These shell scripts should be set executable, and - end with a .sh. In FreeBSD 3.0 and earlier releases, you should - edit the <filename>/etc/rc.local</filename> file.</para> - - <para>The <filename>/etc/rc.serial</filename> is for serial port - initialization (e.g. locking the port characteristics, and so - on.).</para> - - <para>The <filename>/etc/rc.i386</filename> is for Intel-specifics - settings, such as iBCS2 emulation or the PC system console - configuration.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="adding-users"> - <para>How do I add a user easily?</para> - </question> - - <answer> - <para>Use the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?adduser">adduser</ulink> - command. For more complicated usage, the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?pw">pw</ulink> - command.</para> - - <para>To remove the user again, use the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rmuser">rmuser</ulink> - command. Once again, <command>pw</command> will work as - well.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="adding-disks"> - <para>How can I add my new hard disk to my FreeBSD system?</para> - </question> - - <answer> - <para>See the Disk Formatting Tutorial at <ulink - URL="../tutorials/formatting-media/"> - www.FreeBSD.org</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="removable-drives"> - <para>I have a new removable drive, how do I use it?</para> - </question> - - <answer> - - <para>Whether it's a removable drive like a ZIP or an EZ drive - (or even a floppy, if you want to use it that way), or a new - hard disk, once it's installed and recognized by the system, - and you have your cartridge/floppy/whatever slotted in, things - are pretty much the same for all devices.</para> - - <para><anchor id="disklabel">(this section is based on <ulink - URL="http://www.vmunix.com/mark/FreeBSD/ZIP-FAQ.html"> - Mark Mayo's ZIP FAQ</ulink>)</para> - - <para>If it's a ZIP drive or a floppy , you've already got a DOS - filesystem on it, you can use a command like this:</para> - - <screen>&prompt.root; <userinput>mount -t msdos /dev/fd0c /floppy</userinput></screen> - - <para>if it's a floppy, or this:</para> - - <screen>&prompt.root; <userinput>mount -t msdos /dev/da2s4 /zip</userinput></screen> - - <para>for a ZIP disk with the factory configuration.</para> - - <para>For other disks, see how they're laid out using - <command>fdisk</command> or - <filename>/stand/sysinstall</filename>.</para> - - <para>The rest of the examples will be for a ZIP drive on da2, - the third SCSI disk.</para> - - <para>Unless it's a floppy, or a removable you plan on sharing - with other people, it's probably a better idea to stick a BSD - file system on it. You'll get long filename support, at least a - 2X improvement in performance, and a lot more stability. First, - you need to redo the DOS-level partitions/filesystems. You can - either use <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?fdisk">fdisk</ulink> or - <filename>/stand/sysinstall</filename>, or for a small drive - that you don't want to bother with multiple operating system - support on, just blow away the whole FAT partition table - (slices) and just use the BSD partitioning:</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda2 count=2</userinput> -&prompt.root; <userinput>disklabel -Brw da2 auto</userinput></screen> - - <para>You can use disklabel or - <filename>/stand/sysinstall</filename> to create multiple BSD - partitions. You'll certainly want to do this if you're adding - swap space on a fixed disk, but it's probably irrelevant on a - removable drive like a ZIP.</para> - - <para>Finally, create a new file system, this one's on our ZIP - drive using the whole disk:</para> - - <screen>&prompt.root; <userinput>newfs /dev/rda2c</userinput></screen> - - <para>and mount it:</para> - - <screen>&prompt.root; <userinput>mount /dev/da2c /zip</userinput></screen> - - <para>and it's probably a good idea to add a line like this to - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?fstab"> - /etc/fstab</ulink> so you can just type - <command>mount /zip</command> in the future:</para> - - <programlisting>/dev/da2c /zip ffs rw,noauto 0 0</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="root-not-found-cron-errors"> - <para>Why do I keep getting messages like <errorname>root: not - found</errorname> after editing my crontab file?</para> - </question> - - <answer> - <para>This is normally caused by editing the system crontab - (<filename>/etc/crontab</filename>) and then using - &man.crontab.1; to install it:</para> - - <screen>&prompt.root; <userinput>crontab /etc/crontab</userinput></screen> - - <para>This is not the correct way to do things. The system - crontab has a different format to the per-user crontabs - which &man.crontab.1; updates (the &man.crontab.5; manual - page explains the differences in more detail).</para> - - <para>If this is what you did, you should delete the - <filename>/var/cron/tabs/root</filename>, since it will - simply be a copy of <filename>/etc/crontab</filename>, - in the wrong format. Next time, when you edit - <filename>/etc/crontab</filename>, you should not do - anything to inform &man.cron.8; of the changes, since it - will notice them automatically.</para> - - <para>The actual reason for the error is that the system - crontab has an extra field, specifying which user to run the - command as. In the default system crontab provided with - FreeBSD, this is <username>root</username> for all entries. - When this crontab is used as the <username>root</username> - user's crontab (which is <emphasis>not</emphasis> the - same as the system crontab), &man.cron.8; assumes the string - <literal>root</literal> is the first word of the command to - execute, but no such command exists.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="rcconf-readonly"> - <para>I made a mistake in <filename>rc.conf</filename>, - or another startup file, and - now I can't edit it because the filesystem is read-only. - What should I do?</para> - </question> - - <answer> - <para>When you get the prompt to enter the shell - pathname, simply press <literal>ENTER</literal>, and run - <command>mount /</command> to re-mount the root filesystem in - read/write mode. You may also need to run <command>mount -a -t - ufs</command> to mount the filesystem where your favourite - editor is defined. If your favourite editor is on a network - filesystem, you will need to either configure the network - manually before you can mount network filesystems, or use an - editor which resides on a local filesystem, such as - &man.ed.1;.</para> - - <para>If you intend to use a full screen editor such - as &man.vi.1; or &man.emacs.1;, you may also need to - run <command>export TERM=cons25</command> so that these - editors can load the correct data from the &man.termcap.5; - database.</para> - - <para>Once you have performed these steps, you can edit - <filename>/etc/rc.conf</filename> as you usually would - to fix the syntax error. The error message displayed - immediately after the kernel boot messages should tell you - the number of the line in the file which is at fault.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="mount-dos"> - <para>How do I mount a secondary DOS partition?</para> - </question> - - <answer> - - <para>The secondary DOS partitions are found after ALL the primary - partitions. For example, if you have an <quote>E</quote> - partition as the second DOS partition on the second SCSI drive, - you need to create the special files for <quote>slice 5</quote> - in /dev, then mount /dev/da1s5:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV da1s5</userinput> -&prompt.root; <userinput>mount -t msdos /dev/da1s5 /dos/e</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="mount-foreign-fs"> - <para>Can I mount other foreign filesystems under FreeBSD?</para> - </question> - - <answer> - <para><emphasis remap=bf> Digital UNIX</emphasis> UFS CDROMs can - be mounted directly on FreeBSD. Mounting disk partitions from - Digital UNIX and other systems that support UFS may be more - complex, depending on the details of the disk partitioning for - the operating system in question.</para> - - <para><emphasis remap=bf> Linux</emphasis>: 2.2 and later have - support for <emphasis remap=bf>ext2fs</emphasis> partitions. - See <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?mount_ext2fs">mount_ext2fs</ulink> - for more information.</para> - - <para><emphasis remap=bf> NT</emphasis>: A read-only NTFS driver - exists for FreeBSD. For more information, see this tutorial by - Mark Ovens at - <ulink URL="http://ukug.uk.freebsd.org/~mark/ntfs_install.html"> - http://ukug.uk.freebsd.org/~mark/ntfs_install.html</ulink>.</para> - - <para>Any other information on this subject would be - appreciated.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="nt-bootloader"> - <para>How can I use the NT loader to boot FreeBSD?</para> - </question> - - <answer> - <para>This procedure is slightly different for 2.2.x and 3.x - (with the 3-stage boot) systems.</para> - - <para>The general idea is that you copy the first sector of your - native root FreeBSD partition into a file in the DOS/NT - partition. Assuming you name that file something like - <filename>c:\bootsect.bsd</filename> (inspired by - <filename>c:\bootsect.dos</filename>), you can then edit the - <filename>c:\boot.ini</filename> file to come up with something - like this:</para> - - <programlisting>[boot loader] -timeout=30 -default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS -[operating systems] -multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" -C:\BOOTSECT.BSD="FreeBSD" -C:\="DOS"</programlisting> - - <para>For 2.2.x systems this procedure assumes that DOS, NT, - FreeBSD, or whatever have been installed into their respective - fdisk partitions on the <emphasis remap=bf>same</emphasis> - disk. In my case DOS & NT are in the first fdisk partition - and FreeBSD is in the second. I also installed FreeBSD to boot - from its native partition, <emphasis remap=bf>not</emphasis> - the disk MBR.</para> - - <para>Mount a DOS-formatted floppy (if you've converted to NTFS) - or the FAT partition, under, say, - <filename>/mnt</filename>.</para> - - <screen>&prompt.root; <userinput>dd if=/dev/rda0a of=/mnt/bootsect.bsd bs=512 count=1</userinput></screen> - - <para>Reboot into DOS or NT. NTFS users copy the - <filename>bootsect.bsd</filename> and/or the - <filename>bootsect.lnx</filename> file from the floppy to - <filename>C:\</filename>. Modify the attributes (permissions) - on <filename>boot.ini</filename> with:</para> - - <screen><prompt>C:\></prompt> <userinput>attrib -s -r c:\boot.ini</userinput></screen> - - <para>Edit to add the appropriate entries from the example - <filename>boot.ini</filename> above, and restore the - attributes:</para> - - <screen><prompt>C:\></prompt> <userinput>attrib +s +r c:\boot.ini</userinput></screen> - - <para>If FreeBSD is booting from the MBR, restore it with the DOS - <command>fdisk</command> command after you reconfigure them to - boot from their native partitions.</para> - - <para>For FreeBSD 3.x systems the procedure is somewhat - simpler.</para> - - <para>If FreeBSD is installed on the same disk as the NT boot - partition simply copy <filename>/boot/boot1</filename> to - <filename>C:\BOOTSECT.BSD</filename> However, if FreeBSD is - installed on a different disk <filename>/boot/boot1</filename> - will not work, <filename>/boot/boot0</filename> is needed. - - <warning> - <para>DO NOT SIMPLY COPY <filename>/boot/boot0</filename> - INSTEAD OF <filename>/boot/boot1</filename>, YOU WILL - OVERWRITE YOUR PARTITION TABLE AND RENDER YOUR COMPUTER - UN-BOOTABLE!</para> - </warning> - - <filename>/boot/boot0</filename> needs to be installed using - sysinstall by selecting the FreeBSD boot manager on the - screen which asks if you wish to use a boot manager. This is - because <filename>/boot/boot0</filename> has the partition - table area filled with NULL characters but sysinstall copies - the partition table before copying - <filename>/boot/boot0</filename> to the MBR.</para> - - <para>When the FreeBSD boot manager runs it records the last - OS booted by setting the active flag on the partition table - entry for that OS and then writes the whole 512-bytes of itself - back to the MBR so if you just copy - <filename>/boot/boot0</filename> to - <filename>C:\BOOTSECT.BSD</filename> then it writes an empty - partition table, with the active flag set on one entry, to the - MBR.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="lilo-bootloader"> - <para>How do I boot FreeBSD and Linux from LILO?</para> - </question> - - <answer> - <para>If you have FreeBSD and Linux on the same disk, just follow - LILO's installation instructions for booting a non-Linux - operating system. Very briefly, these are:</para> - - <para>Boot Linux, and add the following lines to - <filename>/etc/lilo.conf</filename>: - <programlisting>other=/dev/hda2 - table=/dev/hda - label=FreeBSD</programlisting> - - (the above assumes that your FreeBSD slice is known to Linux - as <filename>/dev/hda2</filename>; tailor to suit your setup). - Then, run <command>lilo</command> as root and you should be - done.</para> - - <para>If FreeBSD resides on another disk, you need to add - <literal>loader=/boot/chain.b</literal> to the LILO entry. - For example: - <programlisting>other=/dev/dab4 - table=/dev/dab - loader=/boot/chain.b - label=FreeBSD</programlisting></para> - - <para>In some cases you may need to specify the BIOS drive number - to the FreeBSD boot loader to successfully boot off the second - disk. For example, if your FreeBSD SCSI disk is probed by BIOS - as BIOS disk 1, at the FreeBSD boot loader prompt you need to - specify:</para> - - <screen>Boot: <userinput>1:da(0,a)/kernel</userinput></screen> - - <para>On FreeBSD 2.2.5 and later, you can configure <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?boot(8)">boot(8)</ulink> - to automatically do this for you at boot time.</para> - - <para>The <ulink - URL="http://sunsite.unc.edu/LDP/HOWTO/mini/Linux+FreeBSD.html"> - Linux+FreeBSD mini-HOWTO</ulink> is a good reference for - FreeBSD and Linux interoperability issues.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="booteasy-loader"> - <para>How do I boot FreeBSD and Linux using BootEasy?</para> - </question> - - <answer> - <para>Install LILO at the start of your Linux boot partition - instead of in the Master Boot Record. You can then boot LILO - from BootEasy.</para> - - <para>If you're running Windows-95 and Linux this is recommended - anyway, to make it simpler to get Linux booting again if you - should need to reinstall Windows95 (which is a Jealous - Operating System, and will bear no other Operating Systems in - the Master Boot Record).</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dangerously-dedicated"> - <para>Will a <quote>dangerously dedicated</quote> disk endanger - my health?</para> - </question> - - <answer> - - <para><anchor id="dedicate">The installation procedure allows - you to chose two different methods in partitioning your - harddisk(s). The default way makes it compatible with other - operating systems on the same machine, by using fdisk table - entries (called <quote>slices</quote> in FreeBSD), with a - FreeBSD slice that employs partitions of its own. Optionally, - one can chose to install a boot-selector to switch between the - possible operating systems on the disk(s). The alternative uses - the entire disk for FreeBSD, and makes no attempt to be - compatible with other operating systems.</para> - - <para>So why it is called <quote>dangerous</quote>? A disk in - this mode doesn't contain what normal PC utilities would - consider a valid fdisk table. Depending on how well they have - been designed, they might complain at you once they are getting - in contact with such a disk, or even worse, they might damage - the BSD bootstrap without even asking or notifying you. In - addition, the <quote>dangerously dedicated</quote> disk's - layout is known to confuse many BIOSsen, including those from - AWARD (eg. as found in HP Netserver and Micronics systems as - well as many others) and Symbios/NCR (for the popular 53C8xx - range of SCSI controllers). This isn't a complete list, there - are more. Symptoms of this confusion include the <quote>read - error</quote> message printed by the FreeBSD bootstrap when it - can't find itself, as well as system lockups when - booting.</para> - - <para>Why have this mode at all then? It only saves a few kbytes - of disk space, and it can cause real problems for a new - installation. <quote>Dangerously dedicated</quote> mode's - origins lie in a desire to avoid one of the most common - problems plaguing new FreeBSD installers - matching the BIOS - <quote>geometry</quote> numbers for a disk to the disk - itself.</para> - - <para><quote>Geometry</quote> is an outdated concept, but one - still at the heart of the PC's BIOS and its interaction with - disks. When the FreeBSD installer creates slices, it has to - record the location of these slices on the disk in a fashion - that corresponds with the way the BIOS expects to find them. If - it gets it wrong, you won't be able to boot.</para> - - <para><quote>Dangerously dedicated</quote> mode tries to work - around this by making the problem simpler. In some cases, it - gets it right. But it's meant to be used as a last-ditch - alternative - there are better ways to solve the problem 99 - times out of 100.</para> - - <para>So, how do you avoid the need for <quote>DD</quote> mode - when you're installing? Start by making a note of the geometry - that your BIOS claims to be using for your disks. You can - arrange to have the kernel print this as it boots by specifying - <option>-v</option> at the <literal>boot:</literal> prompt, or - using <command>boot -v</command> in the loader. Just before the - installer starts, the kernel will print a list of BIOS - geometries. Don't panic - wait for the installer to start and - then use scrollback to read the numbers. Typically the BIOS - disk units will be in the same order that FreeBSD lists your - disks, first IDE, then SCSI.</para> - - <para>When you're slicing up your disk, check that the disk - geometry displayed in the FDISK screen is correct (ie. it - matches the BIOS numbers); if it's wrong, use the - <literal>g</literal> key to fix it. You may have to do this if - there's absolutely nothing on the disk, or if the disk has been - moved from another system. Note that this is only an issue with - the disk that you're going to boot from; FreeBSD will sort - itself out just fine with any other disks you may have.</para> - - <para>Once you've got the BIOS and FreeBSD agreeing about the - geometry of the disk, your problems are almost guaranteed to be - over, and with no need for <quote>DD</quote> mode at all. If, - however, you are still greeted with the dreaded <quote>read - error</quote> message when you try to boot, it's time to cross - your fingers and go for it - there's nothing left to - lose.</para> - - <para>To return a <quote>dangerously dedicated</quote> disk - for normal PC use, there are basically two options. The first - is, you write enough NULL bytes over the MBR to make any - subsequent installation believe this to be a blank disk. You - can do this for example with</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda0 count=15</userinput></screen> - - <para>Alternatively, the undocumented DOS - <quote>feature</quote></para> - - <screen><prompt>C:\></prompt> <userinput>fdisk /mbr</userinput></screen> - - <para>will to install a new master boot record as well, thus - clobbering the BSD bootstrap.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="add-swap-space"> - <para>How can I add more swap space?</para> - </question> - - <answer> - - <para>The best way is to increase the size of your swap partition, - or take advantage of this convenient excuse to add another - disk. The general rule of thumb is to have around 2x the swap - space as you have main memory. However, if you have a very - small amount of main memory you may want to configure swap - beyond that. It is also a good idea to configure sufficient - swap relative to anticipated future memory upgrades so you do - not have to futz with your swap configuration later.</para> - - <para>Adding swap onto a separate disk makes things faster than - simply adding swap onto the same disk. As an example, if you - are compiling source located on one disk, and the swap is on - another disk, this is much faster than both swap and compile on - the same disk. This is true for SCSI disks specifically.</para> - - <para>When you have several disks, configuring a swap partition on - each one is usually beneficial, even if you wind up putting - swap on a work disk. Typically, each fast disk in your system - should have some swap configured. FreeBSD supports up to 4 - interleaved swap devices by default. When configuring multiple - swap partitions you generally want to make them all about the - same size, but people sometimes make their primary swap - parition larger in order to accomodate a kernel core dump. Your - primary swap partition must be at least as large as main memory - in order to be able to accomodate a kernel core.</para> - - <para>IDE drives are not able to allow access to both drives on - the same channel at the same time (FreeBSD doesn't support mode - 4, so all IDE disk I/O is <quote>programmed</quote>). I would - still suggest putting your swap on a separate drive however. - The drives are so cheap, it is not worth worrying about.</para> - - <para>Swapping over NFS is only recommended if you do not have a - local disk to swap to. Swapping over NFS is slow and - inefficient in FreeBSD releases prior to 4.x, but reasonably - fast in releases greater or equal to 4.0. Even so, it will be - limited to the network bandwidth available and puts an - additional burden on the NFS server.</para> - - <para>Here is an example for 64Mb vn-swap - (<filename>/usr/swap0</filename>, though of course you can use - any name that you want).</para> - - <para>Make sure your kernel was built with the line</para> - - <programlisting>pseudo-device vn 1 #Vnode driver (turns a file into a device)</programlisting> - - <para>in your config-file. The GENERIC kernel already contains - this.</para> - - <para> - <orderedlist> - <listitem> - <para>create a vn-device</para> - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV vn0</userinput></screen> - - </listitem> - - <listitem> - <para>create a swapfile - (<filename>/usr/swap0</filename>)</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen> - - </listitem> - - <listitem> - <para>set proper permissions on - (<filename>/usr/swap0</filename>)</para> - - <screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen> - - </listitem> - - <listitem> - <para>enable the swap file in - <filename>/etc/rc.conf</filename></para> - - <programlisting>swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.</programlisting> - - </listitem> - - <listitem> - <para>reboot the machine</para> - </listitem> - </orderedlist></para> - - <para>To enable the swap file immediately, type</para> - - <screen>&prompt.root; <userinput>vnconfig -ce /dev/vn0c /usr/swap0 swap</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="printer-setup"> - <para>I'm having problems setting up my printer.</para> - </question> - - <answer> - - <para>Please have a look at the Handbook entry on printing. It - should cover most of your problem. See the <ulink - URL="../handbook/printing.html"> - Handbook entry on printing.</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="keyboard-mappings"> - <para>The keyboard mappings are wrong for my system.</para> - </question> - - <answer> - <para>The kbdcontrol program has an option to load a keyboard - map file. Under <filename>/usr/share/syscons/keymaps</filename> - are a number of map files. Choose the one relevant to your - system and load it.</para> - - <screen>&prompt.root; <userinput>kbdcontrol -l uk.iso</userinput></screen> - - <para>Both the <filename>/usr/share/syscons/keymaps</filename> - and the <filename>.kbd</filename> extension are assumed by - <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?kbdcontrol"> - kbdcontrol</ulink>.</para> - - <para>This can be configured in <filename>/etc/sysconfig</filename> - (or <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf(5)"> - rc.conf</ulink>). See the appropriate comments in this - file.</para> - - <para>In 2.0.5R and later, everything related to text fonts, - keyboard mapping is in - <filename>/usr/share/examples/syscons</filename>.</para> - - <para>The following mappings are currently supported:</para> - - <para> - <itemizedlist> - <listitem> - <para>Belgian ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Brazilian 275 keyboard Codepage 850 </para> - </listitem> - - <listitem> - <para>Brazilian 275 keyboard ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Danish Codepage 865 </para> - </listitem> - - <listitem> - <para>Danish ISO-8859-1 </para> - </listitem> - - <listitem> - <para>French ISO-8859-1 </para> - </listitem> - - <listitem> - <para>German Codepage 850 </para> - </listitem> - - <listitem> - <para>German ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Italian ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Japanese 106 </para> - </listitem> - - <listitem> - <para>Japanese 106x </para> - </listitem> - - <listitem> - <para>Latin American </para> - </listitem> - - <listitem> - <para>Norwegian ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Polish ISO-8859-2 (programmer's) </para> - </listitem> - - <listitem> - <para>Russian Codepage 866 (alternative) </para> - </listitem> - - <listitem> - <para>Russian koi8-r (shift) </para> - </listitem> - - <listitem> - <para>Russian koi8-r </para> - </listitem> - - <listitem> - <para>Spanish ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Swedish Codepage 850 </para> - </listitem> - - <listitem> - <para>Swedish ISO-8859-1 </para> - </listitem> - - <listitem> - <para>Swiss-German ISO-8859-1 </para> - </listitem> - - <listitem> - <para>United Kingdom Codepage 850 </para> - </listitem> - - <listitem> - <para>United Kingdom ISO-8859-1 </para> - </listitem> - - <listitem> - <para>United States of America ISO-8859-1 </para> - </listitem> - - <listitem> - <para>United States of America dvorak </para> - </listitem> - - <listitem> - <para>United States of America dvorakx </para> - </listitem> - </itemizedlist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="user-quotas"> - <para>I can't get user quotas to work properly.</para> - </question> - - <answer> - - <para> - <orderedlist> - <listitem> - <para>Don't turn on quotas on <filename>/</filename>,</para> - </listitem> - - <listitem> - <para>Put the quota file on the file system that the quotas - are to be enforced on. ie:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Filesystem</entry> - <entry>Quota file</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>/usr</filename></entry> - <entry><filename>/usr/admin/quotas</filename></entry> - </row> - - <row> - <entry><filename>/home</filename></entry> - <entry><filename>/home/admin/quotas</filename></entry> - </row> - - <row> - <entry>…</entry> - <entry>…</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </orderedlist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="inappropriate-ccd"> - <para>What's inappropriate about my ccd?</para> - </question> - - <answer> - <para>The symptom of this is:</para> - - <screen>&prompt.root; <userinput>ccdconfig -C</userinput> -ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format</screen> - - <para>This usually happens when you are trying to concatenate - the <literal>c</literal> partitions, which default to type - <literal>unused</literal>. The ccd driver requires the - underlying partition type to be FS_BSDFFS. Edit the disklabel - of the disks you are trying to concatenate and change the types - of partitions to <literal>4.2BSD</literal>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ccd-disklabel"> - <para>Why can't I edit the disklabel on my ccd?</para> - </question> - - <answer> - <para>The symptom of this is:</para> - - <screen>&prompt.root; <userinput>disklabel ccd0</userinput> -(it prints something sensible here, so let's try to edit it) -&prompt.root; <userinput>disklabel -e ccd0</userinput> -(edit, save, quit) -disklabel: ioctl DIOCWDINFO: No disk label on disk; -use "disklabel -r" to install initial label</screen> - - <para>This is because the disklabel returned by ccd is actually - a <quote>fake</quote> one that is not really on the disk. - You can solve this problem by writing it back explicitly, - as in:</para> - - <screen>&prompt.root; <userinput>disklabel ccd0 > /tmp/disklabel.tmp</userinput> -&prompt.root; <userinput>disklabel -Rr ccd0 /tmp/disklabel.tmp</userinput> -&prompt.root; <userinput>disklabel -e ccd0</userinput> -(this will work now)</screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="sysv-ipc"> - <para>Does FreeBSD support System V IPC primitives?</para> - </question> - - <answer> - <para>Yes, FreeBSD supports System V-style IPC. This includes - shared memory, messages and semaphores. You need to add the - following lines to your kernel config to enable them.</para> - - <programlisting>options SYSVSHM -options SYSVSHM # enable shared memory -options SYSVSEM # enable for semaphores -options SYSVMSG # enable for messaging</programlisting> - - <para> - <note> - <para>In FreeBSD 3.2 and later, these options are already - part of the <emphasis>GENERIC</emphasis> kernel, which - meansthey should already be compiled into your - system.</para> - </note></para> - - <para>Recompile and install your kernel.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="uucpmail"> - <para>How do I use sendmail for mail delivery with UUCP?</para> - </question> - - <answer> - - <para>The sendmail configuration that ships with FreeBSD is - suited for sites that connect directly to the Internet. - Sites that wish to exchange their mail via UUCP must install - another sendmail configuration file.</para> - - <para>Tweaking <filename>/etc/sendmail.cf</filename> manually is - considered something for purists. Sendmail version 8 comes with - a new approach of generating config files via some <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?m4">m4</ulink> - preprocessing, where the actual hand-crafted configuration is - on a higher abstraction level. You should use the configuration - files under - <filename>/usr/src/usr.sbin/sendmail/cf</filename></para> - - <para>If you didn't install your system with full sources, - the sendmail config stuff has been broken out into a separate - source distribution tarball just for you. Assuming you've got - your CD-ROM mounted, do:</para> - - <screen>&prompt.root; <userinput>cd /cdrom/src</userinput> -&prompt.root; <userinput>cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmail</userinput></screen> - - <para>Don't panic, this is only a few hundred kilobytes in size. - The file <filename>README</filename> in the - <filename>cf</filename> directory can serve as a basic - introduction to m4 configuration.</para> - - <para>For UUCP delivery, you are best advised to use the - <literal>mailertable</literal> feature. This constitutes a - database that sendmail can use to base its routing decision - upon.</para> - - <para>First, you have to create your <filename>.mc</filename> - file. The directory - <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the - home of these files. Look around, there are already a few - examples. Assuming you have named your file - <filename>foo.mc</filename>, all you need to do in order to - convert it into a valid <filename>sendmail.cf</filename> - is:</para> - - <screen> -&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput> -&prompt.root; <userinput>make foo.cf</userinput> -&prompt.root; <userinput>cp foo.cf /etc/sendmail.cf</userinput></screen> - - <para>A typical <filename>.mc</filename> file might look - like:</para> - - - <programlisting>include(`../m4/cf.m4') -VERSIONID(`<replaceable>Your version number</replaceable>') -OSTYPE(bsd4.4) - -FEATURE(nodns) -FEATURE(nocanonify) -FEATURE(mailertable) - -define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>) -define(`UUCP_MAX_SIZE', 200000) - -MAILER(local) -MAILER(smtp) -MAILER(uucp) - -Cw <replaceable>your.alias.host.name</replaceable> -Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting> - - <para>The <literal>nodns</literal> and - <literal>nocanonify</literal> features will prevent any usage - of the DNS during mail delivery. The - <literal>UUCP_RELAY</literal> clause is needed for bizarre - reasons, don't ask. Simply put an Internet hostname there that - is able to handle .UUCP pseudo-domain addresses; most likely, - you will enter the mail relay of your ISP there.</para> - - <para>Once you've got this, you need this file called - <filename>/etc/mailertable</filename>. A typical example of - this gender again:</para> - - <programlisting># -# makemap hash /etc/mailertable.db < /etc/mailertable -# -horus.interface-business.de uucp-dom:horus -.interface-business.de uucp-dom:if-bus -interface-business.de uucp-dom:if-bus -.heep.sax.de smtp8:%1 -horus.UUCP uucp-dom:horus -if-bus.UUCP uucp-dom:if-bus -. uucp-dom:</programlisting> - - - <para>As you can see, this is part of a real-life file. The - first three lines handle special cases where domain-addressed - mail should not be sent out to the default route, but instead - to some UUCP neighbor in order to <quote>shortcut</quote> the - delivery path. The next line handles mail to the local Ethernet - domain that can be delivered using SMTP. Finally, the UUCP - neighbors are mentioned in the .UUCP pseudo-domain notation, to - allow for a <literal><replaceable>uucp-neighbor - </replaceable>!<replaceable>recipient</replaceable></literal> - override of the default rules. The last line is always a single - dot, matching everything else, with UUCP delivery to a UUCP - neighbor that serves as your universal mail gateway to the - world. All of the node names behind the - <literal>uucp-dom:</literal> keyword must be valid UUCP - neighbors, as you can verify using the command - <literal>uuname</literal>.</para> - - <para>As a reminder that this file needs to be converted into a - DBM database file before being usable, the command line to - accomplish this is best placed as a comment at the top of - the mailertable. You always have to execute this command - each time you change your mailertable.</para> - - <para>Final hint: if you are uncertain whether some particular - mail routing would work, remember the <option>-bt</option> - option to sendmail. It starts sendmail in <emphasis>address - test mode</emphasis>; simply enter <literal>0 </literal>, - followed by the address you wish to test for the mail routing. - The last line tells you the used internal mail agent, the - destination host this agent will be called with, and the - (possibly translated) address. Leave this mode by typing - Control-D.</para> - - <screen>&prompt.user; <userinput>sendmail -bt</userinput> -ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) -Enter <ruleset> <address> -<prompt>></prompt> <userinput>0 foo@interface-business.de</userinput> -rewrite: ruleset 0 input: foo @ interface-business . de -... -rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo \ -< @ interface-business . de > -<prompt>></prompt> <userinput>^D</userinput></screen> - - - </answer> - </qandaentry> - - <qandaentry> - <question id="ispmail"> - <para>How do I set up mail with a dialup connection to the - 'net?</para> - </question> - - <answer> - <para>If you've got a statically assigned IP number, you should - not need to adjust anything from the default. Set your host - name up as your assigned internet name and sendmail will do - the rest.</para> - - <para>If you've got a dynamically assigned IP number and use a - dialup <emphasis remap=bf>ppp</emphasis> connection to the - internet, you will probably be given a mailbox on your ISPs - mail server. Lets assume your ISPs domain is - <hostid role="domainname">myISP.com</hostid>, and that your user name is - <username>user</username>. Lets also assume you've - called your machine <hostid role="fqdn">bsd.home</hostid> and that your - ISP has told you that you may use - <hostid role="fqdn">relay.myISP.com</hostid> as a mail relay.</para> - - <para>In order to retrieve mail from your mailbox, you'll need - to install a retrieval agent. <application>Fetchmail</application> is a good choice as it supports - many different protocols. Usually, POP3 will be provided by - your ISP. If you've chosen to use user-ppp, you can - automatically fetch your mail when a connection to the 'net is - established with the following entry in - <filename>/etc/ppp/ppp.linkup</filename>:</para> - - <programlisting>MYADDR: - !bg su user -c fetchmail</programlisting> - - <para>If you are using <application>sendmail</application> - (as shown below) to deliver mail to non-local accounts, put - the command</para> - - <programlisting> !bg su user -c "sendmail -q"</programlisting> - - <para>after the above shown entry. This forces sendmail to - process your mailqueue as soon as the connection to the 'net - is established.</para> - - <para>I'm assuming that you have an account for - <username>user</username> on - <hostid role="fqdn">bsd.home</hostid>. In the home directory of - <username>user</username> on - <hostid role="fqdn">bsd.home</hostid>, create a - <filename>.fetchmailrc</filename> file:</para> - - <programlisting>poll myISP.com protocol pop3 fetchall pass MySecret</programlisting> - - <para>Needless to say, this file should not be readable by - anyone except <username>user</username> as it contains - the password <literal>MySecret</literal>.</para> - - <para>In order to send mail with the correct - <literal>from:</literal> header, you must tell - sendmail to use <literal>user@myISP.com</literal> rather than - <literal>user@bsd.home</literal>. You may also wish to tell - sendmail to send all mail via - <filename>relay.myISP.com</filename>, allowing quicker mail - transmission.</para> - - <para>The following <filename>.mc</filename> file should - suffice:</para> - - <programlisting>VERSIONID(`bsd.home.mc version 1.0') -OSTYPE(bsd4.4)dnl -FEATURE(nouucp)dnl -MAILER(local)dnl -MAILER(smtp)dnl -Cwlocalhost -Cwbsd.home -MASQUERADE_AS(`myISP.com')dnl -FEATURE(allmasquerade)dnl -FEATURE(masquerade_envelope)dnl -FEATURE(nocanonify)dnl -FEATURE(nodns)dnl -define(SMART_HOST, `relay.myISP.com') -Dmbsd.home -define(`confDOMAIN_NAME',`bsd.home')dnl -define(`confDELIVERY_MODE',`deferred')dnl</programlisting> - - <para>Refer to the previous section for details of how to turn - this <filename>.mc</filename> file into a - <filename>sendmail.cf</filename> file. Also, don't forget to - restart sendmail after updating sendmail.cf.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="forgot-root-pw"> - <para>Eek! I forgot the root password!</para> - </question><answer> - - <para>Don't Panic! Simply restart the system, type - <userinput>boot -s</userinput> at the Boot: prompt (just - <userinput>-s</userinput> for FreeBSD releases before 3.2) to - enter Single User mode. At the question about the shell to use, - hit ENTER. You'll be dropped to a &prompt.root; prompt. Enter - <command>mount -u /</command> to remount your root filesystem - read/write, then run <command>mount -a</command> to remount all - the filesystems. Run <command>passwd root</command> to change - the root password then run <command>exit</command> to continue - booting. </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="CAD-reboot"> - <para>How do I keep Control-Alt-Delete from rebooting the - system?</para> - </question> - - <answer> - - <para>If you are using syscons (the default console driver) - in FreeBSD 2.2.7-RELEASE or later, - build and install a new kernel with the line</para> - - <programlisting>options SC_DISABLE_REBOOT</programlisting> - - <para>in the configuration file. If you use the PCVT console - driver in FreeBSD 2.2.5-RELEASE or later, use the following - kernel configuration line instead:</para> - - <programlisting>options PCVT_CTRL_ALT_DEL</programlisting> - - <para>For older versions of FreeBSD, edit the keymap you are - using for the console and replace the <literal>boot</literal> - keywords with <literal>nop</literal>. The default keymap is - <filename>/usr/share/syscons/keymaps/us.iso.kbd</filename>. You - may have to instruct <filename>/etc/rc.conf</filename> to load - this keymap explicitly for the change to take effect. Of course - if you are using an alternate keymap for your country, you - should edit that one instead.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dos-to-unix-txt"> - <para>How do I reformat DOS text files to UNIX ones?</para> - </question> - - <answer> - - <para>Simply use this perl command:</para> - - <screen>&prompt.user; <userinput>perl -i.bak -npe 's/\r\n/\n/g' file ...</userinput></screen> - - <para>file is the file(s) to process. The modification is done - in-place, with the original file stored with a .bak - extension.</para> - - <para>Alternatively you can use the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tr">tr</ulink> - command:</para> - - <screen>&prompt.user; <userinput>tr -d '\r' < <replaceable>dos-text-file</replaceable> > <replaceable>unix-file</replaceable></userinput></screen> - - <para><replaceable>dos-text-file</replaceable> is the file - containing DOS text while <replaceable>unix-file</replaceable> - will contain the converted output. This can be quite a bit - faster than using perl.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="kill-by-name"> - <para>How do I kill processes by name?</para> - </question><answer> - - <para>Use <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?killall"> - killall</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="root-acl"> - <para>Why is su bugging me about not being in root's ACL?</para> - </question> - - <answer> - - <para>The error comes from the Kerberos distributed - authentication system. The problem isn't fatal but annoying. - You can either run su with the -K option, or uninstall - Kerberos as described in the next question.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="uninstall-kerberos"> - <para>How do I uninstall Kerberos?</para> - </question> - - <answer> - - <para>To remove Kerberos from the system, reinstall the bin - distribution for the release you are running. If you have - the CDROM, you can mount the cd (we'll assume on /cdrom) - and run</para> - - <screen>&prompt.root; <userinput>cd /cdrom/bin</userinput> -&prompt.root; <userinput>./install.sh</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="add-pty"> - <para>How do I add pseudoterminals to the system?</para> - </question> - - <answer> - - <para>If you have lots of telnet, ssh, X, or screen users, - you'll probably run out of pseudoterminals. Here's how to - add more:</para> - - <para> - <orderedlist> - <listitem> - <para>Build and install a new kernel with the line</para> - - <programlisting>pseudo-device pty 256</programlisting> - - <para>in the configuration file.</para> - </listitem> - - <listitem> - <para>Run the commands</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV pty{1,2,3,4,5,6,7}</userinput></screen> - - <para>to make 256 device nodes for the new terminals.</para> - - </listitem> - - <listitem> - <para>Edit <filename>/etc/ttys</filename> and add lines - for each of the 256 terminals. They should match the form - of the existing entries, i.e. they look like</para> - - <programlisting>ttyqc none network</programlisting> - - <para>The order of the letter designations is - <literal>tty[pqrsPQRS][0-9a-v]</literal>, using a - regular expression. </para> - </listitem> - - <listitem> - <para>Reboot the system with the new kernel and you're - ready to go.</para> - </listitem> - </orderedlist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="create-snd0"> - <para>I can't create the snd0 device!</para> - </question> - - <answer> - <para>There is no <devicename>snd</devicename> device. The name - is used as a shorthand for the various devices that make up the - FreeBSD sound driver, such as <devicename>mixer</devicename>, - <devicename>sequencer</devicename>, and - <devicename>dsp</devicename>.</para> - - <para>To create these devices you should</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="reread-rc"> - <para>How do I re-read /etc/rc.conf and re-start /etc/rc without - a reboot?</para> - </question> - - <answer> - - <para>Go into single user mode and than back to multi user - mode.</para> - - <para>On the console do:</para> - - <screen>&prompt.root; <userinput>shutdown now</userinput> -(Note: without -r or -h) - -&prompt.root; <userinput>return</userinput> -&prompt.root; <userinput>exit</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="sandbox"> - <para>What is a sandbox?</para> - </question><answer> - - <para><quote>Sandbox</quote> is a security term. It can mean - two things:</para> - - <para> - <itemizedlist> - <listitem> - - <para>A process which is placed inside a set of virtual - walls that are designed to prevent someone who breaks - into the process from being able to break into the wider - system.</para> - - <para>The process is said to be able to - <command>play</command> inside the walls. That is, - nothing the process does in regards to executing code is - supposed to be able to breech the walls so you do not - have to do a detailed audit of its code to be able to - say certain things about its security.</para> - - <para>The walls might be a userid, for example. This is - the definition used in the security and named man - pages.</para> - - <para>Take the <literal>ntalk</literal> service, for - example (see /etc/inetd.conf). This service used to run - as userid root. Now it runs as userid tty. The tty user - is a sandbox designed to make it more difficult for - someone who has successfully hacked into the system via - ntalk from being able to hack beyond that user id.</para> - </listitem> - - <listitem> - - <para>A process which is placed inside a simulation of the - machine. This is more hard-core. Basically it means that - someone who is able to break into the process may believe - that he can break into the wider machine but is, in fact, - only breaking into a simulation of that machine and not - modifying any real data.</para> - - <para>The most common way to accomplish this is to build a - simulated environment in a subdirectory and then run the - processes in that directory chroot'd (i.e. - <filename>/</filename> for that process is this - directory, not the real <filename>/</filename> of the - system).</para> - - <para>Another common use is to mount an underlying - filesystem read-only and then create a filesystem layer - on top of it that gives a process a seemingly writeable - view into that filesystem. The process may believe it is - able to write to those files, but only the process sees - the effects - other processes in the system do not, - necessarily.</para> - - <para>An attempt is made to make this sort of sandbox so - transparent that the user (or hacker) does not realize - that he is sitting in it.</para> - </listitem> - </itemizedlist></para> - - <para>UNIX implements two core sanboxes. One is at the - process level, and one is at the userid level.</para> - - <para>Every UNIX process is completely firewalled off from every - other UNIX process. One process can not modify the address - space of another. This is unlike Windows where a process - can easily overwrite the address space of any other, leading - to a crash.</para> - - <para>A UNIX process is owned by a patricular userid. If the - userid is not the root user, it serves to firewall the process - off from processes owned by other users. The userid is also - used to firewall off on-disk data.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="user-floppymount"> - <para>How do I let ordinary users mount floppies, CDROMs and other removable - media?</para> - </question> - - <answer> - <para>Ordinary users can be permitted to mount devices. Here is - how:</para> - - <procedure> - <step> - <para>As <username>root</username> set the sysctl variable - <varname>vfs.usermount</varname> to - <literal>1</literal>.</para> - - <screen>&prompt.root; <userinput>sysctl -w vfs.usermount=1</userinput></screen> - </step> - - <step> - <para>As <username>root</username> assign the appropriate - permissions to the block device associated with the - removable media.</para> - - <para>For example, to allow users to mount the first floppy - drive, use:</para> - - <screen>&prompt.root; <userinput>chmod 666 /dev/fd0</userinput></screen> - - <para>To allow users in the group - <username>operator</username> to mount the cdrom drive, - use:</para> - - <screen>&prompt.root; <userinput>chgrp operator /dev/cd0c</userinput> -&prompt.root; <userinput>chmod 640 /dev/cd0c</userinput></screen> - </step> - - <step> - <para>Finally, add the line - <literal>vfs.usermount=1</literal> to the file - <filename>/etc/sysctl.conf</filename> so that it is reset - at system boot time.</para> - </step> - </procedure> - - <para>All users can now mount the floppy - <filename>/dev/fd0</filename> onto a directory that they - own:</para> - - <screen>&prompt.user; <userinput> mkdir ~/my-mount-point</userinput> -&prompt.user; <userinput> mount -t msdos /dev/fd0 ~/my-mount-point</userinput></screen> - - <para>Users in group <username>operator</username> can now - mount the cdrom <filename>/dev/cd0c</filename> onto a - directory that they own:</para> - - <screen>&prompt.user; <userinput> mkdir ~/my-mount-point</userinput> -&prompt.user; <userinput> mount -t msdos /dev/cd0c ~/my-mount-point</userinput></screen> - - <para>Unmounting the device is simple:</para> - - <screen>&prompt.user; <userinput>umount <filename>~/my-mount-point</filename></userinput></screen> - - <para>Enabling <varname>vfs.usermount</varname>, however, has - negative security implications. A better way to access MSDOS - formatted media is to use the <ulink - URL="http://www.freebsd.org/cgi/ports.cgi?query=%5Emtools-&stype=name">mtools</ulink> package in the ports collection.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="new-huge-disk"> - <para>How do I move my system over to my huge new disk?</para> - </question> - - <answer> - <para>The best way is to reinstall the OS on the new - disk, then move the user data over. This is highly - recommended if you've been tracking -stable for more - than one release, or have updated a release instead of - installing a new one. You can install booteasy on both - disks with &man.boot0cfg.8;, and dual boot them until - you are happy with the new configuration. Skip the - next paragraph to find out how to move the data after - doing this.</para> - - <para>Should you decide not to do a fresh install, you - need to partition and label the new disk with either - <filename>/stand/sysinstall</filename>, or &man.fdisk.8; - and &man.disklabel.8;. You should also install booteasy - on both disks with &man.boot0cfg.8;, so that you can - dual boot to the old or new system after the copying - is done. See the <ulink - url="http://www.freebsd.org/tutorials/formatting-media/index.html"> - formatting-media tutorial</ulink> for details on this - process.</para> - - <para>Now you've got the new disk set up, and are ready - to move the data. Unfortunately, you can't just blindly - copy the data. Things like device files (in - <filename>/dev</filename>) and symbolic links tend to - screw that up. You need to use tools that understand - these things, which means &man.dump.8; and &man.tar.1;. - I recommend doing the data moves in single user mode, - but it's not required.</para> - - <para>You should never use anything but &man.dump.8; and - &man.restore.8; to move the root file system. The - &man.tar.1; command may work - then again, it may not. - You should also use &man.dump.8; and &man.restore.8; - if you are moving a single partition to another empty - partition. The sequence of steps to use dump to move - a partitions data to a new partition is:</para> - - <procedure> - <step> - <para>newfs the new partition.</para> - </step> - - <step> - <para>mount it on a temporary mount point.</para> - </step> - - <step> - <para>cd to that directory.</para> - </step> - - <step> - <para>dump the old partition, piping output to the - new one.</para> - </step> - </procedure> - - <para>For example, if you are going to move root to - <filename>/dev/ad1s1a</filename>, with - <filename>/mnt</filename> as the temporary mount point, - it's:</para> - - <screen>&prompt.root; <userinput>newfs /dev/ad1s1a</userinput> -&prompt.root; <userinput>mount /dev/ad1s1a</userinput> -&prompt.root; <userinput>cd /mnt</userinput> -&prompt.root; <userinput>dump 0uaf - / | restore xf -</userinput></screen> - - - <para>If you are going to rearrange your partitions - - say, splitting one into two, or combing two into one, - you may find yourself needing to move everything under - a subdirectory to a new location. Since &man.dump.8; - works with file systems, it can't do this. So you use - &man.tar.1;. The general command to move - <filename>/old</filename> to <filename>/new</filename> - for &man.tar.1; is:</para> - - <screen>&prompt.root; <userinput>(cd /old; tar cf - .) | (cd /new; tar xpf -)</userinput></screen> - - <para>If <filename>/old</filename> has file systems - mounted on that, and you - don't want to move that data or unmount them, you just - add the 'l' flag to the first &man.tar.1;:</para> - - <screen>&prompt.root; <userinput>(cd /old; tar clf - .) | (cd /new; tar xpf -).</userinput></screen> - - <para>You might prefer cpio(1), pax(1) or cpdup - (in ports/sysutils/cpdup) to tar.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="release-candidate"> - <para>I tried to update by system to the latest -STABLE, but - got -RC or -BETA! What's going on?</para> - </question> - - <answer> - <para>Short answer: it's just a name. RC stands for - <quote>Release Candidate</quote>. It signifies that a - release is imminent. In FreeBSD, -BETA is synonymous with - -RC.</para> - - <para>Long answer: FreeBSD derives its releases from one of - two places. Major, dot-zero, releases, such as - 3.0-RELEASE and 4.0-RELEASE, are branched from the head of - the development stream, commonly referred to as <link - linkend="current">-CURRENT</link>. Minor releases, such - as 3.1-RELEASE or 4.2-RELEASE, are snapshots of the active - <link linkend="stable">-STABLE</link> branch.</para> - - <para>When a release is about to be made, the branch from - which it will be derived from has to undergo a certain - process. Part of this process is a code freeze. When a - code freeze is initiated, the name of the branch is - changed to reflect that it's about to become a release. - For example, if the branch used to be called 4.0-STABLE, - its name will be changed to 4.1-RC to signify that a - release is about to be made from it. Once the release, - 4.1-RELEASE in this example, has been made, the branch - will be renamed to 4.1-STABLE.</para> - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="x"> - <title>The X Window System and Virtual Consoles</title> - - <qandaset> - <qandaentry> - <question id="running-X"> - <para>I want to run X, how do I go about it?</para> - </question> - - <answer> - - <para>The easiest way is to simply specify that you want to - run X during the installation process.</para> - - <para>Then read and follow the documentation on the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=xf86config"> - xf86config</ulink> tool, which assists you in configuring - XFree86(tm) for your particular graphics card/mouse/etc.</para> - - <para>You may also wish to investigate the Xaccel server. - See the section on <link linkend="xig">Xi Graphics</link> or - <link linkend="metrox">Metro Link</link> for more details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="x-and-moused"> - <para>Why doesn't my mouse work with X?</para> - </question> - - <answer> - <para>If you are using syscons (the default console driver), - you can configure FreeBSD to support a mouse pointer on each - virtual screen. In order to avoid conflicting with X, syscons - supports a virtual device called - <filename>/dev/sysmouse</filename>. All mouse events received - from the real mouse device are written to the sysmouse device - via moused. If you wish to use your mouse on one or more - virtual consoles, <emphasis remap=bf>and</emphasis> use X, see - <xref linkend="moused" remap="another section"> and set up - moused.</para> - - <para>Then edit <filename>/etc/XF86Config</filename> and make - sure you have the following lines.</para> - - <programlisting> -Section Pointer -Protocol "SysMouse" -Device "/dev/sysmouse" -.....</programlisting> - - <para>The above example is for XFree86 3.3.2 or later. For - earlier versions, the <emphasis>Protocol</emphasis> should be - <emphasis>MouseSystems</emphasis>.</para> - - <para>Some people prefer to use <filename>/dev/mouse</filename> - under X. To make this work, <filename>/dev/mouse</filename> - should be linked to <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sysmouse"> - /dev/sysmouse</ulink>:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>rm -f mouse</userinput> -&prompt.root; <userinput>ln -s sysmouse mouse</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="x-and-wheel"> - <para>My mouse has a fancy wheel. Can I use it in X?</para> - </question> - - <answer> - <para>Yes. But you need to customize X client programs. See <ulink - URL="http://www.inria.fr/koala/colas/mouse-wheel-scroll/"> - Colas Nahaboo's web page - (http://www.inria.fr/koala/colas/mouse-wheel-scroll/) - </ulink>.</para> - - <para>If you want to use the <application>imwheel</application> - program, just follow these simple steps.</para> - - <orderedlist> - <listitem> - <para>Translate the Wheel Events</para> - - <para>The <application>imwheel</application> program - works by translating mouse button 4 and mouse button 5 - events into key events. Thus, you have to get the - mouse driver to translate mouse wheel events to button - 4 and 5 events. There are two ways of doing this, the - first way is to have &man.moused.8; do the - translation. The second way is for the X server - itself to do the event translation.</para> - - <orderedlist> - <listitem> - <para>Using &man.moused.8; to Translate Wheel - Events</para> - - <para>To have &man.moused.8; perform the event - translations, simply add <option>-z 4</option> to - the command line used to start &man.moused.8;. - For example, if you normally start &man.moused.8; - via <command>moused -p /dev/psm0</command> you - would start it by entering <command>moused -p - /dev/psm0 -z 4</command> instead. If you start - &man.moused.8; automatically during bootup via - <filename>/etc/rc.conf</filename>, you can simply - add <option>-z 4</option> to the - <varname>moused_flags</varname> variable in - <filename>/etc/rc.conf</filename>.</para> - - <para>You now need to tell X that you have a 5 - button mouse. To do this, simply add the line - <literal>Buttons 5</literal> to the - <quote>Pointer</quote> section of - <filename>/etc/XF86Config</filename>. For - example, you might have the following - <quote>Pointer</quote> section in - <filename>/etc/XF86Config</filename>.</para> - - <example> - <title><quote>Pointer</quote> Section for Wheeled - Mouse in XF86Config with moused Translation</title> - - <programlisting>Section "Pointer" - Protocol "SysMouse" - Device "/dev/sysmouse" - Buttons 5 -EndSection - </programlisting> - </example> - </listitem> - - <listitem> - <para>Using Your X Server to Translate the Wheel - Events</para> - - <para>If you aren't running &man.moused.8;, or if - you don't want &man.moused.8; to translate your - wheel events, you can have the X server do the - event translation instead. This requires a couple - of modifications to your - <filename>/etc/XF86Config</filename> file. First, - you need to choose the proper protocol for your - mouse. Most wheeled mice use the - <quote>IntelliMouse</quote> protocol. However, - XFree86 does support other protocols, such as - <quote>MouseManPlusPS/2</quote> for the Logitech - MouseMan+ mice. Once you have chosen the protocol - you will use, you need to add a - <varname>Protocol</varname> line to the - <quote>Pointer</quote> section.</para> - - <para>Secondly, you need to tell the X server to - remap wheel scroll events to mouse buttons 4 and - 5. This is done with the - <varname>ZAxisMapping</varname> option.</para> - - <para>For example, if you aren't using - &man.moused.8;, and you have an IntelliMouse - attached to the PS/2 mouse port you would use - the following in - <filename>/etc/XF86Config</filename>.</para> - - <example> - <title><quote>Pointer</quote> Section for Wheeled - Mouse in <filename>XF86Config</filename> with X - Server Translation</title> - - <programlisting>Section "Pointer" - Protocol "IntelliMouse" - Device "/dev/psm0" - ZAxisMapping 4 5 -EndSection - </programlisting> - </example> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>Install <application>imwheel</application></para> - - <para>Next, install <application>imwheel</application> - from the Ports collection. It can be found in the - <filename>x11</filename> category. This program will - map the wheel events from your mouse into keyboard - events. For example, it might send <keycap>Page - Up</keycap> to a program when you scroll the wheel - forwards. <application>Imwheel</application> uses a - configuration file to map the wheel events to - keypresses so that it can send different keys to - different applications. The default - <application>imwheel</application> configuration file - is installed in - <filename>/usr/X11R6/etc/imwheelrc</filename>. You - can copy it to <filename>~/.imwheelrc</filename> and - then edit it if you wish to customize - <application>imwheel</application>'s configuration. - The format of the configuration file is documented in - &man.imwheel.1;.</para> - </listitem> - - <listitem> - <para>Configure <application>Emacs</application> to Work - with <application>Imwheel</application> - (<emphasis>optional</emphasis>)</para> - - <para>If you use <application>emacs</application> or - <application>Xemacs</application>, then you need to - add a small section to your - <filename>~/.emacs</filename> file. For - <application>emacs</application>, add the - following:</para> - - <example> - <title><application>Emacs</application> Configuration - for <application>Imwheel</application></title> - - <programlisting>;;; For imwheel -(setq imwheel-scroll-interval 3) -(defun imwheel-scroll-down-some-lines () - (interactive) - (scroll-down imwheel-scroll-interval)) -(defun imwheel-scroll-up-some-lines () - (interactive) - (scroll-up imwheel-scroll-interval)) -(global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines) -(global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines) -;;; end imwheel section - </programlisting> - </example> - - <para>For <application>Xemacs</application>, add the - following to your <filename>~/.emacs</filename> file - instead:</para> - - <example> - <title><application>Xemacs</application> Configuration - for <application>Imwheel</application></title> - - <programlisting>;;; For imwheel -(setq imwheel-scroll-interval 3) -(defun imwheel-scroll-down-some-lines () - (interactive) - (scroll-down imwheel-scroll-interval)) -(defun imwheel-scroll-up-some-lines () - (interactive) - (scroll-up imwheel-scroll-interval)) -(define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines) -(define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines) -;;; end imwheel section - </programlisting> - </example> - </listitem> - - <listitem> - <para>Run <application>Imwheel</application></para> - - <para>You can just type <command>imwheel</command> - in an xterm to start it up once it is installed. It - will background itself and take effect immediately. - If you want to always use - <application>imwheel</application>, simply add it to - your <filename>.xinitrc</filename> or - <filename>.xsession</filename> file. You can safely - ignore any warnings <application>imwheel</application> - displays about PID files. Those warnings only apply - to the Linux version of - <application>imwheel</application>.</para> - </listitem> - </orderedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="window-menu-weird"> - <para>X Window menus and dialog boxes don't work right!</para> - </question> - - <answer> - <para>Try turning off the Num Lock key.</para> - - <para>If your Num Lock key is on by default at boot-time, you - may add the following line in the <literal>Keyboard</literal> - section of the <filename>XF86Config</filename> file.</para> - - <programlisting># Let the server do the NumLock processing. This should only be -# required when using pre-R6 clients - ServerNumLock</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="virtual-console"> - <para>What is a virtual console and how do I make more?</para> - </question> - - <answer> - <para>Virtual consoles, put simply, enable you to have several - simultaneous sessions on the same machine without doing anything - complicated like setting up a network or running X.</para> - - <para>When the system starts, it will display a login prompt on - the monitor after displaying all the boot messages. You can - then type in your login name and password and start working (or - playing!) on the first virtual console.</para> - - <para>At some point, you will probably wish to start another - session, perhaps to look at documentation for a program - you are running or to read your mail while waiting for an - FTP transfer to finish. Just do Alt-F2 (hold down the Alt - key and press the F2 key), and you will find a login prompt - waiting for you on the second <quote>virtual console</quote>! - When you want to go back to the original session, do - Alt-F1.</para> - - <para>The default FreeBSD installation has three virtual consoles - enabled (8 starting with 3.3-RELEASE), and Alt-F1, Alt-F2, and - Alt-F3 will switch between these virtual consoles.</para> - - <para>To enable more of them, edit <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys">/etc/ttys</ulink> - and add entries for <devicename>ttyv4</devicename> - to <devicename>ttyvc</devicename> after the comment on - <quote>Virtual terminals</quote>:</para> - - <programlisting># Edit the existing entry for ttyv3 in /etc/ttys and change -# "off" to "on". -ttyv3 "/usr/libexec/getty Pc" cons25 on secure -ttyv4 "/usr/libexec/getty Pc" cons25 on secure -ttyv5 "/usr/libexec/getty Pc" cons25 on secure -ttyv6 "/usr/libexec/getty Pc" cons25 on secure -ttyv7 "/usr/libexec/getty Pc" cons25 on secure -ttyv8 "/usr/libexec/getty Pc" cons25 on secure -ttyv9 "/usr/libexec/getty Pc" cons25 on secure -ttyva "/usr/libexec/getty Pc" cons25 on secure -ttyvb "/usr/libexec/getty Pc" cons25 on secure</programlisting> - - <para>Use as many or as few as you want. The more virtual - terminals you have, the more resources that are used; this - can be important if you have 8MB RAM or less. You may also - want to change the <literal>secure</literal> - to <literal>insecure</literal>.</para> - - <para> - <important> - <para>If you want to run an X server you - <emphasis>must</emphasis> leave at least one virtual - terminal unused (or turned off) for it to use. That is to - say that if you want to have a login prompt pop up for all - twelve of your Alt-function keys, you're out of luck - you - can only do this for eleven of them if you also want to run - an X server on the same machine.</para> - </important> - </para> - - <para>The easiest way to disable a console is by turning it off. - For example, if you had the full 12 terminal allocation - mentioned above and you wanted to run X, you would change - settings for virtual terminal 12 from:</para> - - <programlisting>ttyvb "/usr/libexec/getty Pc" cons25 on secure</programlisting> - - <para>to:</para> - - <programlisting>ttyvb "/usr/libexec/getty Pc" cons25 off secure</programlisting> - - <para>If your keyboard has only ten function keys, you would - end up with:</para> - -<programlisting>ttyv9 "/usr/libexec/getty Pc" cons25 off secure -ttyva "/usr/libexec/getty Pc" cons25 off secure -ttyvb "/usr/libexec/getty Pc" cons25 off secure</programlisting> - - <para>(You could also just delete these lines.)</para> - - <para>Once you have edited <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys"> - /etc/ttys</ulink>, the next step is to make sure that you - have enough virtualterminal devices. The easiest way to do - this is:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV vty12</userinput></screen> - - <para>Next, the easiest (and cleanest) way to activate the - virtual consoles is to reboot. However, if you really don't - want to reboot, you can just shut down the X Window system - and execute (as <username>root</username>):</para> - - <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> - - <para>It's imperative that you completely shut down X Window if - it is running, before running this command. If you don't, - your system will probably appear to hang/lock up after - executing the kill command.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="vty-from-x"> - <para>How do I access the virtual consoles from X?</para> - </question> - - <answer> - <para>Use <keycombo action="simul"> - <keycap>Ctrl</keycap> - <keycap>Alt</keycap> - <keycap>F<replaceable>n</replaceable></keycap> - </keycombo> to switch back to a virtual console. - <keycombo action="simul"> - <keycap>Ctrl</keycap> - <keycap>Alt</keycap> - <keycap>F1</keycap> - </keycombo> would return you to the first virtual console.</para> - - <para>Once you are back to a text console, you can then use - <keycombo action="simul"> - <keycap>Alt</keycap> - <keycap>F<replaceable>n</replaceable></keycap> - </keycombo> as normal to move between them.</para> - - <para>To return to the X session, you must switch to the virtual - console running X. If you invoked X from the command line, (e.g., - using <command>startx</command>) then the X session will attach to - the next unused virtual console, not the text console from which - it was invoked. If you have eight active virtual terminals then X - will be running on the ninth, and you would use - <keycombo action="simul"> - <keycap>Alt</keycap> - <keycap>F9</keycap> - </keycombo> to return.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="xdm-boot"> - <para>How do I start XDM on boot?</para> - </question><answer> - - <para>There are two schools of thought on how to start <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=xdm"> - xdm</ulink>. One school starts xdm from <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys">/etc/ttys</ulink> - using the supplied example, while the other simply runs xdm - from <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc(8)">rc.local</ulink> - or from a <filename>X.sh</filename> script in - <filename>/usr/local/etc/rc.d</filename>. Both are equally - valid, and one may work in situations where the other doesn't. - In both cases the result is the same: X will popup a graphical - login: prompt. </para> - - <para>The ttys method has the advantage of documenting which - vty X will start on and passing the responsibility of - restarting the X server on logout to init. The rc.local - method makes it easy to kill xdm if there is a problem - starting the X server. </para> - - <para>If loaded from rc.local, <command>xdm</command> should - be started without any arguments (i.e., as a daemon). xdm must - start AFTER getty runs, or else getty and xdm will conflict, - locking out the console. The best way around this is to have - the script sleep 10 seconds or so then launch xdm.</para> - - <para>If you are to start <command>xdm</command> from - <filename>/etc/ttys</filename>, there still is a chance of - conflict between <command>xdm</command> and - <command>getty</command>. One way to avoid this is to add the - <literal>vt</literal> number in the - <filename>/usr/X11R6/lib/X11/xdm/Xservers</filename> - file.</para> - - <programlisting>:0 local /usr/X11R6/bin/X vt4</programlisting> - - <para>The above example will direct the X server to run in - <filename>/dev/ttyv3</filename>. Note the number is offset by - one. The X server counts the vty from one, whereas the FreeBSD - kernel numbers the vty from zero.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="xconsole-failure"> - <para>When I run xconsole, I get - <literal>Couldn't open console</literal>.</para> - </question> - - <answer> - <para>If you start <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=X">X</ulink> - with <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=startx"> - startx</ulink>, the permissions on - <filename>/dev/console</filename> will - <emphasis remap=tt>not</emphasis> get changed, resulting in - things like <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=xterm"> - xterm -C</ulink> and <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=xconsole"> - xconsole</ulink>not working.</para> - - <para>This is because of the way console permissions are set - by default. On a multi-user system, one doesn't necessarily - want just any user to be able to write on the system console. - For users who are logging directly onto a machine with a VTY, - the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?fbtab">fbtab</ulink> - file exists to solve such problems.</para> - - <para>In a nutshell, make sure an uncommented line of the - form</para> - - <programlisting>/dev/ttyv0 0600 /dev/console</programlisting> - - <para>is in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?fbtab(5)"> - /etc/fbtab</ulink> and it will ensure that whomever logs in on - <filename>/dev/ttyv0</filename> will own the console.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ps2-x"> - <para>My PS/2 mouse doesn't behave properly under X.</para> - </question> - - <answer> - <para>Your mouse and the mouse driver may have somewhat become - out of synchronization.</para> - - <para>In versions 2.2.5 and earlier, switching away from X to a - virtual terminal and getting back to X again may make them - re-synchronized. If the problem occurs often, you may add the - following option in your kernel configuration file and - recompile it.</para> - - <programlisting>options PSM_CHECKSYNC</programlisting> - - <para>See the section on <link linkend="make-kernel">building - a kernel</link> if you've no experience with building - kernels.</para> - - <para>With this option, there should be less chance of - synchronization problem between the mouse and the driver. - If, however, you still see the problem, click any mouse - button while holding the mouse still to re-synchronize the - mouse and the driver.</para> - - <para>Note that unfortunately this option may not work with all - the systems and voids the <quote>tap</quote> feature of the - ALPS GlidePoint device attached to the PS/2 mouse port.</para> - - <para>In versions 2.2.6 and later, synchronization check is done - in a slightly better way and is standard in the PS/2 mouse - driver. It should even work with GlidePoint. (As the check code - has become a standard feature, PSM_CHECKSYNC option is not - available in these versions.) However, in rare case the driver - may erroneously report synchronization problem and you may see - the kernel message:</para> - - <programlisting>psmintr: out of sync (xxxx != yyyy)</programlisting> - - <para>and find your mouse doesn't seem to work properly.</para> - - <para>If this happens, disable the synchronization check code - by setting the driver flags for the PS/2 mouse driver to 0x100. - Enter <emphasis>UserConfig</emphasis> by giving the - <option>-c</option> option at the boot prompt:</para> - - <screen>boot: <userinput>-c</userinput></screen> - - <para>Then, in the <emphasis>UserConfig</emphasis> command - line, type:</para> - - <screen>UserConfig> <userinput>flags psm0 0x100</userinput> -UserConfig> <userinput>quit</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ps2-mousesystems"> - <para>My PS/2 mouse from MouseSystems doesn't seem to - work.</para> - </question> - - <answer> - <para>There have been some reports that certain model of PS/2 - mouse from MouseSystems works only if it is put into the - <quote>high resolution</quote> mode. Otherwise, the mouse - cursor may jump to the upper-left corner of the screen every - so often.</para> - - <para>Unfortunately there is no workaround for versions 2.0.X - and 2.1.X. In versions 2.2 through 2.2.5, apply the following - patch to <filename>/sys/i386/isa/psm.c</filename> and rebuild - the kernel. See the section on <link - linkend="make-kernel">building a kernel</link> if you've no - experience with building kernels.</para> - - <programlisting>@@ -766,6 +766,8 @@ - if (verbose >= 2) - log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n", - unit, i); -+ set_mouse_resolution(sc->kbdc, PSMD_RES_HIGH); -+ - #if 0 - set_mouse_scaling(sc->kbdc); /* 1:1 scaling */ - set_mouse_mode(sc->kbdc); /* stream mode */</programlisting> - - <para>In versions 2.2.6 or later, specify the flags 0x04 to - the PS/2 mouse driver to put the mouse into the high - resolution mode. Enter <emphasis>UserConfig</emphasis> by - giving the <option>-c</option> option at the boot prompt:</para> - - <screen>boot: <userinput>-c</userinput></screen> - - <para>Then, in the <emphasis>UserConfig</emphasis> command line, - type:</para> - - <screen>UserConfig> <userinput>flags psm0 0x04</userinput> -UserConfig> <userinput>quit</userinput></screen> - - <para>See the previous section for another possible cause of mouse - problems.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="imake-tmpl"> - <para>When building an X app, <command>imake</command> can't - find <filename>Imake.tmpl</filename>. Where is it?</para> - </question> - - <answer> - - <para>Imake.tmpl is part of the Imake package, a standard X - application building tool. Imake.tmpl, as well as several - header files that are required to build X apps, is contained - in the X prog distribution. You can install this from sysinstall - or manually from the X distribution files. </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="mouse-button-reverse"> - <para>How do I reverse the mouse buttons?</para> - </question> - - <answer> - <para>Run the command - <command>xmodmap -e "pointer = 3 2 1"</command> from your - .xinitrc or .xsession.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="install-splash"> - <para>How do I install a splash screen and where do I find - them?</para> - </question> - - <answer> - - <para>Just prior to the release of FreeBSD 3.1, a new feature - was added to allow the display of <quote>splash</quote> screens - during the boot messages. The splash screens currently must be - a 256 color bitmap (<filename>*.BMP</filename>) or ZSoft PCX - (<filename>*.PCX</filename>) file. In addition, they must have - a resolution of 320x200 or less to work on standard VGA - adapters. If you compile VESA support into your kernel, then - you can use larger bitmaps up to 1024x768. Note that VESA - support requires the <literal>VM86</literal> kernel option to - be compiled into the kernel. The actual VESA support can either - be compiled directly into the kernel with the - <literal>VESA</literal> kernel config option or by loading the - VESA kld module during bootup.</para> - - <para>To use a splash screen, you need to modify the startup - files that control the boot process for FreeBSD. The files for - this changed prior to the release of FreeBSD 3.2, so there are - now two ways of loading a splash screen:</para> - - <para> - <itemizedlist> - <listitem> - <para>FreeBSD 3.1</para> - - <para>The first step is to find a bitmap version of your - splash screen. Release 3.1 only supports Windows bitmap - splash screens. Once you've found your splash screen of - choice copy it to <filename>/boot/splash.bmp</filename>. - Next, you need to have a - <filename>/boot/loader.rc</filename> file that contains - the following lines:</para> - - <programlisting>load kernel -load -t splash_image_data /boot/splash.bmp -load splash_bmp -autoboot</programlisting> - - </listitem> - - <listitem> - <para>FreeBSD 3.2+</para> - - <para>In addition to adding support for PCX splash screens, - FreeBSD 3.2 includes a nicer way of configuring the boot - process. If you wish, you can use the method listed above - for FreeBSD 3.1. If you do and you want to use PCX, - replace <literal>splash_bmp</literal> with - <literal>splash_pcx</literal>. If, on the other hand, you - want to use the newer boot configuration, you need to - create a <filename>/boot/loader.rc</filename> file that - contains the following lines:</para> - - <programlisting>include /boot/loader.4th -start</programlisting> - - <para>and a <filename>/boot/loader.conf</filename> that - contains the following:</para> - - <programlisting>splash_bmp_load="YES" -bitmap_load="YES"</programlisting> - - <para>This assumes you are using - <filename>/boot/splash.bmp</filename> for your splash - screen. If you'd rather use a PCX file, copy it to - <filename>/boot/splash.pcx</filename>, create a - <filename>/boot/loader.rc</filename> as instructed - above, and create a - <filename>/boot/loader.conf</filename> that - contains:</para> - - <programlisting>splash_pcx_load="YES" -bitmap_load="YES" -bitmap_name="/boot/splash.pcx"</programlisting> - - </listitem> - </itemizedlist></para> - - <para>Now all you need is a splash screen. For that you can - surf on over to the gallery at <ulink - URL="http://www.baldwin.cx/splash/">http://www.baldwin.cx/splash/</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="windows-keys"> - <para>Can I use the Windows(tm) keys on my keyboard in X?</para> - </question> - - <answer> - <para>Yes. All you need to do is use &man.xmodmap.1; to define - what function you wish them to perform.</para> - - <para>Assuming all <quote>Windows(tm)</quote> keyboards are - standard then the keycodes for the 3 keys are</para> - - <itemizedlist> - <listitem> - <para>115 - Windows(tm) key, between the left-hand Ctrl and - Alt keys</para> - </listitem> - - <listitem> - <para>116 - Windows(tm) key, to the right of the Alt-Gr - key</para> - </listitem> - - <listitem> - <para>117 - Menu key, to the left of the right-hand Ctrl - key</para> - </listitem> - </itemizedlist> - - <para>To have the left Windows(tm) key print a comma, try - this.</para> - - <screen>&prompt.root; <userinput>xmodmap -e "keycode 115 = comma"</userinput></screen> - - <para>You will probably have to re-start your window manager - to see the result.</para> - - <para>To have the Windows(tm) key-mappings enabled automatically - everytime you start X either put the <command>xmodmap</command> - commands in your <filename>~/.xinitrc</filename> file or, - preferably, create a file <filename>~/.xmodmaprc</filename> and - include the <command>xmodmap</command> options, one per line, - then add the line</para> - - <programlisting>xmodmap $HOME/.xmodmaprc</programlisting> - - <para>to your <filename>~/.xinitrc</filename>.</para> - - <para>For example, I have mapped the 3 keys to be F13, F14, and - F15 respectively. This makes it easy to map them to useful - functions within applications or your window manager.</para> - - <para>To do this put the following in - <filename>~/.xmodmaprc</filename>.</para> - - <programlisting>keycode 115 = F13 -keycode 116 = F14 -keycode 117 = F15</programlisting> - - <para>I use <command>fvwm2</command> and have mapped the keys - so that F13 iconifies (or de-iconifies) the window the cursor - is in, F14 brings the window the cursor is in to the front or, - if it is already at the front, pushes it to the back, and F15 - pops up the main Workplace (application) menu even if the - cursor is not on the desktop, which is useful if you don't have - any part of the desktop visible (and the logo on the key - matches its functionality).</para> - - <para>The entries in my <filename>~/.fvwmrc</filename> which map - the keys this way are:</para> - - <programlisting>Key F13 FTIWS A Iconify -Key F14 FTIWS A RaiseLower -Key F15 A A Menu Workplace Nop</programlisting> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="networking"> - <title>Networking</title> - - <qandaset> - <qandaentry> - <question id="diskless-booting"> - <para>Where can I get information on - <quote>diskless booting</quote>?</para> - </question> - - <answer> - <para><quote>Diskless booting</quote> means that the FreeBSD - box is booted over a network, and reads the necessary files - from a server instead of its hard disk. For full details, - please read <ulink URL="../handbook/diskless.html">the - Handbook entry on diskless booting</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="router"> - <para>Can a FreeBSD box be used as a dedicated network - router?</para> - </question> - - <answer> - <para>Internet standards and good engineering practice prohibit - us from providing packet forwarding by default in FreeBSD. You - can however enable this feature by changing the following - variable to <literal>YES</literal> in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf"> - rc.conf</ulink>:</para> - - <programlisting>gateway_enable=YES # Set to YES if this host will be a gateway</programlisting> - - <para>This option will put the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sysctl"> - sysctl</ulink> variable - <filename>net.inet.ip.forwarding</filename> - to <literal>1</literal>.</para> - - <para>In most cases, you will also need to run a routing process - to tell other systems on your network about your router; - FreeBSD comes with the standard BSD routing daemon <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?routed">routed</ulink>, - or for more complex situations you may want to try - <emphasis>GaTeD</emphasis> (available from <ulink - URL="http://www.gated.org/"> http://www.gated.org/ </ulink>) - which supports FreeBSD as of 3_5Alpha7.</para> - - <para>It is our duty to warn you that, even when FreeBSD is - configured in this way, it does not completely comply with - the Internet standard requirements for routers; however, - it comes close enough for ordinary usage.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="win95-connection"> - <para>Can I connect my Win95 box to the Internet via - FreeBSD?</para> - </question> - - <answer> - <para>Typically, people who ask this question have two PC's - at home, one with FreeBSD and one with Win95; the idea is to - use the FreeBSD box to connect to the Internet and then be able - to access the Internet from the Windows95 box through the - FreeBSD box. This is really just a special case of the previous - question.</para> <para> ... and the answer is yes! In FreeBSD - 3.x, user-mode ppp contains a <option>-nat</option> option. If - you run <command>ppp</command> with the <option>-nat</option>, - set <literal>gateway_enable</literal> to - <emphasis>YES</emphasis> in <filename>/etc/rc.conf</filename>, - and configure your Windows machine correctly, this should work - fine.</para> - - <para>More detailed information about setting this up can be - found in the <ulink - URL="http://www.FreeBSD.org/tutorials/ppp/index.html"> - Pedantic PPP Primer</ulink> by Steve Sims.</para> - - <para>If you are using kernel-mode ppp, or have an Ethernet - connection to the Internet, you will have to use - <command>natd</command>. Please look at the - <link linkend="natd">natd</link> section of this FAQ.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="latest-bind"> - <para>Why does recompiling the latest BIND from ISC fail?</para> - </question> - - <answer> - <para>There is a conflict between the - <filename>cdefs.h</filename> file in the distribution and the - one shipped with FreeBSD. Just remove - <filename>compat/include/sys/cdefs.h</filename>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="slip-ppp-support"> - <para>Does FreeBSD support SLIP and PPP?</para> - </question> - - <answer> - <para>Yes. See the man pages for <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?slattach"> - slattach</ulink>, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sliplogin"> - sliplogin</ulink>, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?pppd">pppd</ulink> and - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?ppp">ppp</ulink>. - <command>pppd</command> and <command>ppp</command> provide - support for both incoming and outgoing connections. <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sliplogin"> - Sliplogin</ulink> deals exclusively with incoming connections - and <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?slattach"> - slattach</ulink> deals exclusively with outgoing - connections.</para> - - <para>These programs are described in the following sections of - the <ulink URL="../handbook/index.html">handbook</ulink>:</para> - - <para> - <itemizedlist> - <listitem> - <para><ulink URL="../handbook/slips.html">Handbook entry - on SLIP (server side)</ulink> - </para> - </listitem> - - <listitem> - <para><ulink URL="../handbook/slipc.html">Handbook entry - on SLIP (client side)</ulink></para> - </listitem> - - <listitem> - <para><ulink URL="../handbook/ppp.html">Handbook entry on - PPP (kernel version)</ulink></para> - </listitem> - - <listitem> - <para><ulink URL="../handbook/ppp-and-slip.html#USERPPP"> - Handbook entry on PPP (user-mode version)</ulink></para> - </listitem> - </itemizedlist></para> - - <para>If you only have access to the Internet through a - <quote>shell account</quote>, you may want to have a look at - the <ulink URL="http://www.FreeBSD.org/cgi/ports.cgi?^slirp"> - slirp</ulink> package. It can provide you with (limited) - access to services such as ftp and http direct from your local - machine.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="natd"> - <para>Does FreeBSD support NAT or Masquerading</para> - </question> - - <answer> - <para>If you have a local subnet (one or more local machines), - but have been allocated only a single IP number from your - Internet provider (or even if you receive a dynamic IP number), - you may want to look at the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?natd">natd</ulink> - program. <command>natd</command> allows you to connect an - entire subnet to the internet using only a single IP - number.</para> - - <para>The <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?ppp"> - ppp</ulink> program has similar functionality built in via - the <option>-nat</option> switch. The <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?libalias"> - alias library</ulink> is used in both cases.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="create-dev-net"> - <para>I can't create a <filename>/dev/ed0</filename> - device!</para> - </question> - - <answer> - - <para>In the Berkeley networking framework, network interfaces - are only directly accessible by kernel code. Please see the - <filename>/etc/rc.network</filename> file and the manual pages - for the various network programs mentioned there for more - information. If this leaves you totally confused, then you - should pick up a book describing network administration on - another BSD-related operating system; with few significant - exceptions, administering networking on FreeBSD is basically - the same as on SunOS 4.0 or Ultrix.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ethernet-aliases"> - <para>How can I setup Ethernet aliases?</para> - </question><answer> - - <para>Add <literal>netmask 0xffffffff</literal> to your <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ifconfig"> - ifconfig</ulink> command-line like the following:</para> - - <screen>&prompt.root; <userinput>ifconfig ed0 alias 204.141.95.2 netmask 0xffffffff</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="port-3c503"> - <para>How do I get my 3C503 to use the other network - port?</para> - </question> - - <answer> - <para>If you want to use the other ports, you'll have to specify - an additional parameter on the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ifconfig"> - ifconfig</ulink> command line. The default port is - <literal>link0</literal>. To use the AUI port instead of the - BNC one, use <literal>link2</literal>. These flags should be - specified using the ifconfig_* variables in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf"> - /etc/rc.conf</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="nfs"> - <para>I'm having problems with NFS to/from FreeBSD.</para> - </question> - - <answer> - <para>Certain PC network cards are better than others (to put - it mildly) and can sometimes cause problems with network - intensive applications like NFS.</para> - - <para>See <ulink URL="../handbook/nfs.html"> - the Handbook entry on NFS</ulink> for more information on - this topic.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="nfs-linux"> - <para>Why can't I NFS-mount from a Linux box?</para> - </question> - - <answer> - <para>Some versions of the Linux NFS code only accept mount - requests from a privileged port; try</para> - - <screen>&prompt.root; <userinput>mount -o -P linuxbox:/blah /mnt</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="nfs-sun"> - <para>Why can't I NFS-mount from a Sun box?</para> - </question> - - <answer> - <para>Sun workstations running SunOS 4.X only accept mount - requests from a privileged port; try</para> - - <screen>&prompt.root; <userinput>mount -o -P sunbox:/blah /mnt</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-nextstep"> - <para>I'm having problems talking PPP to NeXTStep - machines.</para> - </question> - - <answer> - - <para>Try disabling the TCP extensions in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf"> - /etc/rc.conf</ulink> by changing the following variable to - NO:</para> - - <programlisting>tcp_extensions=NO</programlisting> - - <para>Xylogic's Annex boxes are also broken in this regard and - you must use the above change to connect thru them.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ip-multicast"> - <para>How do I enable IP multicast support?</para> - </question> - - <answer> - <para>Multicast host operations are fully supported in FreeBSD - 2.0 and later by default. If you want your box to run as a - multicast router, you will need to recompile your kernel with - the <literal>MROUTING</literal> option and run - <command>mrouted</command>. FreeBSD 2.2 and later will start - <command>mrouted</command> at boot time if the flag - <literal>mrouted_enable</literal> is set to - <literal>"YES"</literal> in - <filename>/etc/rc.conf</filename>.</para> - - <para>MBONE tools are available in their own ports category, - mbone. If you are looking for the conference tools - <command>vic</command> and <command>vat</command>, - look there!</para> - - <para>For more information, see the <ulink - URL="http://www.mbone.com/"> - Mbone Information Web</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dec-pci-chipset"> - <para>Which network cards are based on the DEC PCI - chipset?</para> - </question><answer> - - <para>Here is a list compiled by <ulink - URL="mailto:gfoster@driver.nsta.org">Glen Foster</ulink>, - with some more modern additions:</para> - -<programlisting>Vendor Model ----------------------------------------------- -ASUS PCI-L101-TB -Accton ENI1203 -Cogent EM960PCI -Compex ENET32-PCI -D-Link DE-530 -Dayna DP1203, DP2100 -DEC DE435, DE450 -Danpex EN-9400P3 -JCIS Condor JC1260 -Linksys EtherPCI -Mylex LNP101 -SMC EtherPower 10/100 (Model 9332) -SMC EtherPower (Model 8432) -TopWare TE-3500P -Znyx (2.2.x) ZX312, ZX314, ZX342, ZX345, ZX346, ZX348 - (3.x) ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, - ZX444, ZX474, ZX478, ZX212, ZX214 (10mbps/hd) - </programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="fqdn-hosts"> - <para>Why do I have to use the FQDN for hosts on my - site?</para> - </question> - - <answer> - <para>You will probably find that the host is actually in a - different domain; for example, if you are in foo.bar.edu and - you wish to reach a host called <hostid>mumble</hostid> in the - <hostid role="domainname">bar.edu</hostid> domain, you will - have to refer to it by the fully-qualified domain name, <hostid - role="fqdn">mumble.bar.edu</hostid>, instead of just - <hostid>mumble</hostid>.</para> - - <para>Traditionally, this was allowed by BSD BIND resolvers. - However the current version of <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?named">bind</ulink> - that ships with FreeBSD no longer provides default - abbreviations for non-fully qualified domain names other than - the domain you are in. So an unqualified host - <hostid>mumble</hostid> must either be found as <hostid - role="fqdn">mumble.foo.bar.edu</hostid>, or it will be searched - for in the root domain.</para> - - <para>This is different from the previous behavior, where the - search continued across - <hostid role="fqdn">mumble.bar.edu</hostid>, and - <hostid role="domainname">mumble.edu</hostid>. Have a look at - RFC 1535 for why this was considered bad practice, or even a - security hole.</para> - - <para>As a good workaround, you can place the line</para> - - <programlisting>search foo.bar.edu bar.edu</programlisting> - - <para>instead of the previous</para> - - <programlisting>domain foo.bar.edu</programlisting> - - <para>into your <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?resolv.conf"> - /etc/resolv.conf</ulink> file. However, make sure that the - search order does not go beyond the <quote>boundary between - local and public administration</quote>, as RFC 1535 calls - it.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="network-permission-denied"> - <para><literal>Permission denied</literal> for all networking - operations.</para> - </question> - - <answer> - <para>If you have compiled your kernel with the - <literal>IPFIREWALL</literal> option, you need to be aware - that the default policy as of 2.1.7R (this actually changed - during 2.1-STABLE development) is to deny all packets that are - not explicitly allowed.</para> - - <para>If you had unintentionally misconfigured your system for - firewalling, you can restore network operability by typing - the following while logged in as root:</para> - - <screen>&prompt.root; <userinput>ipfw add 65534 allow all from any to any</userinput></screen> - - <para>You can also set <literal>firewall_type="open"</literal> - in <filename>/etc/rc.conf</filename>.</para> - - <para>For further information on configuring a FreeBSD firewall, - see the <ulink URL="../handbook/firewalls.html"> - Handbook section</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ipfw-overhead"> - <para>How much overhead does IPFW incur?</para> - </question> - - <answer> - <para>The answer to this depends mostly on your rule set and - processor speed. For most applications dealing with ethernet - and small rule sets, the answer is, negligible. For those of - you that need actual measurements to satisfy your curiosity, - read on.</para> - - <para>The following measurements were made using 2.2.5-STABLE - on a 486-66. IPFW was modified to measure the time spent - within the <literal>ip_fw_chk</literal> routine, displaying - the results to the console every 1000 packets.</para> - - <para>Two rule sets, each with 1000 rules were tested. The - first set was designed to demonstrate a worst case scenario - by repeating the rule:</para> - - <screen>&prompt.root; <userinput>ipfw add deny tcp from any to any 55555</userinput></screen> - - <para>This demonstrates worst case by causing most of IPFW's - packet check routine to be executed before finally deciding - that the packet does not match the rule (by virtue of the port - number). Following the 999th iteration of this rule was an - <literal>allow ip from any to any</literal>.</para> - - <para>The second set of rules were designed to abort the rule - check quickly:</para> - - <screen>&prompt.root; <userinput>ipfw add deny ip from 1.2.3.4 to 1.2.3.4</userinput></screen> - - <para>The nonmatching source IP address for the above rule causes - these rules to be skipped very quickly. As before, the 1000th - rule was an <literal>allow ip from any to any</literal>.</para> - - <para>The per-packet processing overhead in the former case was - approximately 2.703ms/packet, or roughly 2.7 microseconds per - rule. Thus the theoretical packet processing limit with these - rules is around 370 packets per second. Assuming 10Mbps - ethernet and a ~1500 byte packet size, we would only be able to - achieve a 55.5% bandwidth utilization.</para> - - <para>For the latter case each packet was processed in - approximately 1.172ms, or roughly 1.2 microseconds per rule. - The theoretical packet processing limit here would be about - 853 packets per second, which could consume 10Mbps ethernet - bandwidth.</para> - - <para>The excessive number of rules tested and the nature of - those rules do not provide a real-world scenario -- they were - used only to generate the timing information presented here. - Here are a few things to keep in mind when building an - efficient rule set:</para> - - <para> - <itemizedlist> - <listitem> - <para>Place an <literal>established</literal> rule early - on to handle the majority of TCP traffic. Don't put any - <literal>allow tcp</literal> statements before this - rule.</para> - </listitem> - - <listitem> - <para>Place heavily triggered rules earlier in the rule - set than those rarely used (<emphasis remap=bf>without - changing the permissiveness of the firewall</emphasis>, - of course). You can see which rules are used most often - by examining the packet counting statistics with - <command>ipfw -a l</command>.</para> - </listitem> - </itemizedlist></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="service-redirect"> - <para>How can I redirect service requests from one machine to - another?</para> - </question> - - <answer> - <para>You can redirect FTP (and other service) request with - the <literal>socket</literal> package, available in the ports - tree in category <quote>sysutils</quote>. Simply replace the - service's commandline to call socket instead, like so:</para> - - <programlisting>ftp stream tcp nowait nobody /usr/local/bin/socket socket <replaceable>ftp.foo.com</replaceable> <replaceable>ftp</replaceable></programlisting> - - <para>where <replaceable>ftp.foo.com</replaceable> and - <replaceable>ftp</replaceable> are the host and port to - redirect to, respectively.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="bandwidth-mgr-tool"> - <para>Where can I get a bandwidth management tool?</para> - </question> - - <answer> - <para>There are two bandwidth management tools available for - FreeBSD. <ulink - URL="http://www.csl.sony.co.jp/person/kjc/programs.html"> - ALTQ</ulink> is available for free; Bandwidth Manager from - <ulink URL="http://www.etinc.com/">Emerging Technologies</ulink> - is a commercial product. </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="bpf-not-configured"> - <para>Why do I get <literal>/dev/bpf0: device not - configured</literal>?</para> - </question> - - <answer> - <para>The Berkeley Packet Filter <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?bpf">(bpf)</ulink> - driver needs to be enabled before running programs that - utilize it. Add this to your kernel config file and build - a new kernel:</para> - - <programlisting>pseudo-device bpfilter # Berkeley Packet Filter</programlisting> - - <para>Secondly, after rebooting you will have to create the - device node. This can be accomplished by a change to the - <filename>/dev</filename> directory, followed by the execution - of:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV bpf0</userinput></screen> - - <para>Please see the <ulink - URL="../handbook/kernelconfig-nodes.html"> - handbook's entry on device nodes</ulink> for more information - on creating devices.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="mount-smb-share"> - <para>How do I mount a disk from a Windows machine that's on my - network, like smbmount in Linux?</para> - </question> - - <answer> - <para>Use the <ulink - URL="http://www.freebsd.org/cgi/ports.cgi?query=%5Esharity-light-&;amp;stype=name"> - sharity light</ulink> package in the ports collection.</para> - -<!-- XXX update for bp's SMBFS in CURRENT, when it is imported! --> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="ppp"> - <title>PPP</title> - - <qandaset> - <qandaentry> - <question id="userppp"> - <para>I can't make ppp work. What am I doing wrong ?</para> - </question> - - <answer> - <para>You should first read the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ppp"> - ppp man page</ulink> and the <ulink - URL="../handbook/ppp-and-slip.html#USERPPP"> - ppp section of the handbook</ulink>. Enable logging with - the command</para> - - <programlisting>set log Phase Chat Connect Carrier lcp ipcp ccp command</programlisting> - - <para>This command may be typed at the - <emphasis remap=bf>ppp</emphasis> command prompt or it may be - entered in the <filename>/etc/ppp/ppp.conf</filename> - configuration file (the start of the - <emphasis remap=bf>default</emphasis> section is the best - place to put it). Make sure that <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?syslog.conf"> - /etc/syslog.conf</ulink> contains the lines</para> - - <programlisting>!ppp -*.* /var/log/ppp.log</programlisting> - - <para>and that the file <filename>/var/log/ppp.log</filename> - exists. You can now find out a lot about what's going on - from the log file. Don't worry if it doesn't all make sense. - If you need to get help from someone, it may make sense to - them.</para> - - <para>If your version of ppp doesn't understand the - <command>set log</command> command, you should download the - <ulink URL="http://people.FreeBSD.org/~brian/"> - latest version</ulink>. It will build on FreeBSD version - 2.1.5 and higher.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-hangs"> - <para>Ppp just hangs when I run it</para> - </question> - - <answer> - <para>This is usually because your hostname won't resolve. - The best way to fix this is to make sure that - <filename>/etc/hosts</filename> is consoluted by your - resolver first by editing <filename>/etc/host.conf</filename> - and putting the <literal>hosts</literal> line first. Then, - simply put an entry in <filename>/etc/hosts</filename> for - your local machine. If you have no local network, change your - <hostid>localhost</hostid> line:</para> - - <programlisting>127.0.0.1 foo.bar.com foo localhost</programlisting> - - <para>Otherwise, simply add another entry for your host. - Consult the relevant man pages for more details.</para> - - <para>You should be able to successfully - <command>ping -c1 `hostname`</command> when you're done.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-nodial-auto"> - <para>Ppp won't dial in -auto mode</para> - </question> - - <answer> - <para>First, check that you've got a default route. By running - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?netstat"> - netstat -rn</ulink>, you should see two entries like this:</para> - - <programlisting>Destination Gateway Flags Refs Use Netif Expire -default 10.0.0.2 UGSc 0 0 tun0 -10.0.0.2 10.0.0.1 UH 0 0 tun0</programlisting> - - <para>This is assuming that you've used the addresses from the - handbook, the man page or from the ppp.conf.sample file. - If you haven't got a default route, it may be because you're - running an old version of <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ppp">ppp</ulink> - that doesn't understand the word <literal>HISADDR</literal> - in the ppp.conf file. If your version of - <emphasis remap=bf>ppp</emphasis> is from before FreeBSD - 2.2.5, change the</para> - - <programlisting>add 0 0 HISADDR</programlisting> - - <para>line to one saying</para> - - - <programlisting>add 0 0 10.0.0.2</programlisting> - - <para>Another reason for the default route line being missing - is that you have mistakenly set up a default router in your - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?rc.conf"> - /etc/rc.conf</ulink> file (this file was called - <filename>/etc/sysconfig</filename> prior to release 2.2.2), - and you have omitted the line saying</para> - - <programlisting>delete ALL</programlisting> - - <para>from <filename>ppp.conf</filename>. If this is the case, - go back to the <ulink - URL="../handbook/ppp-and-slip.html#USERPPP-FINAL"> - Final system configuration</ulink> section of the - handbook.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="no-route-to-host"> - <para>What does <literal>No route to host</literal> mean</para> - </question> - - <answer> - <para>This error is usually due to a missing</para> - - <programlisting>MYADDR: - delete ALL - add 0 0 HISADDR</programlisting> - - <para>section in your <filename>/etc/ppp/ppp.linkup</filename> - file. This is only necessary if you have a dynamic IP address - or don't know the address of your gateway. If you're using - interactive mode, you can type the following after entering - <emphasis remap=tt>packet mode</emphasis> (packet mode is - indicated by the capitalized <acronym>PPP</acronym> in the - prompt):</para> - - <programlisting>delete ALL -add 0 0 HISADDR</programlisting> - - <para>Refer to the <ulink - URL="../handbook/ppp-and-slip.html#USERPPP-DYNAMICIP"> - PPP and Dynamic IP addresses</ulink> section of the handbook - for further details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="connection-threeminutedrop"> - <para>My connection drops after about 3 minutes</para> - </question> - - <answer> - <para>The default ppp timeout is 3 minutes. This can be - adjusted with the line</para> - - <programlisting>set timeout <replaceable>NNN</replaceable></programlisting> - - <para>where <replaceable>NNN</replaceable> is the number of - seconds of inactivity before the connection is closed. If - <replaceable>NNN</replaceable> is zero, the connection is never - closed due to a timeout. It is possible to put this command in - the <filename>ppp.conf</filename> file, or to type it at the - prompt in interactive mode. It is also possible to adjust it on - the fly while the line is active by connecting to <emphasis - remap=bf>ppp</emphasis>s server socket using <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?telnet">telnet</ulink> - or <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?pppctl">pppctl</ulink>. - Refer to the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ppp">ppp</ulink> man - page for further details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-drop-heavy-load"> - <para>My connection drops under heavy load</para> - </question> - - <answer> - <para>If you have Link Quality Reporting (LQR) configured, - it is possible that too many LQR packets are lost between - your machine and the peer. Ppp deduces that the line must - therefore be bad, and disconnects. Prior to FreeBSD version - 2.2.5, LQR was enabled by default. It is now disabled by - default. LQR can be disabled with the line</para> - - <programlisting>disable lqr</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-drop-random"> - <para>My connection drops after a random amount of time</para> - </question> - - <answer> - <para>Sometimes, on a noisy phone line or even on a line with - call waiting enabled, your modem may hang up because it - thinks (incorrectly) that it lost carrier.</para> - - <para>There's a setting on most modems for determining how - tolerant it should be to temporary losses of carrier. On a - USR Sportster for example, this is measured by the S10 - register in tenths of a second. To make your modem more - forgiving, you could add the following send-expect sequence - to your dial string:</para> - - <programlisting>set dial "...... ATS10=10 OK ......"</programlisting> - - <para>Refer to your modem manual for details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-hangs-random"> - <para>My connection hangs after a random amount of time</para> - </question><answer> - - <para>Many people experience hung connections with no apparent - explaination. The first thing to establish is which side of - the link is hung.</para> - - <para>If you are using an external modem, you can simply try - using <command>ping</command> to see if the - <acronym>TD</acronym> light is flashing when you transmit data. - If it flashes (and the <acronym>RD</acronym> light doesn't), - the problem is with the remote end. If <acronym>TD</acronym> - doesn't flash, the problem is local. With an internal modem, - you'll need to use the <literal>set server</literal> command in - your <filename>ppp.conf</filename> file. When the hang occurs, - connect to ppp using pppctl. If your network connection - suddenly revives (ppp was revived due to the activity on the - diagnostic socket) or if you can't connect (assuming the - <literal>set socket</literal> command succeeded at startup - time), the problem is local. If you can connect and things are - still hung, enable local async logging with <literal>set log - local async</literal> and use <command>ping</command> from - another window or terminal to make use of the link. The async - logging will show you the data being transmitted and received - on the link. If data is going out and not coming back, the - problem is remote.</para> - - <para>Having established whether the problem is local or remote, - you now have two possibilities:</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-remote-not-responding"> - <para>The remote end isn't responding</para> - </question> - - <answer> - <para>There's very little you can do about this. Most ISPs - will refuse to help if you're not running a Microsoft OS. - You can <literal>enable lqr</literal> in your - <filename>ppp.conf</filename> file, allowing ppp to detect - the remote failure and hang up, but this detection is - relatively slow and therefore not that useful. You may want to - avoid telling your ISP that you're running user-ppp....</para> - - <para>First, try disabling all local compression by adding the - following to your configuration:</para> - - <programlisting>disable pred1 deflate deflate24 protocomp acfcomp shortseq vj -deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> - - <para>Then reconnect to ensure that this makes no difference. - If things improve or if the problem is solved completely, - determine which setting makes the difference through trial - and error. This will provide good amunition when you contact - your ISP (although it may make it apparent that you're not - running a Microsoft product).</para> - - <para>Before contacting your ISP, enable async logging locally - and wait until the connection hangs again. This may use up - quite a bit of disk space. The last data read from the port - may be of interest. It is usually ascii data, and may even - describe the problem - (<quote>Memory fault, core dumped</quote> ?).</para> - - <para>If your ISP is helpful, they should be able to enable - logging on their end, then when the next link drop occurs, - they may be able to tell you why their side is having a - problem. Feel free to send the details to &a.brian;, or - even to ask your ISP to contact me directly.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-hung"> - <para>Ppp is hung</para> - </question> - - <answer> - <para>Your best bet here is to rebuild ppp by adding - <literal>CFLAGS+=-g</literal> and <literal>STRIP=</literal> - to the end of the Makefile, then doing a - <command>make clean && make && make - install</command>. When ppp hangs, find the ppp process id - with <command>ps ajxww | fgrep ppp</command> and run - <command>gdb ppp <replaceable>PID</replaceable></command>. - From the gdb prompt, you can then use <command>bt</command> - to get a stack trace.</para> - - <para>Send the results to <email>brian@Awfulhak.org</email>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-loginok-thennothing"> - <para>Nothing happens after the Login OK! message</para> - </question> - - <answer> - <para>Prior to FreeBSD version 2.2.5, once the link was - established, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ppp">ppp</ulink> - would wait for the peer to initiate the Line Control Protocol - (LCP). Many ISPs will not initiate negotiations and expect - the client to do so. To force - <emphasis remap=bf>ppp</emphasis> to initiate the LCP, use the - following line:</para> - - <programlisting>set openmode active</programlisting> - - <para><emphasis remap=bf>Note</emphasis>: It usually does no - harm if both sides initiate negotiation, so openmode is now - active by default. However, the next section explains when - it <emphasis remap=bf>does</emphasis> do some harm.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-same-magic"> - <para>I keep seeing errors about magic being the same</para> - </question> - - <answer> - <para>Occasionally, just after connecting, you may see messages - in the log that say <quote>magic is the same</quote>. - Sometimes, these messages are harmless, and sometimes one side - or the other exits. Most ppp implementations cannot survive - this problem, and even if the link seems to come up, you'll see - repeated configure requests and configure acknowledgements in - the log file until ppp eventually gives up and closes the - connection.</para> - - <para>This normally happens on server machines with slow disks - that are spawning a getty on the port, and executing ppp from - a login script or program after login. I've also heard reports - of it happening consistently when using slirp. The reason is - that in the time taken between getty exiting and ppp starting, - the client-side ppp starts sending Line Control Protocol (LCP) - packets. Because ECHO is still switched on for the port on - the server, the client ppp sees these packets - <quote>reflect</quote> back.</para> - - <para>One part of the LCP negotiation is to establish a magic - number for each side of the link so that - <quote>reflections</quote> can be detected. The protocol says - that when the peer tries to negotiate the same magic number, a - NAK should be sent and a new magic number should be chosen. - During the period that the server port has ECHO turned on, the - client ppp sends LCP packets, sees the same magic in the - reflected packet and NAKs it. It also sees the NAK reflect - (which also means ppp must change its magic). This produces a - potentially enormous number of magic number changes, all of - which are happily piling into the server's tty buffer. As soon - as ppp starts on the server, it's flooded with magic number - changes and almost immediately decides it's tried enough to - negotiate LCP and gives up. Meanwhile, the client, who no - longer sees the reflections, becomes happy just in time to see - a hangup from the server.</para> - - <para>This can be avoided by allowing the peer to start - negotiating with the following line in your ppp.conf - file:</para> - - <programlisting>set openmode passive</programlisting> - - <para>This tells ppp to wait for the server to initiate LCP - negotiations. Some servers however may never initiate - negotiations. If this is the case, you can do something - like:</para> - - <programlisting>set openmode active 3</programlisting> - - <para>This tells ppp to be passive for 3 seconds, and then to - start sending LCP requests. If the peer starts sending - requests during this period, ppp will immediately respond - rather than waiting for the full 3 second period.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-lcp-constant"> - <para>LCP negotiations continue 'till the connection is - closed</para> - </question> - - <answer> - <para>There is currently an implementation mis-feature in - <emphasis remap=bf>ppp</emphasis> where it doesn't associate - LCP, CCP & IPCP responses with their original requests. As - a result, if one <emphasis remap=bf>ppp</emphasis> - implementation is more than 6 seconds slower than the other - side, the other side will send two additional LCP configuration - requests. This is fatal.</para> - - <para>Consider two implementations, - <emphasis remap=bf>A</emphasis> and <emphasis - remap=bf>B</emphasis>. <emphasis remap=bf>A</emphasis> starts - sending LCP requests immediately after connecting and <emphasis - remap=bf>B</emphasis> takes 7 seconds to start. When <emphasis - remap=bf>B</emphasis> starts, <emphasis remap=bf>A</emphasis> - has sent 3 LCP REQs. We're assuming the line has ECHO switched - off, otherwise we'd see magic number problems as described in - the previous section. <emphasis remap=bf>B</emphasis> sends a - REQ, then an ACK to the first of <emphasis - remap=bf>A</emphasis>'s REQs. This results in <emphasis - remap=bf>A</emphasis> entering the <acronym>OPENED</acronym> - state and sending and ACK (the first) back to <emphasis - remap=bf>B</emphasis>. In the meantime, <emphasis - remap=bf>B</emphasis> sends back two more ACKs in response to - the two additional REQs sent by <emphasis remap=bf>A</emphasis> - before <emphasis remap=bf>B</emphasis> started up. <emphasis - remap=bf>B</emphasis> then receives the first ACK from - <emphasis remap=bf>A</emphasis> and enters the - <acronym>OPENED</acronym> state. <emphasis - remap=bf>A</emphasis> receives the second ACK from <emphasis - remap=bf>B</emphasis> and goes back to the <emphasis - remap=bf>REQ-SENT</emphasis> state, sending another (forth) REQ - as per the RFC. It then receives the third ACK and enters the - <acronym>OPENED</acronym> state. In the meantime, <emphasis - remap=bf>B</emphasis> receives the forth REQ from <emphasis - remap=bf>A</emphasis>, resulting in it reverting to the - <emphasis remap=bf>ACK-SENT</emphasis> state and sending - another (second) REQ and (forth) ACK as per the RFC. <emphasis - remap=bf>A</emphasis> gets the REQ, goes into <emphasis - remap=bf>REQ-SENT</emphasis> and sends another REQ. It - immediately receives the following ACK and enters - <acronym>OPENED</acronym>.</para> - - <para>This goes on 'till one side figures out that they're - getting nowhere and gives up.</para> - - <para>The best way to avoid this is to configure one side to be - <emphasis remap=bf>passive</emphasis> - that is, make one side - wait for the other to start negotiating. This can be done - with the</para> - - <programlisting>set openmode passive</programlisting> - - <para>command. Care should be taken with this option. You - should also use the</para> - - <programlisting>set stopped N</programlisting> - - <para>command to limit the amount of time that - <emphasis remap=bf>ppp</emphasis> waits for the peer to begin - negotiations. Alternatively, the</para> - - <programlisting>set openmode active N</programlisting> - - <para>command (where <emphasis remap=bf>N</emphasis> is the - number of seconds to wait before starting negotiations) can be - used. Check the manual page for details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-lockups"> - <para>Ppp locks up shortly after connecting</para> - </question> - - <answer> - <para>Prior to version 2.2.5 of FreeBSD, it was possible that - your link was disabled shortly after connection due to - <emphasis remap=bf>ppp</emphasis> mis-handling Predictor1 - compression negotiation. This would only happen if both sides - tried to negotiate different Compression Control Protocols - (CCP). This problem is now corrected, but if you're still - running an old version of <emphasis remap=bf>ppp</emphasis>, - the problem can be circumvented with the line</para> - - <programlisting>disable pred1</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-shell-test-lockup"> - <para>Ppp locks up when I shell out to test it</para> - </question> - - <answer> - <para>When you execute the <command>shell</command> or - <command>!</command> command, <command>ppp</command> executes a - shell (or if you've passed any arguements, - <command>ppp</command> will execute those arguements). Ppp will - wait for the command to complete before continuing. If you - attempt to use the ppp link while running the command, the link - will appear to have frozen. This is because - <command>ppp</command> is waiting for the command to - complete.</para> - - <para>If you wish to execute commands like this, use the - <command>!bg</command> command instead. This will execute - the given command in the background, and ppp can continue to - service the link.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-nullmodem"> - <para>Ppp over a null-modem cable never exits</para> - </question> - - <answer> - <para>There is no way for <emphasis remap=bf>ppp</emphasis> to - automatically determine that a direct connection has been - dropped. This is due to the lines that are used in a - null-modem serial cable. When using this sort of connection, - LQR should always be enabled with the line</para> - - <programlisting>enable lqr</programlisting> - - <para>LQR is accepted by default if negotiated by the peer.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-auto-noreasondial"> - <para>Why does ppp dial for no reason in -auto mode</para> - </question><answer> - - <para>If <emphasis remap=bf>ppp</emphasis> is dialing - unexpectedly, you must determine the cause, and set up Dial - filters (dfilters) to prevent such dialing.</para> - - <para>To determine the cause, use the following line:</para> - - <programlisting>set log +tcp/ip</programlisting> - - <para>This will log all traffic through the connection. The - next time the line comes up unexpectedly, you will see the - reason logged with a convenient timestamp next to it.</para> - - <para>You can now disable dialing under these circumstances. - Usually, this sort of problem arises due to DNS lookups. To - prevent DNS lookups from establishing a connection (this will - <emphasis remap=bf>not</emphasis> prevent - <emphasis remap=bf>ppp</emphasis> from passing the packets - through an established connection), use the following:</para> - - <programlisting>set dfilter 1 deny udp src eq 53 -set dfilter 2 deny udp dst eq 53 -set dfilter 3 permit 0/0 0/0</programlisting> - - <para>This is not always suitable, as it will effectively break - your demand-dial capabilities - most programs will need a DNS - lookup before doing any other network related things.</para> - - <para>In the DNS case, you should try to determine what is - actually trying to resolve a host name. A lot of the time, - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?sendmail"> - sendmail</ulink> is the culprit. You should make sure that - you tell sendmail not to do any DNS lookups in its - configuration file. See the section on - <link linkend="ispmail">Mail Configuration</link> for details - on how to create your own configuration file and what should - go into it. You may also want to add the following line to - your <filename>.mc</filename> file:</para> - - <programlisting>define(`confDELIVERY_MODE', `d')dnl</programlisting> - - <para>This will make sendmail queue everything until the queue - is run (usually, sendmail is invoked with - <option>-bd -q30m</option>, telling it to run the queue every - 30 minutes) or until a <command>sendmail -q</command> is done - (perhaps from your ppp.linkup file).</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ccp-errors"> - <para>What do these CCP errors mean</para> - </question> - - <answer> - <para>I keep seeing the following errors in my log file:</para> - - <programlisting>CCP: CcpSendConfigReq -CCP: Received Terminate Ack (1) state = Req-Sent (6)</programlisting> - - <para>This is because ppp is trying to negotiate Predictor1 - compression, and the peer does not want to negotiate any - compression at all. The messages are harmless, but if you - wish to remove them, you can disable Predictor1 compression - locally too:</para> - - <programlisting>disable pred1</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-lockup-ioerrors"> - <para>Ppp locks up during file transfers with IO errors</para> - </question> - - <answer> - <para>Under FreeBSD 2.2.2 and before, there was a bug in the - tun driver that prevents incoming packets of a size larger - than the tun interface's MTU size. Receipt of a packet - greater than the MTU size results in an IO error being logged - via syslogd.</para> - - <para>The ppp specification says that an MRU of 1500 should - <emphasis remap=bf>always</emphasis> be accepted as a minimum, - despite any LCP negotiations, therefore it is possible that - should you decrease the MTU to less than 1500, your ISP will - transmit packets of 1500 regardless, and you will tickle this - non-feature - locking up your link.</para> - - <para>The problem can be circumvented by never setting an MTU of - less than 1500 under FreeBSD 2.2.2 or before.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-connectionspeed"> - <para>Why doesn't ppp log my connection speed?</para> - </question> - - <answer> - - <para>In order to log all lines of your modem - <quote>conversation</quote>, you must enable the - following:</para> - - <programlisting>set log +connect</programlisting> - - <para>This will make <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ppp">ppp</ulink> log - everything up until the last requested <quote>expect</quote> - string.</para> - - <para>If you wish to see your connect speed and are using PAP - or CHAP (and therefore don't have anything to - <quote>chat</quote> after the CONNECT in the dial script - no - <literal>set login</literal> script), you must make sure that - you instruct ppp to <quote>expect</quote> the whole CONNECT - line, something like this:</para> - - <programlisting>set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \ - \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n"</programlisting> - - <para>Here, we get our CONNECT, send nothing, then expect a - line-feed, forcing <emphasis remap=bf>ppp</emphasis> to read - the whole CONNECT response.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-ignores-backslash"> - <para>Ppp ignores the <literal>\</literal> character in my - chat script</para> - </question><answer> - - <para>Ppp parses each line in your config files so that it can - interpret strings such as - <literal>set phone "123 456 789"</literal> correctly (and - realize that the number is actually only - <emphasis remap=bf>one</emphasis> argument. In order to specify - a <literal>"</literal> character, you must escape it using a - backslash (<literal>\</literal>).</para> - - <para>When the chat interpreter parses each argument, it - re-interprets the argument in order to find any special - escape sequences such as <literal>\P</literal> or - <literal>\T</literal> (see the man page). As a result of this - double-parsing, you must remember to use the correct number of - escapes.</para> - - <para>If you wish to actually send a <literal>\</literal> - character to (say) your modem, you'd need something - like:</para> - - <programlisting>set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK"</programlisting> - - <para>resulting in the following sequence:</para> - - <programlisting>ATZ -OK -AT\X -OK</programlisting> - - <para>or</para> - - <programlisting>set phone 1234567 -set dial "\"\" ATZ OK ATDT\\T"</programlisting> - - <para>resulting in the following sequence:</para> - - <programlisting>ATZ -OK -ATDT1234567</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-segfault-nocore"> - <para>Ppp gets a seg-fault, but I see no - <filename>ppp.core</filename> file</para> - </question> - - <answer> - <para>Ppp (or any other program for that matter) should never - dump core. Because ppp runs with an effective user id of 0, - the operating system will not write ppps core image to disk - before terminating it. If, however ppp - <emphasis remap=bf>is</emphasis> actually termating due to a - segmentation violation or some other signal that normally - causes core to be dumped, <emphasis remap=bf>and</emphasis> - you're sure you're using the latest version (see the start of - this section), then you should do the following:</para> - - <screen>&prompt.user; <userinput>tar xfz ppp-*.src.tar.gz</userinput> -&prompt.user; <userinput>cd ppp*/ppp</userinput> -&prompt.user; <userinput>echo STRIP= >>Makefile</userinput> -&prompt.user; <userinput>echo CFLAGS+=-g >>Makefile</userinput> -&prompt.user; <userinput>make clean all</userinput> -&prompt.user; <userinput>su</userinput> -&prompt.root; <userinput>make install</userinput> -&prompt.root; <userinput>chmod 555 /usr/sbin/ppp</userinput></screen> - - <para>You will now have a debuggable version of ppp installed. - You will have to be root to run ppp as all of its privileges - have been revoked. When you start ppp, take a careful note - of what your current directory was at the time.</para> - - <para>Now, if and when ppp receives the segmentation violation, - it will dump a core file called ppp.core. You should then do - the following:</para> - - <screen>&prompt.user; <userinput>su</userinput> -&prompt.root; <userinput>gdb /usr/sbin/ppp ppp.core</userinput> -<prompt>(gdb)</prompt> <userinput>bt</userinput> -..... -<prompt>(gdb)</prompt> <userinput>f 0</userinput> -.... -<prompt>(gdb)</prompt> <userinput>i args</userinput> -.... -<prompt>(gdb)</prompt> <userinput>l</userinput> -.....</screen> - - <para>All of this information should be given alongside your - question, making it possible to diagnose the problem.</para> - - <para>If you're familiar with gdb, you may wish to find out some - other bits and pieces such as what actually caused the dump and - the addresses & values of the relevant variables.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-autodialprocess-noconnect"> - <para>The process that forces a dial in auto mode never - connects</para> - </question> - - <answer> - <para>This was a known problem with - <emphasis remap=bf>ppp</emphasis> set up to negotiate a - dynamic local IP number with the peer in auto mode. It is - fixed in the latest version - search the man page for - <emphasis remap=bf>iface</emphasis>.</para> - - <para>The problem was that when that initial program calls - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?connect"> - connect(2)</ulink>, the IP number of the tun interface is - assigned to the socket endpoint. The kernel creates the first - outgoing packet and writes it to the tun device. <emphasis - remap=bf>Ppp</emphasis> then reads the packet and establishes a - connection. If, as a result of <emphasis - remap=bf>ppp</emphasis>s dynamic IP assignment, the interface - address is changed, the original socket endpoint will be - invalid. Any subsequent packets sent to the peer will usually - be dropped. Even if they aren't, any responses will not route - back to the originating machine as the IP number is no longer - owned by that machine.</para> - - <para>There are several theoretical ways to approach this - problem. It would be nicest if the peer would re-assign the - same IP number if possible <emphasis remap=tt>:-)</emphasis> - The current version of <emphasis remap=bf>ppp</emphasis> does - this, but most other implementations don't.</para> - - <para>The easiest method from our side would be to never change - the tun interface IP number, but instead to change all outgoing - packets so that the source IP number is changed from the - interface IP to the negotiated IP on the fly. This is - essentially what the <literal>iface-alias</literal> option in - the latest version of <emphasis remap=bf>ppp</emphasis> is - doing (with the help of <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?libalias"> - libalias(3)</ulink> and ppp's <option>-nat</option> switch) - - it's maintaining all previous interface addresses and NATing - them to the last negotiated address.</para> - - <para>Another alternative (and probably the most reliable) would - be to implement a system call that changes all bound sockets - from one IP to another. <emphasis remap=bf>Ppp</emphasis> would - use this call to modify the sockets of all existing programs - when a new IP number is negotiated. The same system call could - be used by dhcp clients when they are forced to re-bind() their - sockets.</para> - - <para>Yet another possibility is to allow an interface to be - brought up without an IP number. Outgoing packets would be - given an IP number of 255.255.255.255 up until the first - SIOCAIFADDR ioctl is done. This would result in fully binding - the socket. It would be up to <emphasis remap=bf>ppp</emphasis> - to change the source IP number, but only if it's set to - 255.255.255.255, and only the IP number and IP checksum would - need to change. This, however is a bit of a hack as the kernel - would be sending bad packets to an improperly configured - interface, on the assumption that some other mechanism is - capable of fixing things retrospectively.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ppp-nat-games"> - <para>Why don't most games work with the -nat switch</para> - </question> - - <answer> - <para>The reason games and the like don't work when libalias - is in use is that the machine on the outside will try to open a - connection or send (unsolicited) UDP packets to the machine on - the inside. The NAT software doesn't know that it should send - these packets to the interior machine.</para> - - <para>To make things work, make sure that the only thing - running is the software that you're having problems with, then - either run tcpdump on the tun interface of the gateway or - enable ppp tcp/ip logging (<literal>set log +tcp/ip</literal>) - on the gateway.</para> - - <para>When you start the offending software, you should see - packets passing through the gateway machine. When something - comes back from the outside, it'll be dropped (that's the - problem). Note the port number of these packets then shut down - the offending software. Do this a few times to see if the port - numbers are consistent. If they are, then the following line in - the relevant section of /etc/ppp/ppp.conf will make the - software functional:</para> - - <programlisting>nat port <replaceable>proto</replaceable> <replaceable>internalmachine</replaceable>:<replaceable>port</replaceable> <replaceable>port</replaceable></programlisting> - - <para>where <replaceable>proto</replaceable> is either - <literal>tcp</literal> or <literal>udp</literal>, - <replaceable>internalmachine</replaceable> is the machine that - you want the packets to be sent to and - <replaceable>port</replaceable> is the destination port number - of the packets.</para> - - <para>You won't be able to use the software on other machines - without changing the above command, and running the software - on two internal machines at the same time is out of the question - - after all, the outside world is seeing your entire internal - network as being just a single machine.</para> - - <para>If the port numbers aren't consistent, there are three - more options:</para> - - <para><emphasis remap=bf>1)</emphasis> Submit support in - libalias. Examples of <quote>special cases</quote> can be found - in <filename>/usr/src/lib/libalias/alias_*.c</filename> - (<filename>alias_ftp.c</filename> is a good prototype). This - usually involves reading certain recognised outgoing packets, - identifying the instruction that tells the outside machine to - initiate a connection back to the internal machine on a - specific (random) port and setting up a <quote>route</quote> in - the alias table so that the subsequent packets know where to - go.</para> - - <para>This is the most difficult solution, but it is the best - and will make the software work with multiple machines.</para> - - <para><emphasis remap=bf>2)</emphasis> Use a proxy. The - application may support socks5 for example, or (as in the - <quote>cvsup</quote> case) may have a <quote>passive</quote> - option that avoids ever requesting that the peer open - connections back to the local machine.</para> - - <para><emphasis remap=bf>3)</emphasis> Redirect everything to - the internal machine using <literal>nat addr</literal>. This - is the sledge-hammer approach.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="useful-port-numbers"> - <para>Has anybody made a list of useful port numbers ?</para> - </question><answer> - - <para>Not yet, but this is intended to grow into such a list - (if any interest is shown). In each example, - <replaceable>internal</replaceable> should be replaced with - the IP number of the machine playing the game.</para> - - <itemizedlist> - <listitem> - <para><application>Asheron's Call</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable> - :65000 65000</literal></para> - - <para>Manually change the port number within the game to - 65000. If you've got a number of machines that you wish - to play on assign a unique port number for each (i.e. - 65001, 65002, etc) and add a <literal>nat port</literal> - line for each one.</para> - </listitem> - - <listitem> - <para><application>Half Life</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:27005 - 27015</literal></para> - </listitem> - - <listitem> - <para><application>PCAnywhere 8.0</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:5632 - 5632</literal></para> - - <para><literal>nat port tcp - <replaceable>internal</replaceable>:5631 - 5631</literal></para> - </listitem> - - <listitem> - <para><application>Quake</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:6112 - 6112</literal></para> - - <para>Alternatively, you may want to take a look at <ulink - URL="http://www.battle.net/support/proxy/"> - www.battle.net</ulink> for Quake proxy support.</para> - </listitem> - - <listitem> - <para><application>Quake 2</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:27901 - 27910</literal></para> - </listitem> - - <listitem> - <para><application>Red Alert</application></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:8675 - 8675</literal></para> - - <para><literal>nat port udp - <replaceable>internal</replaceable>:5009 - 5009</literal></para> - </listitem> - </itemizedlist> - - </answer> - </qandaentry> - - <qandaentry> - <question id="fcs-errors"> - <para>What are FCS errors ?</para> - </question> - - <answer> - <para>FCS stands for <emphasis remap=bf>F</emphasis>rame - <emphasis remap=bf>C</emphasis>heck - <emphasis remap=bf>S</emphasis>equence. Each ppp packet - has a checksum attached to ensure that the data being - received is the data being sent. If the FCS of an incoming - packet is incorrect, the packet is dropped and the HDLC FCS - count is increased. The HDLC error values can be displayed - using the <literal>show hdlc</literal> command.</para> - - <para>If your link is bad (or if your serial driver is dropping - packets), you will see the occasional FCS error. This is not - usually worth worrying about although it does slow down the - compression protocols substantially. If you have an external - modem, make sure your cable is properly shielded from - interference - this may eradicate the problem.</para> - - <para>If your link freezes as soon as you've connected and you - see a large number of FCS errors, this may be because your link - is not 8 bit clean. Make sure your modem is not using software - flow control (XON/XOFF). If your datalink - <emphasis>must</emphasis> use software flow control, use the - command <literal>set accmap 0x000a0000</literal> to tell - <command>ppp</command> to escape the <literal>^Q</literal> and - <literal>^S</literal> characters.</para> - - <para>Another reason for seeing too many FCS errors may be that - the remote end has stopped talking <acronym>PPP</acronym>. You - may want to enable <literal>async</literal> logging at this - point to determine if the incoming data is actually a login or - shell prompt. If you have a shell prompt at the remote end, - it's possible to terminate ppp without dropping the line by - using the <literal>close lcp</literal> command (a following - <literal>term</literal> command will reconnect you to the shell - on the remote machine.</para> - - <para>If nothing in your log file indicates why the link might - have been terminated, you should ask the remote administrator - (your ISP?) why the session was terminated.</para> - - </answer> - </qandaentry> - - <qandaentry id=PPPoEwithNAT> - <question id="macos-win98-pppoe-freeze"> - <para>Why do MacOS and Windows 98 connections freeze when - running PPPoE on the gateway</para> - </question> - - <answer> - <para>Thanks to Michael Wozniak - <email>mwozniak@netcom.ca</email> for figuring this out and - Dan Flemming <email>danflemming@mac.com</email> for the Mac - solution:</para> - - <para>This is due to what's called a <quote>Black Hole</quote> - router. MacOS and Windows 98 (and maybe other Microsoft OSs) - send TCP packets with a requested segment size too big to fit - into a PPPoE frame (MTU is 1500 by default for ethernet) - <emphasis remap=bf>and</emphasis> have the <quote>don't - fragment</quote> bit set (default of TCP) and the Telco router - is not sending ICMP <quote>must fragment</quote> back to the - www site you are trying to load. When the www server is sending - you frames that don't fit into the PPPoE pipe the Telco router - drops them on the floor and your page doesn't load (some - pages/graphics do as they are smaller than a MSS.) This seems - to be the default of most Telco PPPoE configurations (if only - they knew how to program a router... sigh...)</para> - - <para>One fix is to use regedit on your 95/98 boxes to add the - following registry entry...</para> - - <literallayout> - HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU - </literallayout> - - <para>It should be a string with a value <quote>1450</quote> - (more accurately it should be <quote>1464</quote> to fit TCP - packets into a PPPoE frame perfectly but the - <quote>1450</quote> gives you a margin of error for other IP - protocols you may encounter).</para> - - <para>Refer to MS KB # <quote>Q158474 - Windows TCPIP Registry - Entries</quote> and <quote>Q120642 - TCPIP & NBT Configuration - Parameters for Windows NT </quote> for more information on - changing Windoze MTU to work with a FreeBSD/NAT/PPPoE - router.</para> - - <para>Unfortunately, MacOS does not provide an interface for - changing TCP/IP settings. However, there is commercial software - available, such as OTAdvancedTuner (OT for OpenTransport, the - MacOS TCP/IP stack) by <ulink - URL="http://www.softworks.com/">Sustainable Softworks</ulink>, - that will allow users to customize TCP/IP settings. MacOS NAT - users should select <literal>ip_interface_MTU</literal> from - the drop-down menu, enter <literal>1450</literal> instead of - <literal>1500</literal> in the box, click the box next to - <literal>Save as Auto Configure</literal>, and click - <literal>Make Active</literal>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="desperation"> - <para>None of this helps - I'm desperate !</para> - </question> - - <answer> - <para>If all else fails, send as much information as you can, - including your config files, how you're starting - <emphasis remap=bf>ppp</emphasis>, the relevant parts of your - log file and the output of the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?netstat"> - netstat -rn</ulink> command (before and after connecting) to - the <email>freebsd-questions@FreeBSD.org</email> mailing list - or the <ulink URL="news:comp.unix.bsd.freebsd.misc"> - comp.unix.bsd.freebsd.misc</ulink> news group, and someone - should point you in the right direction.</para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="serial"> - <title>Serial Communications</title> - - <para>This section answers common questions about serial - communications with FreeBSD. PPP and SLIP are covered in the - <xref linkend="networking" remap="Networking"> section.</para> - - - <qandaset> - <qandaentry> - <question id="found-serial"> - <para>How do I tell if FreeBSD found my serial ports?</para> - </question> - - <answer> - <para>As the FreeBSD kernel boots, it will probe for the serial - ports in your system for which the kernel was configured. - You can either watch your system closely for the messages it - prints or run the command</para> - - <screen>&prompt.user; <userinput>dmesg | grep sio</userinput></screen> - - <para>after your system's up and running.</para> - - <para>Here's some example output from the above command:</para> - - <programlisting>sio0 at 0x3f8-0x3ff irq 4 on isa -sio0: type 16550A -sio1 at 0x2f8-0x2ff irq 3 on isa -sio1: type 16550A</programlisting> - - <para>This shows two serial ports. The first is on irq 4, is - using port address <literal>0x3f8</literal>, and has a - 16550A-type UART chip. The second uses the same kind of chip - but is on irq 3 and is at port address <literal>0x2f8</literal>. - Internal modem cards are treated just like serial ports---except - that they always have a modem <quote>attached</quote> to the - port.</para> - - <para>The <filename>GENERIC</filename> kernel includes support - for two serial ports using the same irq and port address - settings in the above example. If these settings aren't - right for your system, or if you've added modem cards or have - more serial ports than your kernel is configured for, just - reconfigure your kernel. See section - <link linkend="make-kernel">about building a kernel</link> for - more details.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="found-modem"> - <para>How do I tell if FreeBSD found my modem cards?</para> - </question> - - <answer> - <para>Refer to the answer to the previous question.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="missing-tty0X"> - <para>I just upgraded to 2.0.5 and my - <filename>tty0X</filename> are missing!</para> - </question> - - <answer> - <para>Don't worry, they have been merged with the - <filename>ttydX</filename> devices. You'll have to change - any old configuration files you have, though.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="access-serial-ports"> - <para>How do I access the serial ports on FreeBSD?</para> - </question> - - <answer> - <para>The third serial port, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sio">sio2</ulink> - (known as COM3 in DOS), is on <filename>/dev/cuaa2</filename> - for dial-out devices, and on <filename>/dev/ttyd2</filename> - for dial-in devices. What's the difference between these two - classes of devices?</para> - - <para>You use <filename>ttydX</filename> for dial-ins. When - opening <filename>/dev/ttydX</filename> in blocking mode, a - process will wait for the corresponding - <filename>cuaaX</filename> device to become inactive, and then - wait for the carrier detect line to go active. When you open - the <filename>cuaaX</filename> device, it makes sure the serial - port isn't already in use by the <filename>ttydX</filename> - device. If the port's available, it <quote>steals</quote> it - from the <filename>ttydX</filename> device. Also, the - <filename>cuaXX</filename> device doesn't care about carrier - detect. With this scheme and an auto-answer modem, you can have - remote users log in and you can still dialout with the same - modem and the system will take care of all the - conflicts.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="enable-multiport-serial"> - <para>How do I enable support for a multiport serial - card?</para> - </question> - - <answer> - <para>Again, the section on kernel configuration provides - information about configuring your kernel. For a multiport - serial card, place an <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?sio">sio</ulink> line - for each serial port on the card in the kernel configuration - file. But place the irq and vector specifiers on only one of - the entries. All of the ports on the card should share one irq. - For consistency, use the last serial port to specify the irq. - Also, specify the <literal>COM_MULTIPORT</literal> - option.</para> - - <para>The following example is for an AST 4-port serial card on - irq 7:</para> - - <programlisting>options "COM_MULTIPORT" -device sio4 at isa? port 0x2a0 tty flags 0x781 -device sio5 at isa? port 0x2a8 tty flags 0x781 -device sio6 at isa? port 0x2b0 tty flags 0x781 -device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr</programlisting> - - <para>The flags indicate that the master port has minor number 7 - (<literal>0x700</literal>), diagnostics enabled during probe - (<literal>0x080</literal>), and all the ports share an irq - (<literal>0x001</literal>).</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="multiport-serial-share-irq"> - <para>Can FreeBSD handle multiport serial cards sharing - irqs?</para> - </question> - - <answer> - <para>Not yet. You'll have to use a different irq for each - card.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="default-serial-params"> - <para>Can I set the default serial parameters for a - port?</para> - </question> - - <answer> - <para>The <filename>ttydX</filename> (or - <filename>cuaaX</filename>) device is the regular device - you'll want to open for your applications. When a process - opens the device, it'll have a default set of terminal I/O - settings. You can see these settings with the command</para> - - <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen> - - <para>When you change the settings to this device, the settings - are in effect until the device is closed. When it's reopened, - it goes back to the default set. To make changes to the - default set, you can open and adjust the settings of the - <quote>initial state</quote> device. For example, to turn on - <acronym>CLOCAL</acronym> mode, 8 bits, and - <filename>XON/XOFF</filename> flow control by default for - ttyd5, do:</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen> - - <para>A good place to do this is in - <filename>/etc/rc.serial</filename>. Now, an application will - have these settings by default when it opens - <filename>ttyd5</filename>. It can still change these settings - to its liking, though.</para> - - <para>You can also prevent certain settings from being changed - by an application by making adjustments to the - <quote>lock state</quote> device. For example, to lock the - speed of <filename>ttyd5</filename> to 57600 bps, do</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen> - - <para>Now, an application that opens <filename>ttyd5</filename> - and tries to change the speed of the port will be stuck with - 57600 bps.</para> - - <para>Naturally, you should make the initial state and lock state - devices writable only by <username>root</username>. The <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?MAKEDEV">MAKEDEV</ulink> - script does <emphasis>NOT</emphasis> do this when it creates the - device entries.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="enable-dialup"> - <para>How can I enable dialup logins on my modem?</para> - </question> - - <answer> - <para>So you want to become an Internet service provider, eh? - First, you'll need one or more modems that can auto-answer. - Your modem will need to assert carrier-detect when it detects a - carrier and not assert it all the time. It will need to hang up - the phone and reset itself when the data terminal ready - (<acronym>DTR</acronym>) line goes from on to off. It should - probably use <filename>RTS/CTS</filename> flow control or no - local flow control at all. Finally, it must use a constant - speed between the computer and itself, but (to be nice to your - callers) it should negotiate a speed between itself and the - remote modem.</para> - - <para>For many Hayes command-set--compatible modems, this - command will make these settings and store them in - nonvolatile memory:</para> - - <programlisting>AT &C1 &D3 &K3 &Q6 S0=1 &W</programlisting> - - <para>See the section <link linkend="direct-at">on sending AT - commands</link> below for information on how to make these - settings without resorting to an MS-DOS terminal program.</para> - - <para>Next, make an entry in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys"> - /etc/ttys</ulink> for the modem. This file lists all the ports - on which the operating system will await logins. Add a line - that looks something like this:</para> - - <programlisting>ttyd1 "/usr/libexec/getty std.57600" dialup on insecure</programlisting> - - <para>This line indicates that the second serial port - (<filename>/dev/ttyd1</filename>) has a modem connected - running at 57600 bps and no parity - (<literal>std.57600</literal>, which comes from the file <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?gettytab">/etc/gettytab</ulink>). - The terminal type for this port is <literal>dialup</literal>. - The port is <literal>on</literal> and is - <literal>insecure</literal>---meaning root logins on the port - aren't allowed. For dialin ports like this one, use the - <literal>ttydX</literal> entry.</para> - - <para>It's common practice to use <literal>dialup</literal> as - the terminal type. Many users set up in their .profile or - .login files a prompt for the actual terminal type if the - starting type is dialup. The example shows the port as - insecure. To become root on this port, you have to login as a - regular user, then <command>su</command> to become - <username>root</username>. If you use <literal>secure</literal> - then <username>root</username> can login in directly.</para> - - <para>After making modifications to <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys"> - /etc/ttys</ulink>, you need to send a hangup or - <acronym>HUP</acronym> signal to the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?init"> - init</ulink> process:</para> - - <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> - - <para>This forces the init process to reread <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys"> - /etc/ttys</ulink>. The init process will then start getty - processes on all <literal>on</literal> ports. You can find - out if logins are available for your port by typing</para> - - <screen>&prompt.user; <userinput>ps -ax | grep '[t]tyd1'</userinput></screen> - - <para>You should see something like:</para> - - <programlisting>747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dumb-terminal"> - <para>How can I connect a dumb terminal to my FreeBSD - box?</para> - </question> - - <answer> - <para>If you're using another computer as a terminal into your - FreeBSD system, get a null modem cable to go between the two - serial ports. If you're using an actual terminal, see its - accompanying instructions.</para> - - <para>Then, modify <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ttys"> - /etc/ttys</ulink>, like above. For example, if you're - hooking up a WYSE-50 terminal to the fifth serial port, - use an entry like this:</para> - - <programlisting>ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure</programlisting> - - <para>This example shows that the port on - <filename>/dev/ttyd4</filename> has a wyse50 terminal - connected at 38400 bps with no parity - (<literal>std.38400</literal> from <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?gettytab"> - /etc/gettytab</ulink>) and <literal>root</literal> logins are - allowed (secure).</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cannot-tip"> - <para>Why can't I run <command>tip</command> or - <command>cu</command>?</para> - </question> - - <answer> - <para>On your system, the programs <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> - and <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?cu"> - cu</ulink> are probably executable only by <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?uucp">uucp</ulink> - and group <literal>dialer</literal>. You can use the group - <literal>dialer</literal> to control who has access to your - modem or remote systems. Just add yourself to group - dialer.</para> - - <para>Alternatively, you can let everyone on your system - run <command>tip</command> and <command>cu</command> by - typing:</para> - - <screen>&prompt.root; <userinput>chmod 4511 /usr/bin/cu</userinput> -&prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen> - - </answer> - </qandaentry> - - <qandaentry> - <question id="hayes-unsupported"> - <para>My stock Hayes modem isn't supported---what - can I do?</para> - </question> - - <answer> - <para>Actually, the man page for <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> is - out of date. There is a generic Hayes dialer already built in. - Just use <literal>at=hayes</literal> in your <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?remote"> - /etc/remote</ulink> file.</para> - - <para>The Hayes driver isn't smart enough to recognize some of - the advanced features of newer modems---messages like - <literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or - <literal>CONNECT 115200</literal> will just confuse it. You - should turn those messages off when you use <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> - (using <literal>ATX0&W</literal>).</para> - - <para>Also, the dial timeout for <command>tip</command> is 60 - seconds. Your modem should use something less, or else tip - will think there's a communication problem. Try - <literal>ATS7=45&W</literal>.</para> - - <para>Actually, as shipped <command>tip</command> doesn't yet - support it fully. The solution is to edit the file - <filename>tipconf.h</filename> in the directory - <filename>/usr/src/usr.bin/tip/tip</filename>. Obviously you - need the source distribution to do this.</para> - - <para>Edit the line <literal>#define HAYES 0</literal> - to <literal>#define HAYES 1</literal>. Then - <command>make</command> and <command>make install</command>. - Everything works nicely after that.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="direct-at"> - <para>How am I expected to enter these AT commands?</para> - </question> - - <answer> - <para>Make what's called a <quote>direct</quote> entry in your - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?remote"> - /etc/remote</ulink> file. For example, if your modem's hooked - up to the first serial port, <filename>/dev/cuaa0</filename>, - then put in the following line:</para> - - <programlisting>cuaa0:dv=/dev/cuaa0:br#19200:pa=none</programlisting> - - <para>Use the highest bps rate your modem supports in the br - capability. Then, type <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip cuaa0</ulink> - and you'll be connected to your modem.</para> - - <para>If there is no <filename>/dev/cuaa0</filename> on your - system, do this:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV cuaa0</userinput></screen> - - <para>Or use cu as root with the following command:</para> - - <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen> - - <para>with line being the serial port (e.g. - <filename>/dev/cuaa0</filename>) and speed being the speed - (e.g.<literal>57600</literal>). When you are done entering - the AT commands hit <literal>~.</literal> to exit.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="gt-failure"> - <para>The <literal><@></literal> sign for the pn - capability doesn't work!</para></question><answer> - - <para>The <literal><@></literal> sign in the phone number - capability tells tip to look in - <filename>/etc/phones</filename> for a phone number. But the - <literal><@></literal> sign is also a special character - in capability files like <filename>/etc/remote</filename>. - Escape it with a backslash:</para> - - <programlisting>pn=\@</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dial-command-line"> - <para>How can I dial a phone number on the command - line?</para> - </question><answer> - - <para>Put what's called a <quote>generic</quote> entry in your - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?remote"> - /etc/remote</ulink> file. For example:</para> - - <programlisting>tip115200|Dial any phone number at 115200 bps:\ - :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: -tip57600|Dial any phone number at 57600 bps:\ - :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>Then you can do something like <command>tip -115200 - 5551234</command>. If you prefer <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?cu">cu</ulink> - over <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?tip"> - tip</ulink>, use a generic cu entry:</para> - - <programlisting>cu115200|Use cu to dial any number at 115200bps:\ - :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>and type <command>cu 5551234 -s 115200</command>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="set-bps"> - <para>Do I have to type in the bps rate every time I do - that?</para> - </question><answer> - - <para>Put in an entry for <literal>tip1200</literal> or - <literal>cu1200</literal>, but go ahead and use whatever bps - rate is appropriate with the br capability. <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> - thinks a good default is 1200 bps which is why it looks for - a <literal>tip1200</literal> entry. You don't have to use 1200 - bps, though.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="terminal-server"> - <para>I access a number of hosts through a terminal - server.</para> - </question> - - <answer> - <para>Rather than waiting until you're connected and typing - <literal>CONNECT <replaceable>host</replaceable></literal> - each time, use tip's <literal>cm</literal> capability. For - example, these entries in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?remote"> - /etc/remote</ulink>:</para> - - <programlisting>pain|pain.deep13.com|Forrester's machine:\ - :cm=CONNECT pain\n:tc=deep13: -muffin|muffin.deep13.com|Frank's machine:\ - :cm=CONNECT muffin\n:tc=deep13: -deep13:Gizmonics Institute terminal server:\ - :dv=/dev/cua02:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting> - - <para>will let you type <command>tip pain</command> or - <command>tip muffin</command> to connect to the hosts - <hostid>pain</hostid> or <hostid>muffin</hostid>; and - <command>tip deep13</command> to get to the terminal - server.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="tip-multiline"> - <para>Can tip try more than one line for each site?</para> - </question> - - <answer> - <para>This is often a problem where a university has several - modem lines and several thousand students trying to use - them...</para> - - <para>Make an entry for your university in <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?remote"> - /etc/remote</ulink> and use <literal><\@></literal> for - the <literal>pn</literal> capability:</para> - - <programlisting>big-university:\ - :pn=\@:tc=dialout -dialout:\ - :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:</programlisting> - - <para>Then, list the phone numbers for the university in - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?phones"> - /etc/phones</ulink>:</para> - - <programlisting>big-university 5551111 -big-university 5551112 -big-university 5551113 -big-university 5551114</programlisting> - - <para><ulink URL="http://www.FreeBSD.org/cgi/man.cgi?tip"> - tip</ulink> will try each one in the listed order, then give - up. If you want to keep retrying, run <command>tip</command> - in a while loop.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="multi-controlp"> - <para>Why do I have to hit CTRL+P twice to send CTRL+P - once?</para> - </question> - - <answer> - <para>CTRL+P is the default <quote>force</quote> character, - used to tell <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> - that the next character is literal data. You can set the - force character to any other character with the - <literal>~s</literal> escape, which means <quote>set a - variable</quote>.</para> - - <para>Type <literal>~sforce=<replaceable>single-char - </replaceable></literal> followed by a newline. - <replaceable>single-char</replaceable> is any single character. - If you leave out <replaceable>single-char</replaceable>, - then the force character is the nul character, which you can - get by typing CTRL+2 or CTRL+SPACE. A pretty good value for - <replaceable>single-char</replaceable> is SHIFT+CTRL+6, which - I've seen only used on some terminal servers.</para> - - <para>You can have the force character be whatever you want by - specifying the following in your - <filename>$HOME/.tiprc</filename> file:</para> - - <programlisting>force=<replaceable>single-char</replaceable></programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="uppercase"> - <para>Suddenly everything I type is in UPPER CASE??</para> - </question> - - <answer> - <para>You must've pressed CTRL+A, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?tip"> - tip</ulink> <quote>raise character</quote>, specially - designed for people with broken caps-lock keys. Use - <literal>~s</literal> as above and set the variable - <quote>raisechar</quote> to something reasonable. In fact, - you can set it to the same as the force character, if you - never expect to use either of these features.</para> - - <para>Here's a sample .tiprc file perfect for Emacs users who - need to type CTRL+2 and CTRL+A a lot:</para> - - <programlisting>force=^^ -raisechar=^^</programlisting> - -<para>The ^^ is SHIFT+CTRL+6.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="tip-filetransfer"> - <para>How can I do file transfers with - <command>tip</command>?</para> - </question> - - <answer> - <para>If you're talking to another UNIX system, you can send - and receive files with <literal>~p</literal> (put) and - <literal>~t</literal> (take). These commands run <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?cat">cat</ulink> and - <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?echo"> - echo</ulink> on the remote system to accept and send files. - The syntax is:</para> - - <programlisting>~p <local-file> [<remote-file>] -~t <remote-file> [<local-file>]</programlisting> - - <para>There's no error checking, so you probably should use - another protocol, like zmodem.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="zmodem-tip"> - <para>How can I run zmodem with - <emphasis remap=tt>tip</emphasis>?</para> - </question> - - <answer> - <para>First, install one of the zmodem programs from the ports - collection (such as one of the two from the comms category, - <ulink URL="http://www.FreeBSD.org/cgi/ports.cgi?^lrzsz"> - lrzsz</ulink> and <ulink - URL="http://www.FreeBSD.org/cgi/ports.cgi?^rzsz"> - rzsz</ulink>).</para> - - <para>To receive files, start the sending program on the - remote end. Then, press enter and type - <literal>~C rz</literal> (or <literal>~C lrz</literal> if you - installed <application>lrzsz</application>) to begin - receiving them locally.</para> - - <para>To send files, start the receiving program on the remote - end. Then, press enter and type - <literal>~C sz <replaceable>files</replaceable></literal> - (or <literal>~C lsz <replaceable>files</replaceable></literal>) - to send them to the remote system.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="cannot-find-serial"> - <para>FreeBSD can't seem to find my serial ports, even when - the settings are correct.</para> - </question> - - <answer> - <para>Motherboards and cards with Acer UARTs do not probe - properly under the FreeBSD sio probe. Obtain a patch from - <ulink URL="http://www.lemis.com/serial-port-patch.html"> - www.lemis.com</ulink> to fix your problem.</para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="misc"> - <title>Miscellaneous Questions</title> - - <qandaset> - <qandaentry> - <question id="more-swap"> - <para>FreeBSD uses far more swap space than Linux. Why?</para> - </question> - - <answer> - <para>FreeBSD only appears to use more swap than Linux. In - actual fact, it does not. The main difference between FreeBSD - and Linux in this regard is that FreeBSD will proactively move - entirely idle, unused pages of main memory into swap in order - to make more main memory available for active use. Linux tends - to only move pages to swap as a last resort. The perceived - heavier use of swap is balanced by the more efficient use of - main memory. </para> - - <para>Note that while FreeBSD is proactive in this regard, it - does not arbitrarily decide to swap pages when the system is - truely idle. Thus you will not find your system all paged - out when you get up in the morning after leaving it idle - overnight.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="top-freemem"> - <para>Why does &man.top.1; show very little free memory even - when I have very few programs running?</para> - </question> - - <answer> - <para>The simple answer is that free memory is wasted - memory. Any memory that your programs don't actively - allocate is used within the FreeBSD kernel as disk - cache. The values shown by &man.top.1; labelled as - <literal>Inact</literal>, <literal>Cache</literal>, and - <literal>Buf</literal> are all cached data at different - aging levels. This cached data means the system does - not have to access a slow disk again for data it has - accessed recently, thus increasing overall performance. - In general, a low value shown for <literal>Free</literal> - memory in &man.top.1; is good, provided it is not - <emphasis>very</emphasis> low.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="aout-elf"> - <para>Why use (what are) a.out and ELF executable - formats? </para> - </question> - - <answer> - <para>To understand why FreeBSD uses the - <filename>ELF</filename> format, you must first know a little - about the 3 currently <quote>dominant</quote> executable - formats for UNIX:</para> - - <para> - <note> - <para>Prior to FreeBSD 3.x, FreeBSD used the a.out - format.</para> - </note></para> - - <para> - <itemizedlist> - <listitem> - <para><ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?a.out(5)"> - a.out</ulink></para> - - <para>The oldest and <quote>classic</quote> unix object - format. It uses a short and compact header with a magic - number at the beginning that's often used to - characterize the format (see <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?a.out(5)"> - a.out(5)</ulink> for more details). It contains three - loaded segments: .text, .data, and .bss plus a symbol - table and a string table.</para> - - <para></para> - </listitem> - - <listitem> - <para><acronym>COFF</acronym></para> - - <para>The SVR3 object format. The header now comprises - a section table, so you can have more than just .text, - .data, and .bss sections.</para> - </listitem> - - <listitem> - <para><acronym>ELF</acronym></para> - - <para>The successor to <acronym>COFF</acronym>, featuring - Multiple sections and 32-bit or 64-bit possible values. - One major drawback: <acronym>ELF</acronym> was also - designed with the assumption that there would be only - one ABI per system architecture. That assumption is - actually quite incorrect, and not even in the - commercial SYSV world (which has at least three ABIs: - SVR4, Solaris, SCO) does it hold true.</para> - - <para></para> - - <para>FreeBSD tries to work around this problem somewhat - by providing a utility for <emphasis>branding</emphasis> - a known <acronym>ELF</acronym> executable with - information about the ABI it's compliant with. See the - man page for <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?brandelf"> - brandelf</ulink> for more information.</para> - </listitem> - </itemizedlist></para> - - <para>FreeBSD comes from the <quote>classic</quote> camp and has - traditionally used the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?a.out(5)"> - a.out</ulink> format, a technology tried and proven through - many generations of BSD releases. Though it has also been - possible for some time to build and run native - <acronym>ELF</acronym> binaries (and kernels) on a FreeBSD - system, FreeBSD initially resisted the <quote>push</quote> to - switch to <acronym>ELF</acronym> as the default format. Why? - Well, when the Linux camp made their painful transition to - <acronym>ELF</acronym>, it was not so much to flee the - <filename>a.out</filename> executable format as it was their - inflexible jump-table based shared library mechanism, which - made the construction of shared libraries very difficult for - vendors and developers alike. Since the <acronym>ELF</acronym> - tools available offered a solution to the shared library - problem and were generally seen as <quote>the way - forward</quote> anyway, the migration cost was accepted as - necessary and the transition made.</para> - - <para>In FreeBSD's case, our shared library mechanism is based - more closely on Sun's <emphasis remap=tt>SunOS</emphasis>-style - shared library mechanism and, as such, is very easy to use. - However, starting with 3.0, FreeBSD officially supports - <acronym>ELF</acronym> binaries as the default format. Even - though the <filename>a.out</filename> executable format has - served us well, the GNU people, who author the compiler tools - we use, have dropped support for the <filename>a.out</filename> - format. This has forced us to maintain a divergent version of - the compler and linker, and has kept us from reaping the - benefits of the latest GNU development efforts. Also the - demands of ISO-C++, notably contstructors and destructors, has - also led to native <acronym>ELF</acronym> support in future - FreeBSD releases.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="binary-formats"> - <para>Yes, but why are there so many different formats?</para> - </question> - - <answer> - <para>Back in the dim, dark past, there was simple hardware. - This simple hardware supported a simple, small system. a.out - was completely adequate for the job of representing binaries on - this simple system (a PDP-11). As people ported unix from this - simple system, they retained the a.out format because it was - sufficient for the early ports of unix to architectures like - the Motorola 68k, VAXen, etc.</para> - - <para>Then some bright hardware engineer decided that if he - could force software to do some sleazy tricks, then he'd be - able to shave a few gates off the design and allow his CPU core - to run faster. While it was made to work with this new kind of - hardware (known these days as RISC), <filename>a.out</filename> - was ill-suited for this hardware, so many formats were - developed to get to a better performance from this hardware - than the limited, simple <filename>a.out</filename> format - could offer. Things like <acronym>COFF</acronym>, - <acronym>ECOFF</acronym>, and a few obscure others were - invented and their limitations explored before things seemed to - settle on <acronym>ELF</acronym>.</para> - - <para>In addition, program sizes were getting huge and disks - (and physical memory) were still relatively small so the - concept of a shared library was born. The VM system also became - more sophisticated. While each one of these advancements was - done using the <filename>a.out</filename> format, its - usefulness was stretched more and more with each new feature. - In addition, people wanted to dynamically load things at run - time, or to junk parts of their program after the init code had - run to save in core memory and/or swap space. Languages became - more sophistocated and people wanted code called before main - automatically. Lots of hacks were done to the - <filename>a.out</filename> format to allow all of these things - to happen, and they basically worked for a time. In time, - <filename>a.out</filename> wasn't up to handling all these - problems without an ever increasing overhead in code and - complexity. While <acronym>ELF</acronym> solved many of these - problems, it would be painful to switch from the system that - basically worked. So <acronym>ELF</acronym> had to wait until - it was more painful to remain with <filename>a.out</filename> - than it was to migrate to <acronym>ELF</acronym>.</para> - - <para>However, as time passed, the build tools that FreeBSD - derived their build tools from (the assembler and loader - especially) evolved in two parallel trees. The FreeBSD tree - added shared libraries and fixed some bugs. The GNU folks that - originally write these programs rewrote them and added simpler - support for building cross compilers, plugging in different - formats at will, etc. Since many people wanted to build cross - compilers targeting FreeBSD, they were out of luck since the - older sources that FreeBSD had for as and ld weren't up to the - task. The new gnu tools chain (binutils) does support cross - compiling, <acronym>ELF</acronym>, shared libraries, C++ - extnensions, etc. In addition, many vendors are releasing - <acronym>ELF</acronym> binaries, and it is a good thing for - FreeBSD to run them. And if it is running - <acronym>ELF</acronym> binaries, why bother having - <filename>a.out</filename> any more? It is a tired old horse - that has proven useful for a long time, but it is time to turn - him out to pasture for his long, faithful years of - service.</para> - - <para><acronym>ELF</acronym> is more expressive than a.out and - will allow more extensibility in the base system. The - <acronym>ELF</acronym> tools are better maintained, and offer - cross compilation support, which is important to many people. - <acronym>ELF</acronym> may be a little slower than a.out, but - trying to measure it can be difficult. There are also numerous - details that are different between the two in how they map - pages, handle init code, etc. None of these are very important, - but they are differences. In time support for - <filename>a.out</filename> will be moved out of the GENERIC - kernel, and eventually removed from the kernel once the need to - run legacy <filename>a.out</filename> programs is past.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="chmod-symlinks"> - <para>Why won't chmod change the permissions on symlinks?</para> - </question> - - <answer> - <para>Symlinks do not have permissions, and by default, - &man.chmod.1; will not follow symlinks to change the - permissions on the target file. So if you have a file, - <filename>foo</filename>, and a symlink to that file, - <filename>bar</filename>, then this command will always - succeed.</para> - - <screen>&prompt.user; <userinput>chmod g-w bar</userinput></screen> - - <para>However, the permissions on <filename>foo</filename> will - not have changed.</para> - - <para>You have to use either <option>-H</option> or - <option>-L</option> together with the <option>-R</option> - option to make this work. See the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?chmod">chmod</ulink> - and <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?symlink"> - symlink</ulink> man pages for more info.</para> - - <para> - <warning> - <para>The <option>-R</option> option does a - <acronym>RECURSIVE</acronym> - <emphasis remap=tt>chmod</emphasis>. Be careful about - specifying directories or symlinks to directories to - <emphasis remap=tt>chmod</emphasis>. If you want to - change the permissions of a directory referenced by a - symlink, use <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?chmod"> - chmod</ulink> without any options and follow the symlink - with a trailing slash (<filename>/</filename>). For - example, if <filename>foo</filename> is a symlink to - directory <filename>bar</filename>, and you want to change - the permissions of <filename>foo</filename> (actually - <filename>bar</filename>), you would do something - like:</para> - - <screen>&prompt.user; <userinput>chmod 555 foo/</userinput></screen> - - <para>With the trailing slash, <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?chmod"> - chmod</ulink> will follow the symlink, - <filename>foo</filename>, to change the permissions of the - directory, <filename>bar</filename>.</para> - </warning></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="login-8char"> - <para>Why are login names <emphasis remap=bf>still</emphasis> - restricted to 8 characters?</para> - </question> - - <answer> - - <para>You'd think it'd be easy enough to change - <literal>UT_NAMESIZE</literal> and rebuild the whole world, - and everything would just work. Unfortunately there are often - scads of applications and utilities (including system tools) - that have hard-coded small numbers (not always - <literal>8</literal> or <literal>9</literal>, but oddball ones - like <literal>15</literal> and <literal>20</literal>) in - structures and buffers. Not only will this get you log files - which are trashed (due to variable-length records getting - written when fixed records were expected), but it can break - Sun's NIS clients and potentially cause other problems in - interacting with other UNIX systems.</para> - - <para>In FreeBSD 3.0 and later, the maximum name length has - been increased to 16 characters and those various utilities - with hard-coded name sizes have been found and fixed. The fact - that this touched so many areas of the system is why, in fact, - the change was not made until 3.0.</para> - - <para>If you're absolutely confident in your ability to find - and fix these sorts of problems for yourself when and if they - pop up, you can increase the login name length in earlier - releases by editing /usr/include/utmp.h and changing - UT_NAMESIZE accordingly. You must also update MAXLOGNAME in - /usr/include/sys/param.h to match the UT_NAMESIZE change. - Finally, if you build from sources, don't forget that - /usr/include is updated each time! Change the appropriate files - in /usr/src/.. instead.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dos-binaries"> - <para>Can I run DOS binaries under FreeBSD?</para> - </question> - - <answer> - <para>Yes, starting with version 3.0 you can using BSDI's - <emphasis remap=tt>doscmd</emphasis> DOS emulation which has - been integrated and enhanced. Send mail to <ulink - URL="mailto:freebsd-emulation@FreeBSD.org">The FreeBSD - emulation discussion list</ulink> if you're interested in - joining this ongoing effort!</para> - - <para>For pre-3.0 systems, there is a neat utility called - <ulink URL="http://www.FreeBSD.org/cgi/ports.cgi?^pcemu"> - pcemu</ulink> in the ports collection which emulates an 8088 - and enough BIOS services to run DOS text mode applications. - It requires the X Window System (provided as XFree86).</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="sup-define"> - <para>What is <command>sup</command>, and how do I use - it?</para> - </question> - - <answer> - <para><ulink URL="http://www.FreeBSD.org/cgi/ports.cgi?^sup"> - SUP</ulink> stands for Software Update Protocol, and was - developed by CMU for keeping their development trees in sync. - We used it to keep remote sites in sync with our central - development sources.</para> - - <para>SUP is not bandwidth friendly, and has been retired. - The current recommended method to keep your sources up to - date is <ulink URL="../handbook/synching.html#CVSUP"> - Handbook entry on CVSup</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="very-very-cool"> - <para>How cool is FreeBSD?</para> - </question> - - <answer> - <para>Q. Has anyone done any temperature testing while - running FreeBSD? I know Linux runs cooler than dos, but have - never seen a mention of FreeBSD. It seems to run really - hot.</para> - - <para>A. No, but we have done numerous taste tests on - blindfolded volunteers who have also had 250 micrograms of - LSD-25 administered beforehand. 35% of the volunteers said that - FreeBSD tasted sort of orange, whereas Linux tasted like purple - haze. Neither group mentioned any particular variances in - temperature that I can remember. We eventually had to throw the - results of this survey out entirely anyway when we found that - too many volunteers were wandering out of the room during the - tests, thus skewing the results. I think most of the volunteers - are at Apple now, working on their new <quote>scratch and - sniff</quote> GUI. It's a funny old business we're in!</para> - - <para>Seriously, both FreeBSD and Linux use the - <acronym>HLT</acronym> (halt) instruction when the system is - idle thus lowering its energy consumption and therefore the - heat it generates. Also if you have APM (advanced power - management) configured, then FreeBSD can also put the CPU into - a low power mode.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="letmeoutofhere"> - <para>Who's scratching in my memory banks??</para> - </question> - - <answer> - <para>Q. Is there anything <quote>odd</quote> that FreeBSD - does when compiling the kernel which would cause the memory to - make a scratchy sound? When compiling (and for a brief moment - after recognizing the floppy drive upon startup, as well), a - strange scratchy sound emanates from what appears to be the - memory banks.</para> - - <para>A. Yes! You'll see frequent references to - <quote>daemons</quote> in the BSD documentation, and what most - people don't know is that this refers to genuine, non-corporeal - entities that now possess your computer. The scratchy sound - coming from your memory is actually high-pitched whispering - exchanged among the daemons as they best decide how to deal - with various system administration tasks.</para> - - <para>If the noise gets to you, a good - <command>fdisk /mbr</command> from DOS will get rid of them, - but don't be surprised if they react adversely and try to stop - you. In fact, if at any point during the exercise you hear the - satanic voice of Bill Gates coming from the built-in speaker, - take off running and don't ever look back! Freed from the - counterbalancing influence of the BSD daemons, the twin demons - of DOS and Windows are often able to re-assert total control - over your machine to the eternal damnation of your soul. Given - a choice, I think I'd prefer to get used to the scratchy - noises, myself!</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="define-MFC"> - <para>What does <acronym>MFC</acronym> mean?</para> - </question> - - <answer> - <para>MFC is an acronym for <quote>Merged From -CURRENT</quote>. - It's used in the CVS logs to denote when a change was - migrated from the CURRENT to the STABLE branches.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="define-BSD"> - <para>What does <acronym>BSD</acronym> mean?</para> - </question> - - <answer> - <para>It stands for something in a secret language that only - members can know. It doesn't translate literally but its ok - to tell you that BSD's translation is something between, - <quote>Formula-1 Racing Team</quote>, <quote>Penguins are - tasty snacks</quote>, and <quote>We have a better sense of - humor than Linux</quote>. :-)</para> - - <para>Seriously, BSD is an acronym for <quote>Berkeley - Software Distribution</quote>, which is the name the - Berkeley <acronym>CSRG</acronym> (Computer Systems Research - Group) chose for their Unix distribution way back when.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="define-repocopy"> - <para>What is a repo-copy?</para> - </question> - - <answer> - <para>A repo-copy (which is a short form of <quote>repository - copy</quote>) refers to the direct copying of files within - the CVS repository.</para> - - <para>Without a repo-copy, if a file needed to be copied or - moved to another place in the repository, the committer would - run <command>cvs add</command> to put the file in its new - location, and then <command>cvs rm</command> on the old file - if the old copy was being removed.</para> - - <para>The disadvantage of this method is that the history - (i.e. the entries in the CVS logs) of the file would not be - copied to the new location. As the FreeBSD Project considers - this history very useful, a repository copy is often used - instead. This is a process where one of the repository meisters - will copy the files directly within the repository, rather than - using the <command>cvs</command> program.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="bikeshed-painting"> - <para>Why should I care what color the bikeshed is?</para> - </question> - - <answer> - <para>The really, really short answer is that you shouldn't. - The somewhat longer answer is that just because you are - capable of building a bikeshed doesn't mean you should stop - others from building one just because you don't like the - color they plan to paint it. This is a metaphor indicating - that you need not argue about every little feature just - because you know enough to do so. Some people have - commented that the amount of noise generated by a change is - inversely proportional to the complexity of the - change.</para> - - <para>The longer and more complete answer is that after a very - long argument about whether &man.sleep.1; should take - fractional second arguments, &a.phk; posted a long - message entitled <quote><ulink - url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike - shed (any colour will do) on greener grass...</ulink></quote>. - The appropriate portions of that message are quoted - below.</para> - - <blockquote> - <attribution>&a.phk; on freebsd-hackers, October - 2, 1999</attribution> - - <para> - <quote>What is it about this bike shed?</quote> Some - of you have asked me.</para> - - <para>It's a long story, or rather it's an old story, but - it is quite short actually. C. Northcote Parkinson wrote - a book in the early 1960'ies, called <quote>Parkinson's - Law</quote>, which contains a lot of insight into the - dynamics of management.</para> - - <para>[snip a bit of commentary on the book]</para> - - <para>In the specific example involving the bike shed, the - other vital component is an atomic power-plant, I guess - that illustrates the age of the book.</para> - - <para>Parkinson shows how you can go in to the board of - directors and get approval for building a multi-million or - even billion dollar atomic power plant, but if you want to - build a bike shed you will be tangled up in endless - discussions.</para> - - <para>Parkinson explains that this is because an atomic - plant is so vast, so expensive and so complicated that - people cannot grasp it, and rather than try, they fall - back on the assumption that somebody else checked all the - details before it got this far. Richard P. Feynmann - gives a couple of interesting, and very much to the point, - examples relating to Los Alamos in his books.</para> - - <para>A bike shed on the other hand. Anyone can build one - of those over a weekend, and still have time to watch the - game on TV. So no matter how well prepared, no matter how - reasonable you are with your proposal, somebody will seize - the chance to show that he is doing his job, that he is - paying attention, that he is - <emphasis>here</emphasis>.</para> - - <para>In Denmark we call it <quote>setting your - fingerprint</quote>. It is about personal pride and - prestige, it is about being able to point somewhere and - say <quote>There! <emphasis>I</emphasis> did that.</quote> - It is a strong trait in politicians, but present in most - people given the chance. Just think about footsteps in - wet cement.</para> - </blockquote> - </answer> - </qandaentry> - - <qandaentry> - <question id="changing-lightbulbs"> - <para>How many FreeBSD hackers does it take to change a - lightbulb?</para> - </question> - - <answer> - <para>One thousand, one hundred and seventy-two:</para> - - <para>Twenty-three to complain to -CURRENT about the lights - being out;</para> - - <para>Four to claim that it is a configuration problem, and - that such matters really belong on -questions;</para> - - <para>Three to submit PRs about it, one of which is misfiled - under doc and consists only of "it's dark";</para> - - <para>One to commit an untested lightbulb which breaks - buildworld, then back it out five minutes later;</para> - - <para>Eight to flame the PR originators for not including - patches in their PRs;</para> - - <para>Five to complain about buildworld being broken;</para> - - <para>Thirty-one to answer that it works for them, and they - must have cvsupped at a bad time;</para> - - <para>One to post a patch for a new lightbulb to -hackers;</para> - - <para>One to complain that he had patches for this three years - ago, but when he sent them to -CURRENT they were just ignored, - and he has had bad experiences with the PR system; besides, - the proposed new lightbulb is non-reflexive;</para> - - <para>Thirty-seven to scream that lightbulbs do not belong in - the base system, that committers have no right to do things - like this without consulting the Community, and WHAT IS - -CORE DOING ABOUT IT!?</para> - - <para>Two hundred to complain about the color of the bicycle - shed;</para> - - <para>Three to point out that the patch breaks style(9);</para> - - <para>Seventeen to complain that the proposed new lightbulb is - under GPL;</para> - - <para>Five hundred and eighty-six to engage in a flame war - about the comparative advantages of the GPL, the BSD - license, the MIT license, the NPL, and the personal hygiene - of unnamed FSF founders;</para> - - <para>Seven to move various portions of the thread to -chat - and -advocacy;</para> - - <para>One to commit the suggested lightbulb, even though it - shines dimmer than the old one;</para> - - <para>Two to back it out with a furious flame of a commit - message, arguing that FreeBSD is better off in the dark than - with a dim lightbulb;</para> - - <para>Forty-six to argue vociferously about the backing out - of the dim lightbulb and demanding a statement from - -core;</para> - - <para>Eleven to request a smaller lightbulb so it will fit - their Tamagotchi if we ever decide to port FreeBSD to that - platform;</para> - - <para>Seventy-three to complain about the SNR on -hackers and - -chat and unsubscribe in protest;</para> - - <para>Thirteen to post "unsubscribe", "How do I unsubscribe?", - or "Please remove me from the list", followed by the usual - footer;</para> - - <para>One to commit a working lightbulb while everybody is too - busy flaming everybody else to notice;</para> - - <para>Thirty-one to point out that the new lightbulb would shine - 0.364% brighter if compiled with TenDRA (although it will have - to be reshaped into a cube), and that FreeBSD should therefore - switch to TenDRA instead of EGCS;</para> - - <para>One to complain that the new lightbulb lacks - fairings;</para> - - <para>Nine (including the PR originators) to ask - "what is MFC?";</para> - - <para>Fifty-seven to complain about the lights being out two - weeks after the bulb has been changed.</para> - - <para><emphasis>&a.nik; adds:</emphasis></para> - - <para><emphasis>I was laughing quite hard at - this.</emphasis></para> - - <para><emphasis>And then I thought, - "Hang on, shouldn't there be '1 to document it.' in that list somewhere?"</emphasis></para> - - <para><emphasis>And then I was enlightened :-)</emphasis></para> - - <para><emphasis>This entry is Copyright (c) 1999 &a.des;. - Please do not reproduce without attribution.</emphasis></para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="hackers"> - <title>For serious FreeBSD hackers only</title> - - <qandaset> - <qandaentry> - <question id="define-snap-release"> - <para>What are SNAPs and RELEASEs?</para> - </question> - - <answer> - <para>There are currently three active/semi-active branches - in the FreeBSD <ulink - URL="http://www.FreeBSD.org/cgi/cvsweb.cgi"> - CVS Repository</ulink> (the RELENG_2 branch is probably - only changed twice a year, which is why there are only three - active branches of development):</para> - - <para> - <itemizedlist> - <listitem> - <para><literal>RELENG_2_2</literal> AKA - <emphasis>2.2-STABLE</emphasis></para> - </listitem> - - <listitem> - <para><literal>RELENG_3</literal> AKA - <emphasis>3.X-STABLE</emphasis></para> - </listitem> - - <listitem> - <para><literal>RELENG_4</literal> AKA - <emphasis>4-STABLE</emphasis></para> - </listitem> - - <listitem> - <para><literal>HEAD</literal> AKA - <emphasis>-CURRENT</emphasis> AKA - <emphasis>5.0-CURRENT</emphasis></para> - </listitem> - - </itemizedlist></para> - - <para><literal>HEAD</literal> is not an actual branch tag, - like the other two; it's simply a symbolic constant for - <quote><emphasis>the current, non-branched development - stream</emphasis></quote> which we simply refer to as - <quote>-CURRENT</quote>.</para> - - <para>Right now, <quote>-CURRENT</quote> is the 5.0 development - stream and the <emphasis remap=bf>4-STABLE</emphasis> branch, - <symbol>RELENG_4</symbol>, forked off from - <quote>-CURRENT</quote> in Mar 2000.</para> - - <para>The <emphasis remap=bf>2.2-STABLE</emphasis> branch, - <symbol>RELENG_2_2</symbol>, departed -CURRENT in November - 1996, and has pretty much been retired.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="custrel"> - <para>How do I make my own custom release?</para> - </question> - - <answer> - <para>To make a release you need to do three things: First, - you need to be running a kernel with the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?vn">vn</ulink> - driver configured in. Add this to your kernel config file - and build a new kernel:</para> - - <programlisting>pseudo-device vn #Vnode driver (turns a file into a device)</programlisting> - - <para>Second, you have to have the whole CVS repository at - hand. To get this you can use <ulink - URL="../handbook/synching.html#CVSUP">CVSUP</ulink> but in - your supfile set the release name to cvs and remove any tag or - date fields:</para> - - <programlisting>*default prefix=/home/ncvs -*default base=/a -*default host=cvsup.FreeBSD.org -*default release=cvs -*default delete compress use-rel-suffix - -## Main Source Tree -src-all -src-eBones -src-secure - -# Other stuff -ports-all -www -doc-all</programlisting> - - <para>Then run <command>cvsup -g supfile</command> to suck all - the good bits onto your box...</para> - - <para>Finally, you need a chunk of empty space to build into. - Let's say it's in <filename>/some/big/filesystem</filename>, - and from the example above you've got the CVS repository in - <filename>/home/ncvs</filename>:</para> - - <screen>&prompt.root; <userinput>setenv CVSROOT /home/ncvs</userinput> # or export CVSROOT=/home/ncvs -&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildworld</userinput> -&prompt.root; <userinput>cd /usr/src/release</userinput> -&prompt.root; <userinput>make release BUILDNAME=3.0-MY-SNAP CHROOTDIR=/some/big/filesystem/release</userinput> - </screen> - - <blockquote> - <note> - <para>Please note that you <emphasis>do not</emphasis> - need to build world if you already have a populated - <filename>/usr/obj</filename>.</para> - </note> - </blockquote> - - <para>An entire release will be built in - <filename>/some/big/filesystem/release</filename> and you - will have a full FTP-type installation in - <filename>/some/big/filesystem/release/R/ftp</filename> when - you're done. If you want to build your SNAP along some other - branch than -CURRENT, you can also add - <literal>RELEASETAG=SOMETAG</literal> to the make release - command line above, e.g. <literal>RELEASETAG=RELENG_2_2</literal> - would build an up-to-the- minute 2.2-STABLE snapshot.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="custom-install-disks"> - <para>How do I create customized installation disks?</para> - </question> - - <answer> - <para>The entire process of creating installation disks and - source and binary archives is automated by various targets in - <filename>/usr/src/release/Makefile</filename>. The information - there should be enough to get you started. However, it should - be said that this involves doing a <command>make - world</command> and will therefore take up a lot of time and - disk space.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="makeworld-clobbers"> - <para><command>make world</command> clobbers my existing - installed binaries.</para> - </question> - - <answer> - <para>Yes, this is the general idea; as its name might suggest, - <command>make world</command> rebuilds every system binary from - scratch, so you can be certain of having a clean and consistent - environment at the end (which is why it takes so long).</para> - - <para>If the environment variable <literal>DESTDIR</literal> - is defined while running <command>make world</command> or - <command>make install</command>, the newly-created binaries - will be deposited in a directory tree identical to the - installed one, rooted at <literal>${DESTDIR}</literal>. - Some random combination of shared libraries modifications and - program rebuilds can cause this to fail in <command>make - world</command> however.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="bus-speed-defaulted"> - <para>When my system boots, it says <quote>(bus speed - defaulted)</quote>.</para> - </question> - - <answer> - - <para>The Adaptec 1542 SCSI host adapters allow the user to - configure their bus access speed in software. Previous versions - of the 1542 driver tried to determine the fastest usable speed - and set the adapter to that. We found that this breaks some - users' systems, so you now have to define the - <symbol>TUNE_1542</symbol> kernel configuration option in order - to have this take place. Using it on those systems where it - works may make your disks run faster, but on those systems - where it doesn't, your data could be corrupted.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="ctm"> - <para>Can I follow current with limited Internet access?</para> - </question> - - <answer> - <para>Yes, you can do this <emphasis remap=tt>without</emphasis> - downloading the whole source tree by using the <ulink - URL="../handbook/synching.html#CTM">CTM facility.</ulink></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="split-240k"> - <para>How did you split the distribution into 240k files?</para> - </question> - - <answer> - <para>Newer BSD based systems have a <option>-b</option> - option to split that allows them to split files on arbitrary - byte boundaries.</para> - - <para>Here is an example from - <filename>/usr/src/Makefile</filename>.</para> - - <programlisting>bin-tarball: -(cd ${DISTDIR}; \ -tar cf - . \ -gzip --no-name -9 -c | \ -split -b 240640 - \ -${RELEASEDIR}/tarballs/bindist/bin_tgz.)</programlisting> - - </answer> - </qandaentry> - - <qandaentry> - <question id="submitting-kernel-extensions"> - <para>I've written a kernel extension, who do I send it - to?</para> - </question> - - <answer> - <para>Please take a look at <ulink - URL="../handbook/contrib.html">The Handbook entry on how to - submit code.</ulink></para> - - <para>And thanks for the thought!</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="pnp-initialize"> - <para>How are Plug N Play ISA cards detected and - initialized?</para> - </question> - - <answer> - <para>By: <ulink URL="mailto:uhclem@nemesis.lonestar.org"> - Frank Durda IV</ulink></para> - - <para>In a nutshell, there a few I/O ports that all of the - PnP boards respond to when the host asks if anyone is out - there. So when the PnP probe routine starts, he asks if there - are any PnP boards present, and all the PnP boards respond with - their model # to a I/O read of the same port, so the probe - routine gets a wired-OR <quote>yes</quote> to that question. At - least one bit will be on in that reply. Then the probe code is - able to cause boards with board model IDs (assigned by - Microsoft/Intel) lower than X to go <quote>off-line</quote>. It - then looks to see if any boards are still responding to the - query. If the answer was <literal>0</literal>, then there are - no boards with IDs above X. Now probe asks if there are any - boards below <literal>X</literal>. If so, probe knows there are - boards with a model numbers below X. Probe then asks for boards - greater than X-(limit/4) to go off-line. If repeats the query. - By repeating this semi-binary search of IDs-in-range enough - times, the probing code will eventually identify all PnP boards - present in a given machine with a number of iterations that is - much lower than what 2^64 would take.</para> - - <para>The IDs are two 32-bit fields (hence 2ˆ64) + 8 bit - checksum. The first 32 bits are a vendor identifier. They never - come out and say it, but it appears to be assumed that - different types of boards from the same vendor could have - different 32-bit vendor ids. The idea of needing 32 bits just - for unique manufacturers is a bit excessive.</para> - - <para>The lower 32 bits are a serial #, ethernet address, - something that makes this one board unique. The vendor must - never produce a second board that has the same lower 32 bits - unless the upper 32 bits are also different. So you can have - multiple boards of the same type in the machine and the full 64 - bits will still be unique.</para> - - <para>The 32 bit groups can never be all zero. This allows the - wired-OR to show non-zero bits during the initial binary - search.</para> - - <para>Once the system has identified all the board IDs present, - it will reactivate each board, one at a time (via the same I/O - ports), and find out what resources the given board needs, what - interrupt choices are available, etc. A scan is made over all - the boards to collect this information.</para> - - <para>This info is then combined with info from any ECU files - on the hard disk or wired into the MLB BIOS. The ECU and BIOS - PnP support for hardware on the MLB is usually synthetic, and - the peripherals don't really do genuine PnP. However by - examining the BIOS info plus the ECU info, the probe routines - can cause the devices that are PnP to avoid those devices the - probe code cannot relocate.</para> - - <para>Then the PnP devices are visited once more and given - their I/O, DMA, IRQ and Memory-map address assignments. The - devices will then appear at those locations and remain there - until the next reboot, although there is nothing that says you - can't move them around whenever you want.</para> - - <para>There is a lot of oversimplification above, but you - should get the general idea.</para> - - <para>Microsoft took over some of the primary printer status - ports to do PnP, on the logic that no boards decoded those - addresses for the opposing I/O cycles. I found a genuine IBM - printer board that did decode writes of the status port during - the early PnP proposal review period, but MS said - <quote>tough</quote>. So they do a write to the printer status - port for setting addresses, plus that use that address + - <literal>0x800</literal>, and a third I/O port for reading that - can be located anywhere between <literal>0x200</literal> and - <literal>0x3ff</literal>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="architectures"> - <para>Does FreeBSD support architectures other than the - x86?</para> - </question> - - <answer> - - <para>Several groups of people have expressed interest in - working on multi-architecture ports for FreeBSD and the - FreeBSD/AXP (ALPHA) port is one such effort which has been - quite successful, now available at - <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/alpha/"> - ftp://ftp.FreeBSD.org/pub/FreeBSD/alpha</ulink>. The ALPHA port - currently runs on a growing number of ALPHA machine types, - among them the AlphaStation, AXPpci, PC164, Miata and Multia - models. For status information, please join the - <email>freebsd-alpha@FreeBSD.org</email> <link - linkend="mailing">mailing list</link>.</para> - - <para>Interest has also been expressed in a port of FreeBSD to - the SPARC architecture, join the - <email>freebsd-sparc@FreeBSD.org</email> <link linkend="mailing"> - mailing list</link> if you are interested in joining that - project. Most recent additions to the list of upcoming plaforms - are IA-64 and PowerPC, join the - <email>freebsd-ia64@FreeBSD.org</email> or/and - <email>freebsd-ppc@FreeBSD.org</email> <link - linkend="mailing">mailing lists</link> for more information. - For general discussion on new architectures, join - the <email>freebsd-platforms@FreeBSD.org</email> - <link linkend="mailing">mailing list</link>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="major-numbers"> - <para>I need a major number for a device driver I've - written.</para> - </question> - - <answer> - - <para>This depends on whether or not you plan on making the - driver publicly available. If you do, then please send us a - copy of the driver source code, plus the appropriate - modifications to <emphasis remap=tt>files.i386</emphasis>, a - sample configuration file entry, and the appropriate <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?MAKEDEV">MAKEDEV</ulink> - code to create any special files your device uses. If you do - not, or are unable to because of licensing restrictions, then - character major number 32 and block major number 8 have been - reserved specifically for this purpose; please use them. In any - case, we'd appreciate hearing about your driver on - <email>freebsd-hackers@FreeBSD.org</email>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="alternate-directory-layout"> - <para>Alternative layout policies for directories</para> - </question> - - <answer> - <para>In answer to the question of alternative layout policies - for directories, the scheme that is currently in use is - unchanged from what I wrote in 1983. I wrote that policy for - the original fast filesystem, and never revisited it. It works - well at keeping cylinder groups from filling up. As several of - you have noted, it works poorly for find. Most filesystems are - created from archives that were created by a depth first search - (aka ftw). These directories end up being striped across the - cylinder groups thus creating a worst possible senario for - future depth first searches. If one knew the total number of - directories to be created, the solution would be to create - (total / fs_ncg) per cylinder group before moving on. - Obviously, one would have to create some heuristic to guess at - this number. Even using a small fixed number like say 10 would - make an order of magnitude improvement. To differentiate - restores from normal operation (when the current algorithm is - probably more sensible), you could use the clustering of up to - 10 if they were all done within a ten second window. Anyway, my - conclusion is that this is an area ripe for - experimentation.</para> - - <para>Kirk McKusick, September 1998</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="kernel-panic-troubleshooting"> - <para>Making the most of a kernel panic</para> - </question> - - <answer> - <para><emphasis>[This section was extracted from a mail - written by &a.wpaul; on the freebsd-current - <link linkend="mailing">mailing list</link> by &a.des;, who - fixed a few typos and added the bracketed comments] - </emphasis></para> - - <programlisting>From: Bill Paul <wpaul@skynet.ctr.columbia.edu> -Subject: Re: the fs fun never stops -To: ben@rosengart.com -Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT) -Cc: current@FreeBSD.org</programlisting> - - <para><emphasis>[<ben@rosengart.com> posted the following - panic message]</emphasis> - - <programlisting>> Fatal trap 12: page fault while in kernel mode -> fault virtual address = 0x40 -> fault code = supervisor read, page not present -> instruction pointer = 0x8:0xf014a7e5 - ^^^^^^^^^^ -> stack pointer = 0x10:0xf4ed6f24 -> frame pointer = 0x10:0xf4ed6f28 -> code segment = base 0x0, limit 0xfffff, type 0x1b -> = DPL 0, pres 1, def32 1, gran 1 -> processor eflags = interrupt enabled, resume, IOPL = 0 -> current process = 80 (mount) -> interrupt mask = -> trap number = 12 -> panic: page fault</programlisting> - - [When] you see a message like this, it's not enough to just - reproduce it and send it in. The instruction pointer value that - I highlighted up there is important; unfortunately, it's also - configuration dependent. In other words, the value varies - depending on the exact kernel image that you're using. If - you're using a GENERIC kernel image from one of the snapshots, - then it's possible for somebody else to track down the - offending function, but if you're running a custom kernel then - only <emphasis>you</emphasis> can tell us where the fault - occured.</para> - - <para> What you should do is this:</para> - - <para> - <itemizedlist> - <listitem> - <para>Write down the instruction pointer value. Note that - the <literal>0x8:</literal> part at the begining is not - significant in this case: it's the - <literal>0xf0xxxxxx</literal> part that we want.</para> - </listitem> - - <listitem> - <para>When the system reboots, do the following: - - <screen>&prompt.user; <userinput>nm -n /kernel.that.caused.the.panic | grep f0xxxxxx</userinput></screen> - - where <literal>f0xxxxxx</literal> is the instruction - pointer value. The odds are you will not get an exact - match since the symbols in the kernel symbol table are - for the entry points of functions and the instruction - pointer address will be somewhere inside a function, not - at the start. If you don't get an exact match, omit the - last digit from the instruction pointer value and try - again, i.e.: - - <screen>&prompt.user; <userinput>nm -n /kernel.that.caused.the.panic | grep f0xxxxx</userinput></screen> - - If that doesn't yield any results, chop off another - digit. Repeat until you get some sort of output. The - result will be a possible list of functions which caused - the panic. This is a less than exact mechanism for - tracking down the point of failure, but it's better than - nothing.</para> - </listitem> - </itemizedlist></para> - - <para> I see people constantly show panic messages like this - but rarely do I see someone take the time to match up the - instruction pointer with a function in the kernel symbol - table.</para> - - <para> The best way to track down the cause of a panic is by - capturing a crash dump, then using <command>gdb(1)</command> - to to a stack trace on the crash dump. Of course, this depends - on <command>gdb(1)</command> in -CURRENT working correctly, - which I can't guarantee (I recall somebody saying that the new - ELF-ized <command>gdb(1)</command> didn't handle kernel crash - dumps correctly: somebody should check this before 3.0 goes out - of beta or there'll be a lot of red faces after the CDs - ship).</para> - - <para>In any case, the method I normally use is this:</para> - - <para> - <itemizedlist> - <listitem> - <para>Set up a kernel config file, optionally adding - <literal>options DDB</literal> if you think you need - the kernel debugger for something. (I use this mainly - for setting beakpoints if I suspect an infinite loop - condition of some kind.)</para> - </listitem> - - <listitem> - <para>Use <command>config -g - <replaceable>KERNELCONFIG</replaceable></command> to set - up the build directory.</para> - </listitem> - - <listitem> - <para><command>cd /sys/compile/ - <replaceable>KERNELCONFIG</replaceable>; make - </command></para> - </listitem> - - <listitem> - <para>Wait for kernel to finish compiling.</para> - </listitem> - - <listitem> - <para><command>make install</command></para> - </listitem> - - <listitem> - <para>reboot</para> - </listitem> - </itemizedlist> - </para> - - <para>The &man.make.1; process will have built two kernels. - <filename>kernel</filename> and - <filename>kernel.debug</filename>. <filename>kernel</filename> - was installed as <filename>/kernel</filename>, while - <filename>kernel.debug</filename> can be used as the source of - debugging symbols for gdb(1).</para> - - <para> To make sure you capture a crash dump, you need edit - <filename>/etc/rc.conf</filename> and set - <emphasis remap=tt>dumpdev</emphasis> to point to your swap - partition. This will cause the <command>rc(8)</command> scripts - to use the <command>dumpon(8)</command> command to enable crash - dumps. You can also run <command>dumpon(8)</command> manually. - After a panic, the crash dump can be recovered using - <command>savecore(8)</command>; if <emphasis - remap=tt>dumpdev</emphasis> is set in - <filename>/etc/rc.conf</filename>, the <command>rc(8)</command> - scripts will run <command>savecore(8)</command> automatically - and put the crash dump in - <filename>/var/crash</filename>.</para> - - <para> - <note> - <para>FreeBSD crash dumps are usually the same size as the - physical RAM size of your machine. That is, if you have - 64MB of RAM, you will get a 64MB crash dump. Therefore you - must make sure there's enough space in - <filename>/var/crash</filename> to hold the dump. - Alternatively, you run <command>savecore(8)</command> - manually and have it recover the crash dump to another - directory where you have more room. It's possible to limit - the size of the crash dump by using <literal>options - MAXMEM=(foo)</literal> to set the amount of memory the - kernel will use to something a little more sensible. For - example, if you have 128MB of RAM, you can limit the - kernel's memory usage to 16MB so that your crash dump size - will be 16MB instead of 128MB.</para> - </note></para> - - <para> Once you have recovered the crash dump, you can get a - stack trace with <command>gdb(1)</command> as follows:</para> - - <screen>&prompt.user; <userinput>gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0</userinput> -<prompt>(gdb)</prompt> <userinput>where</userinput></screen> - - <para> Note that there may be several screens worth of - information; ideally you should use - <command>script(1)</command> to capture all of them. Using the - unstripped kernel image with all the debug symbols should show - the exact line of kernel source code where the panic occured. - Usually you have to read the stack trace from the bottom up in - order to trace the exact sequence of events that lead to the - crash. You can also use <command>gdb(1)</command> to print out - the contents of various variables or structures in order to - examine the system state at the time of the crash.</para> - - <para> Now, if you're really insane and have a second computer, - you can also configure <command>gdb(1)</command> to do remote - debugging such that you can use <command>gdb(1)</command> on - one system to debug the kernel on another system, including - setting breakpoints, single-stepping through the kernel code, - just like you can do with a normal user-mode program. I haven't - played with this yet as I don't often have the chance to set up - two machines side by side for debugging purposes.</para> - - <para> <emphasis>[Bill adds: "I forgot to mention one thing: if - you have DDB enabled and the kernel drops into the debugger, - you can force a panic (and a crash dump) just by typing 'panic' - at the ddb prompt. It may stop in the debugger again during the - panic phase. If it does, type 'continue' and it will finish the - crash dump." -ed]</emphasis></para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="dlsym-failure"> - <para>dlsym() stopped working for ELF executables!</para> - </question> - - <answer> - <para>The ELF toolchain does not, by default, make the symbols - defined in an executable visible to the dynamic linker. - Consequently <function>dlsym()</function> searches on handles - obtained from calls to <emphasis remap=tt>dlopen(NULL, - flags)</emphasis> will fail to find such symbols.</para> - - <para>If you want to search, using <function>dlsym()</function>, - for symbols present in the main executable of a process, you - need to link the executable using the - <option>-export-dynamic</option> option to the <ulink - URL="http://www.FreeBSD.org/cgi/man.cgi?ld">ELF - linker</ulink>.</para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="change-kernel-address-space"> - <para>Increasing or reducing the kernel address space</para> - </question> - - <answer> - <para>By default, the kernel address space is 256 MB on - FreeBSD 3.x and 1 GB on FreeBSD 4.x. If you run a - network-intensive server (e.g. a large FTP or HTTP server), - you might find that 256 MB is not enough.</para> - - <para>So how do you increase the address space? There are two - aspects to this. First, you need to tell the kernel to reserve - a larger portion of the address space for itself. Second, since - the kernel is loaded at the top of the address space, you need - to lower the load address so it doesn't bump its head against - the ceiling.</para> - - <para>The first goal is achieved by increasing the value of - <literal>NKPDE</literal> in - <filename>src/sys/i386/include/pmap.h</filename>. Here's what - it looks like for a 1 GB address space:</para> - - <programlisting>#ifndef NKPDE -#ifdef SMP -#define NKPDE 254 /* addressable number of page tables/pde's */ -#else -#define NKPDE 255 /* addressable number of page tables/pde's */ -#endif /* SMP */ -#endif</programlisting> - - <para>To find the correct value of <literal>NKPDE</literal>, - divide the desired address space size (in megabytes) by four, - then subtract one for UP and two for SMP.</para> - - <para>To achieve the second goal, you need to compute the - correct load address: simply subtract the address space size - (in bytes) from 0x100100000; the result is 0xc0100000 for a 1 - GB address space. Set <symbol>LOAD_ADDRESS</symbol> in - <filename>src/sys/i386/conf/Makefile.i386</filename> to that - value; then set the location counter in the beginning of the - section listing in - <filename>src/sys/i386/conf/kernel.script</filename> to the - same value, as follows:</para> - - <programlisting>OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") -OUTPUT_ARCH(i386) -ENTRY(btext) -SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib); -SECTIONS -{ - /* Read-only sections, merged into text segment: */ - . = 0xc0100000 + SIZEOF_HEADERS; - .interp : { *(.interp) }</programlisting> - - <para>Then reconfig and rebuild your kernel. You will probably - have problems with <command>ps(1)</command>, - <command>top(1)</command> and the like; <emphasis remap=tt>make - world</emphasis> should take care of it (or a manual rebuild of - <emphasis remap=tt>libkvm</emphasis>, <emphasis - remap=tt>ps</emphasis> and <emphasis remap=tt>top</emphasis> - after copying the patched <filename>pmap.h</filename> to - <filename>/usr/include/vm/</filename>.</para> - - <para>NOTE: the size of the kernel address space must be a - multiple of four megabytes.</para> - - <para>[&a.dg; adds: <emphasis> I think the kernel address space - needs to be a power of two, but I'm not certain about that. The - old(er) boot code used to monkey with the high order address bits - and I think expected at least 256MB - granularity.]</emphasis></para> - - </answer> - </qandaentry> - </qandaset> - </chapter> - - <chapter id="acknowledgments"> - <title>ACKNOWLEDGMENTS</title> - - <blockquote> - <attribution>FreeBSD Core Team</attribution> - - <para>If you see a problem with this FAQ, or wish to submit an - entry, please mail the &a.faq;. We appreciate your feedback, - and cannot make this a better FAQ without your help!</para> - </blockquote> - - <para> - <variablelist> - <varlistentry> - <term>&a.jkh;</term> - <listitem> - <para>Occasional fits of FAQ-reshuffling and updating.</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dwhite;</term> - - <listitem> - <para>Services above and beyond the call of duty on - freebsd-questions</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.joerg;</term> - - <listitem> - <para>Services above and beyond the call of duty on - Usenet</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.wollman;</term> - - <listitem> - <para>Networking and formatting</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>Jim Lowe</term> - - <listitem> - <para>Multicast information</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.pds;</term> - - <listitem> - <para>FreeBSD FAQ typing machine slavey</para> - - <para></para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>The FreeBSD Team</term> - - <listitem> - <para>Kvetching, moaning, submitting data</para> - - </listitem> - </varlistentry> - </variablelist></para> - - <para>And to any others we've forgotten, apologies and heartfelt - thanks!</para> - - </chapter> -</book> diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile deleted file mode 100644 index 2414786eb2..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ /dev/null @@ -1,50 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/Makefile,v 1.8 2000/06/23 00:37:53 nik Exp $ -# -# Build the FreeBSD Documentation Project Primer. -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml -SRCS+= overview/chapter.sgml -SRCS+= psgml-mode/chapter.sgml -SRCS+= see-also/chapter.sgml -SRCS+= sgml-markup/chapter.sgml -SRCS+= sgml-primer/chapter.sgml -SRCS+= stylesheets/chapter.sgml -SRCS+= structure/chapter.sgml -SRCS+= doc-build/chapter.sgml -SRCS+= the-website/chapter.sgml -SRCS+= tools/chapter.sgml -SRCS+= translations/chapter.sgml -SRCS+= writing-style/chapter.sgml - -SRCS+= examples/appendix.sgml - -# Images from the cross-document image library -LIB_IMAGES= callouts/1.png -LIB_IMAGES+= callouts/2.png -LIB_IMAGES+= callouts/3.png -LIB_IMAGES+= callouts/4.png -LIB_IMAGES+= callouts/5.png - -# Entities -SRCS+= chapters.ent - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml deleted file mode 100644 index 7f3410bc16..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/book.sgml +++ /dev/null @@ -1,295 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.11 2000/06/23 00:37:53 nik Exp $ ---> - -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!ENTITY % not.published "INCLUDE"> -]> - -<book> - <bookinfo> - <title>FreeBSD Documentation Project Primer for New Contributors</title> - - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - <affiliation> - <address><email>nik@FreeBSD.org</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <holder role="mailto:nik@FreeBSD.org">Nik Clayton</holder> - </copyright> - - <pubdate role="rcs">$FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.11 2000/06/23 00:37:53 nik Exp $</pubdate> - - <releaseinfo>$FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.11 2000/06/23 00:37:53 nik Exp $</releaseinfo> - - <legalnotice> - <para>Redistribution and use in source (SGML DocBook) and 'compiled' - forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions are - met:</para> - - <orderedlist> - <listitem> - <para>Redistributions of source code (SGML DocBook) must retain the - above copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified.</para> - </listitem> - - <listitem> - <para>Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must - reproduce the above copyright notice, this list of conditions and - the following disclaimer in the documentation and/or other - materials provided with the distribution.</para> - </listitem> - </orderedlist> - - <important> - <para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR - ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH - DAMAGE.</para> - </important> - </legalnotice> - - <abstract> - <para>Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable.</para> - - <para>This primer covers everything you will need to know in order - to start contributing to the FreeBSD Documentation Project, from - the tools and software you will be using (both mandatory and - recommended) to the philosophy behind the Documentation - Project.</para> - - <para>This document is a work in progress, and is not complete. Sections - that are known to be incomplete are indicated with a - <literal>*</literal> in their name.</para> - </abstract> - </bookinfo> - - <preface> - <title>Preface</title> - - <sect1> - <title>Shell Prompts</title> - - <para>The following table shows the default system prompt and superuser - prompt. The examples will use this prompt to indicate which user you - should be running the example as.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>User</entry> - <entry>Prompt</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Normal user</entry> - <entry>&prompt.user;</entry> - </row> - - <row> - <entry><username>root</username></entry> - <entry>&prompt.root;</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Typographic Conventions</title> - - <para>The following table describes the typographic conventions used in - this book.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Meaning</entry> - <entry>Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>The name of commands, files, and directories. On screen - computer output.</entry> - <entry><para>Edit your <filename>.login</filename> - file.</para><para>Use <command>ls -a</command> to list all - files.</para><para><screen>You have mail.</screen> - </para></entry> - </row> - - <row> - <entry>What you type, when contrasted with on-screen computer - output.</entry> - - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> - </row> - - <row> - <entry>Manual page references.</entry> - - <entry>Use <citerefentry> - <refentrytitle>su</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> to change user names.</entry> - </row> - - <row> - <entry>User and group names</entry> - - <entry>Only <username>root</username> can do this.</entry> - </row> - - <row> - <entry>Emphasis</entry> - - <entry>You <emphasis>must</emphasis> do this.</entry> - </row> - - <row> - <entry>Command line variables; replace with the real name or - variable.</entry> - - <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> - </row> - - <row> - <entry>Environment variables</entry> - - <entry><envar>$HOME</envar> is your home directory.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Notes, tips, important information, warnings, and examples</title> - - <para>Within the text appear notes, warnings, and examples.</para> - - <note> - <para>Notes are represented like this, and contain information that - you should take note of, as it may affect what you do.</para> - </note> - - <tip> - <para>Tips are represented like this, and contain information that you - might find useful, or lead to an easier way to do something.</para> - </tip> - - <important> - <para>Important information is represented like this. Typically they - flag extra steps you may need to carry out.</para> - </important> - - <warning> - <para>Warnings are represented like this, and contain information - warning you about possible damage if you do not follow the - instructions. This damage may be physical, to your hardware or to - you, or it may be non-physical, such as the inadvertant deletion of - important files.</para> - </warning> - - <example> - <title>A sample example</title> - - <para>Examples are represented like this, and typically contain - examples you should walk through, or show you what the results of a - particular action should be.</para> - </example> - </sect1> - - <sect1> - <title>Acknowledgments</title> - - <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter - Flynn, and Christopher Maden, who took the time to read early drafts - of this document and offer many valuable comments and - criticisms.</para> - </sect1> - </preface> - - &chap.overview; - &chap.tools; - &chap.sgml-primer; - &chap.sgml-markup; - &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; - - &app.examples; - -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/chapter.decl b/en_US.ISO8859-1/books/fdp-primer/chapter.decl deleted file mode 100644 index ce0a7ed16a..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/chapter.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent deleted file mode 100644 index 651a2bd465..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ /dev/null @@ -1,25 +0,0 @@ -<!-- - Creates entities for each chapter in the Documentation Project Primer. - Each entity is named chap.foo, where foo is the value of the id - attribute on that chapter, and corresponds to the name of the - directory in which that chapter's .sgml file is stored. - - Chapters should be listed in the order in which they are referenced. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/chapters.ent,v 1.5 2000/06/23 00:37:53 nik Exp $ ---> - -<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> -<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> -<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> -<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> -<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> -<!ENTITY chap.structure SYSTEM "structure/chapter.sgml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> -<!ENTITY chap.translations SYSTEM "translations/chapter.sgml"> -<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> -<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> -<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> -<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.sgml"> - -<!ENTITY app.examples SYSTEM "examples/appendix.sgml"> diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml deleted file mode 100644 index 910bf3cf22..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml +++ /dev/null @@ -1,501 +0,0 @@ -<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.1 2000-06-23 00:37:15 nik Exp $ ---> - -<chapter id="doc-build"> - <title>The Documentation Build Process</title> - - <para>This chapter's main purpose is to clearly explain <emphasis>how - the documentation build process is organised</emphasis>, and - <emphasis>how to affect modifications to this process</emphasis>. - </para> - - <para>After you have finished reading this chapter you should:</para> - - <itemizedlist> - <listitem> - <para>Know what you need to build the FDP documentation, in - addition to those mentioned in the <link - linkend="tools">SGML tools chapter</link>.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the - <application>make</application> instructions that are present in - each document's <filename>Makefile</filename>s, as well as an - overview of the <filename>doc.project.mk</filename> includes.</para> - </listitem> - - <listitem> - <para>Be able to customize the build process by using - <application>make</application> variables and - <application>make</application> targets.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>The FreeBSD Documentation Build Toolset</title> - - <para>Here are your tools. Use them every way you can.</para> - - <itemizedlist> - <listitem> - <para>The primary build tool you will need is - <application>make</application>, but specifically - <application>Berkeley Make</application>.</para> - </listitem> - - <listitem> - <para>Package building is handled by FreeBSD's - <application>pkg_create</application>. If you are not using - FreeBSD, you will either have to live without packages, or - compile the source yourself.</para> - </listitem> - - <listitem> - <para><application>gzip</application> is needed to create - compressed versions of the document. - <application>bzip2</application> compression and - <application>zip</application> archives are also supported. - <application>tar</application> is supported, but package - building demands it.</para> - </listitem> - - <listitem> - <para><application>install</application> is the default method - to install the documentation. There are alternatives, - however.</para - </listitem> - </itemizedlist> - - <note> - <para>It is unlikely you will not be able to find these last two, they - are mentioned for completeness.</para> - </note> - </sect1> - - <sect1> - <title>Understanding Makefiles in the Documentation tree</title> - - <para>There are three main types of <filename>Makefile</filename>s - in the FreeBSD Documentation Project tree.</para> - - <itemizedlist> - <listitem> - <para><link linkend="sub-make">Subdirectory - <filename>Makefile</filename>s</link> simply pass - commands to those directories below them.</para> - </listitem> - - <listitem> - <para><link linkend="doc-make">Documentation - <filename>Makefile</filename>s</link> describe the - document(s) that should be produced from this directory.</para> - </listitem> - - <listitem> - <para><link linkend="make-includes"><application>Make</application> - includes</link> are the glue that perform the document production, - and are usually of the form - <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> - </listitem> - </itemizedlist> - - <para><application>Make</application> syntax is quickly revised as - the we explore these types.</para> - - <sect2 id="sub-make"> - <title>Subdirectory Makefiles</title> - - <para>These directories usually take the form of:</para> - - <programlisting>SUBDIR =articles -SUBDIR+=books - -COMPAT_SYMLINK = en - -DOC_PREFIX?= ${.CURDIR}/.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> - - <para>In quick summary, the first four non-empty lines define the - <application>make</application> variables, - <makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>, - and <makevar>DOC_PREFIX</makevar>.</para> - - <para>The first <makevar>SUBDIR</makevar> statement, as well as - the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to - assign a value to a variable, overriding any previous - value.</para> - - <para>The second <makevar>SUBDIR</makevar> statement shows how a - value is appended to the current value of a variable. The - <makevar>SUBDIR</makevar> variable is now <literal>articles - books</literal>.</para> - - <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a - value is assigned to the variable, but only if it is not already - defined. This is useful if <makevar>DOC_PREFIX</makevar> is not - where this <filename>Makefile</filename> thinks it is - the user - can override this and provide the correct value.</para> - - <para>Now what does it all mean? <makevar>SUBDIR</makevar> - mentions which subdirectories below this one the build process - should pass any work on to.</para> - - <para><makevar>COMPAT_SYMLINK</makevar> is specific to - compatibility symlinks (amazingly enough) for languages to their - official encoding (<filename>doc/en</filename> would point to - <filename>en_US.ISO-8859-1</filename>).</para> - - <para><makevar>DOC_PREFIX</makevar> is the path to the root of the - FreeBSD Document Project tree. This is not always that easy to - find, and is also easily overridable, to allow for flexibility. - <makevar>.CURDIR</makevar> is a <application>make</application> - builtin variable with the path to the current directory.</para> - - <para>The final line includes the FreeBSD Documentation Project's - project-wide <application>make</application> system file - <filename>doc.project.mk</filename> which is the glue which - converts these variables into build instructions.</para> - - </sect2> - <sect2 id="doc-make"> - <title>Documentation Makefiles</title> - - <para>These <filename>Makefile</filename>s set a bunch of - <application>make</application> variables that describe how to - build the documentation contained in that directory.</para> - - <para>Here is an example:</para> - - <programlisting>MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# SGML content -SRCS= book.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - - <para>The <makevar>MAINTAINER</makevar> variable is a very - important one. This variable provides the ability to claim - ownership over a document in the FreeBSD Documentation - Project, whereby you gain the responsibility for maintaining - it.</para> - - <para><makevar>DOC</makevar> is the name (sans the - <filename>.sgml</filename> extension) of the main document - created by this directory. <makevar>SRCS</makevar> lists all - the individual files that make up the document. This should - also include important files in which a change should result - in a rebuild.</para> - - <para><makevar>FORMATS</makevar> indicates the default formats - that should be built for this document. - <makevar>INSTALL_COMPRESSED</makevar> is the default list of - compression techniques that should be used in the document - build. <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by - default, should be non-empty if only compressed documents are - desired in the build.</para> - - <note> - <para>We covered optional variable assignments in the - <link linkend="sub-make">previous section</link>.</para> - </note> - - <para>The <makevar>DOC_PREFIX</makevar> and include statements - should be familiar already.</para> - </sect2> - </sect1> - - <sect1 id="make-includes"> - <title>FreeBSD Documentation Project make includes</title> - - <para>This is best explained by inspection of the code. Here are - the system include files:</para> - - <itemizedlist> - <listitem> - <para><filename>doc.project.mk</filename> is the main project - include file, which includes all the following include files, as - necessary.</para> - </listitem> - - <listitem> - <para><filename>doc.subdir.mk</filename> handles traversing of - the document tree during the build and install processes.</para> - </listitem> - - <listitem> - <para><filename>doc.install.mk</filename> provides variables - that affect ownership and installation of documents.</para> - </listitem> - - <listitem> - <para><filename>doc.docbook.mk</filename> is included if - <makevar>DOCFORMAT</makevar> is <literal>docbook</literal> - and <makevar>DOC</makevar> is set.</para> - </listitem> - </itemizedlist> - - <sect2> - <title>doc.project.mk</title> - - <para>By inspection:</para> - - <programlisting>DOCFORMAT?= docbook -MAINTAINER?= doc@FreeBSD.org - -PREFIX?= /usr/local -PRI_LANG?= en_US.ISO_8859-1 - -.if defined(DOC) -.if ${DOCFORMAT} == "docbook" -.include "doc.docbook.mk" -.endif -.endif - -.include "doc.subdir.mk" -.include "doc.install.mk"</programlisting> - - <sect3> - - <title>Variables</title> - - <para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar> - are assigned default values, if these are not set by the - document make file.</para> - - <para><makevar>PREFIX</makevar> is the prefix under which the - <link linkend="tools">documentation building tools</link> are - installed. For normal package and port installation, this is - <filename>/usr/local</filename>.</para> - - <para><makevar>PRI_LANG</makevar> should be set to whatever - language and encoding is natural amongst users these documents are - being built for. US English is the default.</para> - - <note> - <para><makevar>PRI_LANG</makevar> in no way affects what documents - can, or even will, be built. It's main use is creating links to - commonly referenced documents into the FreeBSD documentation - install root.</para> - </note> - </sect3> - - <sect3> - <title>Conditionals</title> - - <para>The <literal>.if defined(DOC)</literal> line is an example of - a <application>make</application> conditional which, like in - other programs, defines behaviour if some condition is true or - if it is false. <literal>defined</literal> is a function which - returns whether the variable given is defined or not.</para> - - <para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next, - tests whether the <makevar>DOCFORMAT</makevar> variable is - <literal>"docbook"</literal>, and in this case, includes - <filename>doc.docbook.mk</filename>.</para> - - <para>The two <literal>.endif</literal>s close the two above - conditionals, marking the end of their application.</para> - </sect3> - </sect2> - - <sect2> - <title>doc.subdir.mk</title> - - <para>This is too long to explain by inspection, you should be - able to work it out with the knowledge gained from the previous - chapters, and a little help given here.</para> - - <sect3> - <title>Variables</title> - - <itemizedlist> - <listitem> - <para><makevar>SUBDIR</makevar> is a list of subdirectories - that the build process should go further down - into.</para> - </listitem> - - <listitem> - <para><makevar>ROOT_SYMLINKS</makevar> is the name of - directories that should be linked to the document - install root from their actual locations, if the current - language is the primary language (specified by - <makevar>PRI_LANG</makevar>).</para> - </listitem> - - <listitem> - <para><makevar>COMPAT_SYMLINK</makevar> is described in the - <link linkend="sub-make">Subdirectory Makefile</link> - section.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Targets and macros</title> - - <para>Dependencies are described by - <literal><replaceable>target</replaceable>: - <replaceable>dependency1 dependency2 ...</replaceable></literal> - tuples, where to build <literal>target</literal>, you need to build - the given dependencies first.</para> - - <para>After that descriptive tuple, instructions on how to build - the target may be given, if the conversion process between the - target and it's dependencies are not previously defined, or if - this particular conversion is not the same as the default - conversion method.</para> - - <para>A special dependency <literal>.USE</literal> defines - the equivalent of a macro.</para> - -<programlisting>_SUBDIRUSE: .USE -.for entry in ${SUBDIR} - @${ECHO} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) -.endfor</programlisting> - - <para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now a - macro which will execute the given commands when it is listed - as a dependency.</para> - - <para>What sets this macro apart from other targets? Basically, - it is executed <emphasis>after</emphasis> the instructions - given in the build procedure it is listed as a dependency to, - and it doesn't adjust <makevar>.TARGET</makevar>, which is the - variable which contains the name of the target currently - being built.</para> - -<programlisting>clean: _SUBDIRUSE - rm -f ${CLEANFILES}</programlisting> - - <para>In the above, <maketarget>clean</maketarget> will use the - <maketarget>_SUBDIRUSE</maketarget> macro after it has - executed the instruction - <command>rm -f ${CLEANFILES}</command>. In effect, this causes - <maketarget>clean</maketarget> to go further and further down - the directory tree, deleting built files as it goes - <emphasis>down</emphasis>, not on the way back up.</para> - - <sect4> - <title>Provided targets</title> - - <itemizedlist> - <listitem> - <para><maketarget>install</maketarget> and - <maketarget>package</maketarget> both go down the - directory tree calling the real versions of themselves - in the subdirectories. - (<maketarget>realinstall</maketarget> and - <maketarget>realpackage</maketarget> - respectively)</para> - </listitem> - - <listitem> - <para><maketarget>clean</maketarget> removes files created - by the build process (and goes down the directory tree - too). <maketarget>cleandir</maketarget> does the same, - and also removes the object directory, if any.</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - <sect3> - <title>More on conditionals</title> - - <itemizedlist> - <listitem> - <para><literal>exists</literal> is another condition - function which returns true if the given file exists.</para> - </listitem> - - <listitem> - <para><literal>empty</literal> returns true if the given - variable is empty.</para> - </listitem> - - <listitem> - <para><literal>target</literal> returns true if the given - target does not already exist.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Looping constructs in make (.for)</title> - - <para><literal>.for</literal> provides a way to repeat a set of - instructions for each space-seperated element in a variable. - It does this by assigning a variable to contain the current - element in the list being examined.</para> - -<programlisting>_SUBDIRUSE: .USE -.for entry in ${SUBDIR} - @${ECHO} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) -.endfor</programlisting> - - <para>In the above, if <makevar>SUBDIR</makevar> is empty, no - action is taken; if it has one or more elements, the - instructions between <literal>.for</literal> and - <literal>.endfor</literal> would repeat for every element, - with <makevar>entry</makevar> being replaced with the value of - the current element.</para> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml deleted file mode 100644 index 229f36aeb7..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml +++ /dev/null @@ -1,355 +0,0 @@ -<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.8 2000/06/15 01:00:01 kevlo Exp $ ---> - -<appendix id="examples"> - <title>Examples</title> - - <para>This appendix contains example SGML files and command lines you can - use to convert them from one output format to another. If you have - successfully installed the Documentation Project tools then you should - be able to to use these examples directly.</para> - - <para>These examples are not exhaustive—they do not contain all the - elements you might want to use, particularly in your document's front - matter. For more examples of DocBook markup you should examine the SGML - source for this and other documents, available in the - <application>CVSup</application> <literal>doc</literal> collection, or - available online starting at <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</ulink>.</para> - - <para>To avoid confusion, these examples use the standard DocBook 3.1 DTD - rather than the FreeBSD extension. They also use the stock stylesheets - distributed by Norm Walsh, rather than any customisations made to those - stylesheets by the FreeBSD Documentation Project. This makes them more - useful as generic DocBook examples.</para> - - <sect1> - <title>DocBook <sgmltag>book</sgmltag></title> - - <example> - <title>DocBook <sgmltag>book</sgmltag></title> - - <programlisting><![ CDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> - -<book> - <bookinfo> - <title>An Example Book</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> - - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> - - <abstract> - <para>If your book has an abstract then it should go here.</para> - </abstract> - </bookinfo> - - <preface> - <title>Preface</title> - - <para>Your book may have a preface, in which case it should be placed - here.</para> - </preface> - - <chapter> - <title>My first chapter</title> - - <para>This is the first chapter in my book.</para> - - <sect1> - <title>My first section</title> - - <para>This is the first section in my book.</para> - </sect1> - </chapter> -</book>]]></programlisting> - </example> - </sect1> - - <sect1> - <title>DocBook <sgmltag>article</sgmltag></title> - - <example> - <title>DocBook <sgmltag>article</sgmltag></title> - - <programlisting><![ CDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> - -<article> - <artheader> - <title>An example article</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> - - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> - - <abstract> - <para>If your article has an abstract then it should go here.</para> - </abstract> - </artheader> - - <sect1> - <title>My first section</title> - - <para>This is the first section in my article.</para> - - <sect2> - <title>My first sub-section</title> - - <para>This is the first sub-section in my article.</para> - </sect2> - </sect1> -</article>]]></programlisting> - </example> - </sect1> - - <sect1> - <title>Producing formatted output</title> - - <para>This section assumes that you have installed the software listed in - the <filename>textproc/docproj</filename> port, either by hand, or by - using the port. Further, it is assumed that your software is installed - in subdirectories under <filename>/usr/local/</filename>, and the - directory where binaries have been installed is in your - <envar>PATH</envar>. Adjust the paths as necessary for your - system.</para> - - <sect2> - <title>Using Jade</title> - - <example> - <title>Converting DocBook to HTML (one large file)</title> - - <screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"> - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl <co id="examples-co-jade-1-dsssl"> - -t sgml <co id="examples-co-jade-1-transform"> file.sgml > file.html <co id="examples-co-jade-1-filename"></userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-1-nochunks"> - <para>Specifies the <literal>nochunks</literal> parameter to the - stylesheets, forcing all output to be written to - <abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para> - </callout> - - <callout arearefs="examples-co-jade-1-catalog"> - <para>Specifies the catalogs that Jade will need to process. - Three catalogs are required. The first is a catalog that - contains information about the DSSSL stylesheets. The second - contains information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-1-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that Jade - will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-1-transform"> - <para>Instructs Jade to perform a - <emphasis>transformation</emphasis> from one DTD to another. In - this case, the input is being transformed from the DocBook DTD - to the HTML DTD.</para> - </callout> - - <callout arearefs="examples-co-jade-1-filename"> - <para>Specifies the file that Jade should process, and redirects - output to the specified <filename>.html</filename> file.</para> - </callout> - </calloutlist> - </example> - - <example> - <title>Converting DocBook to HTML (several small files)</title> - - <screen>&prompt.user; <userinput>jade \ - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl <co id="examples-co-jade-2-dsssl"> - -t sgml <co id="examples-co-jade-2-transform"> <replaceable>file</replaceable>.sgml <co id="examples-co-jade-2-filename"></userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-2-catalog"> - <para>Specifies the catalogs that Jade will need to process. - Three catalogs are required. The first is a catalog that - contains information about the DSSSL stylesheets. The second - contains information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-2-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that Jade - will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-2-transform"> - <para>Instructs Jade to perform a - <emphasis>transformation</emphasis> from one DTD to another. In - this case, the input is being transformed from the DocBook DTD - to the HTML DTD.</para> - </callout> - - <callout arearefs="examples-co-jade-2-filename"> - <para>Specifies the file that Jade should process. The - stylesheets determine how the individual HTML files will be - named, and the name of the <quote>root</quote> file (i.e., the - one that contains the start of the document.</para> - </callout> - </calloutlist> - - <para>This example may still only generate one HTML file, depending on - the structure of the document you are processing, and the - stylesheet's rules for splitting output.</para> - </example> - - <example id="examples-docbook-postscript"> - <title>Converting DocBook to Postscript</title> - - <para>The source SGML file must be converted to a TeX file.</para> - - <screen>&prompt.user; <userinput>jade -Vtex-backend \ <co id="examples-co-jade-3-tex-backend"> - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl <co id="examples-co-jade-3-dsssl"> - -t tex <co id="examples-co-jade-3-tex"> <replaceable>file</replaceable>.sgml</userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-3-tex-backend"> - <para>Customises the stylesheets to use various options - specific to producing output for TeX.</para> - </callout> - - <callout arearefs="examples-co-jade-3-catalog"> - <para>Specifies the catalogs that Jade will need to process. Three - catalogs are required. The first is a catalog that contains - information about the DSSSL stylesheets. The second contains - information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-3-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that - Jade will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-3-tex"> - <para>Instructs Jade to convert the output to TeX.</para> - </callout> - </calloutlist> - - <para>The generated <filename>.tex</filename> file must now be run - through <command>tex</command>, specifying the - <literal>&jadetex</literal> macro package.</para> - - <screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen> - - <para>You have to run <command>tex</command> <emphasis>at - least</emphasis> three times. The first run processes the - document, and determines areas of the document which are referenced - from other parts of the document, for use in indexing, and so - on.</para> - - <para>Do not be alarmed if you see warning messages such as - <literal>LaTeX Warning: Reference `136' on page 5 undefined on input - line 728.</literal> at this point.</para> - - <para>The second run reprocesses the document now that certain pieces - of information are known (such as the document's page length). This - allows index entries and other cross-references to be fixed - up.</para> - - <para>The third pass performs any final cleanup necessary.</para> - - <para>The output from this stage will be - <filename><replaceable>file</replaceable>.dvi</filename>.</para> - - <para>Finally, run <command>dvips</command> to convert the - <filename>.dvi</filename> file to Postscript.</para> - - <screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen> - </example> - - <example> - <title>Converting DocBook to PDF</title> - - <para>The first part of this process is identical to that when - converting DocBook to Postscript, using the same - <command>jade</command> command line (<xref - linkend="examples-docbook-postscript">).</para> - - <para>When the <filename>.tex</filename> file has been generated you - run TeX as before. However, use the &pdfjadetex macro package - instead.</para> - - <screen>&prompt.user; <userinput>tex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen> - - <para>Again, run this command three times.</para> - - <para>This will generate - <filename><replaceable>file</replaceable>.pdf</filename>, which does - not need to be processed any further.</para> - </example> - </sect2> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml deleted file mode 100644 index ff994d5ac3..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ /dev/null @@ -1,179 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml,v 1.4 1999/09/06 06:52:40 peter Exp $ ---> - -<chapter id="overview"> - <title>Overview</title> - - <para>Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that documentation - is produced. Your contributions are very valuable.</para> - - <para>This document's main purpose is to clearly explain <emphasis>how - the FDP is organised</emphasis>, <emphasis>how to write and submit - documentation to the FDP</emphasis>, and <emphasis>how to - effectively use the tools available to you when writing - documentation</emphasis>.</para> - - <para>Every one is welcome to join the FDP. There is no minimum - membership requirement, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - <email>freebsd-doc@FreeBSD.org</email> mailing list.</para> - - <para>After you have finished reading this document you should:</para> - - <itemizedlist> - <listitem> - <para>Know which documentation is maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the SGML source code for the - documentation maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to make changes to the documentation.</para> - </listitem> - - <listitem> - <para>Be able to submit your changes back for review and eventual - inclusion in the FreeBSD documentation.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>The FreeBSD Documentation Set</title> - - <para>The FDP is responsible for four categories of FreeBSD - documentation.</para> - - <variablelist> - <varlistentry> - <term>Manual pages</term> - - <listitem> - <para>The English language system manual pages are not written by - the FDP, as they are part of the base system. However, the FDP can - (and has) re-worded parts of existing manual pages to make them - clearer, or to correct inaccuracies.</para> - - <para>The translation teams are responsible for translating the - system manual pages in to different languages. These translations - are kept within the FDP.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ</term> - - <listitem> - <para>The FAQ aims to address (in short question and answer format) - questions that are asked, or should be asked, on the various - mailing lists and newsgroups devoted to FreeBSD. The format does - not permit long and comprehensive answers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>The Handbook aims to be the comprehensive on-line resource and - reference for FreeBSD users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web site</term> - - <listitem> - <para>This is the main FreeBSD presence on the World Wide Web, - visible at <ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink> - and many mirrors around the world. The web site is many people's - first exposure to FreeBSD.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>These four groups of documentation are all available in the - FreeBSD CVS tree. This means that the logs of changes to these - files are visible to anyone, and anyone can use a program such as - <application>CVSup</application> or - <application>CTM</application> to keep local copies of - this documentation.</para> - - <para>In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the CVS - repository as well (where the author has agreed to this). In - other cases the author has decided to keep his documentation - separate from the main FreeBSD repository. The FDP endeavours to - provide links to as much of this documentation as - possible.</para> - </sect1> - - <sect1> - <title>Before you start</title> - - <para>This document assumes that you already know:</para> - - <itemizedlist> - <listitem> - <para>How to maintain an up-to-date local copy of the FreeBSD - documentation by maintaining a local copy of the - FreeBSD CVS repository (using <application>CVS</application> - and either <application>CVSup</application> or - <application>CTM</application>) or by using - <application>CVSup</application> to download just a - <emphasis>checked-out</emphasis> copy.</para> - </listitem> - - <listitem> - <para>How to download and install new software using either the - FreeBSD Ports system or &man.pkg.add.1;.</para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml deleted file mode 100644 index 8abcde6496..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml +++ /dev/null @@ -1,150 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml,v 1.3 1999/09/06 06:52:41 peter Exp $ ---> - -<chapter id="psgml-mode"> - <title>Using <literal>sgml-mode</literal> with - <application>Emacs</application></title> - - <para>Recent versions of Emacs or Xemacs (available from the ports - collection) contain a very useful package called PSGML. Automatically - invoked when a file with the <filename>.sgml</filename> extension is loaded, - or by typing <command>M-x sgml-mode</command>, it is a major mode for - dealing with SGML files, elements and attributes.</para> - - <para>An understanding of some of the commands provided by this mode can - make working with SGML documents such as the Handbook much easier.</para> - - <variablelist> - <varlistentry> - <term><command>C-c C-e</command></term> - - <listitem> - <para>Runs <literal>sgml-insert-element</literal>. You will be - prompted for the name of the element to insert at the current point. - You can use the TAB key to complete the element. Elements that are - not valid at the current point will be disallowed.</para> - - <para>The start and end tags for the element will be inserted. If the - element contains other, mandatory, elements then these will be - inserted as well.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c =</command></term> - - <listitem> - <para>Runs <literal>sgml-change-element-name</literal>. Place the - point within an element and run this command. You will be prompted - for the name of the element to change to. Both the start and end - tags of the current element will be changed to the new - element.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-r</command></term> - - <listitem> - <para>Runs <literal>sgml-tag-region</literal>. Select some text (move - to start of text, C-space, move to end of text, C-space) and then - run this command. You will be prompted for the element to use. This - element will then be inserted immediately before and after your - marked region.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c -</command></term> - - <listitem> - <para>Runs <literal>sgml-untag-element</literal>. Place the point - within the start or end tag of an element you want to remove, and - run this command. The element's start and end tags will be - removed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-q</command></term> - - <listitem> - <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill - (i.e., reformat) content from the current element in. The filling - <emphasis>will</emphasis> affect content in which whitespace is - significant, such as within <sgmltag>programlisting</sgmltag> - elements, so run this command with care.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-a</command></term> - - <listitem> - <para>Runs <literal>sgml-edit-attributes</literal>. Opens a second - buffer containing a list of all the attributes for the closest - enclosing element, and their current values. Use TAB to navigate - between attributes, <command>C-k</command> to remove an existing - value and replace it with a new one, <command>C-c</command> to close - this buffer and return to the main document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-v</command></term> - - <listitem> - <para>Runs <literal>sgml-validate</literal>. Prompts you to save the - current document (if necessary) and then runs an SGML validator. The - output from the validator is captured into a new buffer, and you can - then navigate from one troublespot to the next, fixing markup errors - as you go.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Doubtless there are other useful functions of this mode, but those are - the ones I use most often.</para> -</chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml deleted file mode 100644 index 9f8ac6dd06..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml +++ /dev/null @@ -1,121 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml,v 1.4 1999/09/06 06:52:41 peter Exp $ ---> - -<chapter id="see-also"> - <title>See Also</title> - - <para>This document is deliberately not an exhaustive discussion of SGML, - the DTDs listed, and the FreeBSD Documentation Project. For more - information about these, you are encouraged to see the following web - sites.</para> - - <sect1> - <title>The FreeBSD Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.FreeBSD.org/docproj/">The FreeBSD - Documentation Project web pages</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/handbook/">The FreeBSD Handbook</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>SGML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web - page</ulink>, a comprehensive SGML resource</para> - </listitem> - - <listitem> - <para><ulink - url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>HTML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.w3.org/">The World Wide Web - Consortium</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 - specification</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>DocBook</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oasis-open.org/docbook/">The DocBook - Technical Committee</ulink>, maintainers of the DocBook DTD</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>The Linux Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.linuxdoc.org/">The Linux Documentation - Project web pages</ulink></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml deleted file mode 100644 index 12d7995a4b..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ /dev/null @@ -1,2555 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.16 2000/10/29 20:20:25 nik Exp $ ---> - -<chapter id="sgml-markup"> - <title>SGML Markup</title> - - <para>This chapter describes the three markup languages you will encounter - when you contribute to the FreeBSD documentation project. Each section - describes the markup language, and details the markup that you are likely - to want to use, or that is already in use.</para> - - <para>These markup languages contain a large number of elements, and it can - be confusing sometimes to know which element to use for a particular - situation. This section goes through the elements you are most likely to - need, and gives examples of how you would use them.</para> - - <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since - that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. - If you have a question about how best to markup a particular piece of - content, please post it to the FreeBSD Documentation Project mailing list - <email>freebsd-doc@FreeBSD.org</email>.</para> - - <note> - <title>Inline vs. block</title> - - <para>In the remainder of this document, when describing elements, - <emphasis>inline</emphasis> means that the element can occur within a - block element, and does not cause a line break. A - <emphasis>block</emphasis> element, by comparison, will cause a line - break (and other processing) when it is encountered.</para> - </note> - - <sect1> - <title>HTML</title> - - <para>HTML, the HyperText Markup Language, is the markup language of - choice on the World Wide Web. More information can be found at - <URL:<ulink - url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> - - <para>HTML is used to markup pages on the FreeBSD web site. It should not - (generally) be used to mark up other documention, since DocBook offers a - far richer set of elements to choose from. Consequently, you will - normally only encounter HTML pages if you are writing for the web - site.</para> - - <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the - latest, 4.0 (available in both <emphasis>strict</emphasis> and - <emphasis>loose</emphasis> variants).</para> - - <para>The HTML DTDs are available from the ports collection in the - <filename>textproc/html</filename> port. They are automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>There are a number of HTML FPIs, depending upon the version (also - known as the level) of HTML that you want to declare your document to - be compliant with.</para> - - <para>The majority of HTML documents on the FreeBSD web site comply with - the loose version of HTML 4.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional elements</title> - - <para>An HTML document is normally split in to two sections. The first - section, called the <emphasis>head</emphasis>, contains - meta-information about the document, such as its title, the name of - the author, the parent document, and so on. The second section, the - <emphasis>body</emphasis>, contains the content that will be displayed - to the user.</para> - - <para>These sections are indicated with <sgmltag>head</sgmltag> and - <sgmltag>body</sgmltag> elements respectively. These elements are - contained within the top-level <sgmltag>html</sgmltag> element.</para> - - <example> - <title>Normal HTML document structure</title> - - <programlisting><html> - <head> - <title><replaceable>The document's title</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Headings</title> - - <para>HTML allows you to denote headings in your document, at up to - six different levels.</para> - - <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, - then <sgmltag>h2</sgmltag>, continuing down to - <sgmltag>h6</sgmltag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<h1>First section</h1> - -<!-- Document introduction goes here --> - -<h2>This is the heading for the first section</h2> - -<!-- Content for the first section goes here --> - -<h3>This is the heading for the first sub-section</h3> - -<!-- Content for the first sub-section goes here --> - -<h2>This is the heading for the second section</h2> - -<!-- Content for the second section goes here -->]]></programlisting> - </example> - - <para>Generally, an HTML page should have one first level heading - (<sgmltag>h1</sgmltag>). This can contain many second level - headings (<sgmltag>h2</sgmltag>), which can in turn contain many - third level headings. Each - <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have - the same element, but one further up the hierarchy, preceeding it. - Leaving gaps in the numbering is to be avoided.</para> - - <example> - <title>Bad ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<h1>First section</h1> - -<!-- Document introduction --> - -<h3>Sub-section</h3> - -<!-- This is bad, <h2> has been left out -->]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphs</title> - - <para>HTML supports a single paragraph element, - <sgmltag>p</sgmltag>.</para> - - <example> - <title><sgmltag>p</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph.</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>A small excerpt from the US Constitution:</p> - -<blockquote>We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the general - Welfare, and secure the Blessings of Liberty to ourselves and our - Posterity, do ordain and establish this Constitution for the - United States of America.</blockquote>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Lists</title> - - <para>You can present the user with three types of lists, ordered, - unordered, and definition.</para> - - <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be preceded by a bullet point. - Definition lists are composed of two sections for each entry. The - first section is the term being defined, and the second section is - the definition of the term.</para> - - <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> - element, unordered lists by the <sgmltag>ul</sgmltag> element, and - definition lists by the <sgmltag>dl</sgmltag> element.</para> - - <para>Ordered and unordered lists contain listitems, indicated by the - <sgmltag>li</sgmltag> element. A listitem can contain textual - content, or it may be further wrapped in one or more - <sgmltag>p</sgmltag> elements.</para> - - <para>Definition lists contain definition terms - (<sgmltag>dt</sgmltag>) and definition descriptions - (<sgmltag>dd</sgmltag>). A definition term can only contain inline - elements. A definition description can contain other block - elements.</para> - - <example> - <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>An unordered list. Listitems will probably be - preceeded by bullets.</p> - -<ul> - <li>First item</li> - - <li>Second item</li> - - <li>Third item</li> -</ul> - -<p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.</p> - -<ol> - <li><p>This is the first item. It only has one paragraph.</p></li> - - <li><p>This is the first paragraph of the second item.</p> - - <p>This is the second paragraph of the second item.</p></li> - - <li><p>This is the first and only paragraph of the third - item.</p></li> -</ol>]]></programlisting> - </example> - - <example> - <title>Definition lists with <sgmltag>dl</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<dl> - <dt>Term 1</dt> - - <dd><p>Paragraph 1 of definition 1.</p></dd> - - <p>Paragraph 2 of definition 1.</p></dd> - - <dt>Term 2</dt> - - <dd><p>Paragraph 1 of definition 2.</p></dd> - - <dt>Term 3</dt> - - <dd>Paragraph 1 of definition 3. Note that the <p> - element is not required in the single paragraph case.</dd> -</dl>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Pre-formatted text</title> - - <para>You can indicate that text should be shown to the user exactly - as it is in the file. Typically, this means that the text is shown - in a fixed font, multiple spaces are not merged in to one, and line - breaks in the text are significant.</para> - - <para>In order to do this, wrap the content in the - <sgmltag>pre</sgmltag> element.</para> - - <example> - <title><sgmltag>pre</sgmltag></title> - - <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail - message;</para> - - <programlisting><![ CDATA [<pre> From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There's a new copy of my primer for contributers to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N</pre>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>Most text-mode browsers (such as Lynx) do not render tables - particularly effectively. If you are relying on the tabular - display of your content, you should consider using alternative - markup to prevent confusion.</para> - </note> - - <para>Mark up tabular information using the <sgmltag>table</sgmltag> - element. A table consists of one or more table rows - (<sgmltag>tr</sgmltag>), each containing one or more cells of table - data (<sgmltag>td</sgmltag>). Each cell can contain other block - elements, such as paragraphs or lists. It can also contain another - table (this nesting can repeat indefinitely). If the cell only - contains one paragraph then you do not need to include the - <sgmltag>p</sgmltag> element.</para> - - <example> - <title>Simple use of <sgmltag>table</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p> - -<table> - <tr> - <td>Top left cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting></example> - - <para>A cell can span multiple rows and columns. To indicate this, - add the <literal>rowspan</literal> and/or <literal>colspan</literal> - attributes, with values indicating the number of rows of columns - that should be spanned.</para> - - <example> - <title>Using <literal>rowspan</literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to - it on the right.</p> - -<table> - <tr> - <td rowspan="2">Long and thin</td> - </tr> - - <tr> - <td>Top cell</td> - - <td>Bottom cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>colspan</literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p> - -<table> - <tr> - <td colspan="2">Top cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> together</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of - cells merged in to one. The other cells are normal.</p> - -<table> - <tr> - <td colspan="2" rowspan="2">Top left large cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <!-- Because the large cell on the left merges in to - this row, the first <td> will occur on its - right --> - - <td>Middle right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom middle cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>You have two levels of emphasis available in HTML, - <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>. - <sgmltag>em</sgmltag> is for a normal level of emphasis and - <sgmltag>strong</sgmltag> indicates stronger emphasis.</para> - - <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and - <sgmltag>strong</sgmltag> is rendered in bold. This is not always - the case, however, and you should not rely on it.</para> - - <example> - <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while - <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Bold and italics</title> - - <para>Because HTML includes presentational markup, you can also - indicate that particular content should be rendered in bold or - italic. The elements are <sgmltag>b</sgmltag> and - <sgmltag>i</sgmltag> respectively.</para> - - <example> - <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - - <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is - in italics.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating fixed pitch text</title> - - <para>If you have content that should be rendered in a fixed pitch - (typewriter) typeface, use <sgmltag>tt</sgmltag> (for - “teletype”).</para> - - <example> - <title><sgmltag>tt</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This document was originally written by - Nik Clayton, who can be reached by e-mail as - <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Content size</title> - - <para>You can indicate that content should be shown in a larger or - smaller font. There are three ways of doing this.</para> - - <orderedlist> - <listitem> - <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> - around the content you wish to change size. These tags can be - nested, so <literal><big><big>This is much - bigger</big></big></literal> is possible.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to <literal>+1</literal> or <literal>-1</literal> - respectively. This has the same effect as using - <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, - the use of this approach is deprecated.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to a number between 1 and 7. The default font size - is <literal>3</literal>. This approach is deprecated.</para> - </listitem> - </orderedlist> - - <example> - <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag></title> - - <para>The following fragments all do the same thing.</para> - - <programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>. But - this text is <big>slightly bigger</big>.</p> - -<p>This text is <font size="-1">slightly smaller</font>. But - this text is <font size="+1">slightly bigger</font.</p> - -<p>This text is <font size="2">slightly smaller</font>. But - this text is <font size="4">slightly bigger</font>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other documents on the WWW</title> - - <para>In order to include a link to another document on the WWW you - must know the URL of the document you want to link to.</para> - - <para>The link is indicated with <sgmltag>a</sgmltag>, and the - <literal>href</literal> attribute contains the URL of the target - document. The content of the element becomes the link, and is - normally indicated to the user in some way (underlining, change of - colour, different mouse cursor when over the link, and so - on).</para> - - <example> - <title>Using <literal><a href="..."></literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>More information is available at the - <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> - </example> - - <para>These links will take the user to the top of the chosen - document.</para> - </sect3> - - <sect3> - <title>Linking to other parts of documents</title> - - <para>Linking to a point within another document (or within the same - document) requires that the document author include anchors that you - can link to.</para> - - <para>Anchors are indicated with <sgmltag>a</sgmltag> and the - <literal>name</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a name="..."></literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>To link to a named part of a document, write a normal link to - that document, but include the name of the anchor after a - <literal>#</literal> symbol.</para> - - <example> - <title>Linking to a named part of another document</title> - - <para>Assume that the <literal>para1</literal> example resides in a - document called <filename>foo.html</filename>.</para> - - <programlisting><![ CDATA [<p>More information can be found in the - <a href="foo.html#para1">first paragraph</a> of - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>If you are linking to a named anchor within the same document - then you can omit the document's URL, and just include the name of - the anchor (with the preceeding <literal>#</literal>).</para> - - <example> - <title>Linking to a named part of the same document</title> - - <para>Assume that the <literal>para1</literal> example resides in - this document</para> - - <programlisting><![ CDATA [<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>DocBook</title> - - <para>DocBook was designed by the <ulink - url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be - a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily oriented towards markup that - describes <emphasis>what</emphasis> something is, rather than describing - <emphasis>how</emphasis> it should be presented.</para> - - <note> - <title><literal>formal</literal> vs. <literal>informal</literal></title> - - <para>Some elements may exist in two forms, <emphasis>formal</emphasis> - and <emphasis>informal</emphasis>. Typically, the formal version of - the element will consist of a title followed by the information - version of the element. The informal version will not have a - title.</para> - </note> - - <para>The DocBook DTD is available from the ports collection in the - <filename>textproc/docbook</filename> port. It is automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>FreeBSD extensions</title> - - <para>The FreeBSD Documentation Project has extended the DocBook DTD by - adding some new elements. These elements serve to make some of the - markup more precise.</para> - - <para>Where a FreeBSD specific element is listed below it is clearly - marked.</para> - - <para>Throughout the rest of this document, the term - “DocBook” is used to mean the FreeBSD extended DocBook - DTD.</para> - - <note> - <para>There is nothing about these extensions that is FreeBSD - specific, it was just felt that they were useful enhancements for - this particular project. Should anyone from any of the other *nix - camps (NetBSD, OpenBSD, Linux, …) be interested in - collaborating on a standard DocBook extension set, please get in - touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para> - </note> - - <para>The FreeBSD extensions are not (currently) in the ports - collection. They are stored in the FreeBSD CVS tree, as <ulink - url="http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para> - </sect2> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing FPIs for - DocBook customisations, the FPI for the FreeBSD extended DocBook DTD - is;</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> - </sect2> - - <sect2> - <title>Document structure</title> - - <para>DocBook allows you to structure your documentation in several - ways. In the FreeBSD Documentation Project we are using two primary - types of DocBook document: the book and the article.</para> - - <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a - mandatory requirement. There may be <sgmltag>part</sgmltag>s between - the book and the chapter to provide another layer of organisation. - The Handbook is arranged in this way.</para> - - <para>A chapter may (or may not) contain one or more sections. These - are indicated with the <sgmltag>sect1</sgmltag> element. If a section - contains another section then use the <sgmltag>sect2</sgmltag> - element, and so on, up to <sgmltag>sect5</sgmltag>.</para> - - <para>Chapters and sections contain the remainder of the content.</para> - - <para>An article is simpler than a book, and does not use chapters. - Instead, the content of an article is organised into one or more - sections, using the same <sgmltag>sect1</sgmltag> (and - <sgmltag>sect2</sgmltag> and so on) elements that are used in - books.</para> - - <para>Obviously, you should consider the nature of the documentation you - are writing in order to decide whether it is best marked up as a book - or an article. Articles are well suited to information that does not - need to be broken down into several chapters, and that is, relatively - speaking, quite short, at up to 20-25 pages of content. Books are - best suited to information that can be broken up into several - chapters, possibly with appendices and similar content as well.</para> - - <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD - tutorials</ulink> are all marked up as articles, while this - document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD - FAQ</ulink>, and the <ulink - url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are - all marked up as books.</para> - - <sect3> - <title>Starting a book</title> - - <para>The content of the book is contained within the - <sgmltag>book</sgmltag> element. As well as containing structural - markup, this element can contain elements that include additional - information about the book. This is either meta-information, used - for reference purposes, or additional content used to produce a - title page.</para> - - <para>This additional information should be contained within - <sgmltag>bookinfo</sgmltag>.</para> - - <example> - <title>Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><book> - <bookinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your e-mail address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> - - … - -</book></programlisting> - </example> - </sect3> - - <sect3> - <title>Starting an article</title> - - <para>The content of the article is contained within the - <sgmltag>article</sgmltag> element. As well as containing - structural markup, this element can contain elements that include - additional information about the article. This is either - meta-information, used for reference purposes, or additional content - used to produce a title page.</para> - - <para>This additional information should be contained within - <sgmltag>artheader</sgmltag>.</para> - - <example> - <title>Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>artheader</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><article> - <artheader> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your e-mail address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> - </abstract> - </artheader> - - … - -</article></programlisting> - </example> - </sect3> - <sect3> - <title>Indicating chapters</title> - - <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each - chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not - contain chapters, they are reserved for books.</para> - - <example> - <title>A simple chapter</title> - - <programlisting><![ CDATA [<chapter> - <title>The chapter's title</title> - - ... -</chapter>]]></programlisting> - </example> - - <para>A chapter cannot be empty; it must contain elements in addition - to <sgmltag>title</sgmltag>. If you need to include an empty - chapter then just use an empty paragraph.</para> - - <example> - <title>Empty chapters</title> - - <programlisting><![ CDATA [<chapter> - <title>This is an empty chapter</title> - - <para></para> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Sections below chapters</title> - - <para>In books, chapters may (but do not need to) be broken up into - sections, subsections, and so on. In articles, sections are the - main structural element, and each article must contain at least one - section. Use the - <sgmltag>sect<replaceable>n</replaceable></sgmltag> element. The - <replaceable>n</replaceable> indicates the section number, which - identifies the section level.</para> - - <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is - <sgmltag>sect1</sgmltag>. You can have one or more of these in a - chapter. They can contain one or more <sgmltag>sect2</sgmltag> - elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> - - <example> - <title>Sections in chapters</title> - - <programlisting><![ RCDATA [<chapter> - <title>A sample chapter</title> - - <para>Some text in the chapter.</para> - - <sect1> - <title>First section (1.1)</title> - - … - </sect1> - - <sect1> - <title>Second section (1.2)</title> - - <sect2> - <title>First sub-section (1.2.1)</title> - - <sect3> - <title>First sub-sub-section (1.2.1.1)</title> - - … - </sect3> - </sect2> - - <sect2> - <title>Second sub-section (1.2.2)</title> - - … - </sect2> - </sect1> -</chapter>]]></programlisting> - </example> - - <note> - <para>This example includes section numbers in the section titles. - You should not do this in your documents. Adding the section - numbers is carried out the by the stylesheets (of which more - later), and you do not need to manage them yourself.</para> - </note> - </sect3> - - <sect3> - <title>Subdividing using <sgmltag>part</sgmltag>s</title> - - <para>You can introduce another layer of organisation between - <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or - more <sgmltag>part</sgmltag>s. This cannot be done in an - <sgmltag>article</sgmltag>.</para> - - <programlisting><![ CDATA [<part> - <title>Introduction</title> - - <chapter> - <title>Overview</title> - - ... - </chapter> - - <chapter> - <title>What is FreeBSD?</title> - - ... - </chapter> - - <chapter> - <title>History</title> - - ... - </chapter> -</part>]]></programlisting> - </sect3> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs: - <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and - <sgmltag>simpara</sgmltag>.</para> - - <para>Most of the time you will only need to use - <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a - <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> - disallows some elements from within <sgmltag>para</sgmltag>. Stick - with <sgmltag>para</sgmltag>.</para> - - <example> - <title><sgmltag>para</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any - other element.</para> ]]></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any other - element.</para> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph. You will - probably only need it infrequently.</para> - - <para>Blockquotes can optionally contain a title and an attribution - (or they can be left untitled and unattributed).</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para> - -<blockquote> - <title>Preamble to the Constitution of the United States</title> - - <attribution>Copied from a web site somewhere</attribution> - - <para>We the People of the United States, in Order to form a more perfect - Union, establish Justice, insure domestic Tranquility, provide for the - common defence, promote the general Welfare, and secure the Blessings - of Liberty to ourselves and our Posterity, do ordain and establish this - Constitution for the United States of America.</para> -</blockquote>]]></programlisting> - - <para>Appearance:</para> - - <blockquote> - <title>Preamble to the Constitution of the United States</title> - - <attribution>Copied from a web site somewhere</attribution> - - <para>We the People of the United States, in Order to form a more - perfect Union, establish Justice, insure domestic Tranquility, - provide for the common defence, promote the general Welfare, and - secure the Blessings of Liberty to ourselves and our Posterity, - do ordain and establish this Constitution for the United States - of America.</para> - </blockquote> - </example> - </sect3> - - <sect3> - <title>Tips, notes, warnings, cautions, important information and - sidebars.</title> - - <para>You may need to include extra information separate from the - main body of the text. Typically this is “meta” - information that the user should be aware of.</para> - - <para>Depending on the nature of the information, one of - <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, - <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and - <sgmltag>important</sgmltag> should be used. Alternatively, if the - information is related to the main text but is not one of the above, - use <sgmltag>sidebar</sgmltag>.</para> - - <para>The circumstances in which to choose one of these elements over - another is unclear. The DocBook documentation suggests;</para> - - <itemizedlist> - <listitem> - <para>A Note is for information that should be heeded by all - readers.</para> - </listitem> - - <listitem> - <para>An Important element is a variation on Note.</para> - </listitem> - - <listitem> - <para>A Caution is for information regarding possible data loss - or software damage.</para> - </listitem> - - <listitem> - <para>A Warning is for information regarding possible hardware - damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><sgmltag>warning</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<warning> - <para>Installing FreeBSD may make you want to delete Windows from your - harddisk.</para> -</warning>]]></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <warning> - <para>Installing FreeBSD may make you want to delete Windows from - your harddisk.</para> - </warning> - </sect3> - - <sect3> - <title>Lists and procedures</title> - - <para>You will often need to list pieces of information to the user, - or present them with a number of steps that must be carried out in - order to accomplish a particular goal.</para> - - <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, or - <sgmltag>procedure</sgmltag><footnote><para>There are other types of - list element in DocBook, but we're not concerned with those at - the moment.</para> - </footnote> - </para> - - <para><sgmltag>itemizedlist</sgmltag> and - <sgmltag>orderedlist</sgmltag> are similar to their counterparts in - HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one - consists of one or more <sgmltag>listitem</sgmltag> elements, and - each <sgmltag>listitem</sgmltag> contains one or more block - elements. The <sgmltag>listitem</sgmltag> elements are analagous to - HTML's <sgmltag>li</sgmltag> tags. However, unlike HTML, they are - required.</para> - - <para><sgmltag>procedure</sgmltag> is slightly different. It consists - of <sgmltag>step</sgmltag>s, which may in turn consists of more - <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each - <sgmltag>step</sgmltag> contains block elements.</para> - - <example> - <title><sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<itemizedlist> - <listitem> - <para>This is the first itemized item.</para> - </listitem> - - <listitem> - <para>This is the second itemized item.</para> - </listitem> -</itemizedlist> - -<orderedlist> - <listitem> - <para>This is the first ordered item.</para> - </listitem> - - <listitem> - <para>This is the second ordered item.</para> - </listitem> -</orderedlist> - -<procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> -</procedure>]]></programlisting> - - <para>Appearance:</para> - - <itemizedlist> - <listitem> - <para>This is the first itemized item.</para> - </listitem> - - <listitem> - <para>This is the second itemized item.</para> - </listitem> - </itemizedlist> - - <orderedlist> - <listitem> - <para>This is the first ordered item.</para> - </listitem> - - <listitem> - <para>This is the second ordered item.</para> - </listitem> - </orderedlist> - </example> - - <!-- Can't have <procedure> inside <example>, so this is a cheat --> - - <procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Showing file samples</title> - - <para>If you want to show a fragment of a file (or perhaps a complete - file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> - element.</para> - - <para>White space and line breaks within - <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> - significant. In particular, this means that the opening tag should - appear on the same line as the first line of the output, and the - closing tag should appear on the same line as the last line of the - output, otherwise spurious blank lines may be included.</para> - - <example> - <title><sgmltag>programlisting</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA[<para>When you have finished, your program should look like - this;</para> - -<programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting>]]></programlisting> - - <para>Notice how the angle brackets in the - <literal>#include</literal> line need to be referenced by their - entities instead of being included literally.</para> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this;</para> - - <programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting> - </example> - </sect3> - - <sect3> - <title>Callouts</title> - - <para>A callout is a mechanism for referring back to an earlier piece - of text or specific position within an earlier example without - linking to it within the text.</para> - - <para>To do this, mark areas of interest in your example - (<sgmltag>programlisting</sgmltag>, - <sgmltag>literallayout</sgmltag>, or whatever) with the - <sgmltag>co</sgmltag> element. Each element must have a unique - <literal>id</literal> assigned to it. After the example include a - <sgmltag>calloutlist</sgmltag> that refers back to the example and - provides additional commentary.</para> - - <example> - <title><sgmltag>co</sgmltag> and - <sgmltag>calloutlist</sgmltag></title> - - <programlisting><![ CDATA[<para>When you have finished, your program should look like - this;</para> - -<programlisting>#include <stdio.h> <co id="co-ex-include"> - -int <co id="co-ex-return"> -main(void) -{ - printf("hello, world\n"); <co id="co-ex-printf"> -}</programlisting> - -<calloutlist> - <callout arearefs="co-ex-include"> - <para>Includes the standard IO header file.</para> - </callout> - - <callout arearefs="co-ex-return"> - <para>Specifies that <function>main()</function> returns an - int.</para> - </callout> - - <callout arearefs="co-ex-printf"> - <para>The <function>printf()</function> call that writes - <literal>hello, world</literal> to standard output.</para> - </callout> -</calloutlist>]]></programlisting> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this;</para> - - <programlisting>#include <stdio.h> <co id="co-ex-include"> - -int <co id="co-ex-return"> -main(void) -{ - printf("hello, world\n"); <co id="co-ex-printf"> -}</programlisting> - - <calloutlist> - <callout arearefs="co-ex-include"> - <para>Includes the standard IO header file.</para> - </callout> - - <callout arearefs="co-ex-return"> - <para>Specifies that <function>main()</function> returns an - int.</para> - </callout> - - <callout arearefs="co-ex-printf"> - <para>The <function>printf()</function> call that writes - <literal>hello, world</literal> to standard output.</para> - </callout> - </calloutlist> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <para>Unlike HTML, you do not need to use tables for layout purposes, - as the stylesheet handles those issues for you. Instead, just use - tables for marking up tabular data.</para> - - <para>In general terms (and see the DocBook documentation for more - detail) a table (which can be either formal or informal) consists of - a <sgmltag>table</sgmltag> element. This contains at least one - <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup - you can then have one <sgmltag>thead</sgmltag> element, which - contains elements for the table headings (column headings), and one - <sgmltag>tbody</sgmltag> which contains the body of the - table.</para> - - <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> - contain <sgmltag>row</sgmltag> elements, which in turn contain - <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> - element specifies one cell in the table.</para> - - <example> - <title><sgmltag>informaltable</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> -</informaltable>]]></programlisting> - - <para>Appearance:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - - <para>If you don't want a border around the table the - <literal>frame</literal> attribute can be added to the - <sgmltag>informaltable</sgmltag> element with a value of - <literal>none</literal> (i.e., <literal><informaltable - frame="none"></literal>).</para> - - <example> - <title>Tables where <literal>frame="none"</literal></title> - - <para>Appearance:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>This is column head 1</entry> - <entry>This is column head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - </sect3> - - <sect3> - <title>Examples for the user to follow</title> - - <para>A lot of the time you need to show examples for the user to - follow. Typically, these will consist of dialogs with the computer; - the user types in a command, the user gets a response back, they - type in another command, and so on.</para> - - <para>A number of distinct elements and entities come in to play - here.</para> - - <variablelist> - <varlistentry> - <term><sgmltag>screen</sgmltag></term> - - <listitem> - <para>Everything the user sees in this example will be on the - computer screen, so the next element is - <sgmltag>screen</sgmltag>.</para> - - <para>Within <sgmltag>screen</sgmltag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>prompt</sgmltag>, - <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal></term> - - <listitem> - <para>Some of the things the user will be seeing on the screen - are prompts from the computer (either from the OS, command - shell, or application. These should be marked up using - <sgmltag>prompt</sgmltag>.</para> - - <para>As a special case, the two shell prompts for the normal - user and the root user have been provided as entities. Every - time you want to indicate the user is at a shell prompt, use - one of <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> as necessary. They do - not need to be inside <sgmltag>prompt</sgmltag>.</para> - - <note> - <para><literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> are FreeBSD - extensions to DocBook, and are not part of the original - DTD.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>userinput</sgmltag></term> - - <listitem> - <para>When displaying text that the user should type in, wrap it - in <sgmltag>userinput</sgmltag> tags. It will probably be - displayed differently to the user.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and - <sgmltag>userinput</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput> -foo1 -foo2 -foo3 -&prompt.user; <userinput>ls -1 | grep foo2</userinput> -foo2 -&prompt.user; <userinput>su</userinput> -<prompt>Password: </prompt> -&prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen>]]></programlisting> - - <para>Appearance:</para> - - <screen>&prompt.user; <userinput>ls -1</userinput> -foo1 -foo2 -foo3 -&prompt.user; <userinput>ls -1 | grep foo2</userinput> -foo2 -&prompt.user; <userinput>su</userinput> -<prompt>Password: </prompt> -&prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> - </example> - - <note> - <para>Even though we are displaying the contents of the file - <filename>foo2</filename>, it is <emphasis>not</emphasis> marked - up as <sgmltag>programlisting</sgmltag>. Reserve - <sgmltag>programlisting</sgmltag> for showing fragments of files - outside the context of user actions.</para> - </note> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>When you want to emphasise a particular word or phrase, use - <sgmltag>emphasis</sgmltag>. This may be presented as italic, or - bold, or might be spoken differently with a text-to-speech - system.</para> - - <para>There is no way to change the presentation of the emphasis - within your document, no equivalent of HTML's <sgmltag>b</sgmltag> - and <sgmltag>i</sgmltag>. If the information you are presenting is - important then consider presenting it in - <sgmltag>important</sgmltag> rather than - <sgmltag>emphasis</sgmltag>.</para> - - <example> - <title><sgmltag>emphasis</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> - premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix - like operating system for the Intel architecture.</para> - </example> - </sect3> - - <sect3> - <title>Applications, commands, options, and cites</title> - - <para>You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between - them is simple: an application is the name for a suite (or possibly - just 1) of programs that fulfil a particular task. A command is the - name of a program that the user can run.</para> - - <para>In addition, you will occasionally need to list one or more of - the options that a command might take.</para> - - <para>Finally, you will often want to list a command with its manual - section number, in the “command(number)” format so - common in Unix manuals.</para> - - <para>Mark up application names with - <sgmltag>application</sgmltag>.</para> - - <para>When you want to list a command with its manual section number - (which should be most of the time) the DocBook element is - <sgmltag>citerefentry</sgmltag>. This will contain a further two - elements, <sgmltag>refentrytitle</sgmltag> and - <sgmltag>manvolnum</sgmltag>. The content of - <sgmltag>refentrytitle</sgmltag> is the name of the command, and the - content of <sgmltag>manvolnum</sgmltag> is the manual page - section.</para> - - <para>This can be cumbersome to write, and so a series of <link - linkend="sgml-primer-general-entities">general entities</link> - have been created to make this easier. Each entity takes the form - <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> - - <para>The file that contains these entities is in - <filename>doc/share/sgml/man-refs.ent</filename>, and can be - referred to using this FPI:</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>Therefore, the introduction to your documentation will probably - look like this:</para> - - <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]></programlisting> - - <para>Use <sgmltag>command</sgmltag> when you want to include a - command name “in-line” but present it as something the - user should type in.</para> - - <para>Use <sgmltag>option</sgmltag> to mark up a command's - options.</para> - - <para>This can be confusing, and sometimes the choice is not always - clear. Hopefully this example makes it clearer.</para> - - <example> - <title>Applications, commands, and options.</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para><application>Sendmail</application> is the most - widely used Unix mail application.</para> - -<para><application>Sendmail</application> includes the - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, &man.mailq.8;, and &man.newaliases.8; - programs.</para> - -<para>One of the command line parameters to <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <option>-bp</option>, will display the current - status of messages in the mail queue. Check this on the command - line by running <command>sendmail -bp</command>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><application>Sendmail</application> is the most widely used - Unix mail application.</para> - - <para><application>Sendmail</application> includes the - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <citerefentry> - <refentrytitle>mailq</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, and <citerefentry> - <refentrytitle>newaliases</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry> programs.</para> - - <para>One of the command line parameters to <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <option>-bp</option>, will display the current - status of messages in the mail queue. Check this on the command - line by running <command>sendmail -bp</command>.</para> - </example> - - <note> - <para>Notice how the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> - </note> - </sect3> - - <sect3> - <title>Files, directories, extensions</title> - - <para>Whenever you wish to refer to the name of a file, a directory, - or a file extension, use <sgmltag>filename</sgmltag>.</para> - - <example> - <title><sgmltag>filename</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be - found in <filename>/usr/doc/en/handbook/</filename>. The first - file is called <filename>handbook.sgml</filename> in that - directory. You should also see a <filename>Makefile</filename> - and a number of files with a <filename>.ent</filename> - extension.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The SGML source for the Handbook in English can be found in - <filename>/usr/doc/en/handbook/</filename>. The first file is - called <filename>handbook.sgml</filename> in that directory. You - should also see a <filename>Makefile</filename> and a number of - files with a <filename>.ent</filename> extension.</para> - </example> - </sect3> - - <sect3> - <title>Devices</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When referring to devices you have two choices. You can either - refer to the device as it appears in <filename>/dev</filename>, or - you can use the name of the device as it appears in the kernel. For - this latter course, use <sgmltag>devicename</sgmltag>.</para> - - <para>Sometimes you will not have a choice. Some devices, such as - networking cards, do not have entries in <filename>/dev</filename>, - or the entries are markedly different from those entries.</para> - - <example> - <title><sgmltag>devicename</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial - communication in FreeBSD. <devicename>sio</devicename> manifests - through a number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> - -<para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in <filename>/dev</filename>. - -<para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><devicename>sio</devicename> is used for serial communication - in FreeBSD. <devicename>sio</devicename> manifests through a - number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and - <filename>/dev/cuaa0</filename>.</para> - - <para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in - <filename>/dev</filename>.</para> - - <para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para> - </example> - </sect3> - - <sect3> - <title>Hosts, domains, IP addresses, and so forth</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>You can markup identification information for networked - computers (hosts) in several ways, depending on the nature of the - information. All of them use <sgmltag>hostid</sgmltag> as the - element, with the <literal>role</literal> attribute selecting the - type of the marked up information.</para> - - <variablelist> - <varlistentry> - <term>No role attribute, or - <literal>role="hostname"</literal></term> - - <listitem> - <para>With no role attribute (i.e., - <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the - marked up information is the simple hostname, such as - <literal>freefall</literal> or <literal>wcarchive</literal>. - You can explicitly specify this with - <literal>role="hostname"</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="domainname"</literal></term> - - <listitem> - <para>The text is a domain name, such as - <literal>FreeBSD.org</literal> or - <literal>ngo.org.uk</literal>. There is no hostname - component.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="fqdn"</literal></term> - - <listitem> - <para>The text is a Fully Qualified Domain Name, with both - hostname and domain name parts.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ipaddr"</literal></term> - - <listitem> - <para>The text is an IP address, probably expressed as a dotted - quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="netmask"</literal></term> - - <listitem> - <para>The text is a network mask, which might be expressed as a - dotted quad, a hexadecimal string, or as a - <literal>/</literal> followed by a number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="mac"</literal></term> - - <listitem> - <para>The text is an ethernet MAC address, expressed as a series - of 2 digit hexadecimal numbers seperated by colons.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>hostid</sgmltag> and roles</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The local machine can always be referred to by the - name <hostid>localhost</hostid>, which will have the IP address - <hostid role="ipaddr">127.0.0.1</hostid>.</para> - -<para>The <hostid role="domainname">FreeBSD.org</hostid> domain - contains a number of different hosts, including - <hostid role="fqdn">freefall.FreeBSD.org</hostid> and - <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para> - -<para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> - (which can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - -<para>The MAC address uniquely identifies every network card in - in existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <hostid>localhost</hostid>, which will have the IP address <hostid - role="ipaddr">127.0.0.1</hostid>.</para> - - <para>The <hostid role="domainname">FreeBSD.org</hostid> domain - contains a number of different hosts, including <hostid - role="fqdn">freefall.FreeBSD.org</hostid> and <hostid - role="fqdn">bento.FreeBSD.org</hostid>.</para> - - <para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> (which - can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - - <para>The MAC address uniquely identifies every network card in - existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para> - </example> - </sect3> - - <sect3> - <title>Usernames</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When you need to refer to a specific username, such as - <literal>root</literal> or <literal>bin</literal>, use - <sgmltag>username</sgmltag>.</para> - - <example> - <title><sgmltag>username</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>To carry out most system administration functions you - will need to be <username>root</username>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>To carry out most system administration functions you will - need to be <username>root</username>.</para> - </example> - </sect3> - - <sect3> - <title>Describing <filename>Makefile</filename>s</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag>.</para> - - <para><sgmltag>maketarget</sgmltag> identifies a build target exported - by a <filename>Makefile</filename> that can be given as a parameter - to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a - variable that can be set (in the environment, on the - <command>make</command> command line, or within the - <filename>Makefile</filename>) to influence the process.</para> - - <example> - <title><sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename> - are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> - -<para>Typically, invoking <maketarget>all</maketarget> will rebuild the - application, and invoking <maketarget>clean</maketarget> will remove - the temporary files (<filename>.o</filename> for example) created by - the build process.</para> - -<para><maketarget>clean</maketarget> may be controlled by a number of - variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Two common targets in a <filename>Makefile</filename> are - <maketarget>all</maketarget> and - <maketarget>clean</maketarget>.</para> - - <para>Typically, invoking <maketarget>all</maketarget> will rebuild - the application, and invoking <maketarget>clean</maketarget> will - remove the temporary files (<filename>.o</filename> for example) - created by the build process.</para> - - <para><maketarget>clean</maketarget> may be controlled by a number - of variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para> - </example> - </sect3> - - <sect3> - <title>Literal text</title> - - <para>You will often need to include “literal” text in the - Handbook. This is text that is excerpted from another file, or - which should be copied from the Handbook into another file - verbatim.</para> - - <para>Some of the time, <sgmltag>programlisting</sgmltag> will be - sufficient to denote this text. <sgmltag>programlisting</sgmltag> - is not always appropriate, particularly when you want to include a - portion of a file “in-line” with the rest of the - paragraph.</para> - - <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> - - <example> - <title><sgmltag>literal</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel - configuration file determines the size of many system tables, and is - a rough guide to how many simultaneous logins the system will - support.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers 10</literal> line in the kernel - configuration file determines the size of many system tables, and - is a rough guide to how many simultaneous logins the system will - support.</para> - </example> - </sect3> - - <sect3> - <title>Showing items that the user <emphasis>must</emphasis> fill - in</title> - - <para>There will often be times when you want to show the user what to - do, or refer to a file, or command line, or similar, where the user - can not simply copy the examples that you provide, but must instead - include some information themselves.</para> - - <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. - Use it <emphasis>inside</emphasis> other elements to indicate parts - of that element's content that the user must replace.</para> - - <example> - <title><sgmltag>replaceable</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> -</informalexample>]]></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><sgmltag>replaceable</sgmltag> can be used in many different - elements, including <sgmltag>literal</sgmltag>. This example also - shows that <sgmltag>replaceable</sgmltag> should only be wrapped - around the content that the user <emphasis>is</emphasis> meant to - provide. The other content should be left alone.</para> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> - line in the kernel configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous logins the system will - support.</para> - -<para>For a desktop workstation, <literal>32</literal> is a good value - for <replaceable>n</replaceable>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers <replaceable>n</replaceable></literal> - line in the kernel configuration file determines the size of many - system tables, and is a rough guide to how many simultaneous - logins the system will support.</para> - - <para>For a desktop workstation, <literal>32</literal> is a good - value for <replaceable>n</replaceable>.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>Images</title> - - <important> - <para>Image support in the documentation is currently extremely - experimental. I think the mechanisms described here are unlikely to - change, but that's not guaranteed.</para> - - <para>You will also need to install the - <filename>graphics/ImageMagick</filename> port, which is used to - convert between the different image formats. This is a big port, - and most of it is not required. However, while we're working on the - <filename>Makefile</filename>s and other infrastructure it makes - things easier. This port is <emphasis>not</emphasis> in the - <filename>textproc/docproj</filename> meta port, you must install it - by hand.</para> - - <para>The best example of what follows in practice is the - <filename>en_US.ISO_8859-1/articles/vm-design/</filename> document. - If you're unsure of the description that follows, take a look at the - files in that directory to see how everything hangs togther. - Experiment with creating different formatted versions of the - document to see how the image markup appears in the formatted - output.</para> - </important> - - <sect3> - <title>Image formats</title> - - <para>We currently support two formats for images. The format you - should use will depend on the nature of your image.</para> - - <para>For images that are primarily vector based, such as network - diagrams, timelines, and similar, use Encapsulated Postscript, and - make sure that your images have the <filename>.eps</filename> - extension.</para> - - <para>For bitmaps, such as screen captures, use the Portable Network - Graphic format, and make sure that your images have the - <filename>.png</filename> extension.</para> - - <para>These are the <emphasis>only</emphasis> formats in which images - should be committed to the CVS repository.</para> - - <para>Use the right format for the right image. It is to be expected - that your documentation will have a mix of EPS and PNG images. The - <filename>Makefile</filename>s ensure that the correct format image - is chosen depending on the output format that you use for your - documentation. <emphasis>Do not commit the same image to the - repository in two different formats</emphasis>.</para> - - <important> - <para>It is anticipated that the Documentation Project will switch to - using the Scalable Vector Graphic (SVG) format for vector images. - However, the current state of SVG capable editing tools makes this - impractical.</para> - </important> - </sect3> - - <sect3> - <title>Markup</title> - - <para>The markup for an image is relatively simple. First, markup a - <sgmltag>mediaobject</sgmltag>. The <sgmltag>mediaobject</sgmltag> - can contain other, more specific objects. We are concerned with - two, the <sgmltag>imageobject</sgmltag> and the - <sgmltag>textobject</sgmltag>.</para> - - <para>You should include one <sgmltag>imageobject</sgmltag>, and two - <sgmltag>textobject</sgmltag> elements. The - <sgmltag>imageobject</sgmltag> will point to the name of the image - file that will be used (without the extension). The - <sgmltag>textobject</sgmltag> elements contain information that will - be presented to the user as well as, or instead of, the - image.</para> - - <para>There are two circumstances where this can happen.</para> - - <itemizedlist> - <listitem> - <para>When the reader is viewing the documentation in HTML. In - this case, each image will need to have associated alternate - text to show the user, typically whilst the image is loading, or - if they hover the mouse pointer over the image.</para> - </listitem> - - <listitem> - <para>When the reader is viewing the documentation in plain text. - In this case, each image should have an ASCII art equivalent to - show the user.</para> - </listitem> - </itemizedlist> - - <para>An example will probably make things easier to understand. - Suppose you have an image, called <filename>fig1</filename>, that - you want to include in the document. This image is of a rectangle - with an A inside it. The markup for this would be as - follows.</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="fig1"> <co id="co-image-ext"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ <co id="co-image-literal"> -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> <co id="co-image-phrase"> - </textobject> -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Include an <sgmltag>imagedata</sgmltag> element inside the - <sgmltag>imageobject</sgmltag> element. The - <literal>fileref</literal> attribute should contain the filename - of the image to include, without the extension. The stylesheets - will work out which extension should be added to the filename - automatically.</para> - </callout> - - <callout arearefs="co-image-literal"> - <para>The first <sgmltag>textobject</sgmltag> should contain a - <sgmltag>literallayout</sgmltag> element, where the - <literal>class</literal> attribute is set to - <literal>monospaced</literal>. This is your opportunity to - demonstrate your ASCII art skills. This content will be used if - the document is converted to plain text.</para> - - <para>Notice how the first and last lines of the content of the - <sgmltag>literallayout</sgmltag> element butt up next to the - element's tags. This ensures no extraneous white space is - included.</para> - </callout> - - <callout arearefs="co-image-phrase"> - <para>The second <sgmltag>textobject</sgmltag> should contain a - single <sgmltag>phrase</sgmltag> element. The contents of this - will become the <literal>alt</literal> attribute for the image - when this document is converted to HTML.</para> - </callout> - </calloutlist> - </sect3> - - <sect3> - <title><filename>Makefile</filename> entries</title> - - <para>Your images must be listed in the - <filename>Makefile</filename> in the <makevar>IMAGES</makevar> - variable. This variable should contain the name of all your - <emphasis>source</emphasis> images. For example, if you have - created three figures, <filename>fig1.eps</filename>, - <filename>fig2.png</filename>, <filename>fig3.png</filename>, then - your <filename>Makefile</filename> should have lines like this in - it.</para> - - <programlisting>… -IMAGES= fig1.eps fig2.png fig3.png -…</programlisting> - - <para>or</para> - - <programlisting>… -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -…</programlisting> - - <para>Again, the <filename>Makefile</filename> will work out the - complete list of images it needs to build your source document, you - only need to list the image files <emphasis>you</emphasis> - provided.</para> - </sect3> - - <sect3> - <title>Images and chapters in subdirectories</title> - - <para>You must be careful when you separate your documentation in to - smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in - different directories.</para> - - <para>Suppose you have a book with three chapters, and the chapters - are stored in their own directories, called - <filename>chapter1/chapter.sgml</filename>, - <filename>chapter2/chapter.sgml</filename>, and - <filename>chapter3/chapter.sgml</filename>. If each chapter has - images associated with it, I suggest you place those images in each - chapter's subdirectory (<filename>chapter1/</filename>, - <filename>chapter2/</filename>, and - <filename>chapter3/</filename>).</para> - - <para>However, if you do this you must include the directory names in - the <makevar>IMAGES</makevar> variable in the - <filename>Makefile</filename>, <emphasis>and</emphasis> you must - include the directory name in the <sgmltag>imagedata</sgmltag> - element in your document.</para> - - <para>For example, if you have <filename>chapter1/fig1.png</filename>, - then <filename>chapter1/chapter.sgml</filename> should - contain</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"> - </imageobject> - - … - -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-dir"> - <para>The directory name must be included in the - <literal>fileref</literal> attribute</para> - </callout> - </calloutlist> - - <para>The <filename>Makefile</filename> must contain</para> - - <programlisting>… -IMAGES= chapter1/fig1.png -…</programlisting> - - <para>Then everything should just work.</para> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other parts of the same document</title> - - <para>Linking within the same document requires you to to specify - where you are linking from (i.e., the text the user will click, or - otherwise indicate, as the source of the link) and where you are - linking to (the link's destination).</para> - - <para>Each element within DocBook has an attribute called - <literal>id</literal>. You can place text in this attribute to - uniquely name the element it is attached to.</para> - - <para>This value will be used when you specify the link - source.</para> - - <para>Normally, you will only be linking to chapters or sections, so - you would add the <literal>id</literal> attribute to these - elements.</para> - - <example> - <title><literal>id on chapters and sections</literal></title> - - <programlisting><![ CDATA [<chapter id="chapter1"> - <title>Introduction</title> - - <para>This is the introduction. It contains a subsection, - which is identified as well.</para> - - <sect1 id="chapter1-sect1"> - <title>Sub-sect 1</title> - - <para>This is the subsection.</para> - </sect1> -</chapter>]]></programlisting> - </example> - - <para>Obviously, you should use more descriptive values. The values - must be unique within the document (i.e., not just the file, but the - document the file might be included in as well). Notice how the - <literal>id</literal> for the subsection is constructed by appending - text to the <literal>id</literal> of the chapter. This helps to - ensure that they are unique.</para> - - <para>If you want to allow the user to jump into a specific portion of - the document (possibly in the middle of a paragraph or an example), - use <sgmltag>anchor</sgmltag>. This element has no content, but - takes an <literal>id</literal> attribute.</para> - - <example> - <title><sgmltag>anchor</sgmltag></title> - - <programlisting><![ CDATA [<para>This paragraph has an embedded - <anchor id="para1">link target in it. It won't show up in - the document.</para>]]></programlisting> - </example> - - <para>When you want to provide the user with a link they can activate - (probably by clicking) to go to a section of the document that has - an <literal>id</literal> attribute, you can use either - <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> - - <para>Both of these elements have a <literal>linkend</literal> - attribute. The value of this attribute should be the value that you - have used in a <literal>id</literal> attribute (it does not matter - if that value has not yet occurred in your document; this will work - for forward links as well as backward links).</para> - - <para>If you use <sgmltag>xref</sgmltag> then you have no control over - the text of the link. It will be generated for you.</para> - - <example> - <title>Using <sgmltag>xref</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example;</para> - - <programlisting><![ CDATA [<para>More information can be found - in <xref linkend="chapter1">.</para> - -<para>More specific information can be found - in <xref linkend="chapter1-sect1">.</para>]]></programlisting> - - <para>The text of the link will be generated automatically, and will - look like (<emphasis>emphasised</emphasis> text indicates the text - that will be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>Chapter - One</emphasis>.</para> - - <para>More specific information can be found in <emphasis>the - section called Sub-sect 1</emphasis>.</para> - </blockquote> - </example> - - <para>Notice how the text from the link is derived from the section - title or the chapter number.</para> - - <note> - <para>This means that you <emphasis>can not</emphasis> use - <sgmltag>xref</sgmltag> to link to an <literal>id</literal> - attribute on an <sgmltag>anchor</sgmltag> element. The - <sgmltag>anchor</sgmltag> has no content, so the - <sgmltag>xref</sgmltag> can not generate the text for the - link.</para> - </note> - - <para>If you want to control the text of the link then use - <sgmltag>link</sgmltag>. This element wraps content, and the - content will be used for the link.</para> - - <example> - <title>Using <sgmltag>link</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example.</para> - - <programlisting><![ CDATA [<para>More information can be found in - <link linkend="chapter1">the first chapter</link>.</para> - -<para>More specific information can be found in - <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting> - - <para>This will generate the following - (<emphasis>emphasised</emphasis> text indicates the text that will - be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>the first - chapter</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>this</emphasis> section.</para> - </blockquote> - </example> - - <note> - <para>That last one is a bad example. Never use words like - “this” or “here” as the source for the - link. The reader will need to hunt around the surrounding context - to see where the link is actually taking them.</para> - </note> - - <note> - <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to - include a link to an <literal>id</literal> on an - <sgmltag>anchor</sgmltag> element, since the - <sgmltag>link</sgmltag> content defines the text that will be used - for the link.</para> - </note> - </sect3> - - <sect3> - <title>Linking to documents on the WWW</title> - - <para>Linking to external documents is much simpler, as long as you - know the URL of the document you want to link to. Use - <sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is - the URL of the page that the link points to, and the content of the - element is the text that will be displayed for the user to - activate.</para> - - <example> - <title><sgmltag>ulink</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>Of course, you could stop reading this document and - go to the <ulink url="http://www.FreeBSD.org/">FreeBSD - home page</ulink> instead.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Of course, you could stop reading this document and go to the - <ulink url="http://www.FreeBSD.org/">FreeBSD home page</ulink> - instead.</para> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>* LinuxDoc</title> - - <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - <ulink url="http://www.linuxdoc.org/">Linux Documentation - Project</ulink>, and subsequently adopted by the FreeBSD Documentation - Project.</para> - - <para>The LinuxDoc DTD contains primarily appearance related markup rather - than content related markup (i.e., it describes what something looks - like rather than what it is).</para> - - <para>Both the FreeBSD Documentation Project and the Linux Documentation - Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> - - <para>The LinuxDoc DTD is available from the ports collection in the - <filename>textproc/linuxdoc</filename> category.</para> - </sect1> -</chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml deleted file mode 100644 index 3cb5589b31..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ /dev/null @@ -1,1583 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml,v 1.14 2000/10/31 19:36:16 nik Exp $ ---> - -<chapter id="sgml-primer"> - <title>SGML Primer</title> - - <para>The majority of FDP documentation is written in applications of - SGML. This chapter explains exactly what that means, how to read - and understand the source to the documentation, and the sort of SGML - tricks you will see used in the documentation.</para> - - <para>Portions of this section were inspired by Mark Galassi's <ulink - url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> - - <sect1> - <title>Overview</title> - - <para>Way back when, electronic text was simple to deal with. Admittedly, - you had to know which character set your document was written in (ASCII, - EBCDIC, or one of a number of others) but that was about it. Text was - text, and what you saw really was what you got. No frills, no - formatting, no intelligence.</para> - - <para>Inevitably, this was not enough. Once you have text in a - machine-usable format, you expect machines to be able to use it and - manipulate it intelligently. You would like to indicate that certain - phrases should be emphasised, or added to a glossary, or be hyperlinks. - You might want filenames to be shown in a “typewriter” style - font for viewing on screen, but as “italics” when printed, - or any of a myriad of other options for presentation.</para> - - <para>It was once hoped that Artificial Intelligence (AI) would make this - easy. Your computer would read in the document and automatically - identify key phrases, filenames, text that the reader should type in, - examples, and more. Unfortunately, real life has not happened quite - like that, and our computers require some assistance before they can - meaningfully process our text.</para> - - <para>More precisely, they need help identifying what is what. You or I - can look at - - <blockquote> - <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - - <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> - </blockquote> - - and easily see which parts are filenames, which are commands to be typed - in, which parts are references to manual pages, and so on. But the - computer processing the document can not. For this we need - markup.</para> - - <para>“Markup” is commonly used to describe “adding - value” or “increasing cost”. The term takes on both - these meanings when applied to text. Markup is additional text included - in the document, distinguished from the document's content in some way, - so that programs that process the document can read the markup and use - it when making decisions about the document. Editors can hide the - markup from the user, so the user is not distracted by it.</para> - - <para>The extra information stored in the markup <emphasis>adds - value</emphasis> to the document. Adding the markup to the document - must typically be done by a person—after all, if computers could - recognise the text sufficiently well to add the markup then there would - be no need to add it in the first place. This <emphasis>increases the - cost</emphasis> (i.e., the effort required) to create the - document.</para> - - <para>The previous example is actually represented in this document like - this;</para> - - <programlisting><![ CDATA [ -<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - -<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> - - <para>As you can see, the markup is clearly separate from the - content.</para> - - <para>Obviously, if you are going to use markup you need to define what - your markup means, and how it should be interpreted. You will need a - markup language that you can follow when marking up your - documents.</para> - - <para>Of course, one markup language might not be enough. A markup - language for technical documentation has very different requirements - than a markup language that was to be used for cookery recipes. This, - in turn, would be very different from a markup language used to describe - poetry. What you really need is a first language that you use to write - these other markup languages. A <emphasis>meta markup - language</emphasis>.</para> - - <para>This is exactly what the Standard Generalised Markup Language (SGML) - is. Many markup languages have been written in SGML, including the two - most used by the FDP, HTML and DocBook.</para> - - <para>Each language definition is more properly called a Document Type - Definition (DTD). The DTD specifies the name of the elements that can - be used, what order they appear in (and whether some markup can be used - inside other markup) and related information. A DTD is sometimes - referred to as an <emphasis>application</emphasis> of SGML.</para> - - <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> - specification of all the elements that are allowed to appear, the order - in which they should appear, which elements are mandatory, which are - optional, and so forth. This makes it possible to write an SGML - <emphasis>parser</emphasis> which reads in both the DTD and a document - which claims to conform to the DTD. The parser can then confirm whether - or not all the elements required by the DTD are in the document in the - right order, and whether there are any errors in the markup. This is - normally referred to as <quote>validating the document</quote>.</para> - - <note> - <para>This processing simply confirms that the choice of elements, their - ordering, and so on, conforms to that listed in the DTD. It does - <emphasis>not</emphasis> check that you have used - <emphasis>appropriate</emphasis> markup for the content. If you were - to try and mark up all the filenames in your document as function - names, the parser would not flag this as an error (assuming, of - course, that your DTD defines elements for filenames and functions, - and that they are allowed to appear in the same place).</para> - </note> - - <para>It is likely that most of your contributions to the Documentation - Project will consist of content marked up in either HTML or DocBook, - rather than alterations to the DTDs. For this reason this book will - not touch on how to write a DTD.</para> - </sect1> - - <sect1 id="sgml-primer-elements"> - <title>Elements, tags, and attributes</title> - - <para>All the DTDs written in SGML share certain characteristics. This is - hardly surprising, as the philosophy behind SGML will inevitably show - through. One of the most obvious manifestations of this philisophy is - that of <emphasis>content</emphasis> and - <emphasis>elements</emphasis>.</para> - - <para>Your documentation (whether it is a single web page, or a lengthy - book) is considered to consist of content. This content is then divided - (and further subdivided) into elements. The purpose of adding markup is - to name and identify the boundaries of these elements for further - processing.</para> - - <para>For example, consider a typical book. At the very top level, the - book is itself an element. This “book” element obviously - contains chapters, which can be considered to be elements in their own - right. Each chapter will contain more elements, such as paragraphs, - quotations, and footnotes. Each paragraph might contain further - elements, identifying content that was direct speech, or the name of a - character in the story.</para> - - <para>You might like to think of this as “chunking” content. - At the very top level you have one chunk, the book. Look a little - deeper, and you have more chunks, the individual chapters. These are - chunked further into paragraphs, footnotes, character names, and so - on.</para> - - <para>Notice how you can make this differentation between different - elements of the content without resorting to any SGML terms. It really - is surprisingly straightforward. You could do this with a highlighter - pen and a printout of the book, using different colours to indicate - different chunks of content.</para> - - <para>Of course, we do not have an electronic highlighter pen, so we need - some other way of indicating which element each piece of content belongs - to. In languages written in SGML (HTML, DocBook, et al) this is done by - means of <emphasis>tags</emphasis>.</para> - - <para>A tag is used to identify where a particular element starts, and - where the element ends. <emphasis>The tag is not part of the element - itself</emphasis>. Because each DTD was normally written to mark up - specific types of information, each one will recognise different - elements, and will therefore have different names for the tags.</para> - - <para>For an element called <replaceable>element-name</replaceable> the - start tag will normally look like - <literal><<replaceable>element-name</replaceable>></literal>. The - corresponding closing tag for this element is - <literal></<replaceable>element-name</replaceable>></literal>.</para> - - <example> - <title>Using an element (start and end tags)</title> - - <para>HTML has an element for indicating that the content enclosed by - the element is a paragraph, called <literal>p</literal>. This - element has both start and end tags.</para> - - <programlisting> -<![ CDATA [<p>This is a paragraph. It starts with the start tag for - the 'p' element, and it will end with the end tag for the 'p' - element.</p> - -<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> - </example> - - <para>Not all elements require an end tag. Some elements have no content. - For example, in HTML you can indicate that you want a horizontal line to - appear in the document. Obviously, this line has no content, so just - the start tag is required for this element.</para> - - <example> - <title>Using an element (start tag only)</title> - - <para>HTML has an element for indicating a horizontal rule, called - <literal>hr</literal>. This element does not wrap content, so only - has a start tag.</para> - - <programlisting> -<![ CDATA [<p>This is a paragraph.</p> - -<hr> - -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> - </example> - - <para>If it is not obvious by now, elements can contain other elements. - In the book example earlier, the book element contained all the chapter - elements, which in turn contained all the paragraph elements, and so - on.</para> - - <example> - <title>Elements within elements; <sgmltag>em</sgmltag></title> - - <programlisting> -<![ CDATA [<p>This is a simple <em>paragraph</em> where some - of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> - </example> - - <para>The DTD will specify the rules detailing which elements can contain - other elements, and exactly what they can contain.</para> - - <important> - <para>People often confuse the terms tags and elements, and use the - terms as if they were interchangeable. They are not.</para> - - <para>An element is a conceptual part of your document. An element has - a defined start and end. The tags mark where the element starts and - end.</para> - - <para>When this document (or anyone else knowledgable about SGML) refers - to “the <p> tag” they mean the literal text - consisting of the three characters <literal><</literal>, - <literal>p</literal>, and <literal>></literal>. But the phrase - “the <p> element” refers to the whole - element.</para> - - <para>This distinction <emphasis>is</emphasis> very subtle. But keep it - in mind.</para> - </important> - - <para>Elements can have attributes. An attribute has a name and a value, - and is used for adding extra information to the element. This might be - information that indicates how the content should be rendered, or might - be something that uniquely identifies that occurence of the element, or - it might be something else.</para> - - <para>An element's attributes are written <emphasis>inside</emphasis> the - start tag for that element, and take the form - <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> - - <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> - element has an attribute called <literal>align</literal>, which suggests - an alignment (justification) for the paragraph to the program displaying - the HTML.</para> - - <para>The <literal>align</literal> attribute can take one of four defined - values, <literal>left</literal>, <literal>center</literal>, - <literal>right</literal> and <literal>justify</literal>. If the - attribute is not specified then the default is - <literal>left</literal>.</para> - - <example> - <title>Using an element with an attribute</title> - - <programlisting> -<![ CDATA [<p align="left">The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.</p> - -<p align="center">This may appear in the center.</p>]]></programlisting> - </example> - - <para>Some attributes will only take specific values, such as - <literal>left</literal> or <literal>justify</literal>. Others will - allow you to enter anything you want. If you need to include quotes - (<literal>"</literal>) within an attribute then use single quotes around - the attribute value.</para> - - <example> - <title>Single quotes around attributes</title> - - <programlisting> -<![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> - </example> - - <para>Sometimes you do not need to use quotes around attribute values at - all. However, the rules for doing this are subtle, and it is far - simpler just to <emphasis>always</emphasis> quote your attribute - values.</para> - - <sect2> - <title>For you to do…</title> - - <para>In order to run the examples in this document you will need to - install some software on your system and ensure that an environment - variable is set correctly.</para> - - <procedure> - <step> - <para>Download and install <filename>textproc/docproj</filename> - from the FreeBSD ports system. This is a - <emphasis>meta-port</emphasis> that should download and install - all of the programs and supporting files that are used by the - Documentation Project.</para> - </step> - - <step> - <para>Add lines to your shell startup files to set - <envar>SGML_CATALOG_FILES</envar>.</para> - - <example id="sgml-primer-envars"> - <title><filename>.profile</filename>, for &man.sh.1; and - &man.bash.1; users</title> - - <programlisting> -SGML_ROOT=/usr/local/share/sgml -SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog -SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES -export SGML_CATALOG_FILES</programlisting> - </example> - - <example> - <title><filename>.login</filename>, for &man.csh.1; and - &man.tcsh.1; users</title> - - <programlisting> -setenv SGML_ROOT /usr/local/share/sgml -setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog -setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</programlisting> - </example> - - <para>Then either log out, and log back in again, or run those - commands from the command line to set the variable values.</para> - </step> - </procedure> - - <procedure> - <step> - <para>Create <filename>example.sgml</filename>, and enter the - following text;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Try and validate this file using an SGML parser.</para> - - <para>Part of <filename>textproc/docproj</filename> is the - &man.nsgmls.1; <link linkend="sgml-primer-validating">validating - parser</link>. Normally, &man.nsgmls.1; reads in a document - marked up according to an SGML DTD and returns a copy of the - document's Element Structure Information Set (ESIS, but that is - not important right now).</para> - - <para>However, when &man.nsgmls.1; is given the <option>-s</option> - parameter, &man.nsgmls.1; will suppress its normal output, and - just print error messages. This makes it a useful way to check to - see if your document is valid or not.</para> - - <para>Use &man.nsgmls.1; to check that your document is - valid;</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> - - <para>As you will see, &man.nsgmls.1; returns without displaying any - output. This means that your document validated - successfully.</para> - </step> - - <step> - <para>See what happens when required elements are omitted. Try - removing the <sgmltag>title</sgmltag> and - <sgmltag>/title</sgmltag> tags, and re-run the validation.</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> -nsgmls:example.sgml:5:4:E: character data is not allowed here -nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> - - <para>The error output from &man.nsgmls.1; is organised into - colon-separated groups, or columns.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Column</entry> - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>The name of the program generating the error. This - will always be <literal>nsgmls</literal>.</entry> - </row> - - <row> - <entry>2</entry> - <entry>The name of the file that contains the error.</entry> - </row> - - <row> - <entry>3</entry> - <entry>Line number where the error appears.</entry> - </row> - - <row> - <entry>4</entry> - <entry>Column number where the error appears.</entry> - </row> - - <row> - <entry>5</entry> - <entry>A one letter code indicating the nature of the - message. <literal>I</literal> indicates an informational - message, <literal>W</literal> is for warnings, and - <literal>E</literal> is for errors<footnote> - <para>It is not always the fifth column either. - <command>nsgmls -sv</command> displays - <literal>nsgmls:I: SP version "1.3"</literal> - (depending on the installed version). As you can see, - this is an informational message.</para> - </footnote>, and <literal>X</literal> is for - cross-references. As you can see, these messages are - errors.</entry> - </row> - - <row> - <entry>6</entry> - <entry>The text of the error message.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Simply omitting the <sgmltag>title</sgmltag> tags has - generated 2 different errors.</para> - - <para>The first error indicates that content (in this case, - characters, rather than the start tag for an element) has occured - where the SGML parser was expecting something else. In this case, - the parser was expecting to see one of the start tags for elements - that are valid inside <sgmltag>head</sgmltag> (such as - <sgmltag>title</sgmltag>).</para> - - <para>The second error is because <sgmltag>head</sgmltag> elements - <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> - element. Because it does not &man.nsgmls.1; considers that the - element has not been properly finished. However, the closing tag - indicates that the element has been closed before it has been - finished.</para> - </step> - - <step> - <para>Put the <literal>title</literal> element back in.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 id="sgml-primer-doctype-declaration"> - <title>The DOCTYPE declaration</title> - - <para>The beginning of each document that you write must specify the name - of the DTD that the document conforms to. This is so that SGML parsers - can determine the DTD and ensure that the document does conform to - it.</para> - - <para>This information is generally expressed on one line, in the DOCTYPE - declaration.</para> - - <para>A typical declaration for a document written to conform with version - 4.0 of the HTML DTD looks like this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> - - <para>That line contains a number of different components.</para> - - <variablelist> - <varlistentry> - <term><literal><!</literal></term> - - <listitem> - <para>Is the <emphasis>indicator</emphasis> that indicates that this - is an SGML declaration. This line is declaring the document type. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>DOCTYPE</literal></term> - - <listitem> - <para>Shows that this is an SGML declaration for the document - type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>html</literal></term> - - <listitem> - <para>Names the first <link linkend="sgml-primer-elements">element</link> that - will appear in the document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> - - <listitem> - <para>Lists the Formal Public Identifier (FPI) for the DTD that this - document conforms to. Your SGML parser will use this to find the - correct DTD when processing this document.</para> - - <para><literal>PUBLIC</literal> is not a part of the FPI, but - indicates to the SGML processor how to find the DTD referenced in - the FPI. Other ways of telling the SGML parser how to find the - DTD are shown <link - linkend="sgml-primer-fpi-alternatives">later</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>></literal></term> - - <listitem> - <para>Returns to the document.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Formal Public Identifiers (FPIs)</title> - - <note> - <para>You don't need to know this, but it's useful background, and - might help you debug problems when your SGML processor can't locate - the DTD you are using.</para> - </note> - - <para>FPIs must follow a specific syntax. This syntax is as - follows;</para> - - <programlisting> -"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> - - <variablelist> - <varlistentry> - <term><replaceable>Owner</replaceable></term> - - <listitem> - <para>This indicates the owner of the FPI.</para> - - <para>If this string starts with “ISO” then this is an - ISO owned FPI. For example, the FPI <literal>"ISO - 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists - <literal>ISO 8879:1986</literal> as being the owner for the set - of entities for greek symbols. ISO 8879:1986 is the ISO number - for the SGML standard.</para> - - <para>Otherwise, this string will either look like - <literal>-//<replaceable>Owner</replaceable></literal> or - <literal>+//<replaceable>Owner</replaceable></literal> (notice - the only difference is the leading <literal>+</literal> or - <literal>-</literal>).</para> - - <para>If the string starts with <literal>-</literal> then the - owner information is unregistered, with a <literal>+</literal> - it identifies it as being registered.</para> - - <para>ISO 9070:1991 defines how registered names are generated; it - might be derived from the number of an ISO publication, an ISBN - code, or an organisation code assigned according to ISO 6523. - In addition, a registration authority could be created in order - to assign registered names. The ISO council delegated this to - the American National Standards Institute (ANSI).</para> - - <para>Because the FreeBSD Project hasn't been registered the - owner string is <literal>-//FreeBSD</literal>. And as you can - see, the W3C are not a registered owner either.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Keyword</replaceable></term> - - <listitem> - <para>There are several keywords that indicate the type of - information in the file. Some of the most common keywords are - <literal>DTD</literal>, <literal>ELEMENT</literal>, - <literal>ENTITIES</literal>, and <literal>TEXT</literal>. - <literal>DTD</literal> is used only for DTD files, - <literal>ELEMENT</literal> is usually used for DTD fragments - that contain only entity or element declarations. - <literal>TEXT</literal> is used for SGML content (text and - tags).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Description</replaceable></term> - - <listitem> - <para>Any description you want to supply for the contents of this - file. This may include version numbers or any short text that - is meaningful to you and unique for the SGML system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Language</replaceable></term> - - <listitem> - <para>This is an ISO two-character code that identifies the native - language for the file. <literal>EN</literal> is used for - English.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title><filename>catalog</filename> files</title> - - <para>If you use the syntax above and try and process this document - using an SGML processor, the processor will need to have some way of - turning the FPI into the name of the file on your computer that - contains the DTD.</para> - - <para>In order to do this it can use a catalog file. A catalog file - (typically called <filename>catalog</filename>) contains lines that - map FPIs to filenames. For example, if the catalog file contained - the line;</para> - - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> - - <para>The SGML processor would know to look up the DTD from - <filename>strict.dtd</filename> in the <filename>4.0</filename> - subdirectory of whichever directory held the - <filename>catalog</filename> file that contained that line.</para> - - <para>Look at the contents of - <filename>/usr/local/share/sgml/html/catalog</filename>. This is - the catalog file for the HTML DTDs that will have been installed as - part of the <filename>textproc/docproj</filename> port.</para> - </sect3> - - <sect3> - <title><envar>SGML_CATALOG_FILES</envar></title> - - <para>In order to locate a <filename>catalog</filename> file, your - SGML processor will need to know where to look. Many of them - feature command line parameters for specifying the path to one or - more catalogs.</para> - - <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to - point to the files. This environment variable should consist of a - colon-separated list of catalog files (including their full - path).</para> - - <para>Typically, you will want to include the following files;</para> - - <itemizedlist> - <listitem> - <para><filename>/usr/local/share/sgml/docbook/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/html/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> - </listitem> - </itemizedlist> - - <para>You should <link linkend="sgml-primer-envars">already have done - this</link>.</para> - </sect3> - </sect2> - - <sect2 id="sgml-primer-fpi-alternatives"> - <title>Alternatives to FPIs</title> - - <para>Instead of using an FPI to indicate the DTD that the document - conforms to (and therefore, which file on the system contains the DTD) - you can explicitly specify the name of the file.</para> - - <para>The syntax for this is slightly different:</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> - - <para>The <literal>SYSTEM</literal> keyword indicates that the SGML - processor should locate the DTD in a system specific fashion. This - typically (but not always) means the DTD will be provided as a - filename.</para> - - <para>Using FPIs is preferred for reasons of portability. You don't - want to have to ship a copy of the DTD around with your document, and - if you used the <literal>SYSTEM</literal> identifier then everyone - would need to keep their DTDs in the same place.</para> - </sect2> - </sect1> - - <sect1 id="sgml-primer-sgml-escape"> - <title>Escaping back to SGML</title> - - <para>Earlier in this primer I said that SGML is only used when writing a - DTD. This is not strictly true. There is certain SGML syntax that you - will want to be able to use within your documents. For example, - comments can be included in your document, and will be ignored by the - parser. Comments are entered using SGML syntax. Other uses for SGML - syntax in your document will be shown later too.</para> - - <para>Obviously, you need some way of indicating to the SGML processor - that the following content is not elements within the document, but is - SGML that the parser should act upon.</para> - - <para>These sections are marked by <literal><! ... ></literal> in - your document. Everything between these delimiters is SGML syntax as - you might find within a DTD.</para> - - <para>As you may just have realised, the <link - linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> - is an example of SGML syntax that you need to include in your - document…</para> - </sect1> - - <sect1> - <title>Comments</title> - - <para>Comments are an SGML construction, and are normally only valid - inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> - shows, it is possible to use SGML syntax within your document.</para> - - <para>The delimiter for SGML comments is the string - “<literal>--</literal>”. The first occurence of this string - opens a comment, and the second closes it.</para> - - <example> - <title>SGML generic comment</title> - - <programlisting> -<!-- test comment --></programlisting> - - <programlisting><![ CDATA [ -<!-- This is inside the comment --> - -<!-- This is another comment --> - -<!-- This is one way - of doing multiline comments --> - -<!-- This is another way of -- - -- doing multiline comments -->]]></programlisting> - </example> - - <![ %output.print; [ - <important> - <title>Use 2 dashes</title> - - <para>There is a problem with producing the Postscript and PDF versions - of this document. The above example probably shows just one hyphen - symbol, <literal>-</literal> after the <literal><!</literal> and - before the <literal>></literal>.</para> - - <para>You <emphasis>must</emphasis> use two <literal>-</literal>, - <emphasis>not</emphasis> one. The Postscript and PDF versions have - translated the two <literal>-</literal> in the original to a longer, - more professional <emphasis>em-dash</emphasis>, and broken this - example in the process.</para> - - <para>The HTML, plain text, and RTF versions of this document are not - affected.</para> - </important> - ]]> - - <para>If you have used HTML before you may have been shown different rules - for comments. In particular, you may think that the string - <literal><!--</literal> opens a comment, and it is only closed by - <literal>--></literal>.</para> - - <para>This is <emphasis>not</emphasis> the case. A lot of web browsers - have broken HTML parsers, and will accept that as valid. However, the - SGML parsers used by the Documentation Project are much stricter, and - will reject documents that make that error.</para> - - <example> - <title>Errorneous SGML comments</title> - - <programlisting><![ CDATA [ -<!-- This is in the comment -- - - THIS IS OUTSIDE THE COMMENT! - - -- back inside the comment -->]]></programlisting> - - <para>The SGML parser will treat this as though it were actually;</para> - - <programlisting> -<!THIS IS OUTSIDE THE COMMENT></programlisting> - - <para>This is not valid SGML, and may give confusing error - messages.</para> - - <programlisting> -<![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> - - <para>As the example suggests, <emphasis>do not</emphasis> write - comments like that.</para> - - <programlisting> -<![ CDATA [<!--===================================================-->]]></programlisting> - - <para>That is a (slightly) better approach, but it still potentially - confusing to people new to SGML.</para> - </example> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add some comments to <filename>example.sgml</filename>, and - check that the file still validates using &man.nsgmls.1;</para> - </step> - - <step> - <para>Add some invalid comments to - <filename>example.sgml</filename>, and see the error messages that - &man.nsgmls.1; gives when it encounters an invalid comment.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Entities</title> - - <para>Entities are a mechanism for assigning names to chunks of content. - As an SGML parser processes your document, any entities it finds are - replaced by the content of the entity.</para> - - <para>This is a good way to have re-usable, easily changeable chunks of - content in your SGML documents. It is also the only way to include one - marked up file inside another using SGML.</para> - - <para>There are two types of entities which can be used in two different - situations; <emphasis>general entities</emphasis> and - <emphasis>parameter entities</emphasis>.</para> - - <sect2 id="sgml-primer-general-entities"> - <title>General Entities</title> - - <para>You can not use general entities in an SGML context (although you - define them in one). They can only be used in your document. - Contrast this with <link - linkend="sgml-primer-parameter-entities">parameter - entities</link>.</para> - - <para>Each general entity has a name. When you want to reference a - general entity (and therefore include whatever text it represents in - your document), you write - <literal>&<replaceable>entity-name</replaceable>;</literal>. For - example, suppose you had an entity called - <literal>current.version</literal> which expanded to the current - version number of your product. You could write;</para> - - <programlisting> -<![ CDATA [<para>The current version of our product is - ¤t.version;.</para>]]></programlisting> - - <para>When the version number changes you can simply change the - definition of the value of the general entity and reprocess your - document.</para> - - <para>You can also use general entities to enter characters that you - could not otherwise include in an SGML document. For example, < - and & can not normally appear in an SGML document. When the SGML - parser sees the < symbol it assumes that a tag (either a start tag - or an end tag) is about to appear, and when it sees the & symbol - it assumes the next text will be the name of an entity.</para> - - <para>Fortunately, you can use the two general entities &lt; and - &amp; whenever you need to include one or other of these </para> - - <para>A general entity can only be defined within an SGML context. - Typically, this is done immediately after the DOCTYPE - declaration.</para> - - <example> - <title>Defining general entities</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY current.version "3.0-RELEASE"> -<!ENTITY last.version "2.2.7-RELEASE"> -]>]]></programlisting> - - <para>Notice how the DOCTYPE declaration has been extended by adding a - square bracket at the end of the first line. The two entities are - then defined over the next two lines, before the square bracket is - closed, and then the DOCTYPE declaration is closed.</para> - - <para>The square brackets are necessary to indicate that we are - extending the DTD indicated by the DOCTYPE declaration.</para> - </example> - </sect2> - - <sect2 id="sgml-primer-parameter-entities"> - <title>Parameter entities</title> - - <para>Like <link linkend="sgml-primer-general-entities">general - entities</link>, parameter entities are used to assign names to - reusable chunks of text. However, where as general entities can only - be used within your document, parameter entities can only be used - within an <link linkend="sgml-primer-sgml-escape">SGML - context</link>.</para> - - <para>Parameter entities are defined in a similar way to general - entities. However, instead of using - <literal>&<replaceable>entity-name</replaceable>;</literal> to - refer to them, use - <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> - <para><emphasis>P</emphasis>arameter entities use the - <emphasis>P</emphasis>ercent symbol.</para> - </footnote>. The definition also includes the <literal>%</literal> - between the <literal>ENTITY</literal> keyword and the name of the - entity.</para> - - <example> - <title>Defining parameter entities</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % param.some "some"> -<!ENTITY % param.text "text"> -<!ENTITY % param.new "%param.some more %param.text"> - -<!-- %param.new now contains "some more text" --> -]>]]></programlisting> - </example> - - <para>This may not seem particularly useful. It will be.</para> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add a general entity to - <filename>example.sgml</filename>.</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ -<!ENTITY version "1.1"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <!-- You might well have some comments in here as well --> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - - <p>The current version of this document is: &version;</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Validate the document using &man.nsgmls.1;</para> - </step> - - <step> - <para>Load <filename>example.sgml</filename> into your web browser - (you may need to copy it to <filename>example.html</filename> - before your browser recognises it as an HTML document).</para> - - <para>Unless your browser is very advanced, you won't see the entity - reference <literal>&version;</literal> replaced with the - version number. Most web browsers have very simplistic parsers - which do not handle proper SGML<footnote> - <para>This is a shame. Imagine all the problems and hacks (such - as Server Side Includes) that could be avoided if they - did.</para> - </footnote>.</para> - </step> - - <step> - <para>The solution is to <emphasis>normalise</emphasis> your - document using an SGML normaliser. The normaliser reads in valid - SGML and outputs equally valid SGML which has been transformed in - some way. One of the ways in which the normaliser transforms the - SGML is to expand all the entity references in the document, - replacing the entities with the text that they represent.</para> - - <para>You can use &man.sgmlnorm.1; to do this.</para> - - <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> - - <para>You should find a normalised (i.e., entity references - expanded) copy of your document in - <filename>example.html</filename>, ready to load into your web - browser.</para> - </step> - - <step> - <para>If you look at the output from &man.sgmlnorm.1; you will see - that it does not include a DOCTYPE declaration at the start. To - include this you need to use the <option>-d</option> - option;</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Using entities to include files</title> - - <para>Entities (both <link - linkend="sgml-primer-general-entities">general</link> and <link - linkend="sgml-primer-parameter-entities">parameter</link>) are - particularly useful when used to include one file inside another.</para> - - <sect2 id="sgml-primer-include-using-gen-entities"> - <title>Using general entities to include files</title> - - <para>Suppose you have some content for an SGML book organised into - files, one file per chapter, called - <filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so forth, with a - <filename>book.sgml</filename> file that will contain these - chapters.</para> - - <para>In order to use the contents of these files as the values for your - entities, you declare them with the <literal>SYSTEM</literal> keyword. - This directs the SGML parser to use the contents of the named file as - the value of the entity.</para> - - <example> - <title>Using general entities to include files</title> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml"> -<!-- And so forth --> -]> - -<html> - <!-- Use the entities to load in the chapters --> - - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - - <warning> - <para>When using general entities to include other files within a - document, the files being included - (<filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so on) <emphasis>must - not</emphasis> start with a DOCTYPE declaration. This is a syntax - error.</para> - </warning> - </sect2> - - <sect2> - <title>Using parameter entities to include files</title> - - <para>Recall that parameter entities can only be used inside an SGML - context. Why then would you want to include a file within an SGML - context?</para> - - <para>You can use this to ensure that you can reuse your general - entities.</para> - - <para>Suppose that you had many chapters in your document, and you - reused these chapters in two different books, each book organising the - chapters in a different fashion.</para> - - <para>You could list the entities at the top of each book, but this - quickly becomes cumbersome to manage.</para> - - <para>Instead, place the general entity definitions inside one file, - and use a parameter entity to include that file within your - document.</para> - - <example> - <title>Using parameter entities to include files</title> - - <para>First, place your entity definitions in a separate file, called - <filename>chapters.ent</filename>. This file contains the - following;</para> - - <programlisting> -<![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> - - <para>Now create a parameter entity to refer to the contents of the - file. Then use the parameter entity to load the file into the - document, which will then make all the general entities available - for use. Then use the general entities as before;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!-- Define a parameter entity to load in the chapter general entities --> -<!ENTITY % chapters SYSTEM "chapters.ent"> - -<!-- Now use the parameter entity to load in this file --> -%chapters; -]> - -<html> - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - </sect2> - - <sect2> - <title>For you to do…</title> - - <sect3> - <title>Use general entities to include files</title> - - <procedure> - <step> - <para>Create three files, <filename>para1.sgml</filename>, - <filename>para2.sgml</filename>, and - <filename>para3.sgml</filename>.</para> - - <para>Put content similar to the following in each file;</para> - - <programlisting> -<![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> - </step> - - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Use parameter entities to include files</title> - - <note> - <para>You must have taken the previous steps first.</para> - </note> - - <procedure> - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting> -<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % entities SYSTEM "entities.sgml"> %entities; -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Create a new file, <filename>entities.sgml</filename>, with - this content:</para> - - <programlisting> -<![ CDATA [<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 id="sgml-primer-marked-sections"> - <title>Marked sections</title> - - <para>SGML provides a mechanism to indicate that particular pieces of the - document should be processed in a special way. These are termed - “marked sections”.</para> - - <example> - <title>Structure of a marked section</title> - - <programlisting> -<![ <replaceable>KEYWORD</replaceable> [ - Contents of marked section -]]></programlisting> - </example> - - <para>As you would expect, being an SGML construct, a marked section - starts with <literal><!</literal>.</para> - - <para>The first square bracket begins to delimit the marked - section.</para> - - <para><replaceable>KEYWORD</replaceable> describes how this marked - section should be processed by the parser.</para> - - <para>The second square bracket indicates that the content of the marked - section starts here.</para> - - <para>The marked section is finished by closing the two square brackets, - and then returning to the document context from the SGML context with - <literal>></literal></para> - - <sect2> - <title>Marked section keywords</title> - - <sect3> - <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> - - <para>These keywords denote the marked sections <emphasis>content - model</emphasis>, and allow you to change it from the - default.</para> - - <para>When an SGML parser is processing a document it keeps track - of what is called the “content model”.</para> - - <para>Briefly, the content model describes what sort of content the - parser is expecting to see, and what it will do with it when it - finds it.</para> - - <para>The two content models you will probably find most useful are - <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> - - <para><literal>CDATA</literal> is for “Character Data”. - If the parser is in this content model then it is expecting to see - characters, and characters only. In this model the < and & - symbols lose their special status, and will be treated as ordinary - characters.</para> - - <para><literal>RCDATA</literal> is for “Entity references and - character data” If the parser is in this content model then it - is expecting to see characters <emphasis>and</emphasis> entities. - < loses its special status, but & will still be treated as - starting the beginning of a general entity.</para> - - <para>This is particularly useful if you are including some verbatim - text that contains lots of < and & characters. While you - could go through the text ensuring that every < is converted to a - &lt; and every & is converted to a &amp;, it can be - easier to mark the section as only containing CDATA. When the SGML - parser encounters this it will ignore the < and & symbols - embedded in the content.</para> - - <!-- The nesting of CDATA within the next example is disgusting --> - - <example> - <title>Using a CDATA marked section</title> - - <programlisting> -<para>Here is an example of how you would include some text - that contained many &lt; and &amp; symbols. The sample - text is a fragment of HTML. The surrounding text (<para> and - <programlisting>) are from DocBook.</para> - -<programlisting> - <![ CDATA [ <![ CDATA [ - <p>This is a sample that shows you some of the elements within - HTML. Since the angle brackets are used so many times, it's - simpler to say the whole example is a CDATA marked section - than to use the entity names for the left and right angle - brackets throughout.</p> - - <ul> - <li>This is a listitem</li> - <li>This is a second listitem</li> - <li>This is a third listitem</li> - </ul> - - <p>This is the end of the example.</p>]]> - ]]> -</programlisting></programlisting> - - <para>If you look at the source for this document you will see this - technique used throughout.</para> - </example> - </sect3> - - <sect3> - <title><literal>INCLUDE</literal> and - <literal>IGNORE</literal></title> - - <para>If the keyword is <literal>INCLUDE</literal> then the contents - of the marked section will be processed. If the keyword is - <literal>IGNORE</literal> then the marked section is ignored and - will not be processed. It will not appear in the output.</para> - - <example> - <title>Using <literal>INCLUDE</literal> and - <literal>IGNORE</literal> in marked sections</title> - - <programlisting> -<![ INCLUDE [ - This text will be processed and included. -]]> - -<![ IGNORE [ - This text will not be processed or included. -]]></programlisting> - </example> - - <para>By itself, this isn't too useful. If you wanted to remove text - from your document you could cut it out, or wrap it in - comments.</para> - - <para>It becomes more useful when you realise you can use <link - linkend="sgml-primer-parameter-entities">parameter entities</link> - to control this. Remember that parameter entities can only be used - in SGML contexts, and the keyword of a marked section - <emphasis>is</emphasis> an SGML context.</para> - - <para>For example, suppose that you produced a hard-copy version of - some documentation and an electronic version. In the electronic - version you wanted to include some extra content that wasn't to - appear in the hard-copy.</para> - - <para>Create a parameter entity, and set it's value to - <literal>INCLUDE</literal>. Write your document, using marked - sections to delimit content that should only appear in the - electronic version. In these marked sections use the parameter - entity in place of the keyword.</para> - - <para>When you want to produce the hard-copy version of the document, - change the parameter entity's value to <literal>IGNORE</literal> and - reprocess the document.</para> - - <example> - <title>Using a parameter entity to control a marked - section</title> - - <programlisting> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % electronic.copy "INCLUDE"> -]]> - -... - -<![ %electronic.copy [ - This content should only appear in the electronic - version of the document. -]]></programlisting> - - <para>When producing the hard-copy version, change the entity's - definition to;</para> - - <programlisting> -<!ENTITY % electronic.copy "IGNORE"></programlisting> - - <para>On reprocessing the document, the marked sections that use - <literal>%electronic.copy</literal> as their keyword will be - ignored.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Create a new file, <filename>section.sgml</filename>, that - contains the following;</para> - - <programlisting> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % text.output "INCLUDE"> -]> - -<html> - <head> - <title>An example using marked sections</title> - </head> - - <body> - <p>This paragraph <![ CDATA [contains many < - characters (< < < < <) so it is easier - to wrap it in a CDATA marked section ]]></p> - - <![ IGNORE [ - <p>This paragraph will definitely not be included in the - output.</p> - ]]> - - <![ <![ CDATA [%text.output]]> [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the <![CDATA[%text.output]]> - parameter entity.</p> - ]]> - </body> -</html></programlisting> - </step> - - <step> - <para>Normalise this file using &man.sgmlnorm.1; and examine the - output. Notice which paragraphs have appeared, which have - disappeared, and what has happened to the content of the CDATA - marked section.</para> - </step> - - <step> - <para>Change the definition of the <literal>text.output</literal> - entity from <literal>INCLUDE</literal> to - <literal>IGNORE</literal>. Re-normalise the file, and examine the - output to see what has changed. </para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>That is the conclusion of this SGML primer. For reasons of space - and complexity several things have not been covered in depth (or at - all). However, the previous sections cover enough SGML for you to be - able to follow the organisation of the FDP documentation.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml deleted file mode 100644 index f564b25e4d..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ /dev/null @@ -1,287 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml,v 1.3 2000/04/30 23:01:09 nik Exp $ ---> - -<chapter id="structure"> - <title>Structuring documents under <filename>doc/</filename></title> - - <para>The <filename>doc/</filename> tree is organised in a particular - fashion, and the documents that are part of the FDP are in turn organised - in a particular fashion. The aim is to make it simple to add new - documentation in to the tree and:</para> - - <orderedlist> - <listitem> - <para>make it easy to automate converting the document to other formats</para> - </listitem> - - <listitem> - <para>promote consistency between the different documentation - organisations, to make it easier to switch between working on - different documents</para> - </listitem> - - <listitem> - <para>make it easy to decide where in the tree new documentation should - be placed</para> - </listitem> - </orderedlist> - - <para>In addition, the documentation tree has to accommodate documentation - that could be in many different languages and in many different - encodings. It is important that the structure of the documentation tree - does not enforce any particular defaults or cultural preferences.</para> - - <sect1> - <title>The top level, <filename>doc/</filename></title> - - <para>There are two types of directory under <filename>doc/</filename>, - each with very specific directory names and meanings.</para> - - <segmentedlist> - <seglistitem> - <seg><filename>share/</filename></seg> - - <seg>Contains files that are not specific to the various translations - and encodings of the documentation. Contains subdirectories to - further categorise the information. For example, the files that - comprise the &man.make.1; infrastructure are in - <filename>share/mk</filename>, while the additional SGML support - files (such as the FreeBSD extended DocBook DTD) are in - <filename>share/sgml</filename>.</seg> - </seglistitem> - - <seglistitem> - <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg> - - <seg>One directory exists for each available translation and encoding - of the documentation, for example - <filename>en_US.ISO_8859-1/</filename> and - <filename>zh_TW.Big5/</filename>. The names are long, but by fully - specifying the language and encoding we prevent any future headaches - should a translation team want to provide the documentation in the - same language but in more than one encoding. This also completely - isolates us from any problems that might be caused by a switch to - Unicode.</seg> - </seglistitem> - </segmentedlist> - </sect1> - - <sect1> - <title>The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories</title> - - <para>These directories contain the documents themselves. The - documentation is split into up to three more categories at this - level, indicated by the different directory names.</para> - - <segmentedlist> - <seglistitem> - <seg><filename>articles</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> - (or equivalent). Reasonably short, and broken up into sections. - Normally only available as one HTML file.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>books</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or - equivalent). Book length, and broken up in to chapters. Normally - available as both one large HTML file (for people with fast - connections, or who want to print it easily from a browser) and - as a collection of linked, smaller files.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>man</filename></seg> - - <seg>For translations of the system manual pages. This directory will - contain one or more - <filename>man<replaceable>n</replaceable></filename> directories, - corresponding to the sections that have been translated.</seg> - </seglistitem> - </segmentedlist> - - <para>Not every - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends - on how much translation has been accomplished by that translation - team.</para> - </sect1> - - <sect1> - <title>Document specific information</title> - - <para>This section contains specific notes about particular documents - managed by the FDP.</para> - - <sect2> - <title>The Handbook</title> - - <subtitle><filename>books/handbook/</filename></subtitle> - - <para>The Handbook is written to comply with the FreeBSD DocBook - extended DTD.</para> - - <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. - It is then divided into <sgmltag>part</sgmltag>s, each of which may - contain several <sgmltag>chapter</sgmltag>s. - <sgmltag>chapter</sgmltag>s are further subdivided into sections - (<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>, - <sgmltag>sect3</sgmltag>) and so on.</para> - - <sect3> - <title>Physical organisation</title> - - <para>There are a number of files and directories within the - <filename>handbook</filename> directory.</para> - - <note> - <para>The Handbook's organisation may change over time, and this - document may lag in detailing the organisational changes. If you - have any questions about how the Handbook is organised, please - contact the FreeBSD Documentation Project, - <email>freebsd-doc@FreeBSD.org</email>.</para> - </note> - - <sect4> - <title><filename>Makefile</filename></title> - - <para>The <filename>Makefile</filename> defines some variables that - affect how the SGML source is converted to other formats, and - lists the various source files that make up the Handbook. It then - includes the standard <filename>doc.project.mk</filename> file, to - bring in the rest of the code that handles converting documents - from one format to another.</para> - </sect4> - - <sect4> - <title><filename>book.sgml</filename></title> - - <para>This is the top level document in the Handbook. It contains - the Handbook's <link - linkend="sgml-primer-doctype-declaration">DOCTYPE - declaration</link>, as well as the elements that describe the - Handbook's structure.</para> - - <para><filename>book.sgml</filename> uses <link - linkend="sgml-primer-parameter-entities">parameter - entities</link> to load in the files with the - <filename>.ent</filename> extension. These files (described later) - then define <link linkend="sgml-primer-general-entities">general - entities</link> that are used throughout the rest of the - Handbook.</para> - </sect4> - - <sect4> - <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> - - <para>Each chapter in the Handbook is stored in a file called - <filename>chapter.sgml</filename> in a separate directory from the - other chapters. Each directory is named after the value of the - <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> - element.</para> - - <para>For example, if one of the chapter files contains:</para> - - <programlisting><![ CDATA [ -<chapter id="kernelconfiguration"> -... -</chapter>]]></programlisting> - - <para>then it will be called <filename>chapter.sgml</filename> in - the <filename>kernelconfiguration</filename> directory. In - general, the entire contents of the chapter will be held in this - file.</para> - - <para>When the HTML version of the Handbook is produced, this will - yield <filename>kernelconfiguration.html</filename>. This is - because of the <literal>id</literal> value, and is not related to - the name of the directory.</para> - - <para>In earlier versions of the Handbook the files were stored in - the same directory as <filename>book.sgml</filename>, and named - after the value of the <literal>id</literal> attribute on the - file's <sgmltag>chapter</sgmltag> element. Moving them in to - separate directories prepares for future plans for the Handbook. - Specifically, it will soon be possible to include images in each - chapter. It makes more sense for each image to be stored in a - directory with the text for the chapter than to try and keep the - text for all the chapters, and all the images, in one large - directory. Namespace collisions would be inevitable, and it is - easier to work with several directories with a few files in them - than it is to work with one directory that has many files in - it.</para> - - <para>A brief look will show that there are many directories with - individual <filename>chapter.sgml</filename> files, including - <filename>basics/chapter.sgml</filename>, - <filename>introduction/chapter.sgml</filename>, and - <filename>printing/chapter.sgml</filename>.</para> - - <important> - <para>Chapters and/or directories should not be named in a fashion - that reflects their ordering within the Handbook. This ordering - might change as the content within the Handbook is reorganised; - this sort of reorganistion should not (generally) include the - need to rename files (unless entire chapters are being promoted - or demoted within the hierarchy).</para> - </important> - - <para>Each <filename>chapter.sgml</filename> file will not be a - complete SGML document. In particular, they will not have their - own DOCTYPE lines at the start of the files.</para> - - <para>This is unfortunate as - it makes it impossible to treat these as generic SGML - files and simply convert them to HTML, RTF, PS, and other - formats in the same way the main Handbook is generated. This - <emphasis>would</emphasis> force you to rebuild the Handbook - every time you want to see the effect a change has had on just - one chapter.</para> - </sect4> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml deleted file mode 100644 index 8a014549cd..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml +++ /dev/null @@ -1,81 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> - -<chapter id="stylesheets"> - <title>* Stylesheets</title> - - <para>SGML says nothing about how a document should be displayed to the - user, or rendered on paper. To do that, various languages have been - developed to describe stylesheets, including DynaText, Panorama, SPICE, - JSSS, FOSI, CSS, and DSSSL.</para> - - <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we - are using CSS.</para> - - <sect1> - <title>* DSSSL</title> - - <para>The Documentation Project uses a slightly customised version of - Norm Walsh's modular DocBook stylesheets.</para> - - <para>These can be found in - <filename>textproc/dsssl-docbook-modular</filename>.</para> - - <para>The modified stylesheets are not in the ports system. Instead they - are part of the Documentation Project source repository, and can be - found in <filename>doc/share/sgml/freebsd.dsl</filename>. It is well - commented, and pending completion of this section you are encouraged to - examine that file to see how some of the available options in the - standard stylesheets have been configured in order to customise the - output for the FreeBSD Documentation Project. That file also contains - examples showing how to extend the elements that the stylesheet - understands, which is how the FreeBSD specific elements have been - formatted.</para> - </sect1> - - <sect1> - <title>* CSS</title> - - <para></para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml deleted file mode 100644 index 92502c7550..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml +++ /dev/null @@ -1,217 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml,v 1.3 1999/09/06 06:52:43 peter Exp $ ---> - -<chapter id="the-website"> - <title>The Website</title> - - <sect1> - <title>Preparation</title> - - <para>Get 200MB free disk space. You will need the disk space for the - SGML tools, a subset of the CVS tree, temporary build space and the - installed web pages. If you aready have installed the SGML tools and - the CVS tree, you need only ~100MB free disk space.</para> - - <note> - <para>Make sure your documentation ports are up to date! When in - doubt, remove the old ports using &man.pkg.delete.1; command before - installing the port. For example, we currently depend on - jade-1.2 and if you have installed jade-1.1, please do</para> - - <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen> - </note> - - <para>Setup a CVS repository. You need the directories www, doc and - ports in the CVS tree (plus the CVSROOT of course). Please read the - CVSup introduction <ulink - url="http://www.freebsd.org/handbook/synching.html#CVSUP"> - http://www.freebsd.org/handbook/synching.html#CVSUP</ulink> how to - mirror a CVS tree or parts of a CVS tree.</para> - - <para>The essential cvsup collections are: <literal>www</literal>, - <literal>doc-all</literal>, <literal>cvs-base</literal>, and - <literal>ports-base</literal>.</para> - - <para>These collections require ~100MB free disk space.</para> - - <para>A full CVS tree - including <literal>src</literal>, - <literal>doc</literal>, <literal>www</literal>, and - <literal>ports</literal> - is currently 650MB large.</para> - </sect1> - - <sect1> - <title>Build the web pages from scratch</title> - - <procedure> - <step> - <para>Go to into a build directory with at least 60MB of free - space.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput> -&prompt.root; <userinput>cd /var/tmp/webuild</userinput></screen> - </step> - - <step> - <para>Checkout the SGML files from the CVS tree.</para> - - <screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen> - </step> - - <step><para>Change in to the <filename>www</filename> directory, and - run the &man.make.1; <maketarget>links</maketarget> target, to - create the necessary symbolic links.</para> - - <screen>&prompt.root; <userinput>cd www</userinput> -&prompt.root; <userinput>make links</userinput></screen> - </step> - - <step> - <para>Change in to the <filename>en</filename> directory, and run - the &man.make.1; <maketarget>all</maketarget> target, to create - the web pages.</para> - - <screen>&prompt.root; <userinput>cd en</userinput> -&prompt.root; <userinput>make all</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1> - <title>Install the web pages into your web server</title> - - <procedure> - <step> - <para>If you have moved out of the <filename>en</filename> - directory, change back to it.</para> - - <screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</userinput></screen> - </step> - - <step> - <para>Run the &man.make.1; <maketarget>install</maketarget> target, - setting the <makevar>DESTDIR</makevar> variable to the name of the - directory you want to install the files to.</para> - - <screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</userinput></screen> - </step> - - <step> - <para>If you have previously installed the web pages in to the same - directory the install process will not have deleted any old or - outdated pages. For example, if you build and install a new copy - of the site every day, this command will find and delete all - files that have not been updated in three days.</para> - - <screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -print0 | xargs -0 rm</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1> - <title>Environment variables</title> - - <variablelist> - <varlistentry> - <term><envar>CVSROOT</envar></term> - - <listitem> - <para>Location of the CVS tree. Essential.</para> - - <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>ENGLISH_ONLY</makevar></term> - - <listitem> - <para>If set and not empty, the makefiles will build and - install only the English documents. All translations will be - ignored. E.g.:</para> - - <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen> - - <para>If you want unset the variable - <makevar>ENGLISH_ONLY</makevar> and build all pages, including - translations, set the variable <makevar>ENGLISH_ONLY</makevar> - to an empty value</para> - - <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>WEB_ONLY</makevar></term> - - <listitem> - <para>If set and not empty, the makefiles wil build and install - only the HTML pages from the www directory. All documents from - the doc directory (Handbook, FAQ, Tutorials) will be ignored. - E.g.:</para> - - <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>NOPORTSCVS</makevar></term> - - <listitem> - <para>If set, the makefiles will not checkout files from the ports - cvs repository. Instead, it will copy the files from - <filename>/usr/ports</filename> (or where the variable - <envar>PORTSBASE</envar> points to).</para> - </listitem> - </varlistentry> - </variablelist> - - <para><envar>CVSROOT</envar> is an environment variable. You must set it - on the commandline or in your dot files (~/.profile).</para> - - <para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and - <makevar>NOPORTSCVS</makevar> are makefile variables. You can set the - variables in <filename>/etc/make.conf</filename>, - <filename>Makefile.inc</filename> or as environment variables on the - commandline or in your dot files.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml deleted file mode 100644 index b3fdda9683..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml +++ /dev/null @@ -1,284 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml,v 1.9 2000/07/07 18:38:38 dannyboy Exp $ ---> - -<chapter id="tools"> - <title>Tools</title> - - <para>The FDP uses a number of different software tools to help - manage the FreeBSD documentation, convert it to different output - formats, and so on. You will need to use these tools yourself if - you are to work with the FreeBSD documentation.</para> - - <para>All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them.</para> - - <para>You will need to install these tools before you work through - any of the examples in later chapters. The actual usage of these - tools is covered in later chapters.</para> - - <important> - <title>Use <filename>textproc/docproj</filename> if possible</title> - - <para>You can save yourself a lot of time if you install the - <filename>textproc/docproj</filename> port. This is a - <emphasis>meta-port</emphasis> which does not contain any software - itself. Instead, it depends on various other ports being installed - correctly. Installing this port <emphasis>should</emphasis> - automatically download and install all of the packages listed in this - chapter that you need.</para> - - <para>One of the packages that you might need is the JadeTeX macro set. - In turn, this macro set requires that TeX is installed. TeX is a large - package, and you only need it if you want to produce Postscript or PDF - output.</para> - - <para>To save yourself time and space you must specify whether or not you - want JadeTeX (and therefore TeX) installed when you install this port. - Either do; - - <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> - - or - - <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> - - as necessary.</para> - </important> - - <sect1> - <title>Mandatory tools</title> - - <sect2> - <title>Software</title> - - <para>These programs are required before you can usefully work with - the FreeBSD documentation. They are all included in - <filename>textproc/docproj</filename>.</para> - - <variablelist> - <varlistentry> - <term><application>SP</application> - (<filename>textproc/sp</filename>)</term> - - <listitem> - <para>A suite of applications, including a validating SGML parser, - and an SGML normaliser.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Jade</application> - (<filename>textproc/jade</filename>)</term> - - <listitem> - <para>A DSSSL implementation. Used for converting marked up - documents to other formats, including HTML and TeX.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Tidy</application> - (<filename>www/tidy</filename>)</term> - - <listitem> - <para>An HTML 'pretty printer', used to reformat some of the - automatically generated HTML so that it is easier to - follow.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>W3M</application> - (<filename>www/w3m</filename>)</term> - - <listitem> - <para>A text-mode WWW browser, &man.w3m.1; can also convert - HTML files to plain text.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>DTDs and Entities</title> - - <para>These are the DTDs and entity sets used by the FDP. They need to - be installed before you can work with any of the documentation.</para> - - <variablelist> - <varlistentry> - <term>HTML DTD (<filename>textproc/html</filename>)</term> - - <listitem> - <para>HTML is the markup language of choice for the World Wide - Web, and is used throughout the FreeBSD web site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LinuxDoc DTD (<filename>textproc/linuxdoc</filename>)</term> - - <listitem> - <para>Some FreeBSD documentation is marked up in LinuxDoc. The - FDP is actively migrating from LinuxDoc to DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DocBook DTD (<filename>textproc/docbook</filename>)</term> - - <listitem> - <para>DocBook is designed for marking up technical documentation, - and the FDP is migrating from LinuxDoc to DocBook. At the time - of writing, this document and the FreeBSD Handbook are marked - up in DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ISO 8879 entities - (<filename>textproc/iso8879</filename>)</term> - - <listitem> - <para>19 of the ISO 8879:1986 character entity sets used by many - DTDs. Includes named mathematical symbols, additional - characters in the 'latin' character set (accents, diacriticals, - and so on), and greek symbols.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Stylesheets</title> - - <para>The stylesheets are used when converting and formatting the - documentation for display on screen, printing, and so on.</para> - - <variablelist> - <varlistentry> - <term>Modular DocBook Stylesheets - (<filename>textproc/dsssl-docbook-modular</filename>)</term> - - <listitem> - <para>The Modular DocBook Stylesheets are used when converting - documentation marked up in DocBook to other formats, such as - HTML or RTF.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1> - <title>Optional tools</title> - - <para>You do not need to have any of the following installed. However, - you may find it easier to work with the documentation if you do, and - they may give you more flexibility in the output formats that can be - generated.</para> - - <sect2> - <title>Software</title> - - <variablelist> - <varlistentry> - <term><application>JadeTeX</application> and - <application>teTeX</application> - (<filename>print/jadetex</filename> and - <filename>print/teTeX</filename>)</term> - - <listitem> - <para><application>Jade</application> and - <application>teTeX</application> are used to convert DocBook - documents to DVI, Postscript, and PDF formats. The - <application>JadeTeX</application> macros are needed in order to - do this.</para> - - <para>If you do not intend to convert your documentation to one of - these formats (i.e., HTML, plain text, and RTF are sufficient) - then you do not need to install - <application>JadeTeX</application> and - <application>teTeX</application>. This can be a significant - space and time saver, as <application>teTeX</application> is - over 30MB in size.</para> - - <important> - <para>If you decide to install - <application>JadeTeX</application> and - <application>teTeX</application> then you will need to - configure <application>teTeX</application> after - <application>JadeTeX</application> has been installed. - <filename>print/jadetex/pkg/MESSAGE</filename> contains - detailed instructions explaining what you need to do.</para> - </important> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Emacs</application> or - <application>xemacs</application> - (<filename>editors/emacs</filename> or - <filename>editors/xemacs</filename>)</term> - - <listitem> - <para>Both these editors include a special mode for editing - documents marked up according to an SGML DTD. This mode - includes commands to reduce the amount of typing you need, and - help reduce the possibility of errors.</para> - - <para>You do not need to use them; any text editor can be used to - edit marked up documents. You may find they make you more - efficient.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If anyone has recommendations for other software that is useful - when manipulating SGML documents, please let Nik Clayton - (<email>nik@FreeBSD.org</email>) know, so they can be added to this - list.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml deleted file mode 100644 index f0e9bbb1c3..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml +++ /dev/null @@ -1,474 +0,0 @@ -<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $ ---> - -<chapter id="translations"> - <title>Translations</title> - - <para>This is the FAQ for people translating the FreeBSD documentation - (FAQ, Handbook, tutorials, man pages, and others) to different - languages.</para> - - <para>It is <emphasis>very</emphasis> heavily based on the translation FAQ - from the FreeBSD German Documentation Project, originally written by Frank - Gründer <email>elwood@mc5sys.in-berlin.de</email> and translated back to - English by Bernd Warken <email>bwarken@mayn.de</email>.</para> - - <para>The FAQ maintainer is Nik Clayton - <email>nik@FreeBSD.org</email>.</para> - - <qandaset> - <qandaentry> - <question> - <para>Why a FAQ?</para> - </question> - - <answer> - <para>More and more people are approaching the freebsd-doc mailing - list and volunteering to translate FreeBSD documentation to other - languages. This FAQ aims to answer their questions so they can start - translating documentation as quickly as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase> - mean?</para> - </question> - - <answer> - <para><phrase>i18n</phrase> means - <phrase>internationalisation</phrase> and <phrase>l10n</phrase> - means <phrase>localisation</phrase>. They are just a convenient - shorthand.</para> - - <para><phrase>i18n</phrase> can be read as “i” followed by - 18 letters, followed by “n”. Similarly, - <phrase>l10n</phrase> is “l” followed by 10 letters, - followed by “n”.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is there a mailing list for translators?</para> - </question> - - <answer> - <para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by - sending a message to - <email>freebsd-translate-request@ngo.org.uk</email> with the word - <literal>subscribe</literal> in the body of the message.</para> - - <para>You will receive a reply asking you to confirm your subscription - (in exactly the same manner as the the FreeBSD lists at <hostid - role="domainname">FreeBSD.org</hostid>).</para> - - <para>The primary language of the mailing list is English. However, - posts in other languages will be accepted. The mailing list is not - moderated, but you need to be a member of the list before you can - post to it.</para> - - <para>The mailing list is archived, but they are not currently - searchable. Sending the message <literal>help</literal> to - <email>majordomo@ngo.org.uk</email> will send back instructions on - how to access the archive.</para> - - <para>It is expected that the mailing list will transfer to <hostid - role="domainname">FreeBSD.org</hostid> and therefore become - <emphasis>official</emphasis> in the near future.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are more translators needed?</para> - </question> - - <answer> - <para>Yes. The more people work on translation the faster it gets - done, and the faster changes to the English documentation are - mirrored in the translated documents.</para> - - <para>You do not have to be a professional translator to be able to - help.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What languages do I need to know?</para> - </question> - - <answer> - <para>Ideally, you will have a good knowledge of written English, and - obviously you will need to be fluent in the language you are - translating to.</para> - - <para>English is not strictly necessary. For example, you could do a - Hungarian translation of the FAQ from the Spanish - translation.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What software do I need to know?</para> - </question> - - <answer> - <para>It is strongly recommended that you maintain a local copy of the - FreeBSD CVS repository (at least the documentation part) either - using <application>CTM</application> or - <application>CVSup</application>. The "Staying current with FreeBSD" - chapter in the Handbook explains how to use these - applications.</para> - - <para>You should be comfortable using <application>CVS</application>. - This will allow you to see what has changed between different - versions of the files that make up the documentation.</para> - - <para>[XXX To Do -- write a tutorial that shows how to use CVSup to - get just the documentation, check it out, and see what's changed - between two arbitrary revisions]</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I find out who else might be translating to the same - language?</para> - </question> - - <answer> - <para>The <ulink - url="http://www.FreeBSD.org/docproj/translations.html">Documentation - Project translations page</ulink> lists the translation efforts - that are currently known about. If others are already working - on translating documentation to your language, please don't - duplicate their efforts. Instead, contact them to see how you can - help.</para> - - <para>If no one is listed on that page as translating for your - language, then send a message to - <email>freebsd-doc@FreeBSD.org</email> in case someone else is - thinking of doing a translation, but hasn't announced it yet.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>No one else is translating to my language. What do I do?</para> - </question> - - <answer> - <para>Congratulations, you have just started the “FreeBSD - <replaceable>your-language-here</replaceable> Documentation - Translation Project”. Welcome aboard.</para> - - <para>First, decide whether or not you've got the time to spare. Since - you are the only person working on your language at the moment it is - going to be your responsibility to publicise your work and - coordinate any volunteers that might want to help you.</para> - - <para>Write an e-mail to the Documentation Project mailing list, - announcing that you are going to translate the documentation, so the - Documentation Project translations page can be maintained.</para> - - <para>You should subscribe to the - <email>freebsd-translate@ngo.org.uk</email> mailing list (as - described earlier).</para> - - <para>If there is already someone in your country providing FreeBSD - mirroring services you should contact them and ask if you can - have some webspace for your project, and possibly an e-mail - address or mailing list services.</para> - - <para>Then pick a document and start translating. It is best to start - with something fairly small—either the FAQ, or one of the - tutorials.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I've translated some documentation, where do I send it?</para> - </question> - - <answer> - <para>That depends. If you are already working with a translation team - (such as the Japanese team, or the German team) then they will have - their own procedures for handling submitted documentation, and these - will be outlined on their web pages.</para> - - <para>If you are the only person working on a particular language (or - you are responsible for a translation project and want to submit - your changes back to the FreeBSD project) then you should send your - translation to the FreeBSD project (see the next question).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I'm the only person working on translating to this language, how - do I submit my translation?</para> - - <para>or</para> - - <para>We're a translation team, and want to submit documentation that - our members have translated for us?</para> - </question> - - <answer> - <para>First, make sure your translation is organised properly. This - means that it should drop in to the existing documentation tree and - build straight away.</para> - - <para>Currently, the FreeBSD documentation is stored in a top level - directory called <filename>doc/</filename>. Directories below this - are named according to the language code they are written in, as - defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a - version of FreeBSD newer than 20th January 1999).</para> - - <para>If your language can be encoded in different ways (for example, - Chinese) then there should be directories below this, one for each - encoding format you have provided.</para> - - <para>Finally, you should have directories for each document.</para> - - <para>For example, a hypothetical Swedish translation might look - like</para> - - <programlisting>doc/ - sv_SE.ISO_8859-1/ - Makefile - books/ - faq/ - Makefile - book.sgml</programlisting> - - <para><literal>sv_SE.ISO_8859-1</literal> is the name of the - translation, in - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - form. Note the - two Makefiles, which will be used to build the documentation.</para> - - <para>Use &man.tar.1; and &man.gzip.1; to compress up your - documentation, and send it to the project.</para> - - <screen>&prompt.user; <userinput>cd doc</userinput> -&prompt.user; <userinput>tar cf swedish-docs.tar sv</userinput> -&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen> - - <para>Put <filename>swedish-docs.tar.gz</filename> somewhere. If you - do not have access to your own webspace (perhaps your ISP does not - let you have any) then you can e-mail Nik Clayton - <email>nik@FreeBSD.org</email>, and arrange to e-mail the files - when it is convenient.</para> - - <para>Either way, you should use &man.send-pr.1; to submit a report - indicating that you have submitted the documentation. It would be - very helpful if you could get other people to look over your - translation and double check it first, since it is unlikely that the - person committing it will be fluent in the language.</para> - - <para>Someone (probably the Documentation Project Manager, currently - Nik Clayton <email>nik@FreeBSD.org</email>) will then take your - translation and confirm that it builds. In particular, the - following things will be looked at:</para> - - <orderedlist> - <listitem> - <para>Do all your files use RCS strings (such as "ID")?</para> - </listitem> - - <listitem> - <para>Does <command>make all</command> in the - <filename>sv_SE.ISO_8859-1</filename> directory work correctly?</para> - </listitem> - - <listitem> - <para>Does <command>make install</command> work correctly?</para> - </listitem> - </orderedlist> - - <para>If there are any problems then whoever is looking at the - submission will get back to you to try and work them out.</para> - - <para>If there are no problems your translation will be committed - as soon as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I include language or country specific text in my - translation?</para> - </question> - - <answer> - <para>We would prefer that you did not.</para> - - <para>For example, suppose that you are translating the Handbook to - Korean, and want to include a section about retailers in Korea in - your Handbook.</para> - - <para>There's no real reason why that information should not be in the - English (or German, or Spanish, or Japanese, or …) versions - as well. It is feasible that an English speaker in Korea might try - and pick up a copy of FreeBSD whilst over there. It also helps - increase FreeBSD's perceived presence around the globe, which is not - a bad thing.</para> - - <para>If you have country specific information, please submit it as a - change to the English Handbook (using &man.send-pr.1;) and then - translate the change back to your language in the translated - Handbook.</para> - - <para>Thanks.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How should language specific characters be included?</para> - - <para>Non-ASCII characters in the documentation should be included - using SGML entities.</para> - - <para>Briefly, these look like an ampersand (&), the name of the - entity, and a semi-colon (;).</para> - - <para>The entity names are defined in ISO8879, which is in the ports - tree as <filename>textproc/iso8879</filename>.</para> - - <para>A few examples include</para> - - <segmentedlist> - <seglistitem> - <seg>&eacute;</seg> - <seg>é</seg> - <seg>Small “e” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&Eacute;</seg> - <seg>É</seg> - <seg>Large “E” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&uuml;</seg> - <seg>ü</seg> - <seg>Small “u” with an umlaut</seg> - </seglistitem> - </segmentedlist> - - <para>After you have installed the iso8879 port, the files in - <filename>/usr/local/share/sgml/iso8879</filename> contain the - complete list.</para> - </question> - </qandaentry> - - <qandaentry> - <question> - <para>Addressing the reader</para> - </question> - - <answer> - <para>In the English documents, the reader is addressed as - “you”, there is no formal/informal distinction as there - is in some languages.</para> - - <para>If you are translating to a language which does distinguish, use - whichever form is typically used in other technical documentation in - your language. If in doubt, use a mildly polite form.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Do I need to include any additional information in my - translations?</para> - </question> - - <answer> - <para>Yes.</para> - - <para>The header of the English version of each document will look - something like this;</para> - - <programlisting><!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $ ---></programlisting> - - <para>The exact boilerplate may change, but it will always include a - $FreeBSD$ line and the phrase <literal>The FreeBSD Documentation - Project</literal>. - Note that the $FreeBSD part is expanded automatically by - CVS, so it should be empty (just - <literal>$FreeBSD$</literal>) for new files.</para> - - <para>Your translated documents should include their own - $FreeBSD$ line, and change the - <literal>FreeBSD Documentation Project</literal> line to - <literal>The FreeBSD <replaceable>language</replaceable> - Documentation Project</literal>.</para> - - <para>In addition, you should add a third line which indicates which - revision of the English text this is based on.</para> - - <para>So, the Spanish version of this file might start</para> - - <programlisting><!-- - The FreeBSD Spanish Documentation Project - - $FreeBSD: doc/es_ES.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ - Original revision: 1.11 ---></programlisting> - </answer> - </qandaentry> - </qandaset> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml deleted file mode 100644 index 078f0efbc1..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml +++ /dev/null @@ -1,316 +0,0 @@ -<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.8 2000/06/15 01:00:01 kevlo Exp $ ---> - -<chapter id="writing-style"> - <title>Writing style</title> - - <para>In order to promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for authors to - follow.</para> - - <variablelist> - <varlistentry> - <term>Do not use contractions</term> - - <listitem> - <para>Do not use contractions. Always spell the phrase out in full. - “Don't use contractions” would be wrong.</para> - - <para>Avoiding contractions makes for a more formal tone, is more - precise, and is slightly easier for translators.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use the serial comma</term> - - <listitem> - <para>In a list of items within a paragraph, separate each item from - the others with a comma. Seperate the last item from the others with - a comma and the word “and”.</para> - - <para>For example, look at the following:</para> - - <blockquote> - <para>This is a list of one, two and three items.</para> - </blockquote> - - <para>Is this a list of three items, “one”, - “two”, and “three”, or a list of two items, - “one” and “two and three”?</para> - - <para>It is better to be explicit and include a serial comma:</para> - - <blockquote> - <para>This is a list of one, two, and three items.</para> - </blockquote> - </listitem> - </varlistentry> - - <varlistentry> - <term>Avoid redundant phrases</term> - - <listitem> - <para>Try not to use redundant phrases. In particular, “the - command”, “the file”, and “man - command” are probably redundant.</para> - - <para>These two examples show this for commands. The second example - is preferred.</para> - - <informalexample> - <para>Use the command <command>cvsup</command> to update your - sources</para> - </informalexample> - - <informalexample> - <para>Use <command>cvsup</command> to update your sources</para> - </informalexample> - - <para>These two examples show this for filenames. The second example - is preferred.</para> - - <informalexample> - <para>… in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <informalexample> - <para>… in - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <para>These two examples show this for manual references. The second - example is preferred (the second example uses - <sgmltag>citerefentry</sgmltag>).</para> - - <informalexample> - <para>See <command>man csh</command> for more - information.</para> - </informalexample> - - <informalexample> - <para>See &man.csh.1;</para> - </informalexample> - </listitem> - </varlistentry> - <varlistentry> - <term>Two spaces at the end of sentences</term> - - <listitem> - <para>Always use two spaces at the end of sentences, as this - improves readability, and eases use of tools such as - <application>emacs</application>.</para> - - <para>While it may be argued that a capital letter following - a period denotes a new sentence, this is not the case, especially - in name usage. <quote>Jordan K. Hubbard</quote> is a good - example; it has a capital <literal>H</literal> following a - period and a space, and there certainly isn't a new sentence - there.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about writing style, see <ulink - url="http://www.bartleby.com/141/index.html">Elements of - Style</ulink>, by William Strunk.</para> - - <sect1> - <title>Style guide</title> - - <para>To keep the source for the Handbook consistent when many different - people are editing it, please follow these style conventions.</para> - - <sect2> - <title>Letter case</title> - - <para>Tags are entered in lower case, <literal><para></literal>, - <emphasis>not</emphasis> <literal><PARA></literal>.</para> - - <para>Text that appears in SGML contexts is generally written in upper - case, <literal><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> - <literal><!entity…></literal> and - <literal><!doctype…></literal>.</para> - </sect2> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line.</para> - - <para>For example, the source for this section looks something - like:</para> - - <programlisting> -<![ CDATA [+--- This is column 0 -V -<chapter> - <title>...</title> - - <sect1> - <title>...</title> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line.</para> - - ... - </sect2> - </sect1> -</chapter>]]></programlisting> - - <para>If you use <application>Emacs</application> or - <application>Xemacs</application> to edit the files then - <literal>sgml-mode</literal> should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles.</para> - </sect2> - - <sect2> - <title>Tag style</title> - - <sect3> - <title>Tag spacing</title> - - <para>Tags that start at the same indent as a previous tag - should be separated by a blank line, and those that are not - at the same indent as a previous tag should not:</para> - - <informalexample> - <programlisting><![ CDATA [<article> - <artheader> - <title>NIS</title> - - <pubdate>October 1999</pubdata> - - <abstract> - <para>... - ... - ...</para> - </abstract> - </artheader> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> -</article>]]></programlisting> - </informalexample> - </sect3> - - <sect3> - <title>Separating tags</title> - - <para>Tags like <sgmltag>itemizedlist</sgmltag> which will - always have further tags inside them, and in fact don't take - character data themselves, are always on a line by - themselves.</para> - - <para>Tags like <sgmltag>para</sgmltag> and - <sgmltag>term</sgmltag> don't need other tags to contain - normal character data, and their contents begin immediately - after the tag, <emphasis>on the same line</emphasis>.</para> - - <para>The same applies to when these two types of tags - close.</para> - - <para>This leads to an obvious problem when mixing these - tags.</para> - - <para>When a starting tag which cannot contain character data - directly follows a tag of the type that requires other tags - within it to use character data, they are on separate lines. - The second tag should be properly indented.</para> - - <para>When a tag which can contain character data closes - directly after a tag which cannot contain character data - closes, they co-exist on the same line.</para> - </sect3> - </sect2> - - <sect2> - <title>White space changes</title> - - <para>When committing changes, <emphasis>do not commit changes to the - content at the same time as changes to the - formatting</emphasis>.</para> - - <para>This is so that the teams that convert the Handbook to other - languages can quickly see what content has actually changed in your - commit, without having to decide whether a line has changed because of - the content, or just because it has been refilled.</para> - - <para>For example, if you have added two sentences to a paragraph, such - that the line lengths on the paragraph now go over 80 columns, first - commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for - the second change, be sure to indicate that this is a whitespace-only - change, and that the translation team can ignore it.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile deleted file mode 100644 index 47fdbb4a79..0000000000 --- a/en_US.ISO8859-1/books/handbook/Makefile +++ /dev/null @@ -1,62 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/Makefile,v 1.28 2000/03/20 20:59:30 jim Exp $ -# -# Build the FreeBSD Handbook. -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml -SRCS+= advanced-networking/chapter.sgml -SRCS+= backups/chapter.sgml -SRCS+= basics/chapter.sgml -SRCS+= bibliography/chapter.sgml -SRCS+= boot/chapter.sgml -SRCS+= contrib/chapter.sgml -SRCS+= cutting-edge/chapter.sgml -SRCS+= disks/chapter.sgml -SRCS+= eresources/chapter.sgml -SRCS+= hw/chapter.sgml -SRCS+= install/chapter.sgml -SRCS+= internals/chapter.sgml -SRCS+= introduction/chapter.sgml -SRCS+= kernelconfig/chapter.sgml -SRCS+= kerneldebug/chapter.sgml -SRCS+= kernelopts/chapter.sgml -SRCS+= l10n/chapter.sgml -SRCS+= linuxemu/chapter.sgml -SRCS+= mail/chapter.sgml -SRCS+= mirrors/chapter.sgml -SRCS+= pgpkeys/chapter.sgml -SRCS+= policies/chapter.sgml -SRCS+= ppp-and-slip/chapter.sgml -SRCS+= printing/chapter.sgml -SRCS+= security/chapter.sgml -SRCS+= serialcomms/chapter.sgml -SRCS+= staff/chapter.sgml -SRCS+= users/chapter.sgml -SRCS+= x11/chapter.sgml -SRCS+= ports/chapter.sgml - -# Entities -SRCS+= authors.ent -SRCS+= chapters.ent -SRCS+= mailing-lists.ent - -SYMLINKS= ${DESTDIR} index.html handbook.html - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml deleted file mode 100644 index 32c941bb80..0000000000 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ /dev/null @@ -1,2746 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.31 2000/09/19 17:05:47 ben Exp $ ---> - -<chapter id="advanced-networking"> - <title>Advanced Networking</title> - - <sect1> - <title>Synopsis</title> - - <para>The following chapter will cover some of the more frequently - used network services on UNIX systems. This, of course, will - pertain to configuring said services on your FreeBSD system.</para> - </sect1> - - <sect1 id="routing"> - <title>Gateways and Routes</title> - - <para><emphasis>Contributed by &a.gryphon;. 6 October - 1995.</emphasis></para> - - <para>For one machine to be able to find another, there must be a - mechanism in place to describe how to get from one to the other. This is - called Routing. A <quote>route</quote> is a defined pair of addresses: a - <quote>destination</quote> and a <quote>gateway</quote>. The pair - indicates that if you are trying to get to this - <emphasis>destination</emphasis>, send along through this - <emphasis>gateway</emphasis>. There are three types of destinations: - individual hosts, subnets, and <quote>default</quote>. The - <quote>default route</quote> is used if none of the other routes apply. - We will talk a little bit more about default routes later on. There are - also three types of gateways: individual hosts, interfaces (also called - <quote>links</quote>), and ethernet hardware addresses.</para> - - <sect2> - <title>An example</title> - - <para>To illustrate different aspects of routing, we will use the - following example which is the output of the command <command>netstat - -r</command>:</para> - - <screen>Destination Gateway Flags Refs Use Netif Expire - -default outside-gw UGSc 37 418 ppp0 -localhost localhost UH 0 181 lo0 -test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 -10.20.30.255 link#1 UHLW 1 2421 -foobar.com link#1 UC 0 0 -host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 -host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => -host2.foobar.com link#1 UC 0 0 -224 link#1 UC 0 0</screen> - - <para>The first two lines specify the default route (which we will cover - in the next section) and the <hostid>localhost</hostid> route.</para> - - <para>The interface (<literal>Netif</literal> column) that it specifies - to use for <literal>localhost</literal> is - <devicename>lo0</devicename>, also known as the loopback device. This - says to keep all traffic for this destination internal, rather than - sending it out over the LAN, since it will only end up back where it - started anyway.</para> - - <para>The next thing that stands out are the <hostid - role="mac">0:e0:...</hostid> addresses. These are ethernet hardware - addresses. FreeBSD will automatically identify any hosts - (<hostid>test0</hostid> in the example) on the local ethernet and add - a route for that host, directly to it over the ethernet interface, - <devicename>ed0</devicename>. There is also a timeout - (<literal>Expire</literal> column) associated with this type of route, - which is used if we fail to hear from the host in a specific amount of - time. In this case the route will be automatically deleted. These - hosts are identified using a mechanism known as RIP (Routing - Information Protocol), which figures out routes to local hosts based - upon a shortest path determination.</para> - - <para>FreeBSD will also add subnet routes for the local subnet (<hostid - role="ipaddr">10.20.30.255</hostid> is the broadcast address for the - subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid - role="domainname">foobar.com</hostid> is the domain name associated - with that subnet). The designation <literal>link#1</literal> refers - to the first ethernet card in the machine. You will notice no - additional interface is specified for those.</para> - - <para>Both of these groups (local network hosts and local subnets) have - their routes automatically configured by a daemon called - <command>routed</command>. If this is not run, then only routes which - are statically defined (ie. entered explicitly) will exist.</para> - - <para>The <literal>host1</literal> line refers to our host, which it - knows by ethernet address. Since we are the sending host, FreeBSD - knows to use the loopback interface (<devicename>lo0</devicename>) - rather than sending it out over the ethernet interface.</para> - - <para>The two <literal>host2</literal> lines are an example of what - happens when we use an ifconfig alias (see the section of ethernet for - reasons why we would do this). The <literal>=></literal> symbol - after the <devicename>lo0</devicename> interface says that not only - are we using the loopback (since this is address also refers to the - local host), but specifically it is an alias. Such routes only show - up on the host that supports the alias; all other hosts on the local - network will simply have a <literal>link#1</literal> line for - such.</para> - - <para>The final line (destination subnet <literal>224</literal>) deals - with MultiCasting, which will be covered in a another section.</para> - - <para>The other column that we should talk about are the - <literal>Flags</literal>. Each route has different attributes that - are described in the column. Below is a short table of some of these - flags and their meanings:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>U</entry> - <entry>Up: The route is active.</entry> - </row> - - <row> - <entry>H</entry> - <entry>Host: The route destination is a single host.</entry> - </row> - - <row> - <entry>G</entry> - <entry>Gateway: Send anything for this destination on to this - remote system, which will figure out from there where to send - it.</entry> - </row> - - <row> - <entry>S</entry> - <entry>Static: This route was configured manually, not - automatically generated by the system.</entry> - </row> - - <row> - <entry>C</entry> - <entry>Clone: Generates a new route based upon this route for - machines we connect to. This type of route is normally used - for local networks.</entry> - </row> - - <row> - <entry>W</entry> - <entry>WasCloned: Indicated a route that was auto-configured - based upon a local area network (Clone) route.</entry> - </row> - - <row> - <entry>L</entry> - <entry>Link: Route involves references to ethernet - hardware.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Default routes</title> - - <para>When the local system needs to make a connection to remote host, - it checks the routing table to determine if a known path exists. If - the remote host falls into a subnet that we know how to reach (Cloned - routes), then the system checks to see if it can connect along that - interface.</para> - - <para>If all known paths fail, the system has one last option: the - <quote>default</quote> route. This route is a special type of gateway - route (usually the only one present in the system), and is always - marked with a <literal>c</literal> in the flags field. For hosts on a - local area network, this gateway is set to whatever machine has a - direct connection to the outside world (whether via PPP link, or your - hardware device attached to a dedicated data line).</para> - - <para>If you are configuring the default route for a machine which - itself is functioning as the gateway to the outside world, then the - default route will be the gateway machine at your Internet Service - Provider's (ISP) site.</para> - - <para>Let us look at an example of default routes. This is a common - configuration:</para> - - <literallayout> -[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] - </literallayout> - - <para>The hosts <hostid>Local1</hostid> and <hostid>Local2</hostid> are - at your site, with the formed being your PPP connection to your ISP's - Terminal Server. Your ISP has a local network at their site, which - has, among other things, the server where you connect and a hardware - device (T1-GW) attached to the ISP's Internet feed.</para> - - <para>The default routes for each of your machines will be:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>host</entry> - <entry>default gateway</entry> - <entry>interface</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Local2</entry> - <entry>Local1</entry> - <entry>ethernet</entry> - </row> - - <row> - <entry>Local1</entry> - <entry>T1-GW</entry> - <entry>PPP</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>A common question is <quote>Why (or how) would we set the T1-GW to - be the default gateway for Local1, rather than the ISP server it is - connected to?</quote>.</para> - - <para>Remember, since the PPP interface is using an address on the ISP's - local network for your side of the connection, routes for any other - machines on the ISP's local network will be automatically generated. - Hence, you will already know how to reach the T1-GW machine, so there - is no need for the intermediate step of sending traffic to the ISP - server.</para> - - <para>As a final note, it is common to use the address <hostid - role="ipaddr">...1</hostid> as the gateway address for your local - network. So (using the same example), if your local class-C address - space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was - using <hostid role="ipaddr">10.9.9</hostid> then the default routes - would be:</para> - - <literallayout> -Local2 (10.20.30.2) --> Local1 (10.20.30.1) -Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1) - </literallayout> - </sect2> - - <sect2> - <title>Dual homed hosts</title> - - <para>There is one other type of configuration that we should cover, and - that is a host that sits on two different networks. Technically, any - machine functioning as a gateway (in the example above, using a PPP - connection) counts as a dual-homed host. But the term is really only - used to refer to a machine that sits on two local-area - networks.</para> - - <para>In one case, the machine as two ethernet cards, each having an - address on the separate subnets. Alternately, the machine may only - have one ethernet card, and be using ifconfig aliasing. The former is - used if two physically separate ethernet networks are in use, the - latter if there is one physical network segment, but two logically - separate subnets.</para> - - <para>Either way, routing tables are set up so that each subnet knows - that this machine is the defined gateway (inbound route) to the other - subnet. This configuration, with the machine acting as a Bridge - between the two subnets, is often used when we need to implement - packet filtering or firewall security in either or both - directions.</para> - </sect2> - - <sect2> - <title>Routing propagation</title> - - <para>We have already talked about how we define our routes to the - outside world, but not about how the outside world finds us.</para> - - <para>We already know that routing tables can be set up so that all - traffic for a particular address space (in our examples, a class-C - subnet) can be sent to a particular host on that network, which will - forward the packets inbound.</para> - - <para>When you get an address space assigned to your site, your service - provider will set up their routing tables so that all traffic for your - subnet will be sent down your PPP link to your site. But how do sites - across the country know to send to your ISP?</para> - - <para>There is a system (much like the distributed DNS information) that - keeps track of all assigned address-spaces, and defines their point of - connection to the Internet Backbone. The <quote>Backbone</quote> are - the main trunk lines that carry Internet traffic across the country, - and around the world. Each backbone machine has a copy of a master - set of tables, which direct traffic for a particular network to a - specific backbone carrier, and from there down the chain of service - providers until it reaches your network.</para> - - <para>It is the task of your service provider to advertise to the - backbone sites that they are the point of connection (and thus the - path inward) for your site. This is known as route - propagation.</para> - </sect2> - - <sect2> - <title>Troubleshooting</title> - - <para>Sometimes, there is a problem with routing propagation, and some - sites are unable to connect to you. Perhaps the most useful command - for trying to figure out where a routing is breaking down is the - &man.traceroute.8; command. It is equally useful if you cannot seem - to make a connection to a remote machine (i.e. &man.ping.8; - fails).</para> - - <para>The &man.traceroute.8; command is run with the name of the remote - host you are trying to connect to. It will show the gateway hosts - along the path of the attempt, eventually either reaching the target - host, or terminating because of a lack of connection.</para> - - <para>For more information, see the manual page for - &man.traceroute.8;.</para> - </sect2> - </sect1> - - <sect1 id="bridging"> - <title>Bridging</title> - - <para><emphasis>Written by Steve Peterson - <email>steve@zpfe.com</email></emphasis>.</para> - - <sect2> - <title>Introduction</title> - - <para>It is sometimes useful to divide one physical network (i.e., an - Ethernet segment) into two separate network segments, without having - to create IP subnets and use a router to connect the segments - together. A device that connects two networks together in this - fashion is called a bridge. and a FreeBSD system with two network - interface cards can act as a bridge.</para> - - <para>The bridge works by learning the MAC layer addresses (i.e., - Ethernet addresses) of the devices on each of its network interfaces. - It forwards traffic between two networks only when its source and - destination are on different networks.</para> - - <para>In many respects, a bridge is like an Ethernet switch with very - few ports.</para> - </sect2> - - <sect2> - <title>Situations where bridging is appropriate</title> - - <para>There are two common situations in which a bridge is used - today.</para> - - <sect3> - <title>High traffic on a segment</title> - - <para>Situation one is where your physical network segment is - overloaded with traffic, but you don't want for whatever reason to - subnet the network and interconnect the subnets with a - router.</para> - - <para>Let's consider an example of a newspaper where the Editorial and - Production departments are on the same subnetwork. The Editorial - users all use server A for file service, and the Production users - are on server B. An Ethernet is used to connect all users together, - and high loads on the network are slowing things down.</para> - - <para>If the Editorial users could be segregated on one network - segment and the Production users on another, the two network - segments could be connected with a bridge. Only the network traffic - destined for interfaces on the "other" side of the bridge would be - sent to the other network, reducing congestion on each network - segment.</para> - </sect3> - - <sect3> - <title>Filtering/traffic shaping firewall</title> - - <para>The second common situation is where firewall functionality is - needed without IP Masquerading (NAT).</para> - - <para>An example is a small company that is connected via DSL or ISDN - to their ISP. They have a 13 address global IP allocation for their - ISP and have 10 PCs on their network. In this situation, using a - router-based firewall is difficult because of subnetting - issues.</para> - - <para>A bridge-based firewall can be configured and dropped into the - path just downstream of their DSL/ISDN router without any IP - numbering issues.</para> - </sect3> - </sect2> - - <sect2> - <title>Configuring a bridge</title> - - <sect3> - <title>Network interface card selection</title> - - <para>A bridge requires at least two network cards to function. - Unfortunately, not all network interface cards as of FreeBSD 4.0 - support bridging. Read &man.bridge.4; for details on the cards that - are supported.</para> - - <para>Install and test the two network cards before continuing.</para> - </sect3> - - <sect3> - <title>Kernel configuration changes</title> - - <para>To enable kernel support for bridging, add the</para> - - <programlisting>options BRIDGE</programlisting> - - <para>statement to your kernel configuration file, and rebuild your - kernel.</para> - </sect3> - - <sect3> - <title>Firewall support</title> - - <para>If you are planning to use the bridge as a firewall, you will - need to add the IPFIREWALL option as well. Read <xref - linkend="firewalls"> for general information on configuring the - bridge as a firewall.</para> - - <para>If you need to allow non-IP packets (such as ARP) to flow - through the bridge, there is an undocumented firewall option that - must be set. This option is - <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>. Note that this - changes the default rule for the firewall to accept any packet. - Make sure you know how this changes the meaning of your ruleset - before you set it.</para> - </sect3> - - <sect3> - <title>Traffic shaping support</title> - - <para>If you want to use the bridge as a traffic shaper, you will need - to add the <literal>DUMMYNET</literal> option to your kernel - configuration. Read &man.dummynet.4; for further - information.</para> - </sect3> - </sect2> - - <sect2> - <title>Enabling the bridge</title> - - <para>Add the line</para> - - <programlisting>net.link.ether.bridge=1</programlisting> - - <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at - runtime. If you want the bridged packets to be filtered by ipfw, you - should also add</para> - - <programlisting>net.link.ether.bridge_ipfw=1</programlisting> - - <para>as well.</para> - </sect2> - - <sect2> - <title>Performance</title> - - <para>My bridge/firewall is a Pentium 90 with one 3Com 3C900B and one - 3C905B. The protected side of the network runs at 10mbps half duplex - and the connection between the bridge and my router (a Cisco 675) runs - at 100mbps full duplex. With no filtering enabled, I've found that - the bridge adds about 0.4 milliseconds of latency to pings from the - protected 10mbps network to the Cisco 675.</para> - </sect2> - - <sect2> - <title>Other information</title> - - <para>If you want to be able to telnet into the bridge from the network, - it is OK to assign one of the network cards an IP address. The - consensus is that assigning both cards an address is a bad - idea.</para> - - <para>If you have multiple bridges on your network, there cannot be more - than one path between any two workstations. Technically, this means - that there is no support for spanning tree link management.</para> - </sect2> - </sect1> - - <sect1 id="nfs"> - <title>NFS</title> - - <para><emphasis>Written by &a.unfurl;, 4 March 2000.</emphasis></para> - - <para>Among the many different file systems that FreeBSD supports is - a very unique type, the Network File System or NFS. NFS allows you - to share directories and files on one machine with one or more other - machines via the network they are attached to. Using NFS, users and - programs can access files on remote systems as if they were local - files.</para> - - <para>NFS has several benefits:</para> - - <itemizedlist> - <listitem> - <para>Local workstations dont need as much disk space because - commonly used data can be stored on a single machine and still - remain accessible to everyone on the network.</para> - </listitem> - - <listitem> - <para>There is no need for users to have unique home directories - on every machine on your network. Once they have an established - directory that is available via NFS it can be accessed from - anywhere.</para> - </listitem> - - <listitem> - <para>Storage devices such as floppies and CD-ROM drives can be - used by other machines on the network eliminating the need for - extra hardware.</para> - </listitem> - </itemizedlist> - - <sect2> - <title>How It Works</title> - - <para> NFS is composed of two sides – a client side and a - server side. Think of it as a want/have relationship. The client - <emphasis>wants</emphasis> the data that the server side - <emphasis>has</emphasis>. The server shares its data with the - client. In order for this system to function properly a few - processes have to be configured and running properly.</para> - - <para>The server has to be running the following daemons:</para> - - <itemizedlist> - <listitem> - <para><command>nfsd</command> - The NFS Daemon which services - requests from NFS clients.</para> - </listitem> - - <listitem> - <para><command>mountd</command> - The NFS Mount Daemon which - actually carries out requests that nfsd passes on to - it.</para> - </listitem> - </itemizedlist> - - <para>The client side only needs to run a single daemon:</para> - - <itemizedlist> - <listitem> - <para><command>nfsiod</command> - The NFS async I/O Daemon which - services requests from its NFS server.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Configuring NFS</title> - - <para>Luckily for us, on a FreeBSD system this setup is a snap. The - processes that need to be running can all be run at boot time with - a few modifications to your <filename>/etc/rc.conf</filename> - file.</para> - - <para>On the NFS server make sure you have:</para> - - <programlisting> -nfs_server_enable="YES" -nfs_server_flags="-u -t -n 4" -mountd_flags="-r"</programlisting> - - <para><command>mountd</command> is automatically run whenever the - NFS server is enabled. The <option>-u</option> and - <option>-t</option> flags to <command>nfsd</command> tell it to - serve UDP and TCP clients. The <option>-n 4</option> flag tells - <command>nfsd</command> to start 4 copies of itself.</para> - - <para>On the client, make sure you have:</para> - - <programlisting> -nfs_client_enable="YES" -nfs_client_flags="-n 4"</programlisting> - - <para>Like <command>nfsd</command>, the <option>-n 4</option> tells - <command>nfsiod</command> to start 4 copies of itself.</para> - - <para>The last configuration step requires that you create a file - called <filename>/etc/exports</filename>. The exports file - specifies which file systems on your server will be shared - (a.k.a., <quote>exported</quote>) and with what clients they will - be shared. Each line in the file specifies a file system to be - shared. There are a handful of options that can be used in this - file but I will only touch on a few of them. You can find out - about the rest in the &man.exports.5; man page.</para> - - <para>Here are a few example <filename>/etc/exports</filename> - entries:</para> - - <para>The following line exports <filename>/cdrom</filename> to - three silly machines that have the same domain name as the server - (hence the lack of a domain name for each) or have entries in your - <filename>/etc/hosts</filename> file. The <option>-ro</option> - flag makes the shared file system read-only. With this flag, the - remote system will not be able to make any changes to the the - shared file system.</para> - - <programlisting>/cdrom -ro moe larry curly</programlisting> - - <para>The following line exports <filename>/home</filename> to three - hosts by IP address. This is a useful setup if you have a - private network but do not have DNS running. The - <option>-alldirs</option> flag allows all the directories below - the specified file system to be exported as well.</para> - - <programlisting>/home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4</programlisting> - - <para>The following line exports <filename>/a</filename> to two - machines that have different domain names than the server. The - <option>-maproot=0</option> flag allows - the root user on the remote system to write to the shared - file system as root. Without the -maproot=0 flag even if - someone has root access on the remote system they won't - be able to modify files on the shared file system.</para> - - <programlisting>/a -maproot=0 host.domain.com box.example.com</programlisting> - - <para>In order for a client to share an exported file system it must - have permission to do so. Make sure your client is listed in your - <filename>/etc/exports</filename> file.</para> - - <para>Now that you have made all these changes you can just reboot - and let FreeBSD start everything for you at boot time or you can - run the following commands as root:</para> - - <para>On the NFS server:</para> - - <screen>&prompt.root; <userinput>nfsd -u -t -n 4</userinput> -&prompt.root; <userinput>mountd -r</userinput></screen> - - <para>On the NFS client:</para> - - <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen> - - <para>Now you should be ready to actually mount a remote file - system. This can be done one of two ways. In these examples the - server's name will be <literal>server</literal> and the client's - name will be <literal>client</literal>. If you just want to - temporarily mount a remote file system or just want to test out - your config you can run a command like this as root on the - client:</para> - - <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen> - - <para>This will mount <filename>/home</filename> on the server on - <filename>/mnt</filename> on the client. If everything is setup - correctly you should be able to go into /mnt on the client and see - all the files that are on the server.</para> - - <para>If you want to permanently (each time you reboot) mount a - remote file system you need to add it to your - <filename>/etc/fstab</filename> file. Here is an example - line:</para> - - <programlisting>server:/home /mnt nfs rw 0 0</programlisting> - - <para>Read the &man.fstab.5; man page for more options.</para> - </sect2> - - <sect2> - <title>Practical Uses</title> - - <para>There are many very cool uses for NFS. I use it quite a bit - on the LAN I admin. Here are a few ways I have found it to be - useful.</para> - - <para>I have several machines on my network but only one of them has - a CD-ROM drive. Why? Because I have that one CD-ROM drive shared - with all the others via NFS. The same can be done with floppy - drives.</para> - - <para>With so many machines on the network it gets old having your - personal files strewn all over the place. I have a central NFS - server that houses all user home directories and shares them with - the rest of the machines on the LAN, so no matter where I login I - have the same home directory.</para> - - <para>When you get to reinstalling FreeBSD on one of your machines, - NFS is the way to go. Just pop your distribution CD into your - file server and away you go.</para> - - <para>I have a common <filename>/usr/ports/distfiles</filename> - directory that all my machines share. That way when I go to - install a port that I already installed on a different machine I - do not have to download the source all over again.</para> - </sect2> - - <sect2> - <title>Problems integrating with other systems</title> - - <para><emphasis>Contributed by &a.jlind;.</emphasis></para> - - <para>Certain Ethernet adapters for ISA PC systems have limitations - which can lead to serious network problems, particularly with NFS. - This difficulty is not specific to FreeBSD, but FreeBSD systems - are affected by it.</para> - - <para>The problem nearly always occurs when (FreeBSD) PC systems are - networked with high-performance workstations, such as those made - by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS - mount will work fine, and some operations may succeed, but - suddenly the server will seem to become unresponsive to the - client, even though requests to and from other systems continue to - be processed. This happens to the client system, whether the - client is the FreeBSD system or the workstation. On many systems, - there is no way to shut down the client gracefully once this - problem has manifested itself. The only solution is often to - reset the client, because the NFS situation cannot be - resolved.</para> - - <para>Though the <quote>correct</quote> 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 - <emphasis>server</emphasis>, include the option - <option>-w=1024</option> on the mount from the client. If the - FreeBSD system is the <emphasis>client</emphasis>, then mount the - NFS file system with the option <option>-r=1024</option>. These - options may be specified using the fourth field of the - <filename>fstab</filename> entry on the client for automatic - mounts, or by using the <option>-o</option> parameter of the mount - command for manual mounts.</para> - - <para>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 - <emphasis>certain</emphasis> that your routers are routing the - necessary UDP information, or you will not get anywhere, no matter - what else you are doing.</para> - - <para>In the following examples, <hostid>fastws</hostid> is the host - (interface) name of a high-performance workstation, and - <hostid>freebox</hostid> is the host (interface) name of a FreeBSD - system with a lower-performance Ethernet adapter. Also, - <filename>/sharedfs</filename> will be the exported NFS - filesystem (see <command>man exports</command>), and - <filename>/project</filename> will be the mount point on the - client for the exported file system. In all cases, note that - additional options, such as <option>hard</option> or - <option>soft</option> and <option>bg</option> may be desirable in - your application.</para> - - <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as - the client: in <filename>/etc/fstab</filename> on freebox:</para> - - <programlisting> -fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting> - - <para>As a manual mount command on <hostid>freebox</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen> - - <para>Examples for the FreeBSD system as the server: in - <filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para> - - <programlisting> -freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting> - - <para>As a manual mount command on <hostid>fastws</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen> - - <para>Nearly any 16-bit Ethernet adapter will allow operation - without the above restrictions on the read or write size.</para> - - <para>For anyone who cares, here is what happens when the failure - occurs, which also explains why it is unrecoverable. NFS - typically works with a <quote>block</quote> size of 8k (though it - may do fragments of smaller sizes). Since the maximum Ethernet - packet is around 1500 bytes, the NFS <quote>block</quote> gets - split into multiple Ethernet packets, even though it is still a - single unit to the upper-level code, and must be received, - assembled, and <emphasis>acknowledged</emphasis> as a unit. The - high-performance workstations can pump out the packets which - comprise the NFS unit one right after the other, just as close - together as the standard allows. On the smaller, lower capacity - cards, the later packets overrun the earlier packets of the same - unit before they can be transferred to the host and the unit as a - whole cannot be reconstructed or acknowledged. As a result, the - workstation will time out and try again, but it will try again - with the entire 8K unit, and the process will be repeated, ad - infinitum.</para> - - <para>By keeping the unit size below the Ethernet packet size - limitation, we ensure that any complete Ethernet packet received - can be acknowledged individually, avoiding the deadlock - situation.</para> - - <para>Overruns may still occur when a high-performance workstations - is slamming data out to a PC system, but with the better cards, - such overruns are not guaranteed on NFS <quote>units</quote>. When - an overrun occurs, the units affected will be retransmitted, and - there will be a fair chance that they will be received, assembled, - and acknowledged.</para> - </sect2> - </sect1> - - <sect1 id="diskless"> - <title>Diskless Operation</title> - - <para><emphasis>Contributed by &a.martin;.</emphasis></para> - - <para><filename>netboot.com</filename>/<filename>netboot.rom</filename> - allow you to boot your FreeBSD machine over the network and run FreeBSD - without having a disk on your client. Under 2.0 it is now possible to - have local swap. Swapping over NFS is also still supported.</para> - - <para>Supported Ethernet cards include: Western Digital/SMC 8003, 8013, - 8216 and compatibles; NE1000/NE2000 and compatibles (requires - recompile)</para> - - <sect2> - <title>Setup Instructions</title> - - <procedure> - <step> - <para>Find a machine that will be your server. This machine will - require enough disk space to hold the FreeBSD 2.0 binaries and - have bootp, tftp and NFS services available. Tested - machines:</para> - - <itemizedlist> - <listitem> - <para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't - work)</para> - </listitem> - - <listitem> - <para>Sun/Solaris 2.3. (you may need to get bootp)</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Set up a bootp server to provide the client with IP, gateway, - netmask.</para> - - <programlisting> -diskless:\ - :ht=ether:\ - :ha=0000c01f848a:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=192.1.2.3:\ - :ip=192.1.2.4:\ - :gw=192.1.2.5:\ - :vm=rfc1048:</programlisting> - </step> - - <step> - <para>Set up a TFTP server (on same machine as bootp server) to - provide booting information to client. The name of this file is - <filename>cfg.<replaceable>X.X.X.X</replaceable></filename> (or - <filename>/tftpboot/cfg.<replaceable>X.X.X.X</replaceable></filename>, - it will try both) where <replaceable>X.X.X.X</replaceable> is the - IP address of the client. The contents of this file can be any - valid netboot commands. Under 2.0, netboot has the following - commands:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>help</entry> - <entry>print help list</entry> - </row> - - <row> - <entry>ip - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set client's IP address</entry> - </row> - - <row> - <entry>server - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set bootp/tftp server address</entry> - </row> - - <row> - <entry>netmask - <option><replaceable>X.X.X.X</replaceable></option></entry> - <entry>print/set netmask</entry> - </row> - - <row> - <entry>hostname <replaceable>name</replaceable></entry> - <entry>print/set hostname</entry> - </row> - - <row> - <entry>kernel - <option><replaceable>name</replaceable></option></entry> - <entry>print/set kernel name</entry> - </row> - - <row> - <entry>rootfs - <option><replaceable>ip:/fs</replaceable></option></entry> - <entry>print/set root filesystem</entry> - </row> - - <row> - <entry>swapfs - <option><replaceable>ip:/fs</replaceable></option></entry> - <entry>print/set swap filesystem</entry> - </row> - - <row> - <entry>swapsize - <option><replaceable>size</replaceable></option></entry> - <entry>set diskless swapsize in KBytes</entry> - </row> - - <row> - <entry>diskboot</entry> - <entry>boot from disk</entry> - </row> - - <row> - <entry>autoboot</entry> - <entry>continue boot process</entry> - </row> - - <row> - <entry>trans - <option>on</option>|<option>off</option></entry> - <entry>turn transceiver on|off</entry> - </row> - - <row> - <entry>flags - <option>b</option><option>c</option><option>d</option><option>h</option><option>s</option><option>v</option></entry> - <entry>set boot flags</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>A typical completely diskless cfg file might contain:</para> - - <programlisting> -rootfs 192.1.2.3:/rootfs/myclient -swapfs 192.1.2.3:/swapfs -swapsize 20000 -hostname myclient.mydomain</programlisting> - - <para>A cfg file for a machine with local swap might contain:</para> - - <programlisting> -rootfs 192.1.2.3:/rootfs/myclient -hostname myclient.mydomain</programlisting> - </step> - - <step> - <para>Ensure that your NFS server has exported the root (and swap if - applicable) filesystems to your client, and that the client has - root access to these filesystems A typical - <filename>/etc/exports</filename> file on FreeBSD might look - like:</para> - - <programlisting> -/rootfs/myclient -maproot=0:0 myclient.mydomain -/swapfs -maproot=0:0 myclient.mydomain</programlisting> - - <para>And on HP-UX:</para> - - <programlisting> -/rootfs/myclient -root=myclient.mydomain -/swapfs -root=myclient.mydomain</programlisting> - </step> - - <step> - <para>If you are swapping over NFS (completely diskless - configuration) create a swap file for your client using - <command>dd</command>. If your <command>swapfs</command> command - has the arguments <filename>/swapfs</filename> and the size 20000 - as in the example above, the swapfile for myclient will be called - <filename>/swapfs/swap.<replaceable>X.X.X.X</replaceable></filename> - where <replaceable>X.X.X.X</replaceable> is the client's IP addr, - e.g.:</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000</userinput></screen> - - <para>Also, the client's swap space might contain sensitive - information once swapping starts, so make sure to restrict read - and write access to this file to prevent unauthorized - access:</para> - - <screen>&prompt.root; <userinput>chmod 0600 /swapfs/swap.192.1.2.4</userinput></screen> - </step> - - <step> - <para>Unpack the root filesystem in the directory the client will - use for its root filesystem (<filename>/rootfs/myclient</filename> - in the example above).</para> - - <itemizedlist> - <listitem> - <para>On HP-UX systems: The server should be running HP-UX 9.04 - or later for HP9000/800 series machines. Prior versions do not - allow the creation of device files over NFS.</para> - </listitem> - - <listitem> - <para>When extracting <filename>/dev</filename> in - <filename>/rootfs/myclient</filename>, beware that some - systems (HPUX) will not create device files that FreeBSD is - happy with. You may have to go to single user mode on the - first bootup (press control-c during the bootup phase), cd - <filename>/dev</filename> and do a <command>sh ./MAKEDEV - all</command> from the client to fix this.</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Run <command>netboot.com</command> on the client or make an - EPROM from the <filename>netboot.rom</filename> file</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Using Shared <filename>/</filename> and <filename>/usr</filename> - filesystems</title> - - <para>At present there isn't an officially sanctioned way of doing this, - although I have been using a shared <filename>/usr</filename> - filesystem and individual <filename>/</filename> filesystems for each - client. If anyone has any suggestions on how to do this cleanly, - please let me and/or the &a.core; know.</para> - </sect2> - - <sect2> - <title>Compiling netboot for specific setups</title> - - <para>Netboot can be compiled to support NE1000/2000 cards by changing - the configuration in - <filename>/sys/i386/boot/netboot/Makefile</filename>. See the - comments at the top of this file.</para> - </sect2> - </sect1> - - <sect1 id="isdn"> - <title>ISDN</title> - - <para><emphasis>Last modified by &a.wlloyd;</emphasis>.</para> - - <para>A good resource for information on ISDN technology and hardware is - <ulink url="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN - Page</ulink>.</para> - - <para>A quick simple road map to ISDN follows:</para> - - <itemizedlist> - <listitem> - <para>If you live in Europe I suggest you investigate the ISDN card - section.</para> - </listitem> - - <listitem> - <para>If you are planning to use ISDN primarily to connect to the - Internet with an Internet Provider on a dial-up non-dedicated basis, - I suggest you look into Terminal Adapters. This will give you the - most flexibility, with the fewest problems, if you change - providers.</para> - </listitem> - - <listitem> - <para>If you are connecting two LANs together, or connecting to the - Internet with a dedicated ISDN connection, I suggest you consider - the stand alone router/bridge option.</para> - </listitem> - </itemizedlist> - - <para>Cost is a significant factor in determining what solution you will - choose. The following options are listed from least expensive to most - expensive.</para> - - <sect2> - <title>ISDN Cards</title> - - <para><emphasis>Contributed by &a.hm;.</emphasis></para> - - <para>This section is really only relevant to ISDN users in countries - where the DSS1/Q.931 ISDN standard is supported.</para> - - <para>Some growing number of PC ISDN cards are supported under FreeBSD - 2.2.x and up by the isdn4bsd driver package. It is still under - development but the reports show that it is successfully used all over - Europe.</para> - - <para>The latest isdn4bsd version is available from <ulink - url="ftp://isdn4bsd@ftp.consol.de/pub/">ftp://isdn4bsd@ftp.consol.de/pub/</ulink>, - the main isdn4bsd ftp site (you have to log in as user - <username>isdn4bsd</username> , give your mail address as the password - and change to the <filename>pub</filename> directory. Anonymous ftp - as user <username>ftp</username> or <username>anonymous</username> - will <emphasis>not</emphasis> give the desired result).</para> - - <para>Isdn4bsd allows you to connect to other ISDN routers using either - IP over raw HDLC or by using synchronous PPP. A telephone answering - machine application is also available.</para> - - <para>Many ISDN PC cards are supported, mostly the ones with a Siemens - ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola, - Cologne Chip Designs) is currently under development. For an - up-to-date list of supported cards, please have a look at the <ulink - url="ftp://isdn4bsd@ftp.consol.de/pub/README">README</ulink> - file.</para> - - <para>In case you are interested in adding support for a different ISDN - protocol, a currently unsupported ISDN PC card or otherwise enhancing - isdn4bsd, please get in touch with <email>hm@kts.org</email>.</para> - - <para>A majordomo maintained mailing list is available. To join the - list, send mail to &a.majordomo; and - specify:</para> - - <programlisting> -subscribe freebsd-isdn</programlisting> - - <para>in the body of your message.</para> - </sect2> - - <sect2> - <title>ISDN Terminal Adapters</title> - - <para>Terminal adapters(TA), are to ISDN what modems are to regular - phone lines.</para> - - <para>Most TA's use the standard hayes modem AT command set, and can be - used as a drop in replacement for a modem.</para> - - <para>A TA will operate basically the same as a modem except connection - and throughput speeds will be much faster than your old modem. You - will need to configure <link linkend="ppp">PPP</link> exactly the same - as for a modem setup. Make sure you set your serial speed as high as - possible.</para> - - <para>The main advantage of using a TA to connect to an Internet - Provider is that you can do Dynamic PPP. As IP address space becomes - more and more scarce, most providers are not willing to provide you - with a static IP anymore. Most stand-alone routers are not able to - accommodate dynamic IP allocation.</para> - - <para>TA's completely rely on the PPP daemon that you are running for - their features and stability of connection. This allows you to - upgrade easily from using a modem to ISDN on a FreeBSD machine, if you - already have PPP setup. However, at the same time any problems you - experienced with the PPP program and are going to persist.</para> - - <para>If you want maximum stability, use the kernel <link - linkend="ppp">PPP</link> option, not the user-land <link - linkend="userppp">iijPPP</link>.</para> - - <para>The following TA's are know to work with FreeBSD.</para> - - <itemizedlist> - <listitem> - <para>Motorola BitSurfer and Bitsurfer Pro</para> - </listitem> - - <listitem> - <para>Adtran</para> - </listitem> - </itemizedlist> - - <para>Most other TA's will probably work as well, TA vendors try to make - sure their product can accept most of the standard modem AT command - set.</para> - - <para>The real problem with external TA's is like modems you need a good - serial card in your computer.</para> - - <para>You should read the <link linkend="uart">serial ports</link> - section in the handbook for a detailed understanding of serial - devices, and the differences between asynchronous and synchronous - serial ports.</para> - - <para>A TA running off a standard PC serial port (asynchronous) limits - you to 115.2Kbs, even though you have a 128Kbs connection. To fully - utilize the 128Kbs that ISDN is capable of, you must move the TA to a - synchronous serial card.</para> - - <para>Do not be fooled into buying an internal TA and thinking you have - avoided the synchronous/asynchronous issue. Internal TA's simply have - a standard PC serial port chip built into them. All this will do, is - save you having to buy another serial cable, and find another empty - electrical socket.</para> - - <para>A synchronous card with a TA is at least as fast as a stand-alone - router, and with a simple 386 FreeBSD box driving it, probably more - flexible.</para> - - <para>The choice of sync/TA v.s. stand-alone router is largely a religious - issue. There has been some discussion of this in the mailing lists. - I suggest you search the <ulink - url="http://www.FreeBSD.org/search.html">archives</ulink> for the - complete discussion.</para> - </sect2> - - <sect2> - <title>Stand-alone ISDN Bridges/Routers</title> - - <para>ISDN bridges or routers are not at all specific to FreeBSD or any - other operating system. For a more complete description of routing - and bridging technology, please refer to a Networking reference - book.</para> - - <para>In the context of this page, I will use router and bridge - interchangeably.</para> - - <para>As the cost of low end ISDN routers/bridges comes down, it will - likely become a more and more popular choice. An ISDN router is a - small box that plugs directly into your local Ethernet network(or - card), and manages its own connection to the other bridge/router. It - has all the software to do PPP and other protocols built in.</para> - - <para>A router will allow you much faster throughput that a standard TA, - since it will be using a full synchronous ISDN connection.</para> - - <para>The main problem with ISDN routers and bridges is that - interoperability between manufacturers can still be a problem. If you - are planning to connect to an Internet provider, I recommend that you - discuss your needs with them.</para> - - <para>If you are planning to connect two lan segments together, ie: home - lan to the office lan, this is the simplest lowest maintenance - solution. Since you are buying the equipment for both sides of the - connection you can be assured that the link will work.</para> - - <para>For example to connect a home computer or branch office network to - a head office network the following setup could be used.</para> - - <example> - <title>Branch office or Home network</title> - - <para>Network is 10 Base T Ethernet. Connect router to network cable - with AUI/10BT transceiver, if necessary.</para> - - <!-- This should be a graphic --> - <programlisting> ----Sun workstation -| ----FreeBSD box -| ----Windows 95 (Do not admit to owning it) -| -Stand-alone router - | -ISDN BRI line</programlisting> - - <para>If your home/branch office is only one computer you can use a - twisted pair crossover cable to connect to the stand-alone router - directly.</para> - </example> - - <example> - <title>Head office or other lan</title> - - <para>Network is Twisted Pair Ethernet.</para> - - <!-- This should be a graphic --> - <programlisting> - -------Novell Server - | H | - | ---Sun - | | - | U ---FreeBSD - | | - | ---Windows 95 - | B | - |___---Stand-alone router - | - ISDN BRI line</programlisting> - </example> - - <para>One large advantage of most routers/bridges is that they allow you - to have 2 <emphasis>separate independent</emphasis> PPP connections to - 2 separate sites at the <emphasis>same</emphasis> time. This is not - supported on most TA's, except for specific(expensive) models that - have two serial ports. Do not confuse this with channel bonding, MPP - etc.</para> - - <para>This can be very useful feature, for example if you have an - dedicated ISDN connection at your office and would like to - tap into it, but don't want to get another ISDN line at work. A router - at the office location can manage a dedicated B channel connection - (64Kbs) to the internet, as well as a use the other B channel for a - separate data connection. The second B channel can be used for - dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel - for more bandwidth.</para> - - <para>An Ethernet bridge will also allow you to transmit more than just - IP traffic, you can also send IPX/SPX or whatever other protocols you - use.</para> - </sect2> - </sect1> - - <sect1 id="nis"> - <title>NIS/YP</title> - - <para><emphasis>Written by &a.unfurl;, 21 January 2000, enhanced - with parts and comments from Eric Ogren - <email>eogren@earthlink.net</email> and Udo Erdelhoff - <email>ue@nathan.ruhr.de</email> in June 2000.</emphasis></para> - - <sect2> - <title>What is it?</title> - - <para>NIS, which stands for Network Information Services, was - developed by Sun Microsystems to centralize adminstration of Unix - (originally SunOS) systems. It has now essentially become an - industry standard; all major Unices (Solaris, HP-UX, AIX, Linux, - NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para> - - <para>NIS was formerly known as Yellow Pages (or yp), but due to - copyright violations, Sun was forced to change the name.</para> - - <para>It is a RPC-based client/server system that allows a group - of machines within an NIS domain to share a common set of - configuration files. This permits a system administrator to set - up NIS client systems with only minimal configuration data and - add, remove or modify configuration data from a single - location.</para> - - <para>It is similar to Windows NT's domain system; although the - internal implementation of the two aren't at all similar, - the basic functionality can be compared.</para> - </sect2> - - <sect2> - <title>Terms/processes you should know</title> - - <para>There are several terms and several important user processes - that you will come across when - attempting to implement NIS on FreeBSD, whether you are trying to - create an NIS server or act an NIS client:</para> - - <itemizedlist> - <listitem> - <para><emphasis>The NIS domainname</emphasis>. An NIS master - server and all of its clients (including its slave servers) have - a NIS domainname. Similar to an NT domain name, the NIS - domainname does not have anything to do with DNS.</para> - </listitem> - <listitem> - <para><emphasis>portmap</emphasis>. <command>portmap</command> - must be running in order to enable RPC (Remote Procedure Call, a - network protocol used by NIS). If <command>portmap</command> is - not running, it will be impossible to run an NIS server, or to - act as an NIS client.</para> - </listitem> - <listitem> - <para><emphasis>ypbind</emphasis>. <command>ypbind</command> - “binds” an NIS client to its NIS server. - It will take the NIS domainname from the system, and - using RPC, connect to the server. <command>ypbind</command> is - the core of client-server communication in an NIS environment; if - <command>ypbind</command> dies on a client machine, it will not - be able to access the NIS server.</para> - </listitem> - <listitem> - <para><emphasis>ypserv</emphasis>. <command>ypserv</command>, - which should only be running on NIS servers, is the NIS server - process itself. If ypserv dies, then the server will no longer be - able to respond to NIS requests (hopefully, there is a slave - server to take over for it).</para> - - <note><para>There are some implementations of NIS (but not the - FreeBSD one), that don't try to reconnect to another server - if the server it used before dies. Often, the only thing - that helps in this case is to restart the server process (or - even the whole server) or the <command>ypbind</command> process - on the client.</para></note> - </listitem> - <listitem> - <para><emphasis>rpc.yppasswdd</emphasis>. - <command>rpc.yppasswdd</command>, another process that should - only be running on NIS master servers, is a daemon that will - allow NIS clients to change their NIS passwords. - If this daemon is not running, users will have to login to the - NIS master server and change their passwords there.</para> - </listitem> - - <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run - on the master --> - </itemizedlist> - </sect2> - - <sect2> - <title>How does it work?</title> - - <para>There are three types of hosts in an NIS environment; master - servers, slave servers, and clients. Servers act as a central - repository for host configuration information. Master servers - hold the authoritative copy of this information, while slave - servers mirror this information for redundancy. Clients rely on - the servers to provide this information to them.</para> - - <para>Information in many files can be shared in this manner. The - <filename>master.passwd</filename>, <filename>group</filename>, - and <filename>hosts</filename> files are commonly shared via NIS. - Whenever a process on a client needs information that would - normally be found in these files locally, it makes a query to the - server it is bound to, to get this information.</para> - - <sect3> - <title>Machine types</title> - - <itemizedlist> - <listitem> - <para>A <emphasis>NIS master server</emphasis>. - This server, analogous to a Windows - NT primary domain controller, maintains the files used by all - of the NIS clients. The <filename>passwd</filename>, - <filename>group</filename>, and other various files used by the - NIS clients live on the master server.</para> - - <note><para>It is possible for one machine to be an NIS - master server for more than one NIS domain. However, this will - not be covered in this introduction, which assumes a relatively - small-scale NIS environment.</para></note> - </listitem> - <listitem> - <para><emphasis>NIS slave servers</emphasis>. - Similar to NT's backup domain - controllers, NIS slave servers maintain copies of the NIS - master's data files. NIS slave servers provide the redundancy, - which is needed in important enviroments. They also help - to balance the load of the master server: NIS Clients always - attach to the NIS server, whose response they get first, and - this includes slave-server-replies.</para> - </listitem> - <listitem> - <para><emphasis>NIS clients</emphasis>. NIS clients, like most - NT workstations, authenticate against the NIS server (or the NT - domain controller in the NT Workstation case) to logon.</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2> - <title>Using NIS/YP</title> - - <para>This section will deal with setting up a sample NIS - environment.</para> - - <note><para>This section assumes that you are running FreeBSD 3.3 - or later. The instructions given here will - <emphasis>probably</emphasis> work for any version of FreeBSD greater - than 3.0, but there are no guarantees that this is - true.</para></note> - - - <sect3> - <title>Planning</title> - - <para>Let's assume that you are the administrator of a small - university lab. This lab, which consists of 15 FreeBSD machines, - currently has no centralised point of administration; each machine - has its own <filename>/etc/passwd</filename> and - <filename>/etc/master.passwd</filename>. These files are kept in - sync with each other only through manual intervention; - currently, when you add a user to the lab, you must run - <command>adduser</command> on all 15 machines. - Clearly, this has to change, so you have decided to convert the - lab to use NIS, using two of the machines as servers.</para> - - <para>Therefore, the configuration of the lab now looks something - like:</para> - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Machine name</entry> - <entry>IP address</entry> - <entry>Machine role</entry> - </row> - </thead> - <tbody> - <row> - <entry><hostid>ellington</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.2</hostid></entry> - <entry>NIS master</entry> - </row> - <row> - <entry><hostid>coltrane</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.3</hostid></entry> - <entry>NIS slave</entry> - </row> - <row> - <entry><hostid>basie</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.4</hostid></entry> - <entry>Faculty workstation</entry> - </row> - <row> - <entry><hostid>bird</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.5</hostid></entry> - <entry>Client machine</entry> - </row> - <row> - <entry><hostid>cli[1-11]</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry> - <entry>Other client machines</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If you are setting up a NIS scheme for the first time, it - is a good idea to think through how you want to go about it. No - matter what the size of your network, there are a few decisions - that need to be made.</para> - - <sect4> - <title>Choosing a NIS Domain Name</title> - - <para>This might not be the <quote>domainname</quote> that you - are used to. It is more accurately called the - <quote>NIS domainname</quote>. When a client broadcasts its - requests for info, it includes the name of the NIS domain - that it is part of. This is how multiple servers on one - network can tell which server should answer which request. - Think of the NIS domainname as the name for a group of hosts - that are related in someway way.</para> - - <para>Some organizations choose to use their Internet domainname - for their NIS domainname. This is not recommended as it can - cause confusion when trying to debug network problems. The - NIS domainname should be unique within your network and it is - helpful if it describes the group of machines it represents. - For example, the Art department at Acme Inc. might be in the - "acme-art" NIS domain. For this example, assume you have - chosen the name <emphasis>test-domain</emphasis>.</para> - - <para>However, some operating systems (notably SunOS) use their - NIS domain name as their Internet domain name. - If one or more machines on your network have this restriction, - you <emphasis>must</emphasis> use the Internet domain name as - your NIS domain name.</para> - </sect4> - - <sect4> - <title>Physical Server Requirements</title> - - <para>There are several things to keep in mind when choosing a - machine to use as a NIS server. One of the unfortunate things - about NIS is the level of dependency the clients have on the - server. If a client cannot contact the server for its NIS - domain, very often the machine becomes unusable. The lack of - user and group information causes most systems to temporarily - freeze up. With this in mind you should make sure to choose a - machine that won't be prone to being rebooted regularly, or - one that might be used for development. The NIS server should - ideally be a stand alone machine whose sole purpose in life is - to be an NIS server. If you have a network that is not very - heavily used, it is acceptable to put the NIS server on a - machine running other services, just keep in mind that if the - NIS server becomes unavailable, it will affect - <emphasis>all</emphasis> of your NIS clients adversely.</para> - </sect4> - </sect3> - - <sect3> - <title>NIS Servers</title> - - <para> The canonical copies of all NIS information are stored on - a single machine called the NIS master server. The databases - used to store the information are called NIS maps. In FreeBSD, - these maps are stored in - <filename>/var/yp/[domainname]</filename> where - <filename>[domainname]</filename> is the name of the NIS domain - being served. A single NIS server can support several domains - at once, therefore it is possible to have several such - directories, one for each supported domain. Each domain will - have its own independent set of maps.</para> - - <para>NIS master and slave servers handle all NIS requests with - the <command>ypserv</command> daemon. <command>Ypserv</command> - is responsible for receiving incoming requests from NIS clients, - translating the requested domain and map name to a path to the - corresponding database file and transmitting data from the - database back to the client.</para> - - <sect4> - <title>Setting up a NIS master server</title> - - <para>Setting up a master NIS server can be relatively straight - forward, depending on your needs. FreeBSD comes with support - for NIS out-of-the-box. All you need is to add the following - lines to <filename>/etc/rc.conf</filename>, and FreeBSD will - do the rest for you.</para> - - <itemizedlist> - <listitem> - <para><programlisting>nisdomainname="test-domain"</programlisting> - This line will set the NIS domainname to - <emphasis>test-domain</emphasis> - upon network setup (e.g. after reboot).</para> - </listitem> - <listitem> - <para><programlisting>nis_server_enable="YES"</programlisting> - This will tell FreeBSD to start up the NIS server processes - when the networking is next brought up.</para> - </listitem> - <listitem> - <para><programlisting>nis_yppasswdd_enable="YES"</programlisting> - This will enable the <command>rpc.yppasswdd</command> - daemon, which, as mentioned above, will allow users to - change their NIS password from a client machine.</para> - </listitem> - </itemizedlist> - - <para>Now, everything you have to do is to run the command - <command>/etc/netstart</command> as superuser. It will - setup everything for you, using the values you defined in - <filename>/etc/rc.conf</filename>.</para> - </sect4> - - <sect4> - <title>Initializing the NIS maps</title> - - <para>The <emphasis>NIS maps</emphasis> are database files, - that are kept in the <filename>/var/yp</filename> directory. - They are generated from configuration files in the - <filename>/etc</filename> directory of the NIS master, with one - exception: the <filename>/etc/master.passwd</filename> file. - This is for a good reason; you don't want to propogate - passwords to your root and other administrative accounts to - all the servers in the NIS domain. Therefore, before we - initialize the NIS maps, you should:</para> - - <screen> -&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput> -&prompt.root; <userinput>cd /var/yp</userinput> -&prompt.root; <userinput>vi master.passwd</userinput> - </screen> - - <para>You should remove all entries regarding system accounts - (bin, tty, kmem, games, etc), as well as any accounts that you - don't want to be propogated to the NIS clients (for example - root and any other UID 0 (superuser) accounts).</para> - - <note><para>Make sure the - <filename>/var/yp/master.passwd</filename> is neither group - nor world readable (mode 600)! Use the - <command>chmod</command> command, if appreciate.</para></note> - - <para>When you have finished, it's time to initialize the NIS - maps! FreeBSD includes a script named - <command>ypinit</command> to do this for you - (see its man page for more information). Note that this - script is available on most UNIX OSs, but not on all. - On Digital Unix/Compaq Tru64 Unix it is called - <command>ypsetup</command>. - Because we are generating maps for an NIS master, we are - going to pass the <option>-m</option> option to - <command>ypinit</command>. - To generate the NIS maps, assuming you already performed - the steps above, run:</para> - - <screen> -ellington&prompt.root; <userinput>ypinit -m test-domain</userinput> -Server Type: MASTER Domain: test-domain -Creating an YP server will require that you answer a few questions. -Questions will all be asked at the beginning of the procedure. -Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput> -Ok, please remember to go back and redo manually whatever fails. -If you don't, something might not work. -At this point, we have to construct a list of this domains YP servers. -rod.darktech.org is already known as master server. -Please continue to add any slave servers, one per line. When you are -done with the list, type a <control D>. -master server : ellington -next host to add: <userinput>coltrane</userinput> -next host to add: <userinput>^D</userinput> -The current list of NIS servers looks like this: -ellington -coltrane -Is this correct? [y/n: y] <userinput>y</userinput> - -[..output from map generation..] - -NIS Map update completed. -ellington has been setup as an YP master server without any errors. - </screen> - - <para><command>ypinit</command> should have created - <filename>/var/yp/Makefile</filename> from - <filename>/var/yp/Makefile.dist</filename>. - When created, this file assumes that you are operating - in a single server NIS environment with only FreeBSD - machines. Since <emphasis>test-domain</emphasis> has - a slave server as well, you must edit - <filename>/var/yp/Makefile</filename>:</para> - - <screen> -ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput> - </screen> - - <para>You should comment out the line that says `NOPUSH = - "True"' (if it is not commented out already).</para> - </sect4> - - <sect4> - <title>Setting up a NIS slave server</title> - - <para>Setting up an NIS slave server is even more simple than - setting up the master. Logon to the slave server and edit the - file <filename>/etc/rc.conf</filename> as you did before. - The only difference is that we now must use the - <option>-s</option> option when running <command>ypinit</command>. - The <option>-s</option> option requires the name of the NIS - master be passed to it as well, so our command line looks - like:</para> - - <screen> -coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput> - -Server Type: SLAVE Domain: test-domain Master: ellington - -Creating an YP server will require that you answer a few questions. -Questions will all be asked at the beginning of the procedure. - -Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput> - -Ok, please remember to go back and redo manually whatever fails. -If you don't, something might not work. -There will be no further questions. The remainder of the procedure -should take a few minutes, to copy the databases from ellington. -Transferring netgroup... -ypxfr: Exiting: Map successfully transferred -Transferring netgroup.byuser... -ypxfr: Exiting: Map successfully transferred -Transferring netgroup.byhost... -ypxfr: Exiting: Map successfully transferred -Transferring master.passwd.byuid... -ypxfr: Exiting: Map successfully transferred -Transferring passwd.byuid... -ypxfr: Exiting: Map successfully transferred -Transferring passwd.byname... -ypxfr: Exiting: Map successfully transferred -Transferring group.bygid... -ypxfr: Exiting: Map successfully transferred -Transferring group.byname... -ypxfr: Exiting: Map successfully transferred -Transferring services.byname... -ypxfr: Exiting: Map successfully transferred -Transferring rpc.bynumber... -ypxfr: Exiting: Map successfully transferred -Transferring rpc.byname... -ypxfr: Exiting: Map successfully transferred -Transferring protocols.byname... -ypxfr: Exiting: Map successfully transferred -Transferring master.passwd.byname... -ypxfr: Exiting: Map successfully transferred -Transferring networks.byname... -ypxfr: Exiting: Map successfully transferred -Transferring networks.byaddr... -ypxfr: Exiting: Map successfully transferred -Transferring netid.byname... -ypxfr: Exiting: Map successfully transferred -Transferring hosts.byaddr... -ypxfr: Exiting: Map successfully transferred -Transferring protocols.bynumber... -ypxfr: Exiting: Map successfully transferred -Transferring ypservers... -ypxfr: Exiting: Map successfully transferred -Transferring hosts.byname... -ypxfr: Exiting: Map successfully transferred - -coltrane has been setup as an YP slave server without any errors. -Don't forget to update map ypservers on ellington.</screen> - - <para>You should now have a directory called - <filename>/var/yp/test-domain</filename>. Copies of the NIS - master server's maps should be in this directory. You will - need to make sure that these stay updated. The following - <filename>/etc/crontab</filename> entries on your slave - servers should do the job:</para> - - <programlisting> -20 * * * * root /usr/libexec/ypxfr passwd.byname -21 * * * * root /usr/libexec/ypxfr passwd.byuid</programlisting> - - <para>These two lines force the slave to sync its maps with - the maps on the master server. Although this is - not mandatory, because the master server - tries to make sure any changes to it's NIS maps are - communicated to it's slaves, the password - information is so vital to systems that depend on the server, - that it is a good idea to force the updates. This is more - important on busy networks where map updates might not always - complete.</para> - - <para>Now, run the command <command>/etc/netstart</command> on the - slave server as well, which again starts the NIS server.</para> - </sect4> - </sect3> - - <sect3> - <title>NIS Clients</title> - - <para> An NIS client establishes what is called a binding to a - particular NIS server using the - <command>ypbind</command> daemon. - <command>ypbind</command> checks the system's default - domain (as set by the <command>domainname</command> command), - and begins broadcasting RPC requests on the local network. - These requests specify the name of the domain for which - <command>ypbind</command> is attempting to establish a binding. - If a server that has been configured to serve the requested - domain receives one of the broadcasts, it will respond to - <command>ypbind</command>, which will record the server's - address. If there are several servers available (a master and - several slaves, for example), <command>ypbind</command> will - use the address of the first one to respond. From that point - on, the client system will direct all of its NIS requests to - that server. <command>Ypbind</command> will - occasionally <quote>ping</quote> the server to make sure it is - still up and running. If it fails to receive a reply to one of - its pings within a reasonable amount of time, - <command>ypbind</command> will mark the domain as unbound and - begin broadcasting again in the hopes of locating another - server.</para> - - <sect4> - <title>Setting up an NIS client</title> - - <para>Setting up a FreeBSD machine to be a NIS client is fairly - straight forward.</para> - - <itemizedlist> - <listitem> - <para>Edit the file <filename>/etc/rc.conf</filename> and - add the following lines in order to set the NIS domainname - and start <command>ypbind</command> upon network - startup:</para> - - <programlisting> -nisdomainname="test-domain" -nis_client_enable="YES"</programlisting> - </listitem> - - <listitem> - <para>To import all possible password entries from the NIS - server, add this line to your - <filename>/etc/master.passwd</filename> file, using - <command>vipw</command>:</para> - - <programlisting>+:::::::::</programlisting> - - <note> - <para>This line will afford anyone with a valid account in - the NIS server's password maps an account. There are - many ways to configure your NIS client by changing this - line. See the <link linkend="netgroups">netgroups - part</link> below for more information. - For more detailed reading see O'Reilly's book on - <literal>Managing NFS and NIS</literal>.</para> - </note> - </listitem> - - <listitem> - <para>To import all possible group entries from the NIS - server, add this line to your - <filename>/etc/group</filename> file:</para> - - <programlisting>+:*::</programlisting> - </listitem> - </itemizedlist> - - <para>After completing these steps, you should be able to run - <command>ypcat passwd</command> and see the NIS server's - passwd map.</para> - </sect4> - </sect3> - </sect2> - - <sect2> - <title>NIS Security</title> - - <para>In general, any remote user can issue an RPC to ypserv and - retrieve the contents of your NIS maps, provided the remote user - knows your domainname. To prevent such unauthorized transactions, - ypserv supports a feature called securenets which can be used to - restrict access to a given set of hosts. At startup, ypserv will - attempt to load the securenets information from a file called - <filename>/var/yp/securenets</filename>.</para> - - <note> - <para>This path varies depending on the path specified with the - <option>-p</option> option. This file contains entries that - consist of a network specification and a network mask separated - by white space. Lines starting with <quote>#</quote> are - considered to be comments. A sample securenets file might look - like this:</para> - </note> - - <programlisting> -# allow connections from local host -- mandatory -127.0.0.1 255.255.255.255 -# allow connections from any host -# on the 192.168.128.0 network -192.168.128.0 255.255.255.0 -# allow connections from any host -# between 10.0.0.0 to 10.0.15.255 -# this includes the machines in the testlab -10.0.0.0 255.255.240.0</programlisting> - - <para>If ypserv receives a request from an address that matches one - of these rules, it will process the request normally. If the - address fails to match a rule, the request will be ignored and a - warning message will be logged. If the - <filename>/var/yp/securenets</filename> file does not exist, - ypserv will allow connections from any host.</para> - - <para>The ypserv program also has support for Wietse Venema's - <application>tcpwrapper</application> package. This allows the - administrator to use the tcpwrapper configuration files for access - control instead of <filename>/var/yp/securenets</filename>.</para> - - <note> - <para>While both of these access control mechanisms provide some - security, they, like the privileged port test, are - vulnerable to <quote>IP spoofing</quote> attacks. All - NIS-related traffic should be blocked at your firewall.</para> - - <para>Servers using <filename>/var/yp/securenets</filename> - may fail to serve legitimate NIS clients with archaic TCP/IP - implementations. Some of these implementations set all - host bits to zero when doing broadcasts and/or fail to - observe the subnet mask when calculating the broadcast - address. While some of these problems can be fixed by - changing the client configuration, other problems may force - the retirement of the client systems in question or the - abandonment of <filename>/var/yp/securenets</filename>.</para> - - <para>Using <filename>/var/yp/securenets</filename> on a - server with such an archaic implementation of TCP/IP is a - really bad idea and will lead to loss of NIS functionality - for large parts of your network.</para> - - <para>The use of the <application>tcpwrapper</application> - package increases the latency of your NIS server. The - additional delay may be long enough to cause timeouts in - client programs, especially in busy networks or with slow - NIS servers. If one or more of your client systems - suffers from these symptoms, you should convert the client - systems in question into NIS slave servers and force them - to bind to themselves.</para> - </note> - </sect2> - - <sect2> - <title>Barring some users from logging on</title> - - <para>In our lab, there is a machine <hostid>basie</hostid> that is - supposed to be a faculty only workstation. We don't want to take this - machine out of the NIS domain, yet the <filename>passwd</filename> - file on the master NIS server contains accounts for both faculty and - students. What can we do?</para> - - <para>There is a way to bar specific users from logging on to a - machine, even if they are present in the NIS database. To do this, - all you must do is add - <emphasis>-<replaceable>username</replaceable></emphasis> to the end of - the <filename>/etc/master.passwd</filename> file on the client - machine, where <replaceable>username</replaceable> is the username of - the user you wish to bar from logging in. This should preferably be - done using <command>vipw</command>, since <command>vipw</command> - will sanity check your changes to - <filename>/etc/master.passwd</filename>, as well as - automatically rebuild the password database when you - finish editing. For example, if we wanted to bar user - <emphasis>bill</emphasis> from logging on to <hostid>basie</hostid> - we would:</para> - - <screen> -basie&prompt.root; <userinput>vipw</userinput> -<userinput>[add -bill to the end, exit]</userinput> -vipw: rebuilding the database... -vipw: done - -basie&prompt.root; <userinput>cat /etc/master.passwd</userinput> - -root:[password]:0:0::0:0:The super-user:/root:/bin/csh -toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh -daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin -operator:*:2:5::0:0:System &:/:/sbin/nologin -bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin -tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin -kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin -games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin -news:*:8:8::0:0:News Subsystem:/:/sbin/nologin -man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin -bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin -uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico -xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin -pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin -nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin -+::::::::: --bill - -basie&prompt.root;</screen> - </sect2> - - <sect2 id="netgroups"> - <title>Using netgroups</title> - - <para><emphasis>The netgroups part was contributed by - Udo Erdelhoff <email>ue@nathan.ruhr.de</email> in July - 2000.</emphasis></para> - - <para>The method shown in the previous chapter works reasonably - well if you need special rules for a very small number of - users and/or machines. On larger networks, you - <emphasis>will</emphasis> forget to bar some users from logging - onto sensitive machines, or you may even have to modify each - machine separately, thus loosing the main benefit of NIS, - <emphasis>centralised</emphasis> administration.</para> - - <para>The NIS developers' solution for this problem is called - <emphasis>netgroups</emphasis>. Their purpose and semantics - can be compared to the normal groups used by Unix file - systems. The main differences are the lack of a numeric id - and the ability to define a netgroup by including both user - accounts and other netgroups.</para> - - <para>Netgroups were developed to handle large, complex networks - with hundreds of users and machines. On one hand, this is - a Good Thing if you are forced to deal with such a situation. - On the other hand, this complexity makes it almost impossible to - explain netgroups with really simple examples. The example - used in the remainder of this chapter demonstrates this - problem.</para> - - <para>Let us assume that your successful introduction of NIS in - your laboratory caught your superiors' interest. Your next - job is to extend your NIS domain to cover some of the other - machines on campus. The two tables contain the names of the - new users and new machines as well as brief descriptions of - them.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>User Name(s)</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>alpha, beta</entry> - <entry>Normal employees of the IT department</entry> - </row> - - <row> - <entry>charlie, delta</entry> - <entry>The new apprentices of the IT department</entry> - </row> - - <row> - <entry>echo, foxtrott, golf, ...</entry> - <entry>Ordinary employees</entry> - </row> - - <row> - <entry>able, baker, ...</entry> - <entry>The current interns</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Machine Name(s)</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <!-- Names taken from "Good Omens" by Neil Gaiman and Terry - Pratchett. Many thanks for a brilliant book. --> - <entry>war, death, famine, polution</entry> - <entry>Your most important servers. Only the IT - employees are allowed to log onto these - machines.</entry> - </row> - <row> - <!-- gluttony was omitted because it was too fat ;-) --> - <entry>pride, greed, envy, wraith, lust, sloth</entry> - <entry>Less important servers. All members of the IT - department are allowed to login onto these machines.</entry> - </row> - - <row> - <entry>one, two, three, four, ...</entry> - <entry>Ordinary workstations. Only the - <emphasis>real</emphasis> employees are allowed to use - these machines.</entry> - </row> - - <row> - <entry>trashcan</entry> - <entry>A very old machine without any critcal data. - Even the intern is allowed to use this box.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If you tried to implement these restrictions by separately - blocking each user, you would have to add one - -<replaceable>user</replaceable> line to each system's passwd - for each user who is not allowed to login onto that system. - If you forget just one entry, you could be in trouble. It may - feasible to do this correctly during the initial setup, - however you <emphasis>will</emphasis> eventually forget to add - the lines for new users during day-to-day operations. After - all, Murphy was an optimist.</para> - - <para>Handling this situation with netgroups offers several - advantages. Each user need not be handled separately; - you assign a user to one or netgroup and allow or forbid - logins for all members of the netgroup. If you add a new - machine, you will only have to define login restrictions for - netgroups. If a new user is added, you will only have to add - the user to one or more netgroups. Those changes are - independent of each other; no more <quote>for each combination - of user and machine do...</quote> If your NIS setup is planned - carefully, you will only have to modify exactly one central - configuration file to grant or deny access to machines.</para> - - <para>The first step is the initialisation of the NIS map - netgroup. FreeBSD's ypinit does not create this map by - default, but its NIS implementation will support it once it has - been created. To create an empty map, simply type</para> - - <screen> -ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput> - </screen> - - <para>and start adding content. For our example, we need at - least four netgroups: IT employees, IT apprentices, normal - employees and interns.</para> - - <programlisting> -IT_EMP (,alpha,test-domain) (,beta,test-domain) -IT_APP (,charlie,test-domain) (,delta,test-domain) -USERS (,echo,test-domain) (,foxtrott,test-domain) \ - (,golf,test-domain) -INTERNS (,able,test-domain) (,baker,test-domain) - </programlisting> - - <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc. - are the names of the netgroups. Each bracketed group adds - one or more user accounts to it. The three fields inside a - group are:</para> - - <orderedlist> - <listitem> - <para>The name of the host(s) where the following items are - valid. If you do not specify a hostname, the entry is - valid on all hosts. If you do specify a hostname, you - will a realm of darkness, horror and utter confusion.</para> - </listitem> - - <listitem> - <para>The name of the account that belongs to this - netgroup.</para> - </listitem> - - <listitem> - <para>The NIS domain for the account. You can import - accounts from other NIS domains into your netgroup if you - are one of unlucky fellows with more than one NIS - domain.</para> - </listitem> - </orderedlist> - - <para>Each of this fields can contain wildcards, see - &man.netgroup.5; for details.</para> - - <note> - <para>Netgroup names longer than 8 characters should not be - used, especially if you have machines running other - operating systems within your NIS domain. The names are - case sensitive; using capital letters for your netgroup - names is an easy way to distinguish between user, machine - and netgroup names.</para> - - <para>Some NIS clients (other than FreeBSD) cannot handle - netgroups with a large number of entries. For example, some - older versions of SunOS start to cause trouble if a netgroup - contains more than 15 <emphasis>entries</emphasis>. You can - circumvent this limit by creating several sub-netgroups with - 15 users or less and a real netgroup that consists of the - sub-netgroups:</para> - - <programlisting> -BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] -BIGGRP2 (,joe16,domain) (,joe17,domain) [...] -BIGGRP3 (,joe32,domain) (,joe33,domain) -BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3 - </programlisting> - - <para>You can repeat this process if you need more than 225 - users within a single netgroup.</para> - </note> - - <para>Activating and distributing your new NIS map is - easy:</para> - - <screen> -ellington&prompt.root; <userinput>cd /var/yp</userinput> -ellington&prompt.root; <userinput>make</userinput> - </screen> - - <para>This will generate the three NIS maps - <filename>netgroup</filename>, - <filename>netgroup.byhost</filename> and - <filename>netgroup.byuser</filename>. Use &man.ypcat.1; to - check if your new NIS map are available:</para> - - <screen> -ellington&prompt.user; <userinput>ypcat -k netgroup</userinput> -ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput> -ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput> - </screen> - - <para>The output of the first command should resemble the - contents of <filename>/var/yp/netgroup</filename>. The second - command will not produce output if you have not specified - host-specific netgroups. The third command can be used to - get the list of netgroups for a user.</para> - - <para>The client setup is quite simple. To configure the server - <replaceable>war</replaceable>, you only have to start - &man.vipw.8; and replace the line</para> - - <programlisting> -+::::::::: - </programlisting> - - <para>with</para> - - <programlisting> -+@IT_EMP::::::::: - </programlisting> - - <para>Now, only the data for the users defined in the netgroup - <replaceable>IT_EMP</replaceable> is imported into - <replaceable>war</replaceable>'s password database and only - these users are allowed to login.</para> - - <para>Unfortunately, this limitation also applies to the ~ - function of the shell and all routines converting between user - names and numerical user ids. In other words, cd - ~<replaceable>user</replaceable> will not work, <command>ls - -l</command> will show the numerical id instead of the - username and <command>find . -user joe -print</command> will - fail with <quote>No such user</quote>. To fix this, you will - have to import all user entries <emphasis>without - allowing them to login onto your servers</emphasis>.</para> - - <para>This can be achieved by adding another line to - <filename>/etc/master.passwd</filename>. This line should - contain <literal>+:::::::::/sbin/nologin</literal>, meaning - <quote>Import all entries but replace the shell with - <filename>/sbin/nologin</filename> in the imported - entries</quote>. You can replace any field - in the passwd entry by placing a default value in your - <filename>/etc/master.passwd</filename>.</para> - - <!-- Been there, done that, got the scars to prove it - ue --> - <warning> - <para>Make sure that the line - <literal>+:::::::::/sbin/nologin</literal> is placed after - <literal>+@IT_EMP:::::::::</literal>. Otherwise, all user - accounts imported from NIS will have /sbin/nologin as their - login shell.</para> - </warning> - - <para>After this change, you will only have to change one NIS - map if a new employee joins the IT department. You could use - a similar approach for the less important servers by replacing - the old <literal>+:::::::::</literal> in their local version - of <filename>/etc/master.passwd</filename> with something like - this:</para> - - <programlisting> -+@IT_EMP::::::::: -+@IT_APP::::::::: -+:::::::::/sbin/nologin - </programlisting> - - <para>The corresponding lines for the normal workstations - could be:</para> - - <programlisting> -+@IT_EMP::::::::: -+@USERS::::::::: -+:::::::::/sbin/nologin - </programlisting> - - <para>And everything would be fine until there is a policy - change a few weeks later: The IT department starts hiring - interns. The IT interns are allowed to use the normal - workstations and the less important servers; and the IT - apprentices are allowed to login onto the main servers. You - add a new netgroup IT_INTERN, add the new IT interns to this - netgroup and start to change the config on each and every - machine... As the old saying goes: <quote>Errors in - centralised planning lead to global mess</quote>.</para> - - <para>NIS' ability to create netgroups from other netgroups can - be used to prevent situations like these. One possibility - is the creation of role-based netgroups. For example, you - could create a netgroup called - <replaceable>BIGSRV</replaceable> to define the login - restrictions for the important servers, another netgroup - called <replaceable>SMALLSRV</replaceable> for the less - important servers and a third netgroup called - <replaceable>USERBOX</replaceable> for the normal - workstations. Each of these netgroups contains the netgroups - that are allowed to login onto these machines. The new - entries for your NIS map netgroup should look like this:</para> - - <programlisting> -BIGSRV IT_EMP IT_APP -SMALLSRV IT_EMP IT_APP ITINTERN -USERBOX IT_EMP ITINTERN USERS - </programlisting> - - <para>This method of defining login restrictions works - reasonably well if you can define groups of machines with - identical restrictions. Unfortunately, this is the exception - and not the rule. Most of the time, you will need the ability - to define login restrictions on a per-machine basis.</para> - - <para>Machine-specific netgroup definitions are the other - possibility to deal with the policy change outlined above. In - this scenario, the <filename>/etc/master.passwd</filename> of - each box contains two lines starting with ``+''. The first of - them adds a netgroup with the accounts allowed to login onto - this machine, the second one adds all other accounts with - <filename>/sbin/nologin</filename> as shell. It is a good - idea to use the ALL-CAPS version of the machine name as the - name of the netgroup. In other words, the lines should look - like this:</para> - - <programlisting> -+@<replaceable>BOXNAME</replaceable>::::::::: -+:::::::::/sbin/nologin - </programlisting> - - <para>Once you have completed this task for all your machines, - you will not have to modify the local versions of - <filename>/etc/master.passwd</filename> ever again. All - further changes can be handled by modifying the NIS map. Here - is an example of a possible netgroup map for this - scenario with some additional goodies.</para> - - <programlisting> -# Define groups of users first -IT_EMP (,alpha,test-domain) (,beta,test-domain) -IT_APP (,charlie,test-domain) (,delta,test-domain) -DEPT1 (,echo,test-domain) (,foxtrott,test-domain) -DEPT2 (,golf,test-domain) (,hotel,test-domain) -DEPT3 (,india,test-domain) (,juliet,test-domain) -ITINTERN (,kilo,test-domain) (,lima,test-domain) -D_INTERNS (,able,test-domain) (,baker,test-domain) -# -# Now, define some groups based on roles -USERS DEPT1 DEPT2 DEPT3 -BIGSRV IT_EMP IT_APP -SMALLSRV IT_EMP IT_APP ITINTERN -USERBOX IT_EMP ITINTERN USERS -# -# And a groups for a special tasks -# Allow echo und golf to access our anti-virus-machine -SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain) -# -# machine-based netgroups -# Our main servers -WAR BIGSRV -FAMINE BIGSRV -# User india needs access to this server -POLUTION BIGSRV (,india,test-domain) -# -# This one is really important and needs more access restrictions -DEATH IT_EMP -# -# The anti-virus-machine mentioned above -ONE SECURITY -# -# Restrict a machine to a single user -TWO (,hotel,test-domain) -# [...more groups to follow] - </programlisting> - - <para>If you are using some kind of database to manage your user - accounts, you should be able to create the first part of the - map with your database's report tools. This way, new users - will automatically have access to the boxes.</para> - - <para>One last word of caution: It may not always be advisable - to use machine-based netgroups. If you are deploying a couple - dozen or even hundreds of identical machines for student labs, - you should use role-based netgroups instead of machine-based - netgroups to keep the size of the NIS map within reasonable - limits.</para> - </sect2> - - <sect2> - <title>Important things to remember</title> - - <para>There are still a couple of things that you will need to do - differently now that you are in an NIS environment.</para> - - <itemizedlist> - <listitem> - <para>Every time you wish to add a user to the lab, you - must add it to the master NIS server <emphasis>only</emphasis>, - and <emphasis>you must remember to rebuild the NIS - maps</emphasis>. If you forget to do this, the new user will - not be able to login anywhere except on the NIS master. - For example, if we needed to add a new user - “jsmith” to the lab, we would:</para> - - <screen> -&prompt.root; <userinput>pw useradd jsmith</userinput> -&prompt.root; <userinput>cd /var/yp</userinput> -&prompt.root; <userinput>make test-domain</userinput></screen> - - <para>You could also run <command>adduser jsmith</command> instead - of <command>pw useradd jsmith</command>.</para> - </listitem> - <listitem> - <para><emphasis>Keep the administration accounts out of the NIS - maps</emphasis>. You don't want to be propogating administrative - accounts and passwords to machines that will have users that - shouldn't have access to those accounts.</para> - </listitem> - <listitem> - <para><emphasis>Keep the NIS master and slave - secure, and minimize their downtime</emphasis>. - If somebody either hacks or simply turns off - these machines, they have effectively rendered many people without - the ability to login to the lab.</para> - - <para>This is the chief weakness of any centralised administration - system, and it is probably the most important weakness. If you do - not protect your NIS servers, you will have a lot of angry - users!</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>NIS v1 compatibility</title> - - <para> FreeBSD's <application>ypserv</application> has some support - for serving NIS v1 clients. FreeBSD's NIS implementation only - uses the NIS v2 protocol, however other implementations include - support for the v1 protocol for backwards compatibility with older - systems. The <application>ypbind</application> daemons supplied - with these systems will try to establish a binding to an NIS v1 - server even though they may never actually need it (and they may - persist in broadcasting in search of one even after they receive a - response from a v2 server). Note that while support for normal - client calls is provided, this version of ypserv does not handle - v1 map transfer requests; consequently, it can not be used as a - master or slave in conjunction with older NIS servers that only - support the v1 protocol. Fortunately, there probably are not any - such servers still in use today.</para> - </sect2> - - <sect2> - <title>NIS servers that are also NIS clients</title> - - <para> Care must be taken when running ypserv in a multi-server - domain where the server machines are also NIS clients. It is - generally a good idea to force the servers to bind to themselves - rather than allowing them to broadcast bind requests and possibly - become bound to each other. Strange failure modes can result if - one server goes down and others are dependent upon on it. - Eventually all the clients will time out and attempt to bind to - other servers, but the delay involved can be considerable and the - failure mode is still present since the servers might bind to each - other all over again.</para> - - <para>You can force a host to bind to a particular server by running - <command>ypbind</command> with the <option>-S</option> - flag.</para> - </sect2> - - <sect2> - <title>libscrypt v.s. libdescrypt</title> - - <para>One of the most common issues that people run into when trying - to implement NIS is crypt library compatibility. If your NIS - server is using the DES crypt libraries, it will only support - clients that are using DES as well. To check which one your server - and clients are using look at the symlinks in - <filename>/usr/lib</filename>. If the machine is configured to - use the DES libraries, it will look something like this:</para> - - <screen> -&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput> -lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a -lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so -lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2 -lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a --r--r--r-- 1 root wheel 13018 Nov 8 14:27 /usr/lib/libdescrypt.a -lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2 --r--r--r-- 1 root wheel 12965 Nov 8 14:27 /usr/lib/libdescrypt.so.2 --r--r--r-- 1 root wheel 14750 Nov 8 14:27 /usr/lib/libdescrypt_p.a</screen> - - <para>If the machine is configured to use the standard FreeBSD MD5 - crypt libraries they will look something like this:</para> - - <screen> -&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput> -lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a -lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so -lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2 -lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a --r--r--r-- 1 root wheel 6194 Nov 8 14:27 /usr/lib/libscrypt.a -lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2 --r--r--r-- 1 root wheel 7579 Nov 8 14:27 /usr/lib/libscrypt.so.2 --r--r--r-- 1 root wheel 6684 Nov 8 14:27 /usr/lib/libscrypt_p.a</screen> - - <para>If you have trouble authenticating on an NIS client, this - is a pretty good place to start looking for possible problems. - If you want to deploy an NIS server for a heterogenous - network, you will probably have to use DES on all systems - because it is the lowest common standard.</para> - </sect2> - </sect1> - - <sect1 id="dhcp"> - <title>DHCP</title> - - <para><emphasis>Written by &a.gsutter;, March 2000.</emphasis></para> - - <sect2> - <title>What is DHCP?</title> - - <para>DHCP, the Dynamic Host Configuration Protocol, describes - the means by which a system can connect to a network and obtain the - necessary information for communication upon that network. FreeBSD - uses the ISC (Internet Software Consortium) DHCP implementation, so - all implementation-specific information here is for use with the ISC - distribution.</para> - </sect2> - - <sect2> - <title>What This Section Covers</title> - - <para>This handbook section attempts to describe only the parts - of the DHCP system that are integrated with FreeBSD; - consequently, the server portions are not described. The DHCP - manual pages, in addition to the references below, are useful - resources.</para> - </sect2> - - <sect2> - <title>How it Works</title> - - <para>When dhclient, the DHCP client, is executed on the client - machine, it begins broadcasting requests for configuration - information. By default, these requests are on UDP port 68. The - server replies on UDP 67, giving the client an IP address and - other relevant network information such as netmask, router, and - DNS servers. All of this information comes in the form of a DHCP - "lease" and is only valid for a certain time (configured by the - DHCP server maintainer). In this manner, stale IP addresses for - clients no longer connected to the network can be automatically - reclaimed.</para> - - <para>DHCP clients can obtain a great deal of information from - the server. An exhaustive list may be found in - &man.dhcp-options.5;.</para> - </sect2> - - <sect2> - <title>FreeBSD Integration</title> - - <para>FreeBSD fully integrates the ISC DHCP client, - <command>dhclient</command>. DHCP client support is provided - within both the installer and the base system, obviating the need - for detailed knowledge of network configurations on any network - that runs a DHCP server. <command>dhclient</command> has been - included in all FreeBSD distributions since 3.2.</para> - - <para>DHCP is supported by <application>sysinstall</application>. - When configuring a network interface within sysinstall, - the first question asked is, "Do you want to try dhcp - configuration of this interface?" Answering affirmatively will - execute dhclient, and if successful, will fill in the network - configuration information automatically.</para> - - <para>There are two things you must do to have your system use - DHCP upon startup:</para> - - <itemizedlist> - <listitem> - <para>Make sure that the <devicename>bpf</devicename> - device is compiled into your kernel. To do this, add - <literal>pseudo-device bpf</literal> to your kernel - configuration file, and rebuild the kernel. For more - information about building kernels, see <xref - linkend="kernelconfig">.</para> - <para>The <devicename>bpf</devicename> device is already - part of the <filename>GENERIC</filename> kernel that is - supplied with FreeBSD, so if you don't have a custom - kernel, you shouldn't need to create one in order to get - DHCP working.</para> - <note> - <para>For those who are particularly security conscious, - you should be warned that <devicename>bpf</devicename> - is also the device that allows packet sniffers to work - correctly (although they still have to be run as - root). <devicename>bpf</devicename> - <emphasis>is</emphasis> required to use DHCP, but if - you are very sensitive about security, you probably - shouldn't add <devicename>bpf</devicename> to your - kernel in the expectation that at some point in the - future you will be using DHCP.</para> - </note> - </listitem> - <listitem> - <para>Edit your <filename>/etc/rc.conf</filename> to - include the following:</para> - - <programlisting> -ifconfig_fxp0="DHCP" - </programlisting> - - <note> - <para>Be sure to replace <literal>fxp0</literal> with the - designation for the interface that you wish to dynamically - configure.</para> - </note> - - <para>If you are using a different location for - <command>dhclient</command>, or if you wish to pass additional - flags to <command>dhclient</command>, also include the - following (editing as necessary):</para> - - <programlisting> -dhcp_program="/sbin/dhclient" -dhcp_flags="" - </programlisting> - </listitem> - </itemizedlist> - - <para>The DHCP server, <command>dhcpd</command>, is included - as part of the <literal>isc-dhcp2</literal> port in the ports - collection. This port contains the full ISC DHCP distribution, - consisting of client, server, relay agent and documentation. - </para> - </sect2> - - <sect2> - <title>Files</title> - - <itemizedlist> - <listitem><para><filename>/etc/dhclient.conf</filename></para> - <para><command>dhclient</command> requires a configuration file, - <filename>/etc/dhclient.conf</filename>. Typically the file - contains only comments, the defaults being reasonably sane. This - configuration file is described by the &man.dhclient.conf.5; - man page.</para> - </listitem> - - <listitem><para><filename>/sbin/dhclient</filename></para> - <para><command>dhclient</command> is statically linked and - resides in <filename>/sbin</filename>. The &man.dhclient.8; - manual page gives more information about - <command>dhclient</command>.</para> - </listitem> - - <listitem><para><filename>/sbin/dhclient-script</filename></para> - <para><command>dhclient-script</command> is the FreeBSD-specific - DHCP client configuration script. It is described in - &man.dhclient-script.8;, but should not need any user - modification to function properly.</para> - </listitem> - - <listitem><para><filename>/var/db/dhclient.leases</filename></para> - <para>The DHCP client keeps a database of valid leases in this - file, which is written as a log. &man.dhclient.leases.5; - gives a slightly longer description.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Further Reading</title> - - <para>The DHCP protocol is fully described in - <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>. - An informational resource has also been set up at - <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</para> - </sect2> - </sect1> - -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/appendix.decl b/en_US.ISO8859-1/books/handbook/appendix.decl deleted file mode 100644 index 5b0425623d..0000000000 --- a/en_US.ISO8859-1/books/handbook/appendix.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE appendix PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/handbook/authors.ent b/en_US.ISO8859-1/books/handbook/authors.ent deleted file mode 100644 index 0ab498c10d..0000000000 --- a/en_US.ISO8859-1/books/handbook/authors.ent +++ /dev/null @@ -1,550 +0,0 @@ -<!-- - Names and email address of contributing authors and CVS committers. - Entity names for committers should be the same as their login names on - freefall.FreeBSD.org. - - Use these entities when referencing people. - - Please keep this list in alphabetical order by entity names. - - IMPORTANT: If you delete names from this file you *must* ensure that - all references to them have been removed from the handbook's - translations. If they haven't then you *will* break the - builds for the other languages, and we will poke fun of you - in public. - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/authors.ent,v 1.130 2000/11/13 15:31:15 shige Exp $ ---> - -<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.org</email>"> - -<!ENTITY a.ache "Andrey A. Chernov <email>ache@FreeBSD.org</email>"> - -<!ENTITY a.adam "Adam David <email>adam@FreeBSD.org</email>"> - -<!ENTITY a.ade "Ade Lovett <email>ade@FreeBSD.org</email>"> - -<!ENTITY a.adrian "Adrian Chadd <email>adrian@FreeBSD.org</email>"> - -<!ENTITY a.akiyama "Shunsuke Akiyama <email>akiyama@FreeBSD.org</email>"> - -<!ENTITY a.alc "Alan L. Cox <email>alc@FreeBSD.org</email>"> - -<!ENTITY a.alex "Alexander Langer <email>alex@FreeBSD.org</email>"> - -<!ENTITY a.alfred "Alfred Perlstein <email>alfred@FreeBSD.org</email>"> - -<!ENTITY a.amurai "Atsushi Murai <email>amurai@FreeBSD.org</email>"> - -<!ENTITY a.andreas "Andreas Klemm <email>andreas@FreeBSD.org</email>"> - -<!ENTITY a.andy "Andrey Zakhvatov <email>andy@FreeBSD.org</email>"> - -<!ENTITY a.archie "Archie Cobbs <email>archie@FreeBSD.org</email>"> - -<!ENTITY a.asami "Satoshi Asami <email>asami@FreeBSD.org</email>"> - -<!ENTITY a.asmodai "Jeroen Ruigrok/Asmodai <email>asmodai@FreeBSD.org</email>"> - -<!ENTITY a.assar "Assar Westerlund <email>assar@FreeBSD.org</email>"> - -<!ENTITY a.ats "Andreas Schulz <email>ats@FreeBSD.org</email>"> - -<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>"> - -<!ENTITY a.babkin "Sergey Babkin <email>babkin@FreeBSD.org</email>"> - -<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.org</email>"> - -<!ENTITY a.ben "Ben Smithurst <email>ben@FreeBSD.org</email>"> - -<!ENTITY a.benno "Benno Rice <email>benno@FreeBSD.org</email>"> - -<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.org</email>"> - -<!ENTITY a.bmah "Bruce A. Mah <email>bmah@FreeBSD.org</email>"> - -<!ENTITY a.bmilekic "Bosko Milekic <email>bmilekic@FreeBSD.org</email>"> - -<!ENTITY a.bp "Boris Popov <email>bp@FreeBSD.org</email>"> - -<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.org</email>"> - -<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.org</email>"> - -<!ENTITY a.bsd "Brian S. Dean <email>bsd@FreeBSD.org</email>"> - -<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.org</email>"> - -<!ENTITY a.cg "Cameron Grant <email>cg@FreeBSD.org</email>"> - -<!ENTITY a.charnier "Philippe Charnier <email>charnier@FreeBSD.org</email>"> - -<!ENTITY a.chris "Chris Costello <email>chris@FreeBSD.org</email>"> - -<!ENTITY a.chuck "Chuck Robey <email>chuckr@glue.umd.edu</email>"> - -<!ENTITY a.chuckr "Chuck Robey <email>chuckr@FreeBSD.org</email>"> - -<!ENTITY a.cjh "Junho CHOI <email>cjh@FreeBSD.org</email>"> - -<!ENTITY a.cp "Chuck Paterson <email>cp@FreeBSD.org</email>"> - -<!ENTITY a.cokane "Coleman Kane <email>cokane@FreeBSD.org</email>"> - -<!ENTITY a.cpiazza "Chris Piazza <email>cpiazza@FreeBSD.org</email>"> - -<!ENTITY a.cracauer "Martin Cracauer <email>cracauer@FreeBSD.org</email>"> - -<!ENTITY a.csgr "Geoff Rehmet <email>csgr@FreeBSD.org</email>"> - -<!ENTITY a.cwt "Chris Timmons <email>cwt@FreeBSD.org</email>"> - -<!ENTITY a.dan "Dan Moschuk <email>dan@FreeBSD.org</email>"> - -<!ENTITY a.danny "Daniel O'Callaghan <email>danny@FreeBSD.org</email>"> - -<!ENTITY a.dannyboy "Daniel Harris <email>dannyboy@FreeBSD.org</email>"> - -<!ENTITY a.darrenr "Darren Reed <email>darrenr@FreeBSD.org</email>"> - -<!ENTITY a.davidn "David Nugent <email>davidn@blaze.net.au</email>"> - -<!ENTITY a.dbaker "Daniel Baker <email>dbaker@FreeBSD.org</email>"> - -<!ENTITY a.dburr "Donald Burr <email>dburr@FreeBSD.org</email>"> - -<!ENTITY a.dcs "Daniel C. Sobral <email>dcs@FreeBSD.org</email>"> - -<!ENTITY a.dec "David E. Cross <email>dec@FreeBSD.org</email>"> - -<!ENTITY a.deischen "Daniel Eischen <email>deischen@FreeBSD.org</email>"> - -<!ENTITY a.demon "Dmitry Sivachenko <email>demon@FreeBSD.org</email>"> - -<!ENTITY a.des "Dag-Erling C. Smørgrav <email>des@FreeBSD.org</email>"> - -<!ENTITY a.dfr "Doug Rabson <email>dfr@FreeBSD.org</email>"> - -<!ENTITY a.dg "David Greenman <email>dg@FreeBSD.org</email>"> - -<!ENTITY a.dick "Richard Seaman Jr. <email>dick@FreeBSD.org</email>"> - -<!ENTITY a.dillon "Matthew Dillon <email>dillon@FreeBSD.org</email>"> - -<!ENTITY a.dima "Dima Ruban <email>dima@FreeBSD.org</email>"> - -<!ENTITY a.dirk "Dirk Frömberg <email>dirk@FreeBSD.org</email>"> - -<!ENTITY a.dirkvangulik "Dirk-Willem van Gulik <email>Dirk.vanGulik@jrc.it</email>"> - -<!ENTITY a.dougb "Doug Barton <email>DougB@FreeBSD.org</email>"> - -<!ENTITY a.dt "Dmitrij Tejblum <email>dt@FreeBSD.org</email>"> - -<!ENTITY a.dufault "Peter Dufault <email>dufault@FreeBSD.org</email>"> - -<!ENTITY a.dwhite "Doug White <email>dwhite@FreeBSD.org</email>"> - -<!ENTITY a.dwmalone "David Malone <email>dwmalone@FreeBSD.org</email>"> - -<!ENTITY a.dyson "John Dyson <email>dyson@FreeBSD.org</email>"> - -<!ENTITY a.eivind "Eivind Eklund <email>eivind@FreeBSD.org</email>"> - -<!ENTITY a.ejc "Eric J. Chet <email>ejc@FreeBSD.org</email>"> - -<!ENTITY a.erich "Eric L. Hernes <email>erich@FreeBSD.org</email>"> - -<!ENTITY a.faq "FAQ Maintainer <email>faq@FreeBSD.org</email>"> - -<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.org</email>"> - -<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.org</email>"> - -<!ENTITY a.foxfair "Howard F. Hu <email>foxfair@FreeBSD.org</email>"> - -<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.org</email>"> - -<!ENTITY a.gad "Garance A Drosehn <email>gad@FreeBSD.org</email>"> - -<!ENTITY a.gallatin "Andrew Gallatin <email>gallatin@FreeBSD.org</email>"> - -<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.org</email>"> - -<!ENTITY a.gena "Gennady B. Sorokopud <email>gena@NetVision.net.il</email>"> - -<!ENTITY a.ghelmer "Guy Helmer <email>ghelmer@cs.iastate.edu</email>"> - -<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.org</email>"> - -<!ENTITY a.gioria "Sebastien Gioria <email>gioria@FreeBSD.org</email>"> - -<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.org</email>"> - -<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.org</email>"> - -<!ENTITY a.graichen "Thomas Graichen <email>graichen@FreeBSD.org</email>"> - -<!ENTITY a.green "Brian F. Feldman <email>green@FreeBSD.org</email>"> - -<!ENTITY a.grog "Greg Lehey <email>grog@FreeBSD.org</email>"> - -<!ENTITY a.groudier "Gerard Roudier <email>groudier@club-internet.fr</email>"> - -<!ENTITY a.gryphon "Coranth Gryphon <email>gryphon@healer.com</email>"> - -<!ENTITY a.gshapiro "Gregory Neil Shapiro <email>gshapiro@FreeBSD.org</email>"> - -<!ENTITY a.gsutter "Gregory Sutter <email>gsutter@FreeBSD.org</email>"> - -<!ENTITY a.guido "Guido van Rooij <email>guido@FreeBSD.org</email>"> - -<!ENTITY a.hanai "Hiroyuki HANAI <email>hanai@FreeBSD.org</email>"> - -<!ENTITY a.handy "Brian N. Handy <email>handy@sxt4.physics.montana.edu</email>"> - -<!ENTITY a.hrs "Hiroki Sato <email>hrs@FreeBSD.org</email>"> - -<!ENTITY a.roger "Roger Hardiman <email>roger@freebsd.org</email>"> - -<!ENTITY a.helbig "Wolfgang Helbig <email>helbig@FreeBSD.org</email>"> - -<!ENTITY a.hm "Hellmuth Michaelis <email>hm@FreeBSD.org</email>"> - -<!ENTITY a.hoek "Tim Vanderhoek <email>hoek@FreeBSD.org</email>"> - -<!ENTITY a.horikawa "Kazuo Horikawa <email>horikawa@FreeBSD.org</email>"> - -<!ENTITY a.hosokawa "Tatsumi Hosokawa <email>hosokawa@FreeBSD.org</email>"> - -<!ENTITY a.hsu "Jeffrey Hsu <email>hsu@FreeBSD.org</email>"> - -<!ENTITY a.imp "Warner Losh <email>imp@FreeBSD.org</email>"> - -<!ENTITY a.issei "Issei Suzuki <email>issei@FreeBSD.org</email>"> - -<!ENTITY a.itojun "Jun-ichiro Itoh <email>itojun@itojun.org</email>"> - -<!ENTITY a.iwasaki "Mitsuru IWASAKI <email>iwasaki@FreeBSD.org</email>"> - -<!ENTITY a.jake "Jake Burkholder <email>jake@FreeBSD.org</email>"> - -<!ENTITY a.jasone "Jason Evans <email>jasone@FreeBSD.org</email>"> - -<!ENTITY a.jayanth "Jayanth Vijayaraghavan <email>jayanth@FreeBSD.org</email>"> - -<!ENTITY a.jb "John Birrell <email>jb@cimlogic.com.au</email>"> - -<!ENTITY a.jdp "John Polstra <email>jdp@FreeBSD.org</email>"> - -<!ENTITY a.jedgar "Chris D. Faulhaber <email>jedgar@FreeBSD.org</email>"> - -<!ENTITY a.jeh "James Housley <email>jeh@FreeBSD.org</email>"> - -<!ENTITY a.jehamby "Jake Hamby <email>jehamby@lightside.com</email>"> - -<!ENTITY a.jesusr "Jesus Rodriguez <email>jesusr@FreeBSD.org</email>"> - -<!ENTITY a.jfieber "John Fieber <email>jfieber@FreeBSD.org</email>"> - -<!ENTITY a.jfitz "James FitzGibbon <email>jfitz@FreeBSD.org</email>"> - -<!ENTITY a.jgreco "Joe Greco <email>jgreco@FreeBSD.org</email>"> - -<!ENTITY a.jhay "John Hay <email>jhay@FreeBSD.org</email>"> - -<!ENTITY a.jhb "John Baldwin <email>jhb@FreeBSD.org</email>"> - -<!ENTITY a.jhs "Julian Stacey <email>jhs@FreeBSD.org</email>"> - -<!ENTITY a.jim "Jim Mock <email>jim@FreeBSD.org</email>"> - -<!ENTITY a.jkh "Jordan K. Hubbard <email>jkh@FreeBSD.org</email>"> - -<!ENTITY a.jkoshy "Joseph Koshy <email>jkoshy@FreeBSD.org</email>"> - -<!ENTITY a.jlemon "Jonathan Lemon <email>jlemon@FreeBSD.org</email>"> - -<!ENTITY a.jlind "John Lind <email>john@starfire.MN.ORG</email>"> - -<!ENTITY a.jlrobin "James L. Robinson <email>jlrobin@FreeBSD.org</email>"> - -<!ENTITY a.jmacd "Joshua Peck Macdonald <email>jmacd@FreeBSD.org</email>"> - -<!ENTITY a.jmas "Jose M. Alcaide <email>jmas@FreeBSD.org</email>"> - -<!ENTITY a.jmb "Jonathan M. Bresler <email>jmb@FreeBSD.org</email>"> - -<!ENTITY a.jmg "John-Mark Gurney <email>jmg@FreeBSD.org</email>"> - -<!ENTITY a.jmz "Jean-Marc Zucconi <email>jmz@FreeBSD.org</email>"> - -<!ENTITY a.joe "Josef Karthauser <email>joe@FreeBSD.org</email>"> - -<!ENTITY a.joerg "Jörg Wunsch <email>joerg@FreeBSD.org</email>"> - -<!ENTITY a.john "John Cavanaugh <email>john@FreeBSD.org</email>"> - -<!ENTITY a.jon "Jonathan Chen <email>jon@FreeBSD.org</email>"> - -<!ENTITY a.jraynard "James Raynard <email>jraynard@FreeBSD.org</email>"> - -<!ENTITY a.jseger "Justin Seger <email>jseger@FreeBSD.org</email>"> - -<!ENTITY a.julian "Julian Elischer <email>julian@FreeBSD.org</email>"> - -<!ENTITY a.jwd "John W. DeBoskey <email>jwd@FreeBSD.org</email>"> - -<!ENTITY a.jvh "Johannes Helander <email>jvh@FreeBSD.org</email>"> - -<!ENTITY a.karl "Karl Strickland <email>karl@FreeBSD.org</email>"> - -<!ENTITY a.kato "Takenori KATO <email>kato@FreeBSD.org</email>"> - -<!ENTITY a.kbyanc "Kelly Yancey <email>kbyanc@FreeBSD.org</email>"> - -<!ENTITY a.keith "Jing-Tang Keith Jang <email>keith@FreeBSD.org</email>"> - -<!ENTITY a.kelly "Sean Kelly <email>kelly@ad1440.net</email>"> - -<!ENTITY a.ken "Kenneth D. Merry <email>ken@FreeBSD.org</email>"> - -<!ENTITY a.kevlo "Kevin Lo <email>kevlo@FreeBSD.org</email>"> - -<!ENTITY a.kiri "Kazuhiko Kiriyama <email>kiri@FreeBSD.org</email>"> - -<!ENTITY a.kjc "Kenjiro Cho <email>kjc@FreeBSD.org</email>"> - -<!ENTITY a.knu "Akinori MUSHA <email>knu@FreeBSD.org</email>"> - -<!ENTITY a.kris "Kris Kennaway <email>kris@FreeBSD.org</email>"> - -<!ENTITY a.kuriyama "Jun Kuriyama <email>kuriyama@FreeBSD.org</email>"> - -<!ENTITY a.lars "Lars Fredriksen <email>lars@FreeBSD.org</email>"> - -<!ENTITY a.lile "Larry Lile <email>lile@FreeBSD.org</email>"> - -<!ENTITY a.lioux "Mário Sérgio Fujikawa Ferreira<email>lioux@FreeBSD.org</email>"> - -<!ENTITY a.ljo "L Jonas Olsson <email>ljo@FreeBSD.org</email>"> - -<!ENTITY a.luoqi "Luoqi Chen <email>luoqi@FreeBSD.org</email>"> - -<!ENTITY a.marcel "Marcel Moolenaar <email>marcel@FreeBSD.org</email>"> - -<!ENTITY a.markm "Mark Murray <email>markm@FreeBSD.org</email>"> - -<!ENTITY a.marko "Mark Ovens <email>marko@FreeBSD.org</email>"> - -<!ENTITY a.martin "Martin Renters <email>martin@FreeBSD.org</email>"> - -<!ENTITY a.max "Masafumi NAKANE <email>max@FreeBSD.org</email>"> - -<!ENTITY a.mayo "Mark Mayo <email>mark@vmunix.com</email>"> - -<!ENTITY a.mbarkah "Ade Barkah <email>mbarkah@FreeBSD.org</email>"> - -<!ENTITY a.mckay "Stephen McKay <email>mckay@FreeBSD.org</email>"> - -<!ENTITY a.mckusick "Kirk McKusick <email>mckusick@FreeBSD.org</email>"> - -<!ENTITY a.md "Mark Dapoz <email>md@bsc.no</email>"> - -<!ENTITY a.mdodd "Matthew N. Dodd <email>winter@jurai.net</email>"> - -<!ENTITY a.mharo "Michael Haro <email>mharo@FreeBSD.org</email>"> - -<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.org</email>"> - -<!ENTITY a.mks "Mike Spengler <email>mks@FreeBSD.org</email>"> - -<!ENTITY a.motoyuki "Motoyuki Konno <email>motoyuki@FreeBSD.org</email>"> - -<!ENTITY a.mph "Matthew Hunt <email>mph@FreeBSD.org</email>"> - -<!ENTITY a.mpp "Mike Pritchard <email>mpp@FreeBSD.org</email>"> - -<!ENTITY a.msmith "Michael Smith <email>msmith@FreeBSD.org</email>"> - -<!ENTITY a.mtaylor "Mark J. Taylor <email>mtaylor@FreeBSD.org</email>"> - -<!ENTITY a.murray "Murray Stokely <email>murray@FreeBSD.org</email>"> - -<!ENTITY a.nakai "Yukihiro Nakai <email>nakai@FreeBSD.org</email>"> - -<!ENTITY a.nate "Nate Williams <email>nate@FreeBSD.org</email>"> - -<!ENTITY a.nbm "Neil Blakey-Milner <email>nbm@FreeBSD.org</email>"> - -<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.org</email>"> - -<!ENTITY a.newton "Mark Newton <email>newton@FreeBSD.org</email>"> - -<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.org</email>"> - -<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.org</email>"> - -<!ENTITY a.non "Noriaki Mitsunaga <email>non@FreeBSD.org</email>"> - -<!ENTITY a.nsayer "Nick Sayer <email>nsayer@FreeBSD.org</email>"> - -<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.org</email>"> - -<!ENTITY a.nyan "Yoshihiro Takahashi <email>nyan@FreeBSD.org</email>"> - -<!ENTITY a.obrien "David O'Brien <email>obrien@FreeBSD.org</email>"> - -<!ENTITY a.okazaki "OKAZAKI Tetsurou <email>okazaki@FreeBSD.org</email>"> - -<!ENTITY a.olah "Andras Olah <email>olah@FreeBSD.org</email>"> - -<!ENTITY a.onoe "Atsushi Onoe <email>onoe@FreeBSD.org</email>"> - -<!ENTITY a.opsys "Chris Watson <email>opsys@open-systems.net</email>"> - -<!ENTITY a.patrick "Patrick S. Gardella <email>patrick@FreeBSD.org</email>"> - -<!ENTITY a.paul "Paul Richards <email>paul@FreeBSD.org</email>"> - -<!ENTITY a.pb "Pierre Beyssac <email>pb@fasterix.freenix.org</email>"> - -<!ENTITY a.pds "Peter da Silva <email>pds@FreeBSD.org</email>"> - -<!ENTITY a.peter "Peter Wemm <email>peter@FreeBSD.org</email>"> - -<!ENTITY a.phantom "Alexey Zelkin <email>phantom@FreeBSD.org</email>"> - -<!ENTITY a.phk "Poul-Henning Kamp <email>phk@FreeBSD.org</email>"> - -<!ENTITY a.pho "Peter Holm <email>pho@FreeBSD.org</email>"> - -<!ENTITY a.piero "Piero Serini <email>piero@strider.inet.it</email>"> - -<!ENTITY a.pjc "Peter Childs <email>pjchilds@imforei.apana.org.au</email>"> - -<!ENTITY a.proven "Chris Provenzano <email>proven@FreeBSD.org</email>"> - -<!ENTITY a.ps "Paul Saab <email>ps@FreeBSD.org</email>"> - -<!ENTITY a.pst "Paul Traina <email>pst@FreeBSD.org</email>"> - -<!ENTITY a.reg "Jeremy Lea <email>reg@FreeBSD.org</email>"> - -<!ENTITY a.rgrimes "Rodney Grimes <email>rgrimes@FreeBSD.org</email>"> - -<!ENTITY a.rhuff "Robert Huff <email>rhuff@cybercom.net</email>"> - -<!ENTITY a.ricardag "Ricardo AG <email>ricardag@ag.com.br</email>"> - -<!ENTITY a.rich "Rich Murphey <email>rich@FreeBSD.org</email>"> - -<!ENTITY a.rnordier "Robert Nordier <email>rnordier@FreeBSD.org</email>"> - -<!ENTITY a.roberto "Ollivier Robert <email>roberto@FreeBSD.org</email>"> - -<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.org</email>"> - -<!ENTITY a.ru "Ruslan Ermilov <email>ru@FreeBSD.org</email>"> - -<!ENTITY a.rv "Rajesh Vaidheeswarran <email>rv@FreeBSD.org</email>"> - -<!ENTITY a.rwatson "Robert Watson <email>rwatson@FreeBSD.org</email>"> - -<!ENTITY a.sada "SADA Kenji <email>sada@FreeBSD.org</email>"> - -<!ENTITY a.sanpei "Yoshiro Sanpei MIHIRA <email>sanpei@FreeBSD.org</email>"> - -<!ENTITY a.scottl "Scott Long <email>scottl@FreeBSD.org</email>"> - -<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.org</email>"> - -<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.org</email>"> - -<!ENTITY a.sef "Sean Eric Fagan <email>sef@FreeBSD.org</email>"> - -<!ENTITY a.shafeeq "Shafeeq Sinnamohideen <email>shafeeq@FreeBSD.org</email>"> - -<!ENTITY a.sheldonh "Sheldon Hearn <email>sheldonh@FreeBSD.org</email>"> - -<!ENTITY a.shige "Shigeyuki Fukushima <email>shige@FreeBSD.org</email>"> - -<!ENTITY a.shin "Yoshinobu Inoue <email>shin@FreeBSD.org</email>"> - -<!ENTITY a.simokawa "Hidetoshi Shimokawa <email>simokawa@FreeBSD.org</email>"> - -<!ENTITY a.smace "Scott Mace <email>smace@FreeBSD.org</email>"> - -<!ENTITY a.smpatel "Sujal Patel <email>smpatel@FreeBSD.org</email>"> - -<!ENTITY a.sobomax "Maxim Sobolev <email>sobomax@FreeBSD.org</email>"> - -<!ENTITY a.sos "Søren Schmidt <email>sos@FreeBSD.org</email>"> - -<!ENTITY a.stark "Gene Stark <email>stark@FreeBSD.org</email>"> - -<!ENTITY a.stb "Stefan Bethke <email>stb@FreeBSD.org</email>"> - -<!ENTITY a.steve "Steve Price <email>steve@FreeBSD.org</email>"> - -<!ENTITY a.sumikawa "Munechika Sumikawa <email>sumikawa@FreeBSD.org</email>"> - -<!ENTITY a.swallace "Steven Wallace <email>swallace@FreeBSD.org</email>"> - -<!ENTITY a.tanimura "Seigo Tanimura <email>tanimura@FreeBSD.org</email>"> - -<!ENTITY a.taoka "Satoshi Taoka <email>taoka@FreeBSD.org</email>"> - -<!ENTITY a.takawata "Takanori Watanabe <email>takawata@FreeBSD.org</email>"> - -<!ENTITY a.tedm "Ted Mittelstaedt <email>tedm@FreeBSD.org</email>"> - -<!ENTITY a.tegge "Tor Egge <email>tegge@FreeBSD.org</email>"> - -<!ENTITY a.tg "Thomas Gellekum <email>tg@FreeBSD.org</email>"> - -<!ENTITY a.thepish "Peter Hawkins <email>thepish@FreeBSD.org</email>"> - -<!ENTITY a.tom "Tom Hukins <email>tom@FreeBSD.org</email>"> - -<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.org</email>"> - -<!ENTITY a.toshi "Toshihiko Arai <email>toshi@FreeBSD.org</email>"> - -<!ENTITY a.trevor "Trevor Johnson <email>trevor@FreeBSD.org</email>"> - -<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.org</email>"> - -<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.org</email>"> - -<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.org</email>"> - -<!ENTITY a.ulf "Ulf Zimmermann <email>ulf@FreeBSD.org</email>"> - -<!ENTITY a.ume "Hajimu UMEMOTO <email>ume@FreeBSD.org</email>"> - -<!ENTITY a.unfurl "Bill Swingle <email>unfurl@FreeBSD.org</email>"> - -<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.org</email>"> - -<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.org</email>"> - -<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>"> - -<!ENTITY a.wilko "Wilko Bulte <email>wilko@FreeBSD.org</email>"> - -<!ENTITY a.will "Will Andrews <email>will@FreeBSD.org</email>"> - -<!ENTITY a.wlloyd "Bill Lloyd <email>wlloyd@mpd.ca</email>"> - -<!ENTITY a.wollman "Garrett Wollman <email>wollman@FreeBSD.org</email>"> - -<!ENTITY a.wosch "Wolfram Schneider <email>wosch@FreeBSD.org</email>"> - -<!ENTITY a.wpaul "Bill Paul <email>wpaul@FreeBSD.org</email>"> - -<!ENTITY a.wsanchez "Wilfredo Sánchez <email>wsanchez@FreeBSD.org</email>"> - -<!ENTITY a.yokota "Kazutaka YOKOTA <email>yokota@FreeBSD.org</email>"> - diff --git a/en_US.ISO8859-1/books/handbook/backups/chapter.sgml b/en_US.ISO8859-1/books/handbook/backups/chapter.sgml deleted file mode 100644 index 779564658b..0000000000 --- a/en_US.ISO8859-1/books/handbook/backups/chapter.sgml +++ /dev/null @@ -1,732 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/backups/chapter.sgml,v 1.25 2000/06/14 23:20:38 jim Exp $ ---> - -<chapter id="backups"> - <title>Backups</title> - - <sect1> - <title>Synopsis</title> - - <para>The following chapter will cover methods of backing up data, and - the programs used to create those backups. If you would like to - contribute something to this section, send it to the &a.doc;.</para> - </sect1> - - <sect1 id="backups-tapebackups"> - <title>Tape Media</title> - - <para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge and - DLT.</para> - - <sect2 id="backups-tapebackups-4mm"> - <title>4mm (DDS: Digital Data Storage)</title> - - <para>4mm tapes are replacing QIC as the workstation backup media of - choice. This trend accelerated greatly when Conner purchased Archive, - a leading manufacturer of QIC drives, and then stopped production of - QIC drives. 4mm drives are small and quiet but do not have the - reputation for reliability that is enjoyed by 8mm drives. The - cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51 - x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short - head life for the same reason, both use helical scan.</para> - - <para>Data throughput on these drives starts ~150kB/s, peaking at ~500kB/s. - Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware - compression, available with most of these drives, approximately - doubles the capacity. Multi-drive tape library units can have 6 - drives in a single cabinet with automatic tape changing. Library - capacities reach 240 GB.</para> - - <para>The DDS-3 standard now supports tape capacities up to 12GB (or - 24GB compressed).</para> - - <para>4mm drives, like 8mm drives, use helical-scan. All the benefits - and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para> - - <para>Tapes should be retired from use after 2,000 passes or 100 full - backups.</para> - </sect2> - - <sect2 id="backups-tapebackups-8mm"> - <title>8mm (Exabyte)</title> - - <para>8mm tapes are the most common SCSI tape drives; they are the best - choice of exchanging tapes. Nearly every site has an exabyte 2 GB 8mm - tape drive. 8mm drives are reliable, convenient and quiet. Cartridges - are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). - One downside of 8mm tape is relatively short head and tape life due to - the high rate of relative motion of the tape across the heads.</para> - - <para>Data throughput ranges from ~250kB/s to ~500kB/s. Data sizes start - at 300 MB and go up to 7 GB. Hardware compression, available with - most of these drives, approximately doubles the capacity. These - drives are available as single units or multi-drive tape libraries - with 6 drives and 120 tapes in a single cabinet. Tapes are changed - automatically by the unit. Library capacities reach 840+ GB.</para> - - <para>The Exabyte <quote>Mammoth</quote> model supports 12GB on one tape - (24GB with compression) and costs approximately twice as much as - conventional tape drives.</para> - - <para>Data is recorded onto the tape using helical-scan, the heads are - positioned at an angle to the media (approximately 6 degrees). The - tape wraps around 270 degrees of the spool that holds the heads. The - spool spins while the tape slides over the spool. The result is a - high density of data and closely packed tracks that angle across the - tape from one edge to the other.</para> - </sect2> - - <sect2 id="backups-tapebackups-qic"> - <title>QIC</title> - - <para>QIC-150 tapes and drives are, perhaps, the most common tape drive - and media around. QIC tape drives are the least expensive "serious" - backup drives. The downside is the cost of media. QIC tapes are - expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB - data storage. But, if your needs can be satisfied with a half-dozen - tapes, QIC may be the correct choice. QIC is the - <emphasis>most</emphasis> common tape drive. Every site has a QIC - drive of some density or another. Therein lies the rub, QIC has a - large number of densities on physically similar (sometimes identical) - tapes. QIC drives are not quiet. These drives audibly seek before - they begin to record data and are clearly audible whenever reading, - writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x - 10.2 x 1.7 mm). <link - linkend="backups-tapebackups-mini">Mini-cartridges</link>, which - also use 1/4" wide tape are discussed separately. Tape libraries and - changers are not available.</para> - - <para>Data throughput ranges from ~150kB/s to ~500kB/s. Data capacity - ranges from 40 MB to 15 GB. Hardware compression is available on many - of the newer QIC drives. QIC drives are less frequently installed; - they are being supplanted by DAT drives.</para> - - <para>Data is recorded onto the tape in tracks. The tracks run along - the long axis of the tape media from one end to the other. The number - of tracks, and therefore the width of a track, varies with the tape's - capacity. Most if not all newer drives provide backward-compatibility - at least for reading (but often also for writing). QIC has a good - reputation regarding the safety of the data (the mechanics are simpler - and more robust than for helical scan drives).</para> - - <para>Tapes should be retired from use after 5,000 backups.</para> - </sect2> - -<![ %not.published; [ - - <sect2 id="backups-tapebackups-mini"> - <title>* Mini-Cartridge</title> - - <para></para> - </sect2> - -]]> - - <sect2 id="backups-tapebackups-dlt"> - <title>DLT</title> - - <para>DLT has the fastest data transfer rate of all the drive types - listed here. The 1/2" (12.5mm) tape is contained in a single spool - cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a - swinging gate along one entire side of the cartridge. The drive - mechanism opens this gate to extract the tape leader. The tape leader - has an oval hole in it which the drive uses to "hook" the tape. The - take-up spool is located inside the tape drive. All the other tape - cartridges listed here (9 track tapes are the only exception) have - both the supply and take-up spools located inside the tape cartridge - itself.</para> - - <para>Data throughput is approximately 1.5MB/s, three times the throughput of - 4mm, 8mm, or QIC tape drives. Data capacities range from 10GB to 20GB - for a single drive. Drives are available in both multi-tape changers - and multi-tape, multi-drive tape libraries containing from 5 to 900 - tapes over 1 to 20 drives, providing from 50GB to 9TB of - storage.</para> - - <para>With compression, DLT Type IV format supports up to 70GB - capacity.</para> - - <para>Data is recorded onto the tape in tracks parallel to the direction - of travel (just like QIC tapes). Two tracks are written at once. - Read/write head lifetimes are relatively long; once the tape stops - moving, there is no relative motion between the heads and the - tape.</para> - </sect2> - - <sect2> - <title id="backups-tapebackups-ait">AIT</title> - - <para>AIT is a new format from Sony, and can hold up to 50GB (with - compression) per tape. The tapes contain memory chips which retain an - index of the tape's contents. This index can be rapidly read by the - tape drive to determine the position of files on the tape, instead of - the several minutes that would be required for other tapes. Software - such as SAMS:Alexandria can operate forty or more AIT tape libraries, - communicating directly with the tape's memory chip to display the - contents on screen, determine what files where backed up to which - tape, locate the correct tape, load it, and restore the data from the - tape.</para> - - <para>Libraries like this cost in the region of $20,000, pricing them a - little out of the hobbyist market.</para> - </sect2> - - <sect2> - <title>Using a New Tape for the First Time</title> - - <para>The first time that you try to read or write a new, completely - blank tape, the operation will fail. The console messages should be - similar to:</para> - - <screen>sa0(ncr1:4:0): NOT READY asc:4,1 -sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen> - - <para>The tape does not contain an Identifier Block (block number 0). - All QIC tape drives since the adoption of QIC-525 standard write an - Identifier Block to the tape. There are two solutions:</para> - - <para><command>mt fsf 1</command> causes the tape drive to write an - Identifier Block to the tape.</para> - - <para>Use the front panel button to eject the tape.</para> - - <para>Re-insert the tape and &man.dump.8; data to the tape.</para> - - <para>&man.dump.8; will report <literal>DUMP: End of tape - detected</literal> and the console will show: <literal>HARDWARE - FAILURE info:280 asc:80,96</literal></para> - - <para>rewind the tape using: <command>mt rewind</command></para> - - <para>Subsequent tape operations are successful.</para> - </sect2> - </sect1> - - <sect1 id="backup-programs"> - <title>Backup Programs</title> - - <para>The three major programs are - &man.dump.8;, - &man.tar.1;, - and - &man.cpio.1;.</para> - - <sect2> - <title>Dump and Restore</title> - - <para>&man.dump.8; and &man.restore.8; are the traditional Unix backup - programs. They operate on the drive as a collection of disk blocks, - below the abstractions of files, links and directories that are - created by the filesystems. &man.dump.8; backs up devices, entire - filesystems, not parts of a filesystem and not directory trees that - span more than one filesystem, using either soft links &man.ln.1; or - mounting one filesystem onto another. &man.dump.8; does not write - files and directories to tape, but rather writes the data blocks that - are the building blocks of files and directories. &man.dump.8; has - quirks that remain from its early days in Version 6 of ATT Unix (circa - 1975). The default parameters are suitable for 9-track tapes (6250 - bpi), not the high-density media available today (up to 62,182 ftpi). - These defaults must be overridden on the command line to utilize the - capacity of current tape drives.</para> - - <para>&man.rdump.8; and &man.rrestore.8; backup data across the network - to a tape drive attached to another computer. Both programs rely upon - &man.rcmd.3; and &man.ruserok.3; to access the remote tape drive. - Therefore, the user performing the backup must have - <literal>rhosts</literal> access to the remote computer. The - arguments to &man.rdump.8; and &man.rrestore.8; must suitable to use - on the remote computer. (e.g. When <command>rdump</command>'ing from - a FreeBSD computer to an Exabyte tape drive connected to a Sun called - <hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu 54000 13000 - 126 komodo:/dev/nrsa8 /dev/rda0a 2>&1</command>) Beware: there - are security implications to allowing <literal>rhosts</literal> - commands. Evaluate your situation carefully.</para> - </sect2> - - <sect2> - <title>Tar</title> - - <para>&man.tar.1; also dates back to Version 6 of ATT Unix (circa 1975). - &man.tar.1; operates in cooperation with the filesystem; &man.tar.1; - writes files and directories to tape. &man.tar.1; does not support the - full range of options that are available from &man.cpio.1;, but - &man.tar.1; does not require the unusual command pipeline that - &man.cpio.1; uses.</para> - - <para>Most versions of &man.tar.1; do not support backups across the - network. The GNU version of &man.tar.1;, which FreeBSD utilizes, - supports remote devices using the same syntax as &man.rdump.8;. To - &man.tar.1; to an Exabyte tape drive connected to a Sun called - <hostid>komodo</hostid>, use: <command>/usr/bin/tar cf - komodo:/dev/nrsa8 . 2>&1</command>. For versions without remote - device support, you can use a pipeline and &man.rsh.1; to send the - data to a remote tape drive.</para> - - <screen>&prompt.root; <userinput>tar cf - . | rsh <replaceable>hostname</replaceable> dd of=<replaceable>tape-device</replaceable> obs=20b</userinput></screen> - - <para>If you're worried about the security of backing over a network - you should use the &man.ssh.1; command instead of &man.rsh.1;.</para> - </sect2> - - <sect2> - <title>Cpio</title> - - <para>&man.cpio.1; is the original Unix file interchange tape program - for magnetic media. &man.cpio.1; has options (among many others) to - perform byte-swapping, write a number of different archives format, - and pipe the data to other programs. This last feature makes - &man.cpio.1; and excellent choice for installation media. - &man.cpio.1; does not know how to walk the directory tree and a list - of files must be provided through <filename>stdin</filename>.</para> - - <para>&man.cpio.1; does not support backups across the network. You can - use a pipeline and &man.rsh.1; to send the data to a remote tape - drive. (XXX add an example command)</para> - </sect2> - - <sect2> - <title>Pax</title> - - <para>&man.pax.1; is IEEE/POSIX's answer to &man.tar.1; and - &man.cpio.1;. Over the years the various versions of &man.tar.1; - and &man.cpio.1; have gotten slightly incompatible. So rather than - fight it out to fully standardize them, POSIX created a new archive - utility. &man.pax.1; attempts to read and write many of the various - &man.cpio.1; and &man.tar.1; formats, plus new formats of its own. - Its command set more resembles &man.cpio.1; than &man.tar.1;.</para> - </sect2> - - <sect2 id="backups-programs-amanda"> - <title>Amanda</title> - - <para><ulink url="../ports/misc.html#amanda-2.4.0">Amanda</ulink> - (Advanced Maryland Network Disk Archiver) is a client/server backup - system, rather than a single program. An Amanda server will backup to - a single tape drive any number of computers that have Amanda clients - and network communications with the Amanda server. A common problem - at locations with a number of large disks is the length of time - required to backup to data directly to tape exceeds the amount of time - available for the task. Amanda solves this problem. Amanda can use a - "holding disk" to backup several filesystems at the same time. Amanda - creates "archive sets": a group of tapes used over a period of time to - create full backups of all the filesystems listed in Amanda's - configuration file. The "archive set" also contains nightly - incremental (or differential) backups of all the filesystems. - Restoring a damaged filesystem requires the most recent full backup - and the incremental backups.</para> - - <para>The configuration file provides fine control backups and the - network traffic that Amanda generates. Amanda will use any of the - above backup programs to write the data to tape. Amanda is available - as either a port or a package, it is not installed by default.</para> - </sect2> - - <sect2> - <title>Do Nothing</title> - - <para><quote>Do nothing</quote> is not a computer program, but it is the - most widely used backup strategy. There are no initial costs. There - is no backup schedule to follow. Just say no. If something happens - to your data, grin and bear it!</para> - - <para>If your time and your data is worth little to nothing, then - <quote>Do nothing</quote> is the most suitable backup program for your - computer. But beware, Unix is a useful tool, you may find that within - six months you have a collection of files that are valuable to - you.</para> - - <para><quote>Do nothing</quote> is the correct backup method for - <filename>/usr/obj</filename> and other directory trees that can be - exactly recreated by your computer. An example is the files that - comprise these handbook pages-they have been generated from - <acronym>SGML</acronym> input files. Creating backups of these - <acronym>HTML</acronym> files is not necessary. The - <acronym>SGML</acronym> source files are backed up regularly.</para> - </sect2> - - <sect2> - <title>Which Backup Program is Best?</title> - - <para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky - torture tested all the backup programs discussed here. The clear - choice for preserving all your data and all the peculiarities of Unix - filesystems is &man.dump.8;. Elizabeth created filesystems containing - a large variety of unusual conditions (and some not so unusual ones) - and tested each program by doing a backup and restore of that - filesystems. The peculiarities included: files with holes, files with - holes and a block of nulls, files with funny characters in their - names, unreadable and unwritable files, devices, files that change - size during the backup, files that are created/deleted during the - backup and more. She presented the results at LISA V in Oct. 1991. - See <ulink - url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing - Backup and Archive Programs</ulink>.</para> - </sect2> - - <sect2> - <title>Emergency Restore Procedure</title> - - <sect3> - <title>Before the Disaster</title> - - <para>There are only four steps that you need to perform in - preparation for any disaster that may occur.</para> - - <para>First, print the disklabel from each of your disks - (<command>e.g. disklabel da0 | lpr</command>), your filesystem table - (<filename>/etc/fstab</filename>) and all boot messages, - two copies of - each.</para> - - <para>Second, determine that the boot and fix-it floppies - (<filename>boot.flp</filename> and <filename>fixit.flp</filename>) - have all your devices. The easiest way to check is to reboot your - machine with the boot floppy in the floppy drive and check the boot - messages. If all your devices are listed and functional, skip on to - step three.</para> - - <para>Otherwise, you have to create two custom bootable floppies which - has a kernel that can mount your all of your disks and access your - tape drive. These floppies must contain: - &man.fdisk.8;, &man.disklabel.8;, &man.newfs.8;, &man.mount.8;, and - whichever backup program you use. These programs must be statically - linked. If you use &man.dump.8;, the floppy must contain - &man.restore.8;.</para> - - <para>Third, create backup tapes regularly. Any changes that you make - after your last backup may be irretrievably lost. Write-protect the - backup tapes.</para> - - <para>Fourth, test the floppies (either <filename>boot.flp</filename> - and <filename>fixit.flp</filename> or the two custom bootable - floppies you made in step two.) and backup tapes. Make notes of the - procedure. Store these notes with the bootable floppy, the - printouts and the backup tapes. You will be so distraught when - restoring that the notes may prevent you from destroying your backup - tapes (How? In place of <command>tar xvf /dev/rsa0</command>, you - might accidently type <command>tar cvf /dev/rsa0</command> and - over-write your backup tape).</para> - - <para>For an added measure of security, make bootable floppies and two - backup tapes each time. Store one of each at a remote location. A - remote location is NOT the basement of the same office building. A - number of firms in the World Trade Center learned this lesson the - hard way. A remote location should be physically separated from - your computers and disk drives by a significant distance.</para> - - <para>An example script for creating a bootable floppy:</para> - - <programlisting> -<![ CDATA [#!/bin/sh -# -# create a restore floppy -# -# format the floppy -# -PATH=/bin:/sbin:/usr/sbin:/usr/bin - -fdformat -q fd0 -if [ $? -ne 0 ] -then - echo "Bad floppy, please use a new one" - exit 1 -fi - -# place boot blocks on the floppy -# -disklabel -w -B /dev/rfd0c fd1440 - -# -# newfs the one and only partition -# -newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/rfd0a - -# -# mount the new floppy -# -mount /dev/fd0a /mnt - -# -# create required directories -# -mkdir /mnt/dev -mkdir /mnt/bin -mkdir /mnt/sbin -mkdir /mnt/etc -mkdir /mnt/root -mkdir /mnt/mnt # for the root partition -mkdir /mnt/tmp -mkdir /mnt/var - -# -# populate the directories -# -if [ ! -x /sys/compile/MINI/kernel ] -then - cat << EOM -The MINI kernel does not exist, please create one. -Here is an example config file: -# -# MINI -- A kernel to get FreeBSD on onto a disk. -# -machine "i386" -cpu "I486_CPU" -ident MINI -maxusers 5 - -options INET # needed for _tcp _icmpstat _ipstat - # _udpstat _tcpstat _udb -options FFS #Berkeley Fast File System -options FAT_CURSOR #block cursor in syscons or pccons -options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device -options NCONS=2 #1 virtual consoles -options USERCONFIG #Allow user configuration with -c XXX - -config kernel root on da0 swap on da0 and da1 dumps on da0 - -controller isa0 -controller pci0 - -controller fdc0 at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr -disk fd0 at fdc0 drive 0 - -controller ncr0 - -controller scbus0 - -device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr -device npx0 at isa? port "IO_NPX" irq 13 vector npxintr - -device da0 -device da1 -device da2 - -device sa0 - -pseudo-device loop # required by INET -pseudo-device gzip # Exec gzipped a.out's -EOM - exit 1 -fi - -cp -f /sys/compile/MINI/kernel /mnt - -gzip -c -best /sbin/init > /mnt/sbin/init -gzip -c -best /sbin/fsck > /mnt/sbin/fsck -gzip -c -best /sbin/mount > /mnt/sbin/mount -gzip -c -best /sbin/halt > /mnt/sbin/halt -gzip -c -best /sbin/restore > /mnt/sbin/restore - -gzip -c -best /bin/sh > /mnt/bin/sh -gzip -c -best /bin/sync > /mnt/bin/sync - -cp /root/.profile /mnt/root - -cp -f /dev/MAKEDEV /mnt/dev -chmod 755 /mnt/dev/MAKEDEV - -chmod 500 /mnt/sbin/init -chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt -chmod 555 /mnt/bin/sh /mnt/bin/sync -chmod 6555 /mnt/sbin/restore - -# -# create the devices nodes -# -cd /mnt/dev -./MAKEDEV std -./MAKEDEV da0 -./MAKEDEV da1 -./MAKEDEV da2 -./MAKEDEV sa0 -./MAKEDEV pty0 -cd / - -# -# create minimum filesystem table -# -cat > /mnt/etc/fstab <<EOM -/dev/fd0a / ufs rw 1 1 -EOM - -# -# create minimum passwd file -# -cat > /mnt/etc/passwd <<EOM -root:*:0:0:Charlie &:/root:/bin/sh -EOM - -cat > /mnt/etc/master.passwd <<EOM -root::0:0::0:0:Charlie &:/root:/bin/sh -EOM - -chmod 600 /mnt/etc/master.passwd -chmod 644 /mnt/etc/passwd -/usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd - -# -# umount the floppy and inform the user -# -/sbin/umount /mnt -echo "The floppy has been unmounted and is now ready."]]></programlisting> - </sect3> - - <sect3> - <title>After the Disaster</title> - - <para>The key question is: did your hardware survive? You have been - doing regular backups so there is no need to worry about the - software.</para> - - <para>If the hardware has been damaged. First, replace those parts - that have been damaged.</para> - - <para>If your hardware is okay, check your floppies. If you are using - a custom boot floppy, boot single-user (type <literal>-s</literal> - at the <prompt>boot:</prompt> prompt). Skip the following - paragraph.</para> - - <para>If you are using the <filename>boot.flp</filename> and - <filename>fixit.flp</filename> floppies, keep reading. Insert the - <filename>boot.flp</filename> floppy in the first floppy drive and - boot the computer. The original install menu will be displayed on - the screen. Select the <literal>Fixit--Repair mode with CDROM or - floppy.</literal> option. Insert the - <filename>fixit.flp</filename> when prompted. - <command>restore</command> and the other programs that you need are - located in <filename>/mnt2/stand</filename>.</para> - - <para>Recover each filesystem separately.</para> - - <para>Try to &man.mount.8; (e.g. <command>mount /dev/da0a - /mnt</command>) the root partition of your first disk. If the - disklabel was damaged, use &man.disklabel.8; to re-partition and - label the disk to match the label that your printed and saved. Use - &man.newfs.8; to re-create the filesystems. Re-mount the root - partition of the floppy read-write (<command>mount -u -o rw - /mnt</command>). Use your backup program and backup tapes to - recover the data for this filesystem (e.g. <command>restore vrf - /dev/sa0</command>). Unmount the filesystem (e.g. <command>umount - /mnt</command>) Repeat for each filesystem that was - damaged.</para> - - <para>Once your system is running, backup your data onto new tapes. - Whatever caused the crash or data loss may strike again. An another - hour spent now, may save you from further distress later.</para> - </sect3> - -<![ %not.published; [ - - <sect3> - <title>* I did not prepare for the Disaster, What Now?</title> - - <para></para> - </sect3> -]]> - - </sect2> - </sect1> - - <sect1 id="backups-floppybackups"> - <title>What about Backups to Floppies?</title> - - <sect2 id="floppies-using"> - <title>Can I use floppies for backing up my data?</title> - - <para>Floppy disks are not really a suitable media for - making backups as:</para> - - <itemizedlist> - <listitem> - <para>The media is unreliable, especially over long periods of - time</para> - </listitem> - - <listitem> - <para>Backing up and restoring is very slow</para> - </listitem> - - <listitem> - <para>They have a very limited capacity (the days of backing up - an entire hard disk onto a dozen or so floppies has long since - passed).</para> - </listitem> - </itemizedlist> - - <para>However, if you have no other method of backing up your data then - floppy disks are better than no backup at all.</para> - - <para>If you do have to use floppy disks then ensure that you use good - quality ones. Floppies that have been lying around the office for a - couple of years are a bad choice. Ideally use new ones from a - reputable manufacturer.</para> - </sect2> - - <sect2 id="floppies-creating"> - <title>So how do I backup my data to floppies?</title> - - <para>The best way to backup to floppy disk is to use - &man.tar.1; with the <option>-M</option> (multi volume) option, which - allows backups to span multiple floppies.</para> - - <para>To backup all the files in the current directory and sub-directory - use this (as root):</para> - - <screen>&prompt.root; <userinput>tar Mcvf /dev/rfd0 *</userinput></screen> - - <para>When the first floppy is full &man.tar.1; will prompt you to - insert the next volume (because &man.tar.1; is media independent it - refers to volumes. In this context it means floppy disk)</para> - - <screen>Prepare volume #2 for /dev/rfd0 and hit return:</screen> - - <para>This is repeated (with the volume number incrementing) until all - the specified files have been archived.</para> - </sect2> - - <sect2 id="floppies-compress"> - <title>Can I compress my backups?</title> - - <para>Unfortunately, &man.tar.1; will not allow the - <option>-z</option> option to be used for multi-volume archives. - You could, of course, &man.gzip.1; all the files, &man.tar.1; them to - the floppies, then &man.gunzip.1; the files again!</para> - </sect2> - - <sect2 id="floppies-restoring"> - <title>How do I restore my backups?</title> - - <para>To restore the entire archive use:</para> - - <screen>&prompt.root; <userinput>tar Mxvf /dev/rfd0</userinput></screen> - - <para>To restore only specific files you can either start with the first - floppy and use:</para> - - <screen>&prompt.root; <userinput>tar Mxvf /dev/rfd0 <replaceable>filename</replaceable></userinput></screen> - - <para>&man.tar.1; will prompt you to insert subsequent floppies until it - finds the required file.</para> - - <para>Alternatively, if you know which floppy the file is on then you - can simply insert that floppy and use the same command as above. Note - that if the first file on the floppy is a continuation from the - previous one then &man.tar.1; will warn you that it cannot restore it, - even if you have not asked it to!</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml deleted file mode 100644 index 70569d401a..0000000000 --- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml +++ /dev/null @@ -1,543 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/basics/chapter.sgml,v 1.21 2000/08/08 23:23:06 marko Exp $ ---> - -<chapter id="basics"> - <title>Unix Basics</title> - - <sect1> - <title>Synopsis</title> - - <para><emphasis>Rewritten by Chris Shumway - <email>cshumway@cdrom.com</email>, 10 Mar 2000.</emphasis></para> - - <para>The following chapter will cover the basic commands and - functionality of the FreeBSD operating system. If you are new to - FreeBSD, you will definitely want to read through this chapter before - asking for help.</para> - </sect1> - - <sect1 id="permissions"> - <title>Permissions</title> - - <para>FreeBSD, having its history rooted in BSD UNIX, has its - fundamentals based on several key UNIX concepts. The first, and - most pronounced, is that FreeBSD is a multi-user operating system. - The system can handle several users all working simultaneously on - completely unrelated tasks. The system is responsible for properly - sharing and managing requests for hardware devices, peripherals, - memory, and CPU time evenly to each user.</para> - - <para>Because the system is capable of supporting multiple users, - everything the system manages has a set of permissions governing who - can read, write, and execute the resource. These permissions are - stored as an octet broken into three pieces, one for the owner of - the file, one for the group that the file belongs to, and one for - everyone else. This numerical representation works like - this:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Value</entry> - <entry>Permission</entry> - <entry>Directory Listing</entry> - </row> - </thead> - - <tbody> - <row> - <entry>0</entry> - <entry>No read, no write, no execute</entry> - <entry><literal>---</literal></entry> - </row> - - <row> - <entry>1</entry> - <entry>No read, no write, execute</entry> - <entry><literal>--x</literal></entry> - </row> - - <row> - <entry>2</entry> - <entry>No read, write, no execute</entry> - <entry><literal>-w-</literal></entry> - </row> - - <row> - <entry>3</entry> - <entry>No read, write, execute</entry> - <entry><literal>-wx</literal></entry> - </row> - - <row> - <entry>4</entry> - <entry>Read, no write, no execute</entry> - <entry><literal>r--</literal></entry> - </row> - - <row> - <entry>5</entry> - <entry>Read, no write, execute</entry> - <entry><literal>r-x</literal></entry> - </row> - - <row> - <entry>6</entry> - <entry>Read, write, no execute</entry> - <entry><literal>rw-</literal></entry> - </row> - - <row> - <entry>7</entry> - <entry>Read, write, execute</entry> - <entry><literal>rwx</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>For the long directory listing by <command>ls -l</command>, a - column will show a file's permissions for the owner, group, and - everyone else. Here's how it is broken up:</para> - - <screen>-rw-r--r--</screen> - - <para>The first character, from left to right, is a special character - that tells if this is a regular file, a directory, a special - character or block device, a socket, or any other special - pseudo-file device. The next three characters, designated as - <literal>rw-</literal> gives the permissions for the owner of the - file. The next three characters, <literal>r--</literal> gives the - permissions for the group that the file belongs to. The final three - characters, <literal>r--</literal>, gives the permissions for the - rest of the world. A dash means that the permission is turned off. - In the case of this file, the permissions are set so the owner can - read and write to the file, the group can read the file, and the - rest of the world can only read the file. According to the table - above, the permissions for this file would be - <literal>644</literal>, where each digit represents the three parts - of the file's permission.</para> - - <para>This is all well and good, but how does the system control - permissions on devices? FreeBSD actually treats most hardware - devices as a file that programs can open, read, and write data to - just like any other file. These special device files are stored on - the <filename>/dev</filename> directory.</para> - - <para>Directories are also treated as files. They have read, write, - and execute permissions. The executable bit for a directory has a - slightly different meaning than that of files. When a directory is - marked executable, it means it can be searched into, for example, a - directory listing can be done in that directory.</para> - - <para>There are more to permissions, but they are primarily used in - special circumstances such as setuid binaries and sticky - directories. If you want more information on file permissions and - how to set them, be sure to look at the &man.chmod.1; man - page.</para> - </sect1> - - <sect1 id="dirstructure"> - <title>Directory Structures</title> - - <para>Since FreeBSD uses its file systems to determine many - fundamental system operations, the hierarchy of the file system is - extremely important. Due to the fact that the &man.hier.7; man page - provides a complete description of the directory structure, it will - not be duplicated here. Please read &man.hier.7; for more - information.</para> - - <para>Of significant importance is the root of all directories, the / - directory. This directory is the first directory mounted at boot - time and it contains the base system necessary at boot time. The - root directory also contains mount points for every other file - system that you want to mount.</para> - - <para>A mount point is a directory where additional file systems can - be grafted onto the root file system. Standard mount points include - <filename>/usr</filename>, <filename>/var</filename>, - <filename>/mnt</filename>, and <filename>/cdrom</filename>. These - directories are usually referenced to entries in the file - <filename>/etc/fstab</filename>. <filename>/etc/fstab</filename> is - a table of various file systems and mount points for reference by the - system. Most of the file systems in <filename>/etc/fstab</filename> - are mounted automatically at boot time from the script &man.rc.8; - unless they contain the <option>noauto</option> option. Consult the - &man.fstab.5; manual page for more information on the format of the - <filename>/etc/fstab</filename> file and the options it - contains.</para> - </sect1> - - <sect1 id="shells"> - <title>Shells</title> - - <para>In FreeBSD, a lot of everyday work is done in a command line - interface called a shell. A shell's main job is to take commands - from the input channel and execute them. A lot of shells also have - built in functions to help everyday tasks such a file management, - file globing, command line editing, command macros, and environment - variables. FreeBSD comes with a set of shells, such as sh, the - Bourne Shell, and csh, the C-shell. Many other shells are available - from the FreeBSD Ports Collection that have much more power, such as - tcsh and bash.</para> - - <para>Which shell do you use? It is really a matter of taste. If you - are a C programmer you might feel more comfortable with a C-like shell - such as tcsh. If you've come from Linux or are new to a UNIX - command line interface you might try bash. The point is that each - shell has unique properties that may or may not work with your - preferred working environment, and that you have a choice of what - shell to use.</para> - - <para>One common feature in a shell is file-name completion. Given - the typing of the first few letters of a command or filename, you - can usually have the shell automatically complete the rest of the - command or filename by hitting the TAB key on the keyboard. Here is - an example. I have two files called <filename>foobar</filename> and - <filename>foo.bar</filename>. I want to delete - <filename>foo.bar</filename>. So what I would type on the keyboard - is: <command>rm fo[TAB].[TAB]</command>.</para> - - <para>The shell would print out <command>rm - foo[BEEP].bar</command>.</para> - - <para>The [BEEP] is the console bell, which is the shell telling me it - was unable to totally complete the filename because there is more - than one match. Both <filename>foobar</filename> and - <filename>foo.bar</filename> start with <literal>fo</literal>, but - it was able to complete to <literal>foo</literal>. Once I typed in - <literal>.</literal>, then hit TAB again, the shell was able to fill - in the rest of the filename for me.</para> - - <para>Another function of the shell is environment variables. - Environment variables are a variable key pair stored in the shell's - environment space. This space can be read by any program invoked by - the shell, and thus contains a lot of program configuration. Here - is a list of common environment variables and what they mean:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><envar>USER</envar></entry> - <entry>Current logged in user's name.</entry> - </row> - - <row> - <entry><envar>PATH</envar></entry> - <entry>Colon separated list of directories to search for - binaries.</entry> - </row> - - <row> - <entry><envar>DISPLAY</envar></entry> - <entry>Network name of the X11 display to connect to, if - available.</entry> - </row> - - <row> - <entry><envar>SHELL</envar></entry> - <entry>The current shell.</entry> - </row> - - <row> - <entry><envar>TERM</envar></entry> - <entry>The name of the user's terminal. Used to determine the - capabilities of the terminal.</entry> - </row> - - <row> - <entry><envar>TERMCAP</envar></entry> - <entry>Database entry of the terminal escape codes to perform - various terminal functions.</entry> - </row> - - <row> - <entry><envar>OSTYPE</envar></entry> - <entry>Type of operating system. E.g., FreeBSD.</entry> - </row> - - <row> - <entry><envar>MACHTYPE</envar></entry> - <entry>The CPU architecture that the system is running - on.</entry> - </row> - - <row> - <entry><envar>EDITOR</envar></entry> - <entry>The user's preferred text editor.</entry> - </row> - - <row> - <entry><envar>PAGER</envar></entry> - <entry>The user's preferred text pager.</entry> - </row> - - <row> - <entry><envar>MANPATH</envar></entry> - <entry>Colon separated list of directories to search for - manual pages.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>To view or set an environment variable differs somewhat from - shell to shell. For example, in the C-Style shells such as tcsh - and csh, you would use <command>setenv</command> to set and view - environment variables. Under Bourne shells such as sh and bash, you - would use <command>set</command> and <command>export</command> to - view and set your current environment variables. For example, to - set or modify the <envar>EDITOR</envar> environment variable, under - csh or tcsh a command like this would set <envar>EDITOR</envar> to - <filename>/usr/local/bin/emacs</filename>:</para> - - <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen> - - <para>Under Bourne shells:</para> - - <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen> - - <para>You can also make most shells expand the environment variable by - placing a <literal>$</literal> character in front of it on the - command line. For example, <command>echo $TERM</command> would - print out whatever <envar>$TERM</envar> is set to, because the shell - expands <envar>$TERM</envar> and passes it on to echo.</para> - - <para>Shells treat a lot of special characters, called meta-characters - as special representations of data. The most common one is the - <literal>*</literal> character, which represents any number of - characters in a filename. These special meta-characters can be used - to do file name globing. For example, typing in - <command>echo *</command> is almost the same as typing in - <command>ls</command> because the shell takes all the files that - match <command>*</command> and puts them on the command line for - echo to see.</para> - - <para>To prevent the shell from interpreting these special characters, - they can be escaped from the shell by putting a backslash - (<literal>\</literal>) character in front of them. <command>echo - $TERM</command> prints whatever your terminal is set to. - <command>echo \$TERM</command> prints <envar>$TERM</envar> as - is.</para> - - <sect2 id="changing-shells"> - <title>Changing your shell</title> - - <para>The easiest way to change your shell is to use the - <command>chsh</command> command. Running <command>chsh</command> will - place you into the editor that is in your <envar>EDITOR</envar> - environment variable; if it is not set, you will be placed in - <command>vi</command>. Change the <quote>Shell:</quote> line - accordingly.</para> - - <para>You can also give <command>chsh</command> the - <option>-s</option> option; this will set your shell for you, - without requiring you to enter an editor. - For example, if you wanted to - change your shell to bash, the following should do the - trick:</para> - - <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen> - - <para>Running <command>chsh</command> with no parameters and editing - the shell from there would work also.</para> - - <note> - <para>The shell that you wish to use <emphasis>must</emphasis> be - present in the <filename>/etc/shells</filename> file. If you - have installed a shell from the <link linkend="ports">ports - collection</link>, then this should have been done for you - already. If you installed the shell by hand, you must do - this.</para> - - <para>For example, if you installed <command>bash</command> by hand - and placed it into <filename>/usr/local/bin</filename>, you would - want to:</para> - - <screen>&prompt.root; <userinput>echo "/usr/local/bin/bash" >> /etc/shells</userinput></screen> - - <para>Then rerun <command>chsh</command>.</para> - </note> - </sect2> - </sect1> - - <sect1 id="editors"> - <title>Text Editors</title> - - <para>A lot of configuration in FreeBSD is done by editing a text - file. Because of this, it would be a good idea to become familiar - with a text editor. FreeBSD comes with a few as part of the base - system, and many more are available in the ports collection.</para> - - <para>The easiest and simplest editor to learn is an editor called - <application>ee</application>, which stands for easy editor. To - start <application>ee</application>, one would type at the command - line <command>ee filename</command> where - <literal>filename</literal> is the name of the file to be edited. - For example, to edit <filename>/etc/rc.conf</filename>, type in - <command>ee /etc/rc.conf</command>. Once inside of ee, all of the - commands for manipulating the editor's functions are listed at the - top of the display. The caret <literal>^</literal> character means - the control key on the keyboard, so ^e expands to pressing the - control key plus the letter <literal>e</literal>. To leave - <application>ee</application>, hit the escape key, then choose leave - editor. The editor will prompt you to save any changes if the file - has been modified.</para> - - <para>FreeBSD also comes with more powerful text editors such as - <application>vi</application> as part of the base system, and - <application>emacs</application> and <application>vim</application> - as part of the FreeBSD ports collection. These editors offer much - more functionality and power at the expense of being a little more - complicated to learn. However if you plan on doing a lot of text - editing, learning a more powerful editor such as - <application>vim</application> or <application>emacs</application> - will save you much more time in the long run.</para> - </sect1> - - <sect1> - <title>For More Information...</title> - - <sect2 id="basics-man"> - <title>Manual pages</title> - - <para>The most comprehensive documentation on FreeBSD is in the form - of man pages. Nearly every program on the system comes with a - short reference manual explaining the basic operation and various - arguments. These manuals can be viewed with the man command. Use - of the man command is simple:</para> - - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - - <para><literal>command</literal> is the name of the command you - wish to learn about. For example, to learn more about - <command>ls</command> command type:</para> - - <screen>&prompt.user; <userinput>man ls</userinput></screen> - - <para>The online manual is divided up into numbered sections:</para> - - <orderedlist> - <listitem> - <para>User commands.</para> - </listitem> - - <listitem> - <para>System calls and error numbers.</para> - </listitem> - - <listitem> - <para>Functions in the C libraries.</para> - </listitem> - - <listitem> - <para>Device drivers.</para> - </listitem> - - <listitem> - <para>File formats.</para> - </listitem> - - <listitem> - <para>Games and other diversions.</para> - </listitem> - - <listitem> - <para>Miscellaneous information.</para> - </listitem> - - <listitem> - <para>System maintenance and operation commands.</para> - </listitem> - - <listitem> - <para>Kernel developers.</para> - </listitem> - </orderedlist> - - <para>In some cases, the same topic may appear in more than one - section of the online manual. For example, there is a chmod user - command and a <literal>chmod()</literal> system call. In this - case, you can tell the man command which one you want by - specifying the section:</para> - - <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> - - <para>This will display the manual page for the user command - <command>chmod</command>. References to a particular section of - the online manual are traditionally placed in parenthesis in - written documentation, so &man.chmod.1; refers to the - <command>chmod</command> user command and &man.chmod.2; refers to - the system call.</para> - - <para>This is fine if you know the name of the command and simply - wish to know how to use it, but what if you cannot recall the - command name? You can use man to search for keywords in the - command descriptions by using the <option>-k</option> - switch:</para> - - <screen>&prompt.user; <userinput>man -k mail</userinput></screen> - - <para>With this command you will be presented with a list of - commands that have the keyword <quote>mail</quote> in their - descriptions. This is actually functionally equivalent to using - the apropos command.</para> - - <para>So, you are looking at all those fancy commands in - <filename>/usr/bin</filename> but do not have the faintest idea - what most of them actually do? Simply do:</para> - - <screen>&prompt.user; <userinput>cd /usr/bin</userinput> -&prompt.user; <userinput>man -f *</userinput></screen> - - <para>or</para> - - <screen>&prompt.user; <userinput>cd /usr/bin</userinput> -&prompt.user; <userinput>whatis *</userinput></screen> - - <para>which does the same thing.</para> - </sect2> - - <sect2 id="basics-info"> - <title>GNU Info Files</title> - - <para>FreeBSD includes many applications and utilities produced by - the Free Software Foundation (FSF). In addition to man pages, - these programs come with more extensive hypertext documents called - <literal>info</literal> files which can be viewed with the - <command>info</command> command or, if you installed - <application>emacs</application>, the info mode of - <application>emacs</application>.</para> - - <para>To use the &man.info.1; command, simply type:</para> - - <screen>&prompt.user; <userinput>info</userinput></screen> - - <para>For a brief introduction, type <literal>h</literal>. For a - quick command reference, type <literal>?</literal>.</para> - </sect2> - </sect1> -</chapter> -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml b/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml deleted file mode 100644 index 053dae079d..0000000000 --- a/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml +++ /dev/null @@ -1,484 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml,v 1.27 2000/08/08 06:00:12 jim Exp $ ---> - -<appendix id="bibliography"> - <title>Bibliography</title> - - <para>While the manual pages provide the definitive reference for individual - pieces of the FreeBSD operating system, they are notorious for not - illustrating how to put the pieces together to make the whole operating - system run smoothly. For this, there is no substitute for a good book on - UNIX system administration and a good users' manual.</para> - - <sect1 id="bibliography-freebsd"> - <title>Books & Magazines Specific to FreeBSD</title> - - <para><emphasis>International books & - Magazines:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://jdli.tw.freebsd.org/publication/book/freebsd2/index.htm">Using FreeBSD</ulink> (in Chinese).</para> - </listitem> - - <listitem> - <para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System - Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para> - </listitem> - - <listitem> - <para>FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 - C3055 P2400E.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.shoeisha.co.jp/pc/index/shinkan/97_05_06.htm">Complete Introduction to FreeBSD</ulink> (in Japanese), published by <ulink url="http://www.shoeisha.co.jp/">Shoeisha Co., Ltd</ulink>. ISBN 4-88135-473-6 P3600E.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal UNIX Starter Kit FreeBSD</ulink> (in Japanese), published by <ulink url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1733-3 P3000E.</para> - </listitem> - - <listitem> - <para>FreeBSD Handbook (Japanese translation), published by <ulink - url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN 4-7561-1580-2 - P3800E.</para> - </listitem> - - <listitem> - <para>FreeBSD mit Methode (in German), published by Computer und - Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para> - </listitem> - </itemizedlist> - - <para><emphasis>English language books & Magazines:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.wccdrom.com/titles/freebsd/bsdcomp_bkx.phtml"> - The Complete FreeBSD</ulink>, published by <ulink - url="http://www.bsdi.com/">BSDi</ulink>.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-userguides"> - <title>Users' Guides</title> - - <itemizedlist> - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - User's Reference Manual</emphasis>. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-075-9</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - User's Supplementary Documents</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-076-7</para> - </listitem> - - <listitem> - <para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly & - Associates, Inc., 1990. ISBN 093717520X</para> - </listitem> - - <listitem> - <para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find - Your UNIX System Administrator</emphasis>. O'Reilly & - Associates, Inc., 1995. ISBN 1-56592-104-6</para> - </listitem> - - <listitem> - <para><ulink url="http://www-wks.acs.ohio-state.edu/">Ohio State - University</ulink> has written a <ulink - url="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX - Introductory Course</ulink> which is available online in HTML and - postscript format.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan - FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's - Reference Manual</ulink> (Japanese translation). <ulink - url="http://www.pc.mycom.co.jp/">Mainichi Communications - Inc.</ulink>, 1998. ISBN4-8399-0088-4 P3800E.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.ed.ac.uk/">Edinburgh - University</ulink> has written an <ulink - url="http://unixhelp.ed.ac.uk/">Online Guide</ulink> for - newcomers to the UNIX environment.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-adminguides"> - <title>Administrators' Guides</title> - - <itemizedlist> - <listitem> - <para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and - BIND</emphasis>, 3rd Ed. O'Reilly & Associates, Inc., 1998. - ISBN 1-56592-512-2</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - System Manager's Manual</emphasis>. O'Reilly & Associates, - Inc., 1994. ISBN 1-56592-080-5</para> - </listitem> - - <listitem> - <para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed. - O'Reilly & Associates, Inc., 1997. ISBN 1-56592-222-0</para> - </listitem> - - <listitem> - <para>Frisch, Æleen. <emphasis>Essential System - Administration</emphasis>, 2nd Ed. O'Reilly & Associates, - Inc., 1995. ISBN 1-56592-127-5</para> - </listitem> - - <listitem> - <para>Hunt, Craig. <emphasis>TCP/IP Network - Administration</emphasis>, 2nd Ed. O'Reilly & Associates, Inc., 1997. - ISBN 1-56592-322-7</para> - </listitem> - - <listitem> - <para>Nemeth, Evi. <emphasis>UNIX System Administration - Handbook</emphasis>. 3rd Ed. Prentice Hall, 2000. ISBN - 0-13-020601-6</para> - </listitem> - - <listitem> - <para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly - & Associates, Inc., 1991. ISBN 0-937175-75-7</para> - </listitem> - - <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan - FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System - Administrator's Manual</ulink> (Japanese translation). <ulink - url="http://www.pc.mycom.co.jp/">Mainichi Communications - Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-programmers"> - <title>Programmers' Guides</title> - - <itemizedlist> - <listitem> - <para>Asente, Paul. <emphasis>X Window System Toolkit</emphasis>. - Digital Press. ISBN 1-55558-051-3</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - Programmer's Reference Manual</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-078-3</para> - </listitem> - - <listitem> - <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD - Programmer's Supplementary Documents</emphasis>. O'Reilly & - Associates, Inc., 1994. ISBN 1-56592-079-1</para> - </listitem> - - <listitem> - <para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A - Reference Manual</emphasis>. 4rd ed. Prentice Hall, 1995. - ISBN 0-13-326224-3</para> - </listitem> - - <listitem> - <para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C - Programming Language.</emphasis>. PTR Prentice Hall, 1988. - ISBN 0-13-110362-9</para> - </listitem> - - <listitem> - <para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>. - O'Reilly & Associates, Inc., 1995. ISBN 1-56592-126-7</para> - </listitem> - - <listitem> - <para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>. - Prentice Hall, 1992. ISBN 0-13-131509-9</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>Advanced Programming in the UNIX - Environment</emphasis>. Reading, Mass. : Addison-Wesley, 1992 - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>UNIX Network - Programming</emphasis>. 2nd Ed, PTR Prentice Hall, 1998. ISBN - 0-13-490012-X</para> - </listitem> - - <listitem> - <para>Wells, Bill. <quote>Writing Serial Drivers for UNIX</quote>. - <emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994. - pp68-71, 97-99.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-osinternals"> - <title>Operating System Internals</title> - - <itemizedlist> - <listitem> - <para>Andleigh, Prabhat K. <emphasis>UNIX System - Architecture</emphasis>. Prentice-Hall, Inc., 1990. ISBN - 0-13-949843-5</para> - </listitem> - - <listitem> - <para>Jolitz, William. <quote>Porting UNIX to the 386</quote>. - <emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July - 1992.</para> - </listitem> - - <listitem> - <para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and - John Quarterman <emphasis>The Design and Implementation of the - 4.3BSD UNIX Operating System</emphasis>. Reading, Mass. : - Addison-Wesley, 1989. ISBN 0-201-06196-1</para> - </listitem> - - <listitem> - <para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design - and Implementation of the 4.3BSD UNIX Operating System: Answer - Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991. ISBN - 0-201-54629-9</para> - </listitem> - - <listitem> - <para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and - John Quarterman. <emphasis>The Design and Implementation of the - 4.4BSD Operating System</emphasis>. Reading, Mass. : - Addison-Wesley, 1996. ISBN 0-201-54979-4</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1: - The Protocols</emphasis>. Reading, Mass. : Addison-Wesley, - 1996. ISBN 0-201-63346-9</para> - </listitem> - - <listitem> - <para>Schimmel, Curt. <emphasis>Unix Systems for Modern - Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994. - ISBN 0-201-63338-8</para> - </listitem> - - <listitem> - <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3: - TCP for Transactions, HTTP, NNTP and the UNIX Domain - Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996. - ISBN 0-201-63495-3</para> - </listitem> - - <listitem> - <para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New - Frontiers</emphasis>. Prentice Hall, 1996. ISBN - 0-13-101908-2</para> - </listitem> - - <listitem> - <para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP - Illustrated, Volume 2: The Implementation</emphasis>. Reading, - Mass. : Addison-Wesley, 1995. ISBN 0-201-63354-X</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-security"> - <title>Security Reference</title> - - <itemizedlist> - <listitem> - <para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls - and Internet Security: Repelling the Wily Hacker</emphasis>. - Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-63357-4</para> - </listitem> - - <listitem> - <para>Garfinkel, Simson and Gene Spafford. <emphasis>Practical UNIX - Security</emphasis>. 2nd Ed. O'Reilly & Associates, Inc., - 1996. ISBN 1-56592-148-8</para> - </listitem> - - <listitem> - <para>Garfinkel, Simson. <emphasis>PGP Pretty Good - Privacy</emphasis> O'Reilly & Associates, Inc., 1995. ISBN - 1-56592-098-8</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-hardware"> - <title>Hardware Reference</title> - - <itemizedlist> - <listitem> - <para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor - System Architecture</emphasis>. 2nd Ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-40992-5</para> - </listitem> - - <listitem> - <para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA, - VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. : - Addison-Wesley, 1995. ISBN 0-201-62490-7</para> - </listitem> - - <listitem> - <para>Intel Corporation publishes documentation on their CPUs, - chipsets and standards on their <ulink - url="http://developer.intel.com/">developer web site</ulink>, - usually as PDF files.</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40994-1</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40996-8</para> - </listitem> - - <listitem> - <para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>. - 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN - 0-201-40993-3</para> - </listitem> - - <listitem> - <para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>. - Reading, Mass: Addison-Wesley Pub. Co., 1994. ISBN - 0-201-62277-7</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-history"> - <title>UNIX History</title> - - <itemizedlist> - <listitem> - <para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With - Source Code</emphasis>. ITP Media Group, 1996. ISBN - 1573980137</para> - </listitem> - - <listitem> - <para>Raymond, Eric S. <emphasis>The New Hacker's Dictionary, 3rd - edition</emphasis>. MIT Press, 1996. ISBN - 0-262-68092-0. Also known as the <ulink - url="http://www.ccil.org/jargon/jargon.html">Jargon - File</ulink></para> - </listitem> - - <listitem> - <para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>. - Addison-Wesley Publishing Company, Inc., 1994. ISBN - 0-201-54777-5</para> - </listitem> - - <listitem> - <para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The - UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc., - 1994. ISBN 1-56884-203-1</para> - </listitem> - - <listitem> - <para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis> - — special edition. Prentice-Hall, Inc., 1989. ISBN - 0-13-536657-7</para> - </listitem> - - <listitem> - <para><emphasis>The BSD family tree</emphasis>. 1997. <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family-tree</ulink> or <ulink url="file:/usr/share/misc/bsd-family-tree">local</ulink> on a FreeBSD-current machine.</para> - </listitem> - - <listitem> - <para><emphasis>The BSD Release Announcements collection</emphasis>. - 1997. <ulink - url="http://www.de.FreeBSD.org/de/ftp/releases/">http://www.de.FreeBSD.org/de/ftp/releases/</ulink></para> - </listitem> - - <listitem> - <para><emphasis>Networked Computer Science Technical Reports - Library</emphasis>. <ulink - url="http://www.ncstrl.org/">http://www.ncstrl.org/</ulink></para> - </listitem> - - <listitem> - <para><emphasis>Old BSD releases from the Computer Systems Research - group (CSRG)</emphasis>. <ulink - url="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</ulink>: - The 4CD set covers all BSD versions from 1BSD to 4.4BSD and - 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). As well, the last - disk holds the final sources plus the SCCS files.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="bibliography-journals"> - <title>Magazines and Journals</title> - - <itemizedlist> - <listitem> - <para><emphasis>The C/C++ Users Journal</emphasis>. R&D - Publications Inc. ISSN 1075-2838</para> - </listitem> - - <listitem> - <para><emphasis>Sys Admin — The Journal for UNIX System - Administrators</emphasis> Miller Freeman, Inc., ISSN - 1061-2688</para> - </listitem> - </itemizedlist> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml deleted file mode 100644 index 233db36773..0000000000 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ /dev/null @@ -1,142 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/book.sgml,v 1.91 2000/07/29 21:18:55 asmodai Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; - -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> -%authors; -<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists; -<!ENTITY % newsgroups SYSTEM "newsgroups.ent"> %newsgroups; -<!ENTITY % not.published "INCLUDE"> - -<!-- The currently released version of FreeBSD. This value is used to - create some links on web sites and such, so do NOT change it until - it's really release time --> -<!ENTITY rel.current CDATA "4.1.1"> -]> - -<book> - <bookinfo> - <title>FreeBSD Handbook</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - <affiliation> - <address> - <email>doc@FreeBSD.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>February 1999</pubdate> - - <copyright> - <year>1995</year> - <year>1996</year> - <year>1997</year> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - &bookinfo.legalnotice; - - <abstract> - <para>Welcome to FreeBSD! This handbook covers the installation and day - to day use of <emphasis>FreeBSD Release &rel.current;</emphasis>. - This manual is a <emphasis>work in progress</emphasis> 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 &a.doc;. The latest version of - this document is always available from the <ulink - URL="http://www.FreeBSD.org/">FreeBSD World Wide Web server</ulink>. - It may also be downloaded in a variety of formats and compression - options from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc">FreeBSD FTP - server</ulink> or one of the numerous <link - linkend="mirrors-ftp">mirror sites</link>. If you would prefer - to have a hard copy of the handbook, you can purchase one at the - <ulink - url="http://www.freebsdmall.com/books/">FreeBSD Mall</ulink>. You - may also want to <ulink - URL="http://www.FreeBSD.org/search.html">Search the - Handbook</ulink>.</para> - </abstract> - </bookinfo> - - <part> - <title>Getting Started</title> - - &chap.introduction; - &chap.install; - &chap.basics; - &chap.ports; - </part> - - <part> - <title>System Administration</title> - - &chap.boot; - &chap.users; - &chap.kernelconfig; - &chap.security; - &chap.printing; - &chap.disks; - &chap.backups; - &chap.x11; - &chap.l10n; - </part> - - <part> - <title>Network Communications</title> - - &chap.serialcomms; - &chap.ppp-and-slip; - &chap.advanced-networking; - &chap.mail; - </part> - - <part> - <title>Advanced topics</title> - - &chap.cutting-edge; - &chap.contrib; - &chap.policies; - &chap.kernelopts; - &chap.kerneldebug; - &chap.linuxemu; - &chap.internals; - </part> - - <part> - <title>Appendices</title> - - &chap.mirrors; - &chap.bibliography; - &chap.eresources; - &chap.staff; - &chap.pgpkeys; - &chap.hw; - </part> -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml deleted file mode 100644 index f87beacb07..0000000000 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml +++ /dev/null @@ -1,549 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/boot/chapter.sgml,v 1.7 2000/04/07 21:26:56 jim Exp $ ---> - -<chapter id="boot"> - <title>The FreeBSD Booting Process</title> - - <sect1 id="boot-synopsis"> - <title>Synopsis</title> - - <para>FreeBSD uses a three-stage bootstrap by default, which - basically entails three programs which call each - other in order (two <link linkend="boot-blocks">boot - blocks</link>, and the <link - linkend="boot-loader">loader</link>). Each of these three build on the - previous program's understanding and provide increasing amounts - of sophistication.</para> - - <para>The kernel is then started, which will then probe for devices - and initialize them for use. Once the kernel boot - process is finished, the kernel passes control to the user process - &man.init.8;, which then makes sure the disks are in a usable state. - &man.init.8; then starts the user-level resource configuration which - then mounts filesystems, sets up network cards to act on the - network, and generally starts all the processes that usually - are run on a FreeBSD system at startup.</para> - </sect1> - - <sect1 id="boot-blocks"> - <title>The Boot Blocks: Bootstrap Stages 1 and 2</title> - - <para><firstterm>Bootstrapping</firstterm> is the process - whereby a computer probes and initializes its devices, and - works out what programs it is supposed to run.</para> - - <para>This involves the use of special Read Only Memory chips, - which determine what further operations to do, and these - usually pass control to other chips that do consistency and - memory tests, configure devices, and provide a mechanism for - programs to determine what configuration details were - determined.</para> - - <para>In standard personal computers, this involves the BIOS - (which oversees the bootstrap), and CMOS (which stores - configuration). BIOS and CMOS understand disks, and also - understand where on the disk to find a program that will know - how to load up an operating system.</para> - - <para>This chapter will not deal with this first part of the - bootstrap process. Instead it will focus on what happens after control - is passed to the program on the disk.</para> - - <para>The boot blocks are responsible for finding (usually) the - loader, and running it, and thus need to understand how to - find that program on the filesystem, how to run the program, - and also allow minor configuration of how they work.</para> - - <sect2 id="boot-boot0"> - <title>boot0</title> - - <para>There is actually a preceding bootblock, named boot0, - which lives on the <firstterm>Master Boot - Record</firstterm>, the special part of the disk that the - system bootstrap looks for and runs, and it simply shows a - list of possible slices to boot from.</para> - - <para>boot0 is very simple, since the program in the - <abbrev>MBR</abbrev> can only be 512 bytes in size.</para> - - <para>It displays something like this:</para> - - <example id="boot-boot0-example"> - <title>boot0 screenshot</title> - - <screen> -F1 DOS -F2 FreeBSD -F3 Linux -F4 ?? -F5 Drive 1 - -Default: F2</screen> - </example> - </sect2> - - <sect2 id="boot-boot1"> - <title>boot1</title> - - <para>boot1 is found on the boot sector of the boot slice, - which is where <link linkend="boot-boot0">boot0</link>, or - any other program on the <abbrev>MBR</abbrev> expects to - find the program to run to continue the boot process.</para> - - <para>boot1 is very simple, since it too can only be 512 bytes - in size, and knows just enough about the FreeBSD - <firstterm>disklabel</firstterm>, which stores information - about the slice, to find and execute <link - linkend="boot-boot2">boot2</link>.</para> - </sect2> - - <sect2 id="boot-boot2"> - <title>boot2</title> - - <para>boot2 is slightly more sophisticated, and understands - the FreeBSD filesystem enough to find files on it, and can - provide a simple interface to choose the kernel or loader to - run.</para> - - <para>Since the <link linkend="boot-loader">loader</link> is - much more sophisticated, and provides a nice easy-to-use - boot configuration, boot2 usually runs it, but previously it - was tasked to run the kernel directly.</para> - - <example id="boot-boot2-example"> - <title>boot2 screenshot</title> - - <screen>>> FreeBSD/i386 BOOT -Default: 0:wd(0,a)/kernel -boot:</screen> - </example> - </sect2> - </sect1> - - <sect1 id="boot-loader"> - <title>Loader: Bootstrap Stage Three</title> - - <para>The loader is the final stage of the three-stage - bootstrap, and is located on the filesystem, usually as - <filename>/boot/loader</filename>.</para> - - <note> - <para>While <filename>/boot/boot0</filename>, - <filename>/boot/boot1</filename>, and - <filename>/boot/boot2</filename> are files there, they are - not the actual copies in the <abbrev>MBR</abbrev>, the boot - sector, or the disklabel respectively.</para> - </note> - - <para>The loader is intended as a user-friendly method for - configuration, using an easy-to-use built-in command set, - backed up by a more powerful interpreter, with a more complex - command set.</para> - - <sect2 id="boot-loader-flow"> - <title>Loader Program Flow</title> - - <para>During initialization, the loader will probe for a - console and for disks, and figure out what disk it is - booting from. It will set variables accordingly, and then - the interpreter is started, and the easy-to-use commands are - explained to it.</para> - - <para>loader will then read - <filename>/boot/loader.rc</filename>, which by default reads - in <filename>/boot/defaults/loader.conf</filename> which - sets reasonable defaults for variables and reads - <filename>/boot/loader.conf</filename> for local changes to - those variables. <filename>loader.rc</filename> then acts - on these variables, loading whichever modules and kernel are - selected.</para> - - <para>Finally, by default, the loader issues a 10 second wait - for keypresses, and boots the kernel if it is interrupted. - If interrupted, the user is presented with a prompt which - understands the easy-to-use command set, where the user may - adjust variables, unload all modules, load modules, and then - finally boot or reboot.</para> - - <para>A more technical discussion of the process is available - in &man.loader.8;</para> - </sect2> - - <sect2 id="boot-loader-commands"> - <title>Loader Built-In Commands</title> - - <para>The easy-to-use command set comprises of:</para> - - <variablelist> - <varlistentry> - <term>autoboot <replaceable>seconds</replaceable></term> - - <listitem> - <para>Proceeds to boot the kernel if not interrupted - within the time span given, in seconds. It displays a - countdown, and the default timespan is 10 - seconds.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>boot - <optional><replaceable>-options</replaceable></optional> - <optional><replaceable>kernelname</replaceable></optional></term> - - <listitem> - <para>Immediately proceeds to boot the kernel, with the - given options, if any, and with the kernel name given, - if it is.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>boot-conf</term> - - <listitem> - <para>Goes through the same automatic configuration of - modules based on variables as what happens at boot. - This only makes sense if you use - <command>unload</command> first, and change some - variables, most commonly <envar>kernel</envar>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>help - <optional><replaceable>topic</replaceable></optional></term> - - <listitem> - <para>Shows help messages read from - <filename>/boot/loader.help</filename>. If the topic - given is <literal>index</literal>, then the list of - available topics is given.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>include <replaceable>filename</replaceable> - …</term> - - <listitem> - <para>Processes the file with the given filename. The - file is read in, and interpreted line by line. An - error immediately stops the include command.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>load <optional><option>-t</option> - <replaceable>type</replaceable></optional> - <replaceable>filename</replaceable></term> - - <listitem> - <para>Loads the kernel, kernel module, or file of the - type given, with the filename given. Any arguments - after filename are passed to the file.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>ls <optional><option>-l</option></optional> - <optional><replaceable>path</replaceable></optional></term> - - <listitem> - <para>Displays a listing of files in the given path, or - the root directory, if the path is not specified. If - <option>-l</option> is specified, file sizes will be - shown too.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>lsdev <optional><option>-v</option></optional></term> - - <listitem> - <para>Lists all of the devices from which it may be - possible to load modules. If <option>-v</option> is - specified, more details are printed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>lsmod <optional><option>-v</option></optional></term> - - <listitem> - <para>Displays loaded modules. If <option>-v</option> is - specified, more details are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>more <replaceable>filename</replaceable></term> - - <listitem> - <para>Display the files specified, with a pause at each - <varname>LINES</varname> displayed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>reboot</term> - - <listitem> - <para>Immediately reboots the system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>set <replaceable>variable</replaceable></term> - <term>set - <replaceable>variable</replaceable>=<replaceable>value</replaceable></term> - - <listitem> - <para>Set loader's environment variables.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>unload</term> - - <listitem> - <para>Removes all loaded modules.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="boot-loader-examples"> - <title>Loader Examples</title> - - <para>Here are some practical examples of loader usage.</para> - - <itemizedlist> - <listitem> - <para>To simply boot your usual kernel, but in single-user - mode:</para> - - <screen><userinput>boot -s</userinput></screen> - </listitem> - - <listitem> - <para>To unload your usual kernel and modules, and then - load just your old (or another) kernel:</para> - - <screen><userinput>unload</userinput> - <userinput>load <replaceable>kernel.old</replaceable></userinput></screen> - - <para>You can use <filename>kernel.GENERIC</filename> to - refer to the generic kernel that comes on the install - disk, or <filename>kernel.old</filename> to refer to - your previously installed kernel (when you've upgraded - or configured your own kernel, for example).</para> - - <note> - <para>Use the following to load your usual modules with - another kernel:</para> - - <screen><userinput>unload</userinput> -<userinput>set kernel="<replaceable>kernel.old</replaceable>"</userinput> -<userinput>boot-conf</userinput></screen> - </note> - </listitem> - - <listitem> - <para>To load a kernel configuration script (an automated - script which does the things you'd normally do in the - kernel boot-time configurator):</para> - - <screen><userinput>load -t userconfig_script - <replaceable>/boot/kernel.conf</replaceable></userinput></screen> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="boot-kernel"> - <title>Kernel Interaction During Boot</title> - - <para>Once the kernel is loaded by either <link - linkend="boot-loader">loader</link> (as usual) or <link - linkend="boot-boot2">boot2</link> (bypassing the loader), it - examines its boot flags, if any, and adjusts its behavior as - necessary.</para> - - <sect2 id="boot-kernel-bootflags"> - <title>Kernel Boot Flags</title> - - <para>Here are the more common boot flags:</para> - - <variablelist id="boot-kernel-bootflags-list"> - <varlistentry> - <term><option>-a</option></term> - - <listitem> - <para>during kernel initialization, ask for the device - to mount as as the root file system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-C</option></term> - - <listitem> - <para>boot from CDROM.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>run UserConfig, the boot-time kernel - configurator</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - - <listitem> - <para>boot into single-user mode</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v</option></term> - - <listitem> - <para>be more verbose during kernel startup</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>There are other boot flags, read &man.boot.8; for more - information on them.</para> - </note> - </sect2> - -<!-- <sect2 id="boot-kernel-userconfig"> - <title>UserConfig: The boot-time kernel configurator</title> - - <para> </para> - </sect2> --> - </sect1> - - <sect1 id="boot-init"> - <title>Init: Process Control Initialization</title> - - <para>Once the kernel has finished booting, it passes control to - the user process <command>init</command>, which is located at - <filename>/sbin/init</filename>, or the program path specified - in the <envar>init_path</envar> variable in - <command>loader</command>.</para> - - <sect2 id="boot-autoreboot"> - <title>Automatic Reboot Sequence</title> - - <para>The automatic reboot sequence makes sure that the - filesystems available on the system are consistent. If they - are not, and <command>fsck</command> can not fix the - inconsistencies, <command>init</command> drops the system - into <link linkend="boot-singleuser">single-user mode</link> - for the system administrator to take care of the problems - directly.</para> - </sect2> - - <sect2 id="boot-singleuser"> - <title>Single-User Mode</title> - - <para>This mode can be reached through the <link - linkend="boot-autoreboot">automatic reboot - sequence</link>, or by the user booting with the - <option>-s</option> or setting the - <envar>boot_single</envar> variable in - <command>loader</command>.</para> - - <para>It can also be reached by calling - <command>shutdown</command> without the reboot - (<option>-r</option>) or halt (<option>-h</option>) options, - from <link linkend="boot-multiuser">multi-user - mode</link>.</para> - - <para>If the system console <literal>console</literal> is set - to <literal>insecure</literal> in - <filename>/etc/ttys</filename>, then the system prompts for - the root password before initiating single-user mode.</para> - - <example id="boot-insecure-console"> - <title>An insecure console in /etc/ttys</title> - - <programlisting># name getty type status comments -# -# This entry needed for asking password when init goes to single-user mode -# If you want to be asked for password, change "secure" to "insecure" here -console none unknown off insecure</programlisting> - </example> - - <note> - <para>An <literal>insecure</literal> console means that you - consider your physical security to the console to be - insecure, and want to make sure only someone who knows the - root password may use single-user mode, and it does not - mean that you want to run your console insecurely. Thus, - if you want security, choose <literal>insecure</literal>, - not <literal>secure</literal>.</para> - </note> - </sect2> - - <sect2 id="boot-multiuser"> - <title>Multi-User Mode</title> - - <para>If <command>init</command> finds your filesystems to be - in order, or once the user has finished in <link - linkend="boot-singleuser">single-user mode</link>, the - system enters multi-user mode, in which it starts the - resource configuration of the system.</para> - - <sect3 id="boot-rc"> - <title>Resource Configuration (rc)</title> - - <para>The resource configuration system reads in - configuration defaults from - <filename>/etc/defaults/rc.conf</filename>, and - system-specific details from - <filename>/etc/rc.conf</filename>, and then proceeds to - mount the system filesystems mentioned in - <filename>/etc/fstab</filename>, start up networking - services, starts up miscellaneous system daemons, and - finally runs the startup scripts of locally installed - packages.</para> - - <para>&man.rc.8; is a good reference to the resource - configuration system, as is examining the scripts - themselves.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="boot-shutdown"> - <title>Shutdown Sequence</title> - - <para>Upon controlled shutdown, via <command>shutdown</command>, - <command>init</command> will attempt to run the script - <filename>/etc/rc.shutdown</filename>, and then proceed to send - all processes the terminate signal, and subsequently the kill - signal to any that don't terminate timely.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/chapter.decl b/en_US.ISO8859-1/books/handbook/chapter.decl deleted file mode 100644 index ce0a7ed16a..0000000000 --- a/en_US.ISO8859-1/books/handbook/chapter.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent deleted file mode 100644 index 990f8a51b3..0000000000 --- a/en_US.ISO8859-1/books/handbook/chapters.ent +++ /dev/null @@ -1,50 +0,0 @@ -<!-- - Creates entities for each chapter in the FreeBSD Handbook. Each entity - is named chap.foo, where foo is the value of the id attribute on that - chapter, and corresponds to the name of the directory in which that - chapter's .sgml file is stored. - - Chapters should be listed in the order in which they are referenced. - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/chapters.ent,v 1.7 2000/03/17 10:44:01 nbm Exp $ ---> - -<!-- Part one --> -<!ENTITY chap.introduction SYSTEM "introduction/chapter.sgml"> -<!ENTITY chap.install SYSTEM "install/chapter.sgml"> -<!ENTITY chap.basics SYSTEM "basics/chapter.sgml"> -<!ENTITY chap.ports SYSTEM "ports/chapter.sgml"> - -<!-- Part two --> -<!ENTITY chap.boot SYSTEM "boot/chapter.sgml"> -<!ENTITY chap.users SYSTEM "users/chapter.sgml"> -<!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.sgml"> -<!ENTITY chap.security SYSTEM "security/chapter.sgml"> -<!ENTITY chap.printing SYSTEM "printing/chapter.sgml"> -<!ENTITY chap.disks SYSTEM "disks/chapter.sgml"> -<!ENTITY chap.backups SYSTEM "backups/chapter.sgml"> -<!ENTITY chap.x11 SYSTEM "x11/chapter.sgml"> -<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml"> - -<!-- Part three --> -<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.sgml"> -<!ENTITY chap.ppp-and-slip SYSTEM "ppp-and-slip/chapter.sgml"> -<!ENTITY chap.advanced-networking SYSTEM "advanced-networking/chapter.sgml"> -<!ENTITY chap.mail SYSTEM "mail/chapter.sgml"> - -<!-- Part four --> -<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.sgml"> -<!ENTITY chap.contrib SYSTEM "contrib/chapter.sgml"> -<!ENTITY chap.policies SYSTEM "policies/chapter.sgml"> -<!ENTITY chap.kernelopts SYSTEM "kernelopts/chapter.sgml"> -<!ENTITY chap.kerneldebug SYSTEM "kerneldebug/chapter.sgml"> -<!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.sgml"> -<!ENTITY chap.internals SYSTEM "internals/chapter.sgml"> - -<!-- Part five (appendices) --> -<!ENTITY chap.mirrors SYSTEM "mirrors/chapter.sgml"> -<!ENTITY chap.bibliography SYSTEM "bibliography/chapter.sgml"> -<!ENTITY chap.eresources SYSTEM "eresources/chapter.sgml"> -<!ENTITY chap.staff SYSTEM "staff/chapter.sgml"> -<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.sgml"> -<!ENTITY chap.hw SYSTEM "hw/chapter.sgml"> diff --git a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml deleted file mode 100644 index 7144714cd4..0000000000 --- a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml +++ /dev/null @@ -1,6224 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml,v 1.337 2000/11/13 19:22:53 okazaki Exp $ ---> - -<chapter id="contrib"> - <title>Contributing to FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;.</emphasis></para> - - <para>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 - <emphasis>relies</emphasis> 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!</para> - - <para>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 whose 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.</para> - - <para>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 <filename>TODO</filename> 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!</para> - - <para>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.</para> - - <sect1 id="contrib-what"> - <title>What is Needed</title> - - <para>The following list of tasks and sub-projects represents something of - an amalgam of the various core team <filename>TODO</filename> 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?</para> - - <sect2> - <title>High priority tasks</title> - - <para>The following tasks are considered to be urgent, usually because - they represent something that is badly broken or sorely needed:</para> - - <orderedlist> - <listitem> - <para>3-stage boot issues. Overall coordination: &a.hackers;</para> - - <itemizedlist> - <listitem> - <para>Do WinNT compatible drive tagging so that the 3rd stage - can provide an accurate mapping of BIOS geometries for - disks.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Filesystem problems. Overall coordination: &a.fs;</para> - - <itemizedlist> - <listitem> - <para>Clean up and document the nullfs filesystem code. - Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Fix the union file system. Coordinator: &a.dg;</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Implement Int13 vm86 disk driver. Coordinator: - &a.hackers;</para> - </listitem> - - <listitem> - <para>New bus architecture. Coordinator: &a.newbus;</para> - - <itemizedlist> - <listitem> - <para>Port existing ISA drivers to new architecture.</para> - </listitem> - - <listitem> - <para>Move all interrupt-management code to appropriate parts of - the bus drivers.</para> - </listitem> - - <listitem> - <para>Port PCI subsystem to new architecture. Coordinator: - &a.dfr;</para> - </listitem> - - <listitem> - <para>Figure out the right way to handle removable devices and - then use that as a substrate on which PC-Card and CardBus - support can be implemented.</para> - </listitem> - - <listitem> - <para>Resolve the probe/attach priority issue once and for - all.</para> - </listitem> - - <listitem> - <para>Move any remaining buses over to the new - architecture.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Kernel issues. Overall coordination: &a.hackers;</para> - </listitem> - - <listitem> - <para>Add more pro-active security infrastructure. Overall - coordination: &a.security;</para> - - <itemizedlist> - <listitem> - <para>Build something like Tripwire(TM) into the kernel, with a - remote and local part. There are a number of cryptographic - issues to getting this right; contact the coordinator for - details. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make the entire kernel use <literal>suser()</literal> - instead of comparing to 0. It is presently using about half - of each. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Split securelevels into different parts, to allow an - administrator to throw away those privileges he can throw - away. Setting the overall securelevel needs to have the same - effect as now, obviously. Coordinator: &a.eivind;</para> - </listitem> - - <listitem> - <para>Make it possible to upload a list of <quote>allowed - program</quote> to BPF, and then block BPF from accepting other - programs. This would allow BPF to be used e.g. for DHCP, - without allowing an attacker to start snooping the local - network.</para> - </listitem> - - <listitem> - <para>Update the security checker script. We should at least - grab all the checks from the other BSD derivatives, and add - checks that a system with securelevel increased also have - reasonable flags on the relevant parts. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add authorization infrastructure to the kernel, to allow - different authorization policies. Part of this could be done - by modifying <literal>suser()</literal>. Coordinator: - &a.eivind;</para> - </listitem> - - <listitem> - <para>Add code to the NFS layer so that you cannot - <literal>chdir("..")</literal> out of an NFS partition. E.g., - <filename>/usr</filename> is a UFS partition with - <filename>/usr/src</filename> NFS exported. Now it is - possible to use the NFS filehandle for - <filename>/usr/src</filename> to get access to - <filename>/usr</filename>.</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Medium priority tasks</title> - - <para>The following tasks need to be done, but not with any particular - urgency:</para> - - <orderedlist> - <listitem> - <para>Full KLD based driver support/Configuration Manager.</para> - - <itemizedlist> - <listitem> - <para>Write a configuration manager (in the 3rd stage boot?) - that probes your hardware in a sane manner, keeps only the - KLDs required for your hardware, etc.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>PCMCIA/PCCARD. Coordinators: &a.msmith; and &a.imp;</para> - - <itemizedlist> - <listitem> - <para>Documentation!</para> - </listitem> - - <listitem> - <para>Reliable operation of the pcic driver (needs - testing).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>sio.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ed.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>Recognizer and handler for <filename>ep.c</filename> - (mostly done).</para> - </listitem> - - <listitem> - <para>User-mode recognizer and handler (partially done).</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Advanced Power Management. Coordinators: &a.msmith; and - &a.phk;</para> - - <itemizedlist> - <listitem> - <para>APM sub-driver (mostly done).</para> - </listitem> - - <listitem> - <para>IDE/ATA disk sub-driver (partially done).</para> - </listitem> - - <listitem> - <para>syscons/pcvt sub-driver.</para> - </listitem> - - <listitem> - <para>Integration with the PCMCIA/PCCARD drivers - (suspend/resume).</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Low priority tasks</title> - - <para>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:</para> - - <para>The first N items are from Terry Lambert - <email>terry@lambert.org</email></para> - - <orderedlist> - <listitem> - <para>NetWare Server (protected mode ODI driver) loader and - sub-services to allow the use of ODI card drivers supplied with - network cards. The same thing for NDIS drivers and NetWare SCSI - drivers.</para> - </listitem> - - <listitem> - <para>An "upgrade system" option that works on Linux boxes instead - of just previous rev FreeBSD boxes.</para> - </listitem> - - <listitem> - <para>Symmetric Multiprocessing with kernel preemption (requires - kernel preemption).</para> - </listitem> - - <listitem> - <para>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 v.s.. 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).</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Smaller tasks</title> - - <para>Most of the tasks listed in the previous sections require either a - considerable investment of time or an in-depth knowledge of the - FreeBSD kernel (or both). However, there are also many useful tasks - which are suitable for "weekend hackers", or people without - programming skills.</para> - - <orderedlist> - <listitem> - <para>If you run FreeBSD-current and have a good Internet - connection, there is a machine <hostid - role="fqdn">current.FreeBSD.org</hostid> which builds a full - release once a day — every now and again, try and install - the latest release from it and report any failures in the - process.</para> - </listitem> - - <listitem> - <para>Read the freebsd-bugs mailing list. There might be a - problem you can comment constructively on or with patches you - can test. Or you could even try to fix one of the problems - yourself.</para> - </listitem> - - <listitem> - <para>Read through the FAQ and Handbook periodically. If anything - is badly explained, out of date or even just completely wrong, let - us know. Even better, send us a fix (SGML is not difficult to - learn, but there is no objection to ASCII submissions).</para> - </listitem> - - <listitem> - <para>Help translate FreeBSD documentation into your native language - (if not already available) — just send an email to &a.doc; - asking if anyone is working on it. Note that you are not - committing yourself to translating every single FreeBSD document - by doing this — in fact, the documentation most in need of - translation is the installation instructions.</para> - </listitem> - - <listitem> - <para>Read the freebsd-questions mailing list and &ng.misc - occasionally (or even regularly). It can be very satisfying to - share your expertise and help people solve their problems; - sometimes you may even learn something new yourself! These forums - can also be a source of ideas for things to work on.</para> - </listitem> - - <listitem> - <para>If you know of any bug fixes which have been successfully - applied to -current but have not been merged into -stable after a - decent interval (normally a couple of weeks), send the committer a - polite reminder.</para> - </listitem> - - <listitem> - <para>Move contributed software to <filename>src/contrib</filename> - in the source tree.</para> - </listitem> - - <listitem> - <para>Make sure code in <filename>src/contrib</filename> is up to - date.</para> - </listitem> - - <listitem> - <para>Look for year 2000 bugs (and fix any you find!)</para> - </listitem> - - <listitem> - <para>Build the source tree (or just part of it) with extra warnings - enabled and clean up the warnings.</para> - </listitem> - - <listitem> - <para>Fix warnings for ports which do deprecated things like using - gets() or including malloc.h.</para> - </listitem> - - <listitem> - <para>If you have contributed any ports, send your patches back to - the original author (this will make your life easier when they - bring out the next version)</para> - </listitem> - - <listitem> - <para>Suggest further tasks for this list!</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Work through the PR database</title> - - <para>The <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD PR - list</ulink> shows all the current active problem reports and - requests for enhancement that have been submitted by FreeBSD users. - Look through the open PRs, and see if anything there takes your - interest. Some of these might be very simple tasks, that just need an - extra pair of eyes to look over them and confirm that the fix in the - PR is a good one. Others might be much more complex.</para> - - <para>Start with the PRs that have not been assigned to anyone else, but - if one them is assigned to someone else, but it looks like something - you can handle, e-mail the person it is assigned to and ask if you can - work on it—they might already have a patch ready to be tested, - or further ideas that you can discuss with them.</para> - </sect2> - </sect1> - - <sect1 id="contrib-how"> - <title>How to Contribute</title> - - <para>Contributions to the system generally fall into one or more of the - following 6 categories:</para> - - <sect2 id="contrib-general"> - <title>Bug reports and general commentary</title> - - <para>An idea or suggestion of <emphasis>general</emphasis> technical - interest should be mailed to the &a.hackers;. Likewise, people with - an interest in such things (and a tolerance for a - <emphasis>high</emphasis> volume of mail!) may subscribe to the - hackers mailing list by sending mail to &a.majordomo;. See <link - linkend="eresources-mail">mailing lists</link> for more information - about this and other mailing lists.</para> - - <para>If you find a bug or are submitting a specific change, please - report it using the &man.send-pr.1; program or its <ulink - url="http://www.FreeBSD.org/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug report. - Unless they exceed 65KB, include any patches directly in the report. - When including patches, <emphasis>do not</emphasis> use cut-and-paste - because cut-and-paste turns tabs into spaces and makes them unusable. - Consider compressing patches and using &man.uuencode.1; if they exceed - 20KB. Upload very large submissions to <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp.FreeBSD.org:/pub/FreeBSD/incoming/</ulink>.</para> - - <para>After filing a report, you should receive confirmation along with - a tracking number. Keep this tracking number so that you can update - us with details about the problem by sending mail to - <email>bug-followup@FreeBSD.org</email>. Use the number as the - message subject, e.g. <literal>"Re: kern/3377"</literal>. Additional - information for any bug report should be submitted this way.</para> - - <para>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 &man.send-pr.1; command, then you may ask - someone to file it for you by sending mail to the &a.bugs;.</para> - </sect2> - - <sect2> - <title>Changes to the documentation</title> - - <para>Changes to the documentation are overseen by the &a.doc;. Send - submissions and changes (even small ones are welcome!) using - <command>send-pr</command> as described in <link - linkend="contrib-general">Bug Reports and General - Commentary</link>.</para> - </sect2> - - <sect2> - <title>Changes to existing source code</title> - - <para>An addition or change to the existing source code is a somewhat - trickier affair and depends a lot on how far out of date you are with - the current state of the core FreeBSD development. There is a special - on-going release of FreeBSD known as <quote>FreeBSD-current</quote> - which is made available in a variety of ways for the convenience of - developers working actively on the system. See <link - linkend="current">Staying current with FreeBSD</link> for more - information about getting and using FreeBSD-current.</para> - - <para>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 &a.announce; and the &a.current; lists, where - discussions on the current state of the system take place.</para> - - <para>Assuming that you can manage to secure fairly up-to-date sources - to base your changes on, the next step is to produce a set of diffs to - send to the FreeBSD maintainers. This is done with the &man.diff.1; - command, with the <quote>context diff</quote> form - being preferred. For example:</para> - - <para> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - - or - - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - - would generate such a set of context diffs for the given source file - or directory hierarchy. See the man page for &man.diff.1; for more - details.</para> - - <para>Once you have a set of diffs (which you may test with the - &man.patch.1; command), you should submit them for inclusion with - FreeBSD. Use the &man.send-pr.1; program as described in <link - linkend="contrib-general">Bug Reports and General Commentary</link>. - <emphasis>Do not</emphasis> just send the diffs to the &a.hackers; or - they will get lost! We greatly appreciate your submission (this is a - volunteer project!); because we are busy, we may not be able to - address it immediately, but it will remain in the pr database until we - do.</para> - - <para>If you feel it appropriate (e.g. you have added, deleted, or - renamed files), bundle your changes into a <command>tar</command> file - and run the &man.uuencode.1; program on it. Shar archives are also - welcome.</para> - - <para>If your change is of a potentially sensitive nature, e.g. 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 &a.core; directly rather than submitting it - with &man.send-pr.1;. 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 <emphasis>very busy</emphasis> and so you - should only send mail to them where it is truly necessary.</para> - - <para>Please refer to <command>man 9 intro</command> and <command>man 9 - style</command> for some information on coding style. We would - appreciate it if you were at least aware of this information before - submitting code.</para> - </sect2> - - <sect2> - <title>New code or major value-added packages</title> - - <para>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 a web or FTP site for other people to - access. If you do not have access to a web or FTP site, ask on an - appropriate FreeBSD mailing list for someone to host the changes for - you.</para> - - <para>When working with large amounts of code, the touchy subject of - copyrights also invariably comes up. Acceptable copyrights for code - included in FreeBSD are:</para> - - <orderedlist> - <listitem> - <para>The BSD copyright. This copyright is most preferred due to - its <quote>no strings attached</quote> nature and general - attractiveness to commercial enterprises. Far from discouraging - such commercial use, the FreeBSD Project actively encourages such - participation by commercial interests who might eventually be - inclined to invest something of their own into FreeBSD.</para> - </listitem> - - <listitem> - <para>The GNU Public License, or <quote>GPL</quote>. 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, assembler, text formatter, etc) it would be silly to - refuse additional contributions under this license. Code under - the GPL also goes into a different part of the tree, that being - <filename>/sys/gnu</filename> or - <filename>/usr/src/gnu</filename>, and is therefore easily - identifiable to anyone for whom the GPL presents a problem.</para> - </listitem> - </orderedlist> - - <para>Contributions coming under any other type of copyright must be - carefully reviewed before their inclusion into FreeBSD will be - considered. Contributions for which particularly restrictive - commercial copyrights apply are generally rejected, though the authors - are always encouraged to make such changes available through their own - channels.</para> - - <para>To place a <quote>BSD-style</quote> copyright on your work, include - the following text at the very beginning of every source code file you - wish to protect, replacing the text between the <literal>%%</literal> - with the appropriate information.</para> - - <programlisting> -Copyright (c) %%proper_years_here%% - %%your_name_here%%, %%your_state%% %%your_zip%%. - All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -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$</programlisting> - - <para>For your convenience, a copy of this text can be found in - <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> - </sect2> - - <sect2> - <title>Money, Hardware or Internet access</title> - - <para>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.</para> - - <sect3> - <title><anchor id="donations">Donating funds</title> - - <para>While the FreeBSD Project is not a 501(c)(3) (charitable) - 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.</para> - - <para>FreeBSD, Inc. was founded in early 1995 by &a.jkh; and &a.dg; - 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.</para> - - <para>Please make any checks payable to FreeBSD, Inc., sent in care of - the following address:</para> - - <address> - <otheraddr>FreeBSD, Inc.</otheraddr> - <otheraddr>c/o Jordan Hubbard</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city> - <state>CA</state>, <postcode>94520</postcode> - </address> - - <para>(currently using the BSDi address until a PO box - can be opened)</para> - - <para>Wire transfers may also be sent directly to:</para> - - <address> - <otheraddr>Bank Of America</otheraddr> - <otheraddr>Concord Main Office</otheraddr> - <pob>P.O. Box 37176</pob> - <city>San Francisco</city> - <state>CA</state>, <postcode>94137-5176</postcode> - - <otheraddr>Routing #: 121-000-358</otheraddr> - <otheraddr>Account #: 01411-07441 (FreeBSD, Inc.)</otheraddr> - </address> - - <para>Any correspondence related to donations should be sent to &a.jkh, - either via email or to the FreeBSD, Inc. postal address given above. - </para> - - <para>If you do not wish to be listed in our <link - linkend="donors">donors</link> section, please specify this when - making your donation. Thanks!</para> - </sect3> - - <sect3> - <title>Donating hardware</title> - - <para>Donations of hardware in any of the 3 following categories are - also gladly accepted by the FreeBSD Project:</para> - - <itemizedlist> - <listitem> - <para>General purpose hardware such as disk drives, memory or - complete systems should be sent to the FreeBSD, Inc. address - listed in the <emphasis>donating funds</emphasis> - section.</para> - </listitem> - - <listitem> - <para>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.dg; - for information on which items are still required.</para> - </listitem> - - <listitem> - <para>Hardware currently unsupported by FreeBSD for which you - would like to see such support added. Please contact the - &a.core; before sending such items as we will need to find a - developer willing to take on the task before we can accept - delivery of new hardware.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Donating Internet access</title> - - <para>We can always use new mirror sites for FTP, WWW or - <command>cvsup</command>. If you would like to be such a mirror, - please contact the FreeBSD project administrators - <email>hubs@FreeBSD.org</email> for more information.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="donors"> - <title>Donors Gallery</title> - - <para>The FreeBSD Project is indebted to the following donors and would - like to publicly thank them here!</para> - - <itemizedlist> - <listitem> - <para><emphasis>Contributors to the central server - project:</emphasis></para> - - <para>The following individuals and businesses made it possible for - the FreeBSD Project to build a new central server machine to - eventually replace <hostid role="fqdn">freefall.FreeBSD.org</hostid> - by donating the following items:</para> - - <itemizedlist> - <listitem> - <para>&a.mbarkah and his employer, <ulink url="http://www.hemi.com/"> - Hemisphere Online</ulink>, donated a <emphasis>Pentium Pro - (P6) 200Mhz CPU</emphasis></para> - </listitem> - - <listitem> - <para><ulink url="http://www.asacomputers.com/">ASA - Computers</ulink> donated a <emphasis>Tyan 1662 - motherboard</emphasis>.</para> - </listitem> - - <listitem> - <para>Joe McGuckin <email>joe@via.net</email> of <ulink - url="http://www.via.net/">ViaNet Communications</ulink> donated - a <emphasis>Kingston ethernet controller.</emphasis></para> - </listitem> - - <listitem> - <para>Jack O'Neill <email>jack@diamond.xtalwind.net</email> - donated an <emphasis>NCR 53C875 SCSI controller - card</emphasis>.</para> - </listitem> - - <listitem> - <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink - url="http://www.Alameda.net/">Alameda Networks</ulink> donated - <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk - drive and the case.</emphasis></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Direct funding:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed direct funding to the project:</para> - - <itemizedlist> - <listitem> - <para>Annelise Anderson - <email>ANDRSN@HOOVER.STANFORD.EDU</email></para> - </listitem> - - <listitem> - <para>&a.dillon</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bluemountain.com/">Blue Mountain - Arts</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.epilogue.com/">Epilogue Technology - Corporation</ulink></para> - </listitem> - - <listitem> - <para>&a.sef</para> - </listitem> - - <listitem> - <para><ulink url="http://www.gta.com/">Global Technology - Associates, Inc</ulink></para> - </listitem> - - <listitem> - <para>Don Scott Wilde</para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@masternet.it</email></para> - </listitem> - - <listitem> - <para>Josef C. Grosch <email>joeg@truenorth.org</email></para> - </listitem> - - <listitem> - <para>Robert T. Morris</para> - </listitem> - - <listitem> - <para>&a.chuckr</para> - </listitem> - - <listitem> - <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of - <ulink url="http://www.imagescape.com/">Imaginary Landscape, - LLC.</ulink></para> - </listitem> - - <listitem> - <para>Dmitry S. Kohmanyuk <email>dk@dog.farm.org</email></para> - </listitem> - - <listitem> - <para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan - (a portion of the profits from sales of their various FreeBSD - CDROMs).</para> - </listitem> - - <listitem> - <para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan - Publishing Co.</ulink> donated a portion of their profits from - <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting - started) to the FreeBSD and XFree86 projects.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink> - donated a portion of their profits from several FreeBSD-related - books to the FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric - Corp</ulink> has generously donated significant funding to the - FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.pacificsolutions.com/">Pacific - Solutions</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.siemens.de/">Siemens AG</ulink> - via <ulink url="mailto:andre.albsmeier@mchp.siemens.de">Andre - Albsmeier</ulink></para> - </listitem> - - <listitem> - <para><ulink url="mailto:ras@interaccess.com">Chris Silva</ulink> - </para> - </listitem> - - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Hardware contributors:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support:</para> - - <itemizedlist> - <listitem> - <para>BSDi for providing the Pentium P5-90 and - 486/DX2-66 EISA/VL systems that are being used for our - development work, to say nothing of the network access and other - donations of hardware resources.</para> - </listitem> - - <listitem> - <para>TRW Financial Systems, Inc. provided 130 PCs, three 68 GB - fileservers, twelve Ethernets, two routers and an ATM switch for - debugging the diskless code.</para> - </listitem> - - <listitem> - <para>Dermot McDonnell donated the Toshiba XM3401B CDROM drive - currently used in freefall.</para> - </listitem> - - <listitem> - <para>&a.chuck; contributed his floppy tape streamer for - experimental work.</para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;, - provided Wangtek and Archive QIC-02 tape drives in order to - improve the <devicename>wt</devicename> driver.</para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed - a 2.88 MB floppy drive to the project. This will hopefully - increase the pressure for rewriting the floppy disk driver. - <!-- smiley -->;-)</para> - </listitem> - - <listitem> - <para><ulink url="http://www.tekram.com/">Tekram - Technologies</ulink> sent one each of their DC-390, DC-390U - and DC-390F FAST and ULTRA SCSI host adapter cards for - regression testing of the NCR and AMD drivers with their cards. - They are also to be applauded for making driver sources for free - operating systems available from their FTP server <ulink - url="ftp://ftp.tekram.com/scsi/FreeBSD/">ftp://ftp.tekram.com/scsi/FreeBSD/</ulink>.</para> - </listitem> - - <listitem> - <para>Larry M. Augustin contributed not only a - Symbios Sym8751S SCSI card, but also a set of data books, - including one about the forthcoming Sym53c895 chip with Ultra-2 - and LVD support, and the latest programming manual with - information on how to safely use the advanced features of the - latest Symbios SCSI chips. Thanks a lot!</para> - </listitem> - - <listitem> - <para>Christoph Kukulies <email>kuku@FreeBSD.org</email> donated - an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver - development.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Special contributors:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM) - has donated almost more than we can say (see the <link - linkend="history">history</link> document for more details). - In particular, we would like to thank them for the original - hardware used for <hostid - role="fqdn">freefall.FreeBSD.org</hostid>, our primary - development machine, and for <hostid - role="fqdn">thud.FreeBSD.org</hostid>, a 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.</para> - </listitem> - - <listitem> - <para>The <ulink url="http://www.interface-business.de/">interface - business GmbH, Dresden</ulink> has been patiently supporting - &a.joerg; who has often preferred FreeBSD work over paid work, and - used to fall back to their (quite expensive) EUnet Internet - connection whenever his private connection became too slow or - flaky to work with it...</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bsdi.com/">Berkeley Software Design, - Inc.</ulink> has contributed their DOS emulator code to the - remaining BSD world, which is used in the - <emphasis>doscmd</emphasis> command.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-corealumni"> - <title>Core Team Alumni</title> - - <para>The following people were members of the FreeBSD core team during - the periods indicated. We thank them for their past efforts in the - service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - <itemizedlist> - <listitem> - <para>&a.ache (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jmb (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.bde (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gibbs (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.rich (1994 - 2000)</para> - </listitem> - - <listitem> - <para>&a.phk (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gpalmer (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.sos (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.wollman (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.joerg (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jdp (1997 - 2000)</para> - </listitem> - - <listitem> - <para>&a.guido (1995 - 1999)</para> - </listitem> - - <listitem> - <para>&a.dyson (1993 - 1998)</para> - </listitem> - - <listitem> - <para>&a.nate (1992 - 1996)</para> - </listitem> - - <listitem> - <para>&a.rgrimes (1992 - 1995)</para> - </listitem> - - <listitem> - <para>Andreas Schulz (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.csgr (1993 - 1995)</para> - </listitem> - - <listitem> - <para>&a.paul (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.smace (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Andrew Moore (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Christoph Robitschko (1993 - 1994)</para> - </listitem> - - <listitem> - <para>J. T. Conklin (1992 - 1993)</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-develalumni"> - <title>Development Team Alumni</title> - - <para>The following people were members of the FreeBSD development team - during the periods indicated. We thank them for their past efforts - in the service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - <itemizedlist> - <listitem> - <para>&a.tedm (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.karl (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.gclarkii (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.jraynard (???? - 2000)</para> - </listitem> - <listitem> - <para>&a.jgreco (???? - 1999)</para> - </listitem> - <listitem> - <para>&a.ats (???? - 1999)</para> - </listitem> - <listitem> - <para>Jamil Weatherby (1997 - 1999)</para> - </listitem> - <listitem> - <para>meganm (???? - 1998)</para> - </listitem> - <listitem> - <para>&a.dyson (???? - 1998)</para> - </listitem> - <listitem> - <para>Amancio Hasty (1997 - 1998)</para> - </listitem> - <listitem> - <para>Drew Derbyshire (1997 - 1998)</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-derived"> - <title>Derived Software Contributors</title> - - <para>This software was originally derived from William F. Jolitz's 386BSD - release 0.1, though almost none of the original 386BSD specific code - remains. This software has been essentially re-implemented from the - 4.4BSD-Lite release provided by the Computer Science Research Group - (CSRG) at the University of California, Berkeley and associated academic - contributors.</para> - - <para>There are also portions of NetBSD and OpenBSD that have been - integrated into FreeBSD as well, and we would therefore like to thank - all the contributors to NetBSD and OpenBSD for their work.</para> - </sect1> - - <sect1 id="contrib-additional"> - <title>Additional FreeBSD Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>AMAGAI Yoshiji <email>amagai@nue.org</email></para> - </listitem> - - <listitem> - <para>Aaron Bornstein <email>aaronb@j51.com</email></para> - </listitem> - - <listitem> - <para>Aaron Smith <email>aaron@mutex.org</email></para> - </listitem> - - <listitem> - <para>Achim Patzner <email>ap@noses.com</email></para> - </listitem> - - <listitem> - <para>Ada T Lim <email>ada@bsd.org</email></para> - </listitem> - - <listitem> - <para>Adam Baran <email>badam@mw.mil.pl</email></para> - </listitem> - - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adam McDougall <email>mcdouga9@egr.msu.edu</email></para> - </listitem> - - <listitem> - <para>Adam Strohl <email>troll@digitalspark.net</email></para> - </listitem> - - <listitem> - <para>Adoal Xu <email>adoal@iname.com</email></para> - </listitem> - - <listitem> - <para>Adrian Colley <email>aecolley@ois.ie</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Adrian Mariano <email>adrian@cam.cornell.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Steinmann <email>ast@marabu.ch</email></para> - </listitem> - - <listitem> - <para>Adrian T. Filipi-Martin - <email>atf3r@agate.cs.virginia.edu</email></para> - </listitem> - - <listitem> - <para>Ajit Thyagarajan <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akio Morita - <email>amorita@meadow.scphys.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akira SAWADA <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akira Watanabe - <email>akira@myaw.ei.meisei-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akito Fujita <email>fujita@zoo.ncl.omron.co.jp</email></para> - </listitem> - - <listitem> - <para>Alain Kalker - <email>A.C.P.M.Kalker@student.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Alan Bawden <email>alan@curry.epilogue.com</email></para> - </listitem> - - <listitem> - <para>Alec Wolman <email>wolman@cs.washington.edu</email></para> - </listitem> - - <listitem> - <para>Aled Morris <email>aledm@routers.co.uk</email></para> - </listitem> - - <listitem> - <para>Aleksandr A Babaylov <email>.@babolo.ru</email></para> - </listitem> - - <listitem> - <para>Alex G. Bulushev <email>bag@demos.su</email></para> - </listitem> - - <listitem> - <para>Alex D. Chen - <email>dhchen@Canvas.dorm7.nccu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Alex Le Heux <email>alexlh@funk.org</email></para> - </listitem> - - <listitem> - <para>Alex Kapranoff <email>kappa@zombie.antar.bryansk.ru</email></para> - </listitem> - - <listitem> - <para>Alex Perel <email>veers@disturbed.net</email></para> - </listitem> - - <listitem> - <para>Alex Varju <email>varju@webct.com</email></para> - </listitem> - - <listitem> - <para>Alex Zepeda <email>garbanzo@hooked.net</email></para> - </listitem> - - <listitem> - <para>Alexander B. Povolotsky <email>tarkhil@mgt.msk.ru</email></para> - </listitem> - - <listitem> - <para>Alexander Gelfenbain <email>mail@gelf.com</email></para> - </listitem> - - <listitem> - <para>Alexander Leidinger - <email>netchild@wurzelausix.CS.Uni-SB.DE</email></para> - </listitem> - - <listitem> - <para>Alexandre Snarskii <email>snar@paranoia.ru</email></para> - </listitem> - - <listitem> - <para>Alistair G. Crooks <email>agc@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Allan Bowhill <email>bowhill@bowhill.vservers.com</email></para> - </listitem> - - <listitem> - <para>Allan Saddi <email>asaddi@philosophysw.com</email></para> - </listitem> - - <listitem> - <para>Allen Campbell <email>allenc@verinet.com</email></para> - </listitem> - - <listitem> - <para>Amakawa Shuhei <email>amakawa@hoh.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Amancio Hasty <email>hasty@star-gate.com</email></para> - </listitem> - - <listitem> - <para>Amir Farah <email>amir@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Amy Baron <email>amee@beer.org</email></para> - </listitem> - - <listitem> - <para>Anatoly A. Orehovsky <email>tolik@mpeks.tomsk.su</email></para> - </listitem> - - <listitem> - <para>Anatoly Vorobey <email>mellon@pobox.com</email></para> - </listitem> - - <listitem> - <para>Anders Nordby <email>anders@fix.no</email></para> - </listitem> - - <listitem> - <para>Anders Thulin <email>Anders.X.Thulin@telia.se</email></para> - </listitem> - - <listitem> - <para>Andras Olah <email>olah@cs.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Andre Albsmeier - <email>Andre.Albsmeier@mchp.siemens.de</email></para> - </listitem> - - <listitem> - <para>Andre Oppermann <email>andre@pipeline.ch</email></para> - </listitem> - - <listitem> - <para>Andreas Haakh <email>ah@alman.robin.de</email></para> - </listitem> - - <listitem> - <para>Andreas Kohout <email>shanee@rabbit.augusta.de</email></para> - </listitem> - - <listitem> - <para>Andreas Lohr <email>andreas@marvin.RoBIN.de</email></para> - </listitem> - - <listitem> - <para>Andreas Schulz <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andreas Wetzel <email>mickey@deadline.snafu.de</email></para> - </listitem> - - <listitem> - <para>Andreas Wrede <email>andreas@planix.com</email></para> - </listitem> - - <listitem> - <para>Andres Vega Garcia <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andrew Atrens <email>atreand@statcan.ca</email></para> - </listitem> - - <listitem> - <para>Andrew Boothman <email>andrew@cream.org</email></para> - </listitem> - - <listitem> - <para>Andrew Gillham <email>gillham@andrews.edu</email></para> - </listitem> - - <listitem> - <para>Andrew Gordon <email>andrew.gordon@net-tel.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew J. Korty <email>ajk@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Andrew L. Moore <email>alm@mclink.com</email></para> - </listitem> - - <listitem> - <para>Andrew L. Neporada <email>andrew@chg.ru</email></para> - </listitem> - - <listitem> - <para>Andrew McRae <email>amcrae@cisco.com</email></para> - </listitem> - - <listitem> - <para>Andrew Stevenson <email>andrew@ugh.net.au</email></para> - </listitem> - - <listitem> - <para>Andrew Timonin <email>tim@pool1.convey.ru</email></para> - </listitem> - - <listitem> - <para>Andrew V. Stesin <email>stesin@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrew Webster <email>awebster@dataradio.com</email></para> - </listitem> - - <listitem> - <para>Andrey Novikov <email>andrey@novikov.com</email></para> - </listitem> - - <listitem> - <para>Andrey Tchoritch <email>andy@venus.sympad.net</email></para> - </listitem> - - <listitem> - <para>Andy Farkas <email>andyf@speednet.com.au</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email></para> - </listitem> - - <listitem> - <para>Andy Whitcroft <email>andy@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Angelo Turetta <email>ATuretta@stylo.it</email></para> - </listitem> - - <listitem> - <para>Anthony C. Chavez <email>magus@xmission.com</email></para> - </listitem> - - <listitem> - <para>Anthony Yee-Hang Chan <email>yeehang@netcom.com</email></para> - </listitem> - - <listitem> - <para>Anton Berezin <email>tobez@plab.ku.dk</email></para> - </listitem> - - <listitem> - <para>Anton N. Bruesov <email>antonz@library.ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Antti Kaipila <email>anttik@iki.fi</email></para> - </listitem> - - <listitem> - <para>arci <email>vega@sophia.inria.fr</email></para> - </listitem> - - <listitem> - <para>Are Bryne <email>are.bryne@communique.no</email></para> - </listitem> - - <listitem> - <para>Ari Suutari <email>ari@suutari.iki.fi</email></para> - </listitem> - - <listitem> - <para>Arindum Mukerji <email>rmukerji@execpc.com</email></para> - </listitem> - - <listitem> - <para>Arjan de Vet <email>devet@IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Arun Sharma <email>adsharma@sharmas.dhs.org</email></para> - </listitem> - - <listitem> - <para>Ask Bjoern Hansen <email>ask@valueclick.com</email></para> - </listitem> - - <listitem> - <para>Atsushi Furuta <email>furuta@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Atsushi Murai <email>amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Bierbauch <email>pivrnec@vszbr.cz</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para> - </listitem> - - <listitem> - <para>Ben Jackson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ben Walter <email>bwalter@itachi.swcp.com</email></para> - </listitem> - - <listitem> - <para>Benjamin Lewis <email>bhlewis@gte.net</email></para> - </listitem> - - <listitem> - <para>Berend de Boer <email>berend@pobox.com</email></para> - </listitem> - - <listitem> - <para>Bernd Rosauer <email>br@schiele-ct.de</email></para> - </listitem> - - <listitem> - <para>Bill Kish <email>kish@osf.org</email></para> - </listitem> - - <listitem> - <para>Bill Trost <email>trost@cloud.rain.com</email></para> - </listitem> - - <listitem> - <para>Blaz Zupan <email>blaz@amis.net</email></para> - </listitem> - - <listitem> - <para>Bob Van Valzah <email>Bob@whitebarn.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Bob Willcox <email>bob@luke.pmr.com</email></para> - </listitem> - - <listitem> - <para>Boris Staeblow <email>balu@dva.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Boyd Faulkner <email>faulkner@mpd.tandem.com</email></para> - </listitem> - - <listitem> - <para>Boyd R. Faulkner <email>faulkner@asgard.bga.com</email></para> - </listitem> - - <listitem> - <para>Brad Chapman <email>chapmanb@arches.uga.edu</email></para> - </listitem> - - <listitem> - <para>Brad Hendrickse <email>bradh@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Brad Karp <email>karp@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>Bradley Dunn <email>bradley@dunn.org</email></para> - </listitem> - - <listitem> - <para>Brandon Fosdick <email>bfoz@glue.umd.edu</email></para> - </listitem> - - <listitem> - <para>Brandon Gillespie <email>brandon@roguetrader.com</email></para> - </listitem> - - <listitem> - <para>&a.wlloyd</para> - </listitem> - - <listitem> - <para>Brent J. Nordquist <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Brett Taylor - <email>brett@peloton.runet.edu</email></para> - </listitem> - - <listitem> - <para>Brian Campbell <email>brianc@pobox.com</email></para> - </listitem> - - <listitem> - <para>Brian Clapper <email>bmc@willscreek.com</email></para> - </listitem> - - <listitem> - <para>Brian Cully <email>shmit@kublai.com</email></para> - </listitem> - - <listitem> - <para>Brian Handy - <email>handy@lambic.space.lockheed.com</email></para> - </listitem> - - <listitem> - <para>Brian Litzinger <email>brian@MediaCity.com</email></para> - </listitem> - - <listitem> - <para>Brian McGovern <email>bmcgover@cisco.com</email></para> - </listitem> - - <listitem> - <para>Brian Moore <email>ziff@houdini.eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Brian R. Haug <email>haug@conterra.com</email></para> - </listitem> - - <listitem> - <para>Brian Tao <email>taob@risc.org</email></para> - </listitem> - - <listitem> - <para>Brion Moss <email>brion@queeg.com</email></para> - </listitem> - - <listitem> - <para>Bruce Albrecht <email>bruce@zuhause.mn.org</email></para> - </listitem> - - <listitem> - <para>Bruce Gingery <email>bgingery@gtcs.com</email></para> - </listitem> - - <listitem> - <para>Bruce J. Keeler <email>loodvrij@gridpoint.com</email></para> - </listitem> - - <listitem> - <para>Bruce Murphy <email>packrat@iinet.net.au</email></para> - </listitem> - - <listitem> - <para>Bruce Walter <email>walter@fortean.com</email></para> - </listitem> - - <listitem> - <para>Carey Jones <email>mcj@acquiesce.org</email></para> - </listitem> - - <listitem> - <para>Carl Fongheiser <email>cmf@netins.net</email></para> - </listitem> - - <listitem> - <para>Carl Mascott <email>cmascott@world.std.com</email></para> - </listitem> - - <listitem> - <para>Casper <email>casper@acc.am</email></para> - </listitem> - - <listitem> - <para>Castor Fu <email>castor@geocast.com</email></para> - </listitem> - - <listitem> - <para>Chain Lee <email>chain@110.net</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Charles Henrich <email>henrich@msu.edu</email></para> - </listitem> - - <listitem> - <para>Charles Mott <email>cmott@scientech.com</email></para> - </listitem> - - <listitem> - <para>Charles Owens <email>owensc@enc.edu</email></para> - </listitem> - - <listitem> - <para>Chet Ramey <email>chet@odin.INS.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Chia-liang Kao <email>clkao@CirX.ORG</email></para> - </listitem> - - <listitem> - <para>Chiharu Shibata <email>chi@bd.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Chip Norkus <email>unknown</email></para> - </listitem> - - <listitem> - <para>Chris Csanady <email>cc@tarsier.ca.sandia.gov</email></para> - </listitem> - - <listitem> - <para>Chris Dabrowski <email>chris@vader.org</email></para> - </listitem> - - <listitem> - <para>Chris Dillon <email>cdillon@wolves.k12.mo.us</email></para> - </listitem> - - <listitem> - <para>Chris Shenton - <email>cshenton@angst.it.hq.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Chris Stenton <email>jacs@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>Chris Timmons <email>skynyrd@opus.cts.cwu.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christian Gusenbauer - <email>cg@fimp01.fim.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christian Haury <email>Christian.Haury@sagem.fr</email></para> - </listitem> - - <listitem> - <para>Christian Weisgerber - <email>naddy@mips.inka.de</email></para> - </listitem> - - <listitem> - <para>Christoph P. Kukulies <email>kuku@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christoph Weber-Fahr - <email>wefa@callcenter.systemhaus.net</email></para> - </listitem> - - <listitem> - <para>Christopher G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Christopher N. Harrell <email>cnh@ivmg.net</email></para> - </listitem> - - <listitem> - <para>Christopher T. Johnson - <email>cjohnson@neunacht.netgsi.com</email></para> - </listitem> - - <listitem> - <para>Chrisy Luke <email>chrisy@flix.net</email></para> - </listitem> - - <listitem> - <para>Chuck Hein <email>chein@cisco.com</email></para> - </listitem> - - <listitem> - <para>Cliff Rowley <email>dozprompt@onsea.com</email></para> - </listitem> - - <listitem> - <para>Clive Lin <email>clive@CiRX.ORG</email></para> - </listitem> - - <listitem> - <para>Colman Reilly <email>careilly@tcd.ie</email></para> - </listitem> - - <listitem> - <para>Conrad Sabatier <email>conrads@neosoft.com</email></para> - </listitem> - - <listitem> - <para>Coranth Gryphon <email>gryphon@healer.com</email></para> - </listitem> - - <listitem> - <para>Cornelis van der Laan - <email>nils@guru.ims.uni-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Cove Schneider <email>cove@brazil.nbn.com</email></para> - </listitem> - - <listitem> - <para>Craig Leres <email>leres@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Craig Loomis <email>unknown</email></para> - </listitem> - - <listitem> - <para>Craig Metz <email>cmetz@inner.net</email></para> - </listitem> - - <listitem> - <para>Craig Spannring <email>cts@internetcds.com</email></para> - </listitem> - - <listitem> - <para>Craig Struble <email>cstruble@vt.edu</email></para> - </listitem> - - <listitem> - <para>Cristian Ferretti <email>cfs@riemann.mat.puc.cl</email></para> - </listitem> - - <listitem> - <para>Curt Mayer <email>curt@toad.com</email></para> - </listitem> - - <listitem> - <para>Cy Schubert <email>cschuber@uumail.gov.bc.ca</email></para> - </listitem> - - <listitem> - <para>Cyrille Lefevre <email>clefevre@citeweb.net</email></para> - </listitem> - - <listitem> - <para>Cyrus Rahman <email>cr@jcmax.com</email></para> - </listitem> - - <listitem> - <para>Dai Ishijima <email>ishijima@tri.pref.osaka.jp</email></para> - </listitem> - - <listitem> - <para>Daisuke Watanabe <email>NU7D-WTNB@asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Damian Hamill <email>damian@cablenet.net</email></para> - </listitem> - - <listitem> - <para>Dan Cross <email>tenser@spitfire.ecsel.psu.edu</email></para> - </listitem> - - <listitem> - <para>Dan Lukes <email>dan@obluda.cz</email></para> - </listitem> - - <listitem> - <para>Dan Nelson <email>dnelson@emsphone.com</email></para> - </listitem> - - <listitem> - <para>Dan Papasian <email>bugg@bugg.strangled.net</email></para> - </listitem> - - <listitem> - <para>Dan Piponi <email>wmtop@tanelorn.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dan Walters <email>hannibal@cyberstation.net</email></para> - </listitem> - - <listitem> - <para>Daniel Hagan - <email>dhagan@cs.vt.edu</email></para> - </listitem> - - <listitem> - <para>Daniel M. Eischen - <email>deischen@iworks.InterWorks.org</email></para> - </listitem> - - <listitem> - <para>Daniel O'Connor <email>doconnor@gsoft.com.au</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Daniel Rock <email>rock@cs.uni-sb.de</email></para> - </listitem> - - <listitem> - <para>Danny Egen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Danny J. Zerkel <email>dzerkel@phofarm.com</email></para> - </listitem> - - <listitem> - <para>Darren Reed <email>avalon@coombs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Dave Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>Dave Andersen <email>angio@aros.net</email></para> - </listitem> - - <listitem> - <para>Dave Blizzard <email>dblizzar@sprynet.com</email></para> - </listitem> - - <listitem> - <para>Dave Bodenstab <email>imdave@synet.net</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Chapeskie <email>dchapes@ddm.on.ca</email></para> - </listitem> - - <listitem> - <para>Dave Cornejo <email>dave@dogwood.com</email></para> - </listitem> - - <listitem> - <para>Dave Edmondson <email>davided@sco.com</email></para> - </listitem> - - <listitem> - <para>Dave Glowacki <email>dglo@ssec.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Dave Marquardt <email>marquard@austin.ibm.com</email></para> - </listitem> - - <listitem> - <para>Dave Tweten <email>tweten@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>David A. Adkins <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>David A. Bader <email>dbader@eece.unm.edu</email></para> - </listitem> - - <listitem> - <para>David Borman <email>dab@bsdi.com</email></para> - </listitem> - - <listitem> - <para>David W. Chapman Jr. <email>dwcjr@inethouston.net</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@XFree86.org</email></para> - </listitem> - - <listitem> - <para>David Filo <email>unknown</email></para> - </listitem> - - <listitem> - <para>David Holland <email>dholland@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>David Holloway <email>daveh@gwythaint.tamis.com</email></para> - </listitem> - - <listitem> - <para>David Horwitt <email>dhorwitt@ucsd.edu</email></para> - </listitem> - - <listitem> - <para>David Hovemeyer <email>daveho@infocom.com</email></para> - </listitem> - - <listitem> - <para>David Jones <email>dej@qpoint.torfree.net</email></para> - </listitem> - - <listitem> - <para>David Kelly <email>dkelly@tomcat1.tbe.com</email></para> - </listitem> - - <listitem> - <para>David Kulp <email>dkulp@neomorphic.com</email></para> - </listitem> - - <listitem> - <para>David L. Nugent <email>davidn@blaze.net.au</email></para> - </listitem> - - <listitem> - <para>David Leonard <email>d@scry.dstc.edu.au</email></para> - </listitem> - - <listitem> - <para>David Muir Sharnoff <email>muir@idiom.com</email></para> - </listitem> - - <listitem> - <para>David S. Miller <email>davem@jenolan.rutgers.edu</email></para> - </listitem> - - <listitem> - <para>David Sugar <email>dyfet@gnu.org</email></para> - </listitem> - - <listitem> - <para>David Wolfskill <email>dhw@whistle.com</email></para> - </listitem> - - <listitem> - <para>Dean Gaudet <email>dgaudet@arctic.org</email></para> - </listitem> - - <listitem> - <para>Dean Huxley <email>dean@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Denis Fortin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Denis Shaposhnikov <email>dsh@vlink.ru</email></para> - </listitem> - - <listitem> - <para>Dennis Glatting - <email>dennis.glatting@software-munitions.com</email></para> - </listitem> - - <listitem> - <para>Denton Gentry <email>denny1@home.com</email></para> - </listitem> - - <listitem> - <para>der Mouse <email>mouse@Collatz.McRCIM.McGill.EDU</email></para> - </listitem> - - <listitem> - <para>Derek Inksetter <email>derek@saidev.com</email></para> - </listitem> - - <listitem> - <para>DI. Christian Gusenbauer - <email>cg@scotty.edvz.uni-linz.ac.at</email></para> - </listitem> - - <listitem> - <para>Dirk Keunecke <email>dk@panda.rhein-main.de</email></para> - </listitem> - - <listitem> - <para>Dirk Meyer <email>dirk.meyer@dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Dirk Nehrling <email>nerle@pdv.de</email></para> - </listitem> - - <listitem> - <para>Dishanker Rajakulendren <email>draj@oceanfree.net</email></para> - </listitem> - - <listitem> - <para>Dmitry Khrustalev <email>dima@xyzzy.machaon.ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Kohmanyuk <email>dk@farm.org</email></para> - </listitem> - - <listitem> - <para>Dom Mitchell <email>dom@myrddin.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Domas Mituzas <email>midom@dammit.lt</email></para> - </listitem> - - <listitem> - <para>Dominik Brettnacher <email>domi@saargate.de</email></para> - </listitem> - - <listitem> - <para>Dominik Rothert <email>dr@domix.de</email></para> - </listitem> - - <listitem> - <para>Don Croyle <email>croyle@gelemna.ft-wayne.in.us</email></para> - </listitem> - - <listitem> - <para>Donn Miller <email>dmmiller@cvzoom.net</email></para> - </listitem> - - <listitem> - <para>Dan Pelleg <email>dpelleg+unison@cs.cmu.edu</email></para> - </listitem> - - <listitem> - <para>&a.whiteside;</para> - </listitem> - - <listitem> - <para>Don Morrison <email>dmorrisn@u.washington.edu</email></para> - </listitem> - - <listitem> - <para>Don Yuniskis <email>dgy@rtd.com</email></para> - </listitem> - - <listitem> - <para>Donald Maddox <email>dmaddox@conterra.com</email></para> - </listitem> - - <listitem> - <para>Douglas Ambrisko <email>ambrisko@whistle.com</email></para> - </listitem> - - <listitem> - <para>Douglas Carmichael <email>dcarmich@mcs.com</email></para> - </listitem> - - <listitem> - <para>Douglas Crosher <email>dtc@scrooge.ee.swin.oz.au</email></para> - </listitem> - - <listitem> - <para>Drew Derbyshire <email>ahd@kew.com</email></para> - </listitem> - - <listitem> - <para>Duncan Barclay <email>dmlb@ragnet.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dustin Sallings <email>dustin@spy.net</email></para> - </listitem> - - <listitem> - <para>Eckart "Isegrim" Hofmann - <email>Isegrim@Wunder-Nett.org</email></para> - </listitem> - - <listitem> - <para>Ed Gold - <email>vegold01@starbase.spd.louisville.edu</email></para> - </listitem> - - <listitem> - <para>Ed Hudson <email>elh@p5.spnet.com</email></para> - </listitem> - - <listitem> - <para>Edward Chuang <email>edwardc@firebird.org.tw</email></para> - </listitem> - - <listitem> - <para>Edward Wang <email>edward@edcom.com</email></para> - </listitem> - - <listitem> - <para>Edwin Groothus <email>edwin@nwm.wan.philips.com</email></para> - </listitem> - - <listitem> - <para>Edwin Mons <email>e@ik.nu</email></para> - </listitem> - - <listitem> - <para>Ege Rekk <email>aagero@aage.priv.no</email></para> - </listitem> - - <listitem> - <para>Eiji-usagi-MATSUmoto <email>usagi@clave.gr.jp</email></para> - </listitem> - - <listitem> - <para>Eike Bernhardt <email>eike.bernhardt@gmx.de</email></para> - </listitem> - - <listitem> - <para>ELISA Font Project</para> - </listitem> - - <listitem> - <para>Elmar Bartel - <email>bartel@informatik.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Eoin Lawless <email>eoin@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Eric A. Griff <email>eagriff@global2000.net</email></para> - </listitem> - - <listitem> - <para>Eric Melville <email>eric@osd.bsdi.com</email></para> - </listitem> - - <listitem> - <para>Eric Blood <email>eblood@cs.unr.edu</email></para> - </listitem> - - <listitem> - <para>Eric D. Futch <email>efutch@nyct.net</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Schwertfeger <email>eric@cybernut.com</email></para> - </listitem> - - <listitem> - <para>Eric L. Hernes <email>erich@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>Eric P. Scott <email>eps@sirius.com</email></para> - </listitem> - - <listitem> - <para>Eric Sprinkle <email>eric@ennovatenetworks.com</email></para> - </listitem> - - <listitem> - <para>Erich Stefan Boleyn <email>erich@uruk.org</email></para> - </listitem> - - <listitem> - <para>Erich Zigler <email>erich@tacni.net</email></para> - </listitem> - - <listitem> - <para>Erik H. Bakke <email>erikhb@bgnett.no</email></para> - </listitem> - - <listitem> - <para>Erik E. Rantapaa <email>rantapaa@math.umn.edu</email></para> - </listitem> - - <listitem> - <para>Erik H. Moe <email>ehm@cris.com</email></para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email></para> - </listitem> - - <listitem> - <para>Espen Skoglund <email>esk@ira.uka.de</email></para> - </listitem> - - <listitem> - <para>Eugene M. Kim <email>astralblue@usa.net</email></para> - </listitem> - - <listitem> - <para>Eugene Radchenko <email>genie@qsar.chem.msu.su</email></para> - </listitem> - - <listitem> - <para>Eugeny Kuzakov <email>CoreDumped@coredumped.null.ru</email></para> - </listitem> - - <listitem> - <para>Evan Champion <email>evanc@synapse.net</email></para> - </listitem> - - <listitem> - <para>Faried Nawaz <email>fn@Hungry.COM</email></para> - </listitem> - - <listitem> - <para>Flemming Jacobsen <email>fj@tfs.com</email></para> - </listitem> - - <listitem> - <para>Fong-Ching Liaw <email>fong@juniper.net</email></para> - </listitem> - - <listitem> - <para>Francis M J Hsieh <email>mjshieh@life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Bartels <email>knarf@camelot.de</email></para> - </listitem> - - <listitem> - <para>Frank Chen Hsiung Chan - <email>frankch@waru.life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Durda IV <email>uhclem@nemesis.lonestar.org</email></para> - </listitem> - - <listitem> - <para>Frank MacLachlan <email>fpm@n2.net</email></para> - </listitem> - - <listitem> - <para>Frank Nobis <email>fn@Radio-do.de</email></para> - </listitem> - - <listitem> - <para>Frank ten Wolde <email>franky@pinewood.nl</email></para> - </listitem> - - <listitem> - <para>Frank van der Linden <email>frank@fwi.uva.nl</email></para> - </listitem> - - <listitem> - <para>Frank Volf <email>volf@oasis.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Fred Cawthorne <email>fcawth@jjarray.umn.edu</email></para> - </listitem> - - <listitem> - <para>Fred Gilham <email>gilham@csl.sri.com</email></para> - </listitem> - - <listitem> - <para>Fred Templin <email>templin@erg.sri.com</email></para> - </listitem> - - <listitem> - <para>Frederick Earl Gray <email>fgray@rice.edu</email></para> - </listitem> - - <listitem> - <para>FUJIMOTO Kensaku - <email>fujimoto@oscar.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>FUJISHIMA Satsuki <email>k5@respo.or.jp</email></para> - </listitem> - - <listitem> - <para>FURUSAWA Kazuhisa - <email>furusawa@com.cs.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>G. Adam Stanislav<email>adam@whizkidtech.net</email></para> - </listitem> - - <listitem> - <para>Gabor Kincses <email>gabor@acm.org</email></para> - </listitem> - - <listitem> - <para>Gabor Zahemszky <email>zgabor@CoDe.hu</email></para> - </listitem> - - <listitem> - <para>Gareth McCaughan <email>gjm11@dpmms.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Gary J. <email>garyj@rks32.pcs.dec.com</email></para> - </listitem> - - <listitem> - <para>Gary Kline <email>kline@thought.org</email></para> - </listitem> - - <listitem> - <para>Gaspar Chilingarov <email>nightmar@lemming.acc.am</email></para> - </listitem> - - <listitem> - <para>Gea-Suan Lin <email>gsl@tpts4.seed.net.tw</email></para> - </listitem> - - <listitem> - <para>Gene Raytsin <email>pal@paladin7.net</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Georg Wagner <email>georg.wagner@ubs.com</email></para> - </listitem> - - <listitem> - <para>George Reid <email>services@nevernet.net</email></para> - </listitem> - - <listitem> - <para>Gianlorenzo Masini <email>masini@uniroma3.it</email></para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@giovannelli.it</email></para> - </listitem> - - <listitem> - <para>Gil Kloepfer Jr. <email>gil@limbic.ssdl.com</email></para> - </listitem> - - <listitem> - <para>Gilad Rom <email>rom_glsa@ein-hashofet.co.il</email></para> - </listitem> - - <listitem> - <para>Giles Lean <email>giles@nemeton.com.au</email></para> - </listitem> - - <listitem> - <para>Ginga Kawaguti - <email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Giorgos Keramidas <email>keramida@ceid.upatras.gr</email></para> - </listitem> - - <listitem> - <para>Glen Foster <email>gfoster@gfoster.com</email></para> - </listitem> - - <listitem> - <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>Godmar Back <email>gback@facility.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Gord Matzigkeit <email>gord@enci.ucalgary.ca</email></para> - </listitem> - - <listitem> - <para>Gordon Greeff <email>gvg@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Graham Wheeler <email>gram@cdsec.com</email></para> - </listitem> - - <listitem> - <para>Greg A. Woods <email>woods@zeus.leitch.com</email></para> - </listitem> - - <listitem> - <para>Greg Ansley <email>gja@ansley.com</email></para> - </listitem> - - <listitem> - <para>Greg Robinson <email>greg@rosevale.com.au</email></para> - </listitem> - - <listitem> - <para>Greg Troxel <email>gdt@ir.bbn.com</email></para> - </listitem> - - <listitem> - <para>Greg Ungerer <email>gerg@stallion.oz.au</email></para> - </listitem> - - <listitem> - <para>Gregory Bond <email>gnb@itga.com.au</email></para> - </listitem> - - <listitem> - <para>Gregory D. Moncreaff - <email>moncrg@bt340707.res.ray.com</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@netapp.com</email></para> - </listitem> - - <listitem> - <para>Guy Helmer <email>ghelmer@cs.iastate.edu</email></para> - </listitem> - - <listitem> - <para>HAMADA Naoki <email>hamada@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>Hannu Savolainen <email>hannu@voxware.pp.fi</email></para> - </listitem> - - <listitem> - <para>Hans Huebner <email>hans@artcom.de</email></para> - </listitem> - - <listitem> - <para>Hans Petter Bieker <email>zerium@webindex.no</email></para> - </listitem> - - <listitem> - <para>Hans Zuidam <email>hans@brandinnovators.com</email></para> - </listitem> - - <listitem> - <para>Harlan Stenn <email>Harlan.Stenn@pfcs.com</email></para> - </listitem> - - <listitem> - <para>Harold Barker <email>hbarker@dsms.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Heikki Suonsivu <email>hsu@cs.hut.fi</email></para> - </listitem> - - <listitem> - <para>Heiko W. Rupp <email>unknown</email></para> - </listitem> - - <listitem> - <para>Helmut F. Wirth <email>hfwirth@ping.at</email></para> - </listitem> - - <listitem> - <para>Henrik Vestergaard Draboel - <email>hvd@terry.ping.dk</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Hideaki Ohmon <email>ohmon@tom.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidekazu Kuroki <email>hidekazu@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hideki Yamamoto <email>hyama@acm.org</email></para> - </listitem> - - <listitem> - <para>Hideyuki Suzuki - <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hirayama Issei <email>iss@mail.wbs.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroaki Sakai <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hiroharu Tamaru <email>tamaru@ap.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hironori Ikura <email>hikura@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Hiroshi Nishikawa <email>nis@pluto.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroya Tsubakimoto <email>unknown</email></para> - </listitem> - - <listitem> - <para>Holger Lamm <email>holger@eit.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Holm Tiffe <email>holm@geophysik.tu-freiberg.de</email></para> - </listitem> - - <listitem> - <para>HONDA Yasuhiro - <email>honda@kashio.info.mie-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Horance Chou - <email>horance@freedom.ie.cycu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Horihiro Kumagai <email>kuma@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>HOSOBUCHI Noriyuki <email>hoso@buchi.tama.or.jp</email></para> - </listitem> - - <listitem> - <para>HOTARU-YA <email>hotaru@tail.net</email></para> - </listitem> - - <listitem> - <para>Hr.Ladavac <email>lada@ws2301.gud.siemens.co.at</email></para> - </listitem> - - <listitem> - <para>Hubert Feyrer <email>hubertf@NetBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Hugh F. Mahon <email>hugh@nsmdserv.cnd.hp.com</email></para> - </listitem> - - <listitem> - <para>Hugh Mahon <email>h_mahon@fc.hp.com</email></para> - </listitem> - - <listitem> - <para>Hung-Chi Chu <email>hcchu@r350.ee.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ian Dowse <email>iedowse@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Ian Holland <email>ianh@tortuga.com.au</email></para> - </listitem> - - <listitem> - <para>Ian Struble <email>ian@broken.net</email></para> - </listitem> - - <listitem> - <para>Ian Vaudrey <email>i.vaudrey@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Igor Khasilev <email>igor@jabber.paco.odessa.ua</email></para> - </listitem> - - <listitem> - <para>Igor Roshchin <email>str@giganda.komkon.org</email></para> - </listitem> - - <listitem> - <para>Igor Sviridov <email>siac@ua.net</email></para> - </listitem> - - <listitem> - <para>Igor Vinokurov <email>igor@zynaps.ru</email></para> - </listitem> - - <listitem> - <para>Ikuo Nakagawa <email>ikuo@isl.intec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ilia Chipitsine <email>ilia@jane.cgu.chel.su</email></para> - </listitem> - - <listitem> - <para>Ilya V. Komarov <email>mur@lynx.ru</email></para> - </listitem> - - <listitem> - <para>IMAI Takeshi <email>take-i@ceres.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>IMAMURA Tomoaki - <email>tomoak-i@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>Itsuro Saito <email>saito@miv.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>IWASHITA Yoji <email>shuna@pop16.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>J. Bryant <email>jbryant@argus.flash.net</email></para> - </listitem> - - <listitem> - <para>J. David Lowe <email>lowe@saturn5.com</email></para> - </listitem> - - <listitem> - <para>J. Han <email>hjh@photino.com</email></para> - </listitem> - - <listitem> - <para>J. Hawk <email>jhawk@MIT.EDU</email></para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jack <email>jack@zeus.xtalwind.net</email></para> - </listitem> - - <listitem> - <para>Jacob Bohn Lorensen <email>jacob@jblhome.ping.mk</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>Jake Hamby <email>jehamby@lightside.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James D. Stewart <email>jds@c4systm.com</email></para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James Raynard - <email>fhackers@jraynard.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>James T. Liu <email>jtliu@phlebas.rockefeller.edu</email></para> - </listitem> - - <listitem> - <para>Jamie Heckford <email>jamie@jamiesdomain.co.uk</email></para> - </listitem> - - <listitem> - <para>Jan Conard - <email>charly@fachschaften.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Jan Koum <email>jkb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Janick Taillandier - <email>Janick.Taillandier@ratp.fr</email></para> - </listitem> - - <listitem> - <para>Janusz Kokot <email>janek@gaja.ipan.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Jarle Greipsland <email>jarle@idt.unit.no</email></para> - </listitem> - - <listitem> - <para>Jason Garman <email>init@risen.org</email></para> - </listitem> - - <listitem> - <para>Jason Thorpe <email>thorpej@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Wright <email>jason@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Young - <email>doogie@forbidden-donut.anet-stl.com</email></para> - </listitem> - - <listitem> - <para>Javier Martin Rueda <email>jmrueda@diatel.upm.es</email></para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jay Krell <email>jay.krell@cornell.edu</email></para> - </listitem> - - <listitem> - <para>Jaye Mathisen <email>mrcpu@cdsnet.net</email></para> - </listitem> - - <listitem> - <para>Jeff Bartig <email>jeffb@doit.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Jeff Brown <email>jabrown@caida.org</email></para> - </listitem> - - <listitem> - <para>Jeff Forys <email>jeff@forys.cranbury.nj.us</email></para> - </listitem> - - <listitem> - <para>Jeff Kletsky <email>Jeff@Wagsky.com</email></para> - </listitem> - - <listitem> - <para>Jeff Palmer <email>jeff@isni.net</email></para> - </listitem> - - <listitem> - <para>Jeffrey Evans <email>evans@scnc.k12.mi.us</email></para> - </listitem> - - <listitem> - <para>Jeffrey Wheat <email>jeff@cetlink.net</email></para> - </listitem> - - <listitem> - <para>Jens Schweikhardt <email>schweikh@noc.dfn.d</email></para> - </listitem> - - <listitem> - <para>Jeremy Allison <email>jallison@whistle.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chadwick <email>yoshi@parodius.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chatfield <email>jdc@xinside.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Karlson <email>karlj000@unbc.ca</email></para> - </listitem> - - <listitem> - <para>Jeremy Prior <email>unknown</email></para> - </listitem> - - <listitem> - <para>Jeremy Shaffner <email>jeremy@external.org</email></para> - </listitem> - - <listitem> - <para>Jesse McConnell <email>jesse@cylant.com</email></para> - </listitem> - - <listitem> - <para>Jesse Rosenstock <email>jmr@ugcs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Jian-Da Li <email>jdli@csie.nctu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Jim Babb <email>babb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Jim Binkley <email>jrb@cs.pdx.edu</email></para> - </listitem> - - <listitem> - <para>Jim Bloom <email>bloom@acm.org</email></para> - </listitem> - - <listitem> - <para>Jim Carroll <email>jim@carroll.com</email></para> - </listitem> - - <listitem> - <para>Jim Flowers <email>jflowers@ezo.net</email></para> - </listitem> - - <listitem> - <para>Jim Leppek <email>jleppek@harris.com</email></para> - </listitem> - - <listitem> - <para>Jim Lowe <email>james@cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>Jim Mattson <email>jmattson@sonic.net</email></para> - </listitem> - - <listitem> - <para>Jim Mercer <email>jim@komodo.reptiles.org</email></para> - </listitem> - - <listitem> - <para>Jim Sloan <email>odinn@atlantabiker.net</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jimbo Bahooli - <email>griffin@blackhole.iceworld.org</email></para> - </listitem> - - <listitem> - <para>Jimmy Olgeni - <email>olgeni@uli.it</email></para> - </listitem> - - <listitem> - <para>Jin Guojun <email>jin@george.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Joachim Kuebart <email>kuebart@mathematik.uni-ulm.de</email></para> - </listitem> - - <listitem> - <para>Joao Carlos Mendes Luis <email>jonny@jonny.eng.br</email></para> - </listitem> - - <listitem> - <para>Jochen Pohl <email>jpo.drs@sni.de</email></para> - </listitem> - - <listitem> - <para>Joe "Marcus" Clarke <email>marcus@miami.edu</email></para> - </listitem> - - <listitem> - <para>Joe Abley <email>jabley@clear.co.nz</email></para> - </listitem> - - <listitem> - <para>Joe Jih-Shian Lu <email>jslu@dns.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Joe Orthoefer <email>j_orthoefer@tia.net</email></para> - </listitem> - - <listitem> - <para>Joe Traister <email>traister@mojozone.org</email></para> - </listitem> - - <listitem> - <para>Joel Faedi <email>Joel.Faedi@esial.u-nancy.fr</email></para> - </listitem> - - <listitem> - <para>Joel Ray Holveck <email>joelh@gnu.org</email></para> - </listitem> - - <listitem> - <para>Joel Sutton <email>jsutton@bbcon.com.au</email></para> - </listitem> - - <listitem> - <para>Joseph Scott <email>joseph.scott@owp.csus.edu</email></para> - </listitem> - - <listitem> - <para>Johan Granlund <email>johan@granlund.nu</email></para> - </listitem> - - <listitem> - <para>Johan Karlsson <email>k@numeri.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johan Larsson <email>johan@moon.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johann Tonsing <email>jtonsing@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Johannes Helander <email>unknown</email></para> - </listitem> - - <listitem> - <para>Johannes Stille <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Beckett <email>jbeckett@southern.edu</email></para> - </listitem> - - <listitem> - <para>John Beukema <email>jbeukema@hk.super.net</email></para> - </listitem> - - <listitem> - <para>John Brezak <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Capo <email>jc@irbs.com</email></para> - </listitem> - - <listitem> - <para>John F. Woods <email>jfw@jfwhome.funhouse.com</email></para> - </listitem> - - <listitem> - <para>John Goerzen - <email>jgoerzen@alexanderwohl.complete.org</email></para> - </listitem> - - <listitem> - <para>John Hay <email>jhay@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>John Heidemann <email>johnh@isi.edu</email></para> - </listitem> - - <listitem> - <para>John Hood <email>cgull@owl.org</email></para> - </listitem> - - <listitem> - <para>John Kohl <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Lind <email>john@starfire.mn.org</email></para> - </listitem> - - <listitem> - <para>John Mackin <email>john@physiol.su.oz.au</email></para> - </listitem> - - <listitem> - <para>John P <email>johnp@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>John Perry <email>perry@vishnu.alias.net</email></para> - </listitem> - - <listitem> - <para>John Preisler <email>john@vapornet.com</email></para> - </listitem> - - <listitem> - <para>John Rochester <email>jr@cs.mun.ca</email></para> - </listitem> - - <listitem> - <para>John Sadler <email>john_sadler@alum.mit.edu</email></para> - </listitem> - - <listitem> - <para>John Saunders <email>john@pacer.nlc.net.au</email></para> - </listitem> - - <listitem> - <para>John Wehle <email>john@feith.com</email></para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jon Morgan <email>morgan@terminus.trailblazer.com</email></para> - </listitem> - - <listitem> - <para>Jonathan H N Chin <email>jc254@newton.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Jonathan Hanna - <email>jh@pc-21490.bc.rogers.wave.ca</email></para> - </listitem> - - <listitem> - <para>Jorge Goncalves <email>j@bug.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jorge M. Goncalves <email>ee96199@tom.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jos Backus <email>jbackus@plex.nl</email></para> - </listitem> - - <listitem> - <para>Jose M. Alcaide <email>jose@we.lc.ehu.es</email></para> - </listitem> - - <listitem> - <para>Jose Marques <email>jose@nobody.org</email></para> - </listitem> - - <listitem> - <para>Josef Grosch - <email>jgrosch@superior.mooseriver.com</email></para> - </listitem> - - <listitem> - <para>Joseph Stein <email>joes@wstein.com</email></para> - </listitem> - - <listitem> - <para>Josh Gilliam <email>josh@quick.net</email></para> - </listitem> - - <listitem> - <para>Josh Tiefenbach <email>josh@ican.net</email></para> - </listitem> - - <listitem> - <para>Juergen Lock <email>nox@jelal.hb.north.de</email></para> - </listitem> - - <listitem> - <para>Juha Inkari <email>inkari@cc.hut.fi</email></para> - </listitem> - - <listitem> - <para>Jukka A. Ukkonen <email>jau@iki.fi</email></para> - </listitem> - - <listitem> - <para>Julian Assange <email>proff@suburbia.net</email></para> - </listitem> - - <listitem> - <para>Julian Coleman <email>j.d.coleman@ncl.ac.uk</email></para> - </listitem> - - <listitem> - <para>&a.jhs</para> - </listitem> - - <listitem> - <para>Julian Jenkins <email>kaveman@magna.com.au</email></para> - </listitem> - - <listitem> - <para>Junichi Satoh <email>junichi@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junji SAKAI <email>sakai@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junya WATANABE <email>junya-w@remus.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Justas <email>justas@mbank.lv</email></para> - </listitem> - - <listitem> - <para>Justin Stanford <email>jus@security.za.net</email></para> - </listitem> - - <listitem> - <para>K.Higashino <email>a00303@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kai Vorma <email>vode@snakemail.hut.fi</email></para> - </listitem> - - <listitem> - <para>Kaleb S. Keithley <email>kaleb@ics.com</email></para> - </listitem> - - <listitem> - <para>Kaneda Hiloshi <email>vanitas@ma3.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kapil Chowksey <email>kchowksey@hss.hns.com</email></para> - </listitem> - - <listitem> - <para>Karl Denninger <email>karl@mcs.com</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>KATO Tsuguru <email>tkato@prontomail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kawanobe Koh <email>kawanobe@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Kees Jan Koster <email>kjk1@ukc.ac.uk</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@bostic.com</email></para> - </listitem> - - <listitem> - <para>Keith E. Walker <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Moore <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Sklower <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Hornstein <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Key <email>key@cs.utk.edu</email></para> - </listitem> - - <listitem> - <para>Ken Mayer <email>kmayer@freegate.com</email></para> - </listitem> - - <listitem> - <para>Kenji Saito <email>marukun@mx2.nisiq.net</email></para> - </listitem> - - <listitem> - <para>Kenji Tomita <email>tommyk@da2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Kenneth Furge <email>kenneth.furge@us.endress.com</email></para> - </listitem> - - <listitem> - <para>Kenneth Monville <email>desmo@bandwidth.org</email></para> - </listitem> - - <listitem> - <para>Kenneth R. Westerback <email>krw@tcn.net</email></para> - </listitem> - - <listitem> - <para>Kenneth Stailey <email>kstailey@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kent Vander Velden <email>graphix@iastate.edu</email></para> - </listitem> - - <listitem> - <para>Kentaro Inagaki <email>JBD01226@niftyserve.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kevin Bracey <email>kbracey@art.acorn.co.uk</email></para> - </listitem> - - <listitem> - <para>Kevin Day <email>toasty@dragondata.com</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml@nas.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Kevin Meltzer <email>perlguy@perlguy.com</email></para> - </listitem> - - <listitem> - <para>Kevin Street <email>street@iname.com</email></para> - </listitem> - - <listitem> - <para>Kevin Van Maren <email>vanmaren@fast.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Kim Scarborough <email>sluggo@unknown.nu</email></para> - </listitem> - - <listitem> - <para>Kiril Mitev <email>kiril@ideaglobal.com</email></para> - </listitem> - - <listitem> - <para>Kiroh HARADA <email>kiroh@kh.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Klaus Herrmann <email>klaus.herrmann@gmx.net</email></para> - </listitem> - - <listitem> - <para>Klaus Klein <email>kleink@layla.inka.de</email></para> - </listitem> - - <listitem> - <para>Klaus-J. Wolf <email>Yanestra@t-online.de</email></para> - </listitem> - - <listitem> - <para>Koichi Sato <email>copan@ppp.fastnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Konstantin Chuguev <email>Konstantin.Chuguev@dante.org.uk</email></para> - </listitem> - - <listitem> - <para>Kostya Lukin <email>lukin@okbmei.msk.su</email></para> - </listitem> - - <listitem> - <para>Kouichi Hirabayashi <email>kh@mogami-wire.co.jp</email></para> - </listitem> - - <listitem> - <para>Kris Dow <email>kris@vilnya.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>KUNISHIMA Takeo <email>kunishi@c.oka-pu.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kurt D. Zeilenga <email>Kurt@Boolean.NET</email></para> - </listitem> - - <listitem> - <para>Kurt Olsen <email>kurto@tiny.mcs.usu.edu</email></para> - </listitem> - - <listitem> - <para>L. Jonas Olsson - <email>ljo@ljo-slip.DIALIN.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email></para> - </listitem> - - <listitem> - <para>Lars Köller - <email>Lars.Koeller@Uni-Bielefeld.DE</email></para> - </listitem> - - <listitem> - <para>Laurence Lopez <email>lopez@mv.mv.com</email></para> - </listitem> - - <listitem> - <para>Lee Cremeans <email>lcremean@tidalwave.net</email></para> - </listitem> - - <listitem> - <para>Leo Kim <email>leo@florida.sarang.net</email></para> - </listitem> - - <listitem> - <para>Liang Tai-hwa - <email>avatar@www.mmlab.cse.yzu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Lon Willett <email>lon%softt.uucp@math.utah.edu</email></para> - </listitem> - - <listitem> - <para>Louis A. Mamakos <email>louie@TransSys.COM</email></para> - </listitem> - - <listitem> - <para>Louis Mamakos <email>loiue@TransSys.com</email></para> - </listitem> - - <listitem> - <para>Lowell Gilbert <email>lowell@world.std.com</email></para> - </listitem> - - <listitem> - <para>Lucas James <email>Lucas.James@ldjpc.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Lyndon Nerenberg <email>lyndon@orthanc.ab.ca</email></para> - </listitem> - - <listitem> - <para>M. L. Dodson <email>bdodson@scms.utmb.EDU</email></para> - </listitem> - - <listitem> - <para>M.C. Wong <email>unknown</email></para> - </listitem> - - <listitem> - <para>Magnus Enbom <email>dot@tinto.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mahesh Neelakanta <email>mahesh@gcomm.com</email></para> - </listitem> - - <listitem> - <para>Makoto MATSUSHITA <email>matusita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Makoto WATANABE - <email>watanabe@zlab.phys.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Makoto YAMAKURA <email>makoto@pinpott.spnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>Malte Lance <email>malte.lance@gmx.net</email></para> - </listitem> - - <listitem> - <para>MANTANI Nobutaka <email>nobutaka@nobutaka.com</email></para> - </listitem> - - <listitem> - <para>Manu Iyengar - <email>iyengar@grunthos.pscwa.psca.com</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Marc Ramirez <email>mrami@mramirez.sy.yale.edu</email></para> - </listitem> - - <listitem> - <para>Marc Slemko <email>marcs@znep.com</email></para> - </listitem> - - <listitem> - <para>Marc van Kempen <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>Marc van Woerkom <email>van.woerkom@netcologne.de</email></para> - </listitem> - - <listitem> - <para>Marcin Cieslak <email>saper@system.pl</email></para> - </listitem> - - <listitem> - <para>Mark Andrews <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Cammidge <email>mark@gmtunx.ee.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Mark Diekhans <email>markd@grizzly.com</email></para> - </listitem> - - <listitem> - <para>Mark Huizer <email>xaa@stack.nl</email></para> - </listitem> - - <listitem> - <para>Mark J. Taylor <email>mtaylor@cybernet.com</email></para> - </listitem> - - <listitem> - <para>Mark Knight <email>markk@knigma.org</email></para> - </listitem> - - <listitem> - <para>Mark Krentel <email>krentel@rice.edu</email></para> - </listitem> - - <listitem> - <para>Mark Mayo <email>markm@vmunix.com</email></para> - </listitem> - - <listitem> - <para>Mark Thompson <email>thompson@tgsoft.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email></para> - </listitem> - - <listitem> - <para>Mark Treacy <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Valentine <email>mark@linus.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Markus Holmberg <email>saska@acc.umu.se</email></para> - </listitem> - - <listitem> - <para>Martin Birgmeier</para> - </listitem> - - <listitem> - <para>Martin Blapp <email>blapp@attic.ch</email></para> - </listitem> - - <listitem> - <para>Martin Hinner <email>mhi@linux.gyarab.cz</email></para> - </listitem> - - <listitem> - <para>Martin Ibert <email>mib@ppe.bb-data.de</email></para> - </listitem> - - <listitem> - <para>Martin Kammerhofer <email>dada@sbox.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Martin Minkus <email>diskiller@cnbinc.com</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Martti Kuparinen - <email>martti.kuparinen@ericsson.com</email></para> - </listitem> - - <listitem> - <para>Masachika ISHIZUKA - <email>ishizuka@isis.min.ntt.jp</email></para> - </listitem> - - <listitem> - <para>Masafumi NAKANE <email>max@wide.ad.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro Sekiguchi - <email>seki@sysrap.cs.fujitsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro TAKEMURA - <email>mastake@msel.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanobu Saitoh <email>msaitoh@spa.is.uec.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kanaoka <email>kana@saijo.mke.mei.co.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kiriake <email>seiken@ARGV.AC</email></para> - </listitem> - - <listitem> - <para>Masatoshi TAMURA - <email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mats Lofkvist <email>mal@algonet.se</email></para> - </listitem> - - <listitem> - <para>Matt Bartley <email>mbartley@lear35.cytex.com</email></para> - </listitem> - - <listitem> - <para>Matt Heckaman <email>matt@LUCIDA.QC.CA</email></para> - </listitem> - - <listitem> - <para>Matt Thomas <email>matt@3am-software.com</email></para> - </listitem> - - <listitem> - <para>Matt White <email>mwhite+@CMU.EDU</email></para> - </listitem> - - <listitem> - <para>Matthew C. Mead <email>mmead@Glock.COM</email></para> - </listitem> - - <listitem> - <para>Matthew Cashdollar <email>mattc@rfcnet.com</email></para> - </listitem> - - <listitem> - <para>Matthew Emmerton <email>root@gabby.gsicomp.on.ca</email></para> - </listitem> - - <listitem> - <para>Matthew Flatt <email>mflatt@cs.rice.edu</email></para> - </listitem> - - <listitem> - <para>Matthew Fuller <email>fullermd@futuresouth.com</email></para> - </listitem> - - <listitem> - <para>Matthew Stein <email>matt@bdd.net</email></para> - </listitem> - - <listitem> - <para>Matthew West <email>mwest@uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Matthias Pfaller <email>leo@dachau.marco.de</email></para> - </listitem> - - <listitem> - <para>Matthias Scheler <email>tron@netbsd.org</email></para> - </listitem> - - <listitem> - <para>Mattias Gronlund - <email>Mattias.Gronlund@sa.erisoft.se</email></para> - </listitem> - - <listitem> - <para>Mattias Pantzare <email>pantzer@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Maurice Castro - <email>maurice@planet.serc.rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Max Euston <email>meuston@jmrodgers.com</email></para> - </listitem> - - <listitem> - <para>Max Khon <email>fjoe@husky.iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxim Bolotin <email>max@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxime Henrion <email>mhenrion@cybercable.fr</email></para> - </listitem> - - <listitem> - <para>Micha Class - <email>michael_class@hpbbse.bbn.hp.com</email></para> - </listitem> - - <listitem> - <para>Michael Lucas <email>mwlucas@blackhelicopters.org</email></para> - </listitem> - - <listitem> - <para>Michael Butler <email>imb@scgt.oz.au</email></para> - </listitem> - - <listitem> - <para>Michael Butschky <email>butsch@computi.erols.com</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Elbel <email>me@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Michael Hancock <email>michaelh@cet.co.jp</email></para> - </listitem> - - <listitem> - <para>Michael Hohmuth <email>hohmuth@inf.tu-dresden.de</email></para> - </listitem> - - <listitem> - <para>Michael Perlman <email>canuck@caam.rice.edu</email></para> - </listitem> - - <listitem> - <para>Michael Petry <email>petry@netwolf.NetMasters.com</email></para> - </listitem> - - <listitem> - <para>Michael Reifenberger <email>root@totum.plaut.de</email></para> - </listitem> - - <listitem> - <para>Michael Sardo <email>jaeger16@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Michael Searle <email>searle@longacre.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Michael Urban <email>murban@tznet.com</email></para> - </listitem> - - <listitem> - <para>Michael Vasilenko <email>acid@stu.cn.ua</email></para> - </listitem> - - <listitem> - <para>Michal Listos <email>mcl@Amnesiac.123.org</email></para> - </listitem> - - <listitem> - <para>Michio Karl Jinbo - <email>karl@marcer.nagaokaut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Miguel Angel Sagreras - <email>msagre@cactus.fi.uba.ar</email></para> - </listitem> - - <listitem> - <para>Mihoko Tanaka <email>m_tonaka@pa.yokogawa.co.jp</email></para> - </listitem> - - <listitem> - <para>Mika Nystrom <email>mika@cs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Mikael Hybsch <email>micke@dynas.se</email></para> - </listitem> - - <listitem> - <para>Mikael Karpberg - <email>karpen@ocean.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mike Barcroft <email>mike@q9media.com</email></para> - </listitem> - - <listitem> - <para>Mike Del <email>repenting@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Mike Durian <email>durian@plutotech.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Mike E. Matsnev <email>mike@azog.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Mike Evans <email>mevans@candle.com</email></para> - </listitem> - - <listitem> - <para>Mike Grupenhoff <email>kashmir@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Mike Harding <email>mvh@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Mike Hibler <email>mike@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Mike Karels <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mike McGaughey <email>mmcg@cs.monash.edu.au</email></para> - </listitem> - - <listitem> - <para>Mike Meyer <email>mwm@mired.org</email></para> - </listitem> - - <listitem> - <para>Mike Mitchell <email>mitchell@ref.tfs.com</email></para> - </listitem> - - <listitem> - <para>Mike Murphy <email>mrm@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Mike Peck <email>mike@binghamton.edu</email></para> - </listitem> - - <listitem> - <para>Mike Sherwood <email>mike@fate.com</email></para> - </listitem> - - <listitem> - <para>Mike Spengler <email>mks@msc.edu</email></para> - </listitem> - - <listitem> - <para>Mikhail A. Sokolov <email>mishania@demos.su</email></para> - </listitem> - - <listitem> - <para>Mikhail Teterin <email>mi@aldan.algebra.com</email></para> - </listitem> - - <listitem> - <para>Ming-I Hseh <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>MITA Yoshio <email>mita@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Mitsuru Yoshida <email>mitsuru@riken.go.jp</email></para> - </listitem> - - <listitem> - <para>Monte Mitzelfelt <email>monte@gonefishing.org</email></para> - </listitem> - - <listitem> - <para>Morgan Davis <email>root@io.cts.com</email></para> - </listitem> - - <listitem> - <para>MOROHOSHI Akihiko <email>moro@race.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mostyn Lewis <email>mostyn@mrl.com</email></para> - </listitem> - - <listitem> - <para>Motomichi Matsuzaki <email>mzaki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Motoyuki Kasahara <email>m-kasahr@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>N.G.Smith <email>ngs@sesame.hensa.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nadav Eiron <email>nadav@barcode.co.il</email></para> - </listitem> - - <listitem> - <para>NAGAO Tadaaki <email>nagao@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAJI Hiroyuki - <email>nakaji@tutrp.tut.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Kazushi <email>nkazushi@highway.or.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Motonori - <email>motonori@econ.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Nanbor Wang <email>nw1@cs.wustl.edu</email></para> - </listitem> - - <listitem> - <para>Naofumi Honda - <email>honda@Kururu.math.sci.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Narvi <email>narvi@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Nathan Ahlstrom <email>nrahlstr@winternet.com</email></para> - </listitem> - - <listitem> - <para>Nathan Dorfman <email>nathan@rtfm.net</email></para> - </listitem> - - <listitem> - <para>Neal Fachan <email>kneel@ishiboo.com</email></para> - </listitem> - - <listitem> - <para>Niall Smart <email>rotel@indigo.ie</email></para> - </listitem> - - <listitem> - <para>Nicholas Esborn <email>nick@netdot.net</email></para> - </listitem> - - <listitem> - <para>Nick Barnes <email>Nick.Barnes@pobox.com</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Nick Hilliard <email>nick@foobar.org</email></para> - </listitem> - - <listitem> - <para>Nick Johnson <email>freebsd@spatula.net</email></para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>Nick Williams <email>njw@cs.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nickolay N. Dudorov <email>nnd@itfs.nsk.su</email></para> - </listitem> - - <listitem> - <para>NIIMI Satoshi <email>sa2c@and.or.jp</email></para> - </listitem> - - <listitem> - <para>Niklas Hallqvist <email>niklas@filippa.appli.se</email></para> - </listitem> - - <listitem> - <para>Nisha Talagala <email>nisha@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>adrian@virginia.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>alex@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>anto@netscape.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>bobson@egg.ics.nitch.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>bovynf@awe.be</email></para> - </listitem> - - <listitem> - <para>No Name <email>burg@is.ge.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>chris@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>No Name <email>colsen@usa.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>coredump@nervosa.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>dannyman@arh0300.urh.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>davids@SECNET.COM</email></para> - </listitem> - - <listitem> - <para>No Name <email>derek@free.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>devet@adv.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>djv@bedford.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>dvv@sprint.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>enami@ba2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@eru.tubank.msk.su</email></para> - </listitem> - - <listitem> - <para>No Name <email>flash@hway.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>fn@pain.csrv.uidaho.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>frf@xocolatl.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gclarkii@netport.neosoft.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gordon@sheaky.lonestar.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>graaf@iae.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>greg@greg.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>grossman@cygnus.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>gusw@fub46.zedat.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>No Name <email>hfir@math.rochester.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>hnokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iaint@css.tuu.utas.edu.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>invis@visi.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>ishisone@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>iverson@lionheart.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>jpt@magic.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>No Name <email>k-sugyou@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kenji@reseau.toyonaka.osaka.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>kfurge@worldnet.att.net</email></para> - </listitem> - - <listitem> - <para>No Name <email>lh@aus.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>lhecking@nmrc.ucc.ie</email></para> - </listitem> - - <listitem> - <para>No Name <email>mrgreen@mame.mu.oz.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>nakagawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>owaki@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>pechter@shell.monmouth.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pete@pelican.pelican.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>pritc003@maroon.tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>risner@stdio.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>roman@rpd.univ.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@ns2.redline.ru</email></para> - </listitem> - - <listitem> - <para>No Name <email>root@uglabgw.ug.cs.sunysb.edu</email></para> - </listitem> - - <listitem> - <para>No Name <email>stephen.ma@jtec.com.au</email></para> - </listitem> - - <listitem> - <para>No Name <email>sumii@is.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>takas-su@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>tamone@eig.unige.ch</email></para> - </listitem> - - <listitem> - <para>No Name <email>tjevans@raleigh.ibm.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>tony-o@iij.ad.jp amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>torii@tcd.hitachi.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uenami@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>uhlar@netlab.sk</email></para> - </listitem> - - <listitem> - <para>No Name <email>vode@hut.fi</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlloyd@mpd.ca</email></para> - </listitem> - - <listitem> - <para>No Name <email>wlr@furball.wellsfargo.com</email></para> - </listitem> - - <listitem> - <para>No Name <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>No Name <email>yamagata@nwgpc.kek.jp</email></para> - </listitem> - - <listitem> - <para>No Name <email>ziggy@ryan.org</email></para> - </listitem> - - <listitem> - <para>No Name <email>ZW6T-KND@j.asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Nobuhiro Yasutomi <email>nobu@psrc.isac.co.jp</email></para> - </listitem> - - <listitem> - <para>Nobuyuki Koganemaru - <email>kogane@koganemaru.co.jp</email></para> - </listitem> - - <listitem> - <para>NOKUBI Hirotaka <email>h-nokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>Norio Suzuki <email>nosuzuki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Noritaka Ishizumi <email>graphite@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Noriyuki Soda <email>soda@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Oddbjorn Steffenson <email>oddbjorn@tricknology.org</email</para> - </listitem> - - <listitem> - <para>Oh Junseon <email>hollywar@mail.holywar.net</email></para> - </listitem> - - <listitem> - <para>Olaf Wagner <email>wagner@luthien.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Oleg Semyonov <email>os@altavista.net</email></para> - </listitem> - - <listitem> - <para>Oleg Sharoiko <email>os@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Oleg V. Volkov <email>rover@lglobus.ru</email></para> - </listitem> - - <listitem> - <para>Oliver Breuninger <email>ob@seicom.NET</email></para> - </listitem> - - <listitem> - <para>Oliver Friedrichs <email>oliver@secnet.com</email></para> - </listitem> - - <listitem> - <para>Oliver Fromme - <email>oliver.fromme@heim3.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Oliver Helmling - <email>oliver.helmling@stud.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Oliver Laumann - <email>net@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Oliver Oberdorf <email>oly@world.std.com</email></para> - </listitem> - - <listitem> - <para>Olof Johansson <email>offe@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Osokin Sergey aka oZZ <email>ozz@FreeBSD.org.ru</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paco Rosich <email>rosich@modico.eleinf.uv.es</email></para> - </listitem> - - <listitem> - <para>Palle Girgensohn <email>girgen@partitur.se</email></para> - </listitem> - - <listitem> - <para>Parag Patel <email>parag@cgt.com</email></para> - </listitem> - - <listitem> - <para>Pascal Pederiva <email>pascal@zuo.dec.com</email></para> - </listitem> - - <listitem> - <para>Pasvorn Boonmark <email>boonmark@juniper.net</email></para> - </listitem> - - <listitem> - <para>Patrick Bihan-Faou <email>patrick@mindstep.com</email></para> - </listitem> - - <listitem> - <para>Patrick Hausen <email>unknown</email></para> - </listitem> - - <listitem> - <para>Patrick Seal <email>patseal@hyperhost.net</email></para> - </listitem> - - <listitem> - <para>Paul Antonov <email>apg@demos.su</email></para> - </listitem> - - <listitem> - <para>Paul F. Werkowski <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Fox <email>pgf@foxharp.boston.ma.us</email></para> - </listitem> - - <listitem> - <para>Paul Koch <email>koch@thehub.com.au</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Paul M. Lambert <email>plambert@plambert.net</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Paul S. LaFollette, Jr. <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Sandys <email>myj@nyct.net</email></para> - </listitem> - - <listitem> - <para>Paul T. Root <email>proot@horton.iaces.com</email></para> - </listitem> - - <listitem> - <para>Paul Vixie <email>paul@vix.com</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>paulo@isr.uc.pt</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes <email>pm@dee.uc.pt</email></para> - </listitem> - - <listitem> - <para>Pedro A M Vazquez <email>vazquez@IQM.Unicamp.BR</email></para> - </listitem> - - <listitem> - <para>Pedro Giffuni <email>giffunip@asme.org</email></para> - </listitem> - - <listitem> - <para>Per Wigren <email>wigren@home.se</email></para> - </listitem> - - <listitem> - <para>Pete Bentley <email>pete@demon.net</email></para> - </listitem> - - <listitem> - <para>Peter Childs <email>pjchilds@imforei.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Peter Cornelius <email>pc@inr.fzk.de</email></para> - </listitem> - - <listitem> - <para>Peter Haight <email>peterh@prognet.com</email></para> - </listitem> - - <listitem> - <para>Peter Jeremy <email>perer.jeremy@alcatel.com.au</email></para> - </listitem> - - <listitem> - <para>Peter M. Chen <email>pmchen@eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Peter Much <email>peter@citylink.dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Peter Olsson <email>unknown</email></para> - </listitem> - - <listitem> - <para>Peter Pentchev <email>roam@orbitel.bg</email></para> - </listitem> - - <listitem> - <para>Peter Philipp <email>pjp@bsd-daemon.net</email></para> - </listitem> - - <listitem> - <para>Peter Stubbs <email>PETERS@staidan.qld.edu.au</email></para> - </listitem> - - <listitem> - <para>Peter van Heusden <email>pvh@egenetics.com</email></para> - </listitem> - - <listitem> - <para>Phil Maker <email>pjm@cs.ntu.edu.au</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Phil Taylor <email>phil@zipmail.co.uk</email></para> - </listitem> - - <listitem> - <para>Philip Musumeci <email>philip@rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Philippe Lefebvre <email>nemesis@balistik.net</email></para> - </listitem> - - <listitem> - <para>Pierre Y. Dampure <email>pierre.dampure@k2c.co.uk</email></para> - </listitem> - - <listitem> - <para>Pius Fischer <email>pius@ienet.com</email></para> - </listitem> - - <listitem> - <para>Pomegranate <email>daver@flag.blackened.net</email></para> - </listitem> - - <listitem> - <para>Powerdog Industries - <email>kevin.ruddy@powerdog.com</email></para> - </listitem> - - <listitem> - <para>Priit Järv <email>priit@cc.ttu.ee</email></para> - </listitem> - - <listitem> - <para>R Joseph Wright <email>rjoseph@mammalia.org</email></para> - </listitem> - - <listitem> - <para>R. Kym Horsell</para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Randal S. Masutani <email>randal@comtest.com</email></para> - </listitem> - - <listitem> - <para>Randall Hopper <email>rhh@ct.picker.com</email></para> - </listitem> - - <listitem> - <para>Randall W. Dean <email>rwd@osf.org</email></para> - </listitem> - - <listitem> - <para>Randy Bush <email>rbush@bainbridge.verio.net</email></para> - </listitem> - - <listitem> - <para>Rasmus Kaj <email>kaj@Raditex.se</email></para> - </listitem> - - <listitem> - <para>Reinier Bezuidenhout - <email>rbezuide@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Remy Card <email>Remy.Card@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Ricardas Cepas <email>rch@richard.eu.org</email></para> - </listitem> - - <listitem> - <para>Riccardo Veraldi <email>veraldi@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Rich Wood <email>rich@FreeBSD.org.uk</email></para> - </listitem> - - <listitem> - <para>Richard Henderson <email>richard@atheist.tamu.edu</email></para> - </listitem> - - <listitem> - <para>Richard Hwang <email>rhwang@bigpanda.com</email></para> - </listitem> - - <listitem> - <para>Richard Kiss <email>richard@homemail.com</email></para> - </listitem> - - <listitem> - <para>Richard J Kuhns <email>rjk@watson.grauel.com</email></para> - </listitem> - - <listitem> - <para>Richard M. Neswold - <email>rneswold@enteract.com</email></para> - </listitem> - - <listitem> - <para>Richard Seaman, Jr. <email>dick@tar.com</email></para> - </listitem> - - <listitem> - <para>Richard Stallman <email>rms@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Richard Straka <email>straka@user1.inficad.com</email></para> - </listitem> - - <listitem> - <para>Richard Tobin <email>richard@cogsci.ed.ac.uk</email></para> - </listitem> - - <listitem> - <para>Richard Wackerbarth <email>rkw@Dataplex.NET</email></para> - </listitem> - - <listitem> - <para>Richard Winkel <email>rich@math.missouri.edu</email></para> - </listitem> - - <listitem> - <para>Richard Wiwatowski <email>rjwiwat@adelaide.on.net</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>rick@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Rick Macklin <email>unknown</email></para> - </listitem> - - <listitem> - <para>Rob Austein <email>sra@epilogue.com</email></para> - </listitem> - - <listitem> - <para>Rob Mallory <email>rmallory@qualcomm.com</email></para> - </listitem> - - <listitem> - <para>Rob Snow <email>rsnow@txdirect.net</email></para> - </listitem> - - <listitem> - <para>Robert Crowe <email>bob@speakez.com</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Robert Eckardt - <email>roberte@MEP.Ruhr-Uni-Bochum.de</email></para> - </listitem> - - <listitem> - <para>Robert Sanders <email>rsanders@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Robert Sexton <email>robert@kudra.com</email></para> - </listitem> - - <listitem> - <para>Robert Shady <email>rls@id.net</email></para> - </listitem> - - <listitem> - <para>Robert Swindells <email>swindellsr@genrad.co.uk</email></para> - </listitem> - - <listitem> - <para>Robert Withrow <email>witr@rwwa.com</email></para> - </listitem> - - <listitem> - <para>Robert Yoder <email>unknown</email></para> - </listitem> - - <listitem> - <para>Robin Carey - <email>robin@mailgate.dtc.rankxerox.co.uk</email></para> - </listitem> - - <listitem> - <para>Rod Taylor <email>rod@idiotswitch.org</email></para> - </listitem> - - <listitem> - <para>Roger Hardiman <email>roger@cs.strath.ac.uk</email></para> - </listitem> - - <listitem> - <para>Roland Jesse <email>jesse@cs.uni-magdeburg.de</email></para> - </listitem> - - <listitem> - <para>Roman Shterenzon <email>roman@xpert.com</email></para> - </listitem> - - <listitem> - <para>Ron Bickers <email>rbickers@intercenter.net</email></para> - </listitem> - - <listitem> - <para>Ron Lenk <email>rlenk@widget.xmission.com</email></para> - </listitem> - - <listitem> - <para>Ronald Kuehn <email>kuehn@rz.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Rudolf Cejka <email>cejkar@dcse.fee.vutbr.cz</email></para> - </listitem> - - <listitem> - <para>Ruslan Belkin <email>rus@home2.UA.net</email></para> - </listitem> - - <listitem> - <para>Ruslan Shevchenko <email>rssh@cam.grad.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Russell L. Carter <email>rcarter@pinyon.org</email></para> - </listitem> - - <listitem> - <para>Russell Vincent <email>rv@groa.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Ryan Younce <email>ryany@pobox.com</email></para> - </listitem> - - <listitem> - <para>Ryuichiro IMURA <email>imura@af.airnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>Sakai Hiroaki <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakari Jalovaara <email>sja@tekla.fi</email></para> - </listitem> - - <listitem> - <para>Sam Hartman <email>hartmans@mit.edu</email></para> - </listitem> - - <listitem> - <para>Samuel Lam <email>skl@ScalableNetwork.com</email></para> - </listitem> - - <listitem> - <para>Samuel Tardieu <email>sam@inf.enst.fr</email></para> - </listitem> - - <listitem> - <para>Samuele Zannoli <email>zannoli@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Sander Janssen <email>janssen@rendo.dekooi.nl</email></para> - </listitem> - - <listitem> - <para>Sander Vesik <email>sander@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Sandro Sigala <email>ssigala@globalnet.it</email></para> - </listitem> - - <listitem> - <para>SANETO Takanori <email>sanewo@strg.sony.co.jp</email></para> - </listitem> - - <listitem> - <para>SASAKI Shunsuke <email>ele@pop17.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>Sascha Blank <email>blank@fox.uni-trier.de</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Satoh Junichi <email>junichi@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>SAWADA Mizuki <email>miz@qb3.so-net.ne.jp</email></para> - </listitem> - - <listitem> - <para>Scot Elliott <email>scot@poptart.org</email></para> - </listitem> - - <listitem> - <para>Scot W. Hetzel <email>hetzels@westbend.net</email></para> - </listitem> - - <listitem> - <para>Scott A. Kenney <email>saken@rmta.ml.org</email></para> - </listitem> - - <listitem> - <para>Scott A. Moberly <email>smoberly@xavier.dyndns.org</email></para> - </listitem> - - <listitem> - <para>Scott Blachowicz - <email>scott.blachowicz@seaslug.org</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Hazen Mueller <email>scott@zorch.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Scott Michel <email>scottm@cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Mitchel <email>scott@uk.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sebastian Strollo <email>seb@erix.ericsson.se</email></para> - </listitem> - - <listitem> - <para>Serge V. Vakulenko <email>vak@zebub.msk.su</email></para> - </listitem> - - <listitem> - <para>Sergei Chechetkin <email>csl@whale.sunbay.crimea.ua</email></para> - </listitem> - - <listitem> - <para>Sergei S. Laskavy <email>laskavy@pc759.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Sergey Gershtein <email>sg@mplik.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Kosyakov <email>ks@itp.ac.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Potapov <email>sp@alkor.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Samoyloff <email>gonza@techline.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Shkonda <email>serg@bcs.zp.ua</email></para> - </listitem> - - <listitem> - <para>Sergey V.Dorokhov <email>svd@kbtelecom.nalnet.ru</email></para> - </listitem> - - <listitem> - <para>Sergio Lenzi <email>lenzi@bsi.com.br</email></para> - </listitem> - - <listitem> - <para>Shaun Courtney <email>shaun@emma.eng.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Shawn M. Carey <email>smcarey@mailbox.syr.edu</email></para> - </listitem> - - <listitem> - <para>Shigio Yamaguchi <email>shigio@tamacom.com</email></para> - </listitem> - - <listitem> - <para>Shinya Esu <email>esu@yk.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Shinya FUJIE <email>fujie@tk.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>Shuichi Tanaka <email>stanaka@bb.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Simon <email>simon@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Simon Burge <email>simonb@telstra.com.au</email></para> - </listitem> - - <listitem> - <para>Simon Dick <email>simond@irrelevant.org</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email></para> - </listitem> - - <listitem> - <para>Simon Marlow <email>simonm@dcs.gla.ac.uk</email></para> - </listitem> - - <listitem> - <para>Simon Shapiro <email>shimon@simon-shapiro.org</email></para> - </listitem> - - <listitem> - <para>Sin'ichiro MIYATANI <email>siu@phaseone.co.jp</email></para> - </listitem> - - <listitem> - <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Soochon Radee <email>slr@mitre.org</email></para> - </listitem> - - <listitem> - <para>Soren Dayton <email>csdayton@midway.uchicago.edu</email></para> - </listitem> - - <listitem> - <para>Soren Dossing <email>sauber@netcom.com</email></para> - </listitem> - - <listitem> - <para>Soren S. Jorvang <email>soren@dt.dk</email></para> - </listitem> - - <listitem> - <para>Stefan Bethke <email>stb@hanse.de</email></para> - </listitem> - - <listitem> - <para>Stefan Eggers <email>seggers@semyam.dinoco.de</email></para> - </listitem> - - <listitem> - <para>Stefan Moeding <email>s.moeding@ndh.net</email></para> - </listitem> - - <listitem> - <para>Stefan Petri <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stefan `Sec` Zehl <email>sec@42.org</email></para> - </listitem> - - <listitem> - <para>Steinar Haug <email>sthaug@nethelp.no</email></para> - </listitem> - - <listitem> - <para>Stephane E. Potvin <email>sepotvin@videotron.ca</email></para> - </listitem> - - <listitem> - <para>Stephane Legrand <email>stephane@lituus.fr</email></para> - </listitem> - - <listitem> - <para>Stephen Clawson - <email>sclawson@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Stephen F. Combs <email>combssf@salem.ge.com</email></para> - </listitem> - - <listitem> - <para>Stephen Farrell <email>stephen@farrell.org</email></para> - </listitem> - - <listitem> - <para>Stephen Hocking <email>sysseh@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen J. Roznowski <email>sjr@home.net</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen Melvin <email>melvin@zytek.com</email></para> - </listitem> - - <listitem> - <para>Steve Bauer <email>sbauer@rock.sdsmt.edu</email></para> - </listitem> - - <listitem> - <para>Steve Coltrin <email>spcoltri@unm.edu</email></para> - </listitem> - - <listitem> - <para>Steve Deering <email>unknown</email></para> - </listitem> - - <listitem> - <para>Steve Gerakines <email>steve2@genesis.tiac.net</email></para> - </listitem> - - <listitem> - <para>Steve Gericke <email>steveg@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Steve Piette <email>steve@simon.chi.il.US</email></para> - </listitem> - - <listitem> - <para>Steve Schwarz <email>schwarz@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Steven G. Kargl - <email>kargl@troutmask.apl.washington.edu</email></para> - </listitem> - - <listitem> - <para>Steven H. Samorodin <email>samorodi@NUXI.com</email></para> - </listitem> - - <listitem> - <para>Steven McCanne <email>mccanne@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Steven Plite <email>splite@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Steven Wallace <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stijn Hoop <email>stijn@win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Stuart Henderson - <email>stuart@internationalschool.co.uk</email></para> - </listitem> - - <listitem> - <para>Sue Blake <email>sue@welearn.com.au</email></para> - </listitem> - - <listitem> - <para>Sugimoto Sadahiro <email>ixtl@komaba.utmc.or.jp</email></para> - </listitem> - - <listitem> - <para>SUGIMURA Takashi <email>sugimura@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Sugiura Shiro <email>ssugiura@duo.co.jp</email></para> - </listitem> - - <listitem> - <para>Sujal Patel <email>smpatel@wam.umd.edu</email></para> - </listitem> - - <listitem> - <para>Sungman Cho <email>smcho@tsp.korea.ac.kr</email></para> - </listitem> - - <listitem> - <para>Sune Stjerneby <email>stjerneby@usa.net</email></para> - </listitem> - - <listitem> - <para>SURANYI Peter - <email>suranyip@jks.is.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>Suzuki Yoshiaki - <email>zensyo@ann.tama.kawasaki.jp</email></para> - </listitem> - - <listitem> - <para>Tadashi Kumano <email>kumano@strl.nhk.or.jp</email></para> - </listitem> - - <listitem> - <para>Taguchi Takeshi <email>taguchi@tohoku.iij.ad.jp</email></para> - </listitem> - - <listitem> - <para>TAKAHASHI Kaoru <email>kaoru@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Takahiro Yugawa <email>yugawa@orleans.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Takashi Mega <email>mega@minz.org</email></para> - </listitem> - - <listitem> - <para>Takashi Uozu <email>j1594016@ed.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Ariga <email>a00821@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeru NAIKI <email>naiki@bfd.es.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Amaike <email>amaike@iri.co.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi MUTOH <email>mutoh@info.nara-k.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Ohashi - <email>ohashi@mickey.ai.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi WATANABE - <email>watanabe@crayon.earth.s.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takuya SHIOZAKI - <email>tshiozak@makino.ise.chuo-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatoku Ogaito <email>tacha@tera.fukui-med.ac.jp</email></para> - </listitem> - - <listitem> - <para>Ted Buswell <email>tbuswell@mediaone.net</email></para> - </listitem> - - <listitem> - <para>Ted Faber <email>faber@isi.edu</email></para> - </listitem> - - <listitem> - <para>Ted Lemon <email>mellon@isc.org</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@lambert.org</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tetsuya Furukawa <email>tetsuya@secom-sis.co.jp</email></para> - </listitem> - - <listitem> - <para>Theo de Raadt <email>deraadt@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Thomas <email>thomas@mathematik.uni-Bremen.de</email></para> - </listitem> - - <listitem> - <para>Thomas D. Dean <email>tomdean@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas David Rivers <email>rivers@dignus.com</email></para> - </listitem> - - <listitem> - <para>Thomas G. McWilliams <email>tgm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas Graichen - <email>graichen@omega.physik.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Thomas König - <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para> - </listitem> - - <listitem> - <para>Thomas Ptacek <email>unknown</email></para> - </listitem> - - <listitem> - <para>Thomas Quinot <email>thomas@cuivre.fr.eu.org</email></para> - </listitem> - - <listitem> - <para>Thomas A. Stephens <email>tas@stephens.org</email></para> - </listitem> - - <listitem> - <para>Thomas Stromberg <email>tstrombe@rtci.com</email></para> - </listitem> - - <listitem> - <para>Thomas Valentino Crimi - <email>tcrimi+@andrew.cmu.edu</email></para> - </listitem> - - <listitem> - <para>Thomas Wintergerst <email>thomas@lemur.nord.de</email></para> - </listitem> - - <listitem> - <para>Þórður Ívarsson - <email>totii@est.is</email></para> - </listitem> - - <listitem> - <para>Timothy Jensen <email>toast@blackened.com</email></para> - </listitem> - - <listitem> - <para>Tim Kientzle <email>kientzle@netcom.com</email></para> - </listitem> - - <listitem> - <para>Tim Singletary - <email>tsingle@sunland.gsfc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Tim Wilkinson <email>tim@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Timo J. Rinne <email>tri@iki.fi</email></para> - </listitem> - - <listitem> - <para>Tobias Reifenberger <email>treif@mayn.de</email></para> - </listitem> - - <listitem> - <para>Todd Miller <email>millert@openbsd.org</email></para> - </listitem> - - <listitem> - <para>Tom <email>root@majestix.cmr.no</email></para> - </listitem> - - <listitem> - <para>Tom <email>tom@sdf.com</email></para> - </listitem> - - <listitem> - <para>Tom Gray - DCA <email>dcasba@rain.org</email></para> - </listitem> - - <listitem> - <para>Tom Jobbins <email>tom@tom.tj</email></para> - </listitem> - - <listitem> - <para>Tom Pusateri <email>pusateri@juniper.net</email></para> - </listitem> - - <listitem> - <para>Tom Rush <email>tarush@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Tom Samplonius <email>tom@misery.sdf.com</email></para> - </listitem> - - <listitem> - <para>Tomohiko Kurahashi - <email>kura@melchior.q.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tony Kimball <email>alk@Think.COM</email></para> - </listitem> - - <listitem> - <para>Tony Li <email>tli@jnx.com</email></para> - </listitem> - - <listitem> - <para>Tony Lynn <email>wing@cc.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Tony Maher <email>Tony.Maher@eBioinformatics.com</email></para> - </listitem> - - <listitem> - <para>Torbjorn Granlund <email>tege@matematik.su.se</email></para> - </listitem> - - <listitem> - <para>Toshihiko SHIMOKAWA <email>toshi@tea.forus.or.jp</email></para> - </listitem> - - <listitem> - <para>Toshihiro Kanda <email>candy@kgc.co.jp</email></para> - </listitem> - - <listitem> - <para>Toshiomi Moriki - <email>Toshiomi.Moriki@ma1.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Trefor S. <email>trefor@flevel.co.uk</email></para> - </listitem> - - <listitem> - <para>Trevor Blackwell <email>tlb@viaweb.com</email></para> - </listitem> - - <listitem> - <para>Udo Schweigert <email>ust@cert.siemens.de</email></para> - </listitem> - - <listitem> - <para>Ugo Paternostro <email>paterno@dsi.unifi.it</email></para> - </listitem> - - <listitem> - <para>Ulf Kieber <email>kieber@sax.de</email></para> - </listitem> - - <listitem> - <para>Ulli Linzen <email>ulli@perceval.camelot.de</email></para> - </listitem> - - <listitem> - <para>URATA Shuichiro <email>s-urata@nmit.tmg.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ustimenko Semen <email>semen@iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Uwe Arndt <email>arndt@mailhost.uni-koblenz.de</email></para> - </listitem> - - <listitem> - <para>Vadim Chekan <email>vadim@gc.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Vadim Kolontsov <email>vadim@tversu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vadim Mikhailov <email>mvp@braz.ru</email></para> - </listitem> - - <listitem> - <para>Valentin Nechayev <email>netch@lucky.net</email></para> - </listitem> - - <listitem> - <para>Van Jacobson <email>van@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Vasily V. Grechishnikov - <email>bazilio@ns1.ied-vorstu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vasim Valejev <email>vasim@uddias.diaspro.com</email></para> - </listitem> - - <listitem> - <para>Vernon J. Schryver <email>vjs@mica.denver.sgi.com</email></para> - </listitem> - - <listitem> - <para>Vic Abell <email>abe@cc.purdue.edu</email></para> - </listitem> - - <listitem> - <para>Ville Eerola <email>ve@sci.fi</email></para> - </listitem> - - <listitem> - <para>Vince Valenti <email>vince@blue-box.net</email></para> - </listitem> - - <listitem> - <para>Vincent Poy <email>vince@venus.gaianet.net</email></para> - </listitem> - - <listitem> - <para>Vincenzo Capuano - <email>VCAPUANO@vmprofs.esoc.esa.de</email></para> - </listitem> - - <listitem> - <para>Virgil Champlin <email>champlin@pa.dec.com</email></para> - </listitem> - - <listitem> - <para>Vladimir A. Jakovenko - <email>vovik@ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Vladimir Kushnir <email>kushn@mail.kar.net</email></para> - </listitem> - - <listitem> - <para>Vsevolod Lobko <email>seva@alex-ua.com</email></para> - </listitem> - - <listitem> - <para>W. Gerald Hicks <email>wghicks@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>W. Richard Stevens <email>rstevens@noao.edu</email></para> - </listitem> - - <listitem> - <para>Walt Howard <email>howard@ee.utah.edu</email></para> - </listitem> - - <listitem> - <para>Walt M. Shandruk <email>walt@erudition.net</email</para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wayne Scott <email>wscott@ichips.intel.com</email></para> - </listitem> - - <listitem> - <para>Werner Griessl - <email>werner@btp1da.phy.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Wes Santee <email>wsantee@wsantee.oz.net</email></para> - </listitem> - - <listitem> - <para>Wietse Venema <email>wietse@wzv.win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>Willem Jan Withagen <email>wjw@surf.IAE.nl</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>William Liao <email>william@tale.net</email></para> - </listitem> - - <listitem> - <para>Wojtek Pilorz - <email>wpilorz@celebris.bdk.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Wolfgang Helbig <email>helbig@ba-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Wu Ching-hong <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Yarema <email>yds@ingress.com</email></para> - </listitem> - - <listitem> - <para>Yaroslav Terletsky <email>ts@polynet.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Yasuhiro Fukama <email>yasuf@big.or.jp</email></para> - </listitem> - - <listitem> - <para>Yasuhito FUTATSUKI <email>futatuki@fureai.or.jp</email></para> - </listitem> - - <listitem> - <para>Yen-Ming Lee <email>leeym@bsd.ce.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yin-Jieh Chen <email>yinjieh@Crazyman.Dorm13.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yixin Jin <email>yjin@rain.cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Yoichi Asai <email>yatt@msc.biglobe.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihiko SARUMRU <email>mistral@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihisa NAKAGAWA - <email>y-nakaga@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshikazu Goto <email>gotoh@ae.anritsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshimasa Ohnishi - <email>ohnishi@isc.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yoshishige Arai <email>ryo2@on.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yuichi MATSUTAKA <email>matutaka@osa.att.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yujiro MIYATA - <email>miyata@bioele.nuee.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yu-Shun Wang <email>yushunwa@isi.edu</email></para> - </listitem> - - <listitem> - <para>Yusuke Nawano <email>azuki@azkey.org</email></para> - </listitem> - - <listitem> - <para>Yuu Yashiki <email>s974123@cc.matsuyama-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuuki SAWADA <email>mami@whale.cc.muroran-it.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuuichi Narahara <email>aconitum@po.teleway.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@cpcoup5.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Yves Fonk <email>yves@dutncp8.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Zach Heilig <email>zach@gaffaneys.com</email></para> - </listitem> - - <listitem> - <para>Zach Zurflu <email>zach@pabst.bendnet.com</email></para> - </listitem> - - <listitem> - <para>Zahemszhky Gabor <email>zgabor@code.hu</email></para> - </listitem> - - <listitem> - <para>Zhong Ming-Xun <email>zmx@mail.CDPA.nsysu.edu.tw</email></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="contrib-386bsd"> - <title>386BSD Patch Kit Patch Contributors</title> - - <para>(in alphabetical order by first name):</para> - - <itemizedlist> - <listitem> - <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Hall <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Andrey A. Chernov <email>ache@astral.msk.su</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew Moore <email>alm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email> - <email>jtk@netcom.com</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Bakul Shah <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Lustig <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Branko Lankester</para> - </listitem> - - <listitem> - <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Rivers <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David Dawes <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Greenman <email>dg@Root.COM</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Felix Gaehtgens - <email>felix@escape.vsse.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Guido van Rooij <email>guido@gvr.org</email></para> - </listitem> - - <listitem> - <para>Guy Antony Halse <email>guy@rucus.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Guy Harris <email>guy@auspex.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl <email>hpeyerl@novatel.cuc.ab.ca</email></para> - </listitem> - - <listitem> - <para>Holger Veit <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro, R. Kym Horsell</para> - </listitem> - - <listitem> - <para>J.T. Conklin <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>James Clark <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James W. Dolter</para> - </listitem> - - <listitem> - <para>James da Silva <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Jay Fenlason <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jörg Lohse - <email>lohse@tech7.informatik.uni-hamburg.de</email></para> - </listitem> - - <listitem> - <para>Jörg Wunsch - <email>joerg_wunsch@uriah.heep.sax.de</email></para> - </listitem> - - <listitem> - <para>John Dyson</para> - </listitem> - - <listitem> - <para>John Woods <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jordan K. Hubbard <email>jkh@whisker.hubbard.ie</email></para> - </listitem> - - <listitem> - <para>Julian Elischer <email>julian@dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Julian Stacey <email>jhs@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer <email>karl@NeoSoft.com</email> - <email>karl@one.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Keith Bostic <email>bostic@toe.CS.Berkeley.EDU</email></para> - </listitem> - - <listitem> - <para>Ken Hughes</para> - </listitem> - - <listitem> - <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey <email>kml%rokkaku.UUCP@mathcs.emory.edu</email> - <email>kml@mosquito.cis.ufl.edu</email></para> - </listitem> - - <listitem> - <para>Marc Frajola <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email> - <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Renters <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Michael Clay <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Nate Williams <email>nate@bsd.coe.montana.edu</email></para> - </listitem> - - <listitem> - <para>Nick Handel <email>nhandel@NeoSoft.com</email> - <email>nick@madhouse.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Pace Willisson <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Peter da Silva <email>peter@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Poul-Henning Kamp<email>phk@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Rick Macklem <email>root@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Rodney W. Grimes <email>rgrimes@cdrom.com</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan <email>sef@kithrup.com</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email> - <email>sjg@zen.void.oz.au</email></para> - </listitem> - - <listitem> - <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Terry Lambert <email>terry@icarus.weber.edu</email></para> - </listitem> - - <listitem> - <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tor Egge <email>Tor.Egge@idi.ntnu.no</email></para> - </listitem> - - <listitem> - <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>William Jolitz <email>withheld</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier <email>wolf@dentaro.GUN.de</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml deleted file mode 100644 index cc3bf20da7..0000000000 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ /dev/null @@ -1,1566 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.56 2000/08/22 05:54:59 kuriyama Exp $ ---> - -<chapter id="cutting-edge"> - <title>The Cutting Edge</title> - - <para><emphasis>Restructured, reorganized, and parts updated by &a.jim; - March 2000. Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik; - with feedback from various others.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>FreeBSD is under constant development between releases. For - people who want to be on the cutting edge, there are several easy - mechanisms for keeping your system in sync with the latest - developments. Be warned—the cutting edge is not for everyone! - This chapter will help you decide if you want to track the - development system, or stick with one of the released - versions.</para> - </sect1> - - <sect1 id="current-stable"> - <title>-CURRENT vs. -STABLE</title> - - <para>There are two development branches to FreeBSD; -CURRENT and - -STABLE. This section will explain a bit about each and describe - how to keep your system up-to-date with each respective tree. - -CURRENT will be discussed first, then -STABLE.</para> - - <sect2 id="current"> - <title>Staying Current with FreeBSD</title> - - <para>As you are reading this, keep in mind that -CURRENT is the - <quote>bleeding edge</quote> of FreeBSD development and that if you - are new to FreeBSD, you are most likely going to want to think - twice about running it.</para> - - <sect3> - <title>What is FreeBSD-CURRENT?</title> - - <para>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!</para> - </sect3> - - <sect3> - <title>Who needs FreeBSD-CURRENT?</title> - - <para>FreeBSD-CURRENT is made generally available for 3 primary - interest groups:</para> - - <orderedlist> - <listitem> - <para>Members of the FreeBSD group who are actively working on - some part of the source tree and for whom keeping - <quote>current</quote> is an absolute requirement.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>Peripheral members of the FreeBSD (or some other) group - who merely wish to keep an eye on things and use the current - sources for reference purposes (e.g. for - <emphasis>reading</emphasis>, not running). These people - also make the occasional comment or contribute code.</para> - </listitem> - </orderedlist> - </sect3> - - <sect3> - <title>What is FreeBSD-CURRENT <emphasis>not</emphasis>?</title> - - <orderedlist> - <listitem> - <para>A fast-track to getting pre-release bits because you - heard there is some cool new feature in there and you want - to be the first on your block to have it.</para> - </listitem> - - <listitem> - <para>A quick way of getting bug fixes.</para> - </listitem> - - <listitem> - <para>In any way <quote>officially supported</quote> by us. - We do our best to help people genuinely in one of the 3 - <quote>legitimate</quote> FreeBSD-CURRENT categories, but we - simply <emphasis>do not have the time</emphasis> to provide - tech support for it. 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 - <emphasis>and</emphasis> 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.</para> - </listitem> - </orderedlist> - </sect3> - - <sect3> - <title>Using FreeBSD-CURRENT</title> - - <orderedlist> - <listitem> - <para>Join the &a.current; and the &a.cvsall; . This is not - just a good idea, it is <emphasis>essential</emphasis>. If - you are not on the <emphasis>FreeBSD-CURRENT</emphasis> - mailing list, 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 important bulletins which may be critical - to your system's continued health.</para> - - <para>The &a.cvsall; mailing list will allow you to see the - commit log entry for each change as it is made along with - any pertinent information on possible side-effects.</para> - - <para>To join these lists, send mail to &a.majordomo; and - specify the following in the body of your message:</para> - - <programlisting> -subscribe freebsd-current -subscribe cvs-all</programlisting> - - <para>Optionally, you can also say <literal>help</literal> - and Majordomo will send you full help on how to subscribe - and unsubscribe to the various other mailing lists we - support.</para> - </listitem> - - <listitem> - <para>Grab the sources from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>. You can do this in - one of three ways:</para> - - <orderedlist> - <listitem> - <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. Unless - you have a good TCP/IP connection at a flat rate, this - is the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> program - with <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this - supfile</ulink>. This is the second most recommended - method, since it allows you to grab the entire - collection once and then only what has changed from then - on. Many people run cvsup from cron and keep their - sources up-to-date automatically. For a fairly easy - interface to this, simply type:</para> - - <blockquote><screen>&prompt.root; <userinput>pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote> - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for - FreeBSD-CURRENT is always <quote>exported</quote> on: - <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/</ulink>. - We also use <command>wu-ftpd</command> which allows - compressed/tarred grabbing of whole trees. e.g. you - see:</para> - - <screen>usr.bin/lex</screen> - - <para>You can do the following to get the whole directory - as a tar file:</para> - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar</userinput></screen> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the - source and communications bandwidth is not a consideration, - use <command>cvsup</command> or <command>ftp</command>. - Otherwise, use <application>CTM</application>.</para> - - <para>If you are grabbing the sources to run, and not just - look at, then grab <emphasis>all</emphasis> of current, not - just selected portions. The reason for this is that various - parts of the source depend on updates elsewhere, and trying - to compile just a subset is almost guaranteed to get you - into trouble.</para> - - <para>Before compiling current, read the - <filename>Makefile</filename>in <filename>/usr/src</filename> - carefully. You should at least run a <link - linkend="makeworld">make world</link> the first time through - as part of the upgrading process. Reading the &a.current; - will keep you up-to-date on other bootstrapping procedures - that sometimes become necessary as we move towards the next - release.</para> - </listitem> - - <listitem> - <para>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!</para> - </listitem> - </orderedlist> - </sect3> - </sect2> - - <sect2 id="stable"> - <title>Staying Stable with FreeBSD</title> - - <para>If you are using FreeBSD in a production environment and want - to make sure you have the latest fixes from the -CURRENT branch, - you want to be running -STABLE. This is the tree that -RELEASEs - are branched from when we are putting together a new release. For - example, if you have a copy of 3.4-RELEASE, that is really just a - <quote>snapshot</quote> from the -STABLE branch that we put on - CDROM. In order to get any changes merged into -STABLE after the - -RELEASE, you need to <quote>track</quote> the -STABLE - branch.</para> - - <sect3> - <title>What is FreeBSD-STABLE?</title> - - <para>FreeBSD-STABLE is our development branch for a more low-key - and conservative set of changes intended for our next mainstream - release. Changes of an experimental or untested nature do not - go into this branch (see <link - linkend="current">FreeBSD-CURRENT</link>).</para> - </sect3> - - <sect3> - <title>Who needs FreeBSD-STABLE?</title> - - <para>If you are a commercial user or someone who puts maximum - stability of their FreeBSD system before all other concerns, you - should consider tracking <emphasis>stable</emphasis>. This is - especially true if you have installed the most recent release - (<ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/&rel.current;-RELEASE/">&rel.current;-RELEASE</ulink> - at the time of this writing) since the - <emphasis>stable</emphasis> branch is effectively a bug-fix - stream relative to the previous release.</para> - - <warning> - <para>The <emphasis>stable</emphasis> tree endeavors, above all, - to be fully compilable and stable at all times, but we do - occasionally make mistakes (these are still active sources - with quickly-transmitted updates, after all). We also do our - best to thoroughly test fixes in <emphasis>current</emphasis> - before bringing them into <emphasis>stable</emphasis>, but - sometimes our tests fail to catch every case. If something - breaks for you in <emphasis>stable</emphasis>, please let us - know <emphasis>immediately!</emphasis> (see next - section).</para> - </warning> - </sect3> - - <sect3> - <title>Using FreeBSD-STABLE</title> - - <orderedlist> - <listitem> - <para>Join the &a.stable;. This will keep you informed of - build-dependencies that may appear in - <emphasis>stable</emphasis> or any other issues requiring - special attention. Developers will also make announcements - in this mailing list when they are contemplating some - controversial fix or update, giving the users a chance to - respond if they have any issues to raise concerning the - proposed change.</para> - - <para>The &a.cvsall; mailing list will allow you to see the - commit log entry for each change as it is made along with - any pertinent information on possible side-effects.</para> - - <para>To join these lists, send mail to &a.majordomo; and - specify the following in the body of your message:</para> - - <programlisting> -subscribe freebsd-stable -subscribe cvs-all</programlisting> - - <para>Optionally, you can also say <literal>help</literal> - and Majordomo will send you full help on how to subscribe - and unsubscribe to the various other mailing lists we - support.</para> - </listitem> - - <listitem> - <para>If you are installing a new system and want it to be as - stable as possible, you can simply grab the latest dated - branch snapshot from <ulink - url="ftp://releng4.FreeBSD.org/pub/FreeBSD/">ftp://releng4.FreeBSD.org/pub/FreeBSD/</ulink> - and install it like any other release.</para> - - <para>If you are already running a previous release of FreeBSD - and wish to upgrade via sources then you can easily do so - from <hostid role="fqdn">ftp.FreeBSD.org</hostid>. This can - be done in one of three ways:</para> - - <orderedlist> - <listitem> - <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. Unless - you have a good TCP/IP connection at a flat rate, this - is the way to do it.</para> - </listitem> - - <listitem> - <para>Use the <link linkend="cvsup">cvsup</link> program - with <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this - supfile</ulink>. This is the second most recommended - method, since it allows you to grab the entire - collection once and then only what has changed from then - on. Many people run cvsup from cron to keep their - sources up-to-date automatically. For a fairly easy - interface to this, simply type:</para> - - <blockquote><screen>&prompt.root; <userinput>pkg_add -f \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote> - </listitem> - - <listitem> - <para>Use <command>ftp</command>. The source tree for - FreeBSD-STABLE is always <quote>exported</quote> on: - <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/</ulink></para> - - <para>We also use <command>wu-ftpd</command> which allows - compressed/tarred grabbing of whole trees. e.g. you - see:</para> - - <screen>usr.bin/lex</screen> - - <para>You can do the following to get the whole directory - for you as a tar file:</para> - - <screen><prompt>ftp></prompt> <userinput>cd usr.bin</userinput> -<prompt>ftp></prompt> <userinput>get lex.tar</userinput></screen> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>Essentially, if you need rapid on-demand access to the - source and communications bandwidth is not a consideration, - use <command>cvsup</command> or <command>ftp</command>. - Otherwise, use <application>CTM</application>.</para> - </listitem> - - <listitem> - <para>Before compiling stable, read the - <filename>Makefile</filename> in <filename>/usr/src</filename> - carefully. You should at least run a <link - linkend="makeworld">make world</link> the first time through - as part of the upgrading process. Reading the &a.stable; will - keep you up-to-date on other bootstrapping procedures that - sometimes become necessary as we move towards the next - release.</para> - </listitem> - </orderedlist> - </sect3> - </sect2> - </sect1> - - <sect1 id="synching"> - <title>Synchronizing Your Source</title> - - <para>There are various ways of using an Internet (or email) - connection to stay up-to-date with any given area of the FreeBSD - project sources, or all areas, depending on what interests you. The - primary services we offer are <link linkend="anoncvs">Anonymous - CVS</link>, <link linkend="cvsup">CVSup</link>, and <link - linkend="ctm">CTM</link>.</para> - - <para><application>Anonymous CVS</application> and - <application>CVSup</application> use the <emphasis>pull</emphasis> - model of updating sources. In the case of - <application>CVSup</application> the user (or a cron script) invokes - the <command>cvsup</command> program, and it interacts with a - <command>cvsupd</command> server somewhere to bring your files - up-to-date. The updates you receive are up-to-the-minute and you - get them when, and only when, you want them. You can easily - restrict your updates to the specific files or directories that are - of interest to you. Updates are generated on the fly by the server, - according to what you have and what you want to have. - <application>Anonymous CVS</application> is quite a bit more - simplistic than CVSup in that it's just an extension to - <application>CVS</application> which allows it to pull changes - directly from a remote CVS repository. - <application>CVSup</application> can do this far more efficiently, - but <application>Anonymous CVS</application> is easier to - use.</para> - - <para><application>CTM</application>, on the other hand, does not - interactively compare the sources you have with those on the master - archive or otherwise pull them across.. Instead, a script which - identifies changes in files since its previous run is executed - several times a day on the master CTM machine, any detected changes - being compressed, stamped with a sequence-number and encoded for - transmission over email (in printable ASCII only). Once received, - these <quote>CTM deltas</quote> can then be handed to the - &man.ctm.rmail.1; utility which will automatically decode, verify - and apply the changes to the user's copy of the sources. This - process is far more efficient than <application>CVSup</application>, - and places less strain on our server resources since it is a - <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis> - model.</para> - - <para>There are other trade-offs, of course. If you inadvertently - wipe out portions of your archive, <application>CVSup</application> - will detect and rebuild the damaged portions for you. - <application>CTM</application> won't do this, and if you wipe some - portion of your source tree out (and don't have it backed up) then - you will have to start from scratch (from the most recent CVS - <quote>base delta</quote>) and rebuild it all with CTM or, with - anoncvs, simply delete the bad bits and resync.</para> - - <para>More information about <application>Anonymous CVS</application>, - <application>CTM</application>, and - <application>CVSup</application> is available further down in this - section.</para> - </sect1> - - <sect1 id="makeworld"> - <title>Using <command>make world</command></title> - - <para>Once you have synchronized your local source tree against a - particular version of FreeBSD (<literal>stable</literal>, - <literal>current</literal> and so on) you must then use the source - tree to rebuild the system.</para> - - <warning> - <title>Take a backup</title> - - <para>I cannot stress highly enough how important it is to take a - backup of your system <emphasis>before</emphasis> you do this. - While remaking the world is (as long as you follow these - instructions) an easy task to do, there will inevitably be times - when you make mistakes, or when mistakes made by others in the - source tree render your system unbootable.</para> - - <para>Make sure you have taken a backup. And have a fix-it floppy to - hand. I have never needed to use them, and, touch wood, I never - will, but it is always better to be safe than sorry.</para> - </warning> - - <warning> - <title>Subscribe to the right mailing list</title> - - <para>The -STABLE and -CURRENT FreeBSD code branches are, by their - nature, <emphasis>in development</emphasis>. People that - contribute to FreeBSD are human, and mistakes occasionally - happen.</para> - - <para>Sometimes these mistakes can be quite harmless, just causing - your system to print a new diagnostic warning. Or the change may - be catastrophic, and render your system unbootable or destroy your - filesystems (or worse).</para> - - <para>If problems like these occur, a <quote>heads up</quote> is - posted to the appropriate mailing list, explaining the nature of - the problem and which systems it affects. And an <quote>all - clear</quote> announcement is posted when the problem has been - solved.</para> - - <para>If you try and track -STABLE or -CURRENT and do not read the - <email>stable@FreeBSD.org</email> or - <email>current@FreeBSD.org</email> mailing lists then you are - asking for trouble.</para> - </warning> - - <sect2> - <title>Read <filename>/usr/src/UPDATING</filename></title> - - <para>Before you do anything else, read - <filename>/usr/src/UPDATING</filename> (or the equivalent file - wherever you have a copy of the source code). This file should - contain important information about problems you might encounter, or - specify the order in which you might have to run certain commands. - If <filename>UPDATING</filename> contradicts something you read here, - <filename>UPDATING</filename> takes precedence.</para> - - <important> - <para>Reading <filename>UPDATING</filename> is not an acceptable - substitute for subscribing to the correct mailing list, as described - previously. The two requirements are complementary, not - exclusive.</para> - </important> - </sect2> - - <sect2> - <title>Check <filename>/etc/make.conf</filename></title> - - <para>Examine the files - <filename>/etc/defaults/make.conf</filename> and - <filename>/etc/make.conf</filename>. The first contains some - default defines – most of which are commented out. To - make use of them when you rebuild your system from source, add - them to <filename>/etc/make.conf</filename>. Keep in mind that - anything you add to <filename>/etc/make.conf</filename> is also - used every time you run <command>make</command>, so it is a good - idea to set them to something sensible for your system.</para> - - <para>As a typical user (not a FreeBSD developer), you will - probably want to copy the <makevar>CFLAGS</makevar> and - <makevar>NOPROFILE</makevar> lines found in - <filename>/etc/defaults/make.conf</filename> to - <filename>/etc/make.conf</filename> and uncomment them.</para> - - <note> - <title/Version 2.1.7 and below/ - - <para>If your machine has a floating point unit (386DX, 486DX, - Pentium and up class machines) then you can also uncomment the - HAVE_FPU line.</para> - - <para>This definition was removed for version 2.2.2 and up of - FreeBSD.</para> - </note> - - <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so - on) and decide if they are relevant to you.</para> - </sect2> - - <sect2> - <title>Update <filename>/etc/group</filename></title> - - <para>The <filename>/etc</filename> directory contains a large part - of your system's configuration information, as well as scripts - that are run at system startup. Some of these scripts change from - version to version of FreeBSD.</para> - - <para>Some of the configuration files are also used in the day to - day running of the system. In particular, - <filename>/etc/group</filename>.</para> - - <para>There have been occasions when the installation part of - <quote>make world</quote> has expected certain usernames or groups - to exist. When performing an upgrade it is likely that these - groups did not exist. This caused problems when upgrading.</para> - - <para>The most recent example of this is when the <quote/ppp/ group - (later renamed <quote/network/) was added. Users had the - installation process fail for them when parts of the - <filename>ppp</filename> subsystem were installed using a - non-existent (for them) group name.</para> - - <para>The solution is to examine - <filename>/usr/src/etc/group</filename> and compare its list of - groups with your own. If they are any groups in the new file that - are not in your file then copy them over. Similarly, you should - rename any groups in <filename>/etc/group</filename> which have - the same GID but a different name to those in - <filename>/usr/src/etc/group</filename>.</para> - - <tip> - <para>If you are feeling particularly paranoid, you can check your - system to see which files are owned by the group you are - renaming or deleting.</para> - - <screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen> - - <para>will show all files owned by group - <replaceable>GID</replaceable> (which can be either a group name - or a numeric group ID).</para> - </tip> - </sect2> - - <sect2> - <title/Drop to single user mode/ - - <para>You may want to compile the system in single user mode. Apart - from the obvious benefit of making things go slightly faster, - reinstalling the system will touch a lot of important system - files, all the standard system binaries, libraries, include files - and so on. Changing these on a running system (particularly if - you have active users on their at the time) is asking for - trouble.</para> - - <para>That said, if you are confident, you can omit this - step.</para> - - <note> - <title>Version 2.2.5 and above</title> - - <para>As described in more detail below, versions 2.2.5 and above - of FreeBSD have separated the building process from the - installing process. You can therefore - <emphasis>build</emphasis> the new system in multi-user mode, - and then drop to single user mode to do the installation.</para> - </note> - - <para>As the superuser, you can execute</para> - - <screen>&prompt.root; <userinput/shutdown now/</screen> - - <para>from a running system, which will drop it to single user - mode.</para> - - <para>Alternatively, reboot the system, and at the boot prompt, - enter the <option>-s</option> flag. The system will then boot - single user. At the shell prompt you should then run:</para> - - <screen>&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>mount -u /</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> -&prompt.root; <userinput>swapon -a</userinput></screen> - - <para>This checks the filesystems, remounts <filename>/</filename> - read/write, mounts all the other UFS filesystems referenced in - <filename>/etc/fstab</filename> and then turns swapping on.</para> - </sect2> - - <sect2> - <title>Remove <filename>/usr/obj</filename></title> - - <para>As parts of the system are rebuilt they are placed in - directories which (by default) go under - <filename>/usr/obj</filename>. The directories shadow those under - <filename>/usr/src</filename>.</para> - - <para>You can speed up the <quote>make world</quote> process, and - possibly save yourself some dependency headaches by removing this - directory as well.</para> - - <para>Some files below <filename>/usr/obj</filename> will have the - immutable flag set (see &man.chflags.1; for more information) - which must be removed first.</para> - - <screen>&prompt.root; <userinput>cd /usr/obj</userinput> -&prompt.root; <userinput>chflags -R noschg *</userinput> -&prompt.root; <userinput>rm -rf *</userinput></screen> - </sect2> - - <sect2> - <title/Recompile the source and install the new system/ - - <sect3> - <title>All versions</title> - - <para>You must be in the <filename>/usr/src</filename> - directory...</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> - - <para>(unless, of course, your source code is elsewhere, in which - case change to that directory instead).</para> - - <para>To rebuild the world you use the &man.make.1; command. This - command reads instructions from the - <filename>Makefile</filename> which describes how the programs - that comprise FreeBSD should be rebuilt, the order they should - be built in, and so on.</para> - - <para>The general format of the command line you will type is as - follows:</para> - - <screen>&prompt.root; <userinput>make <option>-<replaceable/x/</option> <option>-D<replaceable>VARIABLE</replaceable></option> <replaceable>target</replaceable></userinput></screen> - - <para>In this example, <option>-<replaceable>x</replaceable></option> - is an option that you would pass to &man.make.1;. See the - &man.make.1; manual page for an example of the options you can - pass.</para> - - <para><option>-D<replaceable>VARIABLE</replaceable></option> - passes a variable to the <filename>Makefile</filename>. The - behavior of the <filename>Makefile</filename> is controlled by - these variables. These are the same variables as are set in - <filename>/etc/make.conf</filename>, and this provides another - way of setting them.</para> - - <screen>&prompt.root; <userinput>make -DNOPROFILE=true <replaceable>target</replaceable></userinput></screen> - - <para>is another way of specifying that profiled libraries should - not be built, and corresponds with the</para> - - <programlisting>NOPROFILE= true -# Avoid compiling profiled libraries</programlisting> - - <para>lines in <filename>/etc/make.conf</filename>.</para> - - <para><replaceable>target</replaceable> tells &man.make.1; what - you want to do. Each <filename>Makefile</filename> defines a - number of different <quote>targets</quote>, and your choice of - target determines what happens.</para> - - <para>Some targets are listed in the - <filename>Makefile</filename>, but are not meant for you to run. - Instead, they are used by the build process to break out the - steps necessary to rebuild the system into a number of - sub-steps.</para> - - <para>Most of the time you won't need to pass any parameters to - &man.make.1;, and so your command like will look like - this:</para> - - <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> - </sect3> - - <sect3> - <title>Saving the output</title> - - <para>It's a good idea to save the output you get from running - &man.make.1; to another file. If something goes wrong you will - have a copy of the error message, and a complete list of where - the process had got to. While this might not help you in - diagnosing what has gone wrong, it can help others if you post - your problem to one of the FreeBSD mailing lists.</para> - - <para>The easiest way to do this is to use the &man.script.1; - command, with a parameter that specifies the name of the file to - save all output to. You would do this immediately before - remaking the world, and then type <userinput>exit</userinput> - when the process has finished.</para> - - <screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput> -Script started, output file is /var/tmp/mw.out -&prompt.root; <userinput>make world</userinput> -<emphasis>… compile, compile, compile …</emphasis> -&prompt.root; <userinput>exit</userinput> -Script done, …</screen> - - <para>If you do this, <emphasis>do not</emphasis> save the output - in <filename>/tmp</filename>. This directory may be cleared - next time you reboot. A better place to store it is in - <filename>/var/tmp</filename> (as in the previous example) or - in <username>root</username>'s home directory.</para> - </sect3> - - <sect3> - <title>Version 2.2.2 and below</title> - - <para><filename>/usr/src/Makefile</filename> contains the - <maketarget>world</maketarget> target, which will rebuild the - entire system and then install it.</para> - - <para>Use it like this:</para> - - <screen>&prompt.root; <userinput>make world</userinput></screen> - </sect3> - - <sect3> - <title>Version 2.2.5 and above</title> - - <para>Beginning with version 2.2.5 of FreeBSD (actually, it was - first created on the -CURRENT branch, and then retrofitted to - -STABLE midway between 2.2.2 and 2.2.5) the - <maketarget>world</maketarget> target has been split in - two. <maketarget>buildworld</maketarget> and - <maketarget>installworld</maketarget>.</para> - - <para>As the names imply, <maketarget>buildworld</maketarget> - builds a complete new tree under <filename>/usr/obj</filename>, - and <maketarget>installworld</maketarget> installs this tree on - the current machine.</para> - - <para>This is very useful for 2 reasons. First, it allows you to do - the build safe in the knowledge that no components of your running - system will be affected. The build is <quote>self hosted</quote>. - Because of this, you can safely run - <maketarget>buildworld</maketarget> on a machine running in - multi-user mode with no fear of ill-effects. I still recommend you - run the <maketarget>installworld</maketarget> part in single user - mode though.</para> - - <para>Secondly, it allows you to use NFS mounts to upgrade - multiple machines on your network. If you have three machines, - A, B and C that you want to upgrade, run <command>make - buildworld</command> and <command>make installworld</command> on - A. B and C should then NFS mount <filename>/usr/src</filename> - and <filename>/usr/obj</filename> from A, and you can then run - <command>make installworld</command> to install the results of - the build on B and C.</para> - - <para>The <maketarget>world</maketarget> target still exists, and - you can use it exactly as shown for version 2.2.2. - <command>make world</command> runs <command>make - buildworld</command> followed by <command>make - installworld</command>.</para> - - <note> - <para>If you do the <command>make buildworld</command> and - <command>make installworld</command> commands separately, you - must pass the same parameters to &man.make.1; each - time.</para> - - <para>If you run:</para> - - <screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen> - - <para>you must install the results with:</para> - - <screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen> - - <para>otherwise it would try and install profiled libraries that - had not been built during the <command>make buildworld</command> - phase.</para> - </note> - </sect3> - - <sect3> - <title>-CURRENT and above</title> - - <para>If you are tracking -CURRENT you can also pass the - <option>-j</option> option to <command>make</command>. This lets - <command>make</command> spawn several simultaneous processes.</para> - - <para>This is most useful on true multi-CPU machines. However, since - much of the compiling process is IO bound rather than CPU bound it is - also useful on single CPU machines.</para> - - <para>On a typical single-CPU machine you would run:</para> - - <screen>&prompt.root; <userinput>make -j4 <replaceable>target</replaceable></userinput></screen> - - <para>&man.make.1; will then have up to 4 processes running at any one - time. Empirical evidence posted to the mailing lists shows this - generally gives the best performance benefit.</para> - - <para>If you have a multi-CPU machine and you are using an SMP - configured kernel try values between 6 and 10 and see how they speed - things up.</para> - - <para>Be aware that (at the time of writing) this is still - experimental, and commits to the source tree may occasionally break - this feature. If the world fails to compile using this parameter - try again without it before you report any problems.</para> - </sect3> - - <sect3> - <title>Timings</title> - - <para>Assuming everything goes well you have anywhere between an hour - and a half and a day or so to wait.</para> - - <para>As a general rule of thumb, a 200MHz P6 with more than 32MB of - RAM and reasonable SCSI disks will complete <command>make - world</command> in about an hour and a half. A 32MB P133 will - take 5 or 6 hours. Revise these figures down if your machines are - slower…</para> - </sect3> - </sect2> - - <sect2> - <title>Update files not updated by - <command>make world</command></title> - - <para>Remaking the world will not update certain directories (in - particular, <filename>/etc</filename>, <filename>/var</filename> and - <filename>/usr</filename>) with new or changed configuration files.</para> - - <para>The simplest way to update these files is to use - &man.mergemaster.8;, though it is possible to do it manually - if you would prefer to do that. We strongly recommend you - use &man.mergemaster.8;, however, and if you do then you - can skip forward to the <link linkend="update-dev">next - section</link>, since &man.mergemaster.8; is very simple to use. - You should read the manual page first, and make a backup of - <filename>/etc</filename> in case anything goes wrong.</para> - - <para>If you wish to do the update manually, - you cannot just copy over the files from - <filename>/usr/src/etc</filename> to <filename>/etc</filename> and - have it work. Some of these files must be <quote>installed</quote> - first. This is because the <filename>/usr/src/etc</filename> - directory <emphasis>is not</emphasis> a copy of what your - <filename>/etc</filename> directory should look like. In addition, - there are files that should be in <filename>/etc</filename> that are - not in <filename>/usr/src/etc</filename>.</para> - - <para>The simplest way to do this by hand is to install the files into a new - directory, and then work through them looking for differences.</para> - - <warning> - <title>Backup your existing <filename>/etc</filename></title> - - <para>Although, in theory, nothing is going to touch this directory - automatically, it is always better to be sure. So copy your - existing <filename>/etc</filename> directory somewhere safe. - Something like:</para> - - <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> - - <para><option>-R</option> does a recursive copy, <option>-p</option> - preserves times, ownerships on files and suchlike.</para> - </warning> - - <para>You need to build a dummy set of directories to install the new - <filename>/etc</filename> and other files into. I generally choose to - put this dummy directory in <filename>/var/tmp/root</filename>, and - there are a number of subdirectories required under this as - well.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> -&prompt.root; <userinput>cd /usr/src/etc</userinput> -&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen> - - <para>This will build the necessary directory structure and install the - files. A lot of the subdirectories that have been created under - <filename>/var/tmp/root</filename> are empty and should be deleted. - The simplest way to do this is to:</para> - - <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput> -&prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen> - - <para>This will remove all empty directories. (Standard error is - redirected to <filename>/dev/null</filename> to prevent the warnings - about the directories that are not empty.)</para> - - <para><filename>/var/tmp/root</filename> now contains all the files that - should be placed in appropriate locations below - <filename>/</filename>. You now have to go through each of these - files, determining how they differ with your existing files.</para> - - <para>Note that some of the files that will have been installed in - <filename>/var/tmp/root</filename> have a leading <quote/./. At the - time of writing the only files like this are shell startup files in - <filename>/var/tmp/root/</filename> and - <filename>/var/tmp/root/root/</filename>, although there may be others - (depending on when you are reading this. Make sure you use - <command/ls -a/ to catch them.</para> - - <para>The simplest way to do this is to use &man.diff.1; to compare the - two files.</para> - - <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen> - - <para>This will show you the differences between your - <filename>/etc/shells</filename> file and the new - <filename>/etc/shells</filename> file. Use these to decide whether to - merge in changes that you have made or whether to copy over your old - file.</para> - - <tip> - <title>Name the new root directory - (<filename>/var/tmp/root</filename>)with a time stamp, so you can - easily compare differences between versions</title> - - <para>Frequently remaking the world means that you have to update - <filename>/etc</filename> frequently as well, which can be a bit of - a chore.</para> - - <para>You can speed this process up by keeping a copy of the last set - of changed files that you merged into <filename>/etc</filename>. - The following procedure gives one idea of how to do this.</para> - - <procedure> - <step> - <para>Make the world as normal. When you want to update - <filename>/etc</filename> and the other directories, give the - target directory a name based on the current date. If you were - doing this on the 14th of February 1998 you could do the - following.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput> -&prompt.root; <userinput>cd /usr/src/etc</userinput> -&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \ - distrib-dirs distribution</userinput></screen> - </step> - - <step> - <para>Merge in the changes from this directory as outlined - above.</para> - - <para><emphasis>Do not</emphasis> remove the - <filename>/var/tmp/root-19980214</filename> directory when you - have finished.</para> - </step> - - <step> - <para>When you have downloaded the latest version of the source - and remade it, follow step 1. This will give you a new - directory, which might be called - <filename>/var/tmp/root-19980221</filename> (if you wait a week - between doing updates).</para> - </step> - - <step> - <para>You can now see the differences that have been made in the - intervening week using &man.diff.1; to create a recursive diff - between the two directories.</para> - - <screen>&prompt.root; <userinput>cd /var/tmp</userinput> -&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen> - - <para>Typically, this will be a much smaller set of differences - than those between - <filename>/var/tmp/root-19980221/etc</filename> and - <filename>/etc</filename>. Because the set of differences is - smaller, it is easier to migrate those changes across into your - <filename>/etc</filename> directory.</para> - </step> - - <step> - <para>You can now remove the older of the two - <filename>/var/tmp/root-*</filename> directories.</para> - - <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen> - </step> - - <step> - <para>Repeat this process every time you need to merge in changes - to <filename>/etc</filename>.</para> - </step> - </procedure> - - <para>You can use &man.date.1; to automate the generation of the - directory names.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> - </tip> - </sect2> - - <sect2 id="update-dev"> - <title>Update <filename>/dev</filename></title> - - <note> - <title>DEVFS</title> - - <para>If you are using DEVFS then this is probably unnecessary.</para> - </note> - - <para>For safety's sake, this is a multi-step process.</para> - - <procedure> - <step> - <para>Copy <filename>/var/tmp/root/dev/MAKEDEV</filename> to - <filename>/dev</filename>.</para> - - <screen>&prompt.root; <userinput>cp /var/tmp/root/dev/MAKEDEV /dev</userinput></screen> - - <para>If you used &man.mergemaster.8; to - update <filename>/etc</filename>, then your - <filename>MAKEDEV</filename> script should have been updated - already, though it can't hurt to check (with &man.diff.1;) - and copy it manually if necessary.</para> - </step> - - <step> - <para>Now, take a snapshot of your current - <filename>/dev</filename>. This snapshot needs to contain the - permissions, ownerships, major and minor numbers of each filename, - but it should not contain the time stamps. The easiest way to do - this is to use &man.awk.1; to strip out some of the - information.</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out</userinput></screen> - </step> - - <step> - <para>Remake all the devices.</para> - - <screen>&prompt.root; <userinput/sh MAKEDEV all/</screen> - </step> - - <step> - <para>Write another snapshot of the directory, this time to - <filename>/var/tmp/dev2.out</filename>. Now look through these - two files for any devices that you missed creating. There should - not be any, but it is better to be safe than sorry.</para> - - <screen>&prompt.root; <userinput>diff /var/tmp/dev.out /var/tmp/dev2.out</userinput></screen> - - <para>You are most likely to notice disk slice discrepancies which - will involve commands such as - - <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen> - - to recreate the slice entries. Your precise circumstances may - vary.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Update <filename>/stand</filename></title> - - <note> - <para>This step is included only for completeness. It can safely be - omitted.</para> - </note> - - <para>For the sake of completeness, you may want to update the files in - <filename>/stand</filename> as well. These files consist of hard - links to the <filename>/stand/sysinstall</filename> binary. This - binary should be statically linked, so that it can work when no other - filesystems (and in particular <filename>/usr</filename>) have been - mounted.</para> - - <screen>&prompt.root; <userinput>cd /usr/src/release/sysinstall</userinput> -&prompt.root; <userinput>make all install</userinput></screen> - - <note> - <title>Source older than 2 April 1998</title> - - <para>If your source code is older than 2nd April 1998, or the - <filename>Makefile</filename> version is not 1.68 or higher (for - FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X - systems) you will need to add the - <userinput>NOSHARED=yes</userinput> option, like so;</para> - - <screen>&prompt.root; <userinput>make NOSHARED=yes all install</userinput></screen> - </note> - </sect2> - - <sect2> - <title>Compile and install a new kernel</title> - - <para>To take full advantage of your new system you should recompile the - kernel. This is practically a necessity, as certain memory structures - may have changed, and programs like &man.ps.1; and &man.top.1; will - fail to work until the kernel and source code versions are the - same.</para> - - <para>Follow the handbook instructions for compiling a new kernel. If - you have previously built a custom kernel then carefully examine the - <filename>LINT</filename> config file to see if there are any new - options which you should take advantage of.</para> - - <para>A previous version of this document suggested rebooting before - rebuilding the kernel. This is wrong because:</para> - - <itemizedlist> - <listitem> - <para>Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8; - may fail. This could leave your machine unable to connect to the - network.</para> - </listitem> - - <listitem> - <para>Basic utilities like &man.mount.8; could fail, - making it impossible to mount <filename>/</filename>, - <filename>/usr</filename> and so on. This is unlikely if you are - tracking a -STABLE candidate, but more likely if you are tracking - -CURRENT during a large merge.</para> - </listitem> - - <listitem> - <para>Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X - systems and above) built as part of the <quote>world</quote> may - crash an older kernel.</para> - </listitem> - </itemizedlist> - - <para>For these reasons, it is always best to rebuild and install a - new kernel before rebooting.</para> - - <para>You should build your new kernel after you have completed - <userinput>make world</userinput> (or <userinput>make - installworld</userinput>). If you do not want to do this (perhaps - you want to confirm that the kernel builds before updating your - system) you may have problems. These may be because your - &man.config.8; command is out of date with respect to your kernel - sources.</para> - - <para>In this case you could build your kernel with the new version of &man.config.8;</para> - - <screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen> - - <para>This may not work in all cases. It is recommended that you - complete <userinput>make world</userinput> (or <userinput>make - installworld</userinput>) before compiling a new kernel.</para> - </sect2> - - <sect2> - <title/Rebooting/ - - <para>You are now done. After you have verified that everything appears - to be in the right place you can reboot the system. A simple - &man.fastboot.8; should do it.</para> - - <screen>&prompt.root; <userinput>fastboot</userinput></screen> - </sect2> - - <sect2> - <title>Finished</title> - - <para>You should now have successfully upgraded your FreeBSD system. - Congratulations.</para> - - <para>You may notice small problems due to things that you have missed. - For example, I once deleted <filename>/etc/magic</filename> as part of - the upgrade and merge to <filename>/etc</filename>, and the - <command>file</command> command stopped working. A moment's thought - meant that - - <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput> -&prompt.root; <userinput/make all install/</screen> - - was sufficient to fix that one.</para> - </sect2> - - <sect2> - <title/Questions?/ - - <qandaset> - <qandaentry> - <question> - <para>Do I need to re-make the world for every change?</para> - </question> - - <answer> - <para>There is no easy answer to this one, as it depends on the - nature of the change. For example, I have just run CVSup, and - it has shown the following files as being updated since I last - ran it;</para> - - <screen><filename>src/games/cribbage/instr.c</filename> -<filename>src/games/sail/pl_main.c</filename> -<filename>src/release/sysinstall/config.c</filename> -<filename>src/release/sysinstall/media.c</filename> -<filename>src/share/mk/bsd.port.mk</filename></screen> - - <para>There is nothing in there that I would re-make the world - for. I would go to the appropriate sub-directories and - <command>make all install</command>, and that's about it. But - if something major changed, for example - <filename>src/lib/libc/stdlib</filename> then I would either - re-make the world, or at least those parts of it that are - statically linked (as well as anything else I might have added - that is statically linked).</para> - - <para>At the end of the day, it is your call. You might be happy - re-making the world every fortnight say, and let changes - accumulate over that fortnight. Or you might want to re-make - just those things that have changed, and are confident you can - spot all the dependencies.</para> - - <para>And, of course, this all depends on how often you want to - upgrade, and whether you are tracking -STABLE or - -CURRENT.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>My compile failed with lots of signal 11 (or other signal - number) errors. What has happened?</para> - </question> - - <answer> - <para>This is normally indicative of hardware problems. - (Re)making the world is an effective way to stress test your - hardware, and will frequently throw up memory problems. These - normally manifest themselves as the compiler mysteriously dying - on receipt of strange signals.</para> - - <para>A sure indicator of this is if you can restart the make and - it dies at a different point in the process.</para> - - <para>In this instance there is little you can do except start - swapping around the components in your machine to determine - which one is failing.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I remove <filename>/usr/obj</filename> when I have - finished?</para> - </question> - - <answer> - <para>That depends on how you want to make the world on future - occasions.</para> - - <para><filename>/usr/obj</filename> contains all the object files - that were produced during the compilation phase. Normally, one - of the first steps in the <quote/make world/ process is to - remove this directory and start afresh. In this case, keeping - <filename>/usr/obj</filename> around after you have finished - makes little sense, and will free up a large chunk of disk space - (currently about 150MB).</para> - - <para>However, if you know what you are doing you can have - <quote/make world/ skip this step. This will make subsequent - builds run much faster, since most of sources will not need to - be recompiled. The flip side of this is that subtle dependency - problems can creep in, causing your build to fail in odd ways. - This frequently generates noise on the FreeBSD mailing lists, - when one person complains that their build has failed, not - realising that it is because they have tried to cut - corners.</para> - - <para>If you want to live dangerously then make the world, passing - the <makevar>NOCLEAN</makevar> definition to make, like - this:</para> - - <screen>&prompt.root; <userinput>make -DNOCLEAN world</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can interrupted builds be resumed?</para> - </question> - - <answer> - <para>This depends on how far through the process you got before - you found a problem.</para> - - <para><emphasis>In general</emphasis> (and this is not a hard and - fast rule) the <quote>make world</quote> process builds new - copies of essential tools (such as &man.gcc.1;, and - &man.make.1;>) and the system libraries. These tools and - libraries are then installed. The new tools and libraries are - then used to rebuild themselves, and are installed again. The - entire system (now including regular user programs, such as - &man.ls.1; or &man.grep.1;) is then rebuilt with the new - system files.</para> - - <para>If you are at the last state, and you know it (because you - have looked through the output that you were storing) then you - can (fairly safely) do</para> - - <screen><emphasis>… fix the problem …</emphasis> -&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make -DNOCLEAN all</userinput></screen> - - <para>This will not undo the work of the previous - <quote>make world</quote>.</para> - - <para>If you see the message - - <screen>-------------------------------------------------------------- -Building everything.. ---------------------------------------------------------------</screen> - - in the <quote>make world</quote> output then it is - probably fairly safe to do so.</para> - - <para>If you do not see that message, or you are not sure, then it - is always better to be safe than sorry, and restart the build - from scratch.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I use one machine as a <emphasis/master/ to upgrade lots - of machines (NFS)?</para> - </question> - - <answer> - <para>People often ask on the FreeBSD mailing lists whether they - can do all the compiling on one machine, and then use the - results of that compile to <command>make install</command> on to - other machines around the network.</para> - - <para>This is not something I have done, so the suggestions below - are either from other people, or deduced from the - Makefiles.</para> - - <para>The precise approach to take depends on your version of - FreeBSD</para> - - <para>You must still upgrade <filename>/etc</filename> and - <filename>/dev</filename> on the target machines after doing - this.</para> - - <para>For 2.1.7 and below, Antonio Bemfica - suggested the following approach:</para> - - <screen>Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST) -From: Antonio Bemfica <bemfica@militzer.me.tuns.ca> -To: freebsd-questions@FreeBSD.org -Message-ID: <Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca> - -Josef Karthauser asked: - -> Has anybody got a good method for upgrading machines on a network - -First make world, etc. on your main machine -Second, mount / and /usr from the remote machine: - -main_machine% mount remote_machine:/ /mnt -main_machine% mount remote_machine:/usr /mnt/usr - -Third, do a 'make install' with /mnt as the destination: - -main_machine% make install DESTDIR=/mnt - -Repeat for every other remote machine on your network. It works fine -for me. - -Antonio</screen> - - <para>This mechanism will only work (to the best of my knowledge) - if you can write to <filename>/usr/src</filename> on the NFS - server, as the <maketarget>install</maketarget> target in 2.1.7 - and below needed to do this.</para> - - <para>Midway between 2.1.7 and 2.2.0 the <quote>reinstall</quote> - target was committed. You can use the approach exactly as - outlined above for 2.1.7, but use <quote>reinstall</quote> - instead of <quote>install</quote>.</para> - - <para>This approach <emphasis>does not</emphasis> require write - access to the <filename>/usr/src</filename> directory on the NFS - server.</para> - - <para>There was a bug introduced in this target between versions - 1.68 and 1.107 of the Makefile, which meant that write access to - the NFS server <emphasis>was</emphasis> required. This bug was - fixed before version 2.2.0 of FreeBSD was released, but may be an - issue of you have an old server still running -STABLE from this - era.</para> - - <para>For version 2.2.5 and above, you can use the - <quote>buildworld</quote> and <quote>installworld</quote> - targets. Use them to build a source tree on one machine, and - then NFS mount <filename>/usr/src</filename> and - <filename>/usr/obj</filename> on the remote machine and install - it there.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How can I speed up making the world?</para> - - <itemizedlist> - <listitem> - <para>Run in single user mode.</para> - </listitem> - - <listitem> - <para>Put the <filename>/usr/src</filename> and - <filename>/usr/obj</filename> directories on separate - filesystems held on separate disks. If possible, put these - disks on separate disk controllers.</para> - </listitem> - - <listitem> - <para>Better still, put these filesystems across separate - disks using the <quote>ccd</quote> (concatenated disk - driver) device.</para> - </listitem> - - <listitem> - <para>Turn off profiling (set <quote>NOPROFILE=true</quote> in - <filename>/etc/make.conf</filename>). You almost certainly - do not need it.</para> - </listitem> - - <listitem> - <para>Also in <filename>/etc/make.conf</filename>, set - <quote>CFLAGS</quote> to something like <quote>-O - -pipe</quote>. The optimization <quote>-O2</quote> is much - slower, and the optimization difference between - <quote>-O</quote> and <quote>-O2</quote> is normally - negligible. <quote>-pipe</quote> lets the compiler use - pipes rather than temporary files for communication, which - saves disk access (at the expense of memory).</para> - </listitem> - - <listitem> - <para>Pass the <option>-j<n></option> option to make (if - you are running a sufficiently recent version of FreeBSD) to - run multiple processes in parallel. This helps regardless - of whether you have a single or a multi processor - machine.</para> - </listitem> - - <listitem><para>The filesystem holding - <filename>/usr/src</filename> can be mounted (or remounted) - with the <quote>noatime</quote> option. This stops the time - files in the filesystem were last accessed from being - written to the disk. You probably do not need this - information anyway. - - <note> - <para><quote>noatime</quote> is in version 2.2.0 and - above.</para> - </note> - - <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> - - <warning> - <para>The example assumes <filename>/usr/src</filename> is - on its own filesystem. If it is not (if it is a part of - <filename>/usr</filename> for example) then you will - need to use that filesystem mount point, and not - <filename>/usr/src</filename>.</para> - </warning> - </para> - </listitem> - - <listitem> - <para>The filesystem holding <filename>/usr/obj</filename> can - be mounted (or remounted) with the <quote>async</quote> - option. This causes disk writes to happen asynchronously. - In other words, the write completes immediately, and the - data is written to the disk a few seconds later. This - allows writes to be clustered together, and can be a - dramatic performance boost.</para> - - <warning> - <para>Keep in mind that this option makes your filesystem - more fragile. With this option there is an increased - chance that, should power fail, the filesystem will be in - an unrecoverable state when the machine restarts.</para> - - <para>If <filename>/usr/obj</filename> is the only thing on - this filesystem then it is not a problem. If you have - other, valuable data on the same filesystem then ensure - your backups are fresh before you enable this - option.</para> - </warning> - - <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> - - <warning> - <para>As above, if <filename>/usr/obj</filename> is not on - its own filesystem, replace it in the example with the - name of the appropriate mount point.</para> - </warning> - </listitem> - </itemizedlist> - </question> - </qandaentry> - </qandaset> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml deleted file mode 100644 index 5cbfa05109..0000000000 --- a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml +++ /dev/null @@ -1,883 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/disks/chapter.sgml,v 1.22 2000/07/17 07:16:57 hanai Exp $ ---> - -<chapter id="disks"> - <title>Disks</title> - - <sect1 id="disks-synopsis"> - <title>Synopsis</title> - - <para>This chapter covers how to use disks, whether physical, - memory, or networked, on FreeBSD.</para> - </sect1> - - <sect1 id="disks-bios-numbering"> - <title>BIOS Drive Numbering</title> - - <para>Before you install and configure FreeBSD on your system, there is an - important subject that you should be aware of if, especially if you have - multiple hard drives.</para> - - <para>In a PC running DOS or any of the BIOS-dependent operating systems - (WINxxx), the BIOS is able to abstract the normal disk drive order, and - the operating system goes along with the change. This allows the user - to boot from a disk drive other than the so-called <quote>primary - master</quote>. This is especially convenient for some users who have - found that the simplest and cheapest way to keep a system backup is to - buy an identical second hard drive, and perform routine copies of the - first drive to the second drive using Ghost or XCOPY. Then, if the - first drive fails, or is attacked by a virus, or is scribbled upon by an - operating system defect, he can easily recover by instructing the BIOS - to logically swap the drives. It's like switching the cables on the - drives, but without having to open the case.</para> - - <para>More expensive systems with SCSI controllers often include BIOS - extensions which allow the SCSI drives to be re-ordered in a similar - fashion for up to seven drives.</para> - - <para>A user who is accustomed to taking advantage of these features may - become surprised when the results with FreeBSD are not as expected. - FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS - drive mapping</quote>. This can lead to very perplexing situations, - especially when drives are physically identical in geometry, and have - also been made as data clones of one another.</para> - - <para>When using FreeBSD, always restore the BIOS to natural drive - numbering before installing FreeBSD, and then leave it that way. If you - need to switch drives around, then do so, but do it the hard way, and - open the case and move the jumpers and cables.</para> - - <sidebar> - <title>An illustration from the files of Bill and Fred's Exceptional - Adventures:</title> - - <para>Bill breaks-down an older Wintel box to make another FreeBSD box - for Fred. Bill installs a single SCSI drive as SCSI unit zero, and - installs FreeBSD on it.</para> - - <para>Fred begins using the system, but after several days notices that - the older SCSI drive is reporting numerous soft errors, and reports - this fact to Bill.</para> - - <para>After several more days, Bill decides it's time to address the - situation, so he grabs an identical SCSI drive from the disk drive - "archive" in the back room. An initial surface scan indicates that - this drive is functioning well, so Bill installs this drive as SCSI - unit four, and makes an image copy from drive zero to drive four. Now - that the new drive is installed and functioning nicely, Bill decides - that it's a good idea to start using it, so he uses features in the - SCSI BIOS to re-order the disk drives so that the system boots from - SCSI unit four. FreeBSD boots and runs just fine.</para> - - <para>Fred continues his work for several days, and soon Bill and Fred - decide that it's time for a new adventure -- time to upgrade to a - newer version of FreeBSD. Bill removes SCSI unit zero because it was - a bit flaky, and replaces it with another identical disk drive from - the "archive." Bill then installs the new version of FreeBSD onto the - new SCSI unit zero using Fred's magic internet FTP floppies. The - installation goes well.</para> - - <para>Fred uses the new version of FreeBSD for a few days, and certifies - that it is good enough for use in the engineering department...it's - time to copy all of his work from the old version. So Fred mounts - SCSI unit four (the latest copy of the older FreeBSD version). Fred - is dismayed to find that none of his precious work is present on SCSI - unit four.</para> - - <para>Where did the data go?</para> - - <para>When Bill made an image copy of the original SCSI unit zero onto - SCSI unit four, unit four became the "new clone," When Bill - re-ordered the SCSI BIOS so that he could boot from SCSI unit four, he - was only fooling himself. FreeBSD was still running on SCSI unit zero. - Making this kind of BIOS change will cause some or all of the Boot and - Loader code to be fetched from the selected BIOS drive, but when the - FreeBSD kernel drivers take-over, the BIOS drive numbering will be - ignored, and FreeBSD will transition back to normal drive numbering. - In the illustration at hand, the system continued to operate on the - original SCSI unit zero, and all of Fred's data was there, not on SCSI - unit four. The fact that the system appeared to be running on SCSI - unit four was simply an artifact of human expectations.</para> - - <para>We are delighted to mention that no data bytes were killed or - harmed in any way by our discovery of this phenomenon. The older SCSI - unit zero was retrieved from the bone pile, and all of Fred's work was - returned to him, (and now Bill knows that he can count as high as - zero).</para> - - <para>Although SCSI drives were used in this illustration, the concepts - apply equally to IDE drives.</para> - </sidebar> - </sect1> - - <sect1 id="disks-naming"> - <title>Disk Naming</title> - - <para>Physical drives come in two main flavors, - <acronym>IDE</acronym>, or <acronym>SCSI</acronym>; but there - are also drives backed by RAID controllers, flash memory, and so - forth. Since these behave quite differently, they have their - own drivers and devices.</para> - - <table id="disk-naming-physical-table"> - <title>Physical Disk Naming Conventions</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>Drive type</entry> - <entry>Drive device name</entry> - </row> - </thead> - <tbody> - <row> - <entry>IDE hard drives</entry> - <entry><literal>ad</literal> in 4.0-RELEASE, - <literal>wd</literal> before 4.0-RELEASE.</entry> - </row> - <row> - <entry>IDE CDROM drives</entry> - <entry><literal>acd</literal> from 3.1-RELEASE, - <literal>wcd</literal> before 4.0-RELEASE.</entry> - </row> - <row> - <entry>SCSI hard drives</entry> - <entry><literal>da</literal> from 3.0-RELEASE, - <literal>sd</literal> before 3.0-RELEASE.</entry> - </row> - <row> - <entry>SCSI CDROM drives</entry> - <entry><literal>cd</literal></entry> - </row> - <row> - <entry>Assorted non-standard CDROM drives</entry> - <entry><literal>mcd</literal> for Mitsumi CD-ROM, - <literal>scd</literal> for Sony CD-ROM, - <literal>matcd</literal> for Matsushita/Panasonic CD-ROM - </entry> - </row> - <row> - <entry>Floppy drives</entry> - <entry><literal>fd</literal></entry> - </row> - <row> - <entry>SCSI tape drives</entry> - <entry><literal>sa</literal> from 3.0-RELEASE, - <literal>st</literal> before 3.0-RELEASE.</entry> - </row> - <row> - <entry>IDE tape drives</entry> - <entry><literal>ast</literal> from 4.0-RELEASE, - <literal>wst</literal> before 4.0-RELEASE.</entry> - </row> - <row> - <entry>Flash drives</entry> - <entry><literal>fla</literal> for DiskOnChip Flash device - from 3.3-RELEASE.</entry> - </row> - <row> - <entry>RAID drives</entry> - <entry><literal>myxd</literal> for Mylex, and - <literal>amrd</literal> for AMI MegaRAID, - <literal>idad</literal> for Compaq Smart RAID. - from 4.0-RELEASE. <literal>id</literal> between - 3.2-RELEASE and 4.0-RELEASE.</entry> - </row> - </tbody> - </tgroup> - </table> - - <sect2> - <title>Slices and Partitions</title> - - <para>Physical disks usually contain - <firstterm>slices</firstterm>, unless they are - <quote>dangerously dedicated</quote>. Slice numbers follow - the device name, prefixed with an <literal>s</literal>: - <quote>da0<emphasis>s1</emphasis></quote>.</para> - - <para>Slices, <quote>dangerously dedicated</quote> physical - drives, and other drives contain - <firstterm>partitions</firstterm>, which represented as - letters from <literal>a</literal> to <literal>h</literal>. - <literal>b</literal> is reserved for swap partitions, and - <literal>c</literal> is an unused partition the size of the - entire slice or drive. This is explained in <xref - linkend="disks-adding" />.</para> - </sect2> - </sect1> - - <sect1 id="disks-mounting"> - <title>Mounting and Unmounting Filesystems</title> - - <para>The filesystem is best visualized as a tree, - rooted, as it were, at <filename>/</filename>. - <filename>/dev</filename>, <filename>/usr</filename>, and the - other directories in the root directory are branches, which may - have their own branches, such as - <filename>/usr/local</filename>, and so on.</para> - - <para>There are various reasons to house certain of these - directories on separate filesystems. <filename>/var</filename> - contains log, spool, and various types of temporary files, and - as such, may get filled up. Filling up the root filesystem - isn't a good idea, so splitting <filename>/var</filename> from - <filename>/</filename> is often a good idea.</para> - - <para>Another common reason to contain certain directory trees on - other filesystems is if they are to be housed on separate - physical disks, or are separate virtual disks, such as <link - linkend="nfs">Network File System</link> mounts, or CDROM - drives.</para> - - <sect2 id="disks-fstab"> - <title>The fstab File</title> - - <para>During the <link linkend="boot">boot process</link>, - filesystems listed in <filename>/etc/fstab</filename> are - automatically mounted (unless they are listed with - <option>noauto</option>).</para> - - <para>The <filename>/etc/fstab</filename> file contains a list - of lines of the following format:</para> - - <programlisting><replaceable>device</replaceable> <replaceable>/mount-point</replaceable> <replaceable>fstype</replaceable> <replaceable>options</replaceable> <replaceable>dumpfreq</replaceable> <replaceable>passno</replaceable></programlisting> - - <para><literal>device</literal> is a device name (which should - exist), as explained in the <link linkend="disks-naming">Disk - naming conventions</link> above.</para> - - <para><literal>mount-point</literal> is a directory (which - should exist), on which to mount the filesystem.</para> - - <para><literal>fstype</literal> is the filesystem type to pass - to &man.mount.8;. The default FreeBSD filesystem is - <literal>ufs</literal>.</para> - - <para><literal>options</literal> is either <option>rw</option> - for read-write filesystems, or <option>ro</option> for - read-only filesystems, followed by any other options that may - be needed. A common option is <option>noauto</option> for - filesystems not normally mounted during the boot sequence. - Other options in the &man.mount.8; manual page.</para> - - <para><literal>dumpfreq</literal> is the number of days the - filesystem should be dumped, and <literal>passno</literal> is - the pass number during which the filesystem is mounted during - the boot sequence.</para> - </sect2> - - <sect2 id="disks-mount"> - <title>The mount Command</title> - - <para>The &man.mount.8; command is what is ultimately used to - mount filesystems.</para> - - <para>In its most basic form, you use:</para> - - <informalexample> - <screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen> - </informalexample> - - <para>There are plenty of options, as mentioned in the - &man.mount.8; manual page, but the most common are:</para> - - <variablelist> - <title>mount options</title> - - <varlistentry> - <term><option>-a</option></term> - - <listitem> - <para>Mount all filesystems in - <filename>/etc/fstab</filename>, as modified by - <option>-t</option>, if given.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - - <listitem> - <para>Do everything but actually mount the - filesystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - - <listitem> - <para>Force the mounting the filesystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - - <listitem> - <para>Mount the filesystem read-only.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option> - <replaceable>fstype</replaceable></term> - - <listitem> - <para>Mount the given filesystem as the given filesystem - type, or mount only filesystems of the given type, if - given the <option>-a</option> option.</para> - - <para><quote>ufs</quote> is the default filesystem - type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-u</option></term> - - <listitem> - <para>Update mount options on the filesystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v</option></term> - - <listitem> - <para>Be verbose.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</option></term> - - <listitem> - <para>Mount the filesystem read-write.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <option>-o</option> takes a comma-separated list of - the options, including the following:</para> - - <variablelist> - <varlistentry> - <term>nodev</term> - - <listitem> - <para>Do not interpret special devices on the - filesystem. Useful security option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>noexec</term> - - <listitem> - <para>Do not allow execution of binaries on this - filesystem. Useful security option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>nosuid</term> - - <listitem> - <para>Do not interpret setuid or setgid flags on the - filesystem. Useful security option.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="disks-umount"> - <title>The umount Command</title> - - <para>The umount command takes, as a parameter, one of a - mountpoint, a device name, or the <option>-a</option> or - <option>-A</option> option.</para> - - <para>All forms take <option>-f</option> to force unmounting, - and <option>-v</option> for verbosity.</para> - - <para><option>-a</option> and <option>-A</option> are used to - unmount all mounted filesystems, possibly modified by the - filesystem types listed after <option>-t</option>. - <option>-A</option>, however, doesn't attempt to unmount the - root filesystem.</para> - </sect2> - </sect1> - - <sect1 id="disks-adding"> - <title>Adding Disks</title> - - <para><emphasis>Originally contributed by &a.obrien; 26 April - 1998</emphasis></para> - - <para>Lets say we want to add a new SCSI disk to a machine that currently - only has a single drive. First turn off the computer and install the - drive in the computer following the instructions of the computer, - controller, and drive manufacturer. Due the wide variations of procedures - to do this, the details are beyond the scope of this document.</para> - - <para>Login as user <username>root</username>. After you've installed the - drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new - disk was found. Continuing with our example, the newly added drive will - be <filename>da1</filename> and we want to mount it on - <filename>/1</filename> (if you are adding an IDE drive, it will - be <filename>wd1</filename> in pre-4.0 systems, or - <filename>ad1</filename> in most 4.X systems).</para> - - <para>Because FreeBSD runs on IBM-PC compatible computers, it must take into - account the PC BIOS partitions. These are different from the traditional - BSD partitions. A PC disk has up to four BIOS partition entries. If the - disk is going to be truly dedicated to FreeBSD, you can use the - <emphasis>dedicated</emphasis> mode. Otherwise, FreeBSD will have to live - with in one of the PC BIOS partitions. FreeBSD calls the PC BIOS - partitions, <emphasis>slices</emphasis> so as not to confuse them with - traditional BSD partitions. You may also use slices on a disk that is - dedicated to FreeBSD, but used in a computer that also has another - operating system installed. This is to not confuse the - <command>fdisk</command> utility of the other operating system.</para> - - <para>In the slice case the drive will be added as - <filename>/dev/da1s1e</filename>. This is read as: SCSI disk, unit number - 1 (second SCSI disk), slice 1 (PC BIOS partition 1), and - <filename>e</filename> BSD partition. In the dedicated case, the drive - will be added simply as <filename>/dev/da1e</filename>.</para> - - <sect2> - <title>Using sysinstall</title> - - <para>You may use <command>/stand/sysinstall</command> to partition and - label a new disk using its easy to use menus. Either login as user - <username>root</username> or use the <command>su</command> command. Run - <command>/stand/sysinstall</command> and enter the - <literal>Configure</literal> menu. With in the <literal>FreeBSD - Configuration Menu</literal>, scroll down and select the - <literal>Partition</literal> item. Next you should be presented with a - list of hard drives installed in your system. If you do not see - <literal>da1</literal> listed, you need to recheck your physical - installation and <command>dmesg</command> output in the file - <filename>/var/run/dmesg.boot</filename>.</para> - - <para>Select <literal>da1</literal> to enter the <literal>FDISK Partition - Editor</literal>. Choose <literal>A</literal> to use the entire disk - for FreeBSD. When asked if you want to <quote>remain cooperative with - any future possible operating systems</quote>, answer - <literal>YES</literal>. Write the changes to the disk using - <command>W</command>. Now exit the FDISK editor using - <command>q</command>. Next you will be asked about the Master Boot - Record. Since you are adding a disk to an already running system, - choose <literal>None</literal>.</para> - - <para>Next enter the <literal>Disk Label Editor</literal>. This is where - you will create the traditional BSD partitions. A disk can have up to - eight partitions, labeled a-h. A few of the partition labels have - special uses. The <literal>a</literal> partition is used for the root - partition (<filename>/</filename>). Thus only your system disk (e.g, - the disk you boot from) should have an <literal>a</literal> partition. - The <literal>b</literal> partition is used for swap partitions, and you - may have many disks with swap partitions. The <literal>c</literal> - partition addresses the entire disk in dedicated mode, or the entire - FreeBSD slice in slice mode. The other partitions are for general - use.</para> - - <para>Sysinstall's Label editor favors the <literal>e</literal> partition - for non-root, non-swap partitions. With in the Label editor, create a - single file system using <command>C</command>. When prompted if this - will be a FS (file system) or swap, choose <literal>FS</literal> and - give a mount point (e.g, <filename>/mnt</filename>). When adding a disk - in post-install mode, Sysinstall will not create entries in - <filename>/etc/fstab</filename> for you, so the mount point you specify - isn't important.</para> - - <para>You are now ready to write the new label to the disk and create a - file system on it. Do this by hitting <command>W</command>. Ignore any - errors from Sysinstall that it could not mount the new partition. Exit - the Label Editor and Sysinstall completely.</para> - - <para>The last step is to edit <filename>/etc/fstab</filename> to add an - entry for your new disk.</para> - </sect2> - - <sect2> - <title>Using Command Line Utilities</title> - - <sect3> - <title>* Using Slices</title> - - <para></para> - </sect3> - - <sect3> - <title>Dedicated</title> - - <para>If you will not be sharing the new drive with another operating - system, you may use the <literal>dedicated</literal> mode. Remember - this mode can confuse Microsoft operating systems; however, no damage - will be done by them. IBM's OS/2 however, will - <quote>appropriate</quote> any partition it finds which it doesn't - understand.</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 bs=1k count=1</userinput> -&prompt.root; <userinput>disklabel -Brw da1 auto</userinput> -&prompt.root; <userinput>disklabel -e da1</userinput> # create the `e' partition -&prompt.root; <userinput>newfs -d0 /dev/rda1e</userinput> -&prompt.root; <userinput>mkdir -p /1</userinput> -&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e -&prompt.root; <userinput>mount /1</userinput></screen> - - <para>An alternate method is:</para> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda1 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/rda1 | disklabel -BrR da1 /dev/stdin</userinput> -&prompt.root; <userinput>newfs /dev/rda1e</userinput> -&prompt.root; <userinput>mkdir -p /1</userinput> -&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e -&prompt.root; <userinput>mount /1</userinput></screen> - </sect3> - </sect2> - </sect1> - - <sect1 id="disks-virtual"> - <title>Virtual Disks: Network, Memory, and File-Based Filesystems</title> - - <para>Besides the disks you physically insert into your computer; - floppies, CDs, hard drives, and so forth, other forms of disks - are understood by FreeBSD - the <firstterm>virtual - disks</firstterm>.</para> - - <para>These include network filesystems such as the <link - linkend="nfs">Network Filesystem</link> and Coda, memory-based - filesystems such as <link linkend="disks-md">md</link> and - file-backed filesystems created by <link - linkend="disks-vnconfig">vnconfig</link>.</para> - - <sect2 id="disks-vnconfig"> - <title>vnconfig: file-backed filesystem</title> - - <para>&man.vnconfig.8; configures and enables vnode pseudo disk - devices. A <firstterm>vnode</firstterm> is a representation - of a file, and is the focus of file activity. This means that - &man.vnconfig.8; uses files to create and operate a - filesystem. One possible use is the mounting of floppy or CD - images kept in files.</para> - - <para>To mount an existing filesystem image:</para> - - <example> - <title>Using vnconfig to mount an existing filesystem - image</title> - - <screen>&prompt.root; <userinput>vnconfig vn<replaceable>0</replaceable> <replaceable>diskimage</replaceable></userinput> -&prompt.root; <userinput>mount /dev/vn<replaceable>0</replaceable>c <replaceable>/mnt</replaceable></userinput></screen> - </example> - - <para>To create a new filesystem image with vnconfig:</para> - - <example> - <title>Creating a New File-Backed Disk with vnconfig</title> - - <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput> -5120+0 records in -5120+0 records out -&prompt.root; <userinput>vnconfig -s labels -c vn<replaceable>0</replaceable> <replaceable>newimage</replaceable></userinput> -&prompt.root; <userinput>disklabel -r -w vn<replaceable>0</replaceable> auto</userinput> -&prompt.root; <userinput>newfs vn<replaceable>0</replaceable>c</userinput> -Warning: 2048 sector(s) in last cylinder unallocated -/dev/rvn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors - 5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g) -super-block backups (for fsck -b #) at: - 32 -&prompt.root; <userinput>mount /dev/vn<replaceable>0</replaceable>c <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> -Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/vn0c 4927 1 4532 0% /mnt</screen> - </example> - </sect2> - - <sect2 id="disks-md"> - <title>md: Memory Filesystem</title> - - <para>md is a simple, efficient means to do memory - filesystems.</para> - - <para>Simply take a filesystem you've prepared with, for - example, &man.vnconfig.8;, and:</para> - - <example> - <title>md memory disk</title> - - <screen>&prompt.root; <userinput>dd if=<replaceable>newimage</replaceable> of=/dev/md<replaceable>0</replaceable></userinput> -5120+0 records in -5120+0 records out -&prompt.root; <userinput>mount /dev/md<replaceable>0c</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> -Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/md0c 4927 1 4532 0% /mnt</screen> - </example> - </sect2> - </sect1> - - <sect1 id="quotas"> - <title>Disk Quotas</title> - - <para>Quotas are an optional feature of the operating system that - allow you to limit the amount of disk space and/or the number of - files a user, or members of a group, may allocate on a per-file - system basis. This is used most often on timesharing systems where - it is desirable to limit the amount of resources any one user or - group of users may allocate. This will prevent one user from - consuming all of the available disk space.</para> - - <sect2> - <title>Configuring Your System to Enable Disk Quotas</title> - - <para>Before attempting to use disk quotas it is necessary to make - sure that quotas are configured in your kernel. This is done by - adding the following line to your kernel configuration - file:</para> - - <programlisting> -options QUOTA</programlisting> - - <para>The stock <filename>GENERIC</filename> kernel does not have - this enabled by default, so you will have to configure, build and - install a custom kernel in order to use disk quotas. Please refer - to the <link linkend="kernelconfig">Configuring the FreeBSD - Kernel</link> section for more information on kernel - configuration.</para> - - <para>Next you will need to enable disk quotas in - <filename>/etc/rc.conf</filename>. This is done by adding the - line:</para> - - <programlisting> -enable_quotas=<quote>YES</quote></programlisting> - - <para>For finer control over your quota startup, there is an - additional configuration variable available. Normally on bootup, - the quota integrity of each file system is checked by the - <command>quotacheck</command> program. The - <command>quotacheck</command> facility insures that the data in - the quota database properly reflects the data on the file system. - This is a very time consuming process that will significantly - affect the time your system takes to boot. If you would like to - skip this step, a variable is made available for the - purpose:</para> - - <programlisting> -check_quotas=<quote>NO</quote></programlisting> - - <para>If you are running FreeBSD prior to 3.2-RELEASE, the - configuration is simpler, and consists of only one variable. Set - the following in your <filename>/etc/rc.conf</filename>:</para> - - <programlisting> -check_quotas=<quote>YES</quote></programlisting> - - <para>Finally you will need to edit <filename>/etc/fstab</filename> - to enable disk quotas on a per-file system basis. This is where - you can either enable user or group quotas or both for all of your - file systems.</para> - - <para>To enable per-user quotas on a file system, add the - <literal>userquota</literal> option to the options field in the - <filename>/etc/fstab</filename> entry for the file system you want - to to enable quotas on. For example:</para> - - <programlisting> -/dev/da1s2g /home ufs rw,userquota 1 2</programlisting> - - <para>Similarly, to enable group quotas, use the - <literal>groupquota</literal> option instead of the - <literal>userquota</literal> keyword. To enable both user and - group quotas, change the entry as follows:</para> - - <programlisting> -/dev/da1s2g /home ufs rw,userquota,groupquota 1 2</programlisting> - - <para>By default the quota files are stored in the root directory of - the file system with the names <filename>quota.user</filename> and - <filename>quota.group</filename> for user and group quotas - respectively. See <command>man fstab</command> for more - information. Even though that man page says that you can specify - an alternate location for the quota files, this is not recommended - because the various quota utilities do not seem to handle this - properly.</para> - - <para>At this point you should reboot your system with your new - kernel. <filename>/etc/rc</filename> will automatically run the - appropriate commands to create the initial quota files for all of - the quotas you enabled in <filename>/etc/fstab</filename>, so - there is no need to manually create any zero length quota - files.</para> - - <para>In the normal course of operations you should not be required - to run the <command>quotacheck</command>, - <command>quotaon</command>, or <command>quotaoff</command> - commands manually. However, you may want to read their man pages - just to be familiar with their operation.</para> - </sect2> - - <sect2> - <title>Setting Quota Limits</title> - - <para>Once you have configured your system to enable quotas, verify - that they really are enabled. An easy way to do this is to - run:</para> - - <screen>&prompt.root; <userinput>quota -v</userinput></screen> - - <para>You should see a one line summary of disk usage and current - quota limits for each file system that quotas are enabled - on.</para> - - <para>You are now ready to start assigning quota limits with the - <command>edquota</command> command.</para> - - <para>You have several options on how to enforce limits on the - amount of disk space a user or group may allocate, and how many - files they may create. You may limit allocations based on disk - space (block quotas) or number of files (inode quotas) or a - combination of both. Each of these limits are further broken down - into two categories; hard and soft limits.</para> - - <para>A hard limit may not be exceeded. Once a user reaches their - hard limit they may not make any further allocations on the file - system in question. For example, if the user has a hard limit of - 500 blocks on a file system and is currently using 490 blocks, the - user can only allocate an additional 10 blocks. Attempting to - allocate an additional 11 blocks will fail.</para> - - <para>Soft limits on the other hand can be exceeded for a limited - amount of time. This period of time is known as the grace period, - which is one week by default. If a user stays over his or her - soft limit longer than their grace period, the soft limit will - turn into a hard limit and no further allocations will be allowed. - When the user drops back below the soft limit, the grace period - will be reset.</para> - - <para>The following is an example of what you might see when you run - the <command>edquota</command> command. When the - <command>edquota</command> command is invoked, you are placed into - the editor specified by the <envar>EDITOR</envar> environment - variable, or in the <command>vi</command> editor if the - <envar>EDITOR</envar> variable is not set, to allow you to edit - the quota limits.</para> - - <screen>&prompt.root; <userinput>edquota -u test</userinput></screen> - - <programlisting> -Quotas for user test: -/usr: blocks in use: 65, limits (soft = 50, hard = 75) - inodes in use: 7, limits (soft = 50, hard = 60) -/usr/var: blocks in use: 0, limits (soft = 50, hard = 75) - inodes in use: 0, limits (soft = 50, hard = 60)</programlisting> - - <para>You will normally see two lines for each file system that has - quotas enabled. One line for the block limits, and one line for - inode limits. Simply change the value you want updated to modify - the quota limit. For example, to raise this users block limit - from a soft limit of 50 and a hard limit of 75 to a soft limit of - 500 and a hard limit of 600, change:</para> - - <programlisting>/usr: blocks in use: 65, limits (soft = 50, hard = 75)</programlisting> - - <para>to:</para> - - <programlisting> /usr: blocks in use: 65, limits (soft = 500, hard = 600)</programlisting> - - <para>The new quota limits will be in place when you exit the - editor.</para> - - <para>Sometimes it is desirable to set quota limits on a range of - uids. This can be done by use of the <option>-p</option> option - on the <command>edquota</command> command. First, assign the - desired quota limit to a user, and then run - <command>edquota -p protouser startuid-enduid</command>. For - example, if user <username>test</username> has the desired quota - limits, the following command can be used to duplicate those quota - limits for uids 10,000 through 19,999:</para> - - <screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen> - - <para>See <command>man edquota</command> for more detailed - information.</para> - </sect2> - - <sect2> - <title>Checking Quota Limits and Disk Usage</title> - - <para>You can use either the <command>quota</command> or the - <command>repquota</command> commands to check quota limits and - disk usage. The <command>quota</command> command can be used to - check individual user and group quotas and disk usage. Only the - super-user may examine quotas and usage for other users, or for - groups that they are not a member of. The - <command>repquota</command> command can be used to get a summary - of all quotas and disk usage for file systems with quotas - enabled.</para> - - <para>The following is some sample output from the - <command>quota -v</command> command for a user that has quota - limits on two file systems.</para> - - <programlisting> -Disk quotas for user test (uid 1002): - Filesystem blocks quota limit grace files quota limit grace - /usr 65* 50 75 5days 7 50 60 - /usr/var 0 50 75 0 50 60</programlisting> - - <para>On the <filename>/usr</filename> file system in the above - example this user is currently 15 blocks over their soft limit of - 50 blocks and has 5 days of their grace period left. Note the - asterisk <literal>*</literal> which indicates that the user is - currently over their quota limit.</para> - - <para>Normally file systems that the user is not using any disk - space on will not show up in the output from the - <command>quota</command> command, even if they have a quota limit - assigned for that file system. The <option>-v</option> option - will display those file systems, such as the - <filename>/usr/var</filename> file system in the above - example.</para> - </sect2> - - <sect2> - <title>Quotas over NFS</title> - - <para>Quotas are enforced by the quota subsystem on the NFS server. - The &man.rpc.rquotad.8; daemon makes quota information available - to the &man.quota.1; command on NFS clients, allowing users on - those machines to see their quota statistics.</para> - - <para>Enable <command>rpc.rquotad</command> in - <filename>/etc/inetd.conf</filename> like so:</para> - - <programlisting> -rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad</programlisting> - - <para>Now restart <command>inetd</command>:</para> - - <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml deleted file mode 100644 index 5a5486b998..0000000000 --- a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml +++ /dev/null @@ -1,1584 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml,v 1.51 2000/10/03 09:08:17 murray Exp $ ---> - -<appendix id="eresources"> - <title>Resources on the Internet</title> - - <para>The rapid pace of FreeBSD progress makes print media impractical as a - means of following the latest 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 <quote>technical support department</quote> of sorts, - with electronic mail and USENET news being the most effective way of - reaching that community.</para> - - <para>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.</para> - - <sect1 id="eresources-mail"> - <title>Mailing Lists</title> - - <para>Though many of the FreeBSD development members read USENET, we - cannot 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 - <literal>comp.unix.bsd.freebsd.*</literal> 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.</para> - - <para>The charters for the various lists are given at the bottom of this - document. <emphasis>Please read the charter before joining or sending - mail to any list</emphasis>. Most of our list subscribers now receive - many hundreds of FreeBSD related messages every day, and by setting down - charters and rules for proper use we are striving to keep the - signal-to-noise ratio of the lists high. To do less would see the - mailing lists ultimately fail as an effective communications medium for - the project.</para> - - <para>Archives are kept for all of the mailing lists and can be searched - using the <ulink url="http://www.FreeBSD.org/search.html">FreeBSD World - Wide Web server</ulink>. The keyword searchable archive offers an - excellent way of finding answers to frequently asked questions and - should be consulted before posting a question.</para> - - <sect2 id="eresources-summary"> - <title>List Summary</title> - - <para><emphasis>General lists:</emphasis> The following are general - lists which anyone is free (and encouraged) to join:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-advocacy</entry> - <entry>FreeBSD Evangelism</entry> - </row> - - <row> - <entry>freebsd-announce</entry> - <entry>Important events and project milestones</entry> - </row> - - <row> - <entry>freebsd-arch</entry> - <entry>Architecture and design discussions</entry> - </row> - - <row> - <entry>freebsd-bugs</entry> - <entry>Bug reports</entry> - </row> - - <row> - <entry>freebsd-chat</entry> - <entry>Non-technical items related to the FreeBSD - community</entry> - </row> - - <row> - <entry>freebsd-commit</entry> - <entry>Changes made to the FreeBSD source tree</entry> - </row> - - <row> - <entry>freebsd-config</entry> - <entry>Development of FreeBSD installation and configuration tools</entry> - </row> - - <row> - <entry>freebsd-current</entry> - <entry>Discussion concerning the use of - FreeBSD-current</entry> - </row> - - <row> - <entry>freebsd-isp</entry> - <entry>Issues for Internet Service Providers using - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-jobs</entry> - <entry>FreeBSD employment and consulting - opportunities</entry> - </row> - - <row> - <entry>freebsd-newbies</entry> - <entry>New FreeBSD users activities and discussions</entry> - </row> - - <row> - <entry>freebsd-policy</entry> - <entry>FreeBSD Core team policy decisions. Low volume, and - read-only</entry> - </row> - - <row> - <entry>freebsd-questions</entry> - <entry>User questions and technical support</entry> - </row> - - <row> - <entry>freebsd-stable</entry> - <entry>Discussion concerning the use of - FreeBSD-stable</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>Technical lists:</emphasis> The following lists are for - technical discussion. You should read the charter for each list - carefully before joining or sending mail to one as there are firm - guidelines for their use and content.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-afs</entry> - <entry>Porting AFS to FreeBSD</entry> - </row> - - <row> - <entry>freebsd-alpha</entry> - <entry>Porting FreeBSD to the Alpha</entry> - </row> - - <row> - <entry>freebsd-atm</entry> - <entry>Using ATM networking with FreeBSD</entry> - </row> - - <row> - <entry>freebsd-database</entry> - <entry>Discussing database use and development under - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-doc</entry> - <entry>Creating FreeBSD related documents</entry> - </row> - - <row> - <entry>freebsd-emulation</entry> - <entry>Emulation of other systems such as - Linux/DOS/Windows</entry> - </row> - - <row> - <entry>freebsd-fs</entry> - <entry>Filesystems</entry> - </row> - - <row> - <entry>freebsd-hackers</entry> - <entry>General technical discussion</entry> - </row> - - <row> - <entry>freebsd-hardware</entry> - <entry>General discussion of hardware for running - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-i18n</entry> - <entry>FreeBSD Internationalization</entry> - </row> - - <row> - <entry>freebsd-ia64</entry> - <entry>Porting FreeBSD to Intel's upcoming IA64 systems</entry> - </row> - - <row> - <entry>freebsd-ipfw</entry> - <entry>Technical discussion concerning the redesign of the IP - firewall code</entry> - </row> - - <row> - <entry>freebsd-isdn</entry> - <entry>ISDN developers</entry> - </row> - - <row> - <entry>freebsd-java</entry> - <entry>Java developers and people porting JDKs to - FreeBSD</entry> - </row> - - <row> - <entry>freebsd-libh</entry> - <entry>The second generation installation and package - system</entry> - </row> - - <row> - <entry>freebsd-mobile</entry> - <entry>Discussions about mobile computing</entry> - </row> - - <row> - <entry>freebsd-mozilla</entry> - <entry>Porting mozilla to FreeBSD</entry> - </row> - - <row> - <entry>freebsd-multimedia</entry> - <entry>Multimedia applications</entry> - </row> - - <row> - <entry>freebsd-new-bus</entry> - <entry>Technical discussions about bus architecture</entry> - </row> - - <row> - <entry>freebsd-net</entry> - <entry>Networking discussion and TCP/IP source code</entry> - </row> - - <row> - <entry>freebsd-platforms</entry> - <entry>Concerning ports to non-Intel architecture - platforms</entry> - </row> - - <row> - <entry>freebsd-ports</entry> - <entry>Discussion of the ports collection</entry> - </row> - - <row> - <entry>freebsd-ppc</entry> - <entry>Porting FreeBSD to the PowerPC</entry> - </row> - - <row> - <entry>freebsd-realtime</entry> - <entry>Development of realtime extensions to FreeBSD</entry> - </row> - - <row> - <entry>freebsd-scsi</entry> - <entry>The SCSI subsystem</entry> - </row> - - <row> - <entry>freebsd-security</entry> - <entry>Security issues</entry> - </row> - - <row> - <entry>freebsd-security-notifications</entry> - <entry>Security notifications</entry> - </row> - - <row> - <entry>freebsd-small</entry> - <entry>Using FreeBSD in embedded applications</entry> - </row> - - <row> - <entry>freebsd-smp</entry> - <entry>Design discussions for [A]Symmetric - MultiProcessing</entry> - </row> - - <row> - <entry>freebsd-sparc</entry> - <entry>Porting FreeBSD to Sparc systems</entry> - </row> - - <row> - <entry>freebsd-tokenring</entry> - <entry>Support Token Ring in FreeBSD</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>Limited lists:</emphasis> The following lists are for - more specialized (and demanding) audiences and are probably not of - interest to the general public. It is also a good idea to establish a - presence in the technical lists before joining one of these limited - lists so that you'll understand the communications etiquette involved.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>List</entry> - <entry>Purpose</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-core</entry> - <entry>FreeBSD core team</entry> - </row> - - <row> - <entry>freebsd-hubs</entry> - <entry>People running mirror sites (infrastructural - support)</entry> - </row> - - <row> - <entry>freebsd-install</entry> - <entry>Installation development</entry> - </row> - - <row> - <entry>freebsd-user-groups</entry> - <entry>User group coordination</entry> - </row> - - <row> - <entry>freebsd-www</entry> - <entry>Maintainers of <ulink url="http://www.FreeBSD.org">www.freebsd.org</ulink></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>Digest lists:</emphasis> Many of the above lists are - also available as digests. All new messages posted to the list are sent - out as a single e-mail each day. The lists available in digest form are:</para> - - <informaltable frame="none"> - <tgroup cols="1"> - <thead> - <row> - <entry>List</entry> - </row> - </thead> - - <tbody> - <row> - <entry>freebsd-afs-digest</entry> - </row> - - <row> - <entry>freebsd-alpha-digest</entry> - </row> - - <row> - <entry>freebsd-chat-digest</entry> - </row> - - <row> - <entry>freebsd-current-digest</entry> - </row> - - <row> - <entry>freebsd-cvs-all-digest</entry> - </row> - - <row> - <entry>freebsd-database-digest</entry> - </row> - - <row> - <entry>freebsd-hackers-digest</entry> - </row> - - <row> - <entry>freebsd-ia64-digest</entry> - </row> - - <row> - <entry>freebsd-isdn-digest</entry> - </row> - - <row> - <entry>freebsd-java-digest</entry> - </row> - - <row> - <entry>freebsd-questions-digest</entry> - </row> - - <row> - <entry>freebsd-security-digest</entry> - </row> - - <row> - <entry>freebsd-sparc-digest</entry> - </row> - - <row> - <entry>freebsd-stable-digest</entry> - </row> - - <row> - <entry>freebsd-test-digest</entry> - </row> - - </tbody> - </tgroup> - </informaltable> - - <para><emphasis>CVS lists:</emphasis> The following lists are for people - interested in seeing the log messages for changes to various areas of - the source tree. They are <emphasis>Read-Only</emphasis> lists and - should not have mail sent to them.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>List</entry> - <entry>Source area</entry> - <entry>Area Description (source for)</entry> - </row> - </thead> - - <tbody> - <row> - <entry>cvs-all</entry> - <entry>/usr/src</entry> - <entry>All changes to the tree (superset)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2 id="eresources-subscribe"> - <title>How to Subscribe</title> - - <para>All mailing lists live on <hostid - role="fqdn">FreeBSD.org</hostid>, so to post to a given list you - simply mail to - <<replaceable>listname</replaceable>@FreeBSD.org>. It will then - be redistributed to mailing list members world-wide.</para> - - <para>To subscribe to a list, send mail to &a.majordomo; and include - - <programlisting> -subscribe <listname> [<optional address>]</programlisting> - - in the body of your message. For example, to subscribe yourself to - <literal>freebsd-announce</literal>, you'd do:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -subscribe freebsd-announce -^D</screen> - - <para>If you want to subscribe yourself under a different name, or - submit a subscription request for a local mailing list (this is more - efficient if you have several interested parties at one site, and - highly appreciated by us!), you would do something like:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -subscribe freebsd-announce local-announce@somesite.com -^D</screen> - - <para>Finally, it is also possible to unsubscribe yourself from a list, - get a list of other list members or see the list of mailing lists - again by sending other types of control messages to majordomo. For a - complete list of available commands, do this:</para> - - <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput> -help -^D</screen> - - <para>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 important announcements then it is suggested that - you join freebsd-announce, which is intended only for infrequent - traffic.</para> - </sect2> - - <sect2 id="eresources-charters"> - <title>List Charters</title> - - <para><emphasis>All</emphasis> FreeBSD mailing lists have certain basic - rules which must be adhered to by anyone using them. Failure to comply - with these guidelines will result in two (2) written warnings from the - FreeBSD Postmaster <email>postmaster@FreeBSD.org</email>, after which, - on a third offense, the poster will removed from all FreeBSD mailing - lists and filtered from further posting to them. We regret that such - rules and measures are necessary at all, but today's Internet is a - pretty harsh environment, it would seem, and many fail to appreciate - just how fragile some of its mechanisms are.</para> - - <para>Rules of the road:</para> - - <itemizedlist> - <listitem> - <para>The topic of any posting should adhere to the basic charter of - the list it is posted to, e.g. if the list is about technical - issues then your posting should contain technical discussion. - Ongoing irrelevant chatter or flaming only detracts from the value - of the mailing list for everyone on it and will not be tolerated. - For free-form discussion on no particular topic, the freebsd-chat - <email>freebsd-chat@FreeBSD.org</email> mailing list is freely - available and should be used instead.</para> - </listitem> - - <listitem> - <para>No posting should be made to more than 2 mailing lists, and - only to 2 when a clear and obvious need to post to both lists - exists. For most lists, there is already a great deal of - subscriber overlap and except for the most esoteric mixes (say - "-stable & -scsi"), there really is no reason to post to more - than one list at a time. If a message is sent to you in such a - way that multiple mailing lists appear on the Cc line then the Cc - line should also be trimmed before sending it out again. - <emphasis>You are <emphasis>still</emphasis> responsible for your - own cross-postings, no matter who the originator might have - been.</emphasis></para> - </listitem> - - <listitem> - <para>Personal attacks and profanity (in the context of an argument) - are not allowed, and that includes users and developers alike. - Gross breaches of netiquette, like excerpting or reposting private - mail when permission to do so was not and would not be - forthcoming, are frowned upon but not specifically enforced. - <emphasis>However</emphasis>, there are also very few cases where - such content would fit within the charter of a list and it would - therefore probably rate a warning (or ban) on that basis - alone.</para> - </listitem> - - <listitem> - <para>Advertising of non-FreeBSD related products or services is - strictly prohibited and will result in an immediate ban if it is - clear that the offender is advertising by spam.</para> - </listitem> - </itemizedlist> - - <para><emphasis>Individual list charters:</emphasis></para> - - <variablelist> - <varlistentry> - <term>FREEBSD-AFS</term> - - <listitem> - <para><emphasis>Andrew File System</emphasis></para> - - <para>This list is for discussion on porting and using AFS from - CMU/Transarc</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ANNOUNCE</term> - - <listitem> - <para><emphasis>Important events / milestones</emphasis></para> - - <para>This is the mailing list for people interested only in - occasional announcements of significant FreeBSD events. This - includes announcements about snapshots and other releases. It - contains announcements of new FreeBSD capabilities. It may - contain calls for volunteers etc. This is a low volume, strictly - moderated mailing list.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ARCH</term> - - <listitem> - <para><emphasis>Architecture and design - discussions</emphasis></para> - - <para>This is a moderated list for discussion of FreeBSD - architecture. Messages will mostly be kept technical in nature, - with (rare) exceptions for other messages the moderator deems - need to reach all the subscribers of the list. Examples of - suitable topics;</para> - - <itemizedlist> - <listitem> - <para>How to re-vamp the build system to have several - customized builds running at the same time.</para> - </listitem> - - <listitem> - <para>What needs to be fixed with VFS to make Heidemann layers - work.</para> - </listitem> - - <listitem> - <para>How do we change the device driver interface to be able - to use the ame drivers cleanly on many buses and - architectures?</para> - </listitem> - - <listitem> - <para>How do I write a network driver?</para> - </listitem> - </itemizedlist> - - <para>The moderator reserves the right to do minor editing - (spell-checking, grammar correction, trimming) of messages that - are posted to the list. The volume of the list will be kept - low, which may involve having to delay topics until an active - discussion has been resolved.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-BUGS</term> - - <listitem> - <para><emphasis>Bug reports</emphasis></para> - - <para>This is the mailing list for reporting bugs in FreeBSD - Whenever possible, bugs should be submitted using the - &man.send-pr.1; - command or the <ulink - url="http://www.FreeBSD.org/send-pr.html">WEB - interface</ulink> to it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CHAT</term> - - <listitem> - <para><emphasis>Non technical items related to the FreeBSD - community</emphasis></para> - - <para>This list contains the overflow from the other lists about - non-technical, social information. It includes discussion about - 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 parties, weddings, births, new jobs, etc) can be made - to the technical lists, but the follow ups should be directed to - this -chat list.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CORE</term> - - <listitem> - <para><emphasis>FreeBSD core team</emphasis></para> - - <para>This is an internal mailing list for use by the core - members. Messages can be sent to it when a serious - FreeBSD-related matter requires arbitration or high-level - scrutiny.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CURRENT</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-current</emphasis></para> - - <para>This is the mailing list for users of freebsd-current. It - includes warnings about new features coming out in -current that - will affect the users, and instructions on steps that must be - taken to remain -current. Anyone running <quote>current</quote> - must subscribe to this list. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-CURRENT-DIGEST</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-current</emphasis></para> - - <para>This is the digest version of the 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. This list is - <emphasis>Read-Only</emphasis> and should not be posted - to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-DOC</term> - - <listitem> - <para><emphasis>Documentation project</emphasis></para> - - <para>This mailing list is for the discussion of issues and - projects related to the creation of documentation for FreeBSD. - The members of this mailing list are collectively referred to as - <quote>The FreeBSD Documentation Project</quote>. It is an open - list; feel free to join and contribute!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-FS</term> - - <listitem> - <para><emphasis>Filesystems</emphasis></para> - - <para>Discussions concerning FreeBSD filesystems. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-IPFW</term> - - <listitem> - <para>IP Firewall</para> - - <para>This is the forum for technical discussions concerning the - redesign of the IP firewall code in FreeBSD. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-IA64</term> - - <listitem> - <para><emphasis>Porting FreeBSD to IA64</emphasis></para> - - <para>This is a technical mailing list for individuals - actively working on porting FreeBSD to the IA-64 platform - from Intel, to bring up problems or discuss alternative - solutions. Individuals interested in following the - technical discussion are also welcome.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ISDN</term> - - <listitem> - <para><emphasis>ISDN Communications</emphasis></para> - - <para>This is the mailing list for people discussing the - development of ISDN support for FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-JAVA</term> - - <listitem> - <para><emphasis>Java Development</emphasis></para> - - <para>This is the mailing list for people discussing the - development of significant Java applications for FreeBSD and the - porting and maintenance of JDKs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HACKERS</term> - - <listitem> - <para><emphasis>Technical discussions</emphasis></para> - - <para>This is a forum for technical discussions related to - FreeBSD. This is the primary technical mailing list. It is for - individuals actively working on FreeBSD, to bring up problems or - discuss alternative solutions. Individuals interested in - following the technical discussion are also welcome. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HACKERS-DIGEST</term> - - <listitem> - <para><emphasis>Technical discussions</emphasis></para> - - <para>This is the digest version of the freebsd-hackers mailing - list. The digest consists of all messages sent to - freebsd-hackers bundled together and mailed out as a single - message. The average digest size is about 40kB. This list is - <emphasis>Read-Only</emphasis> and should not be posted - to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HARDWARE</term> - - <listitem> - <para><emphasis>General discussion of FreeBSD - hardware</emphasis></para> - - <para>General discussion about the types of hardware that FreeBSD - runs on, various problems and suggestions concerning what to buy - or avoid.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-HUBS</term> - - <listitem> - <para><emphasis>Mirror sites</emphasis></para> - - <para>Announcements and discussion for people who run FreeBSD - mirror sites.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-INSTALL</term> - - <listitem> - <para><emphasis>Installation discussion</emphasis></para> - - <para>This mailing list is for discussing FreeBSD installation - development for the future releases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-ISP</term> - - <listitem> - <para><emphasis>Issues for Internet Service - Providers</emphasis></para> - - <para>This mailing list is for discussing topics relevant to - Internet Service Providers (ISPs) using FreeBSD. This is a - technical mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-NEWBIES</term> - - <listitem> - <para><emphasis>Newbies activities discussion</emphasis></para> - - <para>We cover any of the activities of newbies that are not - already dealt with elsewhere, including: independent learning - and problem solving techniques, finding and using resources and - asking for help elsewhere, how to use mailing lists and which - lists to use, general chat, making mistakes, boasting, sharing - ideas, stories, moral (but not technical) support, and taking an - active part in the FreeBSD community. We take our problems and - support questions to freebsd-questions, and use freebsd-newbies - to meet others who are doing the same things that we do as - newbies.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-PLATFORMS</term> - - <listitem> - <para><emphasis>Porting to Non-Intel platforms</emphasis></para> - - <para>Cross-platform FreeBSD issues, general discussion and - proposals for non-Intel FreeBSD ports. This is a technical - mailing list for which strictly technical content is - expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-POLICY</term> - - <listitem> - <para>Core team policy decisions</para> - - <para>This is a low volume, read-only mailing list for FreeBSD - Core Team Policy decisions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-PORTS</term> - - <listitem> - <para><emphasis>Discussion of - <quote>ports</quote></emphasis></para> - - <para>Discussions concerning FreeBSD's <quote>ports - collection</quote> (<filename>/usr/ports</filename>), proposed - ports, modifications to ports collection infrastructure and - general coordination efforts. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-QUESTIONS</term> - - <listitem> - <para><emphasis>User questions</emphasis></para> - - <para>This is the mailing list for questions about FreeBSD. You - should not send <quote>how to</quote> questions to the technical - lists unless you consider the question to be pretty - technical.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-QUESTIONS-DIGEST</term> - - <listitem> - <para><emphasis>User questions</emphasis></para> - - <para>This is the digest version of the freebsd-questions mailing - list. The digest consists of all messages sent to - freebsd-questions bundled together and mailed out as a single - message. The average digest size is about 40kB.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SCSI</term> - - <listitem> - <para><emphasis>SCSI subsystem</emphasis></para> - - <para>This is the mailing list for people working on the scsi - subsystem for FreeBSD. This is a technical mailing list for - which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SECURITY</term> - - <listitem> - <para><emphasis>Security issues</emphasis></para> - - <para>FreeBSD computer security issues (DES, Kerberos, known - security holes and fixes, etc). This is a technical mailing - list for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SECURITY-NOTIFICATIONS</term> - - <listitem> - <para><emphasis>Security Notifications</emphasis> - Notifications of FreeBSD security problems and fixes. This is - not a discussion list. The discussion list is - FreeBSD-security.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-SMALL</term> - - <listitem> - <para>This list discusses topics related to unusually small and - embedded FreeBSD installations. This is a technical mailing - list for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-STABLE</term> - - <listitem> - <para><emphasis>Discussions about the use of - FreeBSD-stable</emphasis></para> - - <para>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 <quote>stable</quote> - should subscribe to this list. This is a technical mailing list - for which strictly technical content is expected.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FREEBSD-USER-GROUPS</term> - - <listitem> - <para><emphasis>User Group Coordination List</emphasis></para> - - <para>This is the mailing list for the coordinators from each of - the local area Users Groups to discuss matters with each other - and a designated individual from the Core Team. This mail list - should be limited to meeting synopsis and coordination of - projects that span User Groups.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="eresources-news"> - <title>Usenet Newsgroups</title> - - <para>In addition to two FreeBSD specific newsgroups, there are many - others in which FreeBSD is discussed or are otherwise relevant to - FreeBSD users. <ulink - url="http://minnie.cs.adfa.edu.au/BSD-info/bsdnews_search.html">Keyword - searchable archives</ulink> are available for some of these newsgroups - from courtesy of Warren Toomey <email>wkt@cs.adfa.edu.au</email>.</para> - - <sect2> - <title>BSD Specific Newsgroups</title> - - <itemizedlist> - <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Other Unix Newsgroups of Interest</title> - - <itemizedlist> - <listitem> - <para><ulink url="news:comp.unix">comp.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.questions">comp.unix.questions</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.admin">comp.unix.admin</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.programmer">comp.unix.programmer</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.shell">comp.unix.shell</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.security.unix">comp.security.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.sources.unix">comp.sources.unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.misc">comp.unix.misc</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.bugs.4bsd">comp.bugs.4bsd</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.bugs.4bsd.ucb-fixes">comp.bugs.4bsd.ucb-fixes</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.unix.bsd">comp.unix.bsd</ulink></para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>X Window System</title> - - <itemizedlist> - <listitem> - <para><ulink - url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x">comp.windows.x</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="eresources-web"> - <title>World Wide Web Servers</title> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink> - — Central Server.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.au.FreeBSD.org/">http://www.au.FreeBSD.org/</ulink> — Australia/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.au.FreeBSD.org/">http://www2.au.FreeBSD.org/</ulink> — Australia/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.au.FreeBSD.org/">http://www3.au.FreeBSD.org/</ulink> — Australia/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://freebsd.itworks.com.au/">http://freebsd.itworks.com.au/</ulink> — Australia/4.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.br.FreeBSD.org/www.freebsd.org/">http://www.br.FreeBSD.org/www.freebsd.org/</ulink> — Brazil/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.br.FreeBSD.org/www.freebsd.org/">http://www2.br.FreeBSD.org/www.freebsd.org/</ulink> — Brazil/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.br.FreeBSD.org/">http://www3.br.FreeBSD.org/</ulink> — Brazil/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.bg.FreeBSD.org/">http://www.bg.FreeBSD.org/</ulink> — Bulgaria.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ca.FreeBSD.org/">http://www.ca.FreeBSD.org/</ulink> — Canada/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.ca.FreeBSD.org/">http://www2.ca.FreeBSD.org/</ulink> — Canada/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.ca.FreeBSD.org/">http://www3.ca.FreeBSD.org/</ulink> — Canada/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.cn.FreeBSD.org/">http://www.cn.FreeBSD.org/</ulink> — China.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.cz.FreeBSD.org/">http://www.cz.FreeBSD.org/</ulink> — Czech Republic/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.cz.FreeBSD.org/">http://www2.cz.FreeBSD.org/</ulink> — Czech Republic/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.dk.FreeBSD.org/">http://www.dk.FreeBSD.org/</ulink> — Denmark.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ee.FreeBSD.org/">http://www.ee.FreeBSD.org/</ulink> — Estonia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.fi.FreeBSD.org/">http://www.fi.FreeBSD.org/</ulink> — Finland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.fr.FreeBSD.org/">http://www.fr.FreeBSD.org/</ulink> — France.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.de.FreeBSD.org/">http://www.de.FreeBSD.org/</ulink> — Germany/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www1.de.FreeBSD.org/">http://www1.de.FreeBSD.org/</ulink> — Germany/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.de.FreeBSD.org/">http://www2.de.FreeBSD.org/</ulink> — Germany/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.gr.FreeBSD.org/">http://www.gr.FreeBSD.org/</ulink> — Greece.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.hu.FreeBSD.org/">http://www.hu.FreeBSD.org/</ulink> — Hungary.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.is.FreeBSD.org/">http://www.is.FreeBSD.org/</ulink> — Iceland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ie.FreeBSD.org/">http://www.ie.FreeBSD.org/</ulink> — Ireland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.jp.FreeBSD.org/www.FreeBSD.org/">http://www.jp.FreeBSD.org/www.FreeBSD.org/</ulink> — Japan.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink> — Korea/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.kr.FreeBSD.org/">http://www2.kr.FreeBSD.org/</ulink> — Korea/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.lv.FreeBSD.org/">http://www.lv.FreeBSD.org/</ulink> — Latvia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://rama.asiapac.net/freebsd/">http://rama.asiapac.net/freebsd/</ulink> — Malaysia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.nl.FreeBSD.org/">http://www.nl.FreeBSD.org/</ulink> — Netherlands/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.nl.FreeBSD.org/">http://www2.nl.FreeBSD.org/</ulink> — Netherlands/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.no.FreeBSD.org/">http://www.no.FreeBSD.org/</ulink> — Norway.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.nz.FreeBSD.org/">http://www.nz.FreeBSD.org/</ulink> — New Zealand.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.pl.FreeBSD.org/">http://www.pl.FreeBSD.org/</ulink> — Poland/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.pl.FreeBSD.org/">http://www2.pl.FreeBSD.org/</ulink> — Poland/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.pt.FreeBSD.org/">http://www.pt.FreeBSD.org/</ulink> — Portugal/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.pt.FreeBSD.org/">http://www2.pt.FreeBSD.org/</ulink> — Portugal/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.pt.FreeBSD.org/">http://www3.pt.FreeBSD.org/</ulink> — Portugal/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ro.FreeBSD.org/">http://www.ro.FreeBSD.org/</ulink> — Romania.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ru.FreeBSD.org/">http://www.ru.FreeBSD.org/</ulink> — Russia/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.ru.FreeBSD.org/">http://www2.ru.FreeBSD.org/</ulink> — Russia/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www3.ru.FreeBSD.org/">http://www3.ru.FreeBSD.org/</ulink> — Russia/3.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www4.ru.FreeBSD.org/">http://www4.ru.FreeBSD.org/</ulink> — Russia/4.</para> - </listitem> - - <listitem> - <para><ulink - url="http://freebsd.s1web.com/">http://freebsd.s1web.com/</ulink> — Singapore.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.sk.FreeBSD.org/">http://www.sk.FreeBSD.org/</ulink> — Slovak Republic.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.si.FreeBSD.org/">http://www.si.FreeBSD.org/</ulink> — Slovenia.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.es.FreeBSD.org/">http://www.es.FreeBSD.org/</ulink> — Spain.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.za.FreeBSD.org/">http://www.za.FreeBSD.org/</ulink> — South Africa/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.za.FreeBSD.org/">http://www2.za.FreeBSD.org/</ulink> — South Africa/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.se.FreeBSD.org/">http://www.se.FreeBSD.org/</ulink> — Sweden.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ch.FreeBSD.org/">http://www.ch.FreeBSD.org/</ulink> — Switzerland.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.tw.FreeBSD.org/www.freebsd.org/data/">http://www.tw.FreeBSD.org/www.freebsd.org/data/</ulink> — Taiwan.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.tr.FreeBSD.org/">http://www.tr.FreeBSD.org/</ulink> — Turkey.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.ua.FreeBSD.org/www.freebsd.org/">http://www.ua.FreeBSD.org/www.freebsd.org/</ulink> — Ukraine/1.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.ua.FreeBSD.org/">http://www2.ua.FreeBSD.org/</ulink> — Ukraine/2.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www4.ua.FreeBSD.org/">http://www4.ua.FreeBSD.org/</ulink> — Ukraine/Crimea.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.uk.FreeBSD.org/">http://www.uk.FreeBSD.org/</ulink> — United Kingdom.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www6.FreeBSD.org/">http://www6.FreeBSD.org/</ulink> — USA/Oregon.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www2.FreeBSD.org/">http://www2.FreeBSD.org/</ulink> — USA/Texas.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="eresources-email"> - <title>Email Addresses</title> - - <para>The following user groups provide FreeBSD related email addresses - for their members. The listed administrator reserves the right to - revoke the address if it is abused in any way.</para> - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Domain</entry> - <entry>Facilities</entry> - <entry>User Group</entry> - <entry>Administrator</entry> - </row> - </thead> - - <tbody> - <row> - <entry>ukug.uk.FreeBSD.org</entry> - <entry>Forwarding only</entry> - <entry><email>freebsd-users@uk.FreeBSD.org</email></entry> - <entry>Lee Johnston - <email>lee@uk.FreeBSD.org</email></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 id="eresources-shell"> - <title>Shell Accounts</title> - - <para>The following user groups provide shell accounts for people who are - actively supporting the FreeBSD project. The listed administrator - reserves the right to cancel the account if it is abused in any - way.</para> - - <informaltable> - <tgroup cols="4"> - <thead> - <row> - <entry>Host</entry> - <entry>Access</entry> - <entry>Facilities</entry> - <entry>Administrator</entry> - </row> - </thead> - - <tbody> - <row> - <entry>storm.uk.FreeBSD.org</entry> - <entry>SSH only</entry> - <entry>Read-only cvs, personal web space, email</entry> - <entry>&a.brian</entry> - </row> - - <row> - <entry>dogma.freebsd-uk.eu.org</entry> - <entry>Telnet/FTP/SSH</entry> - <entry>E-Mail, Web space, Anonymous FTP</entry> - <entry>Lee Johnston - <email>lee@uk.FreeBSD.org</email></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml b/en_US.ISO8859-1/books/handbook/hw/chapter.sgml deleted file mode 100644 index 6d6a9b8157..0000000000 --- a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml +++ /dev/null @@ -1,5872 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/hw/chapter.sgml,v 1.34 2000/07/13 21:03:21 marko Exp $ ---> - -<appendix id="hw"> - <title>PC Hardware compatibility</title> - - <para>Issues of hardware compatibility are among the most troublesome in the - computer industry today and FreeBSD is by no means immune to trouble. In - this respect, FreeBSD's advantage of being able to run on inexpensive - commodity PC hardware is also its liability when it comes to support for - the amazing variety of components on the market. While it would be - impossible to provide a exhaustive listing of hardware that FreeBSD - supports, this section serves as a catalog of the device drivers included - with FreeBSD and the hardware each drivers supports. Where possible and - appropriate, notes about specific products are included. You may also - want to refer to <link linkend="kernelconfig-config">the kernel - configuration file</link> section in this handbook for a list of - supported devices.</para> - - <para>As FreeBSD is a volunteer project without a funded testing department, - we depend on you, the user, for much of the information contained in this - catalog. If you have direct experience of hardware that does or does not - work with FreeBSD, please let us know by sending e-mail to the &a.doc;. - Questions about supported hardware should be directed to the &a.questions; - (see <link linkend="eresources-mail">Mailing Lists</link> 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.</para> - - <sect1> - <title>Resources on the Internet</title> - - <para>The following links have proven useful in selecting hardware. Though - some of what you see won't necessarily be specific (or even applicable) - to FreeBSD, most of the hardware information out there is OS - independent. Please check with the FreeBSD hardware guide to make sure - that your chosen configuration is supported before making any - purchases.</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.tomshardware.com/">The Pentium Systems - Hardware Performance Guide</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="hw-configs"> - <title>Sample Configurations</title> - - <para>The following list of sample hardware configurations by no means - constitutes an endorsement of a given hardware vendor or product by - <emphasis>The FreeBSD Project</emphasis>. 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.</para> - - <sect2 id="hw-jordans-picks"> - <title>Jordan's Picks</title> - - <para>I have had fairly good luck building workstation and server - configurations with the following components. I can't guarantee that - you will too, nor that any of the companies here will remain - <quote>best buys</quote> 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.</para> - - <sect3 id="hw-mb"> - <title>Motherboards</title> - - <para>For Pentium Pro (P6) systems, I'm quite fond of the <ulink - url="http://www.tyan.com/html/products.html">Tyan</ulink> S1668 - dual-processor motherboard as well as the Intel PR440FX motherboard - with on-board SCSI WIDE and 100/10MB Intel EtherExpress NIC. You - can build a dandy little single or dual processor system (which is - supported in FreeBSD 3.0) for very little cost now that the Pentium - Pro 180/256K chips have fallen so greatly in price, but no telling - how much longer this will last.</para> - - <para>For the Pentium II, I'm rather partial to the <ulink - url="http://www.asus.com.tw/">ASUS</ulink> <ulink - url="http://www.asus.com.tw/Products/Motherboard/Pentiumpro/P2l97-s/index.html">P2l97-S</ulink> - motherboard with the on-board Adaptec SCSI WIDE controller.</para> - - <para>For Pentium machines, the ASUS <ulink - url="http://www.asus.com.tw/Products/Motherboard/Pentium/P55tp4/index.html">P55T2P4</ulink> - motherboard appears to be a good choice for mid-to-high range - Pentium server and workstation systems.</para> - - <para>Those wishing to build more fault-tolerant systems should also - be sure to use Parity memory or, for truly 24/7 applications, ECC - memory.</para> - - <note> - <para>ECC memory does involve a slight performance trade-off (which - may or may not be noticeable depending on your application) but - buys you significantly increased fault-tolerance to memory - errors.</para> - </note> - </sect3> - - <sect3> - <title>Disk Controllers</title> - - <para>This one is a bit trickier, and while I used to recommend the - <ulink url="http://www.buslogic.com/">Buslogic</ulink> controllers - unilaterally for everything from ISA to PCI, now I tend to lean - towards the <ulink url="http://www.adaptec.com/">Adaptec</ulink> - 1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940UW for - PCI.</para> - - <para>The NCR/Symbios cards for PCI have also worked well for me, - though you need to make sure that your motherboard supports the - BIOS-less model if you're using one of those (if your card has - nothing which looks even vaguely like a ROM chip on it, you've - probably got one which expects its BIOS to be on your - motherboard).</para> - - <para>If you should find that you need more than one SCSI controller - in a PCI machine, you may wish to consider conserving your scarce - PCI bus resources by buying the Adaptec 3940 card, which puts two - SCSI controllers (and internal busses) in a single slot.</para> - - <note> - <para>There are two types of 3940 on the market—the older - model with AIC 7880 chips on it, and the newer one with AIC 7895 - chips. The newer model requires <ulink - url="http://www.FreeBSD.org/pub/FreeBSD/development/cam/">CAM</ulink> - support which is not yet part of FreeBSD—you have to add it, - or install from one of the CAM binary snapshot release.</para> - </note> - </sect3> - - <sect3 id="hw-disks"> - <title>Disk drives</title> - - <para>In this particular game of Russian roulette, I'll make few - specific recommendations except to say <quote>SCSI over IDE whenever - you can afford it.</quote> 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! For a - serious server configuration, there's not even any - argument—use SCSI equipment and good cables.</para> - </sect3> - - <sect3 id="hw-jordans-picks-cdrom"> - <title>CDROM drives</title> - - <para>My SCSI preferences extend to SCSI CDROM drives as well, and - while the <ulink url="http://www.toshiba.com/">Toshiba</ulink> drives - have always been favorites of mine (in whatever speed is hot that - week), I'm still fond of my good old <ulink - url="http://www.plextor.com/">Plextor</ulink> PX-12CS drive. It's - only a 12 speed, but it's offered excellent performance and - reliability.</para> - - <para>Generally speaking, most SCSI CDROM drives I've seen have been - of pretty solid construction and you probably won't go wrong with an - HP or NEC SCSI CDROM drive either. SCSI CDROM prices also appear to - have dropped considerably in the last few months and are now quite - competitive with IDE CDROMs while remaining a technically superior - solution. I now see no reason whatsoever to settle for an IDE CDROM - drive if given a choice between the two.</para> - </sect3> - - <sect3 id="hw-worm"> - <title>CD Recordable (WORM) drives</title> - - <para>At the time of this writing, FreeBSD supports 3 types of CDR - drives (though I believe they all ultimately come from Phillips - anyway): The Phillips CDD 522 (Acts like a Plasmon), the PLASMON - RF4100 and the HP 6020i. I myself use the HP 6020i for burning - CDROMs (in 2.2 and later releases—it does not work with - earlier releases of the SCSI code) and it works very well. See - <ulink - url="file:/usr/share/examples/worm">/usr/share/examples/worm</ulink> - on your 2.2 system for example scripts used to created ISO9660 - filesystem images (with RockRidge extensions) and burn them onto an - HP6020i CDR.</para> - </sect3> - - <sect3 id="hw-tape"> - <title>Tape drives</title> - - <para>I've had pretty good luck with both <ulink - url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">8mm - drives</ulink> from <ulink - url="http://www.exabyte.com/">Exabyte</ulink> and <ulink - url="http://www-dmo.external.hp.com:80/tape/_cpb0001.htm">4mm - (DAT)</ulink> drives from <ulink - url="http://www.hp.com/">HP</ulink>.</para> - - <para>For backup purposes, I'd have to give the higher recommendation - to the Exabyte due to the more robust nature (and higher storage - capacity) of 8mm tape.</para> - </sect3> - - <sect3 id="hw-video"> - <title>Video Cards</title> - - <para>If you can also afford to buy a commercial X server for - US$99 from <ulink url="http://www.xig.com/">Xi Graphics, Inc. - (formerly X Inside, Inc)</ulink> then I can heartily recommend the - <ulink url="http://www.matrox.com/">Matrox</ulink> <ulink - url="http://www.matrox.com/mgaweb/brochure.htm">Millenium - II</ulink> card. Note that support for this card is also - excellent with the <ulink - url="http://www.xfree86.org/">XFree86</ulink> server, which is now - at version 3.3.2.</para> - - <para>You also certainly can't go wrong with one of <ulink - url="http://www.nine.com/">Number 9's</ulink> cards — their - S3 Vision 868 and 968 based cards (the 9FX series) also being quite - fast and very well supported by XFree86's S3 server. You can also - pick up their Revolution 3D cards very cheaply these days, - especially if you require a lot of video memory.</para> - </sect3> - - <sect3 id="hw-monitors"> - <title>Monitors</title> - - <para>I have had very good luck with the <ulink - url="http://cons3.sel.sony.com/SEL/ccpg/display/ms17se2.html">Sony - Multiscan 17seII monitors</ulink>, 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,000 for a 21" monitor or $1,700 for a 20" - monitor if that's what you really need. There are good monitors - available in the >=20" range and there are also cheap monitors in - the >=20" range. Unfortunately, very few are both cheap and - good!</para> - </sect3> - - <sect3 id="hw-networking"> - <title>Networking</title> - - <para>I can recommend the Intel EtherExpress Pro/100B card first and - foremost, followed by the <ulink - url="http://www.smc.com/">SMC</ulink> Ultra 16 controller for any - ISA application and the SMC EtherPower or Compex ENET32 cards for - slightly cheaper PCI based networking. In general, any PCI NIC - based around DEC's DC21041 Ethernet controller chip, such as the - Znyx ZX342 or DEC DE435/450, will generally work quite well and can - frequently be found in 2-port and 4-port version (useful for - firewalls and routers), though the Pro/100MB card has the edge when - it comes to providing the best performance with lower - overhead.</para> - - <para>If what you're looking for is the cheapest possible solution - then almost any NE2000 clone will do a fine job for very little - cost.</para> - </sect3> - - <sect3 id="hw-serial"> - <title>Serial</title> - - <para>If you're looking for high-speed serial networking solutions, - then <ulink url="http://www.dgii.com/">Digi International</ulink> - makes the <ulink - url="http://www.dgii.com/prodprofiles/profiles-prices/digiprofiles/digispecs/sync570.html">SYNC/570</ulink> - series, with drivers now in FreeBSD-CURRENT. <ulink - url="http://www.etinc.com/">Emerging Technologies</ulink> also - manufactures a board with T1/E1 capabilities, using software they - provide. I have no direct experience using either product, - however.</para> - - <para>multiport card options are somewhat more numerous, though it has - to be said that FreeBSD's support for <ulink - url="http://www.cyclades.com/">Cyclades</ulink>'s products is - probably the tightest, primarily as a result of that company's - commitment to making sure that we are adequately supplied with - evaluation boards and technical specs. I've heard that the - Cyclom-16Ye offers the best price/performance, though I've not - checked the prices lately. Other multiport cards I've heard good - things about are the BOCA and AST cards, and <ulink - url="http://www.stallion.com/">Stallion Technologies</ulink> - apparently offers an unofficial driver for their cards at <ulink - url="ftp://ftp.stallion.com/drivers/unsupported/freebsd/stalbsd-0.0.4.tar.gz">this</ulink> - location.</para> - </sect3> - - <sect3 id="hw-audio"> - <title>Audio</title> - - <para>I currently use a <ulink url="http://www.creaf.com/">Creative - Labs</ulink> AWE32 though just about anything from Creative Labs - will generally work these days. This is not to say that other types - of sound cards don't also work, simply that I have little experience - with them (I was a former GUS fan, but Gravis's sound card situation - has been dire for some time).</para> - </sect3> - - <sect3 id="hw-vgrabbers"> - <title>Video</title> - - <para>For video capture, there are two good choices — any card - based on the Brooktree BT848 chip, such as the Hauppage or WinTV - boards, will work very nicely with FreeBSD. Another board which - works for me is the <ulink - url="http://www.matrox.com/">Matrox</ulink> <ulink - url="http://www.matrox.com/imgweb/meteor.htm">Meteor</ulink> card. - FreeBSD also supports the older video spigot card from Creative - Labs, but those are getting somewhat difficult to find. Note that - the Meteor frame grabber card <emphasis>will not work</emphasis> - with motherboards based on the 440FX chipset! See the <link - linkend="hw-mb">motherboard reference</link> section for details. - In such cases, it's better to go with a BT848 based board.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="hw-core"> - <title>Core/Processing</title> - - <sect2> - <title>Motherboards, busses, and chipsets</title> - - <sect3> - <title>* ISA</title> - - <para></para> - </sect3> - - <sect3> - <title>* EISA</title> - - <para></para> - </sect3> - - <sect3> - <title>* VLB</title> - - <para></para> - </sect3> - - <sect3 id="hw-mb-pci"> - <title>PCI</title> - - <para><emphasis>Contributed by &a.obrien; from postings by - &a.rgrimes;. 25 April 1995.</emphasis></para> - - <para><emphasis>Continuing updates by &a.jkh;.</emphasis> Last - update on <emphasis>26 August 1996.</emphasis></para> - - <para>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.</para> - - <variablelist> - <varlistentry> - <term>Mercury:</term> - - <listitem> - <para>Cache coherency problems, especially if there are ISA bus - masters behind the ISA to PCI bridge chip. Hardware flaw, only - known work around is to turn the cache off.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Saturn-I <emphasis>(ie, 82424ZX at rev 0, 1 or - 2)</emphasis>:</term> - - <listitem> - <para>Write back cache coherency problems. Hardware flaw, only - known work around is to set the external cache to - write-through mode. Upgrade to Saturn-II.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Saturn-II <emphasis>(ie, 82424ZX at rev 3 or - 4)</emphasis>:</term> - - <listitem> - <para>Works fine, but many MB manufactures leave out the - external dirty bit SRAM needed for write back operation. - You can work around this either by running it in write - through mode, or get the dirty bit SRAM installed (I - have these for the ASUS PCI/I-486SP3G rev 1.6 and later - boards).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Neptune:</term> - - <listitem> - <para>Can not run more than 2 bus master devices. Admitted Intel - design flaw. Workarounds include do not run more than 2 bus - masters, special hardware design to replace the PCI bus - arbiter (appears on Intel Altair board and several other Intel - server group MB's). And of course Intel's official answer, - move to the Triton chip set, we <quote>fixed it - there</quote>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Triton <emphasis>(ie, 430FX)</emphasis>:</term> - - <listitem> - <para>No known cache coherency or bus master problems, chip set - does not implement parity checking. Workaround for parity - issue. Use Triton-II based motherboards if you have the - choice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Triton-II <emphasis>(ie, 430HX)</emphasis>:</term> - - <listitem> - <para>All reports on motherboards using this chipset have been - favorable so far. No known problems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Orion:</term> - - <listitem> - <para>Early versions of this chipset suffered from a PCI - write-posting bug which can cause noticeable performance - degradation in applications where large amounts of PCI bus - traffic is involved. B0 stepping or later revisions of the - chipset fixed this problem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink - url="http://developer.intel.com/design/pcisets/desktop.htm#440FX">440FX</ulink>:</term> - - <listitem> - <para>This <ulink - url="http://www.intel.com/procs/ppro/index.htm">Pentium - Pro</ulink> support chipset seems to work well, and does not - suffer from any of the early Orion chipset problems. It also - supports a wider variety of memory, including ECC and parity. - The only known problem with it is that the Matrox Meteor frame - grabber card doesn't like it.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2> - <title>CPUs/FPUs</title> - - <para><emphasis>Contributed by &a.asami;. 26 December - 1997.</emphasis></para> - - <sect3> - <title>P6 class (Pentium Pro/Pentium II)</title> - - <para>Both the Pentium Pro and Pentium II work fine with FreeBSD. In - fact, our main FTP site <ulink - url="ftp://ftp.FreeBSD.org/">ftp.FreeBSD.org</ulink> (also known - as "<filename>ftp.cdrom.com</filename>", world's largest ftp site) - runs FreeBSD on a Pentium Pro. <ulink - url="ftp://ftp.cdrom.com/archive-info/wcarchive.txt">Configurations - details</ulink> are available for interested parties.</para> - </sect3> - - <sect3> - <title>Pentium class</title> - - <para>The Intel Pentium (P54C), Pentium MMX (P55C), AMD K6 and - Cyrix/IBM 6x86MX processors are all reported to work with FreeBSD. - I will not go into details of which processor is faster than what, - there are millions of web sites on the Internet that tells you one - way or another. <!-- smiley --><emphasis>:)</emphasis></para> - - <note> - <para>Various CPUs have different voltage/cooling requirements. Make - sure your motherboard can supply the exact voltage needed by the - CPU. For instance, many recent MMX chips require split voltage - (e.g., 2.9V core, 3.3V I/O). Also, some AMD and Cyrix/IBM chips - run hotter than Intel chips. In that case, make sure you have - good heatsink/fans (you can get the list of certified parts from - their web pages).</para> - </note> - - <sect4> - <title>Clock speeds</title> - - <para><emphasis>Contributed by &a.rgrimes;. 1 October - 1996.</emphasis></para> - - <para><emphasis>Updated by &a.asami;. 27 December - 1997.</emphasis></para> - - <para>Pentium class machines use different clock speeds for the - various parts of the system. These being the speed of the CPU, - external memory bus, and the PCI bus. It is not always true that - a <quote>faster</quote> processor will make a system faster than a - <quote>slower</quote> one, due to the various clock speeds used. - Below is a table showing the differences:</para> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Rated CPU MHz</entry> - <entry>External Clock and Memory Bus MHz</entry> - <entry>External to Internal Clock Multiplier</entry> - <entry>PCI Bus Clock MHz</entry> - </row> - </thead> - - <tbody> - <row> - <entry>60</entry> - <entry>60</entry> - <entry>1.0</entry> - <entry>30</entry> - </row> - - <row> - <entry>66</entry> - <entry>66</entry> - <entry>1.0</entry> - <entry>33</entry> - </row> - - <row> - <entry>75</entry> - <entry>50</entry> - <entry>1.5</entry> - <entry>25</entry> - </row> - - <row> - <entry>90</entry> - <entry>60</entry> - <entry>1.5</entry> - <entry>30</entry> - </row> - - <row> - <entry>100</entry> - <entry>50</entry> - <entry>2</entry> - <entry>25</entry> - </row> - - <row> - <entry>100</entry> - <entry>66</entry> - <entry>1.5</entry> - <entry>33</entry> - </row> - - <row> - <entry>120</entry> - <entry>60</entry> - <entry>2</entry> - <entry>30</entry> - </row> - - <row> - <entry>133</entry> - <entry>66</entry> - <entry>2</entry> - <entry>33</entry> - </row> - - <row> - <entry>150</entry> - <entry>60</entry> - <entry>2.5</entry> - <entry>30 (Intel, AMD)</entry> - </row> - - <row> - <entry>150</entry> - <entry>75</entry> - <entry>2</entry> - <entry>37.5 (Cyrix/IBM 6x86MX)</entry> - </row> - - <row> - <entry>166</entry> - <entry>66</entry> - <entry>2.5</entry> - <entry>33</entry> - </row> - - <row> - <entry>180</entry> - <entry>60</entry> - <entry>3</entry> - <entry>30</entry> - </row> - - <row> - <entry>200</entry> - <entry>66</entry> - <entry>3</entry> - <entry>33</entry> - </row> - - <row> - <entry>233</entry> - <entry>66</entry> - <entry>3.5</entry> - <entry>33</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>66MHz may actually be 66.667MHz, but don't assume so.</para> - - <para>The Pentium 100 can be run at either 50MHz external clock - with a multiplier of 2 or at 66MHz and a multiplier of - 1.5.</para> - </note> - - <para>As can be seen the best parts to be using are the 100, 133, - 166, 200 and 233, with the exception that at a multiplier of 3 or - more the CPU starves for memory.</para> - </sect4> - - <sect4> - <title>The AMD K6 Bug</title> - - <para>In 1997, there have been reports of the AMD K6 seg faulting - during heavy compilation. That problem has been fixed in 3Q '97. - According to reports, K6 chips with date mark <quote>9733</quote> - or larger (i.e., manufactured in the 33rd week of '97 or later) do - not have this bug.</para> - </sect4> - </sect3> - - <sect3> - <title>* 486 class</title> - - <para></para> - </sect3> - - <sect3> - <title>* 386 class</title> - - <para></para> - </sect3> - - <sect3> - <title>286 class</title> - - <para>Sorry, FreeBSD does not run on 80286 machines. It is nearly - impossible to run today's large full-featured unices on such - hardware.</para> - </sect3> - </sect2> - - <sect2> - <title>* Memory</title> - - <para>The minimum amount of memory you must have to install FreeBSD is 5 - MB. Once your system is up and running you can <link - linkend="kernelconfig-building">build a custom kernel</link> that - will use less memory. If you use the <filename>boot4.flp</filename> - you can get away with having only 4 MB.</para> - </sect2> - - <sect2> - <title>* BIOS</title> - - <para></para> - </sect2> - </sect1> - - <sect1 id="hw-io"> - <title>Input/Output Devices</title> - - <sect2> - <title>* Video cards</title> - - <para></para> - </sect2> - - <sect2> - <title>* Sound cards</title> - - <para></para> - </sect2> - - <sect2> - <title>Serial ports and multiport cards</title> - - <sect3 id="uart"> - <title>The UART: What it is and how it works</title> - - <para><emphasis>Copyright © 1996 &a.uhclem;, All Rights - Reserved. 13 January 1996.</emphasis></para> - - <para>The Universal Asynchronous Receiver/Transmitter (UART) - controller is the key component of the serial communications - subsystem of a computer. The UART takes bytes of data and transmits - the individual bits in a sequential fashion. At the destination, a - second UART re-assembles the bits into complete bytes.</para> - - <para>Serial transmission is commonly used with modems and for - non-networked communication between computers, terminals and other - devices.</para> - - <para>There are two primary forms of serial transmission: Synchronous - and Asynchronous. Depending on the modes that are supported by the - hardware, the name of the communication sub-system will usually - include a <literal>A</literal> if it supports Asynchronous - communications, and a <literal>S</literal> if it supports - Synchronous communications. Both forms are described below.</para> - - <para>Some common acronyms are: - - <blockquote> - <para>UART Universal Asynchronous - Receiver/Transmitter</para> - </blockquote> - - <blockquote> - <para>USART Universal Synchronous-Asynchronous - Receiver/Transmitter</para> - </blockquote></para> - - <sect4> - <title>Synchronous Serial Transmission</title> - - <para>Synchronous serial transmission requires that the sender and - receiver share a clock with one another, or that the sender - provide a strobe or other timing signal so that the receiver knows - when to <quote>read</quote> the next bit of the data. In most - forms of serial Synchronous communication, if there is no data - available at a given instant to transmit, a fill character must be - sent instead so that data is always being transmitted. - Synchronous communication is usually more efficient because only - data bits are transmitted between sender and receiver, and - synchronous communication can be more more costly if extra wiring - and circuits are required to share a clock signal between the - sender and receiver.</para> - - <para>A form of Synchronous transmission is used with printers and - fixed disk devices in that the data is sent on one set of wires - while a clock or strobe is sent on a different wire. Printers and - fixed disk devices are not normally serial devices because most - fixed disk interface standards send an entire word of data for - each clock or strobe signal by using a separate wire for each bit - of the word. In the PC industry, these are known as Parallel - devices.</para> - - <para>The standard serial communications hardware in the PC does not - support Synchronous operations. This mode is described here for - comparison purposes only.</para> - </sect4> - - <sect4> - <title>Asynchronous Serial Transmission</title> - - <para>Asynchronous transmission allows data to be transmitted - without the sender having to send a clock signal to the receiver. - Instead, the sender and receiver must agree on timing parameters - in advance and special bits are added to each word which are used - to synchronize the sending and receiving units.</para> - - <para>When a word is given to the UART for Asynchronous - transmissions, a bit called the "Start Bit" is added to the - beginning of each word that is to be transmitted. The Start Bit - is used to alert the receiver that a word of data is about to be - sent, and to force the clock in the receiver into synchronization - with the clock in the transmitter. These two clocks must be - accurate enough to not have the frequency drift by more than 10% - during the transmission of the remaining bits in the word. (This - requirement was set in the days of mechanical teleprinters and is - easily met by modern electronic equipment.)</para> - - <para>After the Start Bit, the individual bits of the word of data - are sent, with the Least Significant Bit (LSB) being sent first. - Each bit in the transmission is transmitted for exactly the same - amount of time as all of the other bits, and the receiver - <quote>looks</quote> at the wire at approximately halfway through - the period assigned to each bit to determine if the bit is a - <literal>1</literal> or a <literal>0</literal>. For example, if - it takes two seconds to send each bit, the receiver will examine - the signal to determine if it is a <literal>1</literal> or a - <literal>0</literal> after one second has passed, then it will - wait two seconds and then examine the value of the next bit, and - so on.</para> - - <para>The sender does not know when the receiver has - <quote>looked</quote> at the value of the bit. The sender only - knows when the clock says to begin transmitting the next bit of - the word.</para> - - <para>When the entire data word has been sent, the transmitter may - add a Parity Bit that the transmitter generates. The Parity Bit - may be used by the receiver to perform simple error checking. - Then at least one Stop Bit is sent by the transmitter.</para> - - <para>When the receiver has received all of the bits in the data - word, it may check for the Parity Bits (both sender and receiver - must agree on whether a Parity Bit is to be used), and then the - receiver looks for a Stop Bit. If the Stop Bit does not appear - when it is supposed to, the UART considers the entire word to be - garbled and will report a Framing Error to the host processor when - the data word is read. The usual cause of a Framing Error is that - the sender and receiver clocks were not running at the same speed, - or that the signal was interrupted.</para> - - <para>Regardless of whether the data was received correctly or not, - the UART automatically discards the Start, Parity and Stop bits. - If the sender and receiver are configured identically, these bits - are not passed to the host.</para> - - <para>If another word is ready for transmission, the Start Bit for - the new word can be sent as soon as the Stop Bit for the previous - word has been sent.</para> - - <para>Because asynchronous data is <quote>self synchronizing</quote>, - if there is no data to transmit, the transmission line can be - idle.</para> - </sect4> - - <sect4> - <title>Other UART Functions</title> - - <para>In addition to the basic job of converting data from parallel - to serial for transmission and from serial to parallel on - reception, a UART will usually provide additional circuits for - signals that can be used to indicate the state of the transmission - media, and to regulate the flow of data in the event that the - remote device is not prepared to accept more data. For example, - when the device connected to the UART is a modem, the modem may - report the presence of a carrier on the phone line while the - computer may be able to instruct the modem to reset itself or to - not take calls by asserting or disasserting one more more of these - extra signals. The function of each of these additional signals is - defined in the EIA RS232-C standard.</para> - </sect4> - - <sect4> - <title>The RS232-C and V.24 Standards</title> - - <para>In most computer systems, the UART is connected to circuitry - that generates signals that comply with the EIA RS232-C - specification. There is also a CCITT standard named V.24 that - mirrors the specifications included in RS232-C.</para> - - <sect5> - <title>RS232-C Bit Assignments (Marks and Spaces)</title> - - <para>In RS232-C, a value of <literal>1</literal> is called a - <literal>Mark</literal> and a value of <literal>0</literal> is - called a <literal>Space</literal>. When a communication line is - idle, the line is said to be <quote>Marking</quote>, or - transmitting continuous <literal>1</literal> values.</para> - - <para>The Start bit always has a value of <literal>0</literal> (a - Space). The Stop Bit always has a value of <literal>1</literal> - (a Mark). This means that there will always be a Mark (1) to - Space (0) transition on the line at the start of every word, - even when multiple word are transmitted back to back. This - guarantees that sender and receiver can resynchronize their - clocks regardless of the content of the data bits that are being - transmitted.</para> - - <para>The idle time between Stop and Start bits does not have to - be an exact multiple (including zero) of the bit rate of the - communication link, but most UARTs are designed this way for - simplicity.</para> - - <para>In RS232-C, the "Marking" signal (a <literal>1</literal>) is - represented by a voltage between -2 VDC and -12 VDC, and a - "Spacing" signal (a <literal>0</literal>) is represented by a - voltage between 0 and +12 VDC. The transmitter is supposed to - send +12 VDC or -12 VDC, and the receiver is supposed to allow - for some voltage loss in long cables. Some transmitters in low - power devices (like portable computers) sometimes use only +5 - VDC and -5 VDC, but these values are still acceptable to a - RS232-C receiver, provided that the cable lengths are - short.</para> - </sect5> - - <sect5> - <title>RS232-C Break Signal</title> - - <para>RS232-C also specifies a signal called a - <literal>Break</literal>, which is caused by sending continuous - Spacing values (no Start or Stop bits). When there is no - electricity present on the data circuit, the line is considered - to be sending <literal>Break</literal>.</para> - - <para>The <literal>Break</literal> signal must be of a duration - longer than the time it takes to send a complete byte plus - Start, Stop and Parity bits. Most UARTs can distinguish between - a Framing Error and a Break, but if the UART cannot do this, the - Framing Error detection can be used to identify Breaks.</para> - - <para>In the days of teleprinters, when numerous printers around - the country were wired in series (such as news services), any - unit could cause a <literal>Break</literal> by temporarily - opening the entire circuit so that no current flowed. This was - used to allow a location with urgent news to interrupt some - other location that was currently sending information.</para> - - <para>In modern systems there are two types of Break signals. If - the Break is longer than 1.6 seconds, it is considered a "Modem - Break", and some modems can be programmed to terminate the - conversation and go on-hook or enter the modems' command mode - when the modem detects this signal. If the Break is smaller - than 1.6 seconds, it signifies a Data Break and it is up to the - remote computer to respond to this signal. Sometimes this form - of Break is used as an Attention or Interrupt signal and - sometimes is accepted as a substitute for the ASCII CONTROL-C - character.</para> - - <para>Marks and Spaces are also equivalent to <quote>Holes</quote> - and <quote>No Holes</quote> in paper tape systems.</para> - - <note> - <para>Breaks cannot be generated from paper tape or from any - other byte value, since bytes are always sent with Start and - Stop bit. The UART is usually capable of generating the - continuous Spacing signal in response to a special command - from the host processor.</para> - </note> - </sect5> - - <sect5> - <title>RS232-C DTE and DCE Devices</title> - - <para>The RS232-C specification defines two types of equipment: - the Data Terminal Equipment (DTE) and the Data Carrier Equipment - (DCE). Usually, the DTE device is the terminal (or computer), - and the DCE is a modem. Across the phone line at the other end - of a conversation, the receiving modem is also a DCE device and - the computer that is connected to that modem is a DTE device. - The DCE device receives signals on the pins that the DTE device - transmits on, and vice versa.</para> - - <para>When two devices that are both DTE or both DCE must be - connected together without a modem or a similar media translater - between them, a NULL modem must be used. The NULL modem - electrically re-arranges the cabling so that the transmitter - output is connected to the receiver input on the other device, - and vice versa. Similar translations are performed on all of - the control signals so that each device will see what it thinks - are DCE (or DTE) signals from the other device.</para> - - <para>The number of signals generated by the DTE and DCE devices - are not symmetrical. The DTE device generates fewer signals for - the DCE device than the DTE device receives from the DCE.</para> - </sect5> - - <sect5> - <title>RS232-C Pin Assignments</title> - - <para>The EIA RS232-C specification (and the ITU equivalent, V.24) - calls for a twenty-five pin connector (usually a DB25) and - defines the purpose of most of the pins in that - connector.</para> - - <para>In the IBM Personal Computer and similar systems, a subset - of RS232-C signals are provided via nine pin connectors (DB9). - The signals that are not included on the PC connector deal - mainly with synchronous operation, and this transmission mode is - not supported by the UART that IBM selected for use in the IBM - PC.</para> - - <para>Depending on the computer manufacturer, a DB25, a DB9, or - both types of connector may be used for RS232-C communications. - (The IBM PC also uses a DB25 connector for the parallel printer - interface which causes some confusion.)</para> - - <para>Below is a table of the RS232-C signal assignments in the - DB25 and DB9 connectors.</para> - - <informaltable frame="none"> - <tgroup cols="7"> - <thead> - <row> - <entry>DB25 RS232-C Pin</entry> - <entry>DB9 IBM PC Pin</entry> - <entry>EIA Circuit Symbol</entry> - <entry>CCITT Circuit Symbol</entry> - <entry>Common Name</entry> - <entry>Signal Source</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>-</entry> - <entry>AA</entry> - <entry>101</entry> - <entry>PG/FG</entry> - <entry>-</entry> - <entry>Frame/Protective Ground</entry> - </row> - - <row> - <entry>2</entry> - <entry>3</entry> - <entry>BA</entry> - <entry>103</entry> - <entry>TD</entry> - <entry>DTE</entry> - <entry>Transmit Data</entry> - </row> - - <row> - <entry>3</entry> - <entry>2</entry> - <entry>BB</entry> - <entry>104</entry> - <entry>RD</entry> - <entry>DCE</entry> - <entry>Receive Data</entry> - </row> - - <row> - <entry>4</entry> - <entry>7</entry> - <entry>CA</entry> - <entry>105</entry> - <entry>RTS</entry> - <entry>DTE</entry> - <entry>Request to Send</entry> - </row> - - <row> - <entry>5</entry> - <entry>8</entry> - <entry>CB</entry> - <entry>106</entry> - <entry>CTS</entry> - <entry>DCE</entry> - <entry>Clear to Send</entry> - </row> - - <row> - <entry>6</entry> - <entry>6</entry> - <entry>CC</entry> - <entry>107</entry> - <entry>DSR</entry> - <entry>DCE</entry> - <entry>Data Set Ready</entry> - </row> - - <row> - <entry>7</entry> - <entry>5</entry> - <entry>AV</entry> - <entry>102</entry> - <entry>SG/GND</entry> - <entry>-</entry> - <entry>Signal Ground</entry> - </row> - - <row> - <entry>8</entry> - <entry>1</entry> - <entry>CF</entry> - <entry>109</entry> - <entry>DCD/CD</entry> - <entry>DCE</entry> - <entry>Data Carrier Detect</entry> - </row> - - <row> - <entry>9</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>10</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>11</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>12</entry> - <entry>-</entry> - <entry>CI</entry> - <entry>122</entry> - <entry>SRLSD</entry> - <entry>DCE</entry> - <entry>Sec. Recv. Line Signal Detector</entry> - </row> - - <row> - <entry>13</entry> - <entry>-</entry> - <entry>SCB</entry> - <entry>121</entry> - <entry>SCTS</entry> - <entry>DCE</entry> - <entry>Secondary Clear to Send</entry> - </row> - - <row> - <entry>14</entry> - <entry>-</entry> - <entry>SBA</entry> - <entry>118</entry> - <entry>STD</entry> - <entry>DTE</entry> - <entry>Secondary Transmit Data</entry> - </row> - - <row> - <entry>15</entry> - <entry>-</entry> - <entry>DB</entry> - <entry>114</entry> - <entry>TSET</entry> - <entry>DCE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>16</entry> - <entry>-</entry> - <entry>SBB</entry> - <entry>119</entry> - <entry>SRD</entry> - <entry>DCE</entry> - <entry>Secondary Received Data</entry> - </row> - - <row> - <entry>17</entry> - <entry>-</entry> - <entry>DD</entry> - <entry>115</entry> - <entry>RSET</entry> - <entry>DCE</entry> - <entry>Receiver Signal Element Timing</entry> - </row> - - <row> - <entry>18</entry> - <entry>-</entry> - <entry>-</entry> - <entry>141</entry> - <entry>LOOP</entry> - <entry>DTE</entry> - <entry>Local Loopback</entry> - </row> - - <row> - <entry>19</entry> - <entry>-</entry> - <entry>SCA</entry> - <entry>120</entry> - <entry>SRS</entry> - <entry>DTE</entry> - <entry>Secondary Request to Send</entry> - </row> - - <row> - <entry>20</entry> - <entry>4</entry> - <entry>CD</entry> - <entry>108.2</entry> - <entry>DTR</entry> - <entry>DTE</entry> - <entry>Data Terminal Ready</entry> - </row> - - <row> - <entry>21</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>RDL</entry> - <entry>DTE</entry> - <entry>Remote Digital Loopback</entry> - </row> - - <row> - <entry>22</entry> - <entry>9</entry> - <entry>CE</entry> - <entry>125</entry> - <entry>RI</entry> - <entry>DCE</entry> - <entry>Ring Indicator</entry> - </row> - - <row> - <entry>23</entry> - <entry>-</entry> - <entry>CH</entry> - <entry>111</entry> - <entry>DSRS</entry> - <entry>DTE</entry> - <entry>Data Signal Rate Selector</entry> - </row> - - <row> - <entry>24</entry> - <entry>-</entry> - <entry>DA</entry> - <entry>113</entry> - <entry>TSET</entry> - <entry>DTE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>25</entry> - <entry>-</entry> - <entry>-</entry> - <entry>142</entry> - <entry>-</entry> - <entry>DCE</entry> - <entry>Test Mode</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect5> - </sect4> - - <sect4> - <title>Bits, Baud and Symbols</title> - - <para>Baud is a measurement of transmission speed in asynchronous - communication. Because of advances in modem communication - technology, this term is frequently misused when describing the - data rates in newer devices.</para> - - <para>Traditionally, a Baud Rate represents the number of bits that - are actually being sent over the media, not the amount of data - that is actually moved from one DTE device to the other. The Baud - count includes the overhead bits Start, Stop and Parity that are - generated by the sending UART and removed by the receiving UART. - This means that seven-bit words of data actually take 10 bits to - be completely transmitted. Therefore, a modem capable of moving - 300 bits per second from one place to another can normally only - move 30 7-bit words if Parity is used and one Start and Stop bit - are present.</para> - - <para>If 8-bit data words are used and Parity bits are also used, - the data rate falls to 27.27 words per second, because it now - takes 11 bits to send the eight-bit words, and the modem still - only sends 300 bits per second.</para> - - <para>The formula for converting bytes per second into a baud rate - and vice versa was simple until error-correcting modems came - along. These modems receive the serial stream of bits from the - UART in the host computer (even when internal modems are used the - data is still frequently serialized) and converts the bits back - into bytes. These bytes are then combined into packets and sent - over the phone line using a Synchronous transmission method. This - means that the Stop, Start, and Parity bits added by the UART in - the DTE (the computer) were removed by the modem before - transmission by the sending modem. When these bytes are received - by the remote modem, the remote modem adds Start, Stop and Parity - bits to the words, converts them to a serial format and then sends - them to the receiving UART in the remote computer, who then strips - the Start, Stop and Parity bits.</para> - - <para>The reason all these extra conversions are done is so that the - two modems can perform error correction, which means that the - receiving modem is able to ask the sending modem to resend a block - of data that was not received with the correct checksum. This - checking is handled by the modems, and the DTE devices are usually - unaware that the process is occurring.</para> - - <para>By striping the Start, Stop and Parity bits, the additional - bits of data that the two modems must share between themselves to - perform error-correction are mostly concealed from the effective - transmission rate seen by the sending and receiving DTE equipment. - For example, if a modem sends ten 7-bit words to another modem - without including the Start, Stop and Parity bits, the sending - modem will be able to add 30 bits of its own information that the - receiving modem can use to do error-correction without impacting - the transmission speed of the real data.</para> - - <para>The use of the term Baud is further confused by modems that - perform compression. A single 8-bit word passed over the - telephone line might represent a dozen words that were transmitted - to the sending modem. The receiving modem will expand the data - back to its original content and pass that data to the receiving - DTE.</para> - - <para>Modern modems also include buffers that allow the rate that - bits move across the phone line (DCE to DCE) to be a different - speed than the speed that the bits move between the DTE and DCE on - both ends of the conversation. Normally the speed between the DTE - and DCE is higher than the DCE to DCE speed because of the use of - compression by the modems.</para> - - <para>Because the number of bits needed to describe a byte varied - during the trip between the two machines plus the differing - bits-per-seconds speeds that are used present on the DTE-DCE and - DCE-DCE links, the usage of the term Baud to describe the overall - communication speed causes problems and can misrepresent the true - transmission speed. So Bits Per Second (bps) is the correct term - to use to describe the transmission rate seen at the DCE to DCE - interface and Baud or Bits Per Second are acceptable terms to use - when a connection is made between two systems with a wired - connection, or if a modem is in use that is not performing - error-correction or compression.</para> - - <para>Modern high speed modems (2400, 9600, 14,400, and 19,200bps) - in reality still operate at or below 2400 baud, or more - accurately, 2400 Symbols per second. High speed modem are able to - encode more bits of data into each Symbol using a technique called - Constellation Stuffing, which is why the effective bits per second - rate of the modem is higher, but the modem continues to operate - within the limited audio bandwidth that the telephone system - provides. Modems operating at 28,800 and higher speeds have - variable Symbol rates, but the technique is the same.</para> - </sect4> - - <sect4> - <title>The IBM Personal Computer UART</title> - - <para>Starting with the original IBM Personal Computer, IBM selected - the National Semiconductor INS8250 UART for use in the IBM PC - Parallel/Serial Adapter. Subsequent generations of compatible - computers from IBM and other vendors continued to use the INS8250 - or improved versions of the National Semiconductor UART - family.</para> - - <sect5> - <title>National Semiconductor UART Family Tree</title> - - <para>There have been several versions and subsequent generations - of the INS8250 UART. Each major version is described - below.</para> - - <!-- This should really be a graphic --> - <programlisting> -INS8250 -> INS8250B - \ - \ - \-> INS8250A -> INS82C50A - \ - \ - \-> NS16450 -> NS16C450 - \ - \ - \-> NS16550 -> NS16550A -> PC16550D</programlisting> - - <variablelist> - <varlistentry> - <term>INS8250</term> - - <listitem> - <para>This part was used in the original IBM PC and IBM - PC/XT. The original name for this part was the INS8250 - ACE (Asynchronous Communications Element) and it is made - from NMOS technology.</para> - - <para>The 8250 uses eight I/O ports and has a one-byte send - and a one-byte receive buffer. This original UART has - several race conditions and other flaws. The original IBM - BIOS includes code to work around these flaws, but this - made the BIOS dependent on the flaws being present, so - subsequent parts like the 8250A, 16450 or 16550 could not - be used in the original IBM PC or IBM PC/XT.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250-B</term> - - <listitem> - <para>This is the slower speed of the INS8250 made from NMOS - technology. It contains the same problems as the original - INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250A</term> - - <listitem> - <para>An improved version of the INS8250 using XMOS - technology with various functional flaws corrected. The - INS8250A was used initially in PC clone computers by - vendors who used <quote>clean</quote> BIOS designs. Because - of the corrections in the chip, this part could not be - used with a BIOS compatible with the INS8250 or - INS8250B.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS82C50A</term> - - <listitem> - <para>This is a CMOS version (low power consumption) of the - INS8250A and has similar functional - characteristics.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16450</term> - - <listitem> - <para>Same as NS8250A with improvements so it can be used - with faster CPU bus designs. IBM used this part in the - IBM AT and updated the IBM BIOS to no longer rely on the - bugs in the INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C450</term> - - <listitem> - <para>This is a CMOS version (low power consumption) of the - NS16450.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550</term> - - <listitem> - <para>Same as NS16450 with a 16-byte send and receive buffer - but the buffer design was flawed and could not be reliably - be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550A</term> - - <listitem> - <para>Same as NS16550 with the buffer flaws corrected. The - 16550A and its successors have become the most popular - UART design in the PC industry, mainly due it its ability - to reliably handle higher data rates on operating systems - with sluggish interrupt response times.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C552</term> - - <listitem> - <para>This component consists of two NS16C550A CMOS UARTs in - a single package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>PC16550D</term> - - <listitem> - <para>Same as NS16550A with subtle flaws corrected. This is - revision D of the 16550 family and is the latest design - available from National Semiconductor.</para> - </listitem> - </varlistentry> - </variablelist> - </sect5> - - <sect5> - <title>The NS16550AF and the PC16550D are the same thing</title> - - <para>National reorganized their part numbering system a few years - ago, and the NS16550AFN no longer exists by that name. (If you - have a NS16550AFN, look at the date code on the part, which is a - four digit number that usually starts with a nine. The first - two digits of the number are the year, and the last two digits - are the week in that year when the part was packaged. If you - have a NS16550AFN, it is probably a few years old.)</para> - - <para>The new numbers are like PC16550DV, with minor differences - in the suffix letters depending on the package material and its - shape. (A description of the numbering system can be found - below.)</para> - - <para>It is important to understand that in some stores, you may - pay $15(US) for a NS16550AFN made in 1990 and in the next - bin are the new PC16550DN parts with minor fixes that National - has made since the AFN part was in production, the PC16550DN was - probably made in the past six months and it costs half (as low - as $5(US) in volume) as much as the NS16550AFN because they - are readily available.</para> - - <para>As the supply of NS16550AFN chips continues to shrink, the - price will probably continue to increase until more people - discover and accept that the PC16550DN really has the same - function as the old part number.</para> - </sect5> - - <sect5> - <title>National Semiconductor Part Numbering System</title> - - <para>The older NS<replaceable>nnnnnrqp</replaceable> part - numbers are now of the format - PC<replaceable>nnnnnrgp</replaceable>.</para> - - <para>The <replaceable>r</replaceable> is the revision field. The - current revision of the 16550 from National Semiconductor is - <literal>D</literal>.</para> - - <para>The <replaceable>p</replaceable> is the package-type field. - The types are:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>"F"</entry> - <entry>QFP</entry> - <entry>(quad flat pack) L lead type</entry> - </row> - - <row> - <entry>"N"</entry> - <entry>DIP</entry> - <entry>(dual inline package) through hole straight lead - type</entry> - </row> - - <row> - <entry>"V"</entry> - <entry>LPCC</entry> - <entry>(lead plastic chip carrier) J lead type</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The <replaceable>g</replaceable> is the product grade field. - If an <literal>I</literal> precedes the package-type letter, it - indicates an <quote>industrial</quote> grade part, which has - higher specs than a standard part but not as high as Military - Specification (Milspec) component. This is an optional - field.</para> - - <para>So what we used to call a NS16550AFN (DIP Package) is now - called a PC16550DN or PC16550DIN.</para> - </sect5> - </sect4> - - <sect4> - <title>Other Vendors and Similar UARTs</title> - - <para>Over the years, the 8250, 8250A, 16450 and 16550 have been - licensed or copied by other chip vendors. In the case of the - 8250, 8250A and 16450, the exact circuit (the - <quote>megacell</quote>) was licensed to many vendors, including - Western Digital and Intel. Other vendors reverse-engineered the - part or produced emulations that had similar behavior.</para> - - <para>In internal modems, the modem designer will frequently emulate - the 8250A/16450 with the modem microprocessor, and the emulated - UART will frequently have a hidden buffer consisting of several - hundred bytes. Because of the size of the buffer, these - emulations can be as reliable as a 16550A in their ability to - handle high speed data. However, most operating systems will - still report that the UART is only a 8250A or 16450, and may not - make effective use of the extra buffering present in the emulated - UART unless special drivers are used.</para> - - <para>Some modem makers are driven by market forces to abandon a - design that has hundreds of bytes of buffer and instead use a - 16550A UART so that the product will compare favorably in market - comparisons even though the effective performance may be lowered - by this action.</para> - - <para>A common misconception is that all parts with - <quote>16550A</quote> written on them are identical in performance. - There are differences, and in some cases, outright flaws in most - of these 16550A clones.</para> - - <para>When the NS16550 was developed, the National Semiconductor - obtained several patents on the design and they also limited - licensing, making it harder for other vendors to provide a chip - with similar features. Because of the patents, reverse-engineered - designs and emulations had to avoid infringing the claims covered - by the patents. Subsequently, these copies almost never perform - exactly the same as the NS16550A or PC16550D, which are the parts - most computer and modem makers want to buy but are sometimes - unwilling to pay the price required to get the genuine - part.</para> - - <para>Some of the differences in the clone 16550A parts are - unimportant, while others can prevent the device from being used - at all with a given operating system or driver. These differences - may show up when using other drivers, or when particular - combinations of events occur that were not well tested or - considered in the Windows driver. This is because most modem - vendors and 16550-clone makers use the Microsoft drivers from - Windows for Workgroups 3.11 and the Microsoft MS-DOS utility as the - primary tests for compatibility with the NS16550A. This - over-simplistic criteria means that if a different operating - system is used, problems could appear due to subtle differences - between the clones and genuine components.</para> - - <para>National Semiconductor has made available a program named - <application>COMTEST</application> that performs compatibility - tests independent of any OS drivers. It should be remembered that - the purpose of this type of program is to demonstrate the flaws in - the products of the competition, so the program will report major - as well as extremely subtle differences in behavior in the part - being tested.</para> - - <para>In a series of tests performed by the author of this document - in 1994, components made by National Semiconductor, TI, StarTech, - and CMD as well as megacells and emulations embedded in internal - modems were tested with COMTEST. A difference count for some of - these components is listed below. Because these tests were - performed in 1994, they may not reflect the current performance of - the given product from a vendor.</para> - - <para>It should be noted that COMTEST normally aborts when an - excessive number or certain types of problems have been detected. - As part of this testing, COMTEST was modified so that it would not - abort no matter how many differences were encountered.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Vendor</entry> - <entry>Part Number</entry> - <entry>Errors (aka "differences" reported)</entry> - </row> - </thead> - - <tbody> - <row> - <entry>National</entry> - <entry>(PC16550DV)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16550AFN)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16C552V)</entry> - <entry>0</entry> - </row> - - <row> - <entry>TI</entry> - <entry>(TL16550AFN)</entry> - <entry>3</entry> - </row> - - <row> - <entry>CMD</entry> - <entry>(16C550PE)</entry> - <entry>19</entry> - </row> - - <row> - <entry>StarTech</entry> - <entry>(ST16C550J)</entry> - <entry>23</entry> - </row> - - <row> - <entry>Rockwell</entry> - <entry>Reference modem with internal 16550 or an - emulation (RC144DPi/C3000-25)</entry> - <entry>117</entry> - </row> - - <row> - <entry>Sierra</entry> - <entry>Modem with an internal 16550 - (SC11951/SC11351)</entry> - <entry>91</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>To date, the author of this document has not found any - non-National parts that report zero differences using the - COMTEST program. It should also be noted that National has had - five versions of the 16550 over the years and the newest parts - behave a bit differently than the classic NS16550AFN that is - considered the benchmark for functionality. COMTEST appears to - turn a blind eye to the differences within the National product - line and reports no errors on the National parts (except for the - original 16550) even when there are official erratas that - describe bugs in the A, B and C revisions of the parts, so this - bias in COMTEST must be taken into account.</para> - </note> - - <para>It is important to understand that a simple count of - differences from COMTEST does not reveal a lot about what - differences are important and which are not. For example, about - half of the differences reported in the two modems listed above - that have internal UARTs were caused by the clone UARTs not - supporting five- and six-bit character modes. The real 16550, - 16450, and 8250 UARTs all support these modes and COMTEST checks - the functionality of these modes so over fifty differences are - reported. However, almost no modern modem supports five- or - six-bit characters, particularly those with error-correction and - compression capabilities. This means that the differences related - to five- and six-bit character modes can be discounted.</para> - - <para>Many of the differences COMTEST reports have to do with - timing. In many of the clone designs, when the host reads from - one port, the status bits in some other port may not update in the - same amount of time (some faster, some slower) as a - <emphasis>real</emphasis> NS16550AFN and COMTEST looks for these - differences. This means that the number of differences can be - misleading in that one device may only have one or two differences - but they are extremely serious, and some other device that updates - the status registers faster or slower than the reference part - (that would probably never affect the operation of a properly - written driver) could have dozens of differences reported.</para> - - <para>COMTEST can be used as a screening tool to alert the - administrator to the presence of potentially incompatible - components that might cause problems or have to be handled as a - special case.</para> - - <para>If you run COMTEST on a 16550 that is in a modem or a modem is - attached to the serial port, you need to first issue a ATE0&W - command to the modem so that the modem will not echo any of the - test characters. If you forget to do this, COMTEST will report at - least this one difference:</para> - - <screen>Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61</screen> - </sect4> - - <sect4> - <title>8250/16450/16550 Registers</title> - - <para>The 8250/16450/16550 UART occupies eight contiguous I/O port - addresses. In the IBM PC, there are two defined locations for - these eight ports and they are known collectively as COM1 and - COM2. The makers of PC-clones and add-on cards have created two - additional areas known as COM3 and COM4, but these extra COM ports - conflict with other hardware on some systems. The most common - conflict is with video adapters that provide IBM 8514 - emulation.</para> - - <para>COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4 - COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3 COM3 - is located from 0x3e8 to 0x3ef and has no standardized IRQ COM4 is - located from 0x2e8 to 0x2ef and has no standardized IRQ.</para> - - <para>A description of the I/O ports of the 8250/16450/16550 UART is - provided below.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>I/O Port</entry> - <entry>Access Allowed</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>+0x00</entry> - <entry>write (DLAB==0)</entry> - <entry><para>Transmit Holding Register - (THR).</para><para>Information written to this port are - treated as data words and will be transmitted by the - UART.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>read (DLAB==0)</entry> - <entry><para>Receive Buffer Register (RBR).</para><para>Any - data words received by the UART form the serial link are - accessed by the host by reading this - port.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch LSB (DLL)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 0 thru 7 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch MSB (DLH)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 8 thru 15 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==0)</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2"><para>Interrupt Enable Register - (IER)</para><para>The 8250/16450/16550 UART - classifies events into one of four categories. - Each category can be configured to generate an - interrupt when any of the events occurs. The - 8250/16450/16550 UART generates a single external - interrupt signal regardless of how many events in - the enabled categories have occurred. It is up to - the host processor to respond to the interrupt and - then poll the enabled interrupt categories - (usually all categories have interrupts enabled) - to determine the true cause(s) of the - interrupt.</para></entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Enable Modem Status Interrupt (EDSSI). Setting - this bit to "1" allows the UART to generate an - interrupt when a change occurs on one or more of the - status lines.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Enable Receiver Line Status Interrupt (ELSI) - Setting this bit to "1" causes the UART to generate - an interrupt when the an error (or a BREAK signal) - has been detected in the incoming data.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Enable Transmitter Holding Register Empty - Interrupt (ETBEI) Setting this bit to "1" causes the - UART to generate an interrupt when the UART has room - for one or more additional characters that are to be - transmitted.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Enable Received Data Available Interrupt - (ERBFI) Setting this bit to "1" causes the UART to - generate an interrupt when the UART has received - enough characters to exceed the trigger level of the - FIFO, or the FIFO timer has expired (stale data), or - a single character has been received when the FIFO - is disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>write</entry> - <entrytbl cols="4"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <spanspec namest="col1" nameend="col4" spanname="1to4"> - <spanspec namest="col2" nameend="col4" spanname="2to4"> - - <tbody> - <row> - <entry spanname="1to4">FIFO Control Register (FCR) - (This port does not exist on the 8250 and 16450 - UART.)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to4">Receiver Trigger Bit #1</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to4"><para>Receiver Trigger Bit - #0</para><para>These two bits control at what - point the receiver is to generate an interrupt - when the FIFO is active.</para></entry> - </row> - - <row> - <entry colname="col2">7</entry> - <entry colname="col3">6</entry> - <entry colname="col4">How many words are received - before an interrupt is generated</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">4</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4">8</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">14</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to4">DMA Mode Select. If Bit 0 is - set to "1" (FIFOs enabled), setting this bit changes - the operation of the -RXRDY and -TXRDY signals from - Mode 0 to Mode 1.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to4">Transmit FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being transmitted - will be sent intact. This function is useful in - aborting transfers.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to4">Receiver FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being assembled - in the shift register will be received - intact.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to4">16550 FIFO Enable. When set, - both the transmit and receive FIFOs are enabled. - Any contents in the holding register, shift - registers or FIFOs are lost when FIFOs are enabled - or disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>read</entry> - <entrytbl cols="6"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <colspec colnum="6" colname="col6"> - <spanspec namest="col1" nameend="col6" spanname="1to6"> - <spanspec namest="col2" nameend="col6" spanname="2to6"> - - <tbody> - <row> - <entry spanname="1to6">Interrupt Identification - Register</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to6">Interrupt ID Bit #2. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to6">Interrupt ID Bit #1</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to6">Interrupt ID Bit #0.These three - bits combine to report the category of event that - caused the interrupt that is in progress. These - categories have priorities, so if multiple - categories of events occur at the same time, the - UART will report the more important events first and - the host must resolve the events in the order they - are reported. All events that caused the current - interrupt must be resolved before any new interrupts - will be generated. (This is a limitation of the PC - architecture.)</entry> - </row> - - <row> - <entry colname="col2">2</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Priority</entry> - <entry colname="col6">Description</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">1</entry> - <entry colname="col5">First</entry> - <entry colname="col6">Received Error (OE, PE, BI, or - FE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Received Data Available</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Trigger level identification - (Stale data in receive buffer)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - <entry colname="col5">Third</entry> - <entry colname="col6">Transmitter has room for more - words (THRE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Fourth</entry> - <entry colname="col6">Modem Status Change (-CTS, -DSR, - -RI, or -DCD)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to6">Interrupt Pending Bit. If this - bit is set to "0", then at least one interrupt is - pending.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x03</entry> - <entry>write/read</entry> - <entrytbl cols="5"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <spanspec namest="col1" nameend="col5" spanname="1to5"> - <spanspec namest="col2" nameend="col5" spanname="2to5"> - <spanspec namest="col4" nameend="col5" spanname="4to5"> - - <tbody> - <row> - <entry spanname="1to5">Line Control Register - (LCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to5">Divisor Latch Access Bit - (DLAB). When set, access to the data - transmit/receive register (THR/RBR) and the - Interrupt Enable Register (IER) is disabled. Any - access to these ports is now redirected to the - Divisor Latch Registers. Setting this bit, loading - the Divisor Registers, and clearing DLAB should be - done with interrupts disabled.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to5">Set Break. When set to "1", - the transmitter begins to transmit continuous - Spacing until this bit is set to "0". This - overrides any bits of characters that are being - transmitted.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to5">Stick Parity. When parity is - enabled, setting this bit causes parity to always be - "1" or "0", based on the value of Bit 4.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to5">Even Parity Select (EPS). When - parity is enabled and Bit 5 is "0", setting this bit - causes even parity to be transmitted and expected. - Otherwise, odd parity is used.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to5">Parity Enable (PEN). When set - to "1", a parity bit is inserted between the last - bit of the data and the Stop Bit. The UART will - also expect parity to be present in the received - data.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to5">Number of Stop Bits (STB). If - set to "1" and using 5-bit data words, 1.5 Stop Bits - are transmitted and expected in each data word. For - 6, 7 and 8-bit data words, 2 Stop Bits are - transmitted and expected. When this bit is set to - "0", one Stop Bit is used on each data word.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to5">Word Length Select Bit #1 - (WLSB1)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to5">Word Length Select Bit #0 - (WLSB0)</entry> - </row> - - <row> - <entry colname="col2" spanname="2to5">Together these - bits specify the number of bits in each data - word.</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">Word - Length</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">5 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">6 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">7 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">8 Data - Bits</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x04</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Control Register - (MCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Loop-Back Enable. When set to "1", the UART - transmitter and receiver are internally connected - together to allow diagnostic operations. In - addition, the UART modem control outputs are - connected to the UART modem control inputs. CTS is - connected to RTS, DTR is connected to DSR, OUT1 is - connected to RI, and OUT 2 is connected to - DCD.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>OUT 2. An auxiliary output that the host - processor may set high or low. In the IBM PC serial - adapter (and most clones), OUT 2 is used to - tri-state (disable) the interrupt signal from the - 8250/16450/16550 UART.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>OUT 1. An auxiliary output that the host - processor may set high or low. This output is not - used on the IBM PC serial adapter.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Request to Send (RTS). When set to "1", the - output of the UART -RTS line is Low - (Active).</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Terminal Ready (DTR). When set to "1", - the output of the UART -DTR line is Low - (Active).</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x05</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Line Status Register - (LSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Error in Receiver FIFO. On the 8250/16450 - UART, this bit is zero. This bit is set to "1" when - any of the bytes in the FIFO have one or more of the - following error conditions: PE, FE, or BI.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Transmitter Empty (TEMT). When set to "1", - there are no words remaining in the transmit FIFO - or the transmit shift register. The transmitter is - completely idle.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Transmitter Holding Register Empty (THRE). - When set to "1", the FIFO (or holding register) now - has room for at least one additional word to - transmit. The transmitter may still be transmitting - when this bit is set to "1".</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Break Interrupt (BI). The receiver has - detected a Break signal.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Framing Error (FE). A Start Bit was detected - but the Stop Bit did not appear at the expected - time. The received word is probably - garbled.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Parity Error (PE). The parity bit was - incorrect for the word received.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Overrun Error (OE). A new word was received - and there was no room in the receive buffer. The - newly-arrived word in the shift register is - discarded. On 8250/16450 UARTs, the word in the - holding register is discarded and the newly- arrived - word is put in the holding register.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Ready (DR) One or more words are in the - receive FIFO that the host may read. A word must be - completely received and moved from the shift - register into the FIFO (or holding register for - 8250/16450 designs) before this bit is set.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x06</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Status Register - (MSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Data Carrier Detect (DCD). Reflects the state - of the DCD line on the UART.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Ring Indicator (RI). Reflects the state of the - RI line on the UART.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Data Set Ready (DSR). Reflects the state of - the DSR line on the UART.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Clear To Send (CTS). Reflects the state of the - CTS line on the UART.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Delta Data Carrier Detect (DDCD). Set to "1" - if the -DCD line has changed state one more more - times since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Trailing Edge Ring Indicator (TERI). Set to - "1" if the -RI line has had a low to high transition - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Delta Data Set Ready (DDSR). Set to "1" if the - -DSR line has changed state one more more times - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Delta Clear To Send (DCTS). Set to "1" if the - -CTS line has changed state one more more times - since the last time the MSR was read by the - host.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x07</entry> - <entry>write/read</entry> - <entry>Scratch Register (SCR). This register performs no - function in the UART. Any value can be written by the - host to this location and read by the host later - on.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect4> - - <sect4> - <title>Beyond the 16550A UART</title> - - <para>Although National Semiconductor has not offered any components - compatible with the 16550 that provide additional features, - various other vendors have. Some of these components are - described below. It should be understood that to effectively - utilize these improvements, drivers may have to be provided by the - chip vendor since most of the popular operating systems do not - support features beyond those provided by the 16550.</para> - - <variablelist> - <varlistentry> - <term>ST16650</term> - - <listitem> - <para>By default this part is similar to the NS16550A, but an - extended 32-byte send and receive buffer can be optionally - enabled. Made by StarTech.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>TIL16660</term> - - <listitem> - <para>By default this part behaves similar to the NS16550A, - but an extended 64-byte send and receive buffer can be - optionally enabled. Made by Texas Instruments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Hayes ESP</term> - - <listitem> - <para>This proprietary plug-in card contains a 2048-byte send - and receive buffer, and supports data rates to - 230.4Kbit/sec. Made by Hayes.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition to these <quote>dumb</quote> UARTs, many vendors - produce intelligent serial communication boards. This type of - design usually provides a microprocessor that interfaces with - several UARTs, processes and buffers the data, and then alerts the - main PC processor when necessary. Because the UARTs are not - directly accessed by the PC processor in this type of - communication system, it is not necessary for the vendor to use - UARTs that are compatible with the 8250, 16450, or the 16550 UART. - This leaves the designer free to components that may have better - performance characteristics.</para> - </sect4> - </sect3> - - <sect3 id="sio"> - <title>Configuring the <devicename>sio</devicename> driver</title> - - <para>The <devicename>sio</devicename> 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 &man.sio.4; - manual page for detailed technical documentation.</para> - - <sect4> - <title>Digi International (DigiBoard) PC/8</title> - - <para><emphasis>Contributed by &a.awebster;. 26 August - 1995.</emphasis></para> - - <para>Here is a config snippet from a machine with a Digi - International PC/8 with 16550. It has 8 modems connected to these - 8 lines, and they work just great. Do not forget to add - <literal>options COM_MULTIPORT</literal> or it will not work very - well!</para> - - <programlisting> -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</programlisting> - - <para>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.</para> - </sect4> - - <sect4> - <title>Boca 16</title> - - <para><emphasis>Contributed by &a.whiteside;. 26 August - 1995.</emphasis></para> - - <para>The procedures to make a Boca 16 port board with FreeBSD are - pretty straightforward, but you will need a couple things to make - it work:</para> - - <orderedlist> - <listitem> - <para>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 - <emphasis>not</emphasis> come with multiport support enabled - and you will need to add a device entry for each port - anyways.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - </orderedlist> - - <para>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.</para> - - <para>If you do not already have a custom kernel configuration file - set up, refer to <link linkend="kernelconfig">Kernel - Configuration</link> 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.</para> - - <procedure> - <step> - <para>Add the line - - <programlisting> -options COM_MULTIPORT</programlisting> - - to the config file.</para> - </step> - - <step> - <para>Where the current <literal>device - sio<replaceable>n</replaceable></literal> lines are, you - will need to add 16 more devices. Only the last device - includes the interrupt vector for the board. (See the - &man.sio.4; 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.</para> - - <programlisting> -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</programlisting> - - <para>The flags entry <emphasis>must</emphasis> be changed from - this example unless you are using the exact same sio - assignments. Flags are set according to - 0x<replaceable>M</replaceable><replaceable>YY</replaceable> - where <replaceable>M</replaceable> indicates the minor number - of the master port (the last port on a Boca 16) and - <replaceable>YY</replaceable> 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, - <programlisting> flags 0x1005</programlisting> indicates that - the master port is sio16. If I added another board and - assigned sio17 through sio28, the flags for all 16 ports on - <emphasis>that</emphasis> board would be 0x1C05, where 1C - indicates the minor number of the master port. Do not change - the 05 setting.</para> - </step> - - <step> - <para>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)</para> - - <screen>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)</screen> - - <para>If the messages go by too fast to see, - - <screen>&prompt.root; <userinput>dmesg | more</userinput></screen> - will show you the boot messages.</para> - </step> - - <step> - <para>Next, appropriate entries in <filename>/dev</filename> for - the devices must be made using the - <filename>/dev/MAKEDEV</filename> script. After becoming - root:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tty1</userinput> -&prompt.root; <userinput>./MAKEDEV cua1</userinput> -<emphasis>(everything in between)</emphasis> -&prompt.root; <userinput>./MAKEDEV ttyg</userinput> -&prompt.root; <userinput>./MAKEDEV cuag</userinput></screen> - - <para>If you do not want or need call-out devices for some - reason, you can dispense with making the - <filename>cua*</filename> devices.</para> - </step> - - <step> - <para>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) - - <screen>&prompt.root; <userinput>echo at > ttyd*</userinput></screen> - for each device you have made. You - <emphasis>should</emphasis> see the RX lights flash for each - working port.</para> - </step> - </procedure> - </sect4> - - <sect4> - <title>Support for Cheap Multi-UART Cards</title> - - <para><emphasis>Contributed by Helge Oldach - <email>hmo@sep.hamburg.com</email>, September - 1999</emphasis></para> - - <para>Ever wondered about FreeBSD support for your 20$ multi-I/O - card with two (or more) COM ports, sharing IRQs? Here's - how:</para> - - <para>Usually the only option to support these kind of boards is to - use a distinct IRQ for each port. For example, if your CPU board - has an on-board <devicename>COM1</devicename> port (aka - <devicename>sio0</devicename>–I/O address 0x3F8 and IRQ 4) - and you have an extension board with two UARTs, you will commonly - need to configure them as <devicename>COM2</devicename> (aka - <devicename>sio1</devicename>–I/O address 0x2F8 and IRQ 3), - and the third port (aka <devicename>sio2</devicename>) as I/O - 0x3E8 and IRQ 5. Obviously this is a waste of IRQ resources, as - it should be basically possible to run both extension board ports - using a single IRQ with the <literal>COM_MULTIPORT</literal> - configuration described in the previous sections.</para> - - <para>Such cheap I/O boards commonly have a 4 by 3 jumper matrix for - the COM ports, similar to the following:</para> - -<programlisting> o o o * -Port A | - o * o * -Port B | - o * o o -IRQ 2 3 4 5</programlisting> - - <para>Shown here is port A wired for IRQ 5 and port B wired for IRQ - 3. The IRQ columns on your specific board may vary—other - boards may supply jumpers for IRQs 3, 4, 5, and 7 instead.</para> - - <para>One could conclude that wiring both ports for IRQ 3 using a - handcrafted wire-made jumper covering all three connection points - in the IRQ 3 column would solve the issue, but no. You cannot - duplicate IRQ 3 because the output drivers of each UART are wired - in a <quote>totem pole</quote> fashion, so if one of the UARTs - drives IRQ 3, the output signal will not be what you would expect. - Depending on the implementation of the extension board or your - motherboard, the IRQ 3 line will continuously stay up, or always - stay low.</para> - - <para>You need to decouple the IRQ drivers for the two UARTs, so - that the IRQ line of the board only goes up if (and only if) one - of the UARTs asserts a IRQ, and stays low otherwise. The solution - was proposed by Joerg Wunsch - <email>j@ida.interface-business.de</email>: To solder up a - wired-or consisting of two diodes (Germanium or Schottky-types - strongly preferred) and a 1 kOhm resistor. Here is the schematic, - starting from the 4 by 3 jumper field above:</para> - -<programlisting> Diode - +---------->|-------+ - / | - o * o o | 1 kOhm -Port A +----|######|-------+ - o * o o | | -Port B `-------------------+ ==+== - o * o o | Ground - \ | - +--------->|-------+ -IRQ 2 3 4 5 Diode</programlisting> - - <para>The cathodes of the diodes are connected to a common point, - together with a 1 kOhm pull-down resistor. It is essential to - connect the resistor to ground to avoid floating of the IRQ line - on the bus.</para> - - <para>Now we are ready to configure a kernel. Staying with this - example, we would configure:</para> - - <programlisting># standard on-board COM1 port -device sio0 at isa? port "IO_COM1" tty flags 0x10 -# patched-up multi-I/O extension board -options COM_MULTIPORT -device sio1 at isa? port "IO_COM2" tty flags 0x205 -device sio2 at isa? port "IO_COM3" tty flags 0x205 irq 3</programlisting> - - <para>Note that the <literal>flags</literal> setting for - <devicename>sio1</devicename> and <devicename>sio2</devicename> is - truly essential; refer to - &man.sio.4; for details. (Generally, the <literal>2</literal> in - the "flags" attribute refers to <devicename>sio</devicename>2 - which holds the IRQ, and you surely want a <literal>5</literal> - low nibble.) With kernel verbose mode turned on this should yield - something similar to this:</para> - - <screen>sio0: irq maps: 0x1 0x11 0x1 0x1 -sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa -sio0: type 16550A -sio1: irq maps: 0x1 0x9 0x1 0x1 -sio1 at 0x2f8-0x2ff flags 0x205 on isa -sio1: type 16550A (multiport) -sio2: irq maps: 0x1 0x9 0x1 0x1 -sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa -sio2: type 16550A (multiport master)</screen> - - <para>Though <filename>/sys/i386/isa/sio.c</filename> is somewhat - cryptic with its use of the <quote>irq maps</quote> array above, - the basic idea is that you observe <literal>0x1</literal> in the - first, third, and fourth place. This means that the corresponding - IRQ was set upon output and cleared after, which is just what we - would expect. If your kernel does not display this behavior, most - likely there is something wrong with your wiring.</para> - </sect4> - </sect3> - - <sect3 id="cy"> - <title>Configuring the <devicename>cy</devicename> driver</title> - - <para><emphasis>Contributed by Alex Nash. 6 June - 1996.</emphasis></para> - - <para>The Cyclades multiport cards are based on the - <devicename>cy</devicename> driver instead of the usual - <devicename>sio</devicename> driver used by other multiport cards. - Configuration is a simple matter of:</para> - - <procedure> - <step> - <para>Add the <devicename>cy</devicename> device to your <link - linkend="kernelconfig-config">kernel configuration</link> - (note that your irq and iomem settings may differ).</para> - - <programlisting> -device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr</programlisting> - </step> - - <step> - <para><link linkend="kernelconfig-building">Rebuild and - install</link> the new kernel.</para> - </step> - - <step> - <para>Make the <link linkend="kernelconfig-nodes">device - nodes</link> by typing (the following example assumes an - 8-port board):</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done</userinput></screen> - </step> - - <step> - <para>If appropriate, add <link linkend="dialup">dialup</link> - entries to <link linkend="dialup-ttys">/etc/ttys</link> by - duplicating serial device (<literal>ttyd</literal>) entries and - using <literal>ttyc</literal> in place of - <literal>ttyd</literal>. For example:</para> - - <programlisting> -ttyc0 "/usr/libexec/getty std.38400" unknown on insecure -ttyc1 "/usr/libexec/getty std.38400" unknown on insecure -ttyc2 "/usr/libexec/getty std.38400" unknown on insecure -… -ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting> - </step> - - <step> - <para>Reboot with the new kernel.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Configuring the <devicename>si</devicename> driver</title> - - <para><emphasis>Contributed by &a.nsayer;. 25 March - 1998.</emphasis></para> - - <para>The Specialix SI/XIO and SX multiport cards use the - <devicename>si</devicename> driver. A single machine can - have up to 4 host cards. The following host cards - are supported:</para> - - <itemizedlist> - <listitem><para>ISA SI/XIO host card (2 versions)</para></listitem> - <listitem><para>EISA SI/XIO host card</para></listitem> - <listitem><para>PCI SI/XIO host card</para></listitem> - <listitem><para>ISA SX host card</para></listitem> - <listitem><para>PCI SX host card</para></listitem> - </itemizedlist> - - <para>Although the SX and SI/XIO host cards look markedly different, - their functionality are basically the same. The host cards do not - use I/O locations, but instead require a 32K chunk of memory. The - factory configuration for ISA cards places this at - <literal>0xd0000-0xd7fff</literal>. - They also require an IRQ. PCI cards will, of course, auto-configure - themselves.</para> - - <para>You can attach up to 4 external modules to each host card. The - external modules contain either 4 or 8 serial ports. They come in - the following varieties:</para> - - <itemizedlist> - <listitem><para>SI 4 or 8 port modules. Up to 57600 bps on each port - supported.</para></listitem> - - <listitem><para>XIO 8 port modules. Up to 115200 bps on each port - supported. One type of XIO module has 7 serial and 1 parallel - port.</para></listitem> - - <listitem><para>SXDC 8 port modules. Up to 921600 bps on each port - supported. Like XIO, a module is available with one parallel - port as well.</para></listitem> - </itemizedlist> - - <para>To configure an ISA host card, add the following line to your - <link linkend="kernelconfig-config">kernel configuration - file</link>, changing the numbers as appropriate:</para> - - <programlisting> -device si0 at isa? tty iomem 0xd0000 irq 11</programlisting> - - <para>Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards - and 11, 12 and 15 for SI/XIO ISA host cards.</para> - - <para>To configure an EISA or PCI host card, use this line:</para> - - <programlisting> -device si0</programlisting> - - <para>After adding the configuration entry, <link - linkend="kernelconfig-building"> rebuild and install</link> your - new kernel.</para> - - <para>After rebooting with the new kernel, you need to make the <link - linkend="kernelconfig-nodes"> device nodes</link> in /dev. The - <filename>MAKEDEV</filename> script will take care of this for you. - Count how many total ports you have and type:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV ttyA<replaceable>nn</replaceable> cuaA<replaceable>nn</replaceable></userinput></screen> - - <para>(where <replaceable>nn</replaceable> is the number of - ports)</para> - - <para>If you want login prompts to appear on these ports, you will - need to add lines like this to <link - linkend="dialup"><filename>/etc/ttys</filename></link>:</para> - - <programlisting> -ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure - </programlisting> - - <para>Change the terminal type as appropriate. For modems, - <userinput>dialup</userinput> or <userinput>unknown</userinput> is - fine.</para> - </sect3> - </sect2> - - <sect2> - <title>* Parallel ports</title> - - <para></para> - </sect2> - - <sect2> - <title>* Modems</title> - - <para></para> - </sect2> - - <sect2> - <title>* Network cards</title> - - <para></para> - </sect2> - - <sect2> - <title>* Keyboards</title> - - <para></para> - </sect2> - - <sect2> - <title>Mice</title> - - <para><emphasis>Contributed by Joel Sutton - <email>jsutton@bbcon.com.au</email> January 2000</emphasis></para> - - <para>FreeBSD supports a variety of different mice via the PS/2, serial - and USB ports. Most users choose to use the mouse daemon to handle - their mouse because it allows interaction in both X and on the system - console. For more information on the mouse daemon refer to - &man.moused.8;. The examples throughout this section assume that - the mouse daemon is being used.</para> - - <note> - <para>This section contains the names of specific products that the - author has confirmed will work with FreeBSD. Other similar devices - not listed may also be supported.</para> - </note> - - <sect3> - <title>PS/2</title> - - <sect4> - <title>System Configuration</title> - - <para>To ensure that your PS/2 mouse functions correctly with the - mouse daemon you will need to include the following text in - <filename>/etc/rc.conf</filename></para> - - <programlisting>moused_enable="YES" -moused_type="ps/2" -moused_port="/dev/psm0"</programlisting> - </sect4> - - <sect4> - <title>Known Compatible Devices</title> - - <itemizedlist> - <listitem> - <para>Logitech First Mouse - Three Button</para> - </listitem> - - <listitem> - <para>Microsoft Serial - PS/2 Compatible Mouse</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - <sect3> - <title>Serial</title> - - <sect4> - <title>System Configuration</title> - - <para>To ensure that your serial mouse functions correctly with the - mouse daemon you will need to include the following text in - <filename>/etc/rc.conf</filename>. This example assumes that the - mouse is connected to <devicename>COM1:</devicename> and can be - automatically recognized by the mouse daemon.</para> - - <programlisting>moused_enable="YES" -moused_type="auto" -moused_port="/dev/cuaa0"</programlisting> - - <para>See the &man.moused.8; manual page for a detailed description - of how to configure the mouse daemon to work with specific types - of serial mice.</para> - </sect4> - - <sect4> - <title>Known Compatible Devices</title> - - <itemizedlist> - <listitem> - <para>Generic Microsoft Compatible Mice</para> - </listitem> - - <listitem> - <para>Logitech First Mouse - Three Button</para> - </listitem> - - <listitem> - <para>Microsoft Serial - PS/2 Compatible Mouse</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - <sect3> - <title>USB</title> - - <sect4> - <title>System Configuration</title> - - <para>The USB device drivers are a relatively new addition to - FreeBSD and have not yet been included in the GENERIC kernel. The - following procedure is an example of how to setup the relevant - drivers on a typical system.</para> - - <procedure> - <step> - <para>Add the <devicename>ums</devicename> device to the usb - section of your <link linkend="kernelconfig-config">kernel - configuration</link>. For example: - </para> - - <programlisting>controller usb0 controller uhci0 device ums0</programlisting> - </step> - - <step> - <para><link linkend="kernelconfig-building">Rebuild and - install</link> the new kernel.</para> - </step> - - <step> - <para>Make the <link linkend="kernelconfig-nodes">device - node</link> by typing:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>sh MAKEDEV ums0</userinput></screen> - </step> - - <step> - <para>Include the following text in - <filename>/etc/rc.conf</filename> to ensure correct operation - of the mouse daemon:</para> - - <programlisting>moused_enable="YES" -moused_type="auto" -moused_port="/dev/ums0"</programlisting> - </step> - - <step> - <para>Reboot the system.</para> - <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> - </step> - </procedure> - </sect4> - - <sect4> - <title>Known Compatible Devices</title> - - <itemizedlist> - <listitem> - <para>Logitech TrackMan - Marble Wheel</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - </sect2> - -<![ %not.published; [ - - <sect2> - <title>* Other</title> - - <para></para> - </sect2> - </sect1> - -]]> - - <sect1 id="hw-storage"> - <title>Storage Devices</title> - - <sect2 id="esdi"> - <title>Using ESDI hard disks</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. 24 - September 1995.</emphasis></para> - - <para>ESDI is an acronym that means Enhanced Small Device Interface. It - is loosely based on the good old ST506/412 interface originally - devised by Seagate Technology, the makers of the first affordable - 5.25" winchester disk.</para> - - <para>The acronym says Enhanced, and rightly so. In the first place the - speed of the interface is higher, 10 or 15 Mbits/second instead of the - 5 Mbits/second of ST412 interfaced drives. Secondly some higher level - commands are added, making the ESDI interface somewhat 'smarter' to - the operating system driver writers. It is by no means as smart as - SCSI by the way. ESDI is standardized by ANSI.</para> - - <para>Capacities of the drives are boosted by putting more sectors on - each track. Typical is 35 sectors per track, high capacity drives I - have seen were up to 54 sectors/track.</para> - - <para>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.</para> - - <sect3> - <title>Concepts of ESDI</title> - - <sect4> - <title>Physical connections</title> - - <para>The ESDI interface uses two cables connected to each drive. - One cable is a 34 pin flat cable edge connector that carries the - command and status signals from the controller to the drive and - vice-versa. The command cable is daisy chained between all the - drives. So, it forms a bus onto which all drives are - connected.</para> - - <para>The second cable is 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 its own direct connection to the - controller.</para> - - <para>To the best of my knowledge PC ESDI controllers are limited to - using a maximum of 2 drives per controller. This is compatibility - feature(?) left over from the WD1003 standard that reserves only a - single bit for device addressing.</para> - </sect4> - - <sect4> - <title>Device addressing</title> - - <para>On each command cable a maximum of 7 devices and 1 controller - can be present. To enable the controller to uniquely identify - which drive it addresses, each ESDI device is equipped with - jumpers or switches to select the devices address.</para> - - <para>On PC type controllers the first drive is set to address 0, - the second disk to address 1. <emphasis>Always make - sure</emphasis> you 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.</para> - </sect4> - - <sect4> - <title>Termination</title> - - <para>The daisy chained command cable (the 34 pin cable remember?) - needs to be terminated at the last drive on the chain. For this - purpose ESDI drives come with a termination resistor network that - can be removed or disabled by a jumper when it is not used.</para> - - <para>So, one and <emphasis>only</emphasis> one drive, the one at - the farthest end of the command 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 - <emphasis>not</emphasis> in the middle.</para> - </sect4> - </sect3> - - <sect3> - <title>Using ESDI disks with FreeBSD</title> - - <para>Why is ESDI such a pain to get working in the first - place?</para> - - <para>People who tried ESDI disks with FreeBSD are known to have - developed a profound sense of frustration. A combination of factors - works against you to produce effects that are hard to understand - when you have never seen them before.</para> - - <para>This has also led to the popular legend ESDI and FreeBSD is a - plain NO-GO. The following sections try to list all the pitfalls - and solutions.</para> - - <sect4> - <title>ESDI speed variants</title> - - <para>As briefly mentioned before, ESDI comes in two speed flavors. - The older drives and controllers use a 10 Mbits/second data - transfer rate. Newer stuff uses 15 Mbits/second.</para> - - <para>It is not hard to imagine that 15 Mbits/second drive cause - problems on controllers laid out for 10 Mbits/second. As always, - consult your controller <emphasis>and</emphasis> drive - documentation to see if things match.</para> - </sect4> - - <sect4> - <title>Stay on track</title> - - <para>Mainstream ESDI drives use 34 to 36 sectors per track. Most - (older) controllers cannot handle more than this number of - sectors. Newer, higher capacity, drives use higher numbers of - sectors per track. For instance, I own a 670 MB drive that has 54 - sectors per track.</para> - - <para>In my case, the controller could not handle this number of - sectors. It proved to work well except that it only used 35 - sectors on each track. This meant losing a lot of disk - space.</para> - - <para>Once again, check the documentation of your hardware for more - info. Going out-of-spec like in the example might or might not - work. Give it a try or get another more capable - controller.</para> - </sect4> - - <sect4> - <title>Hard or soft sectoring</title> - - <para>Most ESDI drives allow hard or soft sectoring to be selected - using a jumper. Hard sectoring means that the drive will produce - a sector pulse on the start of each new sector. The controller - uses this pulse to tell when it should start to write or - read.</para> - - <para>Hard sectoring allows a selection of sector size (normally - 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 - byte sectors. The number of sectors per track also varies while - still using the same number of bytes per formatted sector. The - number of <emphasis>unformatted</emphasis> bytes per sector - varies, dependent on your controller it needs more or less - overhead bytes to work correctly. Pushing more sectors on a - track of course gives you more usable space, but might give - problems if your controller needs more bytes than the drive - offers.</para> - - <para>In case of soft sectoring, the controller itself determines - where to start/stop reading or writing. For ESDI hard sectoring - is the default (at least on everything I came across). I never - felt the urge to try soft sectoring.</para> - - <para>In general, experiment with sector settings before you install - FreeBSD because you need to re-run the low-level format after each - change.</para> - </sect4> - - <sect4> - <title>Low level formatting</title> - - <para>ESDI drives need to be low level formatted before they are - usable. A reformat is needed whenever you figgle with the number - of sectors/track jumpers or the physical orientation of the drive - (horizontal, vertical). So, first think, then format. The format - time must not be underestimated, for big disks it can take - hours.</para> - - <para>After a low level format, a surface scan is done to find and - flag bad sectors. Most disks have a manufacturer bad block list - listed on a piece of paper or adhesive sticker. In addition, on - most disks the list is also written onto the disk. Please use the - manufacturer's list. It is much easier to remap a defect now than - after FreeBSD is installed.</para> - - <para>Stay away from low-level formatters that mark all sectors of a - track as bad as soon as they find one bad sector. Not only does - this waste space, it also and more importantly causes you grief - with bad144 (see the section on bad144).</para> - </sect4> - - <sect4> - <title>Translations</title> - - <para>Translations, although not exclusively a ESDI-only problem, - might give you real trouble. Translations come in multiple - flavors. Most of them have in common that they attempt to work - around the limitations posed upon disk geometries by the original - IBM PC/AT design (thanks IBM!).</para> - - <para>First of all there is the (in)famous 1024 cylinder limit. For - a system to be able to boot, the stuff (whatever operating system) - must be in the first 1024 cylinders of a disk. Only 10 bits are - available to encode the cylinder number. For the number of - sectors the limit is 64 (0-63). When you combine the 1024 - cylinder limit with the 16 head limit (also a design feature) you - max out at fairly limited disk sizes.</para> - - <para>To work around this problem, the manufacturers of ESDI PC - controllers added a BIOS prom extension on their boards. This - BIOS extension handles disk I/O for booting (and for some - operating systems <emphasis>all</emphasis> disk I/O) by using - translation. For instance, a big drive might be presented to the - system as having 32 heads and 64 sectors/track. 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 does not use the BIOS after its - kernel has started. More on this later.</para> - - <para>A second reason for translations is the fact that most older - system BIOSes could only handle drives with 17 sectors per track - (the old ST412 standard). Newer system BIOSes usually have a - user-defined drive type (in most cases this is drive type - 47).</para> - - <warning> - <para>Whatever you do to translations after reading this document, - keep in mind that if you have multiple operating systems on the - same disk, all must use the same translation</para> - </warning> - - <para>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 - controller wrote this info onto the disk. On power-up it read the - info and presented itself to the system based on the info from the - disk.</para> - </sect4> - - <sect4> - <title>Spare sectoring</title> - - <para>Most ESDI controllers offer the possibility to remap bad - sectors. During/after the low-level format of the disk bad - sectors are marked as such, and a replacement sector is put in - place (logically of course) of the bad one.</para> - - <para>In most cases the remapping is done by using N-1 sectors on - each track for actual data storage, and sector N itself is the - spare sector. N is the total number of sectors physically - available on the track. The idea behind this is that the - operating system sees a 'perfect' disk without bad sectors. In - the case of FreeBSD this concept is not usable.</para> - - <para>The problem is that the translation from - <emphasis>bad</emphasis> to <emphasis>good</emphasis> is performed - by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit - operating system, does not use the BIOS after it has been booted. - Instead, it has device drivers that talk directly to the - hardware.</para> - - <para><emphasis>So: don't use spare sectoring, bad block remapping - or whatever it may be called by the controller manufacturer when - you want to use the disk for FreeBSD.</emphasis></para> - </sect4> - - <sect4> - <title>Bad block handling</title> - - <para>The preceding section leaves us with a problem. The - controller's bad block handling is not usable and still FreeBSD's - filesystems assume perfect media without any flaws. To solve this - problem, FreeBSD use the <command>bad144</command> tool. Bad144 - (named after a Digital Equipment standard for bad block handling) - scans a FreeBSD slice for bad blocks. Having found these bad - blocks, it writes a table with the offending block numbers to the - end of the FreeBSD slice.</para> - - <para>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 <command>bad144</command> list, a - replacement block (also from the end of the FreeBSD slice) is - used. In this way, the <command>bad144</command> replacement - scheme presents 'perfect' media to the FreeBSD filesystems.</para> - - <para>There are a number of potential pitfalls associated with the - use of <command>bad144</command>. First of all, the slice cannot - have more than 126 bad sectors. If your drive has a high number - of bad sectors, you might need to divide it into multiple FreeBSD - slices each containing less than 126 bad sectors. Stay away from - low-level format programs that mark <emphasis>every</emphasis> - sector of a track as bad when they find a flaw on the track. As - you can imagine, the 126 limit is quickly reached when the - low-level format is done this way.</para> - - <para>Second, if the slice contains the root filesystem, the slice - should be within the 1024 cylinder BIOS limit. During the boot - process the bad144 list is read using the BIOS and this only - succeeds when the list is within the 1024 cylinder limit.</para> - - <note> - <para>The restriction is not that only the root - <emphasis>filesystem</emphasis> must be within the 1024 cylinder - limit, but rather the entire <emphasis>slice</emphasis> that - contains the root filesystem.</para> - </note> - </sect4> - - <sect4> - <title>Kernel configuration</title> - - <para>ESDI disks are handled by the same <literal>wd</literal>driver - as IDE and ST412 MFM disks. The <literal>wd</literal> driver - should work for all WD1003 compatible interfaces.</para> - - <para>Most hardware is jumperable for one of two different I/O - address ranges and IRQ lines. This allows you to have two wd - type controllers in one system.</para> - - <para>When your hardware allows non-standard strappings, you can use - these with FreeBSD as long as you enter the correct info into the - kernel config file. An example from the kernel config file (they - live in <filename>/sys/i386/conf</filename> BTW).</para> - - <programlisting> -# First WD compatible controller -controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr -disk wd0 at wdc0 drive 0 -disk wd1 at wdc0 drive 1 -# Second WD compatible controller -controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr -disk wd2 at wdc1 drive 0 -disk wd3 at wdc1 drive 1</programlisting> - </sect4> - </sect3> - - <sect3> - <title>Particulars on ESDI hardware</title> - - <sect4> - <title>Adaptec 2320 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a ACB-2320. No other operating system was present on the - disk.</para> - - <para>To do so I low level formatted the disk using - <command>NEFMT.EXE</command> (<command>ftp</command>able from - <hostid role="fqdn">www.adaptec.com</hostid>) and answered NO to - the question whether the disk should be formatted with a spare - sector on each track. The BIOS on the ACD-2320 was disabled. I - used the <literal>free configurable</literal> option in the system - BIOS to allow the BIOS to boot it.</para> - - <para>Before using <command>NEFMT.EXE</command> I tried to format - the disk using the ACB-2320 BIOS built-in formatter. This proved - to be a show stopper, because it did not give me an option to - disable spare sectoring. With spare sectoring enabled the FreeBSD - installation process broke down on the <command>bad144</command> - run.</para> - - <para>Please check carefully which - ACB-232<replaceable>xy</replaceable> variant you have. The - <replaceable>x</replaceable> is either <literal>0</literal> or - <literal>2</literal>, indicating a controller without or with a - floppy controller on board.</para> - - <para>The <literal>y</literal> is more interesting. It can either - be a blank, a <literal>A-8</literal> or a <literal>D</literal>. A - blank indicates a plain 10 Mbits/second controller. An - <literal>A-8</literal> indicates a 15 Mbits/second controller - capable of handling 52 sectors/track. A <literal>D</literal> - means a 15 Mbits/second controller that can also handle drives - with > 36 sectors/track (also 52 ?).</para> - - <para>All variations should be capable of using 1:1 interleaving. - Use 1:1, FreeBSD is fast enough to handle it.</para> - </sect4> - - <sect4> - <title>Western Digital WD1007 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a WD1007 controller. To be precise, it was a WD1007-WA2. - Other variations of the WD1007 do exist.</para> - - <para>To get it to work, I had to disable the sector translation and - the WD1007's onboard BIOS. This implied I could not use the - low-level formatter built into this BIOS. Instead, I grabbed - <command>WDFMT.EXE</command> from <hostid - role="fqdn">www.wdc.com</hostid> Running this formatted my drive - just fine.</para> - </sect4> - - <sect4> - <title>Ultrastor U14F controllers</title> - - <para>According to multiple reports from the net, Ultrastor ESDI - boards work OK with FreeBSD. I lack any further info on - particular settings.</para> - </sect4> - </sect3> - - <sect3 id="esdi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious ESDI hacking, you might want to - have the official standard at hand:</para> - - <para>The latest ANSI X3T10 committee document is: Enhanced Small - Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D - Rev 11]</para> - - <para>On Usenet the newsgroup <ulink - url="news:comp.periphs">comp.periphs</ulink> is a noteworthy place - to look for more info.</para> - - <para>The World Wide Web (WWW) also proves to be a very handy info - source: For info on Adaptec ESDI controllers see <ulink - url="http://www.adaptec.com/">http://www.adaptec.com/</ulink>. For - info on Western Digital controllers see <ulink - url="http://www.wdc.com/">http://www.wdc.com/</ulink>.</para> - </sect3> - - <sect3> - <title>Thanks to...</title> - - <para>Andrew Gordon for sending me an Adaptec 2320 controller and ESDI - disk for testing.</para> - </sect3> - </sect2> - - <sect2 id="scsi"> - <title>What is SCSI?</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. July 6, - 1996.</emphasis></para> - - <para>SCSI is an acronym for Small Computer Systems Interface. It is an - ANSI standard that has become one of the leading I/O buses in the - computer industry. The foundation of the SCSI standard was laid by - Shugart Associates (the same guys that gave the world the first mini - floppy disks) when they introduced the SASI bus (Shugart Associates - Standard Interface).</para> - - <para>After some time an industry effort was started to come to a more - strict standard allowing devices from different vendors to work - together. This effort was recognized in the ANSI SCSI-1 standard. - The SCSI-1 standard (approximately 1985) is rapidly becoming obsolete. The - current standard is SCSI-2 (see <link - linkend="scsi-further-reading">Further reading</link>), with SCSI-3 - on the drawing boards.</para> - - <para>In addition to a physical interconnection standard, SCSI defines a - logical (command set) standard to which disk devices must adhere. - This standard is called the Common Command Set (CCS) and was developed - more or less in parallel with ANSI SCSI-1. SCSI-2 includes the - (revised) CCS as part of the standard itself. The commands are - dependent on the type of device at hand. It does not make much sense - of course to define a Write command for a scanner.</para> - - <para>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 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 allows a maximum bus width of 32 - bits, using an additional cable. Quickly emerging are Ultra SCSI (also - called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 - million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 - is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). - Most hard drives sold today are single-ended Ultra SCSI (8 or 16 - bits).</para> - - <para>Of course the SCSI bus not only has data lines, but also a number - of control signals. A very elaborate protocol is part of the standard - to allow multiple devices to share the bus in an efficient manner. In - SCSI-2, the data is always checked using a separate parity line. In - pre-SCSI-2 designs parity was optional.</para> - - <para>In SCSI-3 even faster bus types are introduced, along with a - serial SCSI busses that reduces the cabling overhead and allows a - higher maximum bus length. You might see names like SSA and - fibre channel in this context. None of the serial buses are currently - in widespread use (especially not in the typical FreeBSD environment). - For this reason the serial bus types are not discussed any - further.</para> - - <para>As you could have guessed from the description above, SCSI devices - are intelligent. They have to be to adhere to the SCSI standard - (which is over 2 inches thick BTW). So, for a hard disk drive for - instance you do not specify a head/cylinder/sector to address a - particular block, but simply the number of the block you want. - Elaborate caching schemes, automatic bad block replacement etc are all - made possible by this 'intelligent device' approach.</para> - - <para>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.</para> - - <para>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. 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.</para> - - <para>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 implies that you do not 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. From a performance - standpoint you might want to separate your older and newer (=faster) - devices however.</para> - - <sect3> - <title>Components of SCSI</title> - - <para>As said before, SCSI devices are smart. The idea is to put the - knowledge about intimate hardware details onto the SCSI device - itself. In this way, the host system does not have to worry about - things like how many heads are hard disks has, or how many tracks - there are on a specific tape device. If you are curious, the - standard specifies commands with which you can query your devices on - their hardware particulars. FreeBSD uses this capability during - boot to check out what devices are connected and whether they need - any special treatment.</para> - - <para>The advantage of intelligent devices is obvious: the device - drivers on the host can be made in a much more generic fashion, - there is no longer a need to change (and qualify!) drivers for every - odd new device that is introduced.</para> - - <para>For cabling and connectors there is a golden rule: get good - stuff. With bus speeds going up all the time you will save yourself - a lot of grief by using good material.</para> - - <para>So, gold plated connectors, shielded cabling, sturdy connector - hoods with strain reliefs etc are the way to go. Second golden 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 by 1 meter solved the problem. And the original bus - length was well within the SCSI specification.</para> - </sect3> - - <sect3> - <title>SCSI bus types</title> - - <para>From an electrical point of view, there are two incompatible bus - types: single-ended and differential. This means that there are two - different main groups of SCSI devices and controllers, which cannot - be mixed on the same bus. It is possible however to use special - converter hardware to transform a single-ended bus into a - differential one (and vice versa). The differences between the bus - types are explained in the next sections.</para> - - <para>In lots of SCSI related documentation there is a sort of jargon - in use to abbreviate the different bus types. A small list:</para> - - <itemizedlist> - <listitem> - <para>FWD: Fast Wide Differential</para> - </listitem> - - <listitem> - <para>FND: Fast Narrow Differential</para> - </listitem> - - <listitem> - <para>SE: Single Ended</para> - </listitem> - - <listitem> - <para>FN: Fast Narrow</para> - </listitem> - - <listitem> - <para>etc.</para> - </listitem> - </itemizedlist> - - - <para>With a minor amount of imagination one can usually imagine what - is meant.</para> - - <para>Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As - far as I know, the 32 bit variant is not (yet) in use, so wide - normally means 16 bit.</para> - - <para>Fast means that the timing on the bus is somewhat different, so - that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 - Mbytes/sec for 'slow' SCSI. As discussed before, bus speeds of 20 - and 40 million transfers/second are also emerging (Fast-20 == Ultra - SCSI and Fast-40 == Ultra2 SCSI).</para> - - <note> - <para>The data lines > 8 are only used for data transfers and - device addressing. The transfers of commands and status messages - etc are only performed on the lowest 8 data lines. The standard - allows narrow devices to operate on a wide bus. The usable bus - width is negotiated between the devices. You have to watch your - device addressing closely when mixing wide and narrow.</para> - </note> - - <sect4> - <title>Single ended buses</title> - - <para>A single-ended SCSI bus uses signals that are either 5 Volts - or 0 Volts (indeed, TTL levels) and are relative to a COMMON - ground reference. A singled ended 8 bit SCSI bus has - approximately 25 ground lines, who are all tied to a single `rail' - on all devices. A standard single ended bus has a maximum length - of 6 meters. If the same bus is used with fast-SCSI devices, the - maximum length allowed drops to 3 meters. Fast-SCSI means that - instead of 5Mbytes/sec the bus allows 10Mbytes/sec - transfers.</para> - - <para>Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million - transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 - bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max - bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be - aware that F20 is pushing the limits quite a bit, so you will - quickly find out if your SCSI bus is electrically sound.</para> - - <note> - <para>If some devices on your bus use 'fast' to communicate your - bus must adhere to the length restrictions for fast - buses!</para> - </note> - - <para>It is obvious that with the newer fast-SCSI devices the bus - length can become a real bottleneck. This is why the differential - SCSI bus was introduced in the SCSI-2 standard.</para> - - <para>For connector pinning and connector types please refer to the - SCSI-2 standard (see <link linkend="scsi-further-reading">Further - reading</link>) itself, connectors etc are listed there in - painstaking detail.</para> - - <para>Beware of devices using non-standard cabling. For instance - Apple uses a 25pin D-type connecter (like the one on serial ports - and parallel printers). Considering that the official SCSI bus - needs 50 pins you can imagine the use of this connector needs some - 'creative cabling'. The reduction of the number of ground wires - they used is a bad idea, you better stick to 50 pins cabling in - accordance with the SCSI standard. For Fast-20 and 40 do not even - think about buses like this.</para> - </sect4> - - <sect4> - <title>Differential buses</title> - - <para>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 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 (do not - try 10 kVolts though).</para> - - <para>It is beyond the scope of this document to explain why this - differential idea is so much better. Just accept that - electrically seen the use of differential signals gives a much - better noise margin. You will normally find differential buses in - use for inter-cabinet connections. Because of the lower cost - single ended is mostly used for shorter buses like inside - cabinets.</para> - - <para>There is nothing that stops you from using differential stuff - with FreeBSD, as long as you use a controller that has device - driver support in FreeBSD. As an example, Adaptec marketed the - AHA1740 as a single ended board, whereas the AHA1744 was - differential. The software interface to the host is identical for - both.</para> - </sect4> - - <sect4> - <title>Terminators</title> - - <para>Terminators in SCSI terminology are resistor networks that are - used to get a correct impedance matching. Impedance matching is - important to get clean signals on the bus, without reflections or - ringing. If you once made a long distance telephone call on a bad - line you probably know what reflections are. With 20Mbytes/sec - traveling over your SCSI bus, you do not want signals echoing - back.</para> - - <para>Terminators come in various incarnations, with more or less - sophisticated designs. Of course, there are internal and external - variants. Many SCSI devices come with a number of sockets in - which a number of resistor networks can (must be!) installed. If - you remove terminators from a device, 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, or a - connector hood without a cable. So, lots of choice as you can - see.</para> - - <para>There is much debate going on if and when you should switch - from simple resistor (passive) terminators to active 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 active terminator. Try to - borrow one first, they reputedly are quite expensive.</para> - - <para>Please keep in mind that terminators for differential and - single-ended buses are not identical. You should <emphasis>not - mix</emphasis> the two variants.</para> - - <para>OK, and now where should you install your terminators? This is - by far the most misunderstood part of SCSI. And it is by far the - simplest. The rule is: <emphasis>every single line on the SCSI - bus has 2 (two) terminators, one at each end of the - bus.</emphasis> So, two and not one or three or whatever. Do - yourself a favor and stick to this rule. It will save you endless - grief, because wrong termination has the potential to introduce - highly mysterious bugs. (Note the <quote>potential</quote> here; - the nastiest part is that it may or may not work.)</para> - - <para>A common pitfall is to have an internal (flat) cable in a - machine and also an external cable attached to the controller. It - seems almost everybody forgets to remove the terminators from the - controller. The terminator must now be on the last external - device, and not on the controller! In general, every - reconfiguration of a SCSI bus must pay attention to this.</para> - - <note> - <para>Termination is to be done on a per-line basis. This means - if you have both narrow and wide buses connected to the same - host adapter, you need to enable termination on the higher 8 - bits of the bus on the adapter (as well as the last devices on - each bus, of course).</para> - </note> - - <para>What I did myself is remove all terminators from my SCSI - devices and controllers. I own a couple of external terminators, - for both the Centronics-type external cabling and for the internal - flat cable connectors. This makes reconfiguration much - easier.</para> - - <para>On modern devices, sometimes integrated terminators are used. - These things are special purpose integrated circuits that can be - enabled or disabled with a control pin. It is not necessary to - physically remove them from a device. You may find them on newer - host adapters, sometimes they are software configurable, using - some sort of setup tool. Some will even auto-detect the cables - attached to the connectors and automatically set up the - termination as necessary. At any rate, consult your - documentation!</para> - </sect4> - - <sect4> - <title>Terminator power</title> - - <para>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?</para> - - <para>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 in trouble.</para> - - <para>The idea is that initiators (these are devices that initiate - actions on the bus, a discussion follows) must supply terminator - power. All SCSI devices are allowed (but not required) to supply - terminator power.</para> - - <para>To allow for un-powered devices on a bus, the terminator power - must be supplied to the bus via a diode. This prevents the - backflow of current to un-powered devices.</para> - - <para>To prevent all kinds of nastiness, the terminator power is - usually fused. As you can imagine, fuses might blow. This can, - but does not have to, lead to a non functional bus. If multiple - devices supply terminator power, a single blown fuse will not put - you out of business. A single supplier with a blown fuse - certainly will. Clever external terminators sometimes have a LED - indication that shows whether terminator power is present.</para> - - <para>In newer designs auto-restoring fuses that 'reset' themselves - after some time are sometimes used.</para> - </sect4> - - <sect4> - <title>Device addressing</title> - - <para>Because the SCSI bus is, ehh, a bus there must be a way to - distinguish or address the different devices connected to - it.</para> - - <para>This is done by means of the SCSI or target ID. Each device - has a unique target ID. You can select the ID to which a device - must respond using a set of jumpers, or a dip switch, or something - similar. Some SCSI host adapters let you change the target ID - from the boot menu. (Yet some others will not let you change the - ID from 7.) Consult the documentation of your device for more - information.</para> - - <para>Beware of multiple devices configured to use the same ID. - Chaos normally reigns in this case. A pitfall is that one of the - devices sharing the same ID sometimes even manages to answer to - I/O requests!</para> - - <para>For an 8 bit bus, a maximum of 8 targets is possible. The - maximum is 8 because the selection is done bitwise using the 8 - data lines on the bus. For wide buses this increases to the - number of data lines (usually 16).</para> - - <note> - <para>A narrow SCSI device can not communicate with a SCSI device - with a target ID larger than 7. This means it is generally not - a good idea to move your SCSI host adapter's target ID to - something higher than 7 (or your CDROM will stop - working).</para> - </note> - - <para>The higher the SCSI target ID, the higher the priority the - devices has. When it comes to arbitration between devices that - want to use the bus at the same time, the device that has the - highest SCSI ID will win. This also means that the SCSI host - adapter usually uses target ID 7. Note however that the lower 8 - IDs have higher priorities than the higher 8 IDs on a wide-SCSI - bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] - on a wide-SCSI system. (If you you are wondering why the lower 8 - have higher priority, read the previous paragraph for a - hint.)</para> - - <para>For a further subdivision, the standard allows for Logical - Units or LUNs for short. A single target ID may have multiple - LUNs. For example, a tape device including a tape changer may - have LUN 0 for the tape device itself, and LUN 1 for the tape - changer. In this way, the host system can address each of the - functional units of the tape changer as desired.</para> - </sect4> - - <sect4> - <title>Bus layout</title> - - <para>SCSI buses are linear. So, not shaped like Y-junctions, star - topologies, rings, cobwebs or whatever else people might want to - invent. One of the most common mistakes is for people with - wide-SCSI host adapters to connect devices on all three connecters - (external connector, internal wide connector, internal narrow - connector). Don't do that. It may appear to work if you are - really lucky, but I can almost guarantee that your system will - stop functioning at the most unfortunate moment (this is also - known as <quote>Murphy's law</quote>).</para> - - <para>You might notice that the terminator issue discussed earlier - becomes rather hairy if your bus is not linear. Also, if you have - more connectors than devices on your internal SCSI cable, make - sure you attach devices on connectors on both ends instead of - using the connectors in the middle and let one or both ends - dangle. This will screw up the termination of the bus.</para> - - <para>The electrical characteristics, its noise margins and - ultimately the reliability of it all are tightly related to linear - bus rule.</para> - - <para><emphasis>Stick to the linear bus rule!</emphasis></para> - </sect4> - </sect3> - - <sect3> - <title>Using SCSI with FreeBSD</title> - - <sect4> - <title>About translations, BIOSes and magic...</title> - - <para>As stated before, you should first make sure that you have a - electrically sound bus.</para> - - <para>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 - 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 - sectors per track, obscure things like precompensation and reduced - write current cylinder etc.</para> - - <para>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 in order to load the - FreeBSD kernel during boot.</para> - - <para>The SCSI host adapter or SCSI controller you have put in your - 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 present. Obvious, isn't it?</para> - - <para>The SCSI BIOS itself presents to the system a so called - <emphasis>translated</emphasis> 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 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.</para> - - <para>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 1 - GB. With disk capacities going up all the time this is causing - problems.</para> - - <para>Fortunately, the solution is simple: just use another - translation, e.g. with 128 heads instead of 32. In most cases new - SCSI BIOS versions are available to upgrade older SCSI host - adapters. Some newer adapters have an option, in the form of a - jumper or software setup selection, to switch the translation the - SCSI BIOS uses.</para> - - <para>It is very important that <emphasis>all</emphasis> operating - systems on the disk use the <emphasis>same translation</emphasis> - 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.</para> - - <para>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.</para> - - <para>You might have heard some talk of <quote>lying</quote> devices? - Older FreeBSD kernels used to report the geometry of SCSI disks - when booting. An example from one of my systems:</para> - - <screen>aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> -sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512</screen> - - <para>Newer kernels usually do not report this information. - e.g.</para> - - <screen>(bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 -sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors)</screen> - - <para>Why has this changed?</para> - - <para>This info is retrieved from the SCSI disk itself. Newer disks - often use a technique called zone bit recording. The idea is that - on the outer cylinders of the drive there is more space so more - sectors per track can be put on them. This results in disks that - have more tracks on outer cylinders than on the inner cylinders - and, last but not least, have more capacity. You can imagine that - the value reported by the drive when inquiring about the geometry - now becomes 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 <emphasis>if the BIOS is never going - to know about this disk</emphasis>, (e.g. it is not a booting - disk) to supply a fictitious geometry that is convenient.</para> - </sect4> - - <sect4> - <title>SCSI subsystem design</title> - - <para>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 its commands and reports back any status.</para> - - <para>On top of the card drivers there are a number of more generic - drivers for a class of devices. More specific: a driver for tape - devices (abbreviation: st), magnetic disks (sd), CDROMs (cd) etc. - In case you are wondering where you can find this stuff, it all - lives in <filename>/sys/scsi</filename>. See the man pages in - section 4 for more details.</para> - - <para>The multi level design allows a decoupling of low-level bit - banging and more high level stuff. Adding support for another - piece of hardware is a much more manageable problem.</para> - </sect4> - - <sect4> - <title>Kernel configuration</title> - - <para>Dependent on your hardware, the kernel configuration file must - contain one or more lines describing your host adapter(s). This - includes I/O addresses, interrupts etc. Consult the man page for - your adapter driver to get more info. Apart from that, check out - <filename>/sys/i386/conf/LINT</filename> for an overview of a - kernel config file. <filename>LINT</filename> contains every - possible option you can dream of. It does - <emphasis>not</emphasis> imply <filename>LINT</filename> will - actually get you to a working kernel at all.</para> - - <para>Although it is probably stating the obvious: the kernel config - file should reflect your actual hardware setup. So, interrupts, - I/O addresses etc must match the kernel config file. During - system boot messages will be displayed to indicate whether the - configured hardware was actually found.</para> - - <note> - <para>Note that most of the EISA/PCI drivers (namely - <devicename>ahb</devicename>, <devicename>ahc</devicename>, - <devicename>ncr</devicename> and <devicename>amd</devicename> - will automatically obtain the correct parameters from the host - adapters themselves at boot time; thus, you just need to write, - for instance, <literal>controller ahc0</literal>.</para> - </note> - - <para>An example loosely based on the FreeBSD 2.2.5-Release kernel - config file <filename>LINT</filename> with some added comments - (between []):</para> - - <programlisting> -# SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' -# -# aha: Adaptec 154x -# ahb: Adaptec 174x -# ahc: Adaptec 274x/284x/294x -# aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) -# amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) -# bt: Most Buslogic controllers -# nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 -# ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards -# uha: UltraStore 14F and 34F -# sea: Seagate ST01/02 8 bit controller (slow!) -# wds: Western Digital WD7000 controller (no scatter/gather!). -# - -[For an Adaptec AHA274x/284x/294x/394x etc controller] -controller ahc0 - -[For an NCR/Symbios 53c875 based controller] -controller ncr0 - -[For an Ultrastor adapter] -controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr - -# Map SCSI buses to specific SCSI adapters -controller scbus0 at ahc0 -controller scbus2 at ncr0 -controller scbus1 at uha0 - -# The actual SCSI devices -disk sd0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] -disk sd1 at scbus0 target 1 [implicit LUN 0 if omitted] -disk sd2 at scbus1 target 3 [SCSI disk on the uha0] -disk sd3 at scbus2 target 4 [SCSI disk on the ncr0] -tape st1 at scbus0 target 6 [SCSI tape at target 6] -device cd0 at scbus? [the first ever CDROM found, no wiring]</programlisting> - - <para>The example above tells the kernel to look for a ahc (Adaptec - 274x) controller, then for an NCR/Symbios board, and so on. The - lines following the controller specifications tell the kernel to - configure specific devices but <emphasis>only</emphasis> attach - them when they match the target ID and LUN specified on the - corresponding bus.</para> - - <para>Wired down devices get <quote>first shot</quote> at the unit - numbers so the first non <quote>wired down</quote> device, is - allocated the unit number one greater than the highest - <quote>wired down</quote> 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.</para> - - <note> - <para>Wired down devices need not be found 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 - <emphasis>no</emphasis> relationship with its target ID on the - SCSI bus.</para> - </note> - - <para>Below is another example of a kernel config file as used by - FreeBSD version < 2.0.5. The difference with the first example - is that devices are not <quote>wired down</quote>. <quote>Wired - down</quote> means that you specify which SCSI target belongs to - which device.</para> - - <para>A kernel built to the config file below will attach 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 <filename>/etc/fstab</filename> each time.</para> - - <para>Although the old style still works, you are - <emphasis>strongly</emphasis> recommended to use this new feature. - It will save you a lot of grief whenever you shift your hardware - around on the SCSI buses. So, when you re-use your old trusty - config file after upgrading from a pre-FreeBSD2.0.5.R system check - this out.</para> - - <programlisting> -[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 st0 [support for 2 SCSI tapes] - -[for the CDROM] -device cd0 #Only need one of these, the code dynamically grows</programlisting> - - <para>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 simply allocate more - devices, incrementing the unit number starting at the last number - <quote>wired down</quote>. If there are no <quote>wired - down</quote> devices then counting starts at unit 0.</para> - - <para>Use <command>man 4 scsi</command> to check for the latest info - on the SCSI subsystem. For more detailed info on host adapter - drivers use e.g., <command>man 4 ahc</command> for info on the - Adaptec 294x driver.</para> - </sect4> - - <sect4> - <title>Tuning your SCSI kernel setup</title> - - <para>Experience has shown that some devices are slow to respond to - INQUIRY 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.</para> - - <para>To work around the 'slow response' 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:</para> - - <programlisting> -options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device</programlisting> - - <para>This line sets the delay time to 15 seconds. On my own system - I had to use 3 seconds minimum to get my trusty old CDROM drive - to be recognized. Start with a high value (say 30 seconds or so) - when you have problems with device recognition. If this helps, - tune it back until it just stays working.</para> - </sect4> - - <sect4 id="scsi-rogue-devices"> - <title>Rogue SCSI devices</title> - - <para>Although the SCSI standard tries to be complete and concise, - it is a complex standard and implementing things correctly is no - easy task. Some vendors do a better job then others.</para> - - <para>This is exactly where the <quote>rogue</quote> devices come - into view. Rogues are devices that are recognized by the FreeBSD - kernel as behaving slightly (...) non-standard. Rogue devices are - reported by the kernel when booting. An example for two of my - cartridge tape units:</para> - - <screen>Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> -Feb 25 21:03:34 yedi /kernel: st0: Tandberg tdc3600 is a known rogue - -Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> -Mar 29 21:16:37 yedi /kernel: st1: Archive Viper 150 is a known rogue </screen> - - <para>For instance, there are devices that respond to all LUNs on a - certain target ID, even if they are actually only one device. It - is easy to see that the kernel might be fooled into believing that - there are 8 LUNs at that particular target ID. The confusion this - causes is left as an exercise to the reader.</para> - - <para>The SCSI subsystem of FreeBSD recognizes devices with bad - habits by looking at the INQUIRY response they send when probed. - Because the INQUIRY response also includes the version number of - the device firmware, it is even possible that for different - firmware versions different workarounds are used. See e.g. - <filename>/sys/scsi/st.c</filename> and - <filename>/sys/scsi/scsiconf.c</filename> for more info on how - this is done.</para> - - <para>This scheme works fine, but keep in mind that it of course - only works for devices that are known to be weird. If you are the - first to connect your bogus Mumbletech SCSI CDROM you might be - the one that has to define which workaround is needed.</para> - - <para>After you got your Mumbletech working, please send the - required workaround to the FreeBSD development team for inclusion - in the next release of FreeBSD. Other Mumbletech owners will be - grateful to you.</para> - </sect4> - - <sect4> - <title>Multiple LUN devices</title> - - <para>In some cases you come across devices that use multiple - logical units (LUNs) on a single SCSI ID. In most cases FreeBSD - only probes devices for LUN 0. An example are so called bridge - boards that connect 2 non-SCSI harddisks to a SCSI bus (e.g. an - Emulex MD21 found in old Sun systems).</para> - - <para>This means that any devices with LUNs != 0 are not normally - found during device probe on system boot. To work around this - problem you must add an appropriate entry in /sys/scsi/scsiconf.c - and rebuild your kernel.</para> - - <para>Look for a struct that is initialized like below:</para> - - <programlisting> -{ - T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", - "mx1", SC_ONE_LU -}</programlisting> - - <para>For you Mumbletech BRIDGE2000 that has more than one LUN, acts - as a SCSI disk and has firmware revision 123 you would add - something like:</para> - - <programlisting> -{ - T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", - "sd", SC_MORE_LUS -}</programlisting> - - <para>The kernel on boot scans the inquiry data it receives against - the table and acts accordingly. See the source for more - info.</para> - </sect4> - - <sect4> - <title>Tagged command queuing</title> - - <para>Modern SCSI devices, particularly magnetic disks, - support what is called tagged command queuing (TCQ).</para> - - <para>In a nutshell, TCQ allows the device to have multiple I/O - requests outstanding at the same time. Because the device is - intelligent, it can optimize its operations (like head - positioning) based on its own request queue. On SCSI devices - like RAID (Redundant Array of Independent Disks) arrays the TCQ - function is indispensable to take advantage of the device's - inherent parallelism.</para> - - <para>Each I/O request is uniquely identified by a <quote>tag</quote> - (hence the name tagged command queuing) and this tag is used by - FreeBSD to see which I/O in the device drivers queue is reported - as complete by the device.</para> - - <para>It should be noted however that TCQ requires device driver - support and that some devices implemented it <quote>not quite - right</quote> in their firmware. This problem bit me once, and it - leads to highly mysterious problems. In such cases, try to - disable TCQ.</para> - </sect4> - - <sect4> - <title>Busmaster host adapters</title> - - <para>Most, but not all, SCSI host adapters are bus mastering - controllers. This means that they can do I/O on their own without - putting load onto the host CPU for data movement.</para> - - <para>This is of course an advantage for a multitasking operating - system like FreeBSD. It must be noted however that there might be - some rough edges.</para> - - <para>For instance an Adaptec 1542 controller can be set to use - different transfer speeds on the host bus (ISA or AT in this - case). The controller is settable to different rates because not - all motherboards can handle the higher speeds. Problems like - hang-ups, bad data etc might be the result of using a higher data - transfer rate then your motherboard can stomach.</para> - - <para>The solution is of course obvious: switch to a lower data - transfer rate and try if that works better.</para> - - <para>In the case of a Adaptec 1542, there is an option that can be - put into the kernel config file to allow dynamic determination of - the right, read: fastest feasible, transfer rate. This option is - disabled by default:</para> - - <programlisting> -options "TUNE_1542" #dynamic tune of bus DMA speed</programlisting> - - <para>Check the man pages for the host adapter that you use. Or - better still, use the ultimate documentation (read: driver - source).</para> - </sect4> - </sect3> - - <sect3> - <title>Tracking down problems</title> - - <para>The following list is an attempt to give a guideline for the - most common SCSI problems and their solutions. It is by no means - complete.</para> - - <itemizedlist> - <listitem> - <para>Check for loose connectors and cables.</para> - </listitem> - - <listitem> - <para>Check and double check the location and number of your - terminators.</para> - </listitem> - - <listitem> - <para>Check if your bus has at least one supplier of terminator - power (especially with external terminators.</para> - </listitem> - - <listitem> - <para>Check if no double target IDs are used.</para> - </listitem> - - <listitem> - <para>Check if all devices to be used are powered up.</para> - </listitem> - - <listitem> - <para>Make a minimal bus config with as little devices as - possible.</para> - </listitem> - - <listitem> - <para>If possible, configure your host adapter to use slow bus - speeds.</para> - </listitem> - - <listitem> - <para>Disable tagged command queuing to make things as simple as - possible (for a NCR host adapter based system see man - ncrcontrol)</para> - </listitem> - - <listitem> - <para>If you can compile a kernel, make one with the - <literal>SCSIDEBUG</literal> 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 <filename>/sys/scsi/scsidebug.h</filename>. If it - probes but just does not work, you can use the - &man.scsi.8; command to dynamically set a debug level to - it in a running kernel (if <literal>SCSIDEBUG</literal> is - defined). This will give you <emphasis>copious</emphasis> - debugging output with which to confuse the gurus. See - <command>man 4 scsi</command> for more exact information. Also - look at <command>man 8 scsi</command>.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="scsi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious SCSI hacking, you might want to - have the official standard at hand:</para> - - <para>Approved American National Standards can be purchased from - ANSI at - - <address> - <otheraddr>13th Floor</otheraddr> - <street>11 West 42nd Street</street> - <city>New York</city> - <state>NY</state> <postcode>10036</postcode> - Sales Dept: <phone>(212) 642-4900</phone> - </address> - </para> - - <para>You can also buy many ANSI - standards and most committee draft documents from Global - Engineering Documents, - - <address> - <street>15 Inverness Way East</street> - <city>Englewood</city> - <state>CO</state>, <postcode>80112-5704</postcode> - Phone: <phone>(800) 854-7179</phone> - Outside USA and Canada: <phone>(303) 792-2181</phone> - Fax: <fax>(303) 792- 2192</fax> - </address> - </para> - - <para>Many X3T10 draft documents are available electronically on the - SCSI BBS (719-574-0424) and on the <hostid - role="fqdn">ncrinfo.ncr.com</hostid> anonymous ftp site.</para> - - <para>Latest X3T10 committee documents are:</para> - - <itemizedlist> - <listitem> - <para>AT Attachment (ATA or IDE) [X3.221-1994] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>ATA Extensions (ATA-2) [X3T10/948D Rev 2i]</para> - </listitem> - - <listitem> - <para>Enhanced Small Device Interface (ESDI) - [X3.170-1990/X3.170a-1991] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>Small Computer System Interface — 2 (SCSI-2) - [X3.131-1994] (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>SCSI-2 Common Access Method Transport and SCSI Interface - Module (CAM) [X3T10/792D Rev 11]</para> - </listitem> - </itemizedlist> - - <para>Other publications that might provide you with additional - information are:</para> - - <itemizedlist> - <listitem> - <para><quote>SCSI: Understanding the Small Computer System - Interface</quote>, written by NCR Corporation. Available from: - Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 - ISBN 0-13-796855-8</para> - </listitem> - - <listitem> - <para><quote>Basics of SCSI</quote>, a SCSI tutorial written by - Ancot Corporation Contact Ancot for availability information at: - Phone: (415) 322-5322 Fax: (415) 322-0455</para> - </listitem> - - <listitem> - <para><quote>SCSI Interconnection Guide Book</quote>, an AMP - publication (dated 4/93, Catalog 65237) that lists the various - SCSI connectors and suggests cabling schemes. Available from - AMP at (800) 522-6752 or (717) 564-0100</para> - </listitem> - - <listitem> - <para><quote>Fast Track to SCSI</quote>, A Product Guide written by - Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, - 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X</para> - </listitem> - - <listitem> - <para><quote>The SCSI Bench Reference</quote>, <quote>The SCSI - Encyclopedia</quote>, and the <quote>SCSI Tutor</quote>, ENDL - Publications, 14426 Black Walnut Court, Saratoga CA, 95070 - Phone: (408) 867-6642</para> - </listitem> - - <listitem> - <para><quote>Zadian SCSI Navigator</quote> (quick ref. book) and - <quote>Discover the Power of SCSI</quote> (First book along with - a one-hour video and tutorial book), Zadian Software, Suite 214, - 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800</para> - </listitem> - </itemizedlist> - - <para>On Usenet the newsgroups <ulink - url="news:comp.periphs.scsi">comp.periphs.scsi</ulink> and <ulink - url="news:comp.periphs">comp.periphs</ulink> are noteworthy places - to look for more info. You can also find the SCSI-Faq there, which - is posted periodically.</para> - - <para>Most major SCSI device and host adapter suppliers operate ftp - sites and/or BBS systems. They may be valuable sources of - information about the devices you own.</para> - </sect3> - </sect2> - - <sect2 id="hw-storage-controllers"> - <title>* Disk/tape controllers</title> - - <sect3> - <title>* SCSI</title> - - <para></para> - </sect3> - - <sect3> - <title>* IDE</title> - - <para></para> - </sect3> - - <sect3> - <title>* Floppy</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>Hard drives</title> - - <sect3> - <title>SCSI hard drives</title> - - <para><emphasis>Contributed by &a.asami;. 17 February - 1998.</emphasis></para> - - <para>As mentioned in the <link linkend="scsi">SCSI</link> section, - virtually all SCSI hard drives sold today are SCSI-2 compliant and - thus will work fine as long as you connect them to a supported SCSI - host adapter. Most problems people encounter are either due to - badly designed cabling (cable too long, star topology, etc.), - insufficient termination, or defective parts. Please refer to the - <link linkend="scsi">SCSI</link> section first if your SCSI hard - drive is not working. However, there are a couple of things you may - want to take into account before you purchase SCSI hard drives for - your system.</para> - - <sect4> - <title>Rotational speed</title> - - <para>Rotational speeds of SCSI drives sold today range from around - 4,500RPM to 10,000RPM. Most of them are either 5,400RPM or - 7,200RPM. Even though the 7,200RPM drives can generally transfer - data faster, they run considerably hotter than their 5,400RPM - counterparts. A large fraction of today's disk drive malfunctions - are heat-related. If you do not have very good cooling in your PC - case, you may want to stick with 5,400RPM or slower drives.</para> - - <para>Note that newer drives, with higher areal recording densities, - can deliver much more bits per rotation than older ones. Today's - top-of-line 5,400RPM drives can sustain a throughput comparable to - 7,200RPM drives of one or two model generations ago. The number - to find on the spec sheet for bandwidth is <quote>internal data - (or transfer) rate</quote>. It is usually in megabits/sec so - divide it by 8 and you'll get the rough approximation of how much - megabytes/sec you can get out of the drive.</para> - - <para>(If you are a speed maniac and want a 10,000RPM drive for your - cute little PC, be my guest; however, those drives become - extremely hot. Don't even think about it if you don't have a fan - blowing air <emphasis>directly at</emphasis> the drive or a - properly ventilated disk enclosure.)</para> - - <para>Obviously, the latest 10,000RPM drives and 7,200RPM drives can - deliver more data than the latest 5,400RPM drives, so if absolute - bandwidth is the necessity for your applications, you have little - choice but to get the faster drives. Also, if you need low - latency, faster drives are better; not only do they usually have - lower average seek times, but also the rotational delay is one - place where slow-spinning drives can never beat a faster one. - (The average rotational latency is half the time it takes to - rotate the drive once; thus, it's 3 milliseconds for 10,000RPM - drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) - Latency is seek time plus rotational delay. Make sure you - understand whether you need low latency or more accesses per - second, though; in the latter case (e.g., news servers), it may - not be optimal to purchase one big fast drive. You can achieve - similar or even better results by using the ccd (concatenated - disk) driver to create a striped disk array out of multiple slower - drives for comparable overall cost.</para> - - <para>Make sure you have adequate air flow around the drive, - especially if you are going to use a fast-spinning drive. You - generally need at least 1/2" (1.25cm) of spacing above and below a - drive. Understand how the air flows through your PC case. Most - cases have the power supply suck the air out of the back. See - where the air flows in, and put the drive where it will have the - largest volume of cool air flowing around it. You may need to seal - some unwanted holes or add a new fan for effective cooling.</para> - - <para>Another consideration is noise. Many 7,200 or faster drives - generate a high-pitched whine which is quite unpleasant to most - people. That, plus the extra fans often required for cooling, may - make 7,200 or faster drives unsuitable for some office and home - environments.</para> - </sect4> - - <sect4> - <title>Form factor</title> - - <para>Most SCSI drives sold today are of 3.5" form factor. They - come in two different heights; 1.6" (<quote>half-height</quote>) or - 1" (<quote>low-profile</quote>). The half-height drive is the same - height as a CDROM drive. However, don't forget the spacing rule - mentioned in the previous section. If you have three standard - 3.5" drive bays, you will not be able to put three half-height - drives in there (without frying them, that is).</para> - </sect4> - - <sect4> - <title>Interface</title> - - <para>The majority of SCSI hard drives sold today are Ultra or - Ultra-wide SCSI. The maximum bandwidth of Ultra SCSI is 20MB/sec, - and Ultra-wide SCSI is 40MB/sec. There is no difference in max - cable length between Ultra and Ultra-wide; however, the more - devices you have on the same bus, the sooner you will start having - bus integrity problems. Unless you have a well-designed disk - enclosure, it is not easy to make more than 5 or 6 Ultra SCSI - drives work on a single bus.</para> - - <para>On the other hand, if you need to connect many drives, going - for Fast-wide SCSI may not be a bad idea. That will have the same - max bandwidth as Ultra (narrow) SCSI, while electronically it's - much easier to get it <quote>right</quote>. My advice would be: if - you want to connect many disks, get wide SCSI drives; they usually - cost a little more but it may save you down the road. (Besides, - if you can't afford the cost difference, you shouldn't be building - a disk array.)</para> - - <para>There are two variant of wide SCSI drives; 68-pin and 80-pin - SCA (Single Connector Attach). The SCA drives don't have a - separate 4-pin power connector, and also read the SCSI ID settings - through the 80-pin connector. If you are really serious about - building a large storage system, get SCA drives and a good SCA - enclosure (dual power supply with at least one extra fan). They - are more electronically sound than 68-pin counterparts because - there is no <quote>stub</quote> of the SCSI bus inside the disk - canister as in arrays built from 68-pin drives. They are easier - to install too (you just need to screw the drive in the canister, - instead of trying to squeeze in your fingers in a tight place to - hook up all the little cables (like the SCSI ID and disk activity - LED lines).</para> - </sect4> - </sect3> - - <sect3> - <title>* IDE hard drives</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>Tape drives</title> - - <para><emphasis>Contributed by &a.jmb;. 2 July - 1996.</emphasis></para> - - <sect3> - <title>General tape access commands</title> - - <para>&man.mt.1; provides generic access to the tape drives. Some of - the more common commands are <command>rewind</command>, - <command>erase</command>, and <command>status</command>. See the - &man.mt.1; manual page for a detailed description.</para> - </sect3> - - <sect3> - <title>Controller Interfaces</title> - - <para>There are several different interfaces that support tape drives. - The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide - variety of tape drives are available for these interfaces. - Controllers are discussed in <link - linkend="hw-storage-controllers">Disk/tape - controllers</link>.</para> - </sect3> - - <sect3> - <title>SCSI drives</title> - - <para>The &man.st.4; driver provides support for 8mm (Exabyte), 4mm - (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT - (Digital Linear Tape), QIC Mini cartridge and 9-track (remember the - big reels that you see spinning in Hollywood computer rooms) tape - drives. See the &man.st.4; manual page for a detailed - description.</para> - - <para>The drives listed below are currently being used by members of - the FreeBSD community. They are not the only drives that will work - with FreeBSD. They just happen to be the ones that we use.</para> - - <sect4> - <title>4mm (DAT: Digital Audio Tape)</title> - - <para><link linkend="hw-storage-python-28454">Archive Python - 28454</link></para> - - <para><link linkend="hw-storage-python-04687">Archive Python - 04687</link></para> - - <para><link linkend="hw-storage-hp1533a">HP C1533A</link></para> - - <para><link linkend="hw-storage-hp1534a">HP C1534A</link></para> - - <para><link linkend="hw-storage-hp35450a">HP 35450A</link></para> - - <para><link linkend="hw-storage-hp35470a">HP 35470A</link></para> - - <para><link linkend="hw-storage-hp35480a">HP 35480A</link></para> - - <para><link linkend="hw-storage-sdt5000">SDT-5000</link></para> - - <para><link linkend="hw-storage-wangtek6200">Wangtek - 6200</link></para> - </sect4> - - <sect4> - <title>8mm (Exabyte)</title> - - <para><link linkend="hw-storage-exb8200">EXB-8200</link></para> - - <para><link linkend="hw-storage-exb8500">EXB-8500</link></para> - - <para><link linkend="hw-storage-exb8505">EXB-8505</link></para> - </sect4> - - <sect4> - <title>QIC (Quarter-Inch Cartridge)</title> - - <para><link linkend="hw-storage-anaconda">Archive Anaconda - 2750</link></para> - - <para><link linkend="hw-storage-viper60">Archive Viper - 60</link></para> - - <para><link linkend="hw-storage-viper150">Archive Viper - 150</link></para> - - <para><link linkend="hw-storage-viper2525">Archive Viper - 2525</link></para> - - <para><link linkend="hw-storage-tandberg3600">Tandberg TDC - 3600</link></para> - - <para><link linkend="hw-storage-tandberg3620">Tandberg TDC - 3620</link></para> - - <para><link linkend="hw-storage-tandberg3800">Tandberg TDC - 3800</link></para> - - <para><link linkend="hw-storage-tandberg4222">Tandberg TDC - 4222</link></para> - - <para><link linkend="hw-storage-wangtek5525es">Wangtek - 5525ES</link></para> - </sect4> - - <sect4> - <title>DLT (Digital Linear Tape)</title> - - <para><link linkend="hw-storage-dectz87">Digital TZ87</link></para> - </sect4> - - <sect4> - <title>Mini-Cartridge</title> - - <para><link linkend="hw-storage-ctms3200">Conner CTMS - 3200</link></para> - - <para><link linkend="hw-storage-exb2501">Exabyte 2501</link></para> - </sect4> - - <sect4> - <title>Autoloaders/Changers</title> - - <para><link linkend="hw-storage-hp1553a">Hewlett-Packard HP C1553A - Autoloading DDS2</link></para> - </sect4> - </sect3> - - <sect3> - <title>* IDE drives</title> - - <para></para> - </sect3> - - <sect3> - <title>Floppy drives</title> - - <para><link linkend="hw-storage-conner420r">Conner 420R</link></para> - </sect3> - - <sect3> - <title>* Parallel port drives</title> - - <para></para> - </sect3> - - <sect3> - <title>Detailed Information</title> - - <sect4 id="hw-storage-anaconda"> - <title>Archive Anaconda 2750</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - ANCDA 2750 28077 -003 type 1 removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 1.35GB when using QIC-1350 tapes. This - drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and - QIC-525 (DC6525) tapes as well.</para> - - <para>Data transfer rate is 350kB/s using - &man.dump.8;. Rates of 530kB/s have been reported when using - <link linkend="backups-programs-amanda">Amanda</link></para> - - <para>Production of this drive has been discontinued.</para> - - <para>The SCSI bus connector on this tape drive is reversed from - that on most other SCSI devices. Make sure that you have enough - SCSI cable to twist the cable one-half turn before and after the - Archive Anaconda tape drive, or turn your other SCSI devices - upside-down.</para> - - <para>Two kernel code changes are required to use this drive. This - drive will not work as delivered.</para> - - <para>If you have a SCSI-2 controller, short jumper 6. Otherwise, - the drive behaves are a SCSI-1 device. When operating as a SCSI-1 - device, this drive, <quote>locks</quote> the SCSI bus during some - tape operations, including: fsf, rewind, and rewoffl.</para> - - <para>If you are using the NCR SCSI controllers, patch the file - <filename>/usr/src/sys/pci/ncr.c</filename> (as shown below). - Build and install a new kernel.</para> - - <programlisting> -*** 4831,4835 **** - }; - -! if (np->latetime>4) { - /* - ** Although we tried to wake it up, ---- 4831,4836 ---- - }; - -! if (np->latetime>1200) { - /* - ** Although we tried to wake it up,</programlisting> - - <para>Reported by: &a.jmb;</para> - </sect4> - - <sect4 id="hw-storage-python-28454"> - <title>Archive Python 28454</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 28454-XXX4ASB</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x8c, 512-byte - blocks</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2.5GB on 90m tapes.</para> - - <para>Data transfer rate is XXX.</para> - - <para>This drive was repackaged by Sun Microsystems as model - 595-3067.</para> - - <para>Reported by: Bob Bishop <email>rb@gid.co.uk</email></para> - - <para>Throughput is in the 1.5 MByte/sec range, however this will - drop if the disks and tape drive are on the same SCSI - controller.</para> - - <para>Reported by: Robert E. Seastrom - <email>rs@seastrom.com</email></para> - </sect4> - - <sect4 id="hw-storage-python-04687"> - <title>Archive Python 04687</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 04687-XXX 6580</literal> <literal>Removable Sequential - Access SCSI-2 device</literal></para> - - <para>This is a DAT-DDS-2 drive.</para> - - <para>Native capacity is 4GB when using 120m tapes.</para> - - <para>This drive supports hardware data compression. Switch 4 - controls MRS (Media Recognition System). MRS tapes have stripes - on the transparent leader. Switch 4 <emphasis>off</emphasis> - enables MRS, <emphasis>on</emphasis> disables MRS.</para> - - <para>Parity is controlled by switch 5. Switch 5 - <emphasis>on</emphasis> to enable parity control. Compression is - enabled with Switch 6 <emphasis>off</emphasis>. It is possible to - override compression with the <literal>SCSI MODE SELECT</literal> - command (see &man.mt.1;).</para> - - <para>Data transfer rate is 800kB/s.</para> - </sect4> - - <sect4 id="hw-storage-viper60"> - <title>Archive Viper 60</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 60 21116 -007</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 60MB.</para> - - <para>Data transfer rate is XXX.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Philippe Regnauld - <email>regnauld@hsc.fr</email></para> - </sect4> - - <sect4 id="hw-storage-viper150"> - <title>Archive Viper 150</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 150 21531 -004</literal> <literal>Archive Viper 150 is a - known rogue</literal> <literal>type 1 removable SCSI - 1</literal>. A multitude of firmware revisions exist for this - drive. Your drive may report different numbers (e.g - <literal>21247 -005</literal>.</para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB - (DC6250) tapes have the recording format. The 250MB tapes are - approximately 67% longer than the 150MB tapes. This drive can - read 120MB tapes as well. It can not write 120MB tapes.</para> - - <para>Data transfer rate is 100kB/s</para> - - <para>This drive reads and writes DC6150 (150MB) and DC6250 (250MB) - tapes.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;).</para> - - <para>Under FreeBSD 2.2-CURRENT, use <command>mt blocksize - 512</command> to set the blocksize. (The particular drive had - firmware revision 21247 -005. Other firmware revisions may behave - differently) Previous versions of FreeBSD did not have this - problem.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Pedro A M Vazquez - <email>vazquez@IQM.Unicamp.BR</email></para> - - <para>&a.msmith;</para> - </sect4> - - <sect4 id="hw-storage-viper2525"> - <title>Archive Viper 2525</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 2525 25462 -011</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s at 90 inches/sec.</para> - - <para>The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. - Writes QIC-525, QIC-150, and QIC-120.</para> - - <para>Firmware revisions prior to <literal>25462 -011</literal> are - bug ridden and will not function properly.</para> - - <para>Production of this drive has been discontinued.</para> - </sect4> - - <sect4 id="hw-storage-conner420r"> - <title>Conner 420R</title> - - <para>The boot message identifier for this drive is <literal>Conner - tape</literal>.</para> - - <para>This is a floppy controller, mini cartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-80 tape cartridges.</para> - - <para>Reported by: Mark Hannon - <email>mark@seeware.DIALix.oz.au</email></para> - </sect4> - - <sect4 id="hw-storage-ctms3200"> - <title>Conner CTMS 3200</title> - - <para>The boot message identifier for this drive is <literal>CONNER - CTMS 3200 7.00</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a mini cartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-3080 tape cartridges.</para> - - <para>Reported by: Thomas S. Traylor - <email>tst@titan.cs.mci.com</email></para> - </sect4> - - <sect4 id="hw-storage-dectz87"> - <title><ulink - url="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink></title> - - <para>The boot message identifier for this drive is <literal>DEC - TZ87 (C) DEC 9206</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x19</literal></para> - - <para>This is a DLT tape drive.</para> - - <para>Native capacity is 10GB.</para> - - <para>This drive supports hardware data compression.</para> - - <para>Data transfer rate is 1.2MB/s.</para> - - <para>This drive is identical to the Quantum DLT2000. The drive - firmware can be set to emulate several well-known drives, - including an Exabyte 8mm drive.</para> - - <para>Reported by: &a.wilko;</para> - </sect4> - - <sect4 id="hw-storage-exb2501"> - <title><ulink - url="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink></title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-2501</literal></para> - - <para>This is a mini-cartridge tape drive.</para> - - <para>Native capacity is 1GB when using MC3000XL - mini cartridges.</para> - - <para>Data transfer rate is XXX</para> - - <para>This drive can read and write DC2300 (550MB), DC2750 (750MB), - MC3000 (750MB), and MC3000XL (1GB) mini cartridges.</para> - - <para>WARNING: This drive does not meet the SCSI-2 specifications. - The drive locks up completely in response to a SCSI MODE_SELECT - command unless there is a formatted tape in the drive. Before - using this drive, set the tape blocksize with</para> - - <screen>&prompt.root; <userinput>mt -f /dev/st0ctl.0 blocksize 1024</userinput></screen> - - <para>Before using a mini cartridge for the first time, the - mini cartridge must be formated. FreeBSD 2.1.0-RELEASE and - earlier:</para> - - <screen>&prompt.root; <userinput>/sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0"</userinput></screen> - - <para>(Alternatively, fetch a copy of the - <command>scsiformat</command> shell script from FreeBSD - 2.1.5/2.2.) FreeBSD 2.1.5 and later:</para> - - <screen>&prompt.root; <userinput>/sbin/scsiformat -q -w /dev/rst0.ctl</userinput></screen> - - <para>Right now, this drive cannot really be recommended for - FreeBSD.</para> - - <para>Reported by: Bob Beaulieu - <email>ez@eztravel.com</email></para> - </sect4> - - <sect4 id="hw-storage-exb8200"> - <title>Exabyte EXB-8200</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8200 252X</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 2.3GB.</para> - - <para>Data transfer rate is 270kB/s.</para> - - <para>This drive is fairly slow in responding to the SCSI bus during - boot. A custom kernel may be required (set SCSI_DELAY to 10 - seconds).</para> - - <para>There are a large number of firmware configurations for this - drive, some have been customized to a particular vendor's - hardware. The firmware can be changed via EPROM - replacement.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: &a.msmith;</para> - </sect4> - - <sect4 id="hw-storage-exb8500"> - <title>Exabyte EXB-8500</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8500-85Qanx0 0415</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 5GB.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Greg Lehey <email>grog@lemis.de</email></para> - </sect4> - - <sect4 id="hw-storage-exb8505"> - <title><ulink - url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink></title> - - <para>The boot message identifier for this drive is - <literal>EXABYTE EXB-85058SQANXR1 05B0</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is an 8mm tape drive which supports compression, and is - upward compatible with the EXB-5200 and EXB-8500.</para> - - <para>Native capacity is 5GB.</para> - - <para>The drive supports hardware data compression.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Glen Foster - <email>gfoster@gfoster.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp1533a"> - <title>Hewlett-Packard HP C1533A</title> - - <para>The boot message identifier for this drive is <literal>HP - C1533A 9503</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a DDS-2 tape drive. DDS-2 means hardware data - compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore 6000eU and - 6000i tape drives and C1533A DDS-2 DAT drive.</para> - - <para>The drive has a block of 8 dip switches. The proper settings - for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 - ON.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>switch 1</entry> - <entry>switch 2</entry> - <entry>Result</entry> - </row> - </thead> - - <tbody> - <row> - <entry>On</entry> - <entry>On</entry> - <entry>Compression enabled at power-on, with host - control</entry> - </row> - - <row> - <entry>On</entry> - <entry>Off</entry> - <entry>Compression enabled at power-on, no host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>On</entry> - <entry>Compression disabled at power-on, with host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>Off</entry> - <entry>Compression disabled at power-on, no host - control</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Switch 3 controls MRS (Media Recognition System). MRS tapes - have stripes on the transparent leader. These identify the tape - as DDS (Digital Data Storage) grade media. Tapes that do not have - the stripes will be treated as write-protected. Switch 3 OFF - enables MRS. Switch 3 ON disables MRS.</para> - - <para>See <ulink url="http://www.hp.com/tape/c_intro.html">HP - SureStore Tape Products</ulink> and <ulink - url="http://www.impediment.com/hp/hp_technical.html">Hewlett-Packard - Disk and Tape Technical Information</ulink> for more information - on configuring this drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 2 of - these drives. Neither lasted more than 5 months.</para> - - <para>Reported by: &a.se;</para> - </sect4> - - <sect4 id="hw-storage-hp1534a"> - <title>Hewlett-Packard HP 1534A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A T503</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code 0x13, - variable blocks</literal>.</para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink url="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive and HP C1536A DDS format DAT drive.</para> - - <para>The HP C1534A DDS format DAT drive has two indicator lights, - one green and one amber. The green one indicates tape action: - slow flash during load, steady when loaded, fast flash during - read/write operations. The amber one indicates warnings: slow - flash when cleaning is required or tape is nearing the end of its - useful life, steady indicates an hard fault. (factory service - required?)</para> - - <para>Reported by Gary Crutcher - <email>gcrutchr@nightflight.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp1553a"> - <title>Hewlett-Packard HP C1553A Autoloading DDS2</title> - - <para>The boot message identifier for this drive is "".</para> - - <para>This is a DDS-2 tape drive with a tape changer. DDS-2 means - hardware data compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 24GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s (native).</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - url="http://www.dmo.hp.com/tape/sst12000.htm">12000e</ulink> - tape drive.</para> - - <para>The drive has two selectors on the rear panel. The selector - closer to the fan is SCSI id. The other selector should be set to - 7.</para> - - <para>There are four internal switches. These should be set: 1 ON; - 2 ON; 3 ON; 4 OFF.</para> - - <para>At present the kernel drivers do not automatically change - tapes at the end of a volume. This shell script can be used to - change tapes:</para> - - <programlisting> -#!/bin/sh -PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH - -usage() -{ - echo "Usage: dds_changer [123456ne] raw-device-name - echo "1..6 = Select cartridge" - echo "next cartridge" - echo "eject magazine" - exit 2 -} - -if [ $# -ne 2 ] ; then - usage -fi - -cdb3=0 -cdb4=0 -cdb5=0 - -case $1 in - [123456]) - cdb3=$1 - cdb4=1 - ;; - n) - ;; - e) - cdb5=0x80 - ;; - ?) - usage - ;; -esac - -scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting> - </sect4> - - <sect4 id="hw-storage-hp35450a"> - <title>Hewlett-Packard HP 35450A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35450A -A C620</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 1.2GB.</para> - - <para>Data transfer rate is 160kB/s.</para> - - <para>Reported by: Mark Thompson - <email>mark.a.thompson@pobox.com</email></para> - </sect4> - - <sect4 id="hw-storage-hp35470a"> - <title>Hewlett-Packard HP 35470A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A 9 09</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink url="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive, and HP C1536A DDS format DAT drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 5 of - these drives. None lasted more than 9 months.</para> - - <para>Reported by: David Dawes - <email>dawes@rf900.physics.usyd.edu.au</email> (9 09)</para> - - </sect4> - - <sect4 id="hw-storage-hp35480a"> - <title>Hewlett-Packard HP 35480A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35480A 1009</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal>.</para> - - <para>This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware - data compression. DDS-1 is the original DAT tape format.</para> - - <para>Native capacity is 2GB when using 90m tapes. It cannot handle - 120m tapes. This drive supports hardware data compression. - Please refer to the section on <link - linkend="hw-storage-hp1533a">HP C1533A</link> for the proper - switch settings.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - url="http://www.dmo.hp.com/tape/sst5000.htm">5000eU</ulink> and - <ulink url="http://www.dmo.hp.com/tape/sst5000.htm">5000i</ulink> - tape drives and C35480A DDS format DAT drive..</para> - - <para>This drive will occasionally hang during a tape eject - operation (<command>mt offline</command>). Pressing the front - panel button will eject the tape and bring the tape drive back to - life.</para> - - <para>WARNING: HP 35480-03110 only. On at least two occasions this - tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an - 2940W SCSI controller resulted in all SCSI disk partitions being - lost. The problem has not be analyzed or resolved at this - time.</para> - </sect4> - - <sect4 id="hw-storage-sdt5000"> - <title><ulink - url="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink></title> - - <para>There are at least two significantly different models: one is - a DDS-1 and the other DDS-2. The DDS-1 version is - <literal>SDT-5000 3.02</literal>. The DDS-2 version is - <literal>SONY SDT-5000 327M</literal>. The DDS-2 version has a 1MB - cache. This cache is able to keep the tape streaming in almost - any circumstances.</para> - - <para>The boot message identifier for this drive is <literal>SONY - SDT-5000 3.02</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is depends upon the model or the drive. The - rate is 630kB/s for the <literal>SONY SDT-5000 327M</literal> - while compressing the data. For the <literal>SONY SDT-5000 - 3.02</literal>, the data transfer rate is 225kB/s.</para> - - <para>In order to get this drive to stream, set the blocksize to 512 - bytes (<command>mt blocksize 512</command>) reported by Kenneth - Merry <email>ken@ulc199.residence.gatech.edu</email>.</para> - - <para><literal>SONY SDT-5000 327M</literal> information reported by - Charles Henrich <email>henrich@msu.edu</email>.</para> - - <para>Reported by: &a.jmz;</para> - </sect4> - - <sect4 id="hw-storage-tandberg3600"> - <title>Tandberg TDC 3600</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3600 =08:</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB.</para> - - <para>This drive has quirks which are known and work around code is - present in the scsi tape device driver (&man.st.4;). - Upgrading the firmware to XXX version will fix the quirks and - provide SCSI 2 capabilities.</para> - - <para>Data transfer rate is 80kB/s.</para> - - <para>IBM and Emerald units will not work. Replacing the firmware - EPROM of these units will solve the problem.</para> - - <para>Reported by: &a.msmith;</para> - </sect4> - - <sect4 id="hw-storage-tandberg3620"> - <title>Tandberg TDC 3620</title> - - <para>This is very similar to the <link - linkend="hw-storage-tandberg3600">Tandberg TDC 3600</link> - drive.</para> - - <para>Reported by: &a.joerg;</para> - </sect4> - - <sect4 id="hw-storage-tandberg3800"> - <title>Tandberg TDC 3800</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3800 =04Y</literal> <literal>Removable - Sequential Access SCSI-2 device</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Reported by: &a.jhs;</para> - </sect4> - - <sect4 id="hw-storage-tandberg4222"> - <title>Tandberg TDC 4222</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 4222 =07</literal> <literal>type 1 removable - SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 2.5GB. The drive will read all cartridges - from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) - upwards. Hardware compression is optionally supported for the 2.5 - GB cartridges.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;) beginning with FreeBSD - 2.2-CURRENT. For previous versions of FreeBSD, use - <command>mt</command> to read one block from the tape, rewind the - tape, and then execute the backup program (<command>mt fsr 1; mt - rewind; dump ...</command>)</para> - - <para>Data transfer rate is 600kB/s (vendor claim with compression), - 350 KB/s can even be reached in start/stop mode. The rate - decreases for smaller cartridges.</para> - - <para>Reported by: &a.joerg;</para> - </sect4> - - <sect4 id="hw-storage-wangtek5525es"> - <title>Wangtek 5525ES</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 5525ES SCSI REV7 3R1</literal> <literal>type 1 removable SCSI - 1</literal> <literal>density code 0x11, 1024-byte - blocks</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s.</para> - - <para>The drive reads 60, 120, 150, and 525MB tapes. The drive will - not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 - and 150 tapes reliably, first erase (<command>mt erase</command>) - the tape. 120 and 150 tapes used a wider track (fewer tracks per - tape) than 525MB tapes. The <quote>extra</quote> width of the - previous tracks is not overwritten, as a result the new data lies - in a band surrounded on both sides by the previous data unless the - tape have been erased.</para> - - <para>This drives quirks are known and pre-compiled into the scsi - tape device driver (&man.st.4;).</para> - - <para>Other firmware revisions that are known to work are: - M75D</para> - - <para>Reported by: Marc van Kempen <email>marc@bowtie.nl</email> - <literal>REV73R1</literal> Andrew Gordon - <email>Andrew.Gordon@net-tel.co.uk</email> - <literal>M75D</literal></para> - </sect4> - - <sect4 id="hw-storage-wangtek6200"> - <title>Wangtek 6200</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 6200-HS 4B18</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2GB using 90m tapes.</para> - - <para>Data transfer rate is 150kB/s.</para> - - <para>Reported by: Tony Kimball <email>alk@Think.COM</email></para> - </sect4> - </sect3> - - <sect3> - <title>* Problem drives</title> - - <para></para> - </sect3> - </sect2> - - <sect2> - <title>CDROM drives</title> - - <para><emphasis>Contributed by &a.obrien;. 23 November - 1997.</emphasis></para> - - <para>As mentioned in <link linkend="hw-jordans-picks-cdrom">Jordan's - Picks</link> Generally speaking those in <emphasis>The FreeBSD - Project</emphasis> prefer SCSI CDROM drives over IDE CDROM drives. - However not all SCSI CDROM drives are equal. Some feel the quality of - some SCSI CDROM drives have been deteriorating to that of IDE CDROM - drives. Toshiba used to be the favored stand-by, but many on the SCSI - mailing list have found displeasure with the 12x speed XM-5701TA as - its volume (when playing audio CDROMs) is not controllable by the - various audio player software.</para> - - <para>Another area where SCSI CDROM manufacturers are cutting corners is - adherence to the <link linkend="scsi-further-reading">SCSI - specification</link>. Many SCSI CDROMs will respond to <link - linkend="scsi-rogue-devices">multiple LUNs</link> for its target - address. Known violators include the 6x Teac CD-56S 1.0D.</para> - </sect2> - - <sect2> - <title>* Other</title> - - <para></para> - </sect2> - </sect1> - - <sect1 id="hw-other"> - <title>* Other</title> - - - <sect2> - <title>* PCMCIA</title> - - <para></para> - </sect2> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml deleted file mode 100644 index b1abe407e5..0000000000 --- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml +++ /dev/null @@ -1,1831 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/install/chapter.sgml,v 1.60 2000/10/03 13:05:18 eivind Exp $ ---> - -<chapter id="install"> - <title>Installing FreeBSD</title> - - <para><emphasis>Restructured, updated, and parts rewritten by &a.jim;, - January 2000.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>The following chapter will attempt to guide you through the - installation of FreeBSD on your system. It can be installed through a - variety of methods, including anonymous FTP (assuming you have - network connectivity via modem or local network), CDROM, floppy - disk, tape, an MS-DOS partition, or even NFS.</para> - - <para>No matter which method you choose, you will need to get started - by creating the <emphasis>installation disks</emphasis> as described - in the <link linkend="install-floppies">next section</link>. - Booting into the FreeBSD installer, even if you are not planning on - installing FreeBSD right away, will provide important information - about compatibility with your hardware. This information may - dictate which installation options are even possible for you. It - can also provide clues early-on in the process to potential problems - you may come across later.</para> - - <para>If you plan to install FreeBSD via anonymous FTP, the only - things you will need are the <link - linkend="install-floppies">installation floppies</link>. The - installation program itself will handle anything else that is - required.</para> - - <para>For more information about obtaining FreeBSD, see the <link - linkend="mirrors">Obtaining FreeBSD</link> section of the - Appendix.</para> - - <para>By now, you are probably wondering what exactly it is you need - to do. Continue on to the installation guide.</para> - </sect1> - - <sect1 id="install-guide"> - <title>Installation Guide</title> - - <para>The following sections will guide you through preparing for and - actually installing FreeBSD. If you find something missing, please - let us know about it by sending email to the &a.doc;.</para> - - <sect2 id="install-prepare"> - <title>Preparing for the Installation</title> - - <para>There are various things you should do in preparation for the - installation. The following describes what needs to be done prior to - each type of installation.</para> - - <para>The first thing to do is to make sure your hardware is - supported by FreeBSD. The list of <link - linkend="install-hw">supported hardware</link> should - come in handy here. ;-) It would also be a good idea to make a - list of any <quote>special</quote> cards you have installed, - such as SCSI controllers, ethernet cards, sound cards, etc.. - The list should include their IRQs and IO port addresses.</para> - - <sect3 id="install-floppies"> - <title>Creating the Installation Floppies</title> - - <para>You may need to prepare some floppy disks. These disks will - be used to boot your computer in to the FreeBSD install process. - This step is not necessary <emphasis>if</emphasis> you are - installing from CD-ROM, <emphasis>and</emphasis> your computer - supports booting from the CD-ROM. If you do not meet these - requirements then you will need to create some floppies to boot - from.</para> - - <note> - <para>If you are not sure whether your computer can boot from the - CD-ROM it does not hurt to try. Just insert the CD-ROM as - normal and restart your computer. You might need to adjust some - options in your BIOS so that your computer will try and boot - from the CD-ROM drive before the hard disk.</para> - </note> - - <tip> - <para>Even if you have the CD-ROM it might make sense for you to - download the files. There have been occasions where bugs in the - FreeBSD installer have been discovered after the CDs have been - released. When this happens the copies of the images on the FTP - site will be fixed as soon as possible. Obviously, it is not - possible to update the CDs after they have been pressed.</para> - </tip> - - <procedure> - <step> - <title>Acquire the boot floppy images</title> - - <para>These are files with a <filename>.flp</filename> - extension. If you have a CD-ROM release of FreeBSD then you - will find the files in the <filename>floppies</filename> - subdirectory. Alternatively, you can download the images from - the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/">floppies directory</ulink> of the FreeBSD FTP site or your local mirror.</para> - - <para>The names of the files you will need varies between - FreeBSD releases (sometimes) and the architecture you will be - installing on. The <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/README.TXT">installation - boot image information</ulink> on the FTP site provides - up-to-the-minute information about the specific files you will - need.</para> - </step> - - <step> - <title>Prepare the floppy disks</title> - - <para>You must prepare one floppy disk per image file you had to - download. It is imperitive that these disks are free from - defects. The easiest way to test this is to format the disks - for yourself. Do not trust pre-formatted floppies.</para> - - <important> - <para>If you try to install FreeBSD and the installation - program crashes, freezes, or otherwise misbehaves one of - the first things to suspect is the floppies. Try writing - the floppy image files to some other disks, and try - again.</para> - </important> - </step> - - <step> - <title>Write the image files to the floppy disks.</title> - - <para>The image files, such as <filename>kern.flp</filename>, - are <emphasis>not</emphasis> regular files you copy to the - disk. Instead, they are images of the complete contents of - the disk.</para> - - <para>This means that you can <emphasis>not</emphasis> use - commands like DOS' <command>copy</command> to write the - files. Instead, you must use specific tools to write the - images directly to the disk.</para> - - <para>If you are creating the floppies on a computer running DOS - then we provide a tool to do this called - <command>fdimage</command>.</para> - - <para>If you are using the floppies from the CD-ROM, and your - CD-ROM is the <devicename>E:</devicename> drive then you would - run this:</para> - - <screen><prompt>E:\></prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen> - - <para>Repeat this command for each <filename>.flp</filename> - file, replacing the floppy disk each time. Adjust the command - line as necessary, depending on where you have placed the - <filename>.flp</filename> files. If you do not have the - CD-ROM then <command>fdimage</command> can be downloaded from - the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename>tools</filename> directory</ulink> on the FreeBSD FTP site.</para> - - <para>If you are writing the floppies on a Unix system (such as - another FreeBSD system) you can use the &man.dd.1; command to - write the image files directly to disk. On FreeBSD you would - run:</para> - - <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/rfd0</userinput></screen> - - <para>On FreeBSD <filename>/dev/rfd0</filename> refers to the - first floppy disk (the <devicename>A:</devicename> drive). - <filename>/dev/rfd1</filename> would be the - <devicename>B:</devicename> drive, and so on. Other Unix - variants might have different names for the floppy disk - devices, and you will need to check the documentation for the - system as necessary.</para> - </step> - </procedure> - </sect3> - - <sect3 id="install-cdrom"> - <title>Before Installing from CDROM</title> - - <para>If your CDROM is of an unsupported type, please skip ahead - to the <link linkend="install-msdos">MS-DOS Preparation</link> - section.</para> - - <para>There is not a whole lot of preparation needed if you are - installing from one of <ulink - url="http://www.osd.bsdi.com/">BSDi's</ulink> - 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 created). You can either boot into the CD installation - directly from DOS using the <filename>install.bat</filename> or - you can make floppies with the <filename>makeflp.bat</filename> - command.</para> - - <para>If the CD has El Torito boot support and your system - supports booting directly from the CDROM drive (many older - systems do <emphasis>NOT</emphasis>), simply insert the first - CD of the set into the drive and reboot your system. You - will be put into the installation menu directly from the CD.</para> - - <para>If you are installing from an MS-DOS partition and have - the proper drivers to access your CD, run the - <filename>install.bat</filename> script provided on the CDROM. - This will attempt to boot the FreeBSD installation directly - from DOS.</para> - - <note> - <para>You must do this from actual DOS (i.e., boot in DOS - mode) and not from a DOS window under Windows.</para> - </note> - - <para>For the easiest interface of all (from DOS), type - <command>view</command>. This will bring up a DOS menu utility - that leads you through all of the available options.</para> - - <para>If you are creating the boot floppies from a UNIX machine, - see the <link linkend="install-floppies">Creating the Boot - Floppies</link> section of this guide for examples.</para> - - <para>Once you have booted from DOS or floppy, you should then be - able to select CDROM as the media type during the install - process and load the entire distribution from CDROM. No other - types of installation media should be required.</para> - - <para>After your system is fully installed and you have rebooted - (from the hard disk), you can mount the CDROM at any time by - typing:</para> - - <screen>&prompt.root; <userinput>mount /cdrom</userinput></screen> - - <para>Before removing the CD from the drive again, you must first - unmount it. This is done with the following command:</para> - - <screen>&prompt.root; <userinput>umount /cdrom</userinput></screen> - - <para>Do not just remove it from the drive!</para> - - <note> - <para>Before invoking the installation, be sure that the CDROM - is in the drive so that the install probe can find it. This - is also true if you wish the CDROM to be added to the default - system configuration automatically during the installation (whether - or not you actually use it as the installation media).</para> - </note> - - <para>Finally, if you would like people to be able to FTP install - FreeBSD directly from the CDROM in your machine, you will find - it quite easy. After the machine is fully installed, you simply - need to add the following line to the password file (using the - <command>vipw</command> command):</para> - - <programlisting> -ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting> - - <para>Anyone with network connectivity to your machine can now - chose a media type of FTP and type in - <userinput>ftp://<replaceable>your machine</replaceable></userinput> - after picking <quote>Other</quote> in the FTP sites menu during - the install.</para> - - <note><para>If you choose to enable anonymous FTP during the - installation of your system, the installation program will do - the above for you.</para></note> - - </sect3> - - <sect3> - <title>Before installing from Floppies</title> - - <para>If you must install from floppy disk (which we suggest you - do <emphasis>NOT</emphasis> do), either due to unsupported - hardware or simply because you insist on doing things the hard - way, you must first prepare some floppies for the installation.</para> - - <para>At a minimum, you will need as many 1.44MB or 1.2MB floppies - as it takes to hold all the files in the - <filename>bin</filename> (binary distribution) directory. If - you are preparing the floppies from DOS, then they - <emphasis>MUST</emphasis> be formatted using the MS-DOS - <command>FORMAT</command> command. If you are using Windows, - use Explorer to format the disks (right-click on the - <devicename>A:</devicename> drive, and select "Format".</para> - - <para>Do <emphasis>NOT</emphasis> trust factory pre-formatted - floppies! Format them again yourself, just to be sure. Many - problems reported by our users in the past have resulted from - the use of improperly formatted media, which is why we are - making a point of it now.</para> - - <para>If you are creating the floppies on another FreeBSD machine, - a format is still not a bad idea, though you do not need to put - a DOS filesystem on each floppy. You can use the - <command>disklabel</command> and <command>newfs</command> - commands to put a UFS filesystem on them instead, as the - following sequence of commands (for a 3.5" 1.44MB floppy) - illustrates:</para> - - <screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput> -&prompt.root; <userinput>disklabel -w -r fd0.1440 floppy3</userinput> -&prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0</userinput></screen> - - <note> - <para>Use <literal>fd0.1200</literal> and - <literal>floppy5</literal> for 5.25" 1.2MB disks.</para> - </note> - - <para>Then you can mount and write to them like any other - filesystem.</para> - - <para>After you have formatted the floppies, you will need to copy - the files to 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 all of the - distributions you want packed up in this fashion. Each - distribution should go into a subdirectory on the floppy, e.g.: - <filename>a:\bin\bin.aa</filename>, - <filename>a:\bin\bin.ab</filename>, and so on.</para> - - <para>Once you come to the Media screen during the install - process, select <quote>Floppy</quote> and you will be prompted - for the rest.</para> - </sect3> - - <sect3 id="install-msdos"> - <title>Before Installing from MS-DOS</title> - - <para>To prepare for an installation from an MS-DOS partition, - copy the files from the distribution into a directory named, - for example, <filename>c:\FreeBSD</filename>. The directory - structure of the CDROM or FTP site must be partially reproduced - within this directory, so we suggest using the DOS - <command>xcopy</command> command if you are copying it from a - CD. For example, to prepare for a minimal installation of - FreeBSD:</para> - - <screen><prompt>C:\></prompt> <userinput>md c:\FreeBSD</userinput> -<prompt>C:\></prompt> <userinput>xcopy e:\bin c:\FreeBSD\bin\ /s</userinput> -<prompt>C:\></prompt> <userinput>xcopy e:\manpages c:\FreeBSD\manpages\ /s</userinput></screen> - - <para>Assuming that <devicename>C:</devicename> is where you have - free space and <devicename>E:</devicename> is where your CDROM - is mounted.</para> - - <para>If you do not have a CDROM drive, you can download the - distribution from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/"> - ftp.FreeBSD.org</ulink>. Each distribution is in its own directory; - for example, the <emphasis>bin</emphasis> distribution can be - found in the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/bin">&rel.current;/bin</ulink> directory.</para> - - <para>For as many distributions you wish to install from an MS-DOS - partition (and you have the free space for), install each one - under <filename>c:\FreeBSD</filename> — the - <literal>BIN</literal> distribution is the only one required for - a minimum installation.</para> - </sect3> - - <sect3> - <title>Before Installing from QIC/SCSI Tape</title> - - <para>Installing from tape is probably the easiest method, short - of an online FTP install or CDROM install. The installation - program expects the files to be simply tarred onto the tape, so - after getting all of the distribution files you are interested - in, simply tar them onto the tape like so:</para> - - <screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput> -&prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen> - - <para>When you go to do the installation, you should also make - sure that you leave enough room in some temporary directory - (which you will be allowed to choose) to accommodate the - <emphasis>full</emphasis> contents of the tape you have created. - Due to the non-random access nature of tapes, this method of - installation requires quite a bit of temporary storage. You - should expect to require as much temporary storage as you have - stuff written on tape.</para> - - <note> - <para>When starting the installation, the tape must be in the - drive <emphasis>before</emphasis> booting from the boot - floppy. The installation probe may otherwise fail to find - it.</para> - </note> - </sect3> - - <sect3> - <title>Before Installing over a Network</title> - - <para>There are three types of network installations you can do. - Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)), - or Ethernet (a standard ethernet controller (includes some - PCMCIA)).</para> - - <para>The SLIP support is rather primitive, and limited primarily - to hard-wired links, such as a serial cable running between a - laptop computer and another computer. The link should be - hard-wired as the SLIP installation does not currently offer a - dialing capability; that facility is provided with the PPP - utility, which should be used in preference to SLIP whenever - possible.</para> - - <para>If you are using a modem, then PPP is almost certainly - your only choice. Make sure that you have your service - provider's information handy as you will need to know it fairly - early in the installation process.</para> - <para>If you use PAP or CHAP to connect your ISP (in other - words, if you can connect to the ISP in Windows without - using a script), then all you will need to do is type in - <command>dial</command> at the - <application>ppp</application> prompt. Otherwise, - you will need to know - how to dial your ISP using the <quote>AT commands</quote> - specific to your modem, as the PPP dialer provides only a very - simple terminal emulator. Please - to the user-ppp <link linkend="userppp">handbook</link> and <ulink - url="../FAQ/ppp.html">FAQ</ulink> entries for further - information. If you have problems, logging can be directed to - the screen using the command <command>set log local - ...</command>.</para> - - <para>If a hard-wired connection to another FreeBSD (2.0-R or - later) machine is available, you might also consider installing - over a <quote>laplink</quote> parallel port cable. The data rate - over the parallel port is much higher than what is typically - possible over a serial line (up to 50kbytes/sec), thus resulting - in a quicker installation.</para> - - <para>Finally, for the fastest possible network installation, an - ethernet adapter is always a good choice! FreeBSD supports most - common PC ethernet cards; a table of supported cards (and their - required settings) is provided in the <link - linkend="install-hw">Supported Hardware</link> list. If you are - using one of the supported PCMCIA ethernet cards, also be sure - that it is plugged in <emphasis>before</emphasis> the laptop is - powered on! FreeBSD does not, unfortunately, currently support - hot insertion of PCMCIA cards during installation.</para> - - <para>You will also need to know your IP address on the network, - the netmask value for your address class, and the name of your - machine. If you are installing over a PPP connection and do not - have a static IP, fear not, the IP address can be dynamically - assigned by your ISP. Your system administrator can tell you - which values to use for your particular network setup. If you - will be referring to other hosts by name rather than IP address, - you will also need a name server and possibly the address of a - gateway (if you are using PPP, it is your provider's IP address) - to use in talking to it. If you want to install by FTP via a - HTTP proxy (see below), you will also need the proxy's address. - If you do not know the answers to all or most of these questions, - then you should really probably talk to your system administrator - or ISP <emphasis>before</emphasis> trying this type of - installation.</para> - - <sect4> - <title>Before Installing via NFS</title> - - <para>The NFS installation is fairly straight-forward. Simply - copy the FreeBSD distribution files you want onto a server - somewhere and then point the NFS media selection at it.</para> - - <para>If this server supports only <quote>privileged port</quote> - (as is generally the default for Sun workstations), you will - need to set this option in the Options menu before - installation can proceed.</para> - - <para>If you have a poor quality ethernet card which suffers - from very slow transfer rates, you may also wish to toggle the - appropriate Options flag.</para> - - <para>In order for NFS installation to work, the server must - support subdir mounts, e.g., if your FreeBSD 3.4 distribution - directory lives - on:<filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then - <hostid>ziggy</hostid> will have to allow the direct mounting - of <filename>/usr/archive/stuff/FreeBSD</filename>, not just - <filename>/usr</filename> or - <filename>/usr/archive/stuff</filename>.</para> - - <para>In FreeBSD's <filename>/etc/exports</filename> file, this - is controlled by the <option>-alldirs</option>. Other NFS - servers may have different conventions. If you are getting - <quote>permission denied</quote> messages from the server, then - it is likely that you do not have this enabled - properly.</para> - </sect4> - - <sect4> - <title>Before Installing via FTP</title> - - <para>FTP installation may be done from any FreeBSD mirror site - containing a reasonably up-to-date version of FreeBSD. A full - list of FTP mirrors located all over the world is provided - during the install process.</para> - - <para>If you are installing from an FTP site not listed in this - menu, or are having trouble getting your name server - configured properly, you can also specify a URL to use by - selecting the choice labeled <quote>Other</quote> in that menu. - You can also use the IP address of a machine you wish to - install from, so the following would work in the absence of a - name server:</para> - - <screen><userinput>ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASE</userinput></screen> - - <para>There are three FTP installation modes you can choose from: - active or passive FTP or via a HTTP proxy.</para> - - <variablelist> - <varlistentry> - <term>FTP Active</term> - - <listitem> - <para>This option will make all FTP transfers - use <quote>Active</quote> - mode. This will not work through firewalls, but will - often work with older FTP servers that do not support - passive mode. If your connection hangs with passive - mode (the default), try active!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FTP Passive</term> - - <listitem> - <para>This option instructs FreeBSD to use - <quote>Passive</quote> mode for all FTP operations. - This allows the user to pass through firewalls - that do not allow incoming connections on random port - addresses.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FTP via a HTTP proxy</term> - - <listitem> - <para>This option instructs FreeBSD to use the HTTP - protocol (like a web browser) to connect to a proxy - for all FTP operations. The proxy will translate - the requests and send them to the FTP server. - This allows the user to pass through firewalls - that do not allow FTP at all, but offer a HTTP - proxy. - In this case, you have to specify the proxy in - addition to the FTP server.</para> - </listitem> - </varlistentry> - </variablelist> - - <note> - <para>There is another type of FTP proxy other tha HTTP - proxies. This type is very uncommon, though. If you - are not absolutely certain, you can assume that you - have a HTTP proxy as described above.</para> - </note> - - <para>For a proxy FTP server, you should usually give the name - of the server you really want as a part of the username, after - an <quote>@</quote> sign. The proxy server then - <quote>fakes</quote> the real server. For example, assuming - you want to install from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP - server <hostid role="fqdn">foo.bar.com</hostid>, listening on - port 1024.</para> - - <para>In this case, you go to the options menu, set the FTP - username to ftp@ftp.FreeBSD.org, and the password to your - email address. As your installation media, you specify FTP - (or passive FTP, if the proxy supports it), and the URL - <literal>ftp://foo.bar.com:1234/pub/FreeBSD</literal>.</para> - - <para>Since <filename>/pub/FreeBSD</filename> from <hostid - role="fqdn">ftp.FreeBSD.org</hostid> is proxied under <hostid - role="fqdn">foo.bar.com</hostid>, you are able to install from - <emphasis>that</emphasis> machine (which will fetch the files - from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your - installation requests them.</para> - </sect4> - </sect3> - - <sect3> - <title>Check your BIOS drive numbering</title> - - <para>If you have used features in your BIOS to renumber your disk - drives without recabling them then you should read <xref - linkend="disks-bios-numbering"> first to avoid confusion.</para> - </sect3> - </sect2> - - <sect2 id="install-freebsd"> - <title>Installing FreeBSD</title> - - <para>Once you have completed the pre-installation step relevant to - your situation, you are ready to install FreeBSD!</para> - - <para>Although you should not experience any difficulty, there is - always the chance that you may, no matter how slight it is. If this - is the case in your situation, then you may wish to go back and - re-read the relevant preparation section or sections. Perhaps you - will come across something you missed the first time. If you are - having hardware problems, or FreeBSD refuses to boot at all, read - the <ulink url="../FAQ/hardware.html">Hardware Guide</ulink> for a - list of possible solutions.</para> - - <para>The FreeBSD boot floppies contain all of the online - documentation you should need to be able to navigate through an - installation. If it does not, please let us know what you found - to be the most confusing or most lacking. Send your comments to - the &a.doc;. It is the objective of the installation program - (sysinstall) to be self-documenting enough that painful - <quote>step-by-step</quote> guides are no longer necessary. It may - take us a little while to reach that objective, but nonetheless, - it is still our objective :-)</para> - - <para>Meanwhile, you may also find the following <quote>typical - installation sequence</quote> to be helpful:</para> - - <orderedlist> - <listitem> - <para>Boot the <filename>kern.flp</filename> floppy and when - asked, remove it and insert the - <filename>mfsroot.flp</filename> and hit return. After a - boot sequence which can take anywhere from 30 seconds to 3 - minutes, depending on your hardware, you should be presented - with a menu of initial choices. If the - <filename>kern.flp</filename> floppy does not boot at all or - the boot hangs at some stage, read the Q&A section of the - <ulink url="../FAQ/hardware.html">Hardware Guide</ulink> for - possible causes.</para> - </listitem> - - <listitem> - <para>Press F1. You should see some basic usage instructions on - the menu screen and general navigation. If you have not used - this menu system before then <emphasis>please</emphasis> read - this thoroughly.</para> - </listitem> - - <listitem> - <para>Select the Options item and set any special preferences - you may have.</para> - </listitem> - - <listitem> - <para>Select a Standard, Express, or Custom 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, or simply whiz through it (using - reasonable defaults when possible) as fast as possible. If - you have never used FreeBSD before, the Standard installation - method is most recommended.</para> - </listitem> - - <listitem> - <para>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, or floppy install and have not yet configured your - network interfaces (assuming you have any). Properly - configuring such interfaces here will allow FreeBSD to come up - on the network when you first reboot from the hard - disk.</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 id="install-hw"> - <title>Supported Hardware</title> - - <para>FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and - PCI bus based PCs, ranging from the 386SX to Pentium class machines - (though the 386SX is not recommended). Support for generic IDE or - ESDI drive configurations, various SCSI controllers, and network and - serial cards is also provided. FreeBSD also supports IBM's - microchannel (MCA) bus.</para> - - <para>In order to run FreeBSD, a recommended minimum of eight - megabytes of RAM is suggested. Sixteen megabytes is the preferred - amount of RAM as you may have some trouble with anything less than - sixteen depending on your hardware.</para> - - <para>What follows is a list of hardware currently known to work with - FreeBSD. There may be other hardware that works as well, but we - have simply not received any confirmation of it.</para> - - <sect2> - <title>Disk Controllers</title> - - <itemizedlist> - <listitem> - <para>WD1003 (any generic MFM/RLL)</para> - </listitem> - - <listitem> - <para>WD1007 (any generic IDE/ESDI)</para> - </listitem> - - <listitem> - <para>IDE</para> - </listitem> - - <listitem> - <para>ATA</para> - </listitem> - - <listitem> - <para>Adaptec 1535 ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec 154X series ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec 174X series EISA SCSI controllers in standard and - enhanced mode</para> - </listitem> - - <listitem> - <para>Adaptec 274X/284X/2920C/294X/2950/3940/3950 - (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI - controllers</para> - </listitem> - - <listitem> - <para>Adaptec 1510 series ISA SCSI controllers (not for bootable - devices)</para> - </listitem> - - <listitem> - <para>Adaptec 152X series ISA SCSI controllers</para> - </listitem> - - <listitem> - <para>Adaptec AIC-6260 and AIC-6360 based boards, which include - the AHA-152X and SoundBlaster SCSI cards</para> - </listitem> - - <listitem> - <para>AdvanSys SCSI controllers (all models)</para> - </listitem> - - <listitem> - <para>BusLogic MultiMaster <quote>W</quote> Series Host Adapters - including BT-948, BT-958, BT-9580</para> - </listitem> - - <listitem> - <para>BusLogic MultiMaster <quote>C</quote> Series Host Adapters - including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C, - BT-757C, BT-757CD, BT-545C, BT-540CF</para> - </listitem> - - <listitem> - <para>BusLogic MultiMaster <quote>S</quote> Series Host Adapters - including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D, - BT-545S, BT-542D, BT-742A, BT-542B</para> - </listitem> - - <listitem> - <para>BusLogic MultiMaster <quote>A</quote> Series Host Adapters - including BT-742A, BT-542B</para> - </listitem> - - <listitem> - <para>AMI FastDisk controllers that are true BusLogic - MultiMaster clones are also supported.</para> - - <note> - <para>BusLogic/Mylex <quote>Flashpoint</quote> adapters are NOT - yet supported.</para> - </note> - </listitem> - - <listitem> - <para>DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III, - SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The - DPT SmartRAID/CACHE V is not yet supported.</para> - </listitem> - - <listitem> - <para>Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES, - SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and - Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES.</para> - </listitem> - - <listitem> - <para>SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820, - 53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI - controllers including ASUS SC-200, Data Technology DTC3130 - (all variants), Diamond FirePort (all), NCR cards (all), - SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan - S1365</para> - </listitem> - - <listitem> - <para>QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre - Channel Adapters</para> - </listitem> - - <listitem> - <para>DTC 3290 EISA SCSI controller in 1542 evaluation - mode</para> - </listitem> - </itemizedlist> - - <para>With all supported SCSI controllers, full support is provided - for SCSI-I and SCSI-II peripherals, including hard disks, optical - disks, tape drives (including DAT and 8mm Exabyte), medium - changers, processor target devices, and CDROM drives. WORM - devices that support CDROM commands are supported for read-only - access by the CDROM driver. WORM/CD-R/CD-RW writing support is - provided by cdrecord, which is in the ports tree.</para> - - <para>The following CD-ROM type systems are supported at this - time:</para> - - <itemizedlist> - <listitem> - <para><devicename>cd</devicename> - SCSI interface (includes - ProAudio Spectrum and SoundBlaster SCSI)</para> - </listitem> - - <listitem> - <para><devicename>matcd</devicename> - Matsushita/Panasonic - (Creative Soundblaster) proprietary interface (562/563 - models)</para> - </listitem> - - <listitem> - <para><devicename>scd</devicename> - Sony proprietary interface - (all models)</para> - </listitem> - - <listitem> - <para><devicename>acd</devicename> - ATAPI IDE interface</para> - </listitem> - </itemizedlist> - - <para>The following drivers were supported under the old SCSI - subsystem, but are NOT YET supported under the new CAM SCSI - subsystem:</para> - - <itemizedlist> - <listitem> - <para>NCR5380/NCR53400 (<quote>ProAudio Spectrum</quote>) SCSI - controller</para> - </listitem> - - <listitem> - <para>UltraStor 14F, 24F, and 34F SCSI controllers</para> - </listitem> - - <listitem> - <para>Seagate ST01/02 SCSI controllers</para> - </listitem> - - <listitem> - <para>Future Domain 8XX/950 series SCSI controllers</para> - </listitem> - - <listitem> - <para>WD7000 SCSI controller</para> - - <note> - <para>There is work-in-progress to port the UltraStor driver - to the new CAM framework, but no estimates on when or if it - will be completed.</para> - </note> - </listitem> - </itemizedlist> - - <para>Unmaintained drivers, which might or might not work for your - hardware:</para> - - <itemizedlist> - <listitem> - <para>Floppy tape interface (Colorado/Mountain/Insight)</para> - </listitem> - - <listitem> - <para><devicename>mcd</devicename> - Mitsumi proprietary CD-ROM - interface (all models)</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-nics"> - <title>Network Cards</title> - - <itemizedlist> - <listitem> - <para>Adaptec Duralink PCI fast ethernet adapters based on the - Adaptec AIC-6195 fast ethernet controller chip, including the - following:</para> - - <itemizedlist> - <listitem> - <para>ANA-62011 64-bit single port 10/100baseTX - adapter</para> - </listitem> - - <listitem> - <para>ANA-62022 64-bit dual port 10/100baseTX adapter</para> - </listitem> - - <listitem> - <para>ANA-62044 64-bit quad port 10/100baseTX adapter</para> - </listitem> - - <listitem> - <para>ANA-69011 32-bit single port 10/100baseTX - adapter</para> - </listitem> - - <listitem> - <para>ANA-62020 64-bit single port 100baseFX adapter</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Allied-Telesyn AT1700 and RE2000 cards</para> - </listitem> - - <listitem> - <para>Alteon Networks PCI gigabit ethernet NICs based on the - Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC - (Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620 - (Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq - EtherWORKS 1000, NEC Gigabit Ethernet</para> - </listitem> - - <listitem> - <para>AMD PCnet/PCI (79c970 and 53c974 or 79c974)</para> - </listitem> - - <listitem> - <para>RealTek 8129/8139 fast ethernet NICs including the - following:</para> - - <itemizedlist> - <listitem> - <para>Allied-Telesyn AT2550</para> - </listitem> - - <listitem> - <para>Allied-Telesyn AT2500TX</para> - </listitem> - - <listitem> - <para>Genius GF100TXR (RTL8139)</para> - </listitem> - - <listitem> - <para>NDC Communications NE100TX-E</para> - </listitem> - - <listitem> - <para>OvisLink LEF-8129TX</para> - </listitem> - - <listitem> - <para>OvisLink LEF-8139TX</para> - </listitem> - - <listitem> - <para>Netronix Inc. EA-1210 NetEther 10/100</para> - </listitem> - - <listitem> - <para>KTX-9130TX 10/100 Fast Ethernet</para> - </listitem> - - <listitem> - <para>Accton <quote>Cheetah</quote> EN1027D (MPX 5030/5038; - RealTek 8139 clone?)</para> - </listitem> - - <listitem> - <para>SMC EZ Card 10/100 PCI 1211-TX</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Lite-On 98713, 98713A, 98715, and 98725 fast ethernet - NICs, including the LinkSys EtherFast LNE100TX, NetGear - FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston - KNE110TX</para> - </listitem> - - <listitem> - <para>Macronix 98713, 98713A, 98715, 98715A, and 98725 fast - ethernet NICs including the NDC Communications SFA100A - (98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B - (98715), SVEC PN102TX (98713)</para> - </listitem> - - <listitem> - <para>Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs - including the LinkSys EtherFast LNE100TX version 2</para> - </listitem> - - <listitem> - <para>Winbond W89C840F fast ethernet NICs including the - Trendware TE100-PCIE</para> - </listitem> - - <listitem> - <para>VIA Technologies VT3043 <quote>Rhine I</quote> and - VT86C100A <quote>Rhine II</quote> fast ethernet NICs including - the Hawking Technologies PN102TX and D-Link DFE-530TX</para> - </listitem> - - <listitem> - <para>Silicon Integrated Systems SiS 900 and SiS 7016 PCI fast - ethernet NICs</para> - </listitem> - - <listitem> - <para>Sundance Technologies ST201 PCI fast ethernet NICs - including the D-Link DFE-550TX</para> - </listitem> - - <listitem> - <para>SysKonnect SK-984x PCI gigabit ethernet cards including - the SK-9841 1000baseLX (single mode fiber, single port), - the SK-9842 1000baseSX (multimode fiber, single port), the - SK-9843 1000baseLX (single mode fiber, dual port), and the - SK-9844 1000baseSX (multimode fiber, dual port).</para> - </listitem> - - <listitem> - <para>Texas Instruments ThunderLAN PCI NICs, including the - Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100 - Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and - 10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P - w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX - UTP, and the Racore 8165 10/100baseTX and 8148 - 10baseT/100baseTX/100baseFX multi-personality cards</para> - </listitem> - - <listitem> - <para>ADMtek AL981-based and AN985-based PCI fast ethernet - NICs</para> - </listitem> - - <listitem> - <para>ASIX Electronics AX88140A PCI NICs including the Alfa Inc. - GFC2204 and CNet Pro110B</para> - </listitem> - - <listitem> - <para>DEC EtherWORKS III NICs (DE203, DE204, and DE205)</para> - </listitem> - - <listitem> - <para>DEC EtherWORKS II NICs (DE200, DE201, DE202, and - DE422)</para> - </listitem> - - <listitem> - <para>DEC DC21040, DC21041, or DC21140 based NICs (SMC - Etherpower 8432T, DE245, etc.)</para> - </listitem> - - <listitem> - <para>DEC FDDI (DEFPA/DEFEA) NICs</para> - </listitem> - - <listitem> - <para>Efficient ENI-155p ATM PCI</para> - </listitem> - - <listitem> - <para>FORE PCA-200E ATM PCI</para> - </listitem> - - <listitem> - <para>Fujitsu MB86960A/MB86965A</para> - </listitem> - - <listitem> - <para>HP PC Lan+ cards (model numbers: 27247B and 27252A)</para> - </listitem> - - <listitem> - <para>Intel EtherExpress ISA (not recommended due to driver - instability)</para> - </listitem> - - <listitem> - <para>Intel EtherExpress Pro/10</para> - </listitem> - - <listitem> - <para>Intel EtherExpress Pro/100B PCI Fast Ethernet</para> - </listitem> - - <listitem> - <para>Isolan AT 4141-0 (16 bit)</para> - </listitem> - - <listitem> - <para>Isolink 4110 (8 bit)</para> - </listitem> - - <listitem> - <para>Novell NE1000, NE2000, and NE2100 Ethernet - interfaces</para> - </listitem> - - <listitem> - <para>PCI network cards emulating the NE2000, including the - RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA - VT86C926</para> - </listitem> - - <listitem> - <para>3Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507 - Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA), - 3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink - III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL - server adapter, 3CSOHO100-TX OfficeConnect adapter</para> - </listitem> - - <listitem> - <para>Toshiba ethernet cards</para> - </listitem> - - <listitem> - <para>PCMCIA ethernet cards from IBM and National Semiconductor - are also supported</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-usb"> - <title>USB Peripherals</title> - - <para>A wide range of USB peripherals are supported. Owing to the - generic nature of most USB devices, with some exceptions any - device of a given class will be supported even if not explicitly - listed here.</para> - - <itemizedlist> - <listitem> - <para>USB keyboards</para> - </listitem> - - <listitem> - <para>USB mice</para> - </listitem> - - <listitem> - <para>USB printers and USB to parallel printer conversion - cables</para> - </listitem> - - <listitem> - <para>USB hubs</para> - </listitem> - </itemizedlist> - - <para>Motherboard chipsets:</para> - - <itemizedlist> - <listitem> - <para>ALi Aladdin-V</para> - </listitem> - - <listitem> - <para>Intel 82371SB (PIIX3) and 82371AB and EB (PIIX4) - chipsets</para> - </listitem> - - <listitem> - <para>NEC uPD 9210 Host Controller</para> - </listitem> - - <listitem> - <para>VIA 83C572 USB Host Controller</para> - - <para>and any other UHCI or OHCI compliant motherboard chipset - (no exceptions known).</para> - </listitem> - </itemizedlist> - - <para>PCI plug-in USB host controllers</para> - - <itemizedlist> - <listitem> - <para>ADS Electronics PCI plug-in card (2 ports)</para> - </listitem> - - <listitem> - <para>Entrega PCI plug-in card (4 ports)</para> - </listitem> - </itemizedlist> - - <para>Specific USB devices reported to be working:</para> - - <itemizedlist> - <listitem> - <para>Agiler Mouse 29UO</para> - </listitem> - - <listitem> - <para>Andromeda hub</para> - </listitem> - - <listitem> - <para>Apple iMac mouse and keyboard</para> - </listitem> - - <listitem> - <para>ATen parallel printer adapter</para> - </listitem> - - <listitem> - <para>Belkin F4U002 parallel printer adapter and Belkin - mouse</para> - </listitem> - - <listitem> - <para>BTC BTC7935 keyboard with mouse port</para> - </listitem> - - <listitem> - <para>Cherry G81-3504</para> - </listitem> - - <listitem> - <para>Chic mouse</para> - </listitem> - - <listitem> - <para>Cypress mouse</para> - </listitem> - - <listitem> - <para>Entrega USB-to-parallel printer adapter</para> - </listitem> - - <listitem> - <para>Genius Niche mouse</para> - </listitem> - - <listitem> - <para>Iomega USB Zip 100 MB</para> - </listitem> - - <listitem> - <para>Kensington Mouse-in-a-Box</para> - </listitem> - - <listitem> - <para>Logitech M2452 keyboard</para> - </listitem> - - <listitem> - <para>Logictech wheel mouse (3 buttons)</para> - </listitem> - - <listitem> - <para>Logitech PS/2 / USB mouse (3 buttons)</para> - </listitem> - - <listitem> - <para>MacAlly mouse (3 buttons)</para> - </listitem> - - <listitem> - <para>MacAlly self-powered hub (4 ports)</para> - </listitem> - - <listitem> - <para>Microsoft Intellimouse (3 buttons)</para> - </listitem> - - <listitem> - <para>Microsoft keyboard</para> - </listitem> - - <listitem> - <para>NEC hub</para> - </listitem> - - <listitem> - <para>Trust Ami Mouse (3 buttons)</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-isdn"> - <title>ISDN (European DSS1 [Q.921/Q.931] protocol)</title> - - <itemizedlist> - <listitem> - <para>Asuscom I-IN100-ST-DV (experimental, may work)</para> - </listitem> - - <listitem> - <para>Asuscom ISDNlink 128K</para> - </listitem> - - <listitem> - <para>AVM A1</para> - </listitem> - - <listitem> - <para>AVM Fritz!Card classic</para> - </listitem> - - <listitem> - <para>AVM Fritz!Card PCI</para> - </listitem> - - <listitem> - <para>AVM Fritz!Card PCMCIA (currently FreeBSD 3.x only)</para> - </listitem> - - <listitem> - <para>AVM Fritz!Card PnP (currently FreeBSD 3.x only)</para> - </listitem> - - <listitem> - <para>Creatix ISDN-S0/8</para> - </listitem> - - <listitem> - <para>Creatix ISDN-S0/16</para> - </listitem> - - <listitem> - <para>Creatix ISDN-S0 PnP</para> - </listitem> - - <listitem> - <para>Dr.Neuhaus Niccy 1008</para> - </listitem> - - <listitem> - <para>Dr.Neuhaus Niccy 1016</para> - </listitem> - - <listitem> - <para>Dr.Neuhaus Niccy GO@ (ISA PnP)</para> - </listitem> - - <listitem> - <para>Dynalink IS64PH (no longer maintained)</para> - </listitem> - - <listitem> - <para>ELSA 1000pro ISA</para> - </listitem> - - <listitem> - <para>ELSA 1000pro PCI</para> - </listitem> - - <listitem> - <para>ELSA PCC-16</para> - </listitem> - - <listitem> - <para>ITK ix1 micro (currently FreeBSD 3.x only)</para> - </listitem> - - <listitem> - <para>ITK ix1 micro V.3 (currently FreeBSD 3.x only)</para> - </listitem> - - <listitem> - <para>Sagem Cybermod (ISA PnP, may work)</para> - </listitem> - - <listitem> - <para>Sedlbauer Win Speed</para> - </listitem> - - <listitem> - <para>Siemens I-Surf 2.0</para> - </listitem> - - <listitem> - <para>Stollman Tina-pp (under development)</para> - </listitem> - - <listitem> - <para>Teles S0/8</para> - </listitem> - - <listitem> - <para>Teles S0/16</para> - </listitem> - - <listitem> - <para>Teles S0/16.3 (the <quote>c</quote> Versions - like 16.3c - - are unsupported!)</para> - </listitem> - - <listitem> - <para>Teles S0 PnP (experimental, may work)</para> - </listitem> - - <listitem> - <para>3Com/USRobotics Sportster ISDN TA intern (non-PnP - version)</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-sound"> - <title>Sound Devices</title> - - <para>The following soundcards or codecs are supported (devices marked - 'experimental' are only supported in FreeBSD-CURRENT and might - work only unstably):</para> - - <itemizedlist> - <listitem> - <para>16550 UART (Midi) (experimental, needs a trick in the hints - file)</para> - </listitem> - - <listitem> - <para>Advance Asound 100, 110 and Logic ALS120</para> - </listitem> - - <listitem> - <para>Aureal Vortex1/Vortex2 and Vortex Advantage based soundcards - by a - <ulink url="http://www.cis.ohio-state.edu/~matey/au88x0/">third - party driver</ulink></para> - </listitem> - - <listitem> - <para>Creative Labs SB16, SB32, SB AWE64 (including Gold), - Vibra16, SB PCI (experimental), SB Live! (experimental) - and most SoundBlaster compatible cards</para> - </listitem> - - <listitem> - <para>Creative Labs SB Midi Port (experimental), SB OPL3 - Synthesizer (experimental)</para> - </listitem> - - <listitem> - <para>Crystal Semiconductor CS461x/462x Audio Accelerator, - the support for the CS461x Midi port is experimental</para> - </listitem> - - <listitem> - <para>Crystal Semiconductor CS428x Audio Controller</para> - </listitem> - - <listitem> - <para>CS4237, CS4236, CS4232, CS4231 (ISA)</para> - </listitem> - - <listitem> - <para>ENSONIQ AudioPCI ES1370/1371</para> - </listitem> - - <listitem> - <para>ESS ES1868, ES1869, ES1879, ES1888</para> - </listitem> - - <listitem> - <para>Gravis UltraSound PnP, MAX</para> - </listitem> - - <listitem> - <para>NeoMagic 256AV/ZX (PCI)</para> - </listitem> - - <listitem> - <para>OPTi931 (ISA)</para> - </listitem> - - <listitem> - <para>OSS-compatible sequencer (Midi) (experimental)</para> - </listitem> - - <listitem> - <para>Trident 4DWave DX/NX (PCI)</para> - </listitem> - - <listitem> - <para>Yahama OPL-SAx (ISA)</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="install-misc"> - <title>Miscellaneous Devices</title> - - <itemizedlist> - <listitem> - <para>AST 4 port serial card using shared IRQ</para> - </listitem> - - <listitem> - <para>ARNET 8 port serial card using shared IRQ</para> - </listitem> - - <listitem> - <para>ARNET (now Digiboard) Sync 570/i high-speed serial</para> - </listitem> - - <listitem> - <para>Boca BB1004 4-Port serial card (Modems NOT - supported)</para> - </listitem> - - <listitem> - <para>Boca IOAT66 6-Port serial card (Modems supported)</para> - </listitem> - - <listitem> - <para>Boca BB1008 8-Port serial card (Modems NOT - supported)</para> - </listitem> - - <listitem> - <para>Boca BB2016 16-Port serial card (Modems supported)</para> - </listitem> - - <listitem> - <para>Cyclades Cyclom-y Serial Board</para> - </listitem> - - <listitem> - <para>Moxa SmartIO CI-104J 4-Port serial card</para> - </listitem> - - <listitem> - <para>STB 4 port card using shared IRQ</para> - </listitem> - - <listitem> - <para>SDL Communications RISCom/8 Serial Board</para> - </listitem> - - <listitem> - <para>SDL Communications RISCom/N2 and N2pci high-speed sync - serial boards</para> - </listitem> - - <listitem> - <para>Specialix SI/XIO/SX multiport serial cards, with both the - older SIHOST2.x and the new <quote>enhanced</quote> - (transputer based, aka JET) host cards; ISA, EISA and PCI are - supported</para> - </listitem> - - <listitem> - <para>Stallion multiport serial boards: EasyIO, EasyConnection - 8/32 & 8/64, ONboard 4/16 and Brumby</para> - </listitem> - - <listitem> - <para>Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum, - Gravis UltraSound, and Roland MPU-401 sound cards</para> - </listitem> - - <listitem> - <para>Connectix QuickCam</para> - </listitem> - - <listitem> - <para>Matrox Meteor Video frame grabber</para> - </listitem> - - <listitem> - <para>Creative Labs Video Spigot frame grabber</para> - </listitem> - - <listitem> - <para>Cortex1 frame grabber</para> - </listitem> - - <listitem> - <para>Various frame grabbers based on the Brooktree Bt848 - and Bt878 chip</para> - </listitem> - - <listitem> - <para>HP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R - drives</para> - </listitem> - - <listitem> - <para>Bus mice</para> - </listitem> - - <listitem> - <para>PS/2 mice</para> - </listitem> - - <listitem> - <para>Standard PC Joystick</para> - </listitem> - - <listitem> - <para>X-10 power controllers</para> - </listitem> - - <listitem> - <para>GPIB and Transputer drives</para> - </listitem> - - <listitem> - <para>Genius and Mustek hand scanners</para> - </listitem> - - <listitem> - <para>Floppy tape drives (some rather old models only, driver is - rather stale)</para> - </listitem> - - <listitem> - <para>Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA - standard speed (2Mbps) and turbo speed (6Mbps) wireless - network adapters and workalikes (NCR WaveLAN/IEEE 802.11, - Cabletron RoamAbout 802.11 DS)</para> - - <note> - <para>The ISA versions of these adapters are actually PCMCIA - cards combined with an ISA to PCMCIA bridge card, so both - kinds of devices work with the same driver.</para> - </note> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="install-trouble"> - <title>Troubleshooting</title> - - <para>The following section covers basic installation troubleshooting, - such as common problems people have reported. There are also a few - questions and answers for people wishing to dual-boot FreeBSD with - MS-DOS.</para> - - <sect2> - <title>What to do if something goes wrong...</title> - - <para>Due to various limitations of the PC architecture, it is - impossible for probing to be 100% reliable, however, there are a - few things you can do if it fails.</para> - - <para>Check the <link linkend="install-hw">supported - hardware</link> list to make sure your hardware is - supported.</para> - - <para>If your hardware is supported and you still experience - lock-ups or other problems, reset your computer, and when the - visual kernel configuration option is given, choose it. This will - allow you to go through your hardware and supply information to the - system about it. The kernel on the boot disks is configured - assuming that most hardware devices are in their factory default - configuration in terms of IRQs, IO addresses, and DMA channels. If - your hardware has been reconfigured, you will most likely need to - use the configuration editor to tell FreeBSD where to find - things.</para> - - <para>It is also possible that a probe for a device not present will - cause a later probe for another device that is present to fail. In - that case, the probes for the conflicting driver(s) should be - disabled.</para> - - <warning> - <para>Do not disable any drivers you will need during the - installation, such as your screen (<devicename>sc0</devicename>). - If the installation wedges or fails mysteriously after leaving - the configuration editor, you have probably removed or changed - something you should not have. Reboot and try again.</para> - </warning> - - <para>In configuration mode, you can:</para> - - <itemizedlist> - <listitem> - <para>List the device drivers installed in the kernel.</para> - </listitem> - - <listitem> - <para>Change device drivers for hardware that is not present in - your system.</para> - </listitem> - - <listitem> - <para>Change IRQs, DRQs, and IO port addresses used by a device - driver.</para> - </listitem> - </itemizedlist> - - <para>After adjusting the kernel to match your hardware - configuration, type <command>Q</command> to boot with the new - settings. Once the installation has completed, any changes you - made in the configuration mode will be permanent so you do not have - to reconfigure every time you boot. It is still highly likely that - you will eventually want to build a <link - linkend="kernelconfig">custom kernel</link>.</para> - </sect2> - - <sect2> - <title>MS-DOS User's Questions and Answers</title> - - <para>Many users wish to install FreeBSD on PCs inhabited by MS-DOS. - Here are some commonly asked questions about installing FreeBSD on - such systems.</para> - - <qandaset> - <qandaentry> - <question> - <para>Help, I have no space! Do I need to delete everything - first?</para> - </question> - - <answer> - <para>If your machine is already running MS-DOS and has little - or no free space available for the FreeBSD installation, all - hope is not lost! You may find the FIPS utility, provided - in the <filename>tools</filename> directory on the FreeBSD - CDROM or various FreeBSD FTP sites to be quite - useful.</para> - - <para>FIPS allows you to split an existing MS-DOS partition - into two pieces, preserving the original partition and - allowing you to install onto the second free piece. You - first defragment your MS-DOS partition using the Windows - DEFRAG utility (go into Explorer, right-click on the - hard drive, and choose to defrag your - hard drive), or Norton Disk Tools. You then must run FIPS. It - will prompt you for the rest of the information it needs. - Afterwards, you can reboot and install FreeBSD on the new - free slice. See the <emphasis>Distributions</emphasis> menu - for an estimate of how much free space you will need for the - kind of installation you want.</para> - - <para>There is also a <emphasis>very</emphasis> useful - product from <ulink - url="http://www.powerquest.com/">PowerQuest</ulink> - called <application>Partition Magic</application>. This - application has far more functionality than FIPS, and is - highly recommended if you plan to often add/remove - operating systems (like me). However, it does cost - money, and if you plan to install FreeBSD once and then - leave it there, FIPS will probably be fine for you.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I use compressed MS-DOS filesystems from - FreeBSD?</para> - </question> - - <answer> - <para>No. If you are using a utility such as Stacker(tm) or - DoubleSpace(tm), FreeBSD will only be able to use whatever - portion of the filesystem you leave uncompressed. The rest - of the filesystem will show up as one large file (the - stacked/double spaced file!). <emphasis>Do not remove that - file or you will probably regret it - greatly!</emphasis></para> - - <para>It is probably better to create another uncompressed - primary MS-DOS partition and use this for communications - between MS-DOS and FreeBSD.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I mount my extended MS-DOS partition?</para> - </question> - - <answer> - <para>Yes. DOS extended partitions are mapped in at the end - of the other <quote>slices</quote> in FreeBSD, e.g., your - <devicename>D:</devicename> drive might be - <filename>/dev/da0s5</filename>, your - <devicename>E:</devicename> drive, - <filename>/dev/da0s6</filename>, and so on. This example - assumes, of course, that your extended partition is on SCSI - drive 0. For IDE drives, substitute <filename>ad</filename> - for <filename>da</filename> appropriately if installing - 4.0-RELEASE or later, and substitute - <filename>wd</filename> for <filename>da</filename> if you - are installing a version of FreeBSD prior to 4.0. You otherwise - mount extended partitions exactly like you would any other - DOS drive, for example:</para> - - <screen>&prompt.root; <userinput>mount -t msdos /dev/ad0s5 /dos_d</userinput></screen> - </answer> - </qandaentry> - </qandaset> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml deleted file mode 100644 index 7a5572e19c..0000000000 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml +++ /dev/null @@ -1,709 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml,v 1.34 2000/10/30 01:01:31 jim Exp $ ---> - -<chapter id="introduction"> - <title>Introduction</title> - - <para><emphasis>Restructured, reorganized, and parts rewritten by - &a.jim;, 17 January 2000.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>Thank you for your interest in FreeBSD! The following chapter - covers various items about the FreeBSD Project, such as its history, - goals, development model, and so on.</para> - - <para>FreeBSD is a 4.4BSD-Lite based operating system for the Intel - architecture (x86) and DEC Alpha based systems. Ports to other - architectures are also underway. For a brief overview of FreeBSD, - see the <link linkend="nutshell">next section</link>. You can also - read about <link linkend="history">the history of FreeBSD</link>, - or the <link linkend="relnotes">current release</link>. If you - are interested in contributing something to the Project (code, - hardware, unmarked bills), see the <link - linkend="contrib">contributing to FreeBSD</link> section.</para> - </sect1> - - <sect1 id="nutshell"> - <title>Welcome to FreeBSD!</title> - - <para>Since you are still here reading this, you most likely have some - idea as to what FreeBSD is and what it can do for you. If you are - new to FreeBSD, read on for more information.</para> - - <sect2> - <title>What is FreeBSD?</title> - - <para>In general, FreeBSD is a state-of-the-art operating system - based on 4.4BSD-Lite. It runs on computer systems based on the - Intel architecture (x86), and also the DEC Alpha - architecture.</para> - - <para>FreeBSD is used to power some of the biggest sites on the - Internet, including:</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.yahoo.com/">Yahoo!</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.hotmail.com/">Hotmail</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.apache.org/">Apache</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.be.com/">Be, Inc.</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.bluemountain.com/">Blue Mountain - Arts</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.pair.com/">Pair - Networks</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.whistle.com/">Whistle - Communications</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink></para> - </listitem> - </itemizedlist> - - <para>and many more.</para> - </sect2> - - <sect2> - <title>What can FreeBSD do?</title> - - <para>FreeBSD has many noteworthy features. Some of these - are:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Preemptive multitasking</emphasis> with - dynamic priority adjustment to ensure smooth and fair - sharing of the computer between applications and users, even - under the heaviest of loads.</para> - </listitem> - - <listitem> - <para><emphasis>Multi-user facilities</emphasis> which allow many - people to use a FreeBSD system simultaneously for a variety - of things. This means, for example, that system peripherals - such as printers and tape drives are properly shared between - all users on the system or the network and that individual - resource limits can be placed on users or groups of users, - protecting critical system resources from over-use.</para> - </listitem> - - <listitem> - <para>Strong <emphasis>TCP/IP networking</emphasis> with - support for industry standards such as SLIP, PPP, NFS, DHCP, - and NIS. This means that your FreeBSD machine can - inter-operate easily with other systems as well as act as an - enterprise server, providing vital functions such as NFS - (remote file access) and e-mail services or putting your - organization on the Internet with WWW, FTP, routing and - firewall (security) services.</para> - </listitem> - - <listitem> - <para><emphasis>Memory protection</emphasis> ensures that - applications (or users) cannot interfere with each other. One - application crashing will not affect others in any way.</para> - </listitem> - - <listitem> - <para>FreeBSD is a <emphasis>32-bit</emphasis> operating - system (<emphasis>64-bit</emphasis> on the Alpha) and was - designed as such from the ground up.</para> - </listitem> - - <listitem> - <para>The industry standard <emphasis>X Window System</emphasis> - (X11R6) provides a graphical user interface (GUI) for the cost - of a common VGA card and monitor and comes with full - sources.</para> - </listitem> - - <listitem> - <para><emphasis>Binary compatibility</emphasis> with many - programs built for Linux, SCO, SVR4, BSDI and NetBSD.</para> - </listitem> - - <listitem> - <para>Thousands of <emphasis>ready-to-run</emphasis> - applications are available from the FreeBSD - <emphasis>ports</emphasis> and <emphasis>packages</emphasis> - collection. Why search the net when you can find it all right - here?</para> - </listitem> - - <listitem> - <para>Thousands of additional and - <emphasis>easy-to-port</emphasis> applications are available - on the Internet. FreeBSD is source code compatible with most - popular commercial Unix systems and thus most applications - require few, if any, changes to compile.</para> - </listitem> - - <listitem> - <para>Demand paged <emphasis>virtual memory</emphasis> and - <quote>merged VM/buffer cache</quote> design efficiently - satisfies applications with large appetites for memory while - still maintaining interactive response to other users.</para> - </listitem> - - <listitem> - <para><emphasis>SMP</emphasis> support for machines with - multiple CPUs (Intel only).</para> - </listitem> - - <listitem> - <para>A full complement of <emphasis>C</emphasis>, - <emphasis>C++</emphasis>, <emphasis>Fortran</emphasis>, and - <emphasis>Perl</emphasis> development tools. - Many additional languages for advanced research - and development are also available in the ports and packages - collection.</para> - </listitem> - - <listitem> - <para><emphasis>Source code</emphasis> for the entire system - means you have the greatest degree of control over your - environment. Why be locked into a proprietary solution - at the mercy of your vendor when you can have a truly Open - System?</para> - </listitem> - - <listitem> - <para>Extensive <emphasis>on-line - documentation</emphasis>.</para> - </listitem> - - <listitem> - <para><emphasis>And many more!</emphasis></para> - </listitem> - </itemizedlist> - - <para>FreeBSD is based on the 4.4BSD-Lite release from Computer - Systems Research Group (CSRG) at the University of California at - Berkeley, and carries on the distinguished tradition of BSD - systems development. In addition to the fine work provided by - CSRG, the FreeBSD Project has put in many thousands of hours in - fine tuning the system for maximum performance and reliability in - real-life load situations. As many of the commercial giants - struggle to field PC operating systems with such features, - performance and reliability, FreeBSD can offer them - <emphasis>now</emphasis>!</para> - - <para>The applications to which FreeBSD can be put are truly - 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 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 universities around the world, often - available at little to no cost. Commercial applications are also - available and appearing in greater numbers every day.</para> - - <para>Because the source code for FreeBSD itself is generally - available, the system can also be customized to an almost unheard - of degree for special applications or projects, and in ways not - generally possible with operating systems from most major - commercial vendors. Here is just a sampling of some of the - applications in which people are currently using FreeBSD:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Internet Services:</emphasis> The robust TCP/IP - networking built into FreeBSD makes it an ideal platform for a - variety of Internet services such as:</para> - - <itemizedlist> - <listitem> - <para>FTP servers</para> - </listitem> - - <listitem> - <para>World Wide Web servers (standard or secure - [SSL])</para> - </listitem> - - <listitem> - <para>Firewalls and NAT (<quote>IP masquerading</quote>) - gateways.</para> - </listitem> - - <listitem> - <para>Electronic Mail servers</para> - </listitem> - - <listitem> - <para>USENET News or Bulletin Board Systems</para> - </listitem> - - <listitem> - <para>And more...</para> - </listitem> - </itemizedlist> - - <para>With FreeBSD, you can easily start out small with an - inexpensive 386 class PC and upgrade all the way up to a - quad-processor Xeon with RAID storage as your enterprise - grows.</para> - </listitem> - - <listitem> - <para><emphasis>Education:</emphasis> Are you a student of - computer science or a related engineering field? There is no - better way of learning about operating systems, computer - architecture and networking than the hands on, under the hood - experience that FreeBSD can provide. A number of freely - available CAD, mathematical and graphic design packages also - make it highly useful to those whose primary interest in a - computer is to get <emphasis>other</emphasis> work - done!</para> - </listitem> - - <listitem> - <para><emphasis>Research:</emphasis> With source code for the - entire system available, FreeBSD is an excellent platform for - research in operating systems as well as other branches of - computer science. FreeBSD's freely available nature also makes - it possible for remote groups to collaborate on ideas or - shared development without having to worry about special - licensing agreements or limitations on what may be discussed - in open forums.</para> - </listitem> - - <listitem> - <para><emphasis>Networking:</emphasis> Need a new router? A - name server (DNS)? A firewall to keep people out of your - internal network? FreeBSD can easily turn that unused 386 or - 486 PC sitting in the corner into an advanced router with - sophisticated packet-filtering capabilities.</para> - </listitem> - - <listitem> - <para><emphasis>X Window workstation:</emphasis> FreeBSD is a - fine choice for an inexpensive X terminal solution, either - using the freely available XFree86 server or one of the - excellent commercial servers provided by X Inside. Unlike an - X terminal, FreeBSD allows many applications to be run - locally, if desired, thus relieving the burden on a central - server. FreeBSD can even boot <quote>diskless</quote>, making - individual workstations even cheaper and easier to - administer.</para> - </listitem> - - <listitem> - <para><emphasis>Software Development:</emphasis> The basic - FreeBSD system comes with a full complement of development - tools including the renowned GNU C/C++ compiler and - debugger.</para> - </listitem> - </itemizedlist> - - <para>FreeBSD is available in both source and binary form on CDROM - and via anonymous FTP. See <link linkend="mirrors">Obtaining - FreeBSD</link> for more details.</para> - </sect2> - </sect1> - - <sect1 id="history"> - <title>About the FreeBSD Project</title> - - <para>The following section provides some background information on - the project, including a brief history, project goals, and the - development model of the project.</para> - - <sect2> - <title>A Brief History of FreeBSD</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis>.</para> - - <para>The FreeBSD project had its genesis in the early part of 1993, - partially as an outgrowth of the <quote>Unofficial 386BSD - Patchkit</quote> by the patchkit's last 3 coordinators: Nate - Williams, Rod Grimes and myself.</para> - - <para>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 was not capable of solving. Some of you - may remember the early working title for the project being - <quote>386BSD 0.5</quote> or <quote>386BSD Interim</quote> in - reference to that fact.</para> - - <para>386BSD was Bill Jolitz's operating system, which had been up - to that point suffering rather severely from almost a year's worth - of neglect. As the patchkit swelled ever more uncomfortably with - each passing day, we were in unanimous agreement that something - had to be done and decided to try and assist Bill by providing - this interim <quote>cleanup</quote> snapshot. Those plans came to - a rude halt when Bill Jolitz suddenly decided to withdraw his - sanction from the project without any clear indication of what - would be done instead.</para> - - <para>It did not take us long to decide that the goal remained - worthwhile, even without Bill's support, and so we adopted the - name <quote>FreeBSD</quote>, coined by David Greenman. Our initial - objectives were set after consulting with the system's current - users and, once it became clear that the project was on the road - to perhaps even becoming a reality, I contacted Walnut Creek CDROM - with an eye towards improving FreeBSD's distribution channels for - those many unfortunates without easy access to the Internet. - Walnut Creek CDROM not only supported the idea of distributing - FreeBSD on CD but also went so far as to provide the project with a - machine to work on and a fast Internet connection. Without Walnut - Creek CDROM's almost unprecedented degree of faith in what was, at - the time, a completely unknown project, it is quite unlikely that - FreeBSD would have gotten as far, as fast, as it has today.</para> - - <para>The first CDROM (and general net-wide) distribution was - FreeBSD 1.0, released in December of 1993. This was based on the - 4.3BSD-Lite (<quote>Net/2</quote>) tape from U.C. Berkeley, with - many components also provided by 386BSD and the Free Software - Foundation. It was a fairly reasonable success for a first - offering, and we followed it with the highly successful FreeBSD - 1.1 release in May of 1994.</para> - - <para>Around this time, some rather unexpected storm clouds formed - on the horizon as Novell and U.C. Berkeley settled their - long-running lawsuit over the legal status of the Berkeley Net/2 - tape. A condition of that settlement was U.C. Berkeley's - concession that large parts of Net/2 were <quote>encumbered</quote> - code and the property of Novell, who had in turn acquired it from - AT&T some time previously. What Berkeley got in return was - Novell's <quote>blessing</quote> that the 4.4BSD-Lite release, when - it was finally released, would be declared unencumbered and all - existing Net/2 users would be strongly encouraged to switch. This - included FreeBSD, and the project was given until the end of July - 1994 to stop shipping its own Net/2 based product. Under the - terms of that agreement, the project was allowed one last release - before the deadline, that release being FreeBSD 1.1.5.1.</para> - - <para>FreeBSD then set about the arduous task of literally - re-inventing itself from a completely new and rather incomplete - set of 4.4BSD-Lite bits. The <quote>Lite</quote> releases were - light in part because Berkeley's CSRG had removed large chunks of - code required for actually constructing a bootable running system - (due to various legal requirements) and the fact that the Intel - port of 4.4 was highly incomplete. It took the project until - November of 1994 to make this transition, at which point it - released FreeBSD 2.0 to the net and on CDROM (in late December). - Despite being still more than a little rough around the edges, - the release was a significant success and was followed by the - more robust and easier to install FreeBSD 2.0.5 release in June of - 1995.</para> - - <para>We released FreeBSD 2.1.5 in August of 1996, and it appeared - to be popular enough among the ISP and commercial communities that - another release along the 2.1-STABLE branch was merited. This was - FreeBSD 2.1.7.1, released in February 1997 and capping the end of - mainstream development on 2.1-STABLE. Now in maintenance mode, - only security enhancements and other critical bug fixes will be - done on this branch (RELENG_2_1_0).</para> - - <para>FreeBSD 2.2 was branched from the development mainline - (<quote>-CURRENT</quote>) in November 1996 as the RELENG_2_2 - branch, and the first full release (2.2.1) was released in April - 1997. Further releases along the 2.2 branch were done in the - summer and fall of '97, the last of which (2.2.8) appeared in - November 1998. The first official 3.0 release appeared in - October 1998 and spelled the beginning of the end for the 2.2 - branch.</para> - - <para>The tree branched again on Jan 20, 1999, leading to the - 4.0-CURRENT and 3.X-STABLE branches. From 3.X-STABLE, 3.1 was - released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on - September 16, 1999, 3.4 on December 20, 1999, and 3.5 on - June 24, 2000, which was followed a few days later by a minor - point release update to 3.5.1, to incorporate some last-minute - security fixes to Kerberos. This will be the final release in the - 3.X branch.</para> - - <para>There was another branch on March 13, 2000, which saw the - emergence of the 5.0-CURRENT and 4.X-STABLE branches. The only - release from this branch so far is &rel.current;-RELEASE.</para> - - <para>The current -stable branch is 4.x-stable. 4.0-RELEASE - came out in March 2000, 4.1 was released in July 2000 and - 4.2 in November 2000. There will be more releases along the - 4.x-stable (RELENG_4) branch well into 2001.</para> - - <para>Long-term development projects continue to take place in the - 5.0-CURRENT branch, and SNAPshot releases of 5.0 on CDROM (and, of - course, on the net) are continually made available as work - progresses.</para> - </sect2> - - <sect2 id="goals"> - <title>FreeBSD Project Goals</title> - - <para><emphasis>Contributed by &a.jkh;</emphasis>.</para> - - <para>The goals of the FreeBSD Project are to provide software that - may be used for any purpose and without strings attached. Many of - us have a significant investment in the code (and project) and - would certainly not mind a little financial compensation now and - then, but we are definitely not prepared to insist on it. We - believe that our first and foremost <quote>mission</quote> is to - provide code to any and all comers, and for whatever purpose, so - that the code gets the widest possible use and provides the widest - possible benefit. This is, I believe, one of the most fundamental - goals of Free Software and one that we enthusiastically - support.</para> - - <para>That code in our source tree which falls under the GNU General - Public License (GPL) or Library General Public License (LGPL) - comes with slightly more strings attached, though at least on the - side of enforced access rather than the usual opposite. Due to - the additional complexities that can evolve in the commercial use - of GPL software we do, however, prefer software submitted under - the more relaxed BSD copyright when it's a reasonable option to - do so.</para> - </sect2> - - <sect2 id="development"> - <title>The FreeBSD Development Model</title> - - <para><emphasis>Contributed by &a.asami;</emphasis>.</para> - - <para>The development of FreeBSD is a very open and flexible - process, FreeBSD being literally built from the contributions of - hundreds of people around the world, as can be seen from our - <link linkend="staff">list of contributors</link>. We are - constantly on the lookout for new developers and ideas, and those - interested in becoming more closely involved with the project - need simply contact us at the &a.hackers;. The &a.announce; is - also available to those wishing to make other FreeBSD users aware - of major areas of work.</para> - - <para>Useful things to know about the FreeBSD project and its - development process, whether working independently or in close - cooperation:</para> - - <variablelist> - <varlistentry> - <term>The CVS repository<anchor - id="development-cvs-repository"></term> - - <listitem> - <para>The central source tree for FreeBSD is maintained by - <ulink url="http://www.cyclic.com/CVS/index_html">CVS</ulink> - (Concurrent Version System), a freely available source code - control tool that comes bundled with FreeBSD. The primary - <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVS - repository</ulink> resides on a machine in Concord CA, USA - from where it is replicated to numerous mirror machines - throughout the world. The CVS tree, as well as the <link - linkend="current">-CURRENT</link> and <link - linkend="stable">-STABLE</link> trees which are checked out - of it, can be easily replicated to your own machine as well. - Please refer to the <link linkend="synching">Synchronizing - your source tree</link> section for more information on - doing this.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The committers list<anchor - id="development-committers"></term> - - <listitem> - <para>The <link linkend="staff-committers">committers</link> - are the people who have <emphasis>write</emphasis> access to - the CVS tree, and are thus authorized to make modifications - to the FreeBSD source (the term <quote>committer</quote> - comes from the &man.cvs.1; <command>commit</command> - command, which is used to bring new changes into the CVS - repository). The best way of making submissions for review - by the committers list is to use the &man.send-pr.1; - command, though if something appears to be jammed in the - system then you may also reach them by sending mail to - <email>cvs-committers@FreeBSD.org</email>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The FreeBSD core team<anchor id="development-core"></term> - - <listitem> - <para>The <link linkend="staff-core">FreeBSD core team</link> - would be equivalent to the board of directors if the FreeBSD - Project were a company. The primary task of the core team - is to make sure the project, as a whole, is in good shape - and is heading in the right directions. Inviting dedicated - and responsible developers to join our group of committers - is one of the functions of the core team, as is the - recruitment of new core team members as others move on. - The current core team was elected from a pool of committer - candidates in October 2000. Elections are held every 2 years. - </para> - - <para>Some core team members also have specific <link - linkend="staff-who">areas of responsibility</link>, meaning - that they are committed to ensuring that some large portion - of the system works as advertised.</para> - - <note> - <para>Most members of the core team are volunteers when it - comes to FreeBSD development and do not benefit from the - project financially, so <quote>commitment</quote> should - also not be misconstrued as meaning <quote>guaranteed - support.</quote> The <quote>board of directors</quote> - analogy above is not actually very accurate, and it may be - more suitable to say that these are the people who gave up - their lives in favor of FreeBSD against their better - judgment! <!-- smiley --><emphasis>;-)</emphasis></para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>Outside contributors</term> - - <listitem> - <para>Last, but definitely not least, the largest group of - developers are the users themselves who provide feedback and - bug fixes to us on an almost constant basis. The primary - way of keeping in touch with FreeBSD's more non-centralized - development is to subscribe to the &a.hackers; (see <link - linkend="eresources-mail">mailing list info</link>) where - such things are discussed.</para> - - <para><link linkend="contrib-additional">The list</link> of - those who have contributed something, which made its way into - our source tree, is a long and growing one, so why not join - it by contributing something back to FreeBSD today? - <!-- smiley --><emphasis>:-)</emphasis></para> - - <para>Providing code is not the only way of contributing to - the project; for a more complete list of things that need - doing, please refer to the <link linkend="contrib">how to - contribute</link> section in this handbook.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In summary, our development model is organized as a loose set - of concentric circles. The centralized model is designed for the - convenience of the <emphasis>users</emphasis> of FreeBSD, who are - thereby provided with an easy way of tracking one central code - base, not to keep potential contributors out! Our desire is to - present a stable operating system with a large set of coherent - <link linkend="ports">application programs</link> that the users - can easily install and use, and this model works very well in - accomplishing that.</para> - - <para>All we ask of those who would join us as FreeBSD developers is - some of the same dedication its current people have to its - continued success!</para> - </sect2> - - <sect2 id="relnotes"> - <title>The Current FreeBSD Release</title> - - <para>FreeBSD is a freely available, full source 4.4BSD-Lite based - release for Intel i386, i486, Pentium, Pentium Pro, Celeron, - Pentium II, Pentium III (or compatible) and DEC Alpha based computer - systems. It is based primarily on software from U.C. Berkeley's - CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and - the Free Software Foundation.</para> - - <para>Since our release of FreeBSD 2.0 in late 94, the performance, - feature set, and stability of FreeBSD has improved dramatically. - The largest change is a revamped virtual memory system with a merged - VM/file buffer cache that not only increases performance, but also - reduces FreeBSD's memory footprint, making a 5MB configuration a - more acceptable minimum. Other enhancements include full NIS client - and server support, transaction TCP support, dial-on-demand PPP, - integrated DHCP support, an improved SCSI subsystem, ISDN support, - support for ATM, FDDI, Fast and Gigabit Ethernet (1000Mbit) - adapters, improved support for the latest Adaptec controllers, and - many hundreds of bug fixes.</para> - - <para>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 evolving) process is especially welcome!</para> - - <para>In addition to the base distributions, FreeBSD offers a - ported software collection with thousands of commonly sought-after - programs. By mid-November 2000, there were over 4000 ports! The - list of ports ranges from http (WWW) servers, to games, languages, - editors, and almost everything in between. The entire ports - collection requires approximately 100MB of storage, all ports being - expressed as <quote>deltas</quote> to their original sources. This - makes it much easier for us to update ports, and greatly reduces - the disk space demands made by the older 1.0 ports collection. To - compile a port, you simply change to the directory of the program - you wish to install, type <command>make install</command>, and let - the system do the rest. The full original distribution for each - port you build is retrieved dynamically off the CDROM or a local FTP - site, so you need only enough disk space to build the ports you - want. Almost every port is also provided as a pre-compiled - <quote>package</quote>, which can be installed with a simple command - (pkg_add) by those who do not wish to compile their own ports from - source.</para> - - <para>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 <filename>/usr/share/doc</filename> directory on any machine - running FreeBSD 2.1 or later. You may view the locally installed - manuals with any HTML capable browser using the following - URLs:</para> - - <variablelist> - <varlistentry> - <term>The FreeBSD Handbook</term> - - <listitem> - <para><ulink - url="file:/usr/share/doc/handbook/index.html">file:/usr/share/doc/handbook/index.html</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The FreeBSD FAQ</term> - - <listitem> - <para><ulink - url="file:/usr/share/doc/faq/index.html">file:/usr/share/doc/faq/index.html</ulink></para> - </listitem> - </varlistentry> - </variablelist> - - <para>You can also view the master (and most frequently updated) - copies at <ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink>.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml deleted file mode 100644 index eef1eb6165..0000000000 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml +++ /dev/null @@ -1,1177 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml,v 1.35 2000/08/07 05:59:26 kuriyama Exp $ ---> - -<chapter id="kernelconfig"> - <title>Configuring the FreeBSD Kernel</title> - - <sect1> - <title>Synopsis</title> - - <para><emphasis>Updated and restructured by &a.jim;, March 2000. - Originally contributed by &a.jehamby;, 6 October - 1995.</emphasis></para> - - <para>The following chapter of the handbook covers everything you will - need to know in order to build a custom kernel. If you are - wondering what the benefits of a custom kernel are, or would like to - know how to configure, compile, and install a custom kernel, this - chapter is for you.</para> - </sect1> - - <sect1> - <title>Why Build a Custom Kernel?</title> - - <para>Building a custom kernel is one of the most important rites of - passage nearly every UNIX user must endure. This process, while - time consuming, will provide many benefits to your FreeBSD system. - Unlike the <filename>GENERIC</filename> kernel, which must support a - wide range of hardware, a custom kernel only contains support for - <emphasis>your</emphasis> PC's hardware. This has a number of - benefits, such as:</para> - - <itemizedlist> - <listitem> - <para>Faster boot time. Since the kernel will only probe the - hardware you have on your system, the time it takes your system to - boot will decrease dramatically.</para> - </listitem> - - <listitem> - <para>Less memory use. A custom kernel often uses less memory - than the <literal>GENERIC</literal> kernel, which is important - because the kernel is one process that must always be present in - memory. For this reason, a custom kernel is especially useful - on a system with a small amount of RAM.</para> - </listitem> - - <listitem> - <para>Additional hardware support. A custom kernel allows you to - add in support for devices such as sound cards, which are not - present in the <literal>GENERIC</literal> kernel.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="kernelconfig-building"> - <title>Building and Installing a Custom Kernel</title> - - <para>First, let us take a quick tour of the kernel build directory. - All directories mentioned will be relative to the main - <filename>/usr/src/sys</filename> directory, which is also - accessible through <filename>/sys</filename>. There are a number of - subdirectories here representing different parts of the kernel, but - the most important, for our purposes, are - <filename><replaceable>arch</replaceable>/conf</filename>, where you - will edit your custom kernel configuration, and - <filename>compile</filename>, which is the staging area where your - kernel will be built. <replaceable>arch</replaceable> represents - either <filename>i386</filename>, <filename>alpha</filename>, or - <filename>pc98</filename> (an alternative development branch of PC - hardware, popular in Japan). Everything inside a particular - architecture's directory deals with that architecture only; the rest - of the code is common to all platforms to which FreeBSD could - potentially be ported. Notice the logical organization of the - directory structure, with each supported device, filesystem, and - option in its own subdirectory.</para> - - <note> - <para>If there is <emphasis>not</emphasis> a - <filename>/usr/src/sys</filename> directory on your system, then - the kernel source has not been been installed. The easiest way to - do this is by running <command>/stand/sysinstall</command> as - <username>root</username>, choosing <literal>Configure</literal>, - then <literal>Distributions</literal>, then - <literal>src</literal>, then <literal>sys</literal>.</para> - </note> - - <para>Next, move to the - <filename><replaceable>arch</replaceable>/conf</filename> directory - and copy the <filename>GENERIC</filename> configuration file to the - name you want to give your kernel. For example:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput> -&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - - <para>Traditionally, this name is in all capital letters and, if you - are maintaining multiple FreeBSD machines with different hardware, - it is a good idea to name it after your machine's hostname. We will - call it <filename>MYKERNEL</filename> for the purpose of this - example.</para> - - <note> - <para>You must execute these and all of the following commands under - the root account or you will get <errortype>permission - denied</errortype> errors.</para> - </note> - - <para>Now, edit <filename>MYKERNEL</filename> with your favorite text - editor. If you are just starting out, the only editor available - will probably be <command>vi</command>, which is too complex to - explain here, but is covered well in many books in the <link - linkend="bibliography">bibliography</link>. However, FreeBSD does - offer an easier editor called <quote>ee</quote> which, if you are a - beginner, should be your editor of choice. Feel free to change the - comment lines at the top to reflect your configuration or the - changes you have made to differentiate it from - <filename>GENERIC</filename>.</para> - - <para>If you have built a kernel under SunOS or some other BSD - operating system, much of this file will be very familiar to you. - If you are coming from some other operating system such as DOS, on - the other hand, the <filename>GENERIC</filename> configuration file - might seem overwhelming to you, so follow the descriptions in the - <link linkend="kernelconfig-config">Configuration File</link> - section slowly and carefully.</para> - - <note> - <para>Be sure to always check the file - <filename>/usr/src/UPDATING</filename>, before you perform any update - steps, in the case you <link - linkend="cutting-edge">sync your source-tree</link> with the - latest sources of the FreeBSD project. - In this file all important issues with updating FreeBSD - are written down. <filename>/usr/src/UPDATING</filename> always fits - to your version of the FreeBSD source, and is therefore more accurate - for those information than the handbook.</para> - </note> - - <para>When you are finished, type the following to compile and install - your kernel if you are using FreeBSD prior FreeBSD 4.0 and don't - want to upgrade to FreeBSD 4.0 or higher with this step, - or if you are using a release-version of FreeBSD and your - <filename>/usr/src/</filename> directory only contains the - <filename>sys/</filename> sub-directory.</para> - - <note> - <para>If you are trying to upgrade your kernel from an older version - of FreeBSD, you will probably have to get a new version of - &man.config.8; from the same place you got the new kernel sources. - It is located in <filename>/usr/src/usr.sbin</filename>, so you - will need to download those sources as well. Re-build and install - it before running the next commands.</para> - </note> - - <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput> -&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput> -&prompt.root; <userinput>make depend</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - - <para>If you have just upgraded to a newer version of 4.X or - higher (ie from 3.X to 4-STABLE, or even from 4-STABLE to a - later version of 4-STABLE), make sure you have <link - linkend="cutting-edge">built the world</link>, and then run the - following commands:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildkernel KERNEL=MYKERNEL</userinput> -&prompt.root; <userinput>make installkernel KERNEL=MYKERNEL</userinput></screen> - - <para>If you have <emphasis>not</emphasis> upgraded your source - tree in any way (you have not run <application>CVSup</application>, - <application>CTM</application>, or used - <application>anoncvs</application>), then you should use the - <command>config</command>, <command>make depend</command>, - <command>make</command>, <command>make install</command> sequence.</para> - - <warning> - <para>If you have upgraded your sources since your last kernel - build, you <emphasis>must</emphasis> use the <command>make - buildkernel</command> method to build your kernel. Otherwise, - old utilities will be used to build the kernel, which will - probably fail. <emphasis>Do not use the - <command>config</command>/<command>make</command> sequence to - build your kernel if you have updated the - sources!</emphasis></para> - </warning> - - <para>The new kernel will be copied to the root directory as - <filename>/kernel</filename> and the old kernel will be moved to - <filename>/kernel.old</filename>. Now, shutdown the system and - reboot to use your kernel. In case something goes wrong, there are - some <link linkend="kernelconfig-trouble">troubleshooting</link> - instructions at the end of this document. Be sure to read the - section which explains how to recover in case your new kernel <link - linkend="kernelconfig-noboot">does not boot</link>.</para> - - <note> - <para>If you have added any new devices (such as sound cards) you - may have to add some <link linkend="kernelconfig-nodes">device - nodes</link> to your <filename>/dev</filename> directory before - you can use them.</para> - </note> - </sect1> - - <sect1 id="kernelconfig-config"> - <title>The Configuration File</title> - - <para>The general format of a configuration file is quite simple. - Each line contains a keyword and one or more arguments. For - simplicity, most lines only contain one argument. Anything - following a <literal>#</literal> is considered a comment and - ignored. The following sections describe each keyword, generally in - the order they are listed in <filename>GENERIC</filename>, although - some related keywords have been grouped together in a single section - (such as Networking) even though they are actually scattered - throughout the <filename>GENERIC</filename> file. <anchor - id="kernelconfig-options"> An exhaustive list of options and more - detailed explanations of the device lines is present in the - <filename>LINT</filename> configuration file, located in the same - directory as <filename>GENERIC</filename>. If you are in doubt as - to the purpose or necessity of a line, check first in - <filename>LINT</filename>.</para> - - <important> - <title>Quoting numbers</title> - - <para>In all versions of FreeBSD up to and including 3.X, - &man.config.8; required that any strings in the configuration file - that contained numbers used as text had to be enclosed in double - quotes.</para> - - <para>This requirement was removed in the 4.X branch, which this - book covers, so if you are on a pre-4.X system, see the - <filename>/usr/src/sys/i386/conf/LINT</filename> and - <filename>/usr/src/sys/i386/conf/GENERIC</filename> - files on your system for examples.</para> - </important> - - <para>The following is an example <filename>GENERIC</filename> kernel - configuration file with various additional comments where needed for - clarity. This example should match your copy in - <filename>/usr/src/sys/i386/conf/GENERIC</filename> fairly - closely. For details of all the possible kernel options, see - <filename>/usr/src/sys/i386/conf/LINT</filename>.</para> - - <programlisting> -# -# GENERIC -- Generic kernel configuration file for FreeBSD/i386 -# -# For more information on this file, please read the handbook section on -# Kernel Configuration Files: -# -# http://www.freebsd.org/handbook/kernelconfig-config.html -# -# The handbook is also available locally in /usr/share/doc/handbook -# if you've installed the doc distribution, otherwise always see the -# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the -# latest information. -# -# An exhaustive list of options and more detailed explanations of the -# device lines is also present in the ./LINT configuration file. If you are -# in doubt as to the purpose or necessity of a line, check first in LINT. -# -# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $</programlisting> - - <para>The following are the mandatory keywords required in - <emphasis>every</emphasis> kernel you build:</para> - - <programlisting>machine i386</programlisting> - - <para>This is the machine architecture. It must be either - <literal>i386</literal>, <literal>alpha</literal>, or - <literal>pc98</literal>.</para> - - <programlisting> -cpu I386_CPU -cpu I486_CPU -cpu I586_CPU -cpu I686_CPU</programlisting> - - <para>The above specifies the type of CPU you have in your system. - You may have multiple instances of the CPU line (i.e., you are not - sure whether you should use <literal>I586_CPU</literal> or - <literal>I686_CPU</literal>), however, for a custom kernel, it is - best to specify only the CPU you have. If you are unsure which type - your CPU use, you can use the <command>dmesg</command> command to - view your boot up messages.</para> - - <para>The Alpha architecture has different values for - <literal>cpu_type</literal>. They include:</para> - - <programlisting> -cpu EV4 -cpu EV5</programlisting> - - <para>If you are using an Alpha machine, you should be using one of - the above CPU types.</para> - - <programlisting>ident GENERIC</programlisting> - - <para>This is the identification of the kernel. You should change - this to whatever you named your kernel, in our previous example, - <literal>MYKERNEL</literal>. The value you put in the - <literal>ident</literal> string will print when you boot up the - kernel, so it is useful to give a kernel a different name if you - want to keep it separate from your usual kernel (i.e., you want to - build an experimental kernel).</para> - - <programlisting>maxusers 32</programlisting> - - <para>The <literal>maxusers</literal> option sets the size of a number - of important system tables. This number is supposed to be roughly - equal to the number of simultaneous users you expect to have on your - machine. However, under normal circumstances, you will want to set - <literal>maxusers</literal> to at least 4, especially if you are - using the X Window System or compiling software. The reason is that - the most important table set by <literal>maxusers</literal> is the - maximum number of processes, which is set to <literal>20 + 16 * - maxusers</literal>, so if you set <literal>maxusers</literal> to 1, - then you can only have 36 simultaneous processes, including the 18 - or so that the system starts up at boot time, and the 15 or so you - will probably create when you start the X Window System. Even a - simple task like reading a man page will start up nine processes to - filter, decompress, and view it. Setting - <literal>maxusers</literal> to 64 will allow you to have up to 1044 - simultaneous processes, which should be enough for nearly all uses. - If, however, you see the dreaded <errortype>proc table - full</errortype> error when trying to start another program, or are - running a server with a large number of simultaneous users (like - <hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always - increase the number and rebuild.</para> - - <note> - <para><literal>maxusers</literal> does <emphasis>not</emphasis> - limit the number of users which can log into your machine. It - simply sets various table sizes to reasonable values considering - the maximum number of users you will likely have on your system - and how many processes each of them will be running. One keyword - which <emphasis>does</emphasis> limit the number of simultaneous - <emphasis>remote logins</emphasis> is <link - linkend="kernelconfig-ptys"><literal>pseudo-device pty - 16</literal></link>.</para> - </note> - - <para>Everything that follows is more or less optional. See the notes - underneath or next to each option for more information.</para> - - <programlisting> -#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols -options MATH_EMULATE #Support for x87 emulation</programlisting> - - <para>This line allows the kernel to simulate a math co-processor if - your computer does not have one (386 or 486SX). If you have a - 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or - higher (Pentium, Pentium II, etc.), you can comment this line - out.</para> - - <note> - <para>The normal math co-processor emulation routines that come with - FreeBSD are <emphasis>not</emphasis> very accurate. If you do not - have a math co-processor, and you need the best accuracy, it is - recommended that you change this option to - <literal>GPL_MATH_EMULATION</literal> to use the GNU math support, - which is not included by default for licensing reasons.</para> - </note> - - <programlisting> -options INET #InterNETworking</programlisting> - - <para>Networking support. Leave this in, even if you do not plan to - be connected to a network. Most programs require at least loopback - networking (i.e., making network connections within your PC), so - this is essentially mandatory.</para> - - <programlisting> -options INET6 #IPv6 communications protocols</programlisting> - - <para>This enables the IPv6 communication protocols.</para> - - <programlisting> -options FFS #Berkeley Fast Filesystem -options FFS_ROOT #FFS usable as root device [keep this!]</programlisting> - - <para>This is the basic hard drive filesystem. Leave it in if you - boot from the hard disk.</para> - - <programlisting> -options MFS #Memory Filesystem -options MD_ROOT #MD is a potential root device</programlisting> - - <para>This is the memory-mapped filesystem. This is basically a RAM - disk for fast storage of temporary files, useful if you have a lot - of swap space that you want to take advantage of. A perfect place - to mount an MFS partition is on the <filename>/tmp</filename> - directory, since many programs store temporary data here. To mount - an MFS RAM disk on <filename>/tmp</filename>, add the following line - to <filename>/etc/fstab</filename>:</para> - - <informalexample> - <programlisting>/dev/ad1s2b /tmp mfs rw 0 0</programlisting> - </informalexample> - - <para>Now you simply need to either reboot, or run the command - <command>mount /tmp</command>.</para> - - <programlisting> -options NFS #Network Filesystem -options NFS_ROOT #NFS usable as root device, NFS required</programlisting> - - <para>The network filesystem. Unless you plan to mount partitions - from a UNIX file server over TCP/IP, you can comment these - out.</para> - - <programlisting> -options MSDOSFS #MSDOS Filesystem</programlisting> - - <para>The MS-DOS filesystem. Unless you plan to mount a DOS formatted - hard drive partition at boot time, you can safely comment this out. - It will be automatically loaded the first time you mount a DOS - partition, as described above. Also, the excellent - <application>mtools</application> software (in the ports collection) - allows you to access DOS floppies without having to mount and - unmount them (and does not require <literal>MSDOSFS</literal> at - all).</para> - - <programlisting> -options CD9660 #ISO 9660 Filesystem -options CD9660_ROOT #CD-ROM usable as root, CD9660 required</programlisting> - - <para>The ISO 9660 filesystem for CDROMs. Comment it out if you do - not have a CDROM drive or only mount data CDs occasionally (since it - will be dynamically loaded the first time you mount a data CD). - Audio CDs do not need this filesystem.</para> - - <programlisting> -options PROCFS #Process filesystem</programlisting> - - <para>The process filesystem. This is a <quote>pretend</quote> - filesystem mounted on <filename>/proc</filename> which allows - programs like &man.ps.1; to give you more information on what - processes are running.</para> - - <programlisting> -options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]</programlisting> - - <para>Compatibility with 4.3BSD. Leave this in; some programs will - act strangely if you comment this out.</para> - - <programlisting> -options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI</programlisting> - - <para>This causes the kernel to pause for 15 seconds before probing - each SCSI device in your system. If you only have IDE hard 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 will have to raise it back up.</para> - - <programlisting> -options UCONSOLE #Allow users to grab the console</programlisting> - - <para>Allow users to grab the console, which is useful for X users. - For example, you can create a console xterm by typing <command>xterm - -C</command>, which will display any <command>write</command>, - <command>talk</command>, and any other messages you receive, as well - as any console messages sent by the kernel.</para> - - <programlisting> -options USERCONFIG #boot -c editor</programlisting> - - <para>This option allows you to boot the configuration editor from the - boot menu.</para> - - <programlisting> -options VISUAL_USERCONFIG #visual boot -c editor</programlisting> - - <para>This option allows you to boot the visual configuration editor - from the boot menu.</para> - - <programlisting> -options KTRACE #ktrace(1) support</programlisting> - - <para>This enables kernel process tracing, which is useful in - debugging.</para> - - <programlisting> -options SYSVSHM #SYSV-style shared memory</programlisting> - - <para>This option provides for System V shared memory. The most - common use of this is the XSHM extension in X, which many - graphics-intensive programs will automatically take advantage of for - extra speed. If you use X, you'll definitely want to include - this.</para> - - <programlisting> -options SYSVSEM #SYSV-style semaphores</programlisting> - - <para>Support for System V semaphores. Less commonly used but only - adds a few hundred bytes to the kernel.</para> - - <programlisting> -options SYSVMSG #SYSV-style message queues</programlisting> - - <para>Support for System V messages. Again, only adds a few hundred - bytes to the kernel.</para> - - <note> - <para>The &man.ipcs.1; command will list any processes using each of - these System V facilities.</para> - </note> - - <programlisting> -options P1003_1B #Posix P1003_1B real-time extentions -options _KPOSIX_PRIORITY_SCHEDULING</programlisting> - - <para>Real-time extensions added in the 1993 POSIX. Certain - applications in the ports collection use these (such as Star - Office).</para> - - <programlisting> -options ICMP_BANDLIM #Rate limit bad replies</programlisting> - - <para>This option enables ICMP error response bandwidth limiting. You - typically want this option as it will help protect the machine from - denial of service packet attacks.</para> - - <programlisting> -# To make an SMP kernel, the next two are needed -#options SMP # Symmetric MultiProcessor Kernel -#options APIC_IO # Symmetric (APIC) I/O</programlisting> - - <para>The above are both required for SMP support.</para> - - <programlisting> -# Optionally these may need tweaked, (defaults shown): -#options NCPU=2 # number of CPUs -#options NBUS=4 # number of busses -#options NAPIC=1 # number of IO APICs -#options NINTR=24 # number of INTs</programlisting> - - <para>These are some additional SMP knobs.</para> - - <programlisting>device isa</programlisting> - - <para>All PCs supported by FreeBSD have one of these. If you have an - IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at - this time (support is being worked on).</para> - - <programlisting>device eisa</programlisting> - - <para>Include this if you have an EISA motherboard. This enables - auto-detection and configuration support for all devices on the EISA - bus.</para> - - <programlisting>device pci</programlisting> - - <para>Include this if you have a PCI motherboard. This enables - auto-detection of PCI cards and gatewaying from the PCI to ISA - bus.</para> - - <programlisting> -# Floppy drives -device fdc0 at isa? port IO_FD1 irq 6 drq 2 -device fd0 at fdc0 drive 0 -device fd1 at fdc0 drive 1</programlisting> - - <para>This is the floppy drive controller. <literal>fd0</literal> is - the <devicename>A:</devicename> floppy drive, and - <literal>fd1</literal> is the <devicename>B:</devicename> - drive.</para> - - <programlisting>device ata</programlisting> - - <para>This driver supports all ATA and ATAPI devices. You only need - one <literal>device ata</literal> line for the kernel to detect all - PCI ATA/ATAPI devices on modern machines.</para> - - <programlisting> -device atadisk # ATA disk drives</programlisting> - - <para>This is needed along with <literal>device ata</literal> for - ATAPI disk drives.</para> - - <programlisting><anchor id="kernelconfig-atapi"> -device atapicd # ATAPI CDROM drives</programlisting> - - <para>This is needed along with <literal>device ata</literal> for - ATAPI CDROM drives.</para> - - <programlisting> -device atapifd # ATAPI floppy drives</programlisting> - - <para>This is needed along with <literal>device ata</literal> for - ATAPI floppy drives.</para> - - <programlisting> -device atapist # ATAPI tape drives</programlisting> - - <para>This is needed along with <literal>device ata</literal> for - ATAPI tape drives.</para> - - <programlisting> -options ATA_STATIC_ID #Static device numbering</programlisting> - - <para>This makes the controller number static (like the old driver) or - else the device numbers are dynamically allocated.</para> - - <programlisting> -#options ATA_ENABLE_ATAPI_DMA #Enable DMA on ATAPI devices</programlisting> - - <para>This enables DMA on the ATAPI device. Since many ATAPI devices - claim to support DMA, but it does not actually work, this is turned - off by default.</para> - - <programlisting> -# ATA and ATAPI devices -device ata0 at isa? port IO_WD1 irq 14 -device ata1 at isa? port IO_WD2 irq 15</programlisting> - - <para>Use the above for older, non-PCI systems.</para> - - <programlisting> -# SCSI Controllers -device ahb # EISA AHA1742 family -device ahc # AHA2940 and onboard AIC7xxx devices -device amd # AMD 53C974 (Teckram DC-390(T)) -device dpt # DPT Smartcache - See LINT for options! -device isp # Qlogic family -device ncr # NCR/Symbios Logic -device sym # NCR/Symbios Logic (newer chipsets) - -device adv0 at isa? -device adw -device bt0 at isa? -device aha0 at isa? -device aic0 at isa?</programlisting> - - <para>SCSI controllers. Comment out any you do not have in your - system. If you have an IDE only system, you can remove these - altogether.</para> - - <programlisting> -# SCSI peripherals -device scbus # SCSI bus (required) -device da # Direct Access (disks) -device sa # Sequential Access (tape etc) -device cd # CD -device pass # Passthrough device (direct SCSI -access)</programlisting> - - <para>SCSI peripherals. Again, comment out any you do not have, or if - you have only IDE hardware, you can remove them completely.</para> - - <programlisting> -# RAID controllers -device ida # Compaq Smart RAID -device amr # AMI MegaRAID -device mlx # Mylex DAC960 family</programlisting> - - <para>Supported RAID controllers. If you do not have any of these, - you can comment them out or remove them.</para> - - <programlisting> -# atkbdc0 controls both the keyboard and the PS/2 mouse -device atkbdc0 at isa? port IO_KBD</programlisting> - - <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O - services for the AT keyboard and PS/2 style pointing devices. This - controller is required by the keyboard driver - (<literal>atkbd</literal>) and the PS/2 pointing device driver - (<literal>psm</literal>).</para> - - <programlisting> -device atkbd0 at atkbdc? irq 1</programlisting> - - <para>The <literal>atkbd</literal> driver, together with - <literal>atkbdc</literal> controller, provides access to the AT 84 - keyboard or the AT enhanced keyboard which is connected to the AT - keyboard controller.</para> - - <programlisting> -device psm0 at atkbdc? irq 12</programlisting> - - <para>Use this device if your mouse plugs into the PS/2 mouse - port.</para> - - <programlisting>device vga0 at isa?</programlisting> - - <para>The video card driver.</para> - - <programlisting> -# splash screen/screen saver -pseudo-device splash</programlisting> - - <para>Splash screen at start up! Screen savers require this - too.</para> - - <programlisting> -# syscons is the default console driver, resembling an SCO console -device sc0 at isa?</programlisting> - - <para><literal>sc0</literal> is the default console driver, which - resembles a SCO console. Since most full-screen programs access the - console through a terminal database library like - <filename>termcap</filename>, it should not matter whether you use - this or <literal>vt0</literal>, the <literal>VT220</literal> - compatible console driver. When you log in, set your - <envar>TERM</envar> variable to <literal>scoansi</literal> if - full-screen programs have trouble running under this console.</para> - - <programlisting> -# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver -#device vt0 at isa? -#options XSERVER # support for X server on a vt console -#options FAT_CURSOR # start with block cursor -# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines -#options PCVT_SCANSET=2 # IBM keyboards are non-std</programlisting> - - <para>This is a VT220-compatible console driver, backward compatible to - VT100/102. It works well on some laptops which have hardware - incompatibilities with <literal>sc0</literal>. Also set your - <envar>TERM</envar> variable to <literal>vt100</literal> or - <literal>vt220</literal> when you log in. This driver might also - prove useful when connecting to a large number of different machines - over the network, where <filename>termcap</filename> or - <filename>terminfo</filename> entries for the <literal>sc0</literal> - device are often not available — <literal>vt100</literal> - should be available on virtually any platform.</para> - - <programlisting> -# Floating point support - do not disable. -device npx0 at nexus? port IO_NPX irq 13</programlisting> - - <para><literal>npx0</literal> is the interface to the floating point - math unit in FreeBSD, which is either the hardware co-processor or - the software math emulator. This is <emphasis>not</emphasis> - optional.</para> - - <programlisting> -# Power management support (see LINT for more options) -device apm0 at nexus? disable flags 0x20 # Advanced Power Management</programlisting> - - <para>Advanced Power Management support. Useful for laptops.</para> - - <programlisting> -# PCCARD (PCMCIA) support -device card -device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000 -device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable</programlisting> - - <para>PCMCIA support. You need this if you are installing on a - laptop.</para> - - <programlisting> -# Serial (COM) ports -device sio0 at isa? port IO_COM1 flags 0x10 irq 4 -device sio1 at isa? port IO_COM2 irq 3 -device sio2 at isa? disable port IO_COM3 irq 5 -device sio3 at isa? disable port IO_COM4 irq 9</programlisting> - - <para>These are the four serial ports referred to as COM1 through COM4 - in the MS-DOS/Windows world.</para> - - <note> - <para>If you have an internal modem on COM4 and a serial port at - COM2, you will have to change the IRQ of the modem to 2 (for - obscure technical reasons, IRQ2 = IRQ 9) in order to access it - from FreeBSD. If you have a multiport serial card, check the - manual page for &man.sio.4; for more information on the proper - values for these lines. Some video cards (notably those based on - S3 chips) use IO addresses in the form of - <literal>0x*2e8</literal>, and since many cheap serial cards do - not fully decode the 16-bit IO address space, they clash with - these cards making the COM4 port practically unavailable.</para> - - <para>Each serial port is required to have a unique IRQ (unless you - are using one of the multiport cards where shared interrupts are - supported), so the default IRQs for COM3 and COM4 cannot be - used.</para> - </note> - - <programlisting> -# Parallel port -device ppc0 at isa? irq 7</programlisting> - - <para>This is the ISA-bus parallel port interface.</para> - - <programlisting> -device ppbus # Parallel port bus (required)</programlisting> - - <para>Provides support for the parallel port bus.</para> - - <programlisting> -device lpt # Printer</programlisting> - - <para>Support for parallel port printers.</para> - - <note> - <para>All three of the above are required to enable parallel printer - support.</para> - </note> - - <programlisting> -device plip # TCP/IP over parallel</programlisting> - - <para>This is the driver for the parallel network interface.</para> - - <programlisting> -device ppi # Parallel port interface device</programlisting> - - <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284 - I/O.</para> - - <programlisting> -#device vpo # Requires scbus and da</programlisting> - - <para>This is for an Iomega Zip drive. It requires - <literal>scbus</literal> and <literal>da</literal> support. Best - performance is achieved with ports in EPP 1.9 mode.</para> - - <programlisting> -# PCI Ethernet NICs. -device de # DEC/Intel DC21x4x (<quote>Tulip</quote>) -device fxp # Intel EtherExpress PRO/100B (82557, 82558) -device tx # SMC 9432TX (83c170 <quote>EPIC</quote>) -device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>) -device wx # Intel Gigabit Ethernet Card (<quote>Wiseman</quote>)</programlisting> - - <para>Various PCI network card drivers. Comment out or remove any of - these not present in your system.</para> - - <programlisting> -# PCI Ethernet NICs that use the common MII bus controller code. -device miibus # MII bus support</programlisting> - - <para>MII bus support is required for some PCI 10/100 ethernet NICs, - namely those which use MII-compliant transceivers or implement - transceiver control interfaces that operate like an MII. Adding - <literal>device miibus</literal> to the kernel config pulls in - support for the generic miibus API and all of the PHY drivers, - including a generic one for PHYs that are not specifically handled - by an individual driver</para> - - <programlisting> -device dc # DEC/Intel 21143 and various workalikes -device rl # RealTek 8129/8139 -device sf # Adaptec AIC-6915 (<quote>Starfire</quote>) -device sis # Silicon Integrated Systems SiS 900/SiS 7016 -device ste # Sundance ST201 (D-Link DFE-550TX) -device tl # Texas Instruments ThunderLAN -device vr # VIA Rhine, Rhine II -device wb # Winbond W89C840F -device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting> - - <para>Drivers that use the MII bus controller code.</para> - - <programlisting> -# ISA Ethernet NICs. -device ed0 at isa? port 0x280 irq 10 iomem 0xd8000 -device ex -device ep -# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really -# exists only as a PCMCIA device, so there is no ISA attachment needed -# and resources will always be dynamically assigned by the pccard code. -device wi -# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will -# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP -# mode (the factory default). If you set the switches on your ISA -# card for a manually chosen I/O address and IRQ, you must specify -# those parameters here. -device an -# The probe order of these is presently determined by i386/isa/isa_compat.c. -device ie0 at isa? port 0x300 irq 10 iomem 0xd0000 -device fe0 at isa? port 0x300 -device le0 at isa? port 0x300 irq 5 iomem 0xd0000 -device lnc0 at isa? port 0x280 irq 10 drq 0 -device cs0 at isa? port 0x300 -device sn0 at isa? port 0x300 irq 10 -# requires PCCARD (PCMCIA) support to be activated -#device xe0 at isa?</programlisting> - - <para>ISA ethernet drivers. See - <filename>/usr/src/sys/i386/conf/LINT</filename> for which cards are - supported by which driver.</para> - - <programlisting> -# Pseudo devices - the number indicates how many units to allocated. -pseudo-device loop # Network loopback</programlisting> - - <para>This is the generic loopback device for TCP/IP. If you telnet - or FTP to <hostid>localhost</hostid> (a.k.a., <hostid - role="ipaddr">127.0.0.1</hostid>) it will come back at you through - this pseudo-device. This is <emphasis>mandatory</emphasis>.</para> - - <programlisting> -pseudo-device ether # Ethernet support</programlisting> - - <para><literal>ether</literal> is only needed if you have an Ethernet - card. It includes generic Ethernet protocol code.</para> - - <programlisting> -pseudo-device sl 1 # Kernel SLIP</programlisting> - - <para><literal>sl</literal> is for SLIP support. This has been almost - entirely supplanted by PPP, which is easier to set up, better suited - for modem-to-modem connection, and more powerful. The - <replaceable>number</replaceable> after <literal>sl</literal> - specifies how many simultaneous SLIP sessions to support.</para> - - <programlisting> -pseudo-device ppp 1 # Kernel PPP</programlisting> - - <para>This is for kernel PPP support for dial-up connections. There - is also a version of PPP implemented as a userland application that - uses <literal>tun</literal> and offers more flexibility and features - such as demand dialing. The <replaceable>number</replaceable> after - <literal>ppp</literal> specifies how many simultaneous PPP - connections to support.</para> - - <programlisting> -pseudo-device tun # Packet tunnel.</programlisting> - - <para>This is used by the userland PPP software. The - <replaceable>number</replaceable> after <literal>tun</literal> - specifies the number of simultaneous PPP sessions to support. See - the <link linkend="userppp">PPP</link> section of this book for more - information.</para> - - <programlisting><anchor id="kernelconfig-ptys"> -pseudo-device pty # Pseudo-ttys (telnet etc)</programlisting> - - <para>This is a <quote>pseudo-terminal</quote> or simulated login port. - It is used by incoming <command>telnet</command> and - <command>rlogin</command> sessions, - <application>xterm</application>, and some other applications such - as <application>emacs</application>. The - <replaceable>number</replaceable> indicates the number of - <literal>pty</literal>s to create. If you need more than the - default of 16 simultaneous <application>xterm</application> windows - and/or remote logins, be sure to increase this number accordingly, - up to a maximum of 256.</para> - - <programlisting> -pseudo-device md # Memory <quote>disks</quote></programlisting> - - <para>Memory disk pseudo-devices.</para> - - <programlisting> -pseudo-device gif 4 # IPv6 and IPv4 tunneling</programlisting> - - <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 - tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 - tunneling.</para> - - <programlisting> -pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)</programlisting> - - <para>This pseudo-device captures packets that are sent to it and - diverts them to the IPv4/IPv6 translation daemon.</para> - - <programlisting> -# The `bpf' pseudo-device enables the Berkeley Packet Filter. -# Be aware of the administrative consequences of enabling this! -pseudo-device bpf # Berkeley packet filter</programlisting> - - <para>This is the Berkeley Packet Filter. This pseudo-device allows - network interfaces to be placed in promiscuous mode, capturing every - packet on a broadcast network (e.g., an ethernet). These packets - can be captured to disk and or examined with the &man.tcpdump.1; - program.</para> - - <programlisting> -# USB support -#device uhci # UHCI PCI->USB interface -#device ohci # OHCI PCI->USB interface -#device usb # USB Bus (required) -#device ugen # Generic -#device uhid # <quote>Human Interface Devices</quote> -#device ukbd # Keyboard -#device ulpt # Printer -#device umass # Disks/Mass storage - Requires scbus and da -#device ums # Mouse -# USB Ethernet, requires mii -#device aue # ADMtek USB ethernet -#device cue # CATC USB ethernet -#device kue # Kawasaki LSI USB ethernet</programlisting> - - <para>Support for various USB devices.</para> - - <para>For more information and additional devices supported by - FreeBSD, see - <filename>/usr/src/sys/i386/conf/LINT</filename>.</para> - </sect1> - - <sect1 id="kernelconfig-nodes"> - <title>Making Device Nodes</title> - - <para>Almost every device in the kernel has a corresponding - <quote>node</quote> entry in the <filename>/dev</filename> directory. - These nodes look like regular files, but are actually special - entries into the kernel which programs use to access the device. - The shell script <filename>/dev/MAKEDEV</filename>, which is - executed when you first install the operating system, creates - nearly all of the device nodes supported. However, it does not - create <emphasis>all</emphasis> of them, so when you add support for - a new device, it pays to make sure that the appropriate entries are - in this directory, and if not, add them. Here is a simple - example:</para> - - <para>Suppose you add the IDE CD-ROM support to the kernel. The line - to add is:</para> - - <programlisting> -device acd0</programlisting> - - <para>This means that you should look for some entries that start with - <filename>acd0</filename> in the <filename>/dev</filename> - directory, possibly followed by a letter, such as - <literal>c</literal>, or preceded by the letter - <literal>r</literal>, which means a <quote>raw</quote> device. It - turns out that those files are not there, so I must change to the - <filename>/dev</filename> directory and type:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen> - - <para>When this script finishes, you will find that there are now - <filename>acd0c</filename> and <filename>racd0c</filename> entries - in <filename>/dev</filename> so you know that it executed - correctly.</para> - - <para>For sound cards, the following command creates the appropriate - entries:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen> - - <note> - <para>When creating device nodes for devices such as sound cards, if - other people have access to your machine, it may be desirable to - protect the devices from outside access by adding them to the - <filename>/etc/fbtab</filename> file. See &man.fbtab.5; for more - information.</para> - </note> - - <para>Follow this simple procedure for any other - non-<filename>GENERIC</filename> devices which do not have - entries.</para> - - <note> - <para>All SCSI controllers use the same set of - <filename>/dev</filename> entries, so you do not need to create - these. Also, network cards and SLIP/PPP pseudo-devices do not - have entries in <filename>/dev</filename> at all, so you do not - have to worry about these either.</para> - </note> - </sect1> - - <sect1 id="kernelconfig-trouble"> - <title>If Something Goes Wrong</title> - - <para>There are four categories of trouble that can occur when - building a custom kernel. They are:</para> - - <variablelist> - <varlistentry> - <term><command>config</command> fails</term> - - <listitem> - <para>If the <command>config</command> command fails when you - give it your kernel description, you have probably made a - simple error somewhere. Fortunately, - <command>config</command> will print the line number that it - had trouble with, so you can quickly skip to it with - <command>vi</command>. For example, if you see:</para> - - <screen>config: line 17: syntax error</screen> - - <para>You can skip to the problem in <command>vi</command> by - typing <command>17G</command> in command mode. Make sure the - keyword is typed correctly, by comparing it to the - <filename>GENERIC</filename> kernel or another - reference.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>make</command> fails</term> - - <listitem> - <para>If the <command>make</command> command fails, it usually - signals an error in your kernel description, but not severe - enough for <command>config</command> to catch it. Again, look - over your configuration, and if you still cannot resolve the - problem, send mail to the &a.questions; with your kernel - configuration, and it should be diagnosed very quickly.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The kernel will not boot<anchor - id="kernelconfig-noboot"></term> - - <listitem> - <para>If your new kernel does not boot, or fails to recognize - your devices, do not panic! Fortunately, BSD has an excellent - mechanism for recovering from incompatible kernels. Simply - choose the kernel you want to boot from at the FreeBSD boot - loader (i.e., - <command>boot <filename>kernel.old</filename></command>). - When reconfiguring a kernel, it is always a good idea to keep - a kernel that is known to work on hand.</para> - - <para>After booting with a good kernel you can check over your - configuration file and try to build it again. One helpful - resource is the <filename>/var/log/messages</filename> file - which records, among other things, all of the kernel messages - from every successful boot. Also, the &man.dmesg.8; command - will print the kernel messages from the current boot.</para> - - <note> - <para>If you are having trouble building a kernel, make sure - to keep a <filename>GENERIC</filename>, or some other kernel - that is known to work on hand as a different name that will - not get erased on the next build. You cannot rely on - <filename>kernel.old</filename> because when installing a - new kernel, <filename>kernel.old</filename> is overwritten - with the last installed kernel which may be non-functional. - Also, as soon as possible, move the working kernel to the - proper <filename>kernel</filename> location or commands such - as &man.ps.1; will not work properly. The proper command to - <quote>unlock</quote> the kernel file that - <command>make</command> installs (in order to move another - kernel back permanently) is:</para> - - <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen> - - <para>And, if you want to <quote>lock</quote> your new kernel - into place, or any file for that matter, so that it cannot - be moved or tampered with:</para> - - <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>The kernel works, but <command>ps</command> does not work - any more!</term> - - <listitem> - <para>If you have installed a different version of the kernel - from the one that the system utilities have been built with, - for example, a 4.X kernel on a 3.X system, many system-status - commands like &man.ps.1; and &man.vmstat.8; will not work any - more. You must recompile the <filename>libkvm</filename> - library as well as these utilities. This is one reason it is - not normally a good idea to use a different version of the - kernel from the rest of the operating system.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml deleted file mode 100644 index 40919d77d3..0000000000 --- a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml +++ /dev/null @@ -1,647 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml,v 1.27 2000/11/15 12:40:05 des Exp $ ---> - -<chapter id="kerneldebug"> - <title>Kernel Debugging</title> - - <para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para> - - <sect1> - <title>Debugging a Kernel Crash Dump with <command>gdb</command></title> - - <para>Here are some instructions for getting kernel debugging working on a - crash dump. They assume that you have enough swap space for a crash - dump. If you have multiple swap partitions and the first one is too - small to hold the dump, you can configure your kernel to use an - alternate dump device (in the <literal>config kernel</literal> line), or - you can specify an alternate using the - &man.dumpon.8; command. The best way to use &man.dumpon.8; is to set - the <literal>dumpdev</literal> variable in - <filename>/etc/rc.conf</filename>. Typically you want to specify one of - the swap devices specified in <filename>/etc/fstab</filename>. Dumps to - non-swap devices, tapes for example, are currently not supported. Config - your kernel using <command>config <option>-g</option></command>. See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <para>Use the &man.dumpon.8; command to tell the kernel where to dump to - (note that this will have to be done after configuring the partition in - question as swap space via &man.swapon.8;). This is normally arranged - via <filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>. - Alternatively, you can hard-code the dump device via the - <literal>dump</literal> clause in the <literal>config</literal> line of - your kernel config file. This is deprecated and should be used only if - you want a crash dump from a kernel that crashes during booting.</para> - - <note> - <para>In the following, the term <command>gdb</command> refers to - the debugger <command>gdb</command> run in <quote>kernel debug - mode</quote>. This can be accomplished by starting the - <command>gdb</command> with the option <option>-k</option>. In - kernel debug mode, <command>gdb</command> changes its prompt to - <prompt>(kgdb)</prompt>.</para> - </note> - - <tip> - <para>If you are using FreeBSD 3 or earlier, you should make a stripped - copy of the debug kernel, rather than installing the large debug - kernel itself:</para> - - <screen>&prompt.root; <userinput>cp kernel kernel.debug</userinput> -&prompt.root; <userinput>strip -g kernel</userinput></screen> - - <para>This stage isn't necessary, but it is recommended. (In - FreeBSD 4 and later releases this step is performed automatically - at the end of the kernel <command>make</command> process.) - When the kernel has been stripped, either automatically or by - using the commands above, you may install it as usual by typing - <command>make install</command>.</para> - - <para>Note that older releases of FreeBSD (up to but not including - 3.1) used a.out kernels by default, which must have their symbol - tables permanently resident in physical memory. With the larger - symbol table in an unstripped debug kernel, this is wasteful. - Recent FreeBSD releases use ELF kernels where this is no longer a - problem.</para> - </tip> - - <para>If you are testing a new kernel, for example by typing the new - kernel's name at the boot prompt, but need to boot a different one in - order to get your system up and running again, boot it only into single - user state using the <option>-s</option> flag at the boot prompt, and - then perform the following steps:</para> - - <screen>&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> # so your file system for /var/crash is writable -&prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput> -&prompt.root; <userinput>exit</userinput> # ...to multi-user</screen> - - <para>This instructs &man.savecore.8; to use another kernel for symbol - name extraction. It would otherwise default to the currently running - kernel and most likely not do anything at all since the crash dump and - the kernel symbols differ.</para> - - <para>Now, after a crash dump, go to - <filename>/sys/compile/WHATEVER</filename> and run - <command>gdb <option>-k</option></command>. From <command>gdb</command> do: - - <screen><userinput>symbol-file kernel.debug</userinput> -<userinput>exec-file /var/crash/kernel.0</userinput> -<userinput>core-file /var/crash/vmcore.0</userinput></screen> - - and voila, you can debug the crash dump using the kernel sources just - like you can for any other program.</para> - - <para>Here is a script log of a <command>gdb</command> session - illustrating the procedure. Long lines have been folded to improve - readability, and the lines are numbered for reference. Despite this, it - is a real-world error trace taken during the development of the pcvt - console driver.</para> - -<screen> 1:Script started on Fri Dec 30 23:15:22 1994 - 2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput> - 3:&prompt.root; <userinput>gdb -k kernel /var/crash/vmcore.1</userinput> - 4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel -...done. - 5:IdlePTD 1f3000 - 6:panic: because you said to! - 7:current pcb at 1e3f70 - 8:Reading in symbols for ../../i386/i386/machdep.c...done. - 9:<prompt>(kgdb)</prompt> <userinput>where</userinput> -10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767) -11:#1 0xf0115159 in panic () -12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698) -13:#3 0xf010185e in db_fncall () -14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073) -15:#5 0xf0101711 in db_command_loop () -16:#6 0xf01040a0 in db_trap () -17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723) -18:#8 0xf019d2eb in trap_fatal (...) -19:#9 0xf019ce60 in trap_pfault (...) -20:#10 0xf019cb2f in trap (...) -21:#11 0xf01932a1 in exception:calltrap () -22:#12 0xf0191503 in cnopen (...) -23:#13 0xf0132c34 in spec_open () -24:#14 0xf012d014 in vn_open () -25:#15 0xf012a183 in open () -26:#16 0xf019d4eb in syscall (...) -27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput> -28:Reading in symbols for ../../i386/i386/trap.c...done. -29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\ -30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\ -31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\ -32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\ -33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\ -34:ss = -266427884}) (../../i386/i386/trap.c line 283) -35:283 (void) trap_pfault(&frame, FALSE); -36:<prompt>(kgdb)</prompt> <userinput>frame frame->tf_ebp frame->tf_eip</userinput> -37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done. -38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\ -39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403) -40:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -41:<prompt>(kgdb)</prompt> <userinput>list</userinput> -42:398 -43:399 tp->t_state |= TS_CARR_ON; -44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */ -45:401 -46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200) -47:403 return ((*linesw[tp->t_line].l_open)(dev, tp)); -48:404 #else -49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag)); -50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */ -51:407 } -52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput> -53:Reading in symbols for ../../i386/i386/cons.c...done. -54:$1 = (struct tty *) 0x1bae -55:<prompt>(kgdb)</prompt> <userinput>print tp->t_line</userinput> -56:$2 = 1767990816 -57:<prompt>(kgdb)</prompt> <userinput>up</userinput> -58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\ -59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126) -60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p)); -61:<prompt>(kgdb)</prompt> <userinput>up</userinput> -62:#2 0xf0132c34 in spec_open () -63:<prompt>(kgdb)</prompt> <userinput>up</userinput> -64:#3 0xf012d014 in vn_open () -65:<prompt>(kgdb)</prompt> <userinput>up</userinput> -66:#4 0xf012a183 in open () -67:<prompt>(kgdb)</prompt> <userinput>up</userinput> -68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\ -69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\ -70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \ -71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \ -72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673) -73:673 error = (*callp->sy_call)(p, args, rval); -74:<prompt>(kgdb)</prompt> <userinput>up</userinput> -75:Initial frame selected; you cannot go up. -76:<prompt>(kgdb)</prompt> <userinput>quit</userinput> -77:&prompt.root; <userinput>exit</userinput> -78:exit -79: -80:Script done on Fri Dec 30 23:18:04 1994</screen> - <para>Comments to the above script:</para> - - <variablelist> - <varlistentry> - <term>line 6:</term> - - <listitem> - <para>This is a dump taken from within DDB (see below), hence the - panic comment <quote>because you said to!</quote>, and a rather - long stack trace; the initial reason for going into DDB has been a - page fault trap though.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 20:</term> - - <listitem> - <para>This is the location of function <function>trap()</function> - in the stack trace.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 36:</term> - - <listitem> - <para>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 do not have a new core - dump handy <g>, my kernel has not panicked for a rather long - time.) From looking at the code in source line 403, there is a - high probability that either the pointer access for - <quote>tp</quote> was messed up, or the array access was out of - bounds.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 52:</term> - - <listitem> - <para>The pointer looks suspicious, but happens to be a valid - address.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>line 56:</term> - - <listitem> - <para>However, it obviously points to garbage, so we have found our - error! (For those unfamiliar with that particular piece of code: - <literal>tp->t_line</literal> refers to the line discipline of - the console device here, which must be a rather small integer - number.)</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1> - <title>Debugging a Crash Dump with DDD</title> - - <para>Examining a kernel crash dump with a graphical debugger like - <command>ddd</command> is also possible. Add the <option>-k</option> - option to the <command>ddd</command> command line you would use - normally. For example;</para> - - <screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen> - - <para>You should then be able to go about looking at the crash dump using - <command>ddd</command>'s graphical interface.</para> - </sect1> - - <sect1> - <title>Post-Mortem Analysis of a Dump</title> - - <para>What do you do if a kernel dumped core but you did not expect it, - and it is therefore not compiled using <command>config -g</command>? Not - everything is lost here. Do not panic!</para> - - <para>Of course, you still need to enable crash dumps. See above on the - options you have to specify in order to do this.</para> - - <para>Go to your kernel config directory - (<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>) - and edit your configuration file. Uncomment (or add, if it does not - exist) the following line</para> - - <programlisting> -makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting> - - <para>Rebuild the kernel. Due to the time stamp change on the Makefile, - there will be some other object files rebuild, for example - <filename>trap.o</filename>. With a bit of luck, the added - <option>-g</option> 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 &man.size.1; command. If there is a - mismatch, you probably need to give up here.</para> - - <para>Go and examine the dump as described above. The debugging symbols - might be incomplete for some places, as can be seen in the stack trace - in the example above where some functions are displayed without line - numbers and argument lists. If you need more debugging symbols, remove - the appropriate object files and repeat the <command>gdb <option>-k</option></command> - session until you know enough.</para> - - <para>All this is not guaranteed to work, but it will do it fine in most - cases.</para> - </sect1> - - <sect1> - <title>On-Line Kernel Debugging Using DDB</title> - - <para>While <command>gdb <option>-k</option></command> as an off-line debugger provides a very - high level of user interface, there are some things it cannot do. The - most important ones being breakpointing and single-stepping kernel - code.</para> - - <para>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-stepping kernel functions, examining and changing - kernel variables, etc. However, it cannot access kernel source files, - and only has access to the global and static symbols, not to the full - debug information like <command>gdb</command>.</para> - - <para>To configure your kernel to include DDB, add the option line - - <programlisting> -options DDB</programlisting> - - to your config file, and rebuild. (See <link - linkend="kernelconfig">Kernel Configuration</link> for details on - configuring the FreeBSD kernel.</para> - - <note> - <para>Note that if you have an older version of the boot blocks, your - debugger symbols might not be loaded at all. Update the boot blocks; - the recent ones load the DDB symbols automagically.)</para> - </note> - - <para>Once your DDB kernel is running, there are several ways to enter - DDB. The first, and earliest way is to type the boot flag - <option>-d</option> right at the boot prompt. The kernel will start up - in debug mode and enter DDB prior to any device probing. Hence you can - even debug the device probe/attach functions.</para> - - <para>The second scenario is a hot-key on the keyboard, usually - Ctrl-Alt-ESC. For syscons, this can be remapped; some of the - distributed maps do this, so watch out. There is an option available - for serial consoles that allows the use of a serial line BREAK on the - console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal> - in the kernel config file). It is not the default since there are a lot - of crappy serial adapters around that gratuitously generate a BREAK - condition, for example when pulling the cable.</para> - - <para>The third way is that any panic condition will branch to DDB if the - kernel is configured to use it. For this reason, it is not wise to - configure a kernel with DDB for a machine running unattended.</para> - - <para>The DDB commands roughly resemble some <command>gdb</command> - commands. The first thing you probably need to do is to set a - breakpoint:</para> - - <screen><userinput>b function-name</userinput> -<userinput>b address</userinput></screen> - - <para>Numbers are taken hexadecimal by default, but to make them distinct - from symbol names; hexadecimal numbers starting with the letters - <literal>a-f</literal> need to be preceded with <literal>0x</literal> - (this is optional for other numbers). Simple expressions are allowed, - for example: <literal>function-name + 0x103</literal>.</para> - - <para>To continue the operation of an interrupted kernel, simply - type:</para> - - <screen><userinput>c</userinput></screen> - - <para>To get a stack trace, use:</para> - - <screen><userinput>trace</userinput></screen> - - <note> - <para>Note that when entering DDB via a hot-key, the kernel is currently - servicing an interrupt, so the stack trace might be not of much use - for you.</para> - </note> - - <para>If you want to remove a breakpoint, use</para> - - - <screen><userinput>del</userinput> -<userinput>del address-expression</userinput></screen> - - <para>The first form will be accepted immediately after a breakpoint hit, - and deletes the current breakpoint. The second form can remove any - breakpoint, but you need to specify the exact address; this can be - obtained from:</para> - - <screen><userinput>show b</userinput></screen> - - <para>To single-step the kernel, try:</para> - - <screen><userinput>s</userinput></screen> - - <para>This will step into functions, but you can make DDB trace them until - the matching return statement is reached by:</para> - - <screen><userinput>n</userinput></screen> - - <note> - <para>This is different from <command>gdb</command>'s - <command>next</command> statement; it is like <command>gdb</command>'s - <command>finish</command>.</para> - </note> - - <para>To examine data from memory, use (for example): - - <screen><userinput>x/wx 0xf0133fe0,40</userinput> -<userinput>x/hd db_symtab_space</userinput> -<userinput>x/bc termbuf,10</userinput> -<userinput>x/s stringbuf</userinput></screen> - - for word/halfword/byte access, and hexadecimal/decimal/character/ string - display. The number after the comma is the object count. To display - the next 0x10 items, simply use:</para> - - <screen><userinput>x ,10</userinput></screen> - - <para>Similarly, use - - <screen><userinput>x/ia foofunc,10</userinput></screen> - - to disassemble the first 0x10 instructions of - <function>foofunc</function>, and display them along with their offset - from the beginning of <function>foofunc</function>.</para> - - <para>To modify memory, use the write command:</para> - - <screen><userinput>w/b termbuf 0xa 0xb 0</userinput> -<userinput>w/w 0xf0010030 0 0</userinput></screen> - - <para>The command modifier - (<literal>b</literal>/<literal>h</literal>/<literal>w</literal>) - specifies the size of the data to be written, the first following - expression is the address to write to and the remainder is interpreted - as data to write to successive memory locations.</para> - - <para>If you need to know the current registers, use:</para> - - <screen><userinput>show reg</userinput></screen> - - <para>Alternatively, you can display a single register value by e.g. - - <screen><userinput>p $eax</userinput></screen> - - and modify it by:</para> - - <screen><userinput>set $eax new-value</userinput></screen> - - <para>Should you need to call some kernel functions from DDB, simply - say:</para> - - <screen><userinput>call func(arg1, arg2, ...)</userinput></screen> - - <para>The return value will be printed.</para> - - <para>For a &man.ps.1; style summary of all running processes, use:</para> - - <screen><userinput>ps</userinput></screen> - - <para>Now you have now examined why your kernel failed, and you wish to - reboot. Remember that, depending on the severity of previous - malfunctioning, not all parts of the kernel might still be working as - expected. Perform one of the following actions to shut down and reboot - your system:</para> - - <screen><userinput>panic</userinput></screen> - - <para>This will cause your kernel to dump core and reboot, so you can - later analyze the core on a higher level with <command>gdb</command>. This command - usually must be followed by another <command>continue</command> - statement.</para> - - <screen><userinput>call boot(0)</userinput></screen> - - <para>Which might be a good way to cleanly shut down the running system, - <function>sync()</function> all disks, and finally reboot. As long as - the disk and file system interfaces of the kernel are not damaged, this - might be a good way for an almost clean shutdown.</para> - - <screen><userinput>call cpu_reset()</userinput></screen> - - <para>is the final way out of disaster and almost the same as hitting the - Big Red Button.</para> - - <para>If you need a short command summary, simply type:</para> - - <screen><userinput>help</userinput></screen> - - <para>However, it is highly recommended to have a printed copy of the - &man.ddb.4; manual page ready for a debugging - session. Remember that it is hard to read the on-line manual while - single-stepping the kernel.</para> - </sect1> - - <sect1> - <title>On-Line Kernel Debugging Using Remote GDB</title> - - <para>This feature has been supported since FreeBSD 2.2, and it is - actually a very neat one.</para> - - <para>GDB has already supported <emphasis>remote debugging</emphasis> for - a long time. This is done using a very simple protocol along a serial - line. Unlike the other methods described above, you will need two - machines for doing this. One is the host providing the debugging - environment, including all the sources, and a copy of the kernel binary - with all the symbols in it, and the other one is the target machine that - simply runs a similar copy of the very same kernel (but stripped of the - debugging information).</para> - - <para>You should configure the kernel in question with <command>config - -g</command>, include <option>DDB</option> into the configuration, and - compile it as usual. This gives a large blurb of a binary, due to the - debugging information. Copy this kernel to the target machine, strip - the debugging symbols off with <command>strip -x</command>, and boot it - using the <option>-d</option> boot option. Connect the serial line - of the target machine that has "flags 080" set on its sio device - to any serial line of the debugging host. - Now, on the debugging machine, go to the compile directory of the target - kernel, and start <command>gdb</command>:</para> - - <screen>&prompt.user; <userinput>gdb -k kernel</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-freebsd), -Copyright 1996 Free Software Foundation, Inc... -<prompt>(kgdb)</prompt> </screen> - - <para>Initialize the remote debugging session (assuming the first serial - port is being used) by:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen> - - <para>Now, on the target host (the one that entered DDB right before even - starting the device probe), type:</para> - - <screen>Debugger("Boot flags requested debugger") -Stopped at Debugger+0x35: movb $0, edata+0x51bc -<prompt>db></prompt> <userinput>gdb</userinput></screen> - - <para>DDB will respond with:</para> - - <screen>Next trap will enter GDB remote protocol mode</screen> - - <para>Every time you type <command>gdb</command>, the mode will be toggled - between remote GDB and local DDB. In order to force a next trap - immediately, simply type <command>s</command> (step). Your hosting GDB - will now gain control over the target kernel:</para> - - <screen>Remote debugging using /dev/cuaa0 -Debugger (msg=0xf01b0383 "Boot flags requested debugger") - at ../../i386/i386/db_interface.c:257 -<prompt>(kgdb)</prompt></screen> - - <para>You can use this session almost as any other GDB session, including - full access to the source, running it in gud-mode inside an Emacs window - (which gives you an automatic source code display in another Emacs - window) etc.</para> - </sect1> - - <sect1> - <title>Debugging Loadable Modules Using GDB</title> - - <para>When debugging a panic that occurred within a module, or - using remote GDB against a machine that uses dynamic modules, - you need to tell GDB how to obtain symbol information for those - modules.</para> - - <para>First, you need to build the module(s) with debugging - information:</para> - - <screen>&prompt.root; <userinput>cd /sys/modules/linux</userinput> -&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen> - - <para>If you are using remote GDB, you can run - <command>kldstat</command> on the target machine to find out - where the module was loaded:</para> - - <screen>&prompt.root; <userinput>kldstat</userinput> -Id Refs Address Size Name - 1 4 0xc0100000 1c1678 kernel - 2 1 0xc0a9e000 6000 linprocfs.ko - 3 1 0xc0ad7000 2000 warp_saver.ko - 4 1 0xc0adc000 11000 linux.ko -</screen> - - <para>If you are debugging a crash dump, you'll need to walk the - <literal>linker_files</literal> list, starting at - <literal>linker_files->tqh_first</literal> and following the - <literal>link.tqe_next</literal> pointers until you find the - entry with the <literal>filename</literal> you are looking for. - The <literal>address</literal> member of that entry is the load - address of the module.</para> - - <para>Next, you need to find out the offset of the text section - within the module:</para> - - <screen>&prompt.root; <userinput>objdump --section-headers /sys/modules/linux/linux.ko | grep text</userinput> - 3 .rel.text 000016e0 000038e0 000038e0 000038e0 2**2 - 10 .text 00007f34 000062d0 000062d0 000062d0 2**2</screen> - - <para>The one you want is the <literal>.text</literal> section, - section 10 in the above example. The fourth numerical field - (sixth field overall) is the offset in hex of the text section - within the file (0x62d0 in our example). Add this to the load - address reported by <command>kldstat</command> to obtain the - address of the module text in memory.</para> - - <para>Take the load address of the module (as reported by - <command>kldstat</command>) and add the offset of the text - section within the module (0x62d0 + 0xc0adc000 = c0ae22d0 in our - example). This is the address that the module code was - relocated to. Use the <command>add-symbol-file</command> - command in GDB to tell the debugger about the module:</para> - - <screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0</userinput> -add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0? -(y or n) <userinput>y</userinput> -Reading symbols from /sys/modules/linux/linux.ko...done. -<prompt>(kgdb)</prompt></screen> - - <para>You should now have access to all the symbols in the - module.</para> - </sect1> - - <sect1> - <title>Debugging a Console Driver</title> - - <para>Since you need a console driver to run DDB on, things are more - complicated if the console driver itself is failing. You might remember - the use of a serial console (either with modified boot blocks, or by - specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), - and hook up a standard terminal onto your first serial port. DDB works - on any configured console driver, of course also on a serial - console.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml deleted file mode 100644 index 28fcdb26ed..0000000000 --- a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml +++ /dev/null @@ -1,165 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml,v 1.15 2000/06/08 01:56:11 jim Exp $ ---> - -<chapter id="kernelopts"> - <title>Adding New Kernel Configuration Options</title> - - <para><emphasis>Contributed by &a.joerg;</emphasis></para> - - <note> - <para>You should be familiar with the section about <link - linkend="kernelconfig">kernel configuration</link> before reading - here.</para> - </note> - - <sect1> - <title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title> - - <para>The use of kernel options is basically described in the <link - linkend="kernelconfig-options">kernel configuration</link> section. - There's also an explanation of <quote>historic</quote> and - <quote>new-style</quote> options. The ultimate goal is to eventually - turn all the supported options in the kernel into new-style ones, so for - people who correctly did a <command>make depend</command> in their - kernel compile directory after running - &man.config.8;, the build process will automatically pick up modified - options, and only recompile those files where it is necessary. Wiping - out the old compile directory on each run of &man.config.8; as it is - still done now can then be eliminated again.</para> - - <para>Basically, a kernel option is nothing else than the definition of a - C preprocessor macro for the kernel compilation process. To make the - build truly optional, the corresponding part of the kernel source (or - kernel <filename>.h</filename> file) must be written with the option - concept in mind, i.e., the default can be overridden by the - config option. This is usually done with something like:</para> - - <programlisting> -#ifndef THIS_OPTION -#define THIS_OPTION (some_default_value) -#endif /* THIS_OPTION */</programlisting> - - <para>This way, an administrator mentioning another value for the option - in his config file will take the default out of effect, and replace it - with his new value. Clearly, the new value will be substituted into the - source code during the preprocessor run, so it must be a valid C - expression in whatever context the default value would have been - used.</para> - - <para>It is also possible to create value-less options that simply enable - or disable a particular piece of code by embracing it in</para> - - <programlisting> -#ifdef THAT_OPTION - -[your code here] - -#endif</programlisting> - - <para>Simply mentioning <literal>THAT_OPTION</literal> in the config file - (with or without any value) will then turn on the corresponding piece of - code.</para> - - <para>People familiar with the C language will immediately recognize that - everything could be counted as a <quote>config option</quote> where there - is at least a single <literal>#ifdef</literal> referencing it... - However, it's unlikely that many people would put</para> - - <programlisting> -options notyet,notdef</programlisting> - - <para>in their config file, and then wonder why the kernel compilation - falls over. <!-- smiley -->:-)</para> - - <para>Clearly, using arbitrary names for the options makes it very hard to - track their usage throughout the kernel source tree. That is the - rationale behind the <emphasis>new-style</emphasis> option scheme, where - each option goes into a separate <filename>.h</filename> file in the - kernel compile directory, which is by convention named - <filename>opt_<replaceable>foo</replaceable>.h</filename>. This way, - the usual Makefile dependencies could be applied, and - <command>make</command> can determine what needs to be recompiled once - an option has been changed.</para> - - <para>The old-style option mechanism still has one advantage for local - options or maybe experimental options that have a short anticipated - lifetime: since it is easy to add a new <literal>#ifdef</literal> to the - kernel source, this has already made it a kernel config option. In this - case, the administrator using such an option is responsible himself for - knowing about its implications (and maybe manually forcing the - recompilation of parts of his kernel). Once the transition of all - supported options has been done, &man.config.8; will warn whenever an - unsupported option appears in the config file, but it will nevertheless - include it into the kernel Makefile.</para> - </sect1> - - <sect1> - <title>Now What Do I Have to Do for it?</title> - - <para>First, edit <filename>sys/conf/options</filename> (or - <filename>sys/<replaceable><arch></replaceable>/conf/options.<replaceable><arch></replaceable></filename>, - e. g. <filename>sys/i386/conf/options.i386</filename>), and select an - <filename>opt_<replaceable>foo</replaceable>.h</filename> file where - your new option would best go into.</para> - - <para>If there is already something that comes close to the purpose of the - new option, pick this. For example, options modifying the overall - behavior of the SCSI subsystem can go into - <filename>opt_scsi.h</filename>. By default, simply mentioning an - option in the appropriate option file, say <literal>FOO</literal>, - implies its value will go into the corresponding file - <filename>opt_foo.h</filename>. This can be overridden on the - right-hand side of a rule by specifying another filename.</para> - - <para>If there is no - <filename>opt_<replaceable>foo</replaceable>.h</filename> already - available for the intended new option, invent a new name. Make it - meaningful, and comment the new section in the - <filename>options[<replaceable>.<arch></replaceable>]</filename> - file. &man.config.8; will automagically pick up the change, and create - that file next time it is run. Most options should go in a header file - by themselves..</para> - - <para>Packing too many options into a single - <filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too - many kernel files to be rebuilt when one of the options has been changed - in the config file.</para> - - <para>Finally, find out which kernel files depend on the new option. - Unless you have just invented your option, and it does not exist - anywhere yet, <screen> -&prompt.user; <userinput>find /usr/src/sys -type f | xargs fgrep NEW_OPTION</userinput> -</screen> - is your friend in finding them. Go and edit all those files, and add - <programlisting>#include "opt_foo.h"</programlisting> <emphasis>on - top</emphasis> before all the <literal>#include <xxx.h></literal> stuff. - This sequence is most important as the options could override defaults - from the regular include files, if the defaults are of the form - <programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something) - #endif</programlisting> in the regular header.</para> - - <para>Adding an option that overrides something in a system header file - (i.e., a file sitting in <filename>/usr/include/sys/</filename>) is - almost always a mistake. - <filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be - included into those files since it would break the headers more - seriously, but if it is not included, then places that include it may - get an inconsistent value for the option. Yes, there are precedents for - this right now, but that does not make them more correct.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml deleted file mode 100644 index 06a69b5ae0..0000000000 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml +++ /dev/null @@ -1,928 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml,v 1.39 2000/06/30 01:54:03 kevlo Exp $ ---> - -<chapter id="l10n"> - <title>Localization - I18N/L10N Usage and Setup</title> - - <para><emphasis>Contributed by &a.ache;</emphasis></para> - - <para><emphasis>Rewritten by Michael Chin-Yuan Wu - <email>keichii@mail.utexas.edu</email>, 6 March 2000.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>This section of the handbook discusses the internationalization - and localization of FreeBSD to different countries and different - settings. If the users wish to use languages other than the system - default English, he/she will have to setup the system accordingly. - Please note that language support for each language varies in level. - Hence, the user should contact the respective FreeBSD local group - that is responsible for each language.</para> - - <para>The author realizes that he may have been incomplete in the - description of the i18n process in FreeBSD. Due to the various - levels of i18n implementation in both the system and application - levels, we advise you to refer to individual documentation, man - pages, READMEs, and so forth.</para> - - <para>Should you have any questions or suggestions regarding this - chapter, please email the author.</para> - </sect1> - - <sect1> - <title>The Basics</title> - - <sect2> - <title>What is i18n/l10n?</title> - - <para>Developers shortened internationalization into the term i18n, - counting the number of letters between the first and the last - letters of internationalization. l10n uses the same naming - scheme, coming from "localization". Combined - together, i18n/l10n methods, protocols, and applications allow - users to use languages of their choice.</para> - - <para>I18n applications are programmed using i18n kits under - libraries. It allows for developers to write a simple file and - translate displayed menus and texts to each language. We strongly - encourage programmers to follow this convention.</para> - </sect2> - - <sect2> - <title>Why should I use i18n/l10n?</title> - - <para>I18n/l10n is used whenever you wish to either view, input, or - process data in non-English languages.</para> - </sect2> - - <sect2> - <title>What languages are supported in the i18n effort?</title> - - <para>I18n and l10n are not FreeBSD specific. Currently, one can - choose from most of the major languages of the World, including - but not limited to: Chinese, German, Japanese, French, Russian, - and others.</para> - </sect2> - </sect1> - - <sect1 id="using-localization"> - <title>Using Localization</title> - - <para>In all its splendor, i18n is not FreeBSD-specific and is a - convention. We encourage you to help FreeBSD in following this - convention.</para> - - <para>Localization settings are based on three main terms: - Language Code, Country Code, and Encoding. Locale names are - constructed from these parts as follows:</para> - - <programlisting> -<replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting> - - <sect2> - <title>Language and Country Codes</title> - - <para>In order to localize a FreeBSD system to a specific language - (or any other i18n-supporting UNIX's), the user needs to find out - the codes for the specify country and language (country - codes tell applications what variation of given - language to use). In addition, web - browsers, SMTP/POP servers, web servers, etc. make decisions based on - them. The following are examples of language/country codes:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Language/Country Code</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>en_US</entry> - <entry>English - United States</entry> - </row> - - <row> - <entry>ru_RU</entry> - <entry>Russian for Russia</entry> - </row> - - <row> - <entry>zh_TW</entry> - <entry>Traditional Chinese for Taiwan</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - </sect2> - - <sect2> - <title>Encodings</title> - - <para>Some languages use non-ASCII encodings that are 8-bit, wide - or multibyte characters, see &man.multibyte.3; for more - details. Older applications do not recognize them - and mistake them for control characters. Newer applications - usually do recognize 8-bit characters. Depending on the - implementation, users may be required to compile an application - with wide or multibyte characters support, or configure it correctly. - To be able to input and process wide or multibyte characters, the <ulink - url="../ports/">FreeBSD Ports collection</ulink> has provided - each language with different programs. Refer to the i18n - documentation in the respective FreeBSD Port.</para> - - <para>Specifically, the user needs to look at the application - documentation to decide on how to configure it correctly or to - pass correct values into the configure/Makefile/compiler.</para> - - <para>Some things to keep in mind are:</para> - - <itemizedlist> - <listitem> - <para>Language specific single C chars character sets - (see &man.multibyte.3;), i.e., - ISO_8859-1, KOI8-R, CP437.</para> - </listitem> - - <listitem> - <para>Wide or multibyte encodings, f.e. EUC, Big5.</para> - </listitem> - </itemizedlist> - - <para>You can check the active list of character sets at the - <ulink - url="ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets">IANA Registry</ulink>.</para> - </sect2> - - <sect2> - <title>I18n applications</title> - - <para>In the FreeBSD Ports and Package system, i18n applications - have been named with <literal>i18n</literal> in their names for - easy identification. However, they do not always support the - language needed.</para> - </sect2> - - <sect2 id="setting-locale"> - <title>Setting Locale</title> - - <para>Theoretically, one only needs to export the value of his/her - locale name as <envar>LANG</envar> in the login shell and is - usually done through the user's - <filename>~/.login_conf</filename> or the user login shell - configuration (<filename>~/.profile</filename>, - <filename>~/.bashrc</filename>, <filename>~/.cshrc</filename>). - This should set all of the locale subsets (such as - <envar>LC_CTYPE</envar>, <envar>LC_CTIME</envar>, etc.). Please - refer to language-specific FreeBSD documentation for more - information.</para> - - <para>You should set the following two values in your configuration - files:</para> - - <itemizedlist> - <listitem> - <para><envar>LANG</envar> for POSIX &man.setlocale.3; family - functions</para> - </listitem> - - <listitem> - <para><envar>MM_CHARSET</envar> for applications' MIME character - set</para> - </listitem> - </itemizedlist> - - <para>This includes the user shell config, the specific application - config, and the X11 config.</para> - - <sect3> - <title>Setting Locale Methods</title> - - <para>There are two methods for setting locale, and both are - described below. The first (recommended one) is by assigning - the environment variables in <link linkend="login-class">login - class</link>, and the second is by adding the environment - variable assignments to the system's shell <link - linkend="startup-file">startup file</link>.</para> - - <sect4 id="login-class"> - <title>Login Classes Method</title> - - <para>This method allows environment variables needed for locale - name and MIME character sets to be assigned once for every - possible shell instead of adding specific shell assignments to - each shell's startup file. <link linkend="usr-setup">User - Level Setup</link> can be done by an user himself and <link - linkend="adm-setup">Administrator Level Setup</link> require - superuser privileges.</para> - - <sect5 id="usr-setup"> - <title>User Level Setup</title> - - <para>Here is a minimal example of a - <filename>.login_conf</filename> file in user's home - directory which has both variables set for Latin-1 - encoding:</para> - - <programlisting> -me:My Account:\ - :charset=ISO-8859-1:\ - :lang=de_DE.ISO_8859-1:</programlisting> - - <para>See <link linkend="adm-setup">Administrator Level - Setup</link> and &man.login.conf.5; for more details.</para> - </sect5> - - <sect5 id="adm-setup"> - <title>Administrator Level Setup</title> - - <para>Check that <filename>/etc/login.conf</filename> have the - correct language user's class. Make sure these settings - appear in <filename>/etc/login.conf</filename>:</para> - - <programlisting> -<replaceable>language_name</replaceable>:<replaceable>accounts_title</replaceable>:\ - :charset=<replaceable>MIME_charset</replaceable>:\ - :lang=<replaceable>locale_name</replaceable>:\ - :tc=default:</programlisting> - - <para>So sticking with our previous example using Latin-1, it - would look like this:</para> - - <programlisting> -german:German Users Accounts:\ - :charset=ISO-8859-1:\ - :lang=de_DE.ISO_8859-1:\ - :tc=default:</programlisting> - - <para>Changing Login Classes with &man.vipw.8;</para> - - <para>Use <command>vipw</command> to add new users, and make - the entry look like this:</para> - - <programlisting> -user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting> - - <para>Changing Login Classes with &man.adduser.8;</para> - - <para>Use <command>adduser</command> to add new users, and do - the following:</para> - - <itemizedlist> - <listitem> - <para>Set <literal>defaultclass = - <replaceable>language</replaceable></literal> in - <filename>/etc/adduser.conf</filename>. Keep in mind - you must enter a <literal>default</literal> class for - all users of other languages in this case.</para> - </listitem> - - <listitem> - <para>An alternative variant is answering the specified - language each time that -<screen><prompt>Enter login class: default []: </prompt></screen> - appears from &man.adduser.8;</para> - </listitem> - - <listitem> - <para>Another alternative is to use the following for each - user of a different language that you wish to - add:</para> - - <screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen> - </listitem> - </itemizedlist> - - <para>Changing Login Classes with &man.pw.8;</para> - - <para>If you use &man.pw.8; for adding new users, call it in - this form:</para> - - <screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen> - </sect5> - </sect4> - - <sect4 id="startup-file"> - <title>Shell Startup File Method</title> - - <note> - <para>This method is not recommended because it requires a - different setup for each possible login program chosen. Use - the <link linkend="login-class">Login Class Method</link> - instead.</para> - </note> - - <para>To add the locale name and MIME character set, just set - the two environment variables shown below in the - <filename>/etc/profile</filename> and/or - <filename>/etc/csh.login</filename> shell startup files. We - will use the German language as an example below:</para> - - <para>In <filename>/etc/profile</filename>:</para> - - <programlisting> -<envar>LANG=de_DE.ISO_8859-1; export LANG</envar> -<envar>MM_CHARSET=ISO-8859-1; export MM_CHARSET</envar></programlisting> - - <para>Or in <filename>/etc/csh.login</filename>:</para> - - <programlisting> -<envar>setenv LANG de_DE.ISO_8859-1</envar> -<envar>setenv MM_CHARSET ISO-8859-1</envar></programlisting> - - <para>Alternatively, you can add the above instructions to - <filename>/usr/share/skel/dot.profile</filename> (similar to - what was used in <filename>/etc/profile</filename> above), or - <filename>/usr/share/skel/dot.login</filename> (similar to - what was used in <filename>/etc/csh.login</filename> - above).</para> - - <para>For X11:</para> - - <para>In <filename>$HOME/.xinitrc</filename>:</para> - - <programlisting> -<envar>LANG=de_DE.ISO_8859-1; export LANG</envar></programlisting> - - <para>Or:</para> - - <programlisting> -<envar>setenv LANG de_DE.ISO_8859-1</envar></programlisting> - - <para>Depending on your shell (see above).</para> - </sect4> - </sect3> - </sect2> - - <sect2 id="setting-console"> - <title>Console Setup</title> - - <para>For all single C chars character sets, set the correct - console fonts in <filename>/etc/rc.conf</filename> for the - language in question with:</para> - - <programlisting> -font8x16=<replaceable>font_name</replaceable> -font8x14=<replaceable>font_name</replaceable> -font8x8=<replaceable>font_name</replaceable></programlisting> - - <para>The <replaceable>font_name</replaceable> here is taken from - the <filename>/usr/share/syscons/fonts</filename> directory, - without the <filename>.fnt</filename> suffix.</para> - - <para>Also be sure to set the correct keymap and screenmap for your - single C chars character set through - <filename>/stand/sysinstall</filename>. - Once inside sysinstall, choose <literal>Configure</literal>, then - <literal>Console</literal>. Alternatively, you can add the - following to <filename>/etc/rc.conf</filename>:</para> - - <programlisting> -scrnmap=<replaceable>screenmap_name</replaceable> -keymap=<replaceable>keymap_name</replaceable> -keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> - - <para>The <replaceable>screenmap_name</replaceable> here is taken - from the <filename>/usr/share/syscons/scrnmaps</filename> - directory, without the <filename>.scm</filename> suffix. A - screenmap with a corresponding mapped font is usually needed as a - workaround for expanding bit 8 to bit 9 on a VGA adapter's font - character matrix in pseudographics area, i.e., to move letters out - of that area if screen font uses a bit 8 column.</para> - - <para>If you have the following settings, insert the - kernel config specified in the paragraph after the list.</para> - - <itemizedlist> - <listitem> - <para>Console uses a screen font that utilizes 8-bit column font - character.</para> - </listitem> - - <listitem> - <para>The moused daemon is enabled by setting the following in - your <filename>/etc/rc.conf</filename>:</para> - -<programlisting>moused_enable="YES"</programlisting> - </listitem> - </itemizedlist> - - <para>A workaround for expanding 8-bit to 9-bit on a VGA adapter - is usually needed for the above settings. This workaround - disables 8-bit to 9-bit expansion of the font character with the - mouse cursor the sc0 console driver. To enable the workaround, - insert the following line into the kernel config.</para> - - <programlisting> -options SC_MOUSE_CHAR=0x03</programlisting> - - <para>The <replaceable>keymap_name</replaceable> here is taken from - the <filename>/usr/share/syscons/keymaps</filename> directory, - without the <filename>.kbd</filename> suffix.</para> - - <para>The <literal>keychange</literal> is usually needed to program - function keys to match the selected terminal type because - function key sequences can not be defined in the key map.</para> - - <para>Also be sure to set the correct console terminal type in - <filename>/etc/ttys</filename> for all <literal>ttyv*</literal> - entries. Current pre-defined correspondences are:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Character Set</entry> - <entry>Terminal Type</entry> - </row> - </thead> - - <tbody> - <row> - <entry>ISO-8859-1 or ISO-8859-15</entry> - <entry><literal>cons25l1</literal></entry> - </row> - - <row> - <entry>ISO-8859-2</entry> - <entry><literal>cons25l2</literal></entry> - </row> - - <row> - <entry>KOI8-R</entry> - <entry><literal>cons25r</literal></entry> - </row> - - <row> - <entry>CP437 (hardware default)</entry> - <entry><literal>cons25</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>For wide or multibyte characters languages, use the correct - FreeBSD port in your - <filename>/usr/ports/<replaceable>language</replaceable></filename> - directory. Some ports appear as console while the system sees it - as serial vtty's, hence you must reserve enough vtty's for both - X11 and the pseudo-serial console. Here is a partial list of - applications for using other languages in console:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Language</entry> - <entry>Location</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Traditional Chinese (BIG-5)</entry> - <entry><filename>/usr/ports/chinese/big5con</filename></entry> - </row> - - <row> - <entry>Japanese</entry> - <entry><filename>/usr/ports/japanese/ja-kon2-*</filename> or - <filename>/usr/ports/japanese/Mule_Wnn</filename></entry> - </row> - - <row> - <entry>Korean</entry> - <entry><filename>/usr/ports/korean/ko-han</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>X11 Setup</title> - - <para>Although X11 is not part of the FreeBSD Project, we have - included some information here for FreeBSD users. For more - details, refer to the <ulink url="http://www.xfree86.org/">XFree86 - web site</ulink> or whichever X11 Server you use.</para> - - <para>In <filename>~/.Xresources</filename>, you can additionally - tune application specific i18n settings (e.g., fonts, menus, - etc.).</para> - - <sect3> - <title>Displaying Fonts</title> - - <para>Install the X11 True Type-Common server (XTT-common) and - install the language truetype fonts. Setting the correct - locale should allow you to view your selected language in menus - and such.</para> - </sect3> - - <sect3> - <title>Inputting Non-English Characters</title> - - <para>The X11 Input Method (XIM) Protocol is a new standard for - all X11 clients. All X11 applications should be written as XIM - clients that take input from XIM Input servers. There are - several XIM servers available for different languages.</para> - </sect3> - </sect2> - - <sect2> - <title>Printer Setup</title> - - <para>Some single C chars character sets are usually hardware - coded into printers. Wide or multibyte - character sets require special setup and we recommend using - <application>apsfilter</application>. You may also convert the - document to Postscript or PDF formats using language specific - converters.</para> - </sect2> - - <sect2> - <title>Kernel and File Systems</title> - - <para>The FreeBSD FFS filesystem is 8-bit clean, so it can be used - with any single C chars character set (see &man.multibyte.3;), - but there is no character set - name stored in the filesystem; i.e., it is raw 8-bit and does not - know anything about encoding order. Officially, FFS does not - support any form of wide or multibyte character sets yet. However, some - wide or multibyte character sets have independent patches for FFS - enabling such support. They are only temporary unportable - solutions or hacks and we have decided to not include them in the - source tree. Refer to respective languages' web sites for more - informations and the patch files.</para> - - <para>The FreeBSD MS-DOS filesystem has the configurable ability to - convert between MS-DOS, Unicode character sets and chosen - FreeBSD filesystem character sets. See &man.mount.msdos.8; for - details.</para> - </sect2> - </sect1> - - <sect1> - <title>Advanced Topics</title> - - <para>If you wish to compile i18n applications or program i18n - compliant applications, please read this section.</para> - - <sect2> - <title>Compiling i18n Programs</title> - - <para>Many FreeBSD Ports have been ported with i18n support. Some - of them are marked with -i18n in the port name. These and many - other programs have built in support for i18n and need no special - consideration.</para> - - <para>However, some applications such as MySQL need to be have the - <filename>Makefile</filename> configured with the specific - charset. This is usually done in the - <filename>Makefile</filename> or done by passing a value to - configure in the source.</para> - </sect2> - - <sect2> - <title>Programming i18n Compliant Applications</title> - - <para>To make your application more useful for speakers of other - languages, we hope that you will program i18n compliant. The GNU - gcc compiler, GUI Libraries like QT and GTK support i18n through - special handling of strings. Making a program i18n compliant is - very easy. It allows contributors to port your application to - other languages quickly. Refer to library specific i18n - documentation for more details.</para> - - <para>To the contrary of common perception, i18n compliant code is - easy to write. Usually, it only involves wrapping your strings - with library specific functions. In addition, please be sure to - allow for wide or multibyte characters support.</para> - - <sect3> - <title>A Call to Unify the i18n effort</title> - - <para>It has come to our attention that the individual i18n/l10n - efforts for each country has been repeating each others' - efforts. Many of us have been reinventing the wheel repeatedly - and inefficiently. We hope that the various major groups in - i18n could congregate into a group effort similar to the Core - Team's responsibility.</para> - - <para>Currently, we hope that, when you write or port i18n - programs, you would send it out to each country's related - FreeBSD mailing lists for testing. In the future, we hope to - create applications that work in all the languages - out-of-the-box without dirty hacks.</para> - </sect3> - - <sect3> - <title>Perl and Python</title> - - <para>Perl and Python have i18n and wide characters handling - libraries. Please use them for i18n compliance.</para> - - <para>In older FreeBSD versions, - Perl may gives warning about not having a wide characters locale - that is already installed in your system. You can set the - environmental variable <envar>LD_PRELOAD</envar> to - <filename>/usr/lib/libxpg4.so</filename> in your shell.</para> - - <para>In <literal>sh</literal>-based shells:</para> - - <programlisting> -<envar>LD_PRELOAD=/usr/lib/libxpg4.so</envar></programlisting> - - <para>In <literal>C</literal>-based shells:</para> - - <programlisting> -<envar>setenv LD_PRELOAD /usr/lib/libxpg4.so</envar></programlisting> - </sect3> - </sect2> - </sect1> - - <sect1 id="lang-setup"> - <title>Localizing FreeBSD to Specific Languages</title> - - <sect2 id="ru-localize"> - <title>Russian Language (KOI8-R encoding)</title> - - <para><emphasis>Originally contributed by - &a.ache;.</emphasis></para> - - <para>For more information about KOI8-R encoding, see the <ulink - url="http://koi8.pp.ru/">KOI8-R References - (Russian Net Character Set)</ulink>.</para> - - <sect3> - <title>Locale Setup</title> - - <para>Put the following lines into your - <filename>~/.login_conf</filename> file:</para> - - <programlisting> -me:My Account:\ - :charset=KOI8-R:\ - :lang=ru_RU.KOI8-R:</programlisting> - - <para>See earlier in this chapter for examples of setting up the - <link linkend="setting-locale">locale</link>.</para> - </sect3> - - <sect3> - <title>Console Setup</title> - - <itemizedlist> - <listitem> - <para>Add the following to your kernel configuration - file:</para> - - <programlisting> -options SC_MOUSE_CHAR=0x03</programlisting> - </listitem> - - <listitem> - <para>Use following settings in - <filename>/etc/rc.conf</filename>:</para> - - <programlisting> -keymap="ru.koi8-r" -scrnmap="koi8-r2cp866" -font8x16="cp866b-8x16" -font8x14="cp866-8x14" -font8x8="cp866-8x8"</programlisting> - - </listitem> - - <listitem> - <para>For each <literal>ttyv*</literal> entry in - <filename>/etc/ttys</filename>, use - <literal>cons25r</literal> as the terminal type.</para> - </listitem> - </itemizedlist> - - <para>See earlier in this chapter for examples of setting up the - <link linkend="setting-console">console</link>.</para> - </sect3> - - <sect3> - <title>Printer Setup</title> - - <para>Since most printers with Russian characters come with - hardware code page CP866, a special output filter is needed for - KOI8-R -> CP866 conversion. Such a filter is installed by - default as <filename>/usr/libexec/lpr/ru/koi2alt</filename>. - A Russian printer <filename>/etc/printcap</filename> entry - should look like:</para> - - <programlisting> -lp|Russian local line printer:\ - :sh:of=/usr/libexec/lpr/ru/koi2alt:\ - :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting> - - <para>See &man.printcap.5; for a detailed description.</para> - </sect3> - - <sect3> - <title>MS-DOS FS and Russian Filenames</title> - - <para>The following example &man.fstab.5; entry enables support - for Russian filenames in mounted MS-DOS filesystems:</para> - - <programlisting> -/dev/ad0s2 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0</programlisting> - - <para>See &man.mount.msdos.8; for a detailed description of the - <option>-W</option> and <option>-L</option> options.</para> - </sect3> - - <sect3> - <title>X11 Setup</title> - - <orderedlist> - <listitem> - <para>Do <link linkend="setting-locale">non-X locale - setup</link> first as described.</para> - - <note> - <para><anchor id="russian-note">The Russian KOI8-R locale - may not work with old XFree86 releases (lower than 3.3). - The XFree86 port from - <filename>/usr/ports/x11/XFree86</filename> already is the - most recent XFree86 version, so it will work if you - install XFree86 from the port. This should not be an - issue unless you are using an old version of - FreeBSD.</para> - </note> - </listitem> - - <listitem> - <para>Go to the - <filename>/usr/ports/russian/X.language</filename> directory - and issue the following command:</para> - - <screen>&prompt.root; <userinput>make install</userinput></screen> - - <para>The above port installs the latest version of the KOI8-R - fonts. XFree86 3.3 already has some KOI8-R fonts, but these - are scaled better.</para> - - <para>Check the <literal>"Files"</literal> section - in your <filename>/etc/XF86Config</filename> file. - The following - lines must be added <emphasis>before</emphasis> any other - <literal>FontPath</literal> entries:</para> - - <programlisting> -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" -FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting> - - <para>If you use a high resolution video mode, swap the 75 dpi - and 100 dpi lines.</para> - </listitem> - - <listitem> - <para>To activate a Russian keyboard, add the following to the - <literal>"Keyboard"</literal> section of your - <filename>XF86Config</filename> file.</para> - - <para>For XFree86 v3.*:</para> - - <programlisting> -XkbLayout "ru" -XkbOptions "grp:caps_toggle"</programlisting> - - <para>For XFree86 v4.*:</para> - - <programlisting> -Option "XkbLayout" "ru" -Option "XkbOptions" "grp:caps_toggle"</programlisting> - - <para>Also make sure that <literal>XkbDisable</literal> is - turned off (commented out) there.</para> - - <para>The RUS/LAT switch will be <literal>CapsLock</literal>. - The old <literal>CapsLock</literal> function is still - available via <literal>Shift+CapsLock</literal> (in LAT mode - only).</para> - - <para>If you have <quote>Windows</quote> keys on your keyboard, - and notice that some non-alphabetical keys are mapped - incorrectly in RUS mode, add the following line in your - <filename>XF86Config</filename> file.</para> - - <para>For XFree86 v3.*:</para> - - <programlisting> -XkbVariant "winkeys"</programlisting> - - <para>For XFree86 v4.*:</para> - - <programlisting> -Option "XkbVariant" "winkeys"</programlisting> - - <note> - <para>The Russian XKB keyboard may not work with old XFree86 - versions, see the <link linkend="russian-note">above - note</link> for more information. The Russian XKB - keyboard may also not work with non-localized - applications as well. Minimally localized applications - should call a <literal>XtSetLanguageProc (NULL, NULL, - NULL);</literal> function early in the program. - See <ulink - url="http://koi8.pp.ru/xwin.html"> - KOI8-R for X-Window</ulink> for more instructions on - localizing X11 applications.</para> - </note> - </listitem> - </orderedlist> - </sect3> - </sect2> - - <sect2> - <title>Traditional Chinese Localization for Taiwan</title> - - <para>The FreeBSD-Taiwan Project has an i18n/l10n tutorial for - FreeBSD at <ulink url="http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html">http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html</ulink> - using many <filename>/usr/ports/chinese/*</filename> applications. - The editor for the <literal>zh-l10n-tut</literal> is Clive Lin - <email>Clive@CirX.org</email>. You can also cvsup the following - collections at <hostid - role="fqdn">freebsd.sinica.edu.tw</hostid>:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Collection</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>outta-port tag=.</entry> - <entry>Beta-quality Ports Collection for Chinese</entry> - </row> - - <row> - <entry>zh-l10n-tut tag=.</entry> - <entry>Localizing FreeBSD Tutorial in BIG-5 Traditional - Chinese</entry> - </row> - - <row> - <entry>zh-doc tag=.</entry> - <entry>FreeBSD Documentation Translation to BIG-5 Traditional - Chinese</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Chuan-Hsing Shen <email>s874070@mail.yzu.edu.tw</email> has - created the <ulink url="http://cnpa.yzu.edu.tw/~cfc/">Chinese - FreeBSD Collection (CFC)</ulink> using FreeBSD-Taiwan's - <literal>zh-l10n-tut</literal>. The packages and the script files - are available at <ulink url="ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/">ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/</ulink>.</para> - </sect2> - - <sect2> - <title>German Language Localization (For All ISO 8859-1 - Languages)</title> - - <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a - tutorial how to use umlauts on a FreeBSD machine. The tutorial - is written in German and available at <ulink - url="http://www.de.FreeBSD.org/de/umlaute/">http://www.de.FreeBSD.org/de/umlaute/</ulink>.</para> - </sect2> - - <sect2> - <title>Japanese and Korean Language Localization</title> - - <para>For Japanese, refer to <ulink - url="http://www.jp.FreeBSD.org/">http://www.jp.FreeBSD.org/</ulink>, - and for Korean, refer to <ulink - url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink>.</para> - </sect2> - - <sect2> - <title>Non-English FreeBSD Documentation</title> - - <para>Some FreeBSD contributors have translated parts of FreeBSD to - other languages. They are available through links on the <ulink - url="../">main site</ulink> or in - <filename>/usr/share/doc</filename>.</para> - </sect2> - </sect1> -</chapter> diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml deleted file mode 100644 index ed74e35113..0000000000 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml +++ /dev/null @@ -1,786 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml,v 1.31 2000/06/14 20:30:24 jim Exp $ ---> - -<chapter id="linuxemu"> - <title>Linux Binary Compatibility</title> - - <para><emphasis>Restructured and parts updated by &a.jim;, 22 March - 2000. Originally contributed by &a.handy; and - &a.rich;</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>The following chapter will cover FreeBSD's Linux binary - compatibility features, how to install it, and how it works.</para> - - <para>At this point, you may be asking yourself why exactly, does - FreeBSD need to be able to run Linux binaries? The answer to that - question is quite simple. Many companies and developers develop - only for Linux, since it is the latest <quote>hot thing</quote> in - the computing world. That leaves the rest of us FreeBSD users - bugging these same companies and developers to put out native - FreeBSD versions of their applications. The problem is, that most - of these companies do not really realize how many people would use - their product if there were FreeBSD versions too, and most continue - to only develop for Linux. So what is a FreeBSD user to do? This - is where the Linux binary compatibility of FreeBSD comes into - play.</para> - - <para>In a nutshell, the compatibility allows FreeBSD users to run - about 90% of all Linux applications without modification. This - includes applications such as Star Office, the Linux version of - Netscape, Adobe Acrobat, RealPlayer 5 and 7, VMWare, Oracle, - WordPerfect, Doom, Quake, and more. It is also reported that in - some situations, Linux binaries perform better on FreeBSD than they - do under Linux.</para> - - <para>There are, however, some Linux-specific operating system - features that are not supported under FreeBSD. Linux binaries will - not work on FreeBSD if they overly use the Linux - <filename>/proc</filename> filesystem (which is different from - FreeBSD's <filename>/proc</filename> filesystem), or i386-specific - calls, such as enabling virtual 8086 mode.</para> - - <para>For information on installing the Linux binary compatibility - mode, see the <link linkend="linuxemu-lbc-install">next section</link>.</para> - </sect1> - - <sect1 id="linuxemu-lbc-install"> - <title>Installation</title> - - <para>With the advent of 3.0-RELEASE, it is no longer necessary to - specify <literal>options LINUX</literal> or - <literal>options COMPAT_LINUX</literal> in your kernel - configuration.</para> - - <para>The Linux binary compatibility is now done via a KLD object - (<quote>Kernel LoaDable object</quote>), so it can be installed - <quote>on-the-fly</quote> without having to reboot. You will, - however, need to have the following in - <filename>/etc/rc.conf</filename>:</para> - - <programlisting>linux_enable=<quote>YES</quote></programlisting> - - <para>This, in turn, triggers the following action in - <filename>/etc/rc.i386</filename>:</para> - - <programlisting> -# Start the Linux binary compatibility if requested. -# -case ${linux_enable} in -[Yy][Ee][Ss]) - echo -n ' linux'; linux > /dev/null 2>&1 - ;; -esac</programlisting> - - <para>If you wish to verify that the KLD is loaded, - <command>kldstat</command> will do that:</para> - - <screen>&prompt.user; <userinput>kldstat</userinput> -Id Refs Address Size Name - 1 2 0xc0100000 16bdb8 kernel - 7 1 0xc24db000 d000 linux.ko</screen> - - <para>If for some reason you do not want to or cannot load the KLD, - then you may statically link the binary compatibility in the kernel - by adding <literal>options LINUX</literal> to your kernel - configuration file. Then install your new kernel as described in - the <link linkend="kernelconfig">kernel configuration</link> section - of this handbook.</para> - - <sect2> - <title>Installing Linux Runtime Libraries</title> - - <para>This can be done one of two ways, either by using the <link - linkend="linuxemu-libs-port">linux_base</link> port, or by installing them - <link linkend="linuxemu-libs-manually">manually</link>.</para> - - <sect3 id="linuxemu-libs-port"> - <title>Installing using the linux_base port</title> - - <para>This is by far the easiest method to use when installing the - runtime libraries. It is just like installing any other port - from the <ulink url="../ports/">ports collection</ulink>. - Simply do the following:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput> -&prompt.root; <userinput>make install distclean</userinput></screen> - - <para>You should now have working Linux binary compatibility. - Some programs may complain about incorrect minor versions of the - system libraries. In general, however, this does not seem to be - a problem.</para> - </sect3> - - <sect3 id="linuxemu-libs-manually"> - <title>Installing libraries manually</title> - - <para>If you do not have the <quote>ports</quote> collection - installed, you can install the libraries by hand instead. You - will need the Linux shared libraries that the program depends on - and the runtime linker. Also, you will need to create a - <quote>shadow root</quote> directory, - <filename>/compat/linux</filename>, for Linux libraries on your - FreeBSD system. Any shared libraries opened by Linux programs - run under FreeBSD will look in this tree first. So, if a Linux - program loads, for example, <filename>/lib/libc.so</filename>, - FreeBSD will first try to open - <filename>/compat/linux/lib/libc.so</filename>, and if that does - not exist, it will then try <filename>/lib/libc.so</filename>. - Shared libraries should be installed in the shadow tree - <filename>/compat/linux/lib</filename> rather than the paths - that the Linux <command>ld.so</command> reports.</para> - - <para>Generally, you will need to look for the shared libraries - that Linux binaries depend on only the first few times that you - install a Linux program on your FreeBSD system. After a while, - you will have a sufficient set of Linux shared libraries on your - system to be able to run newly imported Linux binaries without - any extra work.</para> - </sect3> - - <sect3> - <title>How to install additional shared libraries</title> - - <para>What if you install the <filename>linux_base</filename> port - and your application still complains about missing shared - libraries? How do you know which shared libraries Linux - binaries need, and where to get them? Basically, there are 2 - possibilities (when following these instructions you will need - to be root on your FreeBSD system).</para> - - <para>If you have access to a Linux system, see what shared - libraries the application needs, and copy them to your FreeBSD - system. Look at the following example:</para> - - <informalexample> - <para>Let us assume you used FTP to get the Linux binary of - Doom, and put it on a Linux system you have access to. You - then can check which shared libraries it needs by running - <command>ldd linuxdoom</command>, like so:</para> - - <screen>&prompt.user; <userinput>ldd linuxdoom</userinput> -libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 -libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 -libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen> - - <para>You would need to get all the files from the last column, - and put them under <filename>/compat/linux</filename>, with - the names in the first column as symbolic links pointing to - them. This means you eventually have these files on your - FreeBSD system:</para> - - <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0 -/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 -/compat/linux/usr/X11/lib/libX11.so.3.1.0 -/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 -/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen> - - <blockquote> - <note> - <para>Note that if you already have a Linux shared library - with a matching major revision number to the first column - of the <command>ldd</command> output, you will not need to - copy the file named in the last column to your system, the - one you already have should work. It is advisable to copy - the shared library anyway if it is a newer version, - though. You can remove the old one, as long as you make - the symbolic link point to the new one. So, if you have - these libraries on your system:</para> - - <screen>/compat/linux/lib/libc.so.4.6.27 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen> - - <para>and you find a new binary that claims to require a - later version according to the output of - <command>ldd</command>:</para> - - <screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen> - - <para>If it is only one or two versions out of date in the - in the trailing digit then do not worry about copying - <filename>/lib/libc.so.4.6.29</filename> too, because the - program should work fine with the slightly older version. - However, if you like, you can decide to replace the - <filename>libc.so</filename> anyway, and that should leave - you with:</para> - - <screen>/compat/linux/lib/libc.so.4.6.29 -/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen> - </note> - </blockquote> - - <blockquote> - <note> - <para>The symbolic link mechanism is - <emphasis>only</emphasis> needed for Linux binaries. The - FreeBSD runtime linker takes care of looking for matching - major revision numbers itself and you do not need to worry - about it.</para> - </note> - </blockquote> - </informalexample> - </sect3> - </sect2> - - <sect2> - <title>Installing Linux ELF binaries</title> - - <para>ELF binaries sometimes require an extra step of - <quote>branding</quote>. If you attempt to run an unbranded ELF - binary, you will get an error message like the following;</para> - - <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput> -ELF binary type not known -Abort</screen> - - <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF - binary from a Linux binary, use the &man.brandelf.1; - utility.</para> - - <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen> - - <para>The GNU toolchain now places the appropriate branding - information into ELF binaries automatically, so you this step - should become increasingly more rare in the future.</para> - </sect2> - - <sect2> - <title>Configuring the host name resolver</title> - - <para>If DNS does not work or you get this message:</para> - - <screen>resolv+: "bind" is an invalid keyword resolv+: -"hosts" is an invalid keyword</screen> - - <para>You will need to configure a - <filename>/compat/linux/etc/host.conf</filename> file - containing:</para> - - <programlisting> -order hosts, bind -multi on</programlisting> - - <para>The order here specifies that <filename>/etc/hosts</filename> - is searched first and DNS is searched second. When - <filename>/compat/linux/etc/host.conf</filename> is not - installed, linux applications find FreeBSD's - <filename>/etc/host.conf</filename> and complain about the - incompatible FreeBSD syntax. You should remove - <literal>bind</literal> if you have not configured a name server - using the <filename>/etc/resolv.conf</filename> file.</para> - </sect2> - </sect1> - - <sect1 id="linuxemu-mathematica"> - <title>Installing Mathematica</title> - - <para><emphasis>Updated for Mathematica version 4.0 by Murray Stokely - <email>murray@cdrom.com</email> and merged with work by Bojan - Bistrovic <email>bojanb@physics.odu.edu</email>.</emphasis></para> - - <para>This document describes the process of installing the Linux - version of Mathematica 4.0 onto a FreeBSD system.</para> - - <para>The Linux version of Mathematica runs perfectly under FreeBSD - however the binaries shipped by Wolfram need to be branded so that - FreeBSD knows to use the Linux ABI to execute them.</para> - - <para>The Linux version of Mathematica or Mathematica for Students can - be ordered directly from Wolfram at <ulink - url="http://www.wolfram.com/">http://www.wolfram.com/</ulink>.</para> - - <sect2> - <title>Branding the Linux binaries</title> - - <para>The Linux binaries are located in the <filename>Unix</filename> - directory of the Mathematica CDROM distributed by Wolfram. You - need to copy this directory tree to your local hard drive so that - you can brand the Linux binaries with &man.brandelf.1; before - running the installer:</para> - - <screen>&prompt.root; <userinput>mount /cdrom</userinput> -&prompt.root; <userinput>cp -rp /cdrom/Unix/ /localdir/</userinput> -&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*</userinput> -&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*</userinput> -&prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*</userinput> -&prompt.root; <userinput>cd /localdir/Installers/Linux/</userinput> -&prompt.root; <userinput>./MathInstaller</userinput></screen> - </sect2> - - <sect2> - <title>Obtaining your Mathematica Password</title> - - <para>Before you can run Mathematica you will have to obtain a - password from Wolfram that corresponds to your <quote>machine - ID</quote>.</para> - - <para>Once you have installed the Linux compatibility runtime - libraries and unpacked Mathematica you can obtain the - <quote>machine ID</quote> by running the program - <command>mathinfo</command> in the Install directory. This - machine ID is based solely on the MAC address of your first - ethernet card.</para> - - <screen>&prompt.root; <userinput>cd /localdir/Files/SystemFiles/Installation/Binaries/Linux</userinput> -&prompt.root; <userinput>mathinfo</userinput> -disco.example.com 7115-70839-20412</screen> - - <para>When you register with Wolfram, either by email, phone or fax, - you will give them the <quote>machine ID</quote> and they will - respond with a corresponding password consisting of groups of - numbers. You can then enter this information when you attempt to - run Mathematica for the first time exactly as you would for any - other Mathematica platform.</para> - </sect2> - - <sect2> - <title>Running the Mathematica front end over a network</title> - - <para>Mathematica uses some special fonts to display characters not - present in any of the standard font sets (integrals, sums, greek - letters, etc.). The X protocol requires these fonts to be install - <emphasis>locally</emphasis>. This means you will have to copy - these fonts from the CDROM or from a host with Mathematica - installed to your local machine. These fonts are normally stored - in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the - CDROM, or - <filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on - your hard drive. The actual fonts are in the subdirectories - <filename>Type1</filename> and <filename>X</filename>. There are - several ways to use them, as described below.</para> - - <para>The first way is to copy them into one of the existing font - directories in <filename>/usr/X11R6/lib/X11/fonts</filename>. - This will require editing the <filename>fonts.dir</filename> file, - adding the font names to it, and changing the number of fonts on - the first line. Alternatively, you should also just be able to - run <command>mkfontdir</command> in the directory you have copied - them to.</para> - - <para>The second way to do this is to copy the directories to - <filename>/usr/X11R6/lib/X11/fonts</filename>:</para> - - <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput> -&prompt.root; <userinput>mkdir X</userinput> -&prompt.root; <userinput>mkdir MathType1</userinput> -&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput> -&prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput> -&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput> -&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput> -&prompt.root; <userinput>mkfontdir</userinput> -&prompt.root; <userinput>cd ../MathType1</userinput> -&prompt.root; <userinput>mkfontdir</userinput</screen> - - <para>Now add the new font directories to your font path:</para> - - <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput> -&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput> -&prompt.root; <userinput>xset fp rehash</userinput></screen> - - <para>If you are using the XFree86 server, you can have these font - directories loaded automatically by adding them to your - <filename>XF86Config</filename> file.</para> - - <para>If you <emphasis>do not</emphasis> already have a directory - called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you - can change the name of the <filename>MathType1</filename> - directory in the example above to - <filename>Type1</filename>.</para> - </sect2> - </sect1> - - <sect1 id="linuxemu-oracle"> - <title>Installing Oracle</title> - - <para><emphasis>Contributed by Marcel Moolenaar - <email>marcel@cup.hp.com</email></emphasis></para> - - <sect2> - <title>Preface</title> - <para>This document describes the process of installing Oracle 8.0.5 and - Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD - machine</para> - </sect2> - - <sect2> - <title>Installing the Linux environment</title> - - <para>Make sure you have both <filename>linux_base</filename> and - <filename>linux_devtools</filename> from the ports collection - installed. These ports are added to the collection after the release - of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for - that matter, update your ports collection. You may want to consider - updating your FreeBSD version too. If you run into difficulties with - <filename>linux_base-6.1</filename> or - <filename>linux_devtools-6.1</filename> you may have to use version - 5.2 of these packages.</para> - - <para>If you want to run the intelligent agent, you'll - also need to install the Red Hat TCL package: - <filename>tcl-8.0.3-20.i386.rpm</filename>. The general command - for installing packages with the official RPM port is :</para> - - <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen> - - <para>Installation of the package should not generate any errors.</para> - </sect2> - - <sect2> - <title>Creating the Oracle environment</title> - - <para>Before you can install Oracle, you need to set up a proper - environment. This document only describes what to do - <emphasis>specially</emphasis> to run Oracle for Linux on FreeBSD, not - what has been described in the Oracle installation guide.</para> - - <sect3 id="linuxemu-kernel-tuning"> - <title>Kernel Tuning</title> - - <para>As described in the Oracle installation guide, you need to set - the maximum size of shared memory. Don't use - <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal> - is merely calculated out of <literal>SHMMAXPGS</literal> and - <literal>PGSIZE</literal>. Therefore define - <literal>SHMMAXPGS</literal>. All other options can be used as - described in the guide. For example:</para> - - <programlisting>options SHMMAXPGS=10000 -options SHMMNI=100 -options SHMSEG=10 -options SEMMNS=200 -options SEMMNI=70 -options SEMMSL=61</programlisting> - - <para>Set these options to suit your intended use of Oracle.</para> - - <para>Also, make sure you have the following options in your kernel - config-file:</para> - -<programlisting>options SYSVSHM #SysV shared memory -options SYSVSEM #SysV semaphores -options SYSVMSG #SysV interprocess communication</programlisting> - </sect3> - - <sect3 id="linuxemu-oracle-account"> - - <title>Oracle account</title> - - <para>Create an Oracle account just as you would create any other - account. The Oracle account is special only that you need to give - it a Linux shell. Add <literal>/compat/linux/bin/bash</literal> to - <filename>/etc/shells</filename> and set the shell for the Oracle - account to <filename>/compat/linux/bin/bash</filename>.</para> - </sect3> - - <sect3 id="linuxemu-environment"> - <title>Environment</title> - - <para>Besides the normal Oracle variables, such as - <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must - set the following environment variables:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - - <entry>Value</entry> - </row> - </thead> - <tbody> - <row> - <entry><envar>LD_LIBRARY_PATH</envar></entry> - - <entry><literal>$ORACLE_HOME/lib</literal></entry> - </row> - - <row> - <entry><envar>CLASSPATH</envar></entry> - - <entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry> - </row> - - <row> - <entry><envar>PATH</envar></entry> - - <entry><literal>/compat/linux/bin -/compat/linux/sbin -/compat/linux/usr/bin -/compat/linux/usr/sbin -/bin -/sbin -/usr/bin -/usr/sbin -/usr/local/bin -$ORACLE_HOME/bin</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>It is advised to set all the environment variables in - <filename>.profile</filename>. A complete example is:</para> - -<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE -ORACLE_HOME=/oracle; export ORACLE_HOME -LD_LIBRARY_PATH=$ORACLE_HOME/lib -export LD_LIBRARY_PATH -ORACLE_SID=ORCL; export ORACLE_SID -ORACLE_TERM=386x; export ORACLE_TERM -CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip -export CLASSPATH -PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:$ORACLE_HOME/bin -export PATH</programlisting> - </sect3> - </sect2> - - <sect2> - <title>Installing Oracle</title> - - <para>Due to a slight inconsistency in the Linux emulator, you need to - create a directory named <filename>.oracle</filename> in - <filename>/var/tmp</filename> before you start the installer. Either - make it world writable or let it be owner by the oracle user. You - should be able to install Oracle without any problems. If you have - problems, check your Oracle distribution and/or configuration first! - After you have installed Oracle, apply the patches described in the - next two subsections.</para> - - <para>A frequent problem is that the TCP protocol adapter is not - installed right. As a consequence, you cannot start any TCP listeners. - The following actions help solve this problem:</para> - - <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput> -&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput> -&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput> -&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput> -&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput> -&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen> - - <para>Don't forget to run <filename>root.sh</filename> again!</para> - - <sect3 id="linuxemu-patch-root"> - <title>Patching root.sh</title> - - <para>When installing Oracle, some actions, which need to be performed - as <username>root</username>, are recorded in a shell script called - <filename>root.sh</filename>. <filename>root.sh</filename> is - written in the <filename>orainst</filename> directory. Apply the - following patch to root.sh, to have it use to proper location of - chown or alternatively run the script under a Linux native - shell.</para> - - <programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 ---- orainst/root.sh Mon Dec 28 15:58:53 1998 -*************** -*** 31,37 **** -# This is the default value for CHOWN -# It will redefined later in this script for those ports -# which have it conditionally defined in ss_install.h -! CHOWN=/bin/chown -# -# Define variables to be used in this script ---- 31,37 ---- -# This is the default value for CHOWN -# It will redefined later in this script for those ports -# which have it conditionally defined in ss_install.h -! CHOWN=/usr/sbin/chown -# -# Define variables to be used in this script</programlisting> - - <para>When you don't install Oracle from CD, you can patch the source - for <filename>root.sh</filename>. It is called - <filename>rthd.sh</filename> and is located in the - <filename>orainst</filename> directory in the source tree.</para> - </sect3> - - <sect3 id="linuxemu-patch-tcl"> - <title>Patching genclntsh</title> - - <para>The script genclntsh is used to create a single shared client - library. It is used when building the demos. Apply the following - patch to comment out the definition of PATH:</para> - - <programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 ---- bin/genclntsh Tue Dec 22 15:36:49 1998 -*************** -*** 32,38 **** -# -# Explicit path to ensure that we're using the correct commands -#PATH=/usr/bin:/usr/ccs/bin export PATH -! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH -# -# each product MUST provide a $PRODUCT/admin/shrept.lst ---- 32,38 ---- -# -# Explicit path to ensure that we're using the correct commands -#PATH=/usr/bin:/usr/ccs/bin export PATH -! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH -# -# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting> - </sect3> - </sect2> - - <sect2> - <title>Running Oracle</title> - - <para>When you have followed the instructions, you should be able to run - Oracle as if it was run on Linux itself.</para> - </sect2> - </sect1> - - <sect1> - <title>Advanced Topics</title> - - <para>If you are curious as to how the Linux binary compatibility - works, this is the section you want to read. Most of what follows - is based heavily on an email written to &a.chat; by Terry Lambert - <email>tlambert@primenet.com</email> (Message ID: - <literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para> - - <sect2> - <title>How Does It Work?</title> - - <para>FreeBSD has an abstraction called an <quote>execution class - loader</quote>. This is a wedge into the &man.execve.2; system - call.</para> - - <para>What happens is that FreeBSD has a list of loaders, instead of - a single loader with a fallback to the <literal>#!</literal> - loader for running any shell interpreters or shell scripts.</para> - - <para>Historically, the only loader on the UNIX platform examined - the magic number (generally the first 4 or 8 bytes of the file) to - see if it was a binary known to the system, and if so, invoked the - binary loader.</para> - - <para>If it was not the binary type for the system, the - &man.execve.2; call returned a failure, and the shell attempted to - start executing it as shell commands.</para> - - <para>The assumption was a default of <quote>whatever the current - shell is</quote>.</para> - - <para>Later, a hack was made for &man.sh.1; to examine the first two - characters, and if they were <literal>:\n</literal>, then it - invoked the &man.csh.1; shell instead (we believe SCO first made - this hack).</para> - - <para>What FreeBSD does now is go through a list of loaders, with a - generic <literal>#!</literal> loader that knows about interpreters - as the characters which follow to the next whitespace next to - last, followed by a fallback to - <filename>/bin/sh</filename>.</para> - - <para>For the Linux ABI support, FreeBSD sees the magic number as an - ELF binary (it makes no distinction between FreeBSD, Solaris, - Linux, or any other OS which has an ELF image type, at this - point).</para> - - <para>The ELF loader looks for a specialized - <emphasis>brand</emphasis>, which is a comment section in the ELF - image, and which is not present on SVR4/Solaris ELF - binaries.</para> - - <para>For Linux binaries to function, they must be - <emphasis>branded</emphasis> as type <literal>Linux</literal>; - from &man.brandelf.1;:</para> - - <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen> - - <para>When this is done, the ELF loader will see the - <literal>Linux</literal> brand on the file.</para> - - <para>When the ELF loader sees the <literal>Linux</literal> brand, - the loader replaces a pointer in the <literal>proc</literal> - structure. All system calls are indexed through this pointer (in - a traditional UNIX system, this would be the - <literal>sysent[]</literal> structure array, containing the system - calls). In addition, the process flagged for special handling of - the trap vector for the signal trampoline code, and sever other - (minor) fix-ups that are handled by the Linux kernel - module.</para> - - <para>The Linux system call vector contains, among other things, a - list of <literal>sysent[]</literal> entries whose addresses reside - in the kernel module.</para> - - <para>When a system call is called by the Linux binary, the trap - code dereferences the system call function pointer off the - <literal>proc</literal> structure, and gets the Linux, not the - FreeBSD, system call entry points.</para> - - <para>In addition, the Linux mode dynamically - <emphasis>reroots</emphasis> lookups; this is, in effect, what the - <literal>union</literal> option to FS mounts - (<emphasis>not</emphasis> the unionfs!) does. First, an attempt - is made to lookup the file in the - <filename>/compat/linux/<replaceable>original-path</replaceable></filename> - directory, <emphasis>then</emphasis> only if that fails, the - lookup is done in the - <filename>/<replaceable>original-path</replaceable></filename> - directory. This makes sure that binaries that require other - binaries can run (e.g., the Linux toolchain can all run under - Linux ABI support). It also means that the Linux binaries can - load and exec FreeBSD binaries, if there are no corresponding - Linux binaries present, and that you could place a &man.uname.1; - command in the <filename>/compat/linux</filename> directory tree - to ensure that the Linux binaries could not tell they were not - running on Linux.</para> - - <para>In effect, there is a Linux kernel in the FreeBSD kernel; the - various underlying functions that implement all of the services - provided by the kernel are identical to both the FreeBSD system - call table entries, and the Linux system call table entries: file - system operations, virtual memory operations, signal delivery, - System V IPC, etc… The only difference is that FreeBSD - binaries get the FreeBSD <emphasis>glue</emphasis> functions, and - Linux binaries get the Linux <emphasis>glue</emphasis> functions - (most older OS's only had their own <emphasis>glue</emphasis> - functions: addresses of functions in a static global - <literal>sysent[]</literal> structure array, instead of addresses - of functions dereferenced off a dynamically initialized pointer in - the <literal>proc</literal> structure of the process making the - call).</para> - - <para>Which one is the native FreeBSD ABI? It does not matter. - Basically the only difference is that (currently; this could - easily be changed in a future release, and probably will be after - this) the FreeBSD <emphasis>glue</emphasis> functions are - statically linked into the kernel, and the Linux glue functions - can be statically linked, or they can be accessed via a kernel - module.</para> - - <para>Yeah, but is this really emulation? No. It is an ABI - implementation, not an emulation. There is no emulator (or - simulator, to cut off the next question) involved.</para> - - <para>So why is it sometimes called <quote>Linux emulation</quote>? - To make it hard to sell FreeBSD! <!-- smiley -->8-). Really, it - is because the historical implementation was done at a time when - there was really no word other than that to describe what was - going on; saying that FreeBSD ran Linux binaries was not true, if - you did not compile the code in or load a module, and there needed - to be a word to describe what was being loaded—hence - <quote>the Linux emulator</quote>.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml deleted file mode 100644 index 9b723687a7..0000000000 --- a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml +++ /dev/null @@ -1,495 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/mail/chapter.sgml,v 1.19 2000/06/14 20:30:34 jim Exp $ ---> - -<chapter id="mail"> - <title>Electronic Mail</title> - - <para><emphasis>Rewritten by &a.jim;, 02 December 1999. Original work - done by &a.wlloyd;.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>Electronic Mail, better known as email, is one of the most - widely used forms of communication today. Millions of people use - email every day, and chances are if you are reading this online, - you fall into that category and probably even have more than one - email address.</para> - - <para>Electronic Mail configuration is the subject of many <link - linkend="bibliography">System Administration</link> books. If you - plan on doing anything beyond setting up one mailhost for your - network, you need industrial strength help.</para> - - <para>Some parts of email configuration are controlled in the Domain - Name System (DNS). If you are going to run your own DNS server, be - sure to read through the files in <filename>/etc/namedb</filename> - and <command>man -k named</command>.</para> - </sect1> - - <sect1 id="mail-using"> - <title>Using Electronic Mail</title> - - <para>There are five major parts involved in an email exchange. They - are: <link linkend="mail-mua">the user program</link>, <link - linkend="mail-mta">the server daemon</link>, <link - linkend="mail-dns">DNS</link>, <link linkend="mail-receive">a pop or - IMAP daemon</link>, and of course, <link linkend="mail-host">the - mailhost itself</link>.</para> - - <sect2 id="mail-mua"> - <title>The User Program</title> - - <para>This includes command line programs such as - <application>mutt</application>, <application>pine</application>, - <application>elm</application>, and - <application>mail</application>, and GUI programs such as - <application>balsa</application>, - <application>xfmail</application> to name a few, and something - more <quote>sophisticated</quote> like a WWW browser. These - programs simply pass off the email transactions to the local <link - linkend="mail-host"><quote>mailhost</quote></link>, either by - calling one of the <link linkend="mail-mta">server daemons</link> - available or delivering it over TCP.</para> - </sect2> - - <sect2 id="mail-mta"> - <title>Mailhost Server Daemon</title> - - <para>This is usually <application>sendmail</application> (by - default with FreeBSD) or one of the other mail server daemons such - as <application>qmail</application>, - <application>postfix</application>, or - <application>exim</application>. There are others, but those are - the most widely used.</para> - - <para>The server daemon usually has two functions—it looks - after receiving incoming mail and delivers outgoing mail. It does - not allow you to connect to it via POP or IMAP to read your mail. - You need an additional <link linkend="mail-receive">daemon</link> - for that.</para> - - <para>Be aware that some older versions of - <application>sendmail</application> have some serious security - problems, however as long as you run a current version of it you - should not have any problems. As always, it is a good idea to - stay up-to-date with any software you run.</para> - </sect2> - - <sect2 id="mail-dns"> - <title>Email and DNS</title> - - <para>The Domain Name System (DNS) and its daemon - <command>named</command> play a large role in the delivery of - email. In order to deliver mail from your site to another, the - server daemon will look up the site in the DNS to determine the - host that will receive mail for the destination.</para> - - <para>It works the same way when you have mail sent to you. The DNS - contains the database mapping hostname to an IP address, and a - hostname to mailhost. The IP address is specified in an A record. - The MX (Mail eXchanger) record specifies the mailhost that will - receive mail for you. If you do not have an MX record for your - hostname, the mail will be delivered directly to your host.</para> - </sect2> - - <sect2 id="mail-receive"> - <title>Receiving Mail</title> - - <para>Receiving mail for your domain is done by the mail host. It - will collect mail sent to you and store it for reading or pickup. - In order to pick the stored mail up, you will need to connect to - the mail host. This is done by either using POP or IMAP. If you - want to read mail directly on the mail host, then a POP or IMAP - server is not needed.</para> - - <para>If you want to run a POP or IMAP server, there are two things - you need to do:</para> - - <procedure> - <step> - <para>Get a POP or IMAP daemon from the <ulink - url="../ports/mail.html">Ports Collection</ulink> and install - it on your system.</para> - </step> - - <step> - <para>Modify <filename>/etc/inetd.conf</filename> to load the - POP or IMAP server.</para> - </step> - </procedure> - </sect2> - - <sect2 id="mail-host"> - <title>The Mail Host</title> - - <para>The mail host is the name given to a server that is - responsible for delivering and receiving mail for your host, and - possibly your network.</para> - </sect2> - </sect1> - - <sect1 id="mail-trouble"> - <title>Troubleshooting</title> - - <para>Here are some frequently asked questions and answers. These - have been migrated from the <ulink url="../FAQ/">FAQ</ulink>.</para> - - <qandaset> - <qandaentry> - <question> - <para>Why do I have to use the FQDN for hosts on my site?</para> - </question> - - <answer> - <para>You will probably find that the host is actually in a - different domain; for example, if you are in - <hostid role="fqdn">foo.bar.edu</hostid> and you wish to reach - a host called <hostid>mumble</hostid> in the <hostid - role="domainname">bar.edu</hostid> domain, you will have to - refer to it by the fully-qualified domain name, <hostid - role="fqdn">mumble.bar.edu</hostid>, instead of just - <hostid>mumble</hostid>.</para> - - <para>Traditionally, this was allowed by BSD BIND resolvers. - However the current version of <application>BIND</application> - that ships with FreeBSD no longer provides default abbreviations - for non-fully qualified domain names other than the domain you - are in. So an unqualified host <hostid>mumble</hostid> must - either be found as <hostid - role="fqdn">mumble.foo.bar.edu</hostid>, or it will be searched - for in the root domain.</para> - - <para>This is different from the previous behavior, where the - search continued across <hostid - role="domainname">mumble.bar.edu</hostid>, and <hostid - role="domainname">mumble.edu</hostid>. Have a look at RFC 1535 - for why this was considered bad practice, or even a security - hole.</para> - - <para>As a good workaround, you can place the line: - - <programlisting> -search foo.bar.edu bar.edu</programlisting> - - instead of the previous: - - <programlisting> -domain foo.bar.edu</programlisting> - - into your <filename>/etc/resolv.conf</filename>. However, make - sure that the search order does not go beyond the - <quote>boundary between local and public administration</quote>, - as RFC 1535 calls it.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Sendmail says <errorname>mail loops back to - myself</errorname></para> - </question> - - <answer> - <para>This is answered in the sendmail FAQ as follows:</para> - - <programlisting> -* I am getting <quote>Local configuration error</quote> messages, such as: - -553 relay.domain.net config error: mail loops back to myself -554 <user@domain.net>... Local configuration error - -How can I solve this problem? - -You have asked mail to the domain (e.g., domain.net) to be -forwarded to a specific host (in this case, relay.domain.net) -by using an MX record, but the relay machine does not recognize -itself as domain.net. Add domain.net to /etc/sendmail.cw -(if you are using FEATURE(use_cw_file)) or add <quote>Cw domain.net</quote> -to /etc/sendmail.cf.</programlisting> - - <para>The sendmail FAQ is in - <filename>/usr/src/usr.sbin/sendmail</filename> and is - recommended reading if you want to do any - <quote>tweaking</quote> of your mail setup.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How can I do email with a dial-up PPP host?</para> - </question> - - <answer> - <para>You want to connect a FreeBSD box on a lan, to the - Internet. The FreeBSD box will be a mail gateway for the lan. - The PPP connection is non-dedicated.</para> - - <para>There are at least two ways to do this.</para> - - <para>The other is to use UUCP.</para> - - <para>The key is to get a Internet site to provide secondary MX - service for your domain. For example:</para> - - <programlisting> -bigco.com. MX 10 bigco.com. - MX 20 smalliap.com.</programlisting> - - <para>Only one host should be specified as the final recipient - (add <literal>Cw bigco.com</literal> in - <filename>/etc/sendmail.cf</filename> on bigco.com).</para> - - <para>When the senders' <command>sendmail</command> is trying to - deliver the mail it will try to connect to you over the modem - link. It will most likely time out because you are not online. - <command>sendmail</command> will automatically deliver it to the - secondary MX site, i.e., your Internet provider. The secondary MX - site will try every - (<literal>sendmail_flags = -bd -q15m</literal> in - <filename>/etc/rc.conf</filename>) 15 minutes to connect to - your host to deliver the mail to the primary MX site.</para> - - <para>You might want to use something like this as a login - script.</para> - - <programlisting> -#!/bin/sh -# Put me in /usr/local/bin/pppbigco -( sleep 60 ; /usr/sbin/sendmail -q ) & -/usr/sbin/ppp -direct pppbigco</programlisting> - - <para>If you are going to create a separate login script for a - user you could use <command>sendmail -qRbigco.com</command> - instead in the script above. This will force all mail in your - queue for bigco.com to be processed immediately.</para> - - <para>A further refinement of the situation is as follows.</para> - - <para>Message stolen from the &a.isp;.</para> - - <programlisting> -> we provide the secondary MX for a customer. The customer connects to -> our services several times a day automatically to get the mails to -> his primary MX (We do not call his site when a mail for his domains -> arrived). Our sendmail sends the mailqueue every 30 minutes. At the -> moment he has to stay 30 minutes online to be sure that all mail is -> gone to the primary MX. -> -> Is there a command that would initiate sendmail to send all the mails -> now? The user has not root-privileges on our machine of course. - -In the <quote>privacy flags</quote> section of sendmail.cf, there is a -definition Opgoaway,restrictqrun - -Remove restrictqrun to allow non-root users to start the queue processing. -You might also like to rearrange the MXs. We are the 1st MX for our -customers like this, and we have defined: - -# If we are the best MX for a host, try directly instead of generating -# local config error. -OwTrue - -That way a remote site will deliver straight to you, without trying -the customer connection. You then send to your customer. Only works for -<quote>hosts</quote>, so you need to get your customer to name their mail -machine <quote>customer.com</quote> as well as -<quote>hostname.customer.com</quote> in the DNS. Just put an A record in -the DNS for <quote>customer.com</quote>.</programlisting> - </answer> - </qandaentry> - </qandaset> - </sect1> - - <sect1 id="mail-advanced"> - <title>Advanced Topics</title> - - <para>The following section covers more involved topics such as mail - configuration and setting up mail for your entire domain.</para> - - <sect2 id="mail-config"> - <title>Basic Configuration</title> - - <para>Out of the box, you should be able to send email to external - hosts as long as you have set up - <filename>/etc/resolv.conf</filename> or are running your own - name server. If you would like to have mail for your host - delivered to that specific host, there are two methods:</para> - - <itemizedlist> - <listitem> - <para>Run your own name server and have your own domain. For - example, <hostid - role="domainname">FreeBSD.org</hostid></para> - </listitem> - - <listitem> - <para>Get mail delivered directly to your host. This is done by - delivering mail directly to the current DNS name for your - machine. For example, <hostid - role="fqdn">example.FreeBSD.org</hostid>.</para> - </listitem> - </itemizedlist> - - <para>Regardless of which of the above you choose, in order to have - mail delivered directly to your host, you must have a permanent - (static) IP address (no dynamic PPP dial-up). If you are behind a - firewall, it must pass SMTP traffic on to you. If you want to - receive mail at your host itself, you need to be sure of one of two - things:</para> - - <itemizedlist> - <listitem> - <para>Make sure that the MX record in your DNS points to your - host's IP address.</para> - </listitem> - - <listitem> - <para>Make sure there is no MX entry in your DNS for your - host.</para> - </listitem> - </itemizedlist> - - <para>Either of the above will allow you to receive mail directly at - your host.</para> - - <para>Try this:</para> - - <screen>&prompt.root; <userinput>hostname</userinput> -example.FreeBSD.org -&prompt.root; <userinput>host example.FreeBSD.org</userinput> -example.FreeBSD.org has address 204.216.27.XX</screen> - - <para>If that is what you see, mail directly to - <email>yourlogin@example.FreeBSD.org</email> should work without - problems.</para> - - <para>If instead you see something like this:</para> - - <screen>&prompt.root; <userinput>host example.FreeBSD.org</userinput> -example.FreeBSD.org has address 204.216.27.XX -example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen> - - <para>All mail sent to your host (<hostid - role="fqdn">example.FreeBSD.org</hostid>) will end up being - collected on <hostid>hub</hostid> under the same username instead - of being sent directly to your host.</para> - - <para>The above information is handled by your DNS server. The DNS - record that carries mail routing information is the - <emphasis>M</emphasis>ail e<emphasis>X</emphasis>change entry. If - no MX record exists, mail will be delivered directly to the host by - way of its IP address.</para> - - <para>The MX entry for <hostid - role="fqdn">freefall.FreeBSD.org</hostid> at one time looked like - this:</para> - - <programlisting> -freefall MX 30 mail.crl.net -freefall MX 40 agora.rdrop.com -freefall MX 10 freefall.FreeBSD.org -freefall MX 20 who.cdrom.com</programlisting> - - <para>As you can see, <hostid>freefall</hostid> had many MX entries. - The lowest MX number is the host that ends up receiving the mail in - the end while the others will queue mail temporarily if - <hostid>freefall</hostid> is busy or down.</para> - - <para>Alternate MX sites should have separate Internet connections - from your own in order to be the most useful. Your ISP or other - friendly site should have no problem providing this service for - you.</para> - </sect2> - - <sect2 id="mail-domain"> - <title>Mail for your Domain</title> - - <para>In order to set up a <quote>mailhost</quote> (a.k.a., mail - server) you need to have any mail sent to various workstations - directed to it. Basically, you want to <quote>hijack</quote> any - mail for your domain (in this case <hostid - role="fqdn">*.FreeBSD.org</hostid>) and divert it to your mail - server so your users can check their mail via POP or directly on - the server.</para> - - <para>To make life easiest, a user account with the same - <emphasis>username</emphasis> should exist on both machines. Use - <command>adduser</command> to do this.</para> - - <para>The mailhost you will be using must be the designated mail - exchange for each workstation on the network. This is done in - your DNS configuration like so:</para> - - <programlisting> -example.FreeBSD.org A 204.216.27.XX ; Workstation - MX 10 hub.FreeBSD.org ; Mailhost</programlisting> - - <para>This will redirect mail for the workstation to the mailhost no - matter where the A record points. The mail is sent to the MX - host.</para> - - <para>You cannot do this yourself unless you are running a DNS - server. If you are not, or cannot, run your own DNS server, talk - to your ISP or whoever does your DNS for you.</para> - - <para>If you're doing virtual email hosting, the following - information will come in handy. For the sake of an example, we - will assume you have a customer with their own domain, in this - case <hostid role="domainname">customer1.org</hostid> and you want - all the mail for <hostid role="domainname">customer1.org</hostid> - sent to your mailhost, which is named <hostid - role="fqdn">mail.myhost.com</hostid>. The entry in your DNS - should look like this:</para> - - <programlisting> -customer1.org MX 10 mail.myhost.com</programlisting> - - <para>You do <emphasis>not</emphasis> need an A record if you only - want to handle email for the domain.</para> - - <note> - <para>Be aware that this means pinging <hostid - role="domainname">customer1.org</hostid> will not work unless - an A record exists for it.</para> - </note> - - <para>The last thing that you must do is tell - <application>sendmail</application> on your mailhost what domains - and/or hostnames it should be accepting mail for. There are a few - different ways this can be done. Either of the following will - work:</para> - - <itemizedlist> - <listitem> - <para>Add the hosts to your - <filename>/etc/sendmail.cw</filename> file if you are using the - <literal>FEATURE(use_cw_file)</literal>. If you are using - sendmail 8.10 or higher, the file is - <filename>/etc/mail/local-host-names</filename>.</para> - </listitem> - - <listitem> - <para>Add a <literal>Cwyour.host.com</literal> line to your - <filename>/etc/sendmail.cf</filename> or - <filename>/etc/mail/sendmail.cf</filename> if you are using - sendmail 8.10 or higher.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/mailing-lists.ent b/en_US.ISO8859-1/books/handbook/mailing-lists.ent deleted file mode 100644 index 934341d91e..0000000000 --- a/en_US.ISO8859-1/books/handbook/mailing-lists.ent +++ /dev/null @@ -1,107 +0,0 @@ -<!-- - Names of FreeBSD mailing lists and related software. - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/mailing-lists.ent,v 1.4 1999/09/06 06:52:47 peter Exp $ ---> - -<!ENTITY a.advocacy "FreeBSD advocacy mailing list - <email>freebsd-advocacy@FreeBSD.org</email>"> - -<!ENTITY a.announce "FreeBSD announcements mailing list - <email>freebsd-announce@FreeBSD.org</email>"> - -<!ENTITY a.bugs "FreeBSD problem reports mailing list - <email>freebsd-bugs@FreeBSD.org</email>"> - -<!ENTITY a.chat "FreeBSD chat mailing list - <email>freebsd-chat@FreeBSD.org</email>"> - -<!ENTITY a.core "FreeBSD core team - <email>freebsd-core@FreeBSD.org</email>"> - -<!ENTITY a.current "FreeBSD-current mailing list - <email>freebsd-current@FreeBSD.org</email>"> - -<!ENTITY a.cvsall "FreeBSD CVS commit message mailing list - <email>cvs-all@FreeBSD.org</email>"> - -<!ENTITY a.database "FreeBSD based Databases mailing list - <email>freebsd-database@FreeBSD.org</email>"> - -<!ENTITY a.doc "FreeBSD documentation project mailing list - <email>freebsd-doc@FreeBSD.org</email>"> - -<!ENTITY a.emulation "FreeBSD-emulation mailing list - <email>freebsd-emulation@FreeBSD.org</email>"> - -<!ENTITY a.fs "FreeBSD filesystem project mailing list - <email>freebsd-fs@FreeBSD.org</email>"> - -<!ENTITY a.hackers "FreeBSD technical discussions mailing list - <email>freebsd-hackers@FreeBSD.org</email>"> - -<!ENTITY a.hardware "FreeBSD hardware and equipment mailing list - <email>freebsd-hardware@FreeBSD.org</email>"> - -<!ENTITY a.isdn "FreeBSD ISDN mailing list - <email>freebsd-isdn@FreeBSD.org</email>"> - -<!ENTITY a.isp "FreeBSD Internet service provider's mailing list - <email>freebsd-isp@FreeBSD.org</email>"> - -<!ENTITY a.java "FreeBSD Java Language mailing list - <email>freebsd-java@FreeBSD.org</email>"> - -<!ENTITY a.jobs "FreeBSD related employment mailing list - <email>freebsd-jobs@FreeBSD.org</email>"> - -<!ENTITY a.mobile "FreeBSD laptop computer mailing list - <email>freebsd-mobile@FreeBSD.org</email>"> - -<!ENTITY a.mozilla "FreeBSD port of the Mozilla browser mailing list - <email>freebsd-mozilla@FreeBSD.org</email>"> - -<!ENTITY a.multimedia "FreeBSD multimedia mailing list - <email>freebsd-multimedia@FreeBSD.org</email>"> - -<!ENTITY a.net "FreeBSD networking mailing list - <email>freebsd-net@FreeBSD.org</email>"> - -<!ENTITY a.newbies "FreeBSD new users mailing list - <email>freebsd-newbies@FreeBSD.org</email>"> - -<!ENTITY a.newbus "New Bus Architecture mailing list - <email>new-bus-arch@bostonradio.org</email>"> - -<!ENTITY a.ports "FreeBSD ports mailing list - <email>freebsd-ports@FreeBSD.org</email>"> - -<!ENTITY a.questions "FreeBSD general questions mailing list - <email>freebsd-questions@FreeBSD.org</email>"> - -<!ENTITY a.scsi "FreeBSD SCSI subsystem mailing list - <email>freebsd-scsi@FreeBSD.org</email>"> - -<!ENTITY a.security "FreeBSD security mailing list - <email>freebsd-security@FreeBSD.org</email>"> - -<!ENTITY a.security-notifications "FreeBSD security notifications mailing list - <email>freebsd-security-notifications@FreeBSD.org</email>"> - -<!ENTITY a.small "FreeBSD-small mailing list - <email>freebsd-small@FreeBSD.org</email>"> - -<!ENTITY a.smp "FreeBSD symmetric multiprocessing mailing list - <email>freebsd-smp@FreeBSD.org</email>"> - -<!ENTITY a.stable "FreeBSD-stable mailing list - <email>freebsd-stable@FreeBSD.org</email>"> - -<!ENTITY a.tokenring "FreeBSD tokenring mailing list - <email>freebsd-tokenring@FreeBSD.org</email>"> - -<!ENTITY a.www "FreeBSD Webmaster mailing list - <email>freebsd-www@FreeBSD.org</email>"> - -<!ENTITY a.majordomo "<email>majordomo@FreeBSD.org</email>"> - diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml deleted file mode 100644 index d5d475cd62..0000000000 --- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml +++ /dev/null @@ -1,3728 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml,v 1.98 2000/11/14 15:28:51 jdp Exp $ ---> - -<appendix id="mirrors"> - <title>Obtaining FreeBSD</title> - - <sect1> - <title>CDROM Publishers</title> - - <para>FreeBSD is available on CDROM from BSDi: - - <address> - <otheraddr>BSDi</otheraddr> - <street>4041 Pike Lane, Suite F</street> - <city>Concord</city>, <state>CA</state> <postcode>94520</postcode> - <country>USA</country> - Phone: <phone>+1 925 691-2800</phone> - Fax: <fax>+1 925 674-0821</fax> - Email: <email>info@osd.bsdi.com</email> - WWW: <otheraddr><ulink url="http://www.osd.bsdi.com/">http://www.osd.bsdi.com/</ulink></otheraddr> - </address></para> - </sect1> - - <sect1 id="mirrors-ftp"> - <title>FTP Sites</title> - - <para>The official sources for FreeBSD are available via anonymous FTP - from: - - <blockquote> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.FreeBSD.org/pub/FreeBSD/</ulink>.</para> - </blockquote></para> - - <para>The <ulink - url="http://www.itworks.com.au/~gavin/FBSDsites.php3">FreeBSD mirror - sites database</ulink> is more accurate than the mirror listing in the - handbook, as it gets its information form the DNS rather than relying on - static lists of hosts.</para> - - <para>Additionally, FreeBSD is available via anonymous FTP from the - following mirror sites. If you choose to obtain FreeBSD via anonymous - FTP, please try to use a site near you.</para> - - <para><link linkend="mirrors-ar">Argentina</link>, - <link linkend="mirrors-au">Australia</link>, - <link linkend="mirrors-br">Brazil</link>, - <link linkend="mirrors-ca">Canada</link>, - <link linkend="mirrors-cn">China</link>, - <link linkend="mirrors-cz">Czech Republic</link>, - <link linkend="mirrors-dk">Denmark</link>, - <link linkend="mirrors-ee">Estonia</link>, - <link linkend="mirrors-fi">Finland</link>, - <link linkend="mirrors-fr">France</link>, - <link linkend="mirrors-de">Germany</link>, - <link linkend="mirrors-hk">Hong Kong</link>, - <link linkend="mirrors-hu">Hungary</link>, - <link linkend="mirrors-ie">Ireland</link>, - <link linkend="mirrors-il">Israel</link>, - <link linkend="mirrors-jp">Japan</link>, - <link linkend="mirrors-kr">Korea</link>, - <link linkend="mirrors-lt">Lithuania</link>, - <link linkend="mirrors-nl">Netherlands</link>, - <link linkend="mirrors-nz">New Zealand</link>, - <link linkend="mirrors-pl">Poland</link>, - <link linkend="mirrors-pt">Portugal</link>, - <link linkend="mirrors-ru">Russia</link>, - <link linkend="mirrors-sa">Saudi Arabia</link>, - <link linkend="mirrors-za">South Africa</link>, - <link linkend="mirrors-es">Spain</link>, - <link linkend="mirrors-sk">Slovak Republic</link>, - <link linkend="mirrors-si">Slovenia</link>, - <link linkend="mirrors-se">Sweden</link>, - <link linkend="mirrors-tw">Taiwan</link>, - <link linkend="mirrors-th">Thailand</link>, - <link linkend="mirrors-uk">UK</link>, - <link linkend="mirrors-ua">Ukraine</link>, - <link linkend="mirrors-us">USA</link>.</para> - - <variablelist> - <varlistentry> - <term><anchor id="mirrors-ar">Argentina</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ar.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ar.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ar.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-au">Australia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@au.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp.au.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.au.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.au.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.au.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-br">Brazil</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@br.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp7.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.br.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ca">Canada</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ca.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ca.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ca.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-cn">China</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>phj@cn.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.cn.FreeBSD.org/pub/FreeBSD/">ftp://ftp.cn.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-cz">Czech Republic</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@cz.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.cz.FreeBSD.org/pub/FreeBSD/">ftp://ftp.cz.FreeBSD.org/pub/FreeBSD/</ulink> Contact: <email>calda@dzungle.ms.mff.cuni.cz</email></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-dk">Denmark</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@dk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.dk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.dk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ee">Estonia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ee.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ee.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ee.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-fi">Finland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@fi.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.fi.FreeBSD.org/pub/FreeBSD/">ftp://ftp.fi.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-fr">France</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@fr.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.fr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-de">Germany</term> - - <listitem> - <para>In case of problems, please contact the mirror admins - <email>de-bsd-hubs@de.FreeBSD.org </email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp7.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.de.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-hk">Hong Kong</term> - - <listitem> - <itemizedlist> - - <listitem> - <para><ulink - url="ftp://ftp.hk.super.net/pub/FreeBSD/">ftp://ftp.hk.super.net/pub/FreeBSD/</ulink> Contact: <email>ftp-admin@HK.Super.NET</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-hu">Hungary</term> - <listitem> - <para>In case of problems, please contact the hostmaster - <email>mohacsi@ik.bme.hu</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.hu.FreeBSD.org/pub/FreeBSD/">ftp://ftp.hu.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - - <varlistentry> - <term><anchor id="mirrors-ie">Ireland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ie.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ie.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ie.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-il">Israel</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@il.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.il.FreeBSD.org/pub/FreeBSD/">ftp://ftp.il.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.il.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.il.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-jp">Japan</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@jp.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-kr">Korea</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@kr.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-lt">Lithuania</term> - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@lt.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.lt.FreeBSD.org/pub/FreeBSD/">ftp://ftp.lt.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-nl">Netherlands</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@nl.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.nl.FreeBSD.org/pub/FreeBSD/">ftp://ftp.nl.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-nz">New Zealand</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@nz.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.nz.FreeBSD.org/pub/FreeBSD/">ftp://ftp.nz.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-pl">Poland</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@pl.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.pl.FreeBSD.org/pub/FreeBSD/">ftp://ftp.pl.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-pt">Portugal</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@pt.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.pt.FreeBSD.org/pub/FreeBSD/">ftp://ftp.pt.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ru">Russia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@ru.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ru.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-sa">Saudi Arabia</term> - <listitem> - <para>In case of problems, please contact - <email>ftpadmin@isu.net.sa</email></para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org/">ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - - <varlistentry> - <term><anchor id="mirrors-za">South Africa</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@za.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.za.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.za.FreeBSD.org/FreeBSD/">ftp://ftp3.za.FreeBSD.org/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-sk">Slovak Republic</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@sk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.sk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.sk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry><term><anchor id="mirrors-si">Slovenia</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@si.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.si.FreeBSD.org/pub/FreeBSD/">ftp://ftp.si.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-es">Spain</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@es.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.es.FreeBSD.org/pub/FreeBSD/">ftp://ftp.es.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-se">Sweden</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@se.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp.se.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.se.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.se.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-tw">Taiwan</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@tw.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp.tw.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.tw.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-th">Thailand</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.nectec.or.th/pub/FreeBSD/">ftp://ftp.nectec.or.th/pub/FreeBSD/</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-ua">Ukraine</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.ua.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ua.FreeBSD.org/pub/FreeBSD/</ulink> Contact: <email>freebsd-mnt@lucky.net</email>.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-uk">UK</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@uk.FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.uk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.uk.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><anchor id="mirrors-us">USA</term> - - <listitem> - <para>In case of problems, please contact the hostmaster - <email>hostmaster@FreeBSD.org</email> for this domain.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp2.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp3.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp4.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp5.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp6.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp7.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp8.FreeBSD.org/pub/FreeBSD/">ftp://ftp8.FreeBSD.org/pub/FreeBSD/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp9.FreeBSD.org/pub/os/FreeBSD/">ftp://ftp9.FreeBSD.org/pub/os/FreeBSD/</ulink></para> - </listitem> - - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="anoncvs"> - <title>Anonymous CVS</title> - - <sect2> - <title><anchor id="anoncvs-intro">Introduction</title> - - <para>Anonymous CVS (or, as it is otherwise known, - <emphasis>anoncvs</emphasis>) is a feature provided by the CVS - utilities bundled with FreeBSD for synchronizing with a remote - CVS repository. Among other things, it allows users of FreeBSD - to perform, with no special privileges, read-only CVS operations - against one of the FreeBSD project's official anoncvs servers. - To use it, one simply sets the <envar>CVSROOT</envar> - environment variable to point at the appropriate anoncvs server, - provides the well-known password <quote>anoncvs</quote> with the - <command>cvs login</command> command, and then uses the - &man.cvs.1; command to access it like any local - repository.</para> - - <para>While it can also be said that the <link - linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis> - services both perform essentially the same function, there are - various trade-offs which can influence the user's choice of - synchronization methods. In a nutshell, - <application>CVSup</application> is much more efficient in its - usage of network resources and is by far the most technically - sophisticated of the two, but at a price. To use - <application>CVSup</application>, a special client must first be - installed and configured before any bits can be grabbed, and - then only in the fairly large chunks which - <application>CVSup</application> calls - <emphasis>collections</emphasis>.</para> - - <para><application>Anoncvs</application>, by contrast, can be used - to examine anything from an individual file to a specific - program (like <command>ls</command> or <command>grep</command>) - by referencing the CVS module name. Of course, - <application>anoncvs</application> is also only good for - read-only operations on the CVS repository, so if it's your - intention to support local development in one repository shared - with the FreeBSD project bits then - <application>CVSup</application> is really your only - option.</para> - </sect2> - - <sect2> - <title><anchor id="anoncvs-usage">Using Anonymous CVS</title> - - <para>Configuring &man.cvs.1; to use an Anonymous CVS repository - is a simple matter of setting the <envar>CVSROOT</envar> - environment variable to point to one of the FreeBSD project's - <emphasis>anoncvs</emphasis> servers. At the time of this - writing, the following servers are available:</para> - - <itemizedlist> - <listitem> - <para><emphasis>USA</emphasis>: - :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs - (Use <command>cvs login</command> and enter the password - <quote>anoncvs</quote> when prompted.)</para> - </listitem> - </itemizedlist> - - <para>Since CVS allows one to <quote>check out</quote> virtually - any version of the FreeBSD sources that ever existed (or, in - some cases, will exist <!-- smiley -->:-), you need to be - familiar with the revision (<option>-r</option>) flag to - &man.cvs.1; and what some of the permissible values for it in - the FreeBSD Project repository are.</para> - - <para>There are two kinds of tags, revision tags and branch tags. - A revision tag refers to a specific revision. Its meaning stays - the same from day to day. A branch tag, on the other hand, - refers to the latest revision on a given line of development, at - any given time. Because a branch tag does not refer to a - specific revision, it may mean something different tomorrow than - it means today.</para> - - <para>Here are the branch tags that users might be interested - in (keep in mind that the only tags valid for the <link - linkend="ports">ports collection</link> is - <literal>HEAD</literal>).</para> - - <variablelist> - <varlistentry> - <term>HEAD</term> - - <listitem> - <para>Symbolic name for the main line, or FreeBSD-CURRENT. - Also the default when no revision is specified.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_4</term> - - <listitem> - <para>The line of development for FreeBSD-4.X, also known - as FreeBSD-STABLE.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.X, also known - as 3.X-STABLE.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.X, also known - as 2.2-STABLE. This branch is mostly obsolete.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here are the revision tags that users might be interested - in. Again, none of these are valid for the ports collection - since the ports collection does not have multiple - revisions.</para> - - <variablelist> - <varlistentry> - <term>RELENG_4_1_1_RELEASE</term> - - <listitem> - <para>FreeBSD 4.1.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_4_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD 4.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_4_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD 4.0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_5_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_4_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.4.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_3_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.3.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.2.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_3_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_8_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.8.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.7.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.6.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>When you specify a branch tag, you normally receive the - latest versions of the files on that line of development. If - you wish to receive some past version, you can do so by - specifying a date with the <option>-D date</option> flag. - See the &man.cvs.1; man page for more details.</para> - </sect2> - - <sect2> - <title>Examples</title> - - <para>While it really is recommended that you read the manual page - for &man.cvs.1; thoroughly before doing anything, here are some - quick examples which essentially show how to use Anonymous - CVS:</para> - - <example> - <title>Checking out something from -CURRENT (&man.ls.1;) and - deleting it again:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput> -&prompt.user; <userinput>cvs login</userinput> -<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>. -&prompt.user; <userinput>cvs co ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput> -&prompt.user; <userinput>cvs logout</userinput> - </screen> - </example> - - <example> - <title>Checking out the version of &man.ls.1; in the 3.X-STABLE - branch:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput> -&prompt.user; <userinput>cvs login</userinput> -<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>. -&prompt.user; <userinput>cvs co -rRELENG_3 ls</userinput> -&prompt.user; <userinput>cvs release -d ls</userinput> -&prompt.user; <userinput>cvs logout</userinput> - </screen> - </example> - - <example> - <title>Creating a list of changes (as unified diffs) to &man.ls.1;</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput> -&prompt.user; <userinput>cvs login</userinput> -<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>. -&prompt.user; <userinput>cvs rdiff -u -rRELENG_3_0_0_RELEASE -rRELENG_3_4_0_RELEASE ls</userinput> -&prompt.user; <userinput>cvs logout</userinput> - </screen> - </example> - - <example> - <title>Finding out what other module names can be used:</title> - - <screen> -&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput> -&prompt.user; <userinput>cvs login</userinput> -<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>. -&prompt.user; <userinput>cvs co modules</userinput> -&prompt.user; <userinput>more modules/modules</userinput> -&prompt.user; <userinput>cvs release -d modules</userinput> -&prompt.user; <userinput>cvs logout</userinput> - </screen> - </example> - </sect2> - - <sect2> - <title>Other Resources</title> - - <para>The following additional resources may be helpful in learning - CVS:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.cyclic.com/">Cyclic Software</ulink>, - commercial maintainers of CVS.</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSWeb</ulink> is - the FreeBSD Project web interface for CVS.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - - <sect1 id="ctm"> - <title>Using CTM</title> - - <para><application>CTM</application> is a method for keeping a - remote directory tree in sync with a central one. It has been - developed for usage with FreeBSD's source trees, though other - people may find it useful for other purposes as time goes by. - Little, if any, documentation currently exists at this time on the - process of creating deltas, so talk to &a.phk; for more - information should you wish to use <application>CTM</application> - for other things.</para> - - <sect2> - <title>Why should I use <application>CTM</application>?</title> - - <para><application>CTM</application> will give you a local copy of - the FreeBSD source trees. There are a number of - “flavors” of the tree available. Whether you wish - to track the entire CVS tree or just one of the branches, - <application>CTM</application> can provide you the information. - If you are an active developer on FreeBSD, but have lousy or - non-existent TCP/IP connectivity, or simply wish to have the - changes automatically sent to you, - <application>CTM</application> was made for you. You will need - to obtain up to three deltas per day for the most active - branches. However, you should consider having them sent by - automatic email. The sizes of the updates are always kept as - small as possible. This is typically less than 5K, with an - occasional (one in ten) being 10-50K and every now and then a - biggie of 100K+ or more coming around.</para> - - <para>You will also need to make yourself aware of the various - caveats related to working directly from the development sources - rather than a pre-packaged release. This is particularly true - if you choose the “current” sources. It is - recommended that you read <link linkend="current">Staying - current with FreeBSD</link>.</para> - </sect2> - - <sect2> - <title>What do I need to use - <application>CTM</application>?</title> - - <para>You will need two things: The <application>CTM</application> - program, and the initial deltas to feed it (to get up to - “current” levels).</para> - - <para>The <application>CTM</application> program has been part of - FreeBSD ever since version 2.0 was released, and lives in - <filename>/usr/src/usr.sbin/CTM</filename> if you have a copy - of the source available.</para> - - <para>If you are running a pre-2.0 version of FreeBSD, you can - fetch the current <application>CTM</application> sources - directly from:</para> - - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/</ulink></para> - - <para>The “deltas” you feed - <application>CTM</application> can be had two ways, FTP or - email. If you have general FTP access to the Internet then the - following FTP sites support access to - <application>CTM</application>:</para> - - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para> - - <para>or see section <link - linkend="mirrors-ctm">mirrors</link>.</para> - - <para>FTP the relevant directory and fetch the - <filename>README</filename> file, starting from there.</para> - - <para>If you wish to get your deltas via email:</para> - - <para>Send email to &a.majordomo; to subscribe to one of the - <application>CTM</application> distribution lists. - “ctm-cvs-cur” supports the entire cvs tree. - “ctm-src-cur” supports the head of the development - branch. “ctm-src-2_2” supports the 2.2 release - branch, etc.. (If you do not know how to subscribe yourself - using majordomo, send a message first containing the word - <literal>help</literal> — it will send you back usage - instructions.)</para> - - <para>When you begin receiving your <application>CTM</application> - updates in the mail, you may use the - <command>ctm_rmail</command> program to unpack and apply them. - You can actually use the <command>ctm_rmail</command> program - directly from a entry in <filename>/etc/aliases</filename> if - you want to have the process run in a fully automated fashion. - Check the <command>ctm_rmail</command> man page for more - details.</para> - - <note> - <para>No matter what method you use to get the - <application>CTM</application> deltas, you should subscribe to - the <email>ctm-announce@FreeBSD.org</email> mailing list. In - the future, this will be the only place where announcements - concerning the operations of the - <application>CTM</application> system will be posted. Send an - email to &a.majordomo; with a single line of - <literal>subscribe ctm-announce</literal> to get added to the - list.</para> - </note> - </sect2> - - <sect2> - <title>Using <application>CTM</application> for the first - time</title> - - <para>Before you can start using <application>CTM</application> - deltas, you will need to get to a starting point for the deltas - produced subsequently to it.</para> - - <para>First you should determine what you already have. Everyone - can start from an “empty” directory. You must use - an initial “Empty” delta to start off your - <application>CTM</application> supported tree. At some point it - is intended that one of these “started” deltas be - distributed on the CD for your convenience, however, this does - not currently happen.</para> - - <para>Since the trees are many tens of megabytes, you should - prefer to start from something already at hand. If you have a - -RELEASE CD, you can copy or extract an initial source from it. - This will save a significant transfer of data.</para> - - <para>You can recognize these “starter” deltas by the - <literal>X</literal> appended to the number - (<filename>src-cur.3210XEmpty.gz</filename> for instance). The - designation following the <filename>X</filename> corresponds to - the origin of your initial “seed”. - <filename>Empty</filename> is an empty directory. As a rule a - base transition from <filename>Empty</filename> is produced - every 100 deltas. By the way, they are large! 25 to 30 - Megabytes of <command>gzip</command>'d data is common for the - <filename>XEmpty</filename> deltas.</para> - - <para>Once you've picked a base delta to start from, you will also - need all deltas with higher numbers following it.</para> - </sect2> - - <sect2> - <title>Using <application>CTM</application> in your daily - life</title> - - <para>To apply the deltas, simply say:</para> - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput> -&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen> - - <para><application>CTM</application> understands deltas which have - been put through <command>gzip</command>, so you do not need to - gunzip them first, this saves disk space.</para> - - <para>Unless it feels very secure about the entire process, - <application>CTM</application> will not touch your tree. To - verify a delta you can also use the <option>-c</option> flag and - <application>CTM</application> 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.</para> - - <para>There are other options to <application>CTM</application> - as well, see the manual pages or look in the sources for more - information.</para> - - <para>I would also be very happy if somebody could help with the - “user interface” portions, as I have realized that I - cannot make up my mind on what options should do what, how and - when...</para> - - <para>That is really all there is to it. Every time you get a new - delta, just run it through <application>CTM</application> to - keep your sources up to date.</para> - - <para>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 - <command>fdwrite</command> to make a copy.</para> - </sect2> - - <sect2> - <title>Keeping your local changes</title> - - <para>As a developer one would like to experiment with and change - files in the source tree. <application>CTM</application> - supports local modifications in a limited way: before checking - for the presence of a file <filename>foo</filename>, it first - looks for <filename>foo.ctm</filename>. If this file exists, - CTM will operate on it instead of - <filename>foo</filename>.</para> - - <para>This behavior gives us a simple way to maintain local - changes: simply copy the files you plan to modify to the - corresponding file names with a <filename>.ctm</filename> - suffix. Then you can freely hack the code, while CTM keeps the - <filename>.ctm</filename> file up-to-date.</para> - </sect2> - - <sect2> - <title>Other interesting <application>CTM</application> options</title> - - <sect3> - <title>Finding out exactly what would be touched by an - update</title> - - <para>You can determine the list of changes that - <application>CTM</application> will make on your source - repository using the <option>-l</option> option to - <application>CTM</application>.</para> - - <para>This is useful if you would like to keep logs of the - changes, pre- or post- process the modified files in any - manner, or just are feeling a tad paranoid - <!-- smiley -->:-).</para> - </sect3> - - <sect3> - <title>Making backups before updating</title> - - <para>Sometimes you may want to backup all the files that would - be changed by a <application>CTM</application> update.</para> - - <para>Specifying the <option>-B backup-file</option> option - causes <application>CTM</application> to backup all files that - would be touched by a given <application>CTM</application> - delta to <filename>backup-file</filename>.</para> - </sect3> - - <sect3> - <title>Restricting the files touched by an update</title> - - <para>Sometimes you would be interested in restricting the scope - of a given <application>CTM</application> update, or may be - interested in extracting just a few files from a sequence of - deltas.</para> - - <para>You can control the list of files that - <application>CTM</application> would operate on by specifying - filtering regular expressions using the <option>-e</option> - and <option>-x</option> options.</para> - - <para>For example, to extract an up-to-date copy of - <filename>lib/libc/Makefile</filename> from your collection of - saved CTM deltas, run the commands:</para> - - <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput> -&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen> - - <para>For every file specified in a - <application>CTM</application> delta, the <option>-e</option> - and <option>-x</option> options are applied in the order given - on the command line. The file is processed by - <application>CTM</application> only if it is marked as - eligible after all the <option>-e</option> and - <option>-x</option> options are applied to it.</para> - </sect3> - </sect2> - - <sect2> - <title>Future plans for <application>CTM</application></title> - - <para>Tons of them:</para> - - <itemizedlist> - <listitem> - <para>Use some kind of authentication into the CTM system, so - as to allow detection of spoofed CTM updates.</para> - </listitem> - - <listitem> - <para>Clean up the options to <application>CTM</application>, - they became confusing and counter intuitive.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Miscellaneous stuff</title> - - <para>There is a sequence of deltas for the - <literal>ports</literal> collection too, but interest has not - been all that high yet. Tell me if you want an email list for - that too and we will consider setting it up.</para> - </sect2> - - <sect2 id="mirrors-ctm"> - <title>CTM mirrors</title> - - <para><link linkend="ctm">CTM</link>/FreeBSD is available via anonymous - FTP from the following mirror sites. If you choose to obtain CTM via - anonymous FTP, please try to use a site near you.</para> - - <para>In case of problems, please contact &a.phk;.</para> - - <variablelist> - <varlistentry> - <term>California, Bay Area, official source</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Germany, Trier</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM/">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>South Africa, backup server for old deltas</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Taiwan/R.O.C, Chiayi</term> - - <listitem> - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ctm3.tw.FreeBSD.org/pub/freebsd/CTM/</ulink></para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>If you did not find a mirror near to you or the mirror is - incomplete, try <ulink url="http://ftpsearch.ntnu.no/">FTP - search</ulink> at <ulink - url="http://ftpsearch.ntnu.no/ftpsearch/">http://ftpsearch.ntnu.no/ftpsearch</ulink>. - FTP search is a great free archie server in Trondheim, Norway.</para> - </sect2></sect1> - - <sect1 id="cvsup"> - <title>Using CVSup</title> - - <sect2 id="cvsup-intro"> - <title>Introduction</title> - - <para><application>CVSup</application> is a software package for - distributing and updating source trees from a master CVS - repository on a remote server host. The FreeBSD sources are - maintained in a CVS repository on a central development machine - in California. With <application>CVSup</application>, FreeBSD - users can easily keep their own source trees up to date.</para> - - <para><application>CVSup</application> uses the so-called - <emphasis>pull</emphasis> model of updating. Under the pull - model, each client asks the server for updates, if and when they - are wanted. The server waits passively for update requests from - its clients. Thus all updates are instigated by the client. - The server never sends unsolicited updates. Users must either - run the <application>CVSup</application> client manually to get - an update, or they must set up a <command>cron</command> job to - run it automatically on a regular basis.</para> - - <para>The term <application>CVSup</application>, capitalized just - so, refers to the entire software package. Its main components - are the client <command>cvsup</command> which runs on each - user's machine, and the server <command>cvsupd</command> which - runs at each of the FreeBSD mirror sites.</para> - - <para>As you read the FreeBSD documentation and mailing lists, you - may see references to <application>sup</application>. - <application>Sup</application> was the predecessor of - <application>CVSup</application>, and it served a similar - purpose.<application>CVSup</application> is in used in much the - same way as sup and, in fact, uses configuration files which are - backward-compatible with <command>sup</command>'s. - <application>Sup</application> is no longer used in the FreeBSD - project, because <application>CVSup</application> is both faster - and more flexible.</para> - </sect2> - - <sect2 id="cvsup-install"> - <title>Installation</title> - - <para>The easiest way to install <application>CVSup</application> - is to use the <filename>net/cvsup-bin</filename> port - from the FreeBSD <link linkend="ports">ports collection</link>. - If you prefer to build <application>CVSup</application> from - source, you can use the <filename>net/cvsup</filename> - port instead. But be forewarned: the - <filename>net/cvsup</filename> port depends on the Modula-3 - system, which takes a substantial amount of time, memory, and - disk space to build.</para> - - <para>If you do not know anything about cvsup at all and want a - single package which will install it, set up the configuration - file and start the transfer via a pointy-clicky type of - interface, then get the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz">cvsupit</ulink> - package. Just hand it to &man.pkg.add.1; and it will lead you - through the configuration process in a menu-oriented - fashion.</para> - </sect2> - - <sect2 id="cvsup-config"> - <title>CVSup Configuration</title> - - <para><application>CVSup</application>'s operation is controlled - by a configuration file called the <filename>supfile</filename>. - There are some sample <filename>supfiles</filename> in the - directory <ulink - url="file:/usr/share/examples/cvsup/">/usr/share/examples/cvsup/</ulink>.</para> - - <para>The information in a <filename>supfile</filename> answers - the following questions for cvsup:</para> - - <itemizedlist> - <listitem> - <para><link linkend="cvsup-config-files">Which files do you - want to receive?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-vers">Which versions of them - do you want?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-where">Where do you want to - get them from?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-dest">Where do you want to - put them on your own machine?</link></para> - </listitem> - - <listitem> - <para><link linkend="cvsup-config-status">Where do you want to - put your status files?</link></para> - </listitem> - </itemizedlist> - - <para>In the following sections, we will construct a typical - <filename>supfile</filename> by answering each of these - questions in turn. First, we describe the overall structure of - a <filename>supfile</filename>.</para> - - <para>A <filename>supfile</filename> is a text file. Comments - begin with <literal>#</literal> and extend to the end of the - line. Lines that are blank and lines that contain only - comments are ignored.</para> - - <para>Each remaining line describes a set of files that the user - wishes to receive. The line begins with the name of a - <quote>collection</quote>, a logical grouping of files defined by - the server. The name of the collection tells the server which - files you want. After the collection name come zero or more - fields, separated by white space. These fields answer the - questions listed above. There are two types of fields: flag - fields and value fields. A flag field consists of a keyword - standing alone, e.g., <literal>delete</literal> or - <literal>compress</literal>. A value field also begins with a - keyword, but the keyword is followed without intervening white - space by <literal>=</literal> and a second word. For example, - <literal>release=cvs</literal> is a value field.</para> - - <para>A <filename>supfile</filename> typically specifies more than - one collection to receive. One way to structure a - <filename>supfile</filename> is to specify all of the relevant - fields explicitly for each collection. However, that tends to - make the <filename>supfile</filename> lines quite long, and it - is inconvenient because most fields are the same for all of the - collections in a <filename>supfile</filename>. - <application>CVSup</application> provides a defaulting mechanism - to avoid these problems. Lines beginning with the special - pseudo-collection name <literal>*default</literal> can be used - to set flags and values which will be used as defaults for the - subsequent collections in the <filename>supfile</filename>. A - default value can be overridden for an individual collection, by - specifying a different value with the collection itself. - Defaults can also be changed or augmented in mid-supfile by - additional <literal>*default</literal> lines.</para> - - <para>With this background, we will now proceed to construct a - <filename>supfile</filename> for receiving and updating the main - source tree of <link - linkend="current">FreeBSD-CURRENT</link>.</para> - - <itemizedlist> - <listitem> - <para><anchor id="cvsup-config-files">Which files do you want - to receive?</para> - - <para>The files available via <application>CVSup</application> - are organized into named groups called - <quote>collections</quote>. The collections that are - available are described <link - linkend="cvsup-collec">here</link>. In this example, we - wish to receive the entire main source tree for the FreeBSD - system. There is a single large collection - <literal>src-all</literal> which will give us all of that. - As a first step toward constructing our - <filename>supfile</filename>, we - simply list the collections, one per line (in this case, - only one line):</para> - - <programlisting> -src-all</programlisting> - </listitem> - - <listitem> - <para><anchor id="cvsup-config-vers">Which version(s) of them - do you want?</para> - - <para>With <application>CVSup</application>, you can receive - virtually any version of the sources that ever existed. - That is possible because the cvsupd server works directly - from the CVS repository, which contains all of the versions. - You specify which one of them you want using the - <literal>tag=</literal> and <option>date=</option> value - fields.</para> - - <warning> - <para>Be very careful to specify any <literal>tag=</literal> - fields correctly. Some tags are valid only for certain - collections of files. If you specify an incorrect or - misspelled tag, CVSup will delete files which you probably - do not want deleted. In particular, use <emphasis>only - </emphasis> <literal>tag=.</literal> for the - <literal>ports-*</literal> collections.</para> - </warning> - - <para>The <literal>tag=</literal> field names a symbolic tag - in the repository. There are two kinds of tags, revision - tags and branch tags. A revision tag refers to a specific - revision. Its meaning stays the same from day to day. A - branch tag, on the other hand, refers to the latest revision - on a given line of development, at any given time. Because - a branch tag does not refer to a specific revision, it may - mean something different tomorrow than it means - today.</para> - - <para>Here are the branch tags that users might be interested - in. Keep in mind that only the <literal>tag=.</literal> is - relevant for the ports collection.</para> - - <variablelist> - <varlistentry> - <term>tag=.</term> - - <listitem> - <para>The main line of development, also known as - FreeBSD-CURRENT.</para> - - <note> - <para>The <literal>.</literal> is not punctuation; it - is the name of the tag. Valid for all - collections.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_4</term> - - <listitem> - <para>The line of development for FreeBSD-4.X, also known as - FreeBSD-STABLE.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3</term> - - <listitem> - <para>The line of development for FreeBSD-3.X</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2</term> - - <listitem> - <para>The line of development for FreeBSD-2.2.X, also - known as 2.2-STABLE.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here are the revision tags that users might be interested - in. Again, these are not valid for the ports - collection.</para> - - <variablelist> - <varlistentry> - <term>tag=RELENG_4_1_1_RELEASE</term> - - <listitem> - <para>FreeBSD-4.1.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_4_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-4.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_4_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-4.0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_5_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_4_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.4.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_3_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.3.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.2.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_1_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_3_0_0_RELEASE</term> - - <listitem> - <para>FreeBSD-3.0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_8_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.8.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_7_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.7.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_6_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.6.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_5_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_2_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.2.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_1_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.1.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tag=RELENG_2_2_0_RELEASE</term> - - <listitem> - <para>FreeBSD-2.2.0.</para> - </listitem> - </varlistentry> - </variablelist> - - <warning> - <para>Be very careful to type the tag name exactly as shown. - <application>CVSup</application> cannot distinguish - between valid and invalid tags. If you misspell the tag, - <application>CVSup</application> will behave as though you - had specified a valid tag which happens to refer to no - files at all. It will delete your existing sources in - that case.</para> - </warning> - - <para>When you specify a branch tag, you normally receive the - latest versions of the files on that line of development. - If you wish to receive some past version, you can do so by - specifying a date with the <option>date=</option> value - field. The &man.cvsup.1; manual page explains how to do - that.</para> - - <para>For our example, we wish to receive FreeBSD-CURRENT. We - add this line at the beginning of our - <filename>supfile</filename>:</para> - - <programlisting> -*default tag=.</programlisting> - - <para>There is an important special case that comes into play - if you specify neither a <literal>tag=</literal> field nor a - <literal>date=</literal> field. In that case, you receive - the actual RCS files directly from the server's CVS - repository, rather than receiving a particular version. - Developers generally prefer this mode of operation. By - maintaining a copy of the repository itself on their - systems, they gain the ability to browse the revision - histories and examine past versions of files. This gain is - achieved at a large cost in terms of disk space, - however.</para> - </listitem> - - <listitem> - <para><anchor id="cvsup-config-where">Where do you want to get - them from?</para> - - <para>We use the <literal>host=</literal> field to tell - <command>cvsup</command> where to obtain its updates. Any - of the <link linkend="cvsup-mirrors">CVSup mirror - sites</link> will do, though you should try to select one - that is close to you in cyberspace. In this example we will - use a fictional FreeBSD distribution site, - <hostid role="fqdn">cvsup666.FreeBSD.org</hostid>:</para> - - <programlisting> -*default host=cvsup666.FreeBSD.org</programlisting> - - <para>You will need to change the host to one that actually - exists before running CVSup. On any particular run of - <command>cvsup</command>, you can override the host setting - on the command line, with <option>-h - <replaceable>hostname</replaceable></option>.</para> - </listitem> - - <listitem> - <para><anchor id="cvsup-config-dest">Where do you want to put - them on your own machine?</para> - - <para>The <literal>prefix=</literal> field tells - <command>cvsup</command> where to put the files it receives. - In this example, we will put the source files directly into - our main source tree, <filename>/usr/src</filename>. The - <filename>src</filename> directory is already implicit in - the collections we have chosen to receive, so this is the - correct specification:</para> - - <programlisting> -*default prefix=/usr</programlisting> - </listitem> - - <listitem> - <para><anchor id="cvsup-config-status">Where should - <command>cvsup</command> maintain its status files?</para> - - <para>The cvsup client maintains certain status files in what - is called the <quote>base</quote> directory. These files - help <application>CVSup</application> to work more - efficiently, by keeping track of which updates you have - already received. We will use the standard base directory, - <filename>/usr/local/etc/cvsup</filename>:</para> - - <programlisting> -*default base=/usr/local/etc/cvsup</programlisting> - - <para>This setting is used by default if it is not specified - in the <filename>supfile</filename>, so we actually do not - need the above line.</para> - - <para>If your base directory does not already exist, now would - be a good time to create it. The <command>cvsup</command> - client will refuse to run if the base directory does not - exist.</para> - </listitem> - - <listitem> - <para>Miscellaneous <filename>supfile</filename> - settings:</para> - - <para>There is one more line of boiler plate that normally - needs to be present in the - <filename>supfile</filename>:</para> - - <programlisting> -*default release=cvs delete use-rel-suffix compress</programlisting> - - <para><literal>release=cvs</literal> indicates that the server - should get its information out of the main FreeBSD CVS - repository. This is virtually always the case, but there - are other possibilities which are beyond the scope of this - discussion.</para> - - <para><literal>delete</literal> gives - <application>CVSup</application> permission to delete files. - You should always specify this, so that - <application>CVSup</application> can keep your source tree - fully up-to-date. <application>CVSup</application> is - careful to delete only those files for which it is - responsible. Any extra files you happen to have will be - left strictly alone.</para> - - <para><literal>use-rel-suffix</literal> is ... arcane. If you - really want to know about it, see the &man.cvsup.1; manual - page. Otherwise, just specify it and do not worry about - it.</para> - - <para><literal>compress</literal> enables the use of - gzip-style compression on the communication channel. If - your network link is T1 speed or faster, you probably should - not use compression. Otherwise, it helps - substantially.</para> - </listitem> - - <listitem> - <para>Putting it all together:</para> - - <para>Here is the entire <filename>supfile</filename> for our - example:</para> - - <programlisting> -*default tag=. -*default host=cvsup666.FreeBSD.org -*default prefix=/usr -*default base=/usr/local/etc/cvsup -*default release=cvs delete use-rel-suffix compress - -src-all</programlisting> - </listitem> - </itemizedlist> - <sect3> - <title>The refuse file</title> - - <para>As mentioned above, <application>CVSup</application> uses - a <emphasis>pull method</emphasis>. Basically, this means that - you connect to the <application>CVSup</application> server, and - it says, <quote>Here's what you can download from - me...</quote>, and your client responds <quote>OK, I'll take - this, this, this, and this.</quote> In the default - configuration, the <application>CVSup</application> client will - take every file associated with the collection and tag you - chose in the configuration file. However, this is not always - what you want, especially if you are synching the doc, ports, or - www trees — most people can't read four or five - languages, and therefore they don't need to download the - language-specific files. If you are - <application>CVSup</application>ing the ports collection, you - can get around this by specifying each collection individually - (e.g., <emphasis>ports-astrology</emphasis>, - <emphasis>ports-biology</emphasis>, etc instead of simply - saying <emphasis>ports-all</emphasis>). However, since the doc - and www trees do not have language-specific collections, you - must use one of <application>CVSup</application>'s many nifty - features; the <emphasis>refuse file</emphasis>.</para> - - <para>The <emphasis>refuse file</emphasis> essentially tells - <application>CVSup</application> that it should not take every - single file from a collection; in other words, it tells the - client to <emphasis>refuse</emphasis> certain files from the - server. The refuse file can be found (or, if you do not yet - have one, should be placed) in - <filename><replaceable>base</replaceable>/sup/refuse</filename>. - <replaceable>base</replaceable> is defined in your supfile; by - default, <replaceable>base</replaceable> is - <filename>/usr/sup</filename>, which means that by default the - refuse file is in <filename>/usr/sup/refuse</filename>.</para> - - <para>The refuse file has a very simple format; it simply - contains the names of files or directories that you do not wish - to to download. For example, since I cannot speak any languages - except for English and some German, and I do not feel the need - to use German applications, I have the following in my - <emphasis>refuse file</emphasis>:</para> - - <screen> - ports/chinese - ports/german - ports/japanese - ports/korean - ports/russian - ports/vietnamese - doc/es_ES.ISO_8859-1 - doc/ja_JP.eucJP</screen> - - <para>and so forth for the other languages. Note that the name - of the repository is the first <quote>directory</quote> in the - <emphasis>refuse file</emphasis>.</para> - - <para>With this very useful feature, those users who are on - slow links or pay by the minute for their Internet connection - will be able to save valuable time as they will no longer need - to download files that they will never use. For more - information on <emphasis>refuse files</emphasis> and other neat - features of <application>CVSup</application>, please view its - man page.</para> - </sect3> - </sect2> - - <sect2> - <title>Running <application>CVSup</application></title> - - <para>You are now ready to try an update. The command line for - doing this is quite simple:</para> - - <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen> - - <para>where <filename><replaceable>supfile</replaceable></filename> - is of course the name of the supfile you have just created. - Assuming you are running under X11, <command>cvsup</command> - will display a GUI window with some buttons to do the usual - things. Press the <quote>go</quote> button, and watch it - run.</para> - - <para>Since you are updating your actual - <filename>/usr/src</filename> tree in this example, you will - need to run the program as <username>root</username> so that - <command>cvsup</command> has the permissions it needs to update - your files. Having just created your configuration file, and - having never used this program before, that might - understandably make you nervous. There is an easy way to do a - trial run without touching your precious files. Just create an - empty directory somewhere convenient, and name it as an extra - argument on the command line:</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput> -&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen> - - <para>The directory you specify will be used as the destination - directory for all file updates. - <application>CVSup</application> will examine your usual files - in <filename>/usr/src</filename>, but it will not modify or - delete any of them. Any file updates will instead land in - <filename>/var/tmp/dest/usr/src</filename>. - <application>CVSup</application> will also leave its base - directory status files untouched when run this way. The new - versions of those files will be written into the specified - directory. As long as you have read access to - <filename>/usr/src</filename>, you do not even need to be root - to perform this kind of trial run.</para> - - <para>If you are not running X11 or if you just do not like GUIs, - you should add a couple of options to the command line when you - run cvsup:</para> - - <screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen> - - <para>The <option>-g</option> tells cvsup not to use its GUI. - This is automatic if you are not running X11, but otherwise you - have to specify it.</para> - - <para>The <option>-L 2</option> tells cvsup to print out the - details of all the file updates it is doing. There are three - levels of verbosity, from <option>-L 0</option> to - <option>-L 2</option>. The default is 0, which means total - silence except for error messages.</para> - - <para>There are plenty of other options available. For a brief - list of them, type <command>cvsup -H</command>. For more - detailed descriptions, see the manual page.</para> - - <para>Once you are satisfied with the way updates are working, you - can arrange for regular runs of cvsup using &man.cron.8;. - Obviously, you should not let cvsup use its GUI when running it - from cron.</para> - </sect2> - - <sect2 id="cvsup-collec"> - <title><application>CVSup</application> File Collections</title> - - <para>The file collections available via - <application>CVSup</application> are organized hierarchically. - There are a few large collections, and they are divided into - smaller sub-collections. Receiving a large collection is - equivalent to receiving each of its sub-collections. The - hierarchical relationships among collections are reflected by - the use of indentation in the list below.</para> - - <para>The most commonly used collections are - <literal>src-all</literal>, and - <literal>ports-all</literal>. The other collections are used - only by small groups of people for specialized purposes, and - some mirror sites may not carry all of them.</para> - - <variablelist> - <varlistentry> - <term><literal>cvs-all release=cvs</literal></term> - - <listitem> - <para>The main FreeBSD CVS repository, including the - cryptography code.</para> - - <variablelist> - <varlistentry> - <term><literal>distrib release=cvs</literal></term> - - <listitem> - <para>Files related to the distribution and mirroring - of FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>doc-all release=cvs</literal></term> - - <listitem> - <para>Sources for the FreeBSD handbook and other - documentation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-all release=cvs</literal></term> - - <listitem> - <para>The FreeBSD ports collection.</para> - - <variablelist> - <varlistentry> - <term><literal>ports-archivers - release=cvs</literal></term> - - <listitem> - <para>Archiving tools.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-astro - release=cvs</literal></term> - - <listitem> - <para>Astronomical ports.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-audio - release=cvs</literal></term> - - <listitem> - <para>Sound support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-base - release=cvs</literal></term> - - <listitem> - <para>Miscellaneous files at the top of - /usr/ports.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-benchmarks - release=cvs</literal></term> - - <listitem> - <para>Benchmarks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-biology - release=cvs</literal></term> - - <listitem> - <para>Biology.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-cad - release=cvs</literal></term> - - <listitem> - <para>Computer aided design tools.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-chinese - release=cvs</literal></term> - - <listitem> - <para>Chinese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-comms - release=cvs</literal></term> - - <listitem> - <para>Communication software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-converters - release=cvs</literal></term> - - <listitem> - <para>character code converters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-databases - release=cvs</literal></term> - - <listitem> - <para>Databases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-deskutils - release=cvs</literal></term> - - <listitem> - <para>Things that used to be on the desktop - before computers were invented.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-devel - release=cvs</literal></term> - - <listitem> - <para>Development utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-editors - release=cvs</literal></term> - - <listitem> - <para>Editors.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-emulators - release=cvs</literal></term> - - <listitem> - <para>Emulators for other operating - systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-ftp - release=cvs</literal></term> - - <listitem> - <para>FTP client and server utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-games - release=cvs</literal></term> - - <listitem> - <para>Games.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-german - release=cvs</literal></term> - - <listitem> - <para>German language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-graphics - release=cvs</literal></term> - - <listitem> - <para>Graphics utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-irc - release=cvs</literal></term> - - <listitem> - <para>Internet Relay Chat utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-japanese - release=cvs</literal></term> - - <listitem> - <para>Japanese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-java - release=cvs</literal></term> - - <listitem> - <para>Java utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-korean - release=cvs</literal></term> - - <listitem> - <para>Korean language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-lang - release=cvs</literal></term> - - <listitem> - <para>Programming languages.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-mail - release=cvs</literal></term> - - <listitem> - <para>Mail software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-math - release=cvs</literal></term> - - <listitem> - <para>Numerical computation software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-mbone - release=cvs</literal></term> - - <listitem> - <para>MBone applications.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-misc - release=cvs</literal></term> - - <listitem> - <para>Miscellaneous utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-net - release=cvs</literal></term> - - <listitem> - <para>Networking software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-news - release=cvs</literal></term> - - <listitem> - <para>USENET news software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-palm - release=cvs</literal></term> - - <listitem> - <para>Software support for 3Com Palm(tm) - series.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-print - release=cvs</literal></term> - - <listitem> - <para>Printing software.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-russian - release=cvs</literal></term> - - <listitem> - <para>Russian language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-security - release=cvs</literal></term> - - <listitem> - <para>Security utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-shells - release=cvs</literal></term> - - <listitem> - <para>Command line shells.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-sysutils - release=cvs</literal></term> - - <listitem> - <para>System utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-textproc - release=cvs</literal></term> - - <listitem> - <para>text processing utilities (does not - include desktop publishing).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-vietnamese - release=cvs</literal></term> - - <listitem> - <para>Vietnamese language support.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-www - release=cvs</literal></term> - - <listitem> - <para>Software related to the World Wide - Web.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11 - release=cvs</literal></term> - - <listitem> - <para>Ports to support the X window - system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-clocks - release=cvs</literal></term> - - <listitem> - <para>X11 clocks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fm - release=cvs</literal></term> - - <listitem> - <para>X11 file managers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-fonts - release=cvs</literal></term> - - <listitem> - <para>X11 fonts and font utilities.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-toolkits - release=cvs</literal></term> - - <listitem> - <para>X11 toolkits.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-servers</literal></term> - - <listitem> - <para>X11 servers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ports-x11-wm</literal></term> - - <listitem> - <para>X11 window managers.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-all release=cvs</literal></term> - - <listitem> - <para>The main FreeBSD sources, including the - cryptography code.</para> - - <variablelist> - <varlistentry> - <term><literal>src-base - release=cvs</literal></term> - - <listitem> - <para>Miscellaneous files at the top of - <filename>/usr/src</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-bin - release=cvs</literal></term> - - <listitem> - <para>User utilities that may be needed in - single-user mode - (<filename>/usr/src/bin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-contrib - release=cvs</literal></term> - - <listitem> - <para>Utilities and libraries from outside the - FreeBSD project, used relatively unmodified - (<filename>/usr/src/contrib</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-crypto release=cvs</literal></term> - - <listitem> - <para>Cryptography utilities and libraries from - outside the FreeBSD project, used relatively - unmodified - (<filename>/usr/src/crypto</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-eBones release=cvs</literal></term> - - <listitem> - <para>Kerberos and DES - (<filename>/usr/src/eBones</filename>). Not - used in current releases of FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-etc - release=cvs</literal></term> - - <listitem> - <para>System configuration files - (<filename>/usr/src/etc</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-games - release=cvs</literal></term> - - <listitem> - <para>Games - (<filename>/usr/src/games</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-gnu - release=cvs</literal></term> - - <listitem> - <para>Utilities covered by the GNU Public - License (<filename>/usr/src/gnu</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-include - release=cvs</literal></term> - - <listitem> - <para>Header files - (<filename>/usr/src/include</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-kerberos5 - release=cvs</literal></term> - - <listitem> - <para>Kerberos5 security package - (<filename>/usr/src/kerberos5</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-kerberosIV - release=cvs</literal></term> - - <listitem> - <para>KerberosIV security package - (<filename>/usr/src/kerberosIV</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-lib - release=cvs</literal></term> - - <listitem> - <para>Libraries - (<filename>/usr/src/lib</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-libexec - release=cvs</literal></term> - - <listitem> - <para>System programs normally executed by other - programs - (<filename>/usr/src/libexec</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-release - release=cvs</literal></term> - - <listitem> - <para>Files required to produce a FreeBSD - release - (<filename>/usr/src/release</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-secure release=cvs</literal></term> - - <listitem> - <para>DES (<filename>/usr/src/secure</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-sbin - release=cvs</literal></term> - - <listitem> - <para>System utilities for single-user mode - (<filename>/usr/src/sbin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-share - release=cvs</literal></term> - - <listitem> - <para>Files that can be shared across multiple - systems - (<filename>/usr/src/share</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-sys - release=cvs</literal></term> - - <listitem> - <para>The kernel - (<filename>/usr/src/sys</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-sys-crypto - release=cvs</literal></term> - - <listitem> - <para>Kernel cryptography code - (<filename>/usr/src/sys/crypto</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-tools - release=cvs</literal></term> - - <listitem> - <para>Various tools for the maintenance of - FreeBSD - (<filename>/usr/src/tools</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-usrbin - release=cvs</literal></term> - - <listitem> - <para>User utilities - (<filename>/usr/src/usr.bin</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>src-usrsbin - release=cvs</literal></term> - - <listitem> - <para>System utilities - (<filename>/usr/src/usr.sbin</filename>).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>www release=cvs</literal></term> - - <listitem> - <para>The sources for the World Wide Web data.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>distrib release=self</literal></term> - - <listitem> - <para>The CVSup server's own configuration files. Used by - CVSup mirror sites.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>gnats release=current</literal></term> - - <listitem> - <para>The GNATS bug-tracking database.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>mail-archive release=current</literal></term> - - <listitem> - <para>FreeBSD mailing list archive.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>www release=current</literal></term> - - <listitem> - <para>The installed World Wide Web data. Used by WWW mirror - sites.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>For more information</title> - - <para>For the CVSup FAQ and other information about CVSup, see - <ulink url="http://www.polstra.com/projects/freeware/CVSup/">The - CVSup Home Page</ulink>.</para> - - <para>Most FreeBSD-related discussion of - <application>CVSup</application> takes place on the - &a.hackers;. New versions of the software are announced there, - as well as on the &a.announce;.</para> - - <para>Questions and bug reports should be addressed to the author - of the program at <email>cvsup-bugs@polstra.com</email>.</para> - </sect2> - - <sect2 id="cvsup-mirrors"> - <title>CVSup Sites</title> - - <para><link linkend="cvsup">CVSup</link> servers for FreeBSD are running - at the following sites:</para> - - <variablelist> - <varlistentry> - <term>Argentina</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.ar.FreeBSD.org (maintainer - <email>msagre@cactus.fi.uba.ar</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Australia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.au.FreeBSD.org (maintainer - <email>dawes@xfree86.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.au.FreeBSD.org (maintainer - <email>FreeBSD@admin.gil.com.au</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Austria</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.at.FreeBSD.org (maintainer - <email>postmaster@wu-wien.ac.at</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Brazil</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.br.FreeBSD.org (maintainer - <email>cvsup@cvsup.br.FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.br.FreeBSD.org (maintainer - <email>tps@ti.sk</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.br.FreeBSD.org (maintainer - <email>camposr@matrix.com.br</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Canada</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ca.FreeBSD.org (maintainer - <email>dan@jaded.net</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.ca.FreeBSD.org (maintainer - <email>mitayai@dreaming.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>China</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.cn.FreeBSD.org (maintainer - <email>phj@cn.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Czech Republic</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.cz.FreeBSD.org (maintainer - <email>cejkar@dcse.fee.vutbr.cz</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Denmark</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.dk.FreeBSD.org (maintainer - <email>jesper@skriver.dk</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Estonia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ee.FreeBSD.org (maintainer - <email>taavi@uninet.ee</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Finland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.fi.FreeBSD.org (maintainer - <email>count@key.sms.fi</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.fi.FreeBSD.org (maintainer - <email>count@key.sms.fi</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>France</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.fr.FreeBSD.org (maintainer - <email>hostmaster@fr.FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.fr.FreeBSD.org (maintainer - <email>ftpmaint@uvsq.fr</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Germany</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.de.FreeBSD.org (maintainer - <email>wosch@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.de.FreeBSD.org (maintainer - <email>cvsup@nikoma.de</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.de.FreeBSD.org (maintainer - <email>ag@leo.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup4.de.FreeBSD.org (maintainer - <email>cvsup@cosmo-project.de</email>)</para> - </listitem> - - <listitem> - <para>cvsup5.de.FreeBSD.org (maintainer - <email>rse@freebsd.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Iceland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.is.FreeBSD.org (maintainer - <email>adam@veda.is</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Japan</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup.jp.FreeBSD.org (maintainer - <email>cvsupadm@jp.FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.jp.FreeBSD.org (maintainer - <email>max@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.jp.FreeBSD.org (maintainer - <email>shige@cin.nihon-u.ac.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup4.jp.FreeBSD.org (maintainer - <email>cvsup-admin@ftp.media.kyoto-u.ac.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup5.jp.FreeBSD.org (maintainer - <email>cvsup@imasy.or.jp</email>)</para> - </listitem> - - <listitem> - <para>cvsup6.jp.FreeBSD.org (maintainer - <email>cvsupadm@jp.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Korea</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.kr.FreeBSD.org (maintainer - <email>cjh@kr.FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.kr.FreeBSD.org (maintainer - <email>holywar@mail.holywar.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Lithuania</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.lt.FreeBSD.org (maintainer - <email>domas.mituzas@delfi.lt</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Netherlands</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.nl.FreeBSD.org (maintainer - <email>xaa@xaa.iae.nl</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.nl.FreeBSD.org (maintainer - <email>cvsup@nl.uu.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Norway</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.no.FreeBSD.org (maintainer - <email>Per.Hove@math.ntnu.no</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Poland</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.pl.FreeBSD.org (maintainer - <email>Mariusz@kam.pl</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Portugal</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.pt.FreeBSD.org (maintainer - <email>jpedras@webvolution.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Russia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.ru.FreeBSD.org (maintainer - <email>ache@nagual.pp.ru</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.ru.FreeBSD.org (maintainer - <email>dv@dv.ru</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.ru.FreeBSD.org (maintainer - <email>fjoe@iclub.nsu.ru</email>)</para> - </listitem> - - <listitem> - <para>cvsup4.ru.FreeBSD.org (maintainer - <email>zhecka@klondike.ru</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slovak Republic</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.sk.FreeBSD.org (maintainer - <email>tps@tps.sk</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.sk.FreeBSD.org (maintainer - <email>tps@tps.sk</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slovenia</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.si.FreeBSD.org (maintainer - <email>blaz@si.FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>South Africa</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.za.FreeBSD.org (maintainer - <email>markm@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.za.FreeBSD.org (maintainer - <email>markm@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Spain</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.es.FreeBSD.org (maintainer - <email>jesusr@FreeBSD.org</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Sweden</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.se.FreeBSD.org (maintainer - <email>pantzer@ludd.luth.se</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Taiwan</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.tw.FreeBSD.org (maintainer - <email>jdli@freebsd.csie.nctu.edu.tw</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.tw.FreeBSD.org (maintainer - <email>ycheng@sinica.edu.tw</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.tw.FreeBSD.org (maintainer - <email>foxfair@FreeBSD.org</email>)</para> - </listitem> - - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Ukraine</term> - - <listitem> - <itemizedlist> - - <listitem> - <para>cvsup2.ua.FreeBSD.org (maintainer - <email>freebsd-mnt@lucky.net</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.ua.FreeBSD.org (maintainer - <email>ftpmaster@ukr.net</email>), Kiev</para> - </listitem> - - <listitem> - <para>cvsup4.ua.FreeBSD.org (maintainer - <email>phantom@cris.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>United Kingdom</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup.uk.FreeBSD.org (maintainer - <email>joe@pavilion.net</email>)</para> - </listitem> - - <listitem> - <para>cvsup2.uk.FreeBSD.org (maintainer - <email>brian@FreeBSD.org</email>)</para> - </listitem> - - <listitem> - <para>cvsup3.uk.FreeBSD.org (maintainer - <email>ftp-admin@plig.net</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>USA</term> - - <listitem> - <itemizedlist> - <listitem> - <para>cvsup1.FreeBSD.org (maintainer - <email>skynyrd@opus.cts.cwu.edu</email>), Washington - state</para> - </listitem> - - <listitem> - <para>cvsup2.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), California</para> - </listitem> - - <listitem> - <para>cvsup3.FreeBSD.org (maintainer - <email>wollman@FreeBSD.org</email>), Massachusetts</para> - </listitem> - - <listitem> - <para>cvsup4.FreeBSD.org (maintainer - <email>rgrimes@FreeBSD.org</email>), Oregon</para> - </listitem> - - <listitem> - <para>cvsup5.FreeBSD.org (maintainer - <email>mjr@blackened.com</email>), Arizona</para> - </listitem> - - <listitem> - <para>cvsup6.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), Florida</para> - </listitem> - - <listitem> - <para>cvsup7.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), Washington state</para> - </listitem> - - <listitem> - <para>cvsup8.FreeBSD.org (maintainer - <email>hostmaster@bigmirror.com</email>), Washington - state</para> - </listitem> - - <listitem> - <para>cvsup9.FreeBSD.org (maintainer - <email>qbsd@uswest.net</email>), Minnesota</para> - </listitem> - - <listitem> - <para>cvsup10.FreeBSD.org (maintainer - <email>jdp@FreeBSD.org</email>), California</para> - </listitem> - - <listitem> - <para>cvsup11.FreeBSD.org (maintainer - <email>cvsup@research.uu.net</email>), Virginia</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - <para>The following <application>CVSup</application> site is especially - designed for <link linkend="ctm">CTM</link> users. Unlike the other - CVSup mirrors, it is kept up-to-date by <application>CTM</application>. - That means if you <application>CVSup</application> - <literal>cvs-all</literal> with <literal>release=cvs</literal> from this - site, you get a version of the repository (including the inevitable - <filename>.ctm_status</filename> file) which is suitable for being - updated using the <application>CTM</application> - <literal>cvs-cur</literal> deltas. This allows users who track the - entire <literal>cvs-all</literal> tree to go from - <application>CVSup</application> to <application>CTM</application> - without having to rebuild their repository from scratch using a fresh - <application>CTM</application> base delta.</para> - - <note> - <para>This special feature only works for the <literal>cvs-all</literal> - distribution with <command>cvs</command> as the release tag. - CVSupping any other distribution and/or release will get you the - specified distribution, but it will not be suitable for - <application>CTM</application> updating.</para> - </note> - - <note> - <para>Because the current version of <application>CTM</application> does - not preserve the time stamps of files, the time stamps at this mirror - site are not the same as those at other mirror sites. Switching - between this site and other sites is not recommended. It will work - correctly, but will be somewhat inefficient.</para> - </note> - - <variablelist> - <varlistentry> - <term>Germany</term> - - <listitem> - <itemizedlist> - <listitem> - <para>ctm.FreeBSD.org (maintainer - <email>blank@fox.uni-trier.de</email>)</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="mirrors-afs"> - <title>AFS Sites</title> - - <para>AFS servers for FreeBSD are running at the following sites;</para> - - <variablelist> - <varlistentry> - <term>Sweden</term> - - <listitem> - <para>The path to the files are: - <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD/</filename></para> - - <programlisting> -stacken.kth.se # Stacken Computer Club, KTH, Sweden -130.237.234.43 #hot.stacken.kth.se -130.237.237.230 #fishburger.stacken.kth.se -130.237.234.3 #milko.stacken.kth.se</programlisting> - - <para>Maintainer <email>ftp@stacken.kth.se</email></para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/newsgroups.ent b/en_US.ISO8859-1/books/handbook/newsgroups.ent deleted file mode 100644 index db6585344a..0000000000 --- a/en_US.ISO8859-1/books/handbook/newsgroups.ent +++ /dev/null @@ -1,10 +0,0 @@ -<!-- - Names of FreeBSD newsgroups - - $FreeBSD$ ---> - -<!ENTITY ng.misc "the - <ulink url='news:comp.unix.bsd.freebsd.misc'>comp.unix.bsd.freebsd.misc</ulink> - newsgroup"> - diff --git a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml deleted file mode 100644 index d15dd55dc0..0000000000 --- a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml +++ /dev/null @@ -1,1644 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml,v 1.50 2000/11/01 02:25:03 joe Exp $ ---> - -<appendix id="pgpkeys"> - <title>PGP Keys</title> - - <para>In case you need to verify a signature or send encrypted email - to one of the officers or developers a number of keys are provided - here for your convenience. &a.wollman; maintains <ulink - url="http://people.FreeBSD.org/~wollman/freebsd.keyring">a - complete keyring of FreeBSD.org users</ulink> for easy - download.</para> - - <sect1 id="pgpkeys-officers"> - <title>Officers</title> - - <sect2> - <title>FreeBSD Security Officer - <email>security-officer@FreeBSD.org</email></title> - - <programlisting> -FreeBSD Security Officer <security-officer@FreeBSD.org> -Fingerprint = 41 08 4E BB DB 41 60 71 F9 E5 0E 98 73 AF 3F 11 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3i - -mQCNAzF7MY4AAAEEAK7qBgPuBejER5HQbQlsOldk3ZVWXlRj54raz3IbuAUrDrQL -h3g57T9QY++f3Mot2LAf5lDJbsMfWrtwPrPwCCFRYQd6XH778a+l4ju5axyjrt/L -Ciw9RrOC+WaPv3lIdLuqYge2QRC1LvKACIPNbIcgbnLeRGLovFUuHi5z0oilAAUR -tDdGcmVlQlNEIFNlY3VyaXR5IE9mZmljZXIgPHNlY3VyaXR5LW9mZmljZXJAZnJl -ZWJzZC5vcmc+iQCVAwUQMX6yrOJgpPLZnQjrAQHyowQA1Nv2AY8vJIrdp2ttV6RU -tZBYnI7gTO3sFC2bhIHsCvfVU3JphfqWQ7AnTXcD2yPjGcchUfc/EcL1tSlqW4y7 -PMP4GHZp9vHog1NAsgLC9Y1P/1cOeuhZ0pDpZZ5zxTo6TQcCBjQA6KhiBFP4TJql -3olFfPBh3B/Tu3dqmEbSWpuJAJUDBRAxez3C9RVb+45ULV0BAak8A/9JIG/jRJaz -QbKom6wMw852C/Z0qBLJy7KdN30099zMjQYeC9PnlkZ0USjQ4TSpC8UerYv6IfhV -nNY6gyF2Hx4CbEFlopnfA1c4yxtXKti1kSN6wBy/ki3SmqtfDhPQ4Q31p63cSe5A -3aoHcjvWuqPLpW4ba2uHVKGP3g7SSt6AOYkAlQMFEDF8mz0ff6kIA1j8vQEBmZcD -/REaUPDRx6qr1XRQlMs6pfgNKEwnKmcUzQLCvKBnYYGmD5ydPLxCPSFnPcPthaUb -5zVgMTjfjS2fkEiRrua4duGRgqN4xY7VRAsIQeMSITBOZeBZZf2oa9Ntidr5PumS -9uQ9bvdfWMpsemk2MaRG9BSoy5Wvy8VxROYYUwpT8Cf2iQCVAwUQMXsyqWtaZ42B -sqd5AQHKjAQAvolI30Nyu3IyTfNeCb/DvOe9tlOn/o+VUDNJiE/PuBe1s2Y94a/P -BfcohpKC2kza3NiW6lLTp00OWQsuu0QAPc02vYOyseZWy4y3Phnw60pWzLcFdemT -0GiYS5Xm1o9nAhPFciybn9j1q8UadIlIq0wbqWgdInBT8YI/l4f5sf6JAJUDBRAx -ezKXVS4eLnPSiKUBAc5OBACIXTlKqQC3B53qt7bNMV46m81fuw1PhKaJEI033mCD -ovzyEFFQeOyRXeu25Jg9Bq0Sn37ynISucHSmt2tUD5W0+p1MUGyTqnfqejMUWBzO -v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1 -lw== -=ipyA ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - </sect1> - - <sect1 id="pgpkeys-core"> - <title>Core Team Members</title> - - <sect2> - <title>&a.asami;</title> - - <programlisting> -Satoshi Asami <asami@cs.berkeley.edu> - aka <asami@FreeBSD.org> -Fingerprint = EB 3C 68 9E FB 6C EB 3F DB 2E 0F 10 8F CE 79 CA - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzPVyoQAAAEEAL7W+kipxB171Z4SVyyL9skaA7hG3eRsSOWk7lfvfUBLtPog -f3OKwrApoc/jwLf4+Qpdzv5DLEt/6Hd/clskhJ+q1gMNHyZ5ABmUxrTRRNvJMTrb -3fPU3oZj7sL/MyiFaT1zF8EaMP/iS2ZtcFsbYOqGeA8E/58uk4NA0SoeCNiJAAUR -tCVTYXRvc2hpIEFzYW1pIDxhc2FtaUBjcy5iZXJrZWxleS5lZHU+iQCVAwUQM/AT -+EqGN2HYnOMZAQF11QP/eSXb2FuTb1yX5yoo1Im8YnIk1SEgCGbyEbOMMBznVNDy -5g2TAD0ofLxPxy5Vodjg8rf+lfMVtO5amUH6aNcORXRncE83T10JmeM6JEp0T6jw -zOHKz8jRzygYLBayGsNIJ4BGxa4LeaGxJpO1ZEvRlNkPH/YEXK5oQmq9/DlrtYOJ -AEUDBRAz42JT8ng6GBbVvu0BAU8nAYCsJ8PiJpRUGlrz6rxjX8hqM1v3vqFHLcG+ -G52nVMBSy+RZBgzsYIPwI5EZtWAKb22JAJUDBRAz4QBWdbtuOHaj97EBAaQPA/46 -+NLUp+Wubl90JoonoXocwAg88tvAUVSzsxPXj0lvypAiSI2AJKsmn+5PuQ+/IoQy -lywRsxiQ5GD7C72SZ1yw2WI9DWFeAi+qa4b8n9fcLYrnHpyCY+zxEpu4pam8FJ7H -JocEUZz5HRoKKOLHErzXDiuTkkm72b1glmCqAQvnB4kAlQMFEDPZ3gyDQNEqHgjY -iQEBFfUEALu2C0uo+1Z7C5+xshWRYY5xNCzK20O6bANVJ+CO2fih96KhwsMof3lw -fDso5HJSwgFd8WT/sR+Wwzz6BAE5UtgsQq5GcsdYQuGI1yIlCYUpDp5sgswNm+OA -bX5a+r4F/ZJqrqT1J56Mer0VVsNfe5nIRsjd/rnFAFVfjcQtaQmjiQCVAwUQM9uV -mcdm8Q+/vPRJAQELHgP9GqNiMpLQlZig17fDnCJ73P0e5t/hRLFehZDlmEI2TK7j -Yeqbw078nZgyyuljZ7YsbstRIsWVCxobX5eH1kX+hIxuUqCAkCsWUY4abG89kHJr -XGQn6X1CX7xbZ+b6b9jLK+bJKFcLSfyqR3M2eCyscSiZYkWKQ5l3FYvbUzkeb6K0 -IVNhdG9zaGkgQXNhbWkgPGFzYW1pQEZyZWVCU0QuT1JHPg== -=39SC ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.jkh;</title> - - <programlisting> -Jordan K. Hubbard <jkh@FreeBSD.org> -Fingerprint = 3C F2 27 7E 4A 6C 09 0A 4B C9 47 CD 4F 4D 0B 20 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzFjX0IAAAEEAML+nm9/kDNPp43ZUZGjYkm2QLtoC1Wxr8JulZXqk7qmhYcQ -jvX+fyoriJ6/7ZlnLe2oG5j9tZOnRLPvMaz0g9CpW6Dz3nkXrNPkmOFV9B8D94Mk -tyFeRJFqnkCuqBj6D+H8FtBwEeeTecSh2tJ0bZZTXnAMhxeOdvUVW/uOVC1dAAUR -tCNKb3JkYW4gSy4gSHViYmFyZCA8amtoQEZyZWVCU0Qub3JnPokBFQMFEDXCTXQM -j46yp4IfPQEBwO8IAIN0J09AXBf86dFUTFGcAMrEQqOF5IL+KGorAjzuYxERhKfD -ZV7jA+sCQqxkWfcVcE20kVyVYqzZIkio9a5zXP6TwA247JkPt54S1PmMDYHNlRIY -laXlNoji+4q3HP2DfHqXRT2859rYpm/fG/v6pWkos5voPKcZ2OFEp9W+Ap88oqw+ -5rx4VetZNJq1Epmis4INj6XqNqj85+MOOIYE+f445ohDM6B/Mxazd6cHFGGIR+az -VjZ6lCDMLjzhB5+FqfrDLYuMjqkMTR5z9DL+psUvPlCkYbQ11NEWtEmiIWjUcNJN -GCxGzv5bXk0XPu3ADwbPkFE2usW1cSM7AQFiwuyJAJUDBRAxe+Q9a1pnjYGyp3kB -AV7XA/oCSL/Cc2USpQ2ckwkGpyvIkYBPszIcabSNJAzm2hsU9Qa6WOPxD8olDddB -uJNiW/gznPC4NsQ0N8Zr4IqRX/TTDVf04WhLmd8AN9SOrVv2q0BKgU6fLuk979tJ -utrewH6PR2qBOjAaR0FJNk4pcYAHeT+e7KaKy96YFvWKIyDvc4kAlQMFEDF8ldof -f6kIA1j8vQEBDH4D/0Zm0oNlpXrAE1EOFrmp43HURHbij8n0Gra1w9sbfo4PV+/H -U8ojTdWLy6r0+prH7NODCkgtIQNpqLuqM8PF2pPtUJj9HwTmSqfaT/LMztfPA6PQ -csyT7xxdXl0+4xTDl1avGSJfYsI8XCAy85cTs+PQwuyzugE/iykJO1Bnj/paiQCV -AwUQMXvlBvUVW/uOVC1dAQF2fQP/RfYC6RrpFTZHjo2qsUHSRk0vmsYfwG5NHP5y -oQBMsaQJeSckN4n2JOgR4T75U4vS62aFxgPLJP3lOHkU2Vc7xhAuBvsbGr5RP8c5 -LvPOeUEyz6ZArp1KUHrtcM2iK1FBOmY4dOYphWyWMkDgYExabqlrAq7FKZftpq/C -BiMRuaw= -=C/Jw ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.imp;</title> - - <programlisting> -Warner Losh <imp@village.org> - aka <imp@FreeBSD.org> -Fingerprint = D4 31 FD B9 F7 90 17 E8 37 C5 E7 7F CF A6 C1 B9 ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzDzTiAAAAEEAK8D7KWEbVFUrmlqhUEnAvphNIqHEbqqT8s+c5f5c2uHtlcH -V4mV2TlUaDSVBN4+/D70oHmZc4IgiQwMPCWRrSezg9z/MaKlWhaslc8YT6Xc1q+o -EP/fAdKUrq49H0QQbkQk6Ks5wKW6v9AOvdmsS6ZJEcet6d9G4dxynu/2qPVhAAUR -tCBNLiBXYXJuZXIgTG9zaCA8aW1wQHZpbGxhZ2Uub3JnPokAlQMFEDM/SK1VLh4u -c9KIpQEBFPsD/1n0YuuUPvD4CismZ9bx9M84y5sxLolgFEfP9Ux196ZSeaPpkA0g -C9YX/IyIy5VHh3372SDWN5iVSDYPwtCmZziwIV2YxzPtZw0nUu82P/Fn8ynlCSWB -5povLZmgrWijTJdnUWI0ApVBUTQoiW5MyrNN51H3HLWXGoXMgQFZXKWYiQCVAwUQ -MzmhkfUVW/uOVC1dAQG3+AP/T1HL/5EYF0ij0yQmNTzt1cLt0b1e3N3zN/wPFFWs -BfrQ+nsv1zw7cEgxLtktk73wBGM9jUIdJu8phgLtl5a0m9UjBq5oxrJaNJr6UTxN -a+sFkapTLT1g84UFUO/+8qRB12v+hZr2WeXMYjHAFUT18mp3xwjW9DUV+2fW1Wag -YDKJAJUDBRAzOYK1s1pi61mfMj0BARBbA/930CHswOF0HIr+4YYUs1ejDnZ2J3zn -icTZhl9uAfEQq++Xor1x476j67Z9fESxyHltUxCmwxsJ1uOJRwzjyEoMlyFrIN4C -dE0C8g8BF+sRTt7VLURLERvlBvFrVZueXSnXvmMoWFnqpSpt3EmN6TNaLe8Cm87a -k6EvQy0dpnkPKokAlQMFEDD9Lorccp7v9qj1YQEBrRUD/3N4cCMWjzsIFp2Vh9y+ -RzUrblyF84tJyA7Rr1p+A7dxf7je3Zx5QMEXosWL1WGnS5vC9YH2WZwv6sCU61gU -rSy9z8KHlBEHh+Z6fdRMrjd9byPf+n3cktT0NhS23oXB1ZhNZcB2KKhVPlNctMqO -3gTYx+Nlo6xqjR+J2NnBYU8p -=7fQV ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.peter;</title> - - <programlisting> -Peter Wemm <peter@FreeBSD.org> - aka <peter@spinner.dialix.com> - aka <peter@haywire.dialix.com> - aka <peter@perth.dialix.oz.au> -Key fingerprint = 47 05 04 CA 4C EE F8 93 F6 DB 02 92 6D F5 58 8A - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAy9/FJwAAAEEALxs9dE9tFd0Ru1TXdq301KfEoe5uYKKuldHRBOacG2Wny6/ -W3Ill57hOi2+xmq5X/mHkapywxvy4cyLdt31i4GEKDvxpDvEzAYcy2n9dIup/eg2 -kEhRBX9G5k/LKM4NQsRIieaIEGGgCZRm0lINqw495aZYrPpO4EqGN2HYnOMZAAUT -tCVQZXRlciBXZW1tIDxwZXRlckBoYXl3aXJlLmRpYWxpeC5jb20+iQCVAwUQMwWT -cXW7bjh2o/exAQEFkQP+LIx5zKlYp1uR24xGApMFNrNtjh+iDIWnxxb2M2Kb6x4G -9z6OmbUCoDTGrX9SSL2Usm2RD0BZfyv9D9QRWC2TSOPkPRqQgIycc11vgbLolJJN -eixqsxlFeKLGEx9eRQCCbo3dQIUjc2yaOe484QamhsK1nL5xpoNWI1P9zIOpDiGJ -AJUDBRAxsRPqSoY3Ydic4xkBAbWLA/9q1Fdnnk4unpGQsG31Qbtr4AzaQD5m/JHI -4gRmSmbj6luJMgNG3fpO06Gd/Z7uxyCJB8pTst2a8C/ljOYZxWT+5uSzkQXeMi5c -YcI1sZbUpkHtmqPW623hr1PB3ZLA1TIcTbQW+NzJsxQ1Pc6XG9fGkT9WXQW3Xhet -AP+juVTAhLQlUGV0ZXIgV2VtbSA8cGV0ZXJAcGVydGguZGlhbGl4Lm96LmF1PokA -lQMFEDGxFCFKhjdh2JzjGQEB6XkD/2HOwfuFrnQUtdwFPUkgtEqNeSr64jQ3Maz8 -xgEtbaw/ym1PbhbCk311UWQq4+izZE2xktHTFClJfaMnxVIfboPyuiSF99KHiWnf -/Gspet0S7m/+RXIwZi1qSqvAanxMiA7kKgFSCmchzas8TQcyyXHtn/gl9v0khJkb -/fv3R20btB5QZXRlciBXZW1tIDxwZXRlckBGcmVlQlNELm9yZz6JAJUDBRAxsRJd -SoY3Ydic4xkBAZJUA/4i/NWHz5LIH/R4IF/3V3LleFyMFr5EPFY0/4mcv2v+ju9g -brOEM/xd4LlPrx1XqPeZ74JQ6K9mHR64RhKR7ZJJ9A+12yr5dVqihe911KyLKab9 -4qZUHYi36WQu2VtLGnw/t8Jg44fQSzbBF5q9iTzcfNOYhRkSD3BdDrC3llywO7Ql -UGV0ZXIgV2VtbSA8cGV0ZXJAc3Bpbm5lci5kaWFsaXguY29tPokAlQMFEDGxEi1K -hjdh2JzjGQEBdA4EAKmNFlj8RF9HQsoI3UabnvYqAWN5wCwEB4u+Zf8zq6OHic23 -TzoK1SPlmSdBE1dXXQGS6aiDkLT+xOdeewNs7nfUIcH/DBjSuklAOJzKliXPQW7E -kuKNwy4eq5bl+j3HB27i+WBXhn6OaNNQY674LGaR41EGq44Wo5ATcIicig/z -=gv+h ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - </sect1> - - <sect1 id="pgpkeys-developers"> - <title>Developers</title> - - <sect2> - <title>&a.jmb;</title> - - <programlisting> -Jonathan M. Bresler <jmb@FreeBSD.org> -f16 Fingerprint16 = 31 57 41 56 06 C1 40 13 C5 1C E3 E5 DC 62 0E FB - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAzG2GToAAAEEANI6+4SJAAgBpl53XcfEr1M9wZyBqC0tzpie7Zm4vhv3hO8s -o5BizSbcJheQimQiZAY4OnlrCpPxijMFSaihshs/VMAz1qbisUYAMqwGEO/T4QIB -nWNo0Q/qOniLMxUrxS1RpeW5vbghErHBKUX9GVhxbiVfbwc4wAHbXdKX5jjdAAUR -tCVKb25hdGhhbiBNLiBCcmVzbGVyIDxqbWJARnJlZUJTRC5PUkc+iQCVAwUQNbtI -gAHbXdKX5jjdAQHamQP+OQr10QRknamIPmuHmFYJZ0jU9XPIvTTMuOiUYLcXlTdn -GyTUuzhbEywgtOldW2V5iA8platXThtqC68NsnN/xQfHA5xmFXVbayNKn8H5stDY -2s/4+CZ06mmJfqYmONF1RCbUk/M84rVT3Gn2tydsxFh4Pm32lf4WREZWRiLqmw+J -AJUDBRA0DfF99RVb+45ULV0BAcZ0BACCydiSUG1VR0a5DBcHdtin2iZMPsJUPRqJ -tWvP6VeI8OFpNWQ4LW6ETAvn35HxV2kCcQMyht1kMD+KEJz7r8Vb94TS7KtZnNvk -2D1XUx8Locj6xel5c/Lnzlnnp7Bp1XbJj2u/NzCaZQ0eYBdP/k7RLYBYHQQln5x7 -BOuiRJNVU4kAlQMFEDQLcShVLh4uc9KIpQEBJv4D/3mDrD0MM9EYOVuyXik3UGVI -8quYNA9ErVcLdt10NjYc16VI2HOnYVgPRag3Wt7W8wlXShpokfC/vCNt7f5JgRf8 -h2a1/MjQxtlD+4/Js8k7GLa53oLon6YQYk32IEKexoLPwIRO4L2BHWa3GzHJJSP2 -aTR/Ep90/pLdAOu/oJDUiQCVAwUQMqyL0LNaYutZnzI9AQF25QP9GFXhBrz2tiWz -2+0gWbpcGNnyZbfsVjF6ojGDdmsjJMyWCGw49XR/vPKYIJY9EYo4t49GIajRkISQ -NNiIz22fBAjT2uY9YlvnTJ9NJleMfHr4dybo7oEKYMWWijQzGjqf2m8wf9OaaofE -KwBX6nxcRbKsxm/BVLKczGYl3XtjkcuJAJUDBRA1ol5TZWCprDT5+dUBATzXA/9h -/ZUuhoRKTWViaistGJfWi26FB/Km5nDQBr/Erw3XksQCMwTLyEugg6dahQ1u9Y5E -5tKPxbB69eF+7JXVHE/z3zizR6VL3sdRx74TPacPsdhZRjChEQc0htLLYAPkJrFP -VAzAlSlm7qd+MXf8fJovQs6xPtZJXukQukPNlhqZ94kAPwMFEDSH/kF4tXKgazlt -bxECfk4AoO+VaFVfguUkWX10pPSSfvPyPKqiAJ4xn8RSIe1ttmnqkkDMhLh00mKj -lLQuSm9uYXRoYW4gTS4gQnJlc2xlciA8Sm9uYXRoYW4uQnJlc2xlckBVU2kubmV0 -PokAlQMFEDXbdSkB213Sl+Y43QEBV/4D/RLJNTrtAqJ1ATxXWv9g8Cr3/YF0GTmx -5dIrJOpBup7eSSmiM/BL9Is4YMsoVbXCI/8TqA67TMICvq35PZU4wboQB8DqBAr+ -gQ8578M7Ekw1OAF6JXY6AF2P8k7hMcVBcVOACELPT/NyPNByG5QRDoNmlsokJaWU -/2ls4QSBZZlb -=zbCw ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.ache;</title> - - <programlisting> -Andrey A. Chernov <ache@FreeBSD.org> - aka <ache@nagual.pp.ru> -Key fingerprint = 33 03 9F 48 33 7B 4A 15 63 48 88 0A C4 97 FD 49 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAiqUMGQAAAEEAPGhcD6A2Buey5LYz0sphDLpVgOZc/bb9UHAbaGKUAGXmafs -Dcb2HnsuYGgX/zrQXuCi/wIGtXcZWB97APtKOhFsZnPinDR5n/dde/mw9FnuhwqD -m+rKSL1HlN0z/Msa5y7g16760wHhSR6NoBSEG5wQAHIMMq7Q0uJgpPLZnQjrAAUT -tCVBbmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucHAucnU+iQCVAwUQM2Ez -u+JgpPLZnQjrAQEyugP8DPnS8ixJ5OeuYgPFQf5sy6l+LrB6hyaS+lgsUPahWjNY -cnaDmfda/q/BV5d4+y5rlQe/pjnYG7/yQuAR3jhlXz8XDrqlBOnW9AtYjDt5rMfJ -aGFTGXAPGZ6k6zQZE0/YurT8ia3qjvuZm3Fw4NJrHRx7ETHRvVJDvxA6Ggsvmr20 -JEFuZHJleSBBLiBDaGVybm92IDxhY2hlQEZyZWVCU0Qub3JnPokAlQMFEDR5uVbi -YKTy2Z0I6wEBLgED/2mn+hw4/3peLx0Sb9LNx//NfCCkVefSf2G9Qwhx6dvwbX7h -mFca97h7BQN4GubU1Z5Ffs6TeamSBrotBYGmOCwvJ6S9WigF9YHQIQ3B4LEjskAt -pcjU583y42zM11kkvEuQU2Gde61daIylJyOxsgpjSWpkxq50fgY2kLMfgl/ftCZB -bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuaWV0enNjaGUubmV0PokAlQMFEDR5svDi -YKTy2Z0I6wEBOTQD/0OTCAXIjuak363mjERvzSkVsNtIH9hA1l0w6Z95+iH0fHrW -xXKT0vBZE0y0Em+S3cotLL0bMmVE3F3D3GyxhBVmgzjyx0NYNoiQjYdi+6g/PV30 -Cn4vOO6hBBpSyI6vY6qGNqcsawuRtHNvK/53MpOfKwSlICEBYQimcZhkci+EtCJB -bmRyZXkgQS4gQ2hlcm5vdiA8YWNoZUBuYWd1YWwucnU+iQCVAwUQMcm5HeJgpPLZ -nQjrAQHwvQP9GdmAf1gdcuayHEgNkc11macPH11cwWjYjzA2YoecFMGV7iqKK8QY -rr1MjbGXf8DAG8Ubfm0QbI8Lj8iG3NgqIru0c72UuHGSn/APfGGG0AtPX5UK/k7B -gI0Ca2po6NA5nrSp8tDsdEz/4gyea84RXl2prtTf5Jj07hflbRstGXK0MkFuZHJl -eSBBLiBDaGVybm92LCBCbGFjayBNYWdlIDxhY2hlQGFzdHJhbC5tc2suc3U+iQCV -AwUQMCsAo5/rGryoL8h3AQHq1QQAidyNFqA9hvrmMcjpY7csJVFlGvj574Wj4GPa -o3pZeuQaMBmsWqaXLYnWU/Aldb6kTz6+nRcQX50zFH0THSPfApwEW7yybSTI5apJ -mWT3qhKN2vmLNg2yNzhqLTzHLD1lH3i1pfQq8WevrNfjLUco5S/VuekTma/osnzC -Cw7fQzCJAJUDBRAwKvwoa1pnjYGyp3kBARihBACoXr3qfG65hFCyKJISmjOvaoGr -anxUIkeDS0yQdTHzhQ+dwB1OhhK15E0Nwr0MKajLMm90n6+Zdb5y/FIjpPriu8dI -rlHrWZlewa88eEDM+Q/NxT1iYg+HaKDAE171jmLpSpCL0MiJtO0i36L3ekVD7Hv8 -vffOZHPSHirIzJOZTYkAlQMFEDAau6zFLUdtDb+QbQEBQX8D/AxwkYeFaYxZYMFO -DHIvSk23hAsjCmUA2Uil1FeWAusb+o8xRfPDc7TnosrIifJqbF5+fcHCG5VSTGlh -Bhd18YWUeabf/h9O2BsQX55yWRuB2x3diJ1xI/VVdG+rxlMCmE4ZR1Tl9x+Mtun9 -KqKVpB39VlkCBYQ3hlgNt/TJUY4riQCVAwUQMBHMmyJRltlmbQBRAQFQkwP/YC3a -hs3ZMMoriOlt3ZxGNUUPTF7rIER3j+c7mqGG46dEnDB5sUrkzacpoLX5sj1tGR3b -vz9a4vmk1Av3KFNNvrZZ3/BZFGpq3mCTiAC9zsyNYQ8L0AfGIUO5goCIjqwOTNQI -AOpNsJ5S+nMAkQB4YmmNlI6GTb3D18zfhPZ6uciJAJUCBRAwD0sl4uW74fteFRkB -AWsAA/9NYqBRBKbmltQDpyK4+jBAYjkXBJmARFXKJYTlnTgOHMpZqoVyW96xnaa5 -MzxEiu7ZWm5oL10QDIp1krkBP2KcmvfSMMHb5aGCCQc2/P8NlfXAuHtNGzYiI0UA -Iwi8ih/S1liVfvnqF9uV3d3koE7VsQ9OA4Qo0ZL2ggW+/gEaYIkAlQMFEDAOz6qx -/IyHe3rl4QEBIvYD/jIr8Xqo/2I5gncghSeFR01n0vELFIvaF4cHofGzyzBpYsfA -+6pgFI1IM+LUF3kbUkAY/2uSf9U5ECcaMCTWCwVgJVO+oG075SHEM4buhrzutZiM -1dTyTaepaPpTyRMUUx9ZMMYJs7sbqLId1eDwrJxUPhrBNvf/w2W2sYHSY8cdiQCV -AwUQMAzqgHcdkq6JcsfBAQGTxwQAtgeLFi2rhSOdllpDXUwz+SS6bEjFTWgRsWFM -y9QnOcqryw7LyuFmWein4jasjY033JsODfWQPiPVNA3UEnXVg9+n8AvNMPO8JkRv -Cn1eNg0VaJy9J368uArio93agd2Yf/R5r+QEuPjIssVk8hdcy/luEhSiXWf6bLMV -HEA0J+OJAJUDBRAwDUi+4mCk8tmdCOsBAatBBACHB+qtW880seRCDZLjl/bT1b14 -5po60U7u6a3PEBkY0NA72tWDQuRPF/Cn/0+VdFNxQUsgkrbwaJWOoi0KQsvlOm3R -rsxKbn9uvEKLxExyKH3pxp76kvz/lEWwEeKvBK+84Pb1lzpG3W7u2XDfi3VQPTi3 -5SZMAHc6C0Ct/mjNlYkAlQMFEDAMrPD7wj+NsTMUOQEBJckD/ik4WsZzm2qOx9Fw -erGq7Zwchc+Jq1YeN5PxpzqSf4AG7+7dFIn+oe6X2FcIzgbYY+IfmgJIHEVjDHH5 -+uAXyb6l4iKc89eQawO3t88pfHLJWbTzmnvgz2cMrxt94HRvgkHfvcpGEgbyldq6 -EB33OunazFcfZFRIcXk1sfyLDvYE -=1ahV ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.green;</title> - - <programlisting> -pub 1024D/773905D6 2000-09-02 Brian Fundakowski Feldman <green@FreeBSD.org> -sig 773905D6 2000-09-02 Brian Fundakowski Feldman <green@FreeBSD.org> -sub 2048g/D2009B98 2000-09-02 -sig 773905D6 2000-09-02 Brian Fundakowski Feldman <green@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: GnuPG v1.0.2 (FreeBSD) -Comment: For info see http://www.gnupg.org - -mQGiBDmwog8RBAC+zE0IpGNV1naZh9os6S//ct1MfEMBoHH2TQhajIfLVraWA1I9 -AbOTuYYsPgxqK44ZnPUnNLmgIRBeVJXklXsdvjtMrh7QMj7evAGneT4vVdVj/9aY -7mEBuQephgvE4bUM7RPvOc/paiY08+HANljrvxcmMhygDTP5SEp/QJn7zwCghB66 -YVHI5u4xBAcHiHbyJWShmekEAIUWEIL4I33C9/yuenYogKLLS2/wmMYMCM5uMTkF -jls9KtfW/TQz8M8ZU6xdVBQjvDpw9G96l78amjiMN9Gm32C8m3HJaN0V+4SGJjiQ -fL07gu60LG0phnk1CtWLVQnH0LuIyB8jJeoaeYmS2Xv0rLLeMQ/hgUcQB8xu61Z4 -n1shBACf1w7B9ivEhBGWBsjuX2gTfW2eS4Mprs7FD1/8f/wbdvhitMdjZOFjOIO8 -yi/2W6B6T3suTcUgdC2qFmXkiWUun5kpGp/KRvrYm2eKpfveOL0HgD7juEZtBJcT -zV4oMel8TlZidIjIgLUeTbGfxbYPm0gONEGZHsymlZg9/7sDS7QtQnJpYW4gRnVu -ZGFrb3dza2kgRmVsZG1hbiA8Z3JlZW5ARnJlZUJTRC5vcmc+iFYEExECABYFAjmw -og8ECwoEAwMVAwIDFgIBAheAAAoJELVSsEN3OQXWVdUAnR13DerFrFdS3xufFox/ -m9T+VKs6AJ0Y7mgJalqPTTalJB3fbWUeIsZBsLkCDQQ5sKJfEAgA5LI3C4rGWWbG -cGZMLDhuBhjcoSFeWnrVVVZAPEm92+LcrfoT1Slp/2+KcKTJN/uQA0EpNmgUFBYr -3vSoVoVm10xBxBIX0zP7uPQNYKoJX3gLBiRZ3xOo4A6VqEpRbo5yjj3rshN4IO9B -T9zqx0ZoHSSsCds0Ax/m+0eSTghl+Shle1tbJstgcoxf6peKa6XcOAJWtQ+r6hZB -Z1tpjmIrfaeG/26da858C4TcogNhi1cpbyfQTZA7070JBnpRjhcQpELT4hRsJV2G -BX0dZn2hJOb5J5zl2M0N0Yx2BHM6mVT+oUc4EvfRn6fuhVRwIuckxwXaA31vWNPh -v+S9VD5BqwADBQgAjOXR9HNAh/teG0p4ynOlWx5G+tBWSfqWAKOSpi9SKb2Zipjg -bVNjmO4zNYhdAK6YbyQgrDrwUVPWoc8OieUACujklkY11eg8QFGr+tJow7iCMOPL -ES5vW1sBUl7dN+4tf5QTg5q9EGHL2rTndEVeutFbcKPR8YQXdu/U5hdO9zha5fd0 -RWjG7zLTaukO4mT2bTuojgCrnsvZ4D0XRW+SUcfXZrbKcsoFiU3q+EvlOuWg0W5b -FcFfAXSAzC2CpZlQV3hhSDkgeM3cbnb0hv7feSIizFpqFbNyOgarqymZIU07HcX5 -c44etbO++GQ/tMI7oCPUb9a5jIt/YqPvIvmPDohGBBgRAgAGBQI5sKJfAAoJELVS -sEN3OQXWr4MAnjpZdSq11IEN34VjwhD+eBMcxjqaAJ4yDvFd8u5ehurCY+KjWSXo -uPPUsA== -=EiNZ ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.jmg;</title> - - <programlisting> -Type bits/keyID Date User ID -pub 1024/3F9951F5 1997/02/11 John-Mark Gurney <gurney_j@efn.org> - Key fingerprint = B7 EC EF F8 AE ED A7 31 96 7A 22 B3 D8 56 36 F4 - John-Mark Gurney <johnmark@gladstone.uoregon.edu> - John-Mark Gurney <jmg@cs.uoregon.edu> - John-Mark Gurney <gurney_j@resnet.uoregon.edu> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzL/8IwAAAEEANuX7fcIa0S5fVATYQCGwgBJo9DxRr0m/QjrP4dJh/JEIjmv -h37FMs9qsMPtyAZWlRSnbVFyQiz5ptFuL1irClW2UHzlLvd5s+pKMfIkJWDTnrvp -0jFebYQt0chZeLcKT9s5sSo9ua+fUumOfaWyubUZPIqmDYqy98Em7wI/mVH1AAUR -tCNKb2huLU1hcmsgR3VybmV5IDxndXJuZXlfakBlZm4ub3JnPokAlQMFEDMBDfTB -Ju8CP5lR9QEBmnsEALAS5dZyQXxsDAROz+yHizsbgV1Ok9vFwE5en7QnOGcSkQX9 -pE7MzzlbpP63toF9zWLF75dbXE5X0yYLoB0pvNi1NXhXqA0YbDeAi1Ed6uBXbomW -MDdm0s+O0Y1NfuS0uKiFiJUDOjdBrgEbnmPZM/77dhr5UbmAtQUHFftaQfY6tDFK -b2huLU1hcmsgR3VybmV5IDxqb2hubWFya0BnbGFkc3RvbmUudW9yZWdvbi5lZHU+ -iQCVAwUQMwF753W7bjh2o/exAQGjjwP+MKiFH9EfOGS7yr5NQ4+vWXuHe1N6fi9N -jJsFfzT/RCM/wo/dNG/xhTgdCoCWRt0gKkv3SLEPYGDPDtC3Nf7HV/66wOiYYnxD -3cmjgpLn5u/Ju0oS5xxNb5Ly8EZnfz967lIHjp/qhbZ9o7kO7Nkb7bUgozNqBaRy -9Yo81fVAtrOJAJUDBRAzARCXwSbvAj+ZUfUBAeUyBACKoIXfYBpsKqmmnTg944Tw -5t8lAFZ8qJz42Fjw+hswC6c+7b87imwaH3AjPnFmsA6f1ES7xDHG8RQleDtKsyik -gHc9Yos/neVqwfrr4zSV1PdNPPpG5uNT/jI1k1M3pH8kwYdKiwaIHQb5+sGUQsO1 -ZoxCdzT7HJq4jJtBGVIRULQlSm9obi1NYXJrIEd1cm5leSA8am1nQGNzLnVvcmVn -b24uZWR1PokAlQMFEDMBEHfBJu8CP5lR9QEBak8D/2V+1pP6zA1dvhRLcO2pGldn -Q/dcVAAtZIZ7AUUap1pKXZF/Tt4gWKMtAHj01xUbwU1fmI6DF1p4AVjDqOxJDnoZ -RD9gv0RiZXdUesXL2UBNHc/7f+amAJgmXNrP/m70ejgzPluniR5hQm76fKYjkxV1 -opRhhchTjhrFndoQ9nvQtC5Kb2huLU1hcmsgR3VybmV5IDxndXJuZXlfakByZXNu -ZXQudW9yZWdvbi5lZHU+iQCVAwUQMwEQWsEm7wI/mVH1AQHxMgP8D7VM+qUo0qGM -uFUKqxoQcDPVKt2W1X6wWTHdj9cxo3oW1tlLEZ24Y2v5v1pzonvseaTjsse134dP -a9qjcwXjs/zxXzHoQs3B9BZB2qXaR4T3YeuCjq2qIXGwsrrY5fkoch4OLg0/FOui -dmNbFjVQkIma2rIRPa8GhXZJtGl+UEk= -=bUtb ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.phk;</title> - - <programlisting> -Poul-Henning Kamp <phk@FreeBSD.org> -Fingerprint = A3 F3 88 28 2F 9B 99 A2 49 F4 E2 FA 5A 78 8B 3E -RSA 1024 0x0358FCBD 1995/08/01 Poul-Henning Kamp <phk@FreeBSD.org> - - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGP 6.5.1i - -mQCNAzAdpMIAAAEEALHDgrFUwhZtb7PbXg3upELoDVEUPFRwnmpJH1rRqyROUGcI -ooVe7u+FQlIs5OsXK8ECs/5Wpe2UrZSzHvjwBYOND5H42YtI5UULZLRCo5bFfTVA -K9Rpo5icfTsYihrzU2nmnycwFMk+jYXyT/ZDYWDP/BM9iLjj0x9/qQgDWPy9AAUR -tCNQb3VsLUhlbm5pbmcgS2FtcCA8cGhrQEZyZWVCU0Qub3JnPokAPwMFEDV/uZj8 -RhrUfjKrKxECNmkAoJkszkn0MRLSjLIQdFSQoAIvXsaoAKDaLAvAv9JBTIhiPHYw -a8YkNTtr6YkAPwMFEDQ+7sYIrLG2o9cqlBECGFIAn1n9YKcO0hJfgVT1sX/lAoS+ -a+0aAKCwrJjWaTvSjDbZtSZ2887P3MnFA4kAdQMFEDAghiMKfXRy8QybzQEBWsQC -/37UbJxWsNURURdw1NDcJf4eJko1ew1au41ytTb792O1HiXTr1nKxa/HXg0+2d59 -HGynOVQfoKtEw2BHakYlNQNk1mznxGxi/4F0cThX+hmJ8/V8wjtm5bQ0hGMeFQjB -4YkAlQMFEDjGXEvKbyuD/AwC1QEBMcwD+wWwOmzXE7wpIEZ1p5KsRiVBQ4F1VEo4 -LviQkE0jUx8/i0/Y+kRpb3sZc+yh84qYA9vrRe8IDqc1a66ZvGUPZOsfiICpJoH4 -ftPz8xMLgyfHZrSR+wICStXNAKok8Oq6a56+Vxjh7wpNDoObN5XfYyAr23yNoPh0 -7pP7dXNRfGKiiQCVAwUQNBDRpnW7bjh2o/exAQG7ggP+NcUV4mCzYx1MM05kz8Vt -8OEjirEBthSypLf5FrXrJ3xZ38CNX4gckTY2iYVaXxStSMIaKdeLDM+ArU58UmtL -06DXBAu8CXRfzgEDwxM/0FCvjDvoj9FuSyBRKtUIg7wwnCXJ2NI+hxYYF5eVWNtn -FfPK4mTsf5Mb7O4jkG4Fw0iJAJUDBRAzBivas1pi61mfMj0BAeIhA/9fG0FYVdoF -GBUsSFE2lLTth1T4uxkaUs5l6E30vhSckUdBA806kx7LaAXtj3loE7Dn/XFLm+VC -nCZEUKe1ayb+Cp3Mrqu6V+vWvkDL3gs7lMALq5w27f3pji+jVPIPVJOdELjroqW+ -a1C0C0UaBeU5FYsv1REvNxEV3WEPTJd31okAlQMFEDF+jX1rWmeNgbKneQEBCrID -/i/ri8/eXUXRJp2fqJqzvrWGTP9Ix1O4vMguah9IILijgpYyOJYkezZKijjVCVmL -X7EwfNXfYkqLAWUa08eov4QfJfJDgfe+Z/3/UoX7RcJoy2AjTBZQzOI9JMkrzFdt -FGYwMr/QXhOdVVpSGeZ/6Hkrs7pd2Z6MNNrRf81ZyJyYiQCVAwUQMXyV5/UVW/uO -VC1dAQFyfAP/SujU+lS2WQuat4O2wZOQ1rswUt6CthG8MOsc7A9kfXnZbaM9Sdxj -54CtAlqR4eJMOYk2kVqAtmCWETRuonJxr5TAJdf7q6kByVYcQEyDZvKJYwyrI9UQ -SelSgczWwiSB01aV9ACaKlEF9iHYvIKBa9HwJu3A9ggW9SYaAHcxHzuJAJUDBRAx -Sx5cH3+pCANY/L0BAY+TA/9YQPISXYaS+5r0I60wCJ+i3a9PC69Zak2ikgTHQi97 -LhpVtEsP3SAYInDw4YMS2oU9w1XxoiLLd9hUpcZlmO8Ip3vNF+E2ZCfR4sNzKarY -5fdo+sxzatGWRPgnHjbm6RHWCw6qJACDD3VpaFjx2XD8QrOTyiObnbHhWBdoEAIy -NokAlQMFEDE5Q6DvYbnpEdWO1QEBsvgD/0c6flBrSWr20oj8eRJ1zl8ZAP/rpV0I -EBvb3ZFsHsJL8QzTsx1typFFghrT7SDBDc52xY90JWAflEiGn9aIL5Q+RHVxjw30 -yDaRPAl9ll82o34GBaWBEw83bsI6Fg2XxDfc2X0KkEutlYAEXjiM95PQS+9PM//l -lDtPvkSxgpiJiQCVAwUQMOavJADy2QnruxtBAQE92wQAsKPq/U4G4ksslOXGaauS -oBk9XO3lB147cSpra1w9ZxTSeo+8dgzNlxnugWDnw1mxauFJBAMgHl74rrlD+Hp0 -Ltb9oOyRl3riPG0TOdfaS3T8w6vw52wOKzUrZ/0pB+2sDHzUqZXBbhOq3OXs1ZMN -e3jh8w62JsLBWry/YMWRMnKJAJUDBRA5r4KrpZDsojuazKUBAWpxA/97mQ6bH6q7 -32rASSvClNbOl+mAaXUG4SwoMhGTpU6ajuh6C13yTNGMv5LY5SBRYD2XqLi5RexM -lYgPOo85zyLa8j8596Wcoga7+5Nn8DYDPxXv7qGE+Ehn4kdnd6nmtN377j5LIIUt -daIKXw2ZDB2GYmmxZS0dq8SwLc0GBb7msw== -=GFOn ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.joe;</title> - - <programlisting> -pub 1024D/E6B15016 2000-10-19 Josef Karthauser <joe@tao.org.uk> -uid Josef Karthauser <joe@FreeBSD.org> -uid Josef Karthauser <joe@uk.FreeBSD.org> -uid Josef Karthauser <joe@pavilion.net> -sub 2048g/1178B692 2000-10-19 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: GnuPG v1.0.3 (FreeBSD) -Comment: For info see http://www.gnupg.org - -mQGiBDnuWJERBAChyOg7jb+Cj5UDqGfChHZDAN5GqF28W0GwrvV0RVWqlGx3pn+S -XzDur7ijNQfj3jAAGgFErCptXWcDz7CLzS2GxddaMAaQcPWP9hDjJtUJ633xwjU6 -H0U0VPdLcWtJJCva1LvKp67ICkM4Wx8OdVHhCQN4akvNkYzdt4AG+s9vFwCg8Ddq -naF901g4VlK1IUqWTxPUtocEAJROiv4o3aIWrXvD9YBxkwIrrvtR8V+QaB6drOer -AU9NC3T2Vkm90lgmUpP+HCmpZt/T2v1t5a4HHjyf2ljD5ANeznAZORA6SowuWRhv -ObmYoN9B+vzHCitVTXLNksJCK9kpEvbS5shzbU6UsecCUTohjCU4po2RrsSSILqE -oXYjA/4/j3Qg/w0RabnS6RJyGDls3FBqS4gyVByaJpH81snvZUbw/y9aT9xdo1YW -gUaLcEW09whi00M50vaMzXJ0KYcWHZzk7LrhOqcIiCAUm5Dfve3dwk0DbgVD6iCb -LRI7NuB1Tm8YyvZRRqG2ZcfYVPZgVm3zj748sRaRSPWfb4wGgbQhSm9zZWYgS2Fy -dGhhdXNlciA8am9lQHRhby5vcmcudWs+iFYEExECABYFAjnuWJEECwoDBAMVAwID -FgIBAheAAAoJEF1SHIzmsVAWQIwAn0w8RM1V3LItIBHR8eshFGY2JEWYAKCEyE24 -oYKcuicRF1rIjYE/2rQiVYinBBABAQARBQI57mETCgZhZHBwcnRtcwAACgkQMaY9 -luwUC4HbZQP8Cb0k/oQeiWFQ8fi9xw8yhpnu7yeDTqelVddiOcsZsLxSwqVCygvE -ywLtzUDeK6ZDiB4gXb9HwiGPiOk5dhtzHqiQOOFkjKoHWC/5GKCGxb27CGxUXt+G -TW5FzdqyzA1mCL2wEao2d8KowXfnVQxO98FceerMMny88w5K2xYPMJiIRgQQEQIA -BgUCOe6GJQAKCRBzh+KSrRDGxHRpAJ9kXxEpFoqpHh6ZCO5vzt8BVig+TgCePRZp -I7ALUJffhFQ3hvHM2LnvFF6IRgQQEQIABgUCOe6GYgAKCRC2JAbmW8FSodhuAKDw -AWzaNDrGEojOI7/GG6kRdP1llQCfcimMK6b+ghk4ZQQsmhqMAbcZySOIRgQQEQIA -BgUCOe6G6wAKCRAgFTHVhF3+3XVKAKCApTk05imwb/TgvUuQJxXaVPlXtQCfd3QR -0Ahvy0y8KAvWekNJimGhLN2JAJUDBRA57onQTVYoIXkFDBEBAbowA/9gwtRKJ34c -Em00fkCO5mVfnZnQ6HUAiepfqKAetBi61IbuPZJ3xymTePq9P1XTeuZt7YgArcJF -2eQhFC3mcfRpyKOCOcDJSon6rlZhNSSwWHlvuLepuE2Pt/D/oPDcDk50aWGBPMxK -k9JJe7F56iCeqQ0pSZbD3KOuvarQaLdQr4hGBBARAgAGBQI57pf1AAoJEIjhex38 -5WVhPMMAnRFflWfwqE/7N0UHF2U1Bw7X+83LAJ46XAcPuhjfrKiDjpGJWPJNX6zY -SYhGBBARAgAGBQI57yLsAAoJEBj1A4AkwngCL0kAn3isV53v+0kmBub2o44wBd0L -0xb4AJ4ktFbTjFNbjfRj0bTn7iZzNx9RubQiSm9zZWYgS2FydGhhdXNlciA8am9l -QEZyZWVCU0Qub3JnPohWBBMRAgAWBQI57l2WBAsKAwQDFQMCAxYCAQIXgAAKCRBd -UhyM5rFQFrqZAKDlnAKtVcJbEhn8IMQaweOMFOtGvACg0CXGhrdEnSf3CIdXIAka -IxXMD4iIRgQQEQIABgUCOe6GJwAKCRBzh+KSrRDGxFrNAJoDGBDBAdgtPu8el+wU -n2+PXPDW4wCg3Gy/gd+64vyV7YdqzFhlAB4wG/6InAQQAQEABgUCOe6H3AAKCRAf -f6kIA1j8vR8hA/9q3WGuLUuMF3H8dzNfqJDGWREa1mjvK7WDkS3762WO9hCfdIIg -em88OZLlCXnlmaGbCVZ3eyEwbV6JQVqzrfrNQeEnVeILdNhuC/5SeNqJNbDpUC1Y -dFA2YBsXO1lGoM/ZfBdDrFRS8Y5RBSPjQ6IG7/pM9Gtm0zI4liywLteIsYhGBBAR -AgAGBQI57obuAAoJECAVMdWEXf7dvXQAniU1sn29A3+Xz5tVz7LMMHmC4xg0AJ46 -TA1BzhXOX5zTFaiaKfY6vwBeSYkAlQMFEDnuidxNVigheQUMEQEBYboD/ikGELEC -nmAfoD6EiNnoChMp2TACRtGIiOXAOQqOIcjWOWCGyDHqOBosR78EHJ0x/9z82RXJ -g815ttqHOueKaPoa8i8fF+3WZwjfEZr6MjGiX8dOuuD11qucy532iZ694FfyL1R4 -9LlWw2os1lMiu3Sy3vZyxN5z+tPPwCrnNOnRiQCVAwUQOe6GCgHbXdKX5jjdAQFO -2wQAl15HhtwPGwzC7RtkJZhdu/Rm3kNGQRtx6I8k81G5NCOp5TOcnkvf0gZFlnls -ZFmYCA4TehVrkThfVYdYyK52dMIoVorSFbMrR3cBE+DJX2IdLB/uxltc1IvLMosh -jwnfPcwS9xFbNvKSbPm7Sv5A9gxkJEVh2TewbjS29MjN/0eIRgQQEQIABgUCOe6X -+QAKCRCI4Xsd/OVlYcOuAKDWloqHTKm80hgbNV6f+pg6+67IjwCeOmwJnY3s5Mkw -wts+n2ugc4faOHaIRgQQEQIABgUCOe8i7wAKCRAY9QOAJMJ4ArajAKDHV0d9rtFi -HwBO5nt/grnF9BjQEACfXWhAVozW0/lZUUPyXNYiHcUgcR60JUpvc2VmIEthcnRo -YXVzZXIgPGpvZUB1ay5GcmVlQlNELm9yZz6IVgQTEQIAFgUCOe5dsAQLCgMEAxUD -AgMWAgECF4AACgkQXVIcjOaxUBaVvACeL56tzrJ95N3oJ64sQVgyo18bEX0An3Gd -CM9mg6dAunhroSuY+73Y6ZGriEYEEBECAAYFAjnuhicACgkQc4fikq0QxsSzVACg -nCcE565FTv9LhGJmmxjNZi4jNzUAnAkJn9QVDkwFp54Vtl921duYZQX5iQCVAwUQ -Oe6KFU1WKCF5BQwRAQEUagQAiJqlq1zf+IrjiffxGzKP1vcCkeaXRiPyBHkS0yCS -y6OBxPhdUsvOzT93qgRUqPGBB4Q7jM7abSuM99gZW9uQN59nwbBFzWRKK/Cz8xHM -lEWIdMZHUXupWUTDBHdHERaj4NaZvE6RXgAdk4saIRT1IFLeWejpaBvLMN8XQXHL -3XGIRgQQEQIABgUCOe6X+QAKCRCI4Xsd/OVlYY8eAJ40vquX/AaE+KslwUBVTBmN -pQo/UwCgvAbcnU4rzYZ+TCBB4ZRUW+MpdhOIRgQQEQIABgUCOe8i7wAKCRAY9QOA -JMJ4ApoRAKC5Wcxx1y8Dr9u4ePt0SA9IhZ22sgCfTOrGFzNJcy5nI2qDz1VoZPVJ -QOu0I0pvc2VmIEthcnRoYXVzZXIgPGpvZUBwYXZpbGlvbi5uZXQ+iFYEExECABYF -AjnuXcMECwoDBAMVAwIDFgIBAheAAAoJEF1SHIzmsVAWrvEAnA25W9/TOnsEaoTm -teZSGg2KAIFvAJ0V7c6OGojBe8ctGclnLH7ICP8lKYhGBBARAgAGBQI57oYnAAoJ -EHOH4pKtEMbEcBIAoMOq/6CtvThjqojHvSEGavUE3sgKAKDUmArUdbawnzF8Q74V -KZ/CmrCmfIhGBBARAgAGBQI57pf5AAoJEIjhex385WVhUPIAoILrCWnWobHn9O7b -zn54Aui/GG6aAJ9W7fRe+mAOsUEmKfT04zKSQmQK84hGBBARAgAGBQI57yLvAAoJ -EBj1A4AkwngCYkoAoOdHEQmEnl5pwQj0f6/boXE/YprVAJ99rpmTV5i/8l3H14O2 -185LvwykibkCDQQ57li6EAgAy6eLPS6a6scj08nvURMX5xkuzKRgMExOdSKtSgGT -95Ekvad+Pg0FsKVMsNPbEJQ4fJpsMS0xh25vON+z3Y3rIJEri/7fXxtPt3pcwcbo -Hm8EcJwyFLs7SW41fT31LrTk1ZEX4bbkHe/SimYnqnmGycJ+wQ6pd7mDxiiqqXjK -Ns4VUzcveB/GD0vS0ZLrXRWrH9mccXWt3kEGWYQ763RTcUxYeJ2cQwEQTjZ4oDjd -TUOqY5Q8d4ijjpSKkZUBE7uxbxQ3R1EpJ/EvBlASJi+YxMAERHUdSL4f/QzU3Qhg -UypDyGl+OhyxlQ1h9wKhuVugJq5eTJsH+AsBRFNqlhnSRwADBQgAjDFwDsZTWbFg -hjW4DhZGOkZ9PjDSpFJuic7lb6kln9OYz7Vy6p7hB60B77ann31MtySKwO/PXtnE -Gcxmzdp3GvXwLyg8OVOBF6p5VjRQD+vvYAv6LQ9dKuIW6wPcAfdjCxKY18Xjypnh -Fql1lRY8Y7wv1M3Lt5PPTusPZaunSQOeD28YF4ww0YZvJOelgd1I1bmZ/f7ZVPvQ -cDNHXTm/xwECfjDHjrJA8Qg15NZeew1tjLoR8naJUDI0CetBbvs0mEUGwjySDzov -1Lz+jZQUJJcQcCx3u4RcE8sneb4jADy2F7LpzMKbmLym59FEK95MlQE+wnkixZcu -ta1JwVq7zIhGBBgRAgAGBQI57li6AAoJEF1SHIzmsVAWGx4AoN0XDe6xdktWsoej -fSw+/aM108z5AJ9GqM/+F/Exr5OnknWCPjFbKSBO4A== -=BvSg ------END PGP PUBLIC KEY BLOCK----- - - -pub 768R/7EBDECB1 1996-12-19 Josef L. Karthauser <joe@pavilion.net> -uid Josef L. Karthauser <joe@tao.org.uk> -uid Josef L. Karthauser <joe@uk.FreeBSD.org> -uid Josef L. Karthauser <joe@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: GnuPG v1.0.3 (FreeBSD) -Comment: For info see http://www.gnupg.org - -mQBtAzK5TJQAAAEDAKlRtbnhuBNWwq+hkYyubUzCYZu60ZFtwdkCgyBurSzTmfMG -1ylVOdwzpgFL8JHRAGhzugRvZqRiCrCl+CvYaeW2+ee3Yw+brl6YEqLMxy0ap2kD -NbpZ7LIO7AMffr3ssQAFEbQmSm9zZWYgTC4gS2FydGhhdXNlciA8am9lQHBhdmls -aW9uLm5ldD6JAJUDBRA3DNxYDu2852ZqdCEBAXrwBACTRn6uz+uFHxi9nj8qdg14 -m3SvBJ58i82IdyhuD5m04/Rgc3Bwk1VDY2eKHuILcgDInd94EePpHTxMvjblfImn -No9yqKYQw+V2zbsa8idTVDb5eNWGdRmVndjY95ZVKuhhIlwqLJELvKKbYZjjSabl -ijn+lvEEl+gO4avcQZnOjIkAlQMFEDRSgYdv0qcS0gZ4vQEBq/cD+gJsogBSFwYl -otle1JGgq1lkIq46uJWS8h61QL9+wnKQ3l19VElXK3/s/HUqBZagKyrF7QSs1dhg -T/RKSr/kdG0dPhLhqESgzii9CS6MgHM8CnmP7oDP78i1yAkVL9bJ/a22Il+YZNlt -r+XOn9EivaFojjHFQy5a+7e/HEXbgtwMiQD2AwUQMxRrf6ZKZnTBjNYdAQENIgcH -RcYYGiOYT0FAqSvAlHPunpPhO+9TBKD5FP307YtUTHdI19Y+LgFT599ond3wfArR -K3ue6D1G6//kbemfLZVxOJ+PRpJ0jIqZQ//7mKAI3VGu4vGO0EGQLkzIfwiVaCwa -8jZh5406CaqE7DkXVypvcVkL3hdqD8o16qht8Y23rjrEUgRYIIWUGftCAHWMZEq3 -NqU/nqzgIv72PMEC3jBjdPld84GOiX9e3XjOSur6uLMRj87e9qce73sYUsGb2/cf -ypx8Hy/FN/FVUKbW4/ddHOeW75vBGgtIwY0R+eDW1wWXiQB1AwUQMrlMlA7sAx9+ -veyxAQFftQL/T64Xc63YXllDIVGw0ZQtM0cdolYzP5OAu2Pvb0iWiJia6SkxePJo -FyNuWEO0obBpeP/QuapnceYUBNiheT4gRccEO1+VjFRuAiZb7+Huwh4FXrRbhJte -3FmOE07jacQ9iEYEEBECAAYFAjnuWWYACgkQXVIcjOaxUBY54QCgi3rAVInCyy/4 -/8BPhXAnQGc/BgYAoOopcjB7kpP5JRgkh+Zfa62GgNuYiQCVAwUQOe5hBzGmPZbs -FAuBAQFf/gP5ARTyrfk36GelJTBPaNFe1oYt6bI5dC/iD7Kaw+GOvOYMSTTOh+iE -2uYefAC5bhjq6e5Z+DoU+TRubEMSHdeS+cR7/skXN3d6E33aDVRXmdKJI9Ek8iO/ -DTOq49Raxv7Uw9Er1OxktMkPiDi6EPgJwt6hKDqQ4Y+g3q0mWMEYlmqJAJUDBRA5 -7mN23EnUDlCYIW8BAfb2BADNmVAV6VW2nGYEod9sgMgxBjByV4Xdkh/eLk5J/fpq -rknIFLD5msy9BEc1a1FjK0VZtCoUy/RPlCk8/bYYTthb9Xg6tNjcoLoYNRW6r6In -o8JkpffH4jccaaXSAzcX91h4Xo/a7sqjCy0FSVl/EpAt8cSw4yAGqFU4yyYgkgii -7IkAlQMFEDnueXIff6kIA1j8vQEBzvoEAJDyZ/zlKtINFF8Lyl3KV1ORYuauJGua -IB0Dv1loZD/cDkQz2gpfL7Jkn+RLXZAzhhgJOeKxUefe/umr1S58fYUc4PKluvu7 -eZxTMZyK0w7wT3fUb5wwubDC2M8OytiyJyaKc7qYEMeJ7YrK1cBbT0mw1o8YMRtr -98K6ZA7TAEfNiQCVAwUQOe8hK9bgof5PvirdAQFwXQP/V+1l21r51eR6lnmU69r9 -nuNhuAn1eQKKKWrFHOkJ7c3UhIItwHYUsO1ytWnbaLsQMBuVaiqe5ZPE+dZefc+L -qXZ40O5WhU73x3BTPDtH4lbe97oTzOUMl7wZdu1U4rzR8tWU2GY6mC3Gh+1Rewxv -NnwXUxvBg2zAzWo1PcfNyaaJAJUDBRA57yFBfEtnbaAOFWMBAfxqBACIZ+hnf7St -MSCPRN1o5uGCnq+Saj5qD5edL3KGIvn3KwzpgYJraZtkQFz44SgzsFM720dLzG72 -Ck5uq2N7Ayu5eUi1/JgcgMnYTNA4wdTeSOC1ZrkOIXXyYgzEc88rs3TIRNJFarwt -sqBJBvT7IBo+Zqk4OzHrnw1Qvla2pVtuKrQkSm9zZWYgTC4gS2FydGhhdXNlciA8 -am9lQHRhby5vcmcudWs+iQB1AwUQOYTMTw7sAx9+veyxAQFJwAL/Xk/6bm1NsXcv -NKgClM3rVeF+Zl5M+hffa/JL4GXSrwCRTrAcRzDFEmT2hEdKVdsq4WsFTQFxpAgT -qc6J00W3WiZwBZPD1hMzE3/PJiB1ZvTuNdyAxckvpwoAHA1BmciaiEYEEBECAAYF -AjnuWXEACgkQXVIcjOaxUBZsxgCg2eyZMcbTrO39+2p+KN1XQAFlKvwAoJUuBkZ5 -7DTARF/YVKlyDo0kiZ0ViQCVAwUQOe6KnE1WKCF5BQwRAQGp+AQAqFXMM9pamu4Y -f3GzaKWZe9vKzswWu2P1H+5I9+trNTZv/xNO2V6BbKaMw0nCrBiLja3M84KfVGBs -85nu8AuV5tDDaj/elGpWzEkm2LzmzHLh8FqmatUr0po2UFc+JohX69dqFyXXYBa0 -wK5fic6rW7U2BFS/tbwx0lmUhMnHG/eJAJUDBRA57yEw1uCh/k++Kt0BAaRnA/92 -x+Ew+zeCaS2tTDMEYDTw9VkburcR2S/zXBzFh12oHb+1WjhTcDajhCumgof+ZKwf -onQU9nN0nFy8YOGpmTsBs9TNOFq9XyJg1Lf1HGQ2KV7GqIas2OGtcnOLwyrQwET5 -kNHE3Y/OlekXBMBbUQzB9bUoX+OY/izKP/aWAxe+0okAlQMFEDnvIUR8S2dtoA4V -YwEBNnMD/0B0sW3i3Obs4QOqoTxvoRYulGRtxpvEntdWycgHgnY0qPHhNZ4s1Hhw -vYG/1Tx6YDWjEQyptdKQxZq5xZt/Yw/gD9gY6Y3x4PRlqp4kTcQg7YMDd/c7OdQ+ -4aBpQvkQ37Ib7catx5THnW4/mxxpvj4Rn3sR4zytHVTk2Frl2eg0tChKb3NlZiBM -LiBLYXJ0aGF1c2VyIDxqb2VAdWsuRnJlZUJTRC5vcmc+iQB1AwUQOYTMHQ7sAx9+ -veyxAQHwdAL8DbjMvucetIb+3yjrRhG/EfzxQKRqKzu5isvGckc9K4AA0Xwl9TYg -9v1QKsCqf8q8GOxyhEhGob5O+4USTcETgkerUjsMYK5uCEHQuGRZ9pYCH4A2qL3n -8/rhcX6qxhgMiEYEEBECAAYFAjnuWXEACgkQXVIcjOaxUBZZGgCgqIsXrbcFqkyf -Gn3Nw57oTwFflZwAnRGZwnHMFUJocLcSpAp76a8+QQc4iQCVAwUQOe6Kvk1WKCF5 -BQwRAQG/JgP+NbjceEgGYm89CE/FiPuq/EWD6m+gzJCWvVqmfPmX8PTlbaA+Jlzl -cI7vUVKkvDEqnvVbnNgtpLMC6L2tonrB2vx47odmCLm7H8L24XpHOKyNiimm6fKB -6r9z9mEWf2WRueMnjAGouNJUh0oGaS8RxT+MKzEFIDKShcMgaWkvlfGJAJUDBRA5 -7yEw1uCh/k++Kt0BAQ+TBACfZQI5vWUQ2S8dZBauOqvuF+k4VMl3bvr2bXAMm7Th -uBJc50BloTirtBo2dt+zozgm5oELP3jHXwGXIJ3ODGPIBGVLdQLU4Aer35ziKUO1 -DL/GdE2yCdHX6UABL6De/nz3vILhjf1HcATcaUl+Wl3579Qax4zYU0KTccJVQND3 -MokAlQMFEDnvIUR8S2dtoA4VYwEB290EAJDiYx4ODYvElwbsS72OBzRkGTkbs8pU -Cd+LHI4REUR63R0FpOdnjPPAesX4DeeoRhQ/Wwhp5Yaakvba3VPNRxIM+qOskPnN -iVhBY/7EOZYcjWsnvhdwZQfrfOfBLQyVpXLFWmy9rzihYegOHXNyUrqX0CGu9ido -8tkOscMHQ8Y/tCVKb3NlZiBMLiBLYXJ0aGF1c2VyIDxqb2VARnJlZUJTRC5vcmc+ -iQB1AwUQOYTL+w7sAx9+veyxAQHCygMAkQ1Itu9AEwmlYXbxEi9HCbgkZbBp73jc -/qFyWmxa2D9F+a0hYksmN6RTYAmayenD4K88rnWM4OI4L3F3O1B92W5vCmKD4MvG -ZyWGXxz8xk6SLNFC7NBIz74C/fB/QrgDiEYEEBECAAYFAjnuWXEACgkQXVIcjOax -UBbA+QCgvWou6z02+Va9nlYsHgxjrHp6T9kAoMF95mQhMNA+uq9F/BAHa52MJIgg -iQCVAwUQOe6Ktk1WKCF5BQwRAQFEFQP+Ke1kFqP7obQs4s3w2SZAhGTfUROcOISu -QJ7s2kpkjQkA5pZOhJiCHAyDFYTQv6LKtjosIIb84oKE228QJ+C8ow/ds8fSlh/F -G2GYFLvwwluZhCN6yOeshF034v1OiUD73K01m/O5QD/MqPVj8/SATHhCCZw+lC2o -nTxxPnRdnvyJAJUDBRA57yEw1uCh/k++Kt0BAUkSA/9bXfJrcrjjkjra8ohCZ4qa -nL2LjlMfcOEcpO36zdugmQU1+53/iw4FtKHgrZgZPNZjlx5jWldKrBEbFM3fa9E4 -03MWe9vNFLagKjSzFQlZojqLtHCO4pasGomBAn4kDM/W2cZJvkpl8JA+qLif7SU8 -HaFdlUg1fbF/9VeYXuhh/IkAlQMFEDnvIUR8S2dtoA4VYwEB3hED/0j1PKQNfRlV -rPioEGF0uX95ZUEkjklKRehITBbXBkq1cQ3b1s/dIunzvs/BUbQdHpkLB1P57Xfa -e6JcokvLH3ufk37d9ubmBkJHgdxSv64y58lp9YqUPe9gMbctN1SeBCOdQufz5sJ7 -XDiq/TqRPR2PHPLESCPhc4j5XoShg37+tA5qb2VAdGFvLm9yZy51a4kAdQMFEDgP -y5gO7AMffr3ssQEBYGsC/iIslOxLXMgz9BSw1ndflqYOImPtn4OQJAG+eyZInVKf -ZDhyEHtO6ID7zRNx+0whfAgEU760e8V5rEFea9U0/qY7QneanDRGI+rP81V/fnP3 -wdZBCGXDNMCM6ofcuTP6MYkAlQMFEDnuimtNVigheQUMEQEBgLIEALr7UlhPKziB -hml1nZ3PuovK5B8OuO655YTpAiOD8JwHEUTXsVl46rX0YBDZB7EpvuaNfzbA7d5Y -4RwrVGiF1xwLMkekPxa5j1XswmlXCDfpVfNfPYaRNobhMnXaPeGI9unkJBp1BsJS -RPI0J3A3W/u/g2wUl+7B+ykInMOgG1m5iQCVAwUQOe8hMNbgof5PvirdAQF5egP7 -B76wggcC7IMvmTFEtt7f1v9W0XaA2fP2gmznSlh8FUkq6k0TgOx0uk1lM2DaQXWB -7quXzwzpBKnesniCg/Ve4gyCvWOCQKtYR47y+lSzHvXrIW+7xRX6n1CjvpCdChlo -3PrwUdWi4Z2gq5GElu22NvvHfssnB13UnBNAmhSIB1KJAJUDBRA57yFEfEtnbaAO -FWMBAaivA/95fj5ScpPKEUEpwIwgX8g0Gx7BEYO6r+atQhf2pGbPHTKq1IcGqioD -YD0ac2Sn4eBqsjxzTArnZViG0lITyoxegfYS3Tz6MADdpX5vGzWaa5Rs1IXjtjuv -4hINpCySWRxAlJPZXdz7rwFB+oCy1IzBFf4PujCGbWb2f2v6qKOIkbQSam9lQHVr -LmZyZWVic2Qub3JniQB1AwUQOA/Lgg7sAx9+veyxAQHeXgL8DJQ1xeeFLQOrg4vI -5nfQOjPJqaZ4xpPv1k5wIjPRElGj7QACZVX5L/bEzhK+7fggSXxBb4cmEhiDOIFO -BR6HWL/RnMimoGtC53OHKRrA43/eqB/saCbTfN4+KAypw1WaiQCVAwUQOe6KjE1W -KCF5BQwRAQEmMwQApmdAtX/o4jD+RqGr3YgzI8HiGt3GCrDjvZUnC4zKG6YvEvbH -Xel57TmiIQ6Fi3WhOupGa/jcosB+XJ7vchrsCvB/LfLY4c6DtlFdXnQn0loU+WjL -PjAUI4ZSSy2Wvgsck/9fofJJyUw/QWG+LlbCmBbGXed7Y8CwxLS6HvthNGWJAJUD -BRA57yEw1uCh/k++Kt0BAYGdA/4jp6QvLYigWfH+ZQQ07oZoa1bIRksCbiZBNTKH -315qV26M8FGj7+7G1lqlcbqdLqRUeNLFBiTHuycOUD+zN48dxTkspT89+XfajMFY -yEkdND4C+NUAaBdspjiCsA2Pywhg5K2Nb2mGbqhRyafdl/lDx+IoJ7tL9u62GsdK -+wpMrYkAlQMFEDnvIUR8S2dtoA4VYwEBvpYD/02+ANOeYrF3nRr32KOxxsJkXZQ6 -7bjQLaOHqubnWbG1+OSOcJ6+it+l/uotFghzsvKk/qYG57n23yB526ePyTF27eYP -mE30qUt/msLiJ2C8OoWs7UUqWp9GyZBKNt0ETc9qD9Ns2Qd8a4AEePJfsSC5v2rs -SpVIsgagGHpZqMKqtA9qb2VARnJlZUJTRC5vcmeJAHUDBRA4D8tRDuwDH3697LEB -AZU6Av0e8n+hesovDEknox3JKhC1L33jXu0nOQZ/2Yz6jY1icghgy/L2KO57+T2Y -BV6DGpk4IlY9jZJRRKtiKCHSMahng7whIHNSugWqzLNanK+YPfXC2CsUI02w1srj -FcDurBiJAJUDBRA57ofYH3+pCANY/L0BAR+mBACPZUQxKJbjtlMSbJ5+Ox09fD3+ -oUR4k5mBMyFb0lQhTJ7DW+O7h//xyYyPZA3AEe356zb94J9OPjRW4qxWSzgMlckF -CVFa8Ru0/TivE0ArHJbhQnMtrFYbQar5t2RNrlq+B8UqhmA5D00qfdM9/62oxBmA -f0g8rbiWGEL5XmbssIkAlQMFEDnuinhNVigheQUMEQEBOPIEAKGnDr7tgz3kuRaU -8IAglUDXaRPqIpsr1UFEwfg9n6PXXbU/vRn2549zaApsHTTJnYZ2ENH4hv9Og5c1 -t9Qr+DEV7ht+8Z0ykoxyFJb9YDEO9W2Y0WTglYMaqBD3NDdo4Mamuj+RtsVxGh0Z -Gm/G7Wu+cTtnwCoSbQ/XEpX2Re5kiQCVAwUQOe8hMNbgof5PvirdAQEUwQQAlMnI -YZPTtjsl+IUGHj/Faay52iUxRxeyWenCp7VYKj6SBgnKO4STveUhIlqVM1iRuf6h -tmSTXF1kztXzPGdTqZig6x7WOLAYSqsEY5DdM1W90+UYTnf0pbkQ1pAJ/2kfd1uo -4W3zpzgQZK9FFsW938C4VqzxBS8bneYmq4JAa1OJAJUDBRA57yFEfEtnbaAOFWMB -AVcxA/4i5j7aqDIkboVaD473bQKYs8GB4riBx3VGEHHfASe7Bracv0jawdPwIUhA -VpOT5hbtJH69tsPUUXphtspcqCrJ8xObA5RuWdBTMxq12+dYYKBoop/0F6PaOSh1 -4KVX8m0J9/iGHV+J5QZSKPpBEAAwwK1fJQzBw5DHW8cxxE3OdQ== -=dREe ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.bmah;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/23EC263D 1997/03/12 Bruce A. Mah <bmah@cisco.com> - Bruce A. Mah <bmah@freebsd.org> - Bruce A. Mah <bmah@employees.org> - Bruce A. Mah <bmah@ca.sandia.gov> - Bruce A. Mah <bmah@ieee.org> - Bruce A. Mah <bmah@acm.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAzMl/sEAAAEEAJbQArJB1mbsGAc0eiv6XmoBPdjXDy9wWYbFdTSKcR88iZUB -o/lie1eIyfqOFp/bbOVuCuhuCB1L/y9iS1x+rcmQgMbzelF9EbyyAoIvD3kPy5wa -/dgE7L8fAHzHzmLP8uHccXu1eGMmY93of2s7BKvrboWjVCUbaqjOOi0j7CY9AAUR -tCFCcnVjZSBBLiBNYWggPGJtYWhAY2Euc2FuZGlhLmdvdj6JAJUDBRAzJf79qM46 -LSPsJj0BAbKLA/9ei7MJSASsyBm8AyC4xLSYI/ftiYBPeuHH3f4t6Hb4Uu99iZRx -+TG88DMg3ZHQZNMrvn+iMojWlvPlExFbpb0FRDX1JksB1gaadsEH6b22Tv2Uc6bd -6iYe4rav6JR5ZnDtgCAzNiaeTEZc/Tn47vM3KDqnz6gUl+zTN+8/ujHp6YkAVQMF -EDMl/4Q8L1TZGfd8EQEB9YoB/36khd19cZLdhLcaGDnbbPqRIjXC+Ha0LD9QEiK8 -p4TzPhQu/QIQTlKMOm+dMUZfabiJG07QUM7/aoDFF6VoJHyJANUDBRAzJf9iWGPT -gxP/0IkBAR89BgDSitVdHQvjjV5UtbaJ34CYNz+KB2r7/08U5yeN5ZSQiqAW6PiS -SXujzHnB/kxUlG93bCq75ljwvozSomSE/n+1QKM5j+WNB8judbIuesAlKVlnej05 -X2hLXfsAcJuGmG9jwlchd5uhSEBnrhpQEQh+44BKdSc5Jp/rtUeHwuu+rqvNECR8 -MSIpY3IFREANAv8TVqVBxbEHGjyKR1f3iwo+KGFgcNcE9w7eWCW9FOTOe1iI550/ -r/CounwRTVarkVWJAJUDBRA0BgS1YDZyE/6Ll60BAUY3A/9bVICm3lamaA/hkvL9 -mMfIlgqJVG1iv6ghiTgJJN9eRSNStPB8ho4sfekYmsJOj8Dsnmgw3Z876TiAeeG8 -KBDYrB2CeirciqgEvki1tof36NVrTlNfyjMe7DuRdIGwlMsysCTGQ91sjdTvQ1gW -qCOCMPq2hbUiy3O1H2lSAFWZN4kAlQMFEDNqQB+G+HorH0Oa6QEB6xsD/jlw33WI -8LNxVgySQ9IEX7F0+cFsto1iTnxc5xRTKqcNfD3h1N89noVJHZa+4Y0/EqgexPda -ADARba+e0bomsOKaGuK4thiO/UVKf+que9JmNwIW+bmvbfwQhRwaT5tXHGJDbP8U -DOhIIbfd3N6VpxmcH6azvvCBAhRpb5vW8VXxiQCVAwUQNRn9lvRZcafORvxJAQF5 -bgQAmpEu9wcVqJa+P1I6iSivnY0nJJDBiXTHnGep9zwdCODRa7rZwgZptqn4naXr -rK/jAr6Vdj73b5TbwLtLiWR/MwortPFp80M+6Ff15lsO6viynMWgLFSBli2WcxIU -pnjlnt8sLs1opDV+nwoSlFCeXGMbPSal3FOA7oIdmDBbG1CJAJUDBRA57prdfEtn -baAOFWMBAc8zBACltXDpn23WLpy6jp37uZuijhGt2B8wksTv8J9ZRaUbEbpRwNe8 -v0RsxqQ7NbwFUIMeVdswnF6smXPpp55SOHOa+TKOnjdJwk6jZWewRTRV43ZQ+F5I -Vt1rGWB4zXu9/umAWXvVy4cVcfvOLoYYvMucNHgawWby3qiEwsWMuukmY4kAlQMF -EDnumuHW4KH+T74q3QEBcQ4D+gK7LMHp/gktEuOFhqKHdLxbocqyKL6Nm/R1lKP/ -5iJ60IWCBhz4OV4xU6Vm6T+JcMYnewdfsxuxbQndN5lhzQCFwEVrkj5/ibsCqAiD -v3Z4IOIVWOwESCM5nJVleieNZ8D8Y33UICCh/kqLzDF97PpD+kGROWi1sSNXlQIr -VdQttBxCcnVjZSBBLiBNYWggPGJtYWhAaWVlZS5vcmc+iQCVAwUQNTUXEKjOOi0j -7CY9AQGGuQP/fDgRCZ0Nq7P+IkNq1cxxHEjYJoIXbiESK5gtdWelJuxVDaZ3XbL4 -/yoSIN5ZnVHZMi04P3Khgqequjwr3/rae/a4MmVQdtNrCFMSY+8d/l8bXkG8tuky -5b+Qd9ZOBVw8zbq3xB1o89qf0D07bTX2EC1glvrU3g6VV300BaHpvimJAJUDBRA5 -7prdfEtnbaAOFWMBAZnhBADMxh5KVEBKn5L5ZOuXJdi1EIAk0L8bq7xbxUZ1MKTD -oWlfc1xxBxs3xfMIJFjAv5CRzrGg8y3EUBRLgaN6KzMbvmA8FQ77PIM3x/lc3jHa -nIQPlWWdCSq6WZEFtq/rOFi8WhATlCBPehwMV7gNEDh4bIhG/5jY0cA2kmfJqo06 -TokAlQMFEDnumuHW4KH+T74q3QEBTj8D/i5VjPmPkOz7cKEaK2NbUnTM7bKvyKWX -7qprmjkmeunVA4LY3M68SG1NcMmEWbM4p4yl5xDvR3r7WChPKZE/5Kzvvzo76V6L -CSqy4L9pwFlAw9xZOjhRtJTrEE2HsoDeN2nvWrPpeXJtGCpZ+d9WTg4I6mxfyrp9 -qK9Mj6XJKc0FtBtCcnVjZSBBLiBNYWggPGJtYWhAYWNtLm9yZz6JAJUDBRA1NRbM -qM46LSPsJj0BAQ3oA/9Bxqn1Kll1R6+bRbz2VKOCijC8iooYriFF1MBC38PsvBXN -epnXsbAkRrvwzAiY7f+aaxYOLbyG3VOTtEwGlQ8WSfc4BcHBmC8CK3G+jXn8Hk4Z -iZQ0s+khhAlIbr0Wpxvk5Prazzv417dBCIHzk0dxaDJ5dolvxA9NK2po/oTDzYkA -lQMFEDnumt58S2dtoA4VYwEBgtoD/jAqZt89XHmtWtMzJIOft9z8dXyvXXwmkuOx -91P2egetX69Ru3XzqPays/uvdFkaVgo09nHRLPGXPQ0GbgUuc8mPa0H3jn/OA+Tn -KxeB9rKY2fPr6vccP6OSeOk4nbHqPqfz7/U/edbHZ88kNu4iqiH+dDB0L7QNGK9p -l8Zpd5TOiQCVAwUQOe6a4dbgof5PvirdAQGDDgP/SdujS5XMRbqKMe41f5P0TMAm -VeGplK1mdX4WRmB+wvdV0ddIiEgSQIklmNM5nIwYzRGNLZrRBQNDArOO4826Amvu -lntP6+LmN+vl+lmOA6kEbVYFnADkNGP3jVmwJ/ni4luKDWevMHpxfHTGoKKaKA9P -A4WaT+49RRX1RSGkWU+0HUJydWNlIEEuIE1haCA8Ym1haEBjaXNjby5jb20+iQCV -AwUQOUVroKjOOi0j7CY9AQHdzAQAiq+kDC2WEAG3gglnEIG0oIp292a2qhrDIu1P -d+xUxXoPs8OzqHe1D4RaJiEhDMmQ1t6kJbUdzTKENzjyT84KbaHBgYujgcLsGqmx -nVDxkVC6YlTXOngI4y96sw9k2HRELWTEGfAUFCPmAQOWH/ftDEPCvAZHXrTJaRSr -nkK80NuJAJUDBRA57prdfEtnbaAOFWMBASUzA/47C9vbfPB4sqLpT+PSZ6cOkPXp -Wn4ddvYC7iTCE8Jn9E4V4v86wUqWScXK00OO6suFERj8b8gFsWhR+ud1a8lTMuKt -lmdJw6S2XWFadTQCDUPoOul4WlUwEbhWSohSoTu/FFJ8AMgI6q2Umeo/MANga69L -SXnYuG31GxEZPEknkokAlQMFEDnumuDW4KH+T74q3QEBXw8D/j4k+AzvQg9rY3Pm -R2qUtjPm2JBw1206J3XCf7CYwmhuMKiLC3EMqfwu7U43+sD1xgIjOV5Y5VFz6zQ/ -cZ/DkRexCIJYe6hXhqx+VVBRCRUsQnCDkrCr/sX14EsgQoFluIKfuCstxtLe6F/g -OCAoHM0QG34Z2IrThLWSo/oIhNBstCFCcnVjZSBBLiBNYWggPGJtYWhAZW1wbG95 -ZWVzLm9yZz6JAJUDBRA5RWu3qM46LSPsJj0BAQrYBACUnUQn0t6tnxAJMQxgje/L -kNGkZOzGNMazfrFPe8+iDCq9nnJ7zkh2OtSNTiS/VJqJjT/2iDjCxWG4Cqn4eBUD -1d8GW1klKeK3yUIFlfAsMAfQshhPQ47865UlHWvuePLS/0L2rLofu/++7reTzYW+ -4mnzeXfj+UKAqr5LlzlFxIkAlQMFEDnumt18S2dtoA4VYwEBnGYEAMc2YVJk8YsW -RJjU9zKtsbfMabifvNUYvvkIi42du1t+brnCXf5aFnFjAAO3sGbEoTRCEbT8SRPU -hbk76R++bG02XmCYepWX5iS3I0LUzVpqas1t0H/luc4mUgOYDUhsPWuBtNmYuuxD -uMSCgL1ZUPb+S5ZLmYMk5hxpKQEEO94FiQCVAwUQOe6a4dbgof5PvirdAQHZXwP+ -INhyMrT6qLG6+fjYWZ3hu9nvXO11MtPtNObo7VqIERSRqccvhQO1ut04VXb5Na+h -AO8kTnqS6+43TZUWtAkKLmcZakgb7juFXxnM/BJP+UmMr08LMkB5Yf3VNfrdthbt -GyFh4tY7kYJFa+1K7CngPvRoBbd1iHO419O6MiLusoa0H0JydWNlIEEuIE1haCA8 -Ym1haEBmcmVlYnNkLm9yZz6JAJUDBRA5sD/kqM46LSPsJj0BAaWJA/9kzr2n26NW -NE2PscqmABhyXXDZptY7t6NRAc6yXgPnbXs5AlAkiL+P0FLs1P9MMnw7PCd2TAXd -MYLhPecx1dWJAiaRNmoJBaPknnr4rqNKM45XbPfkJAvvSVGNi52VHcmrnmFdSX6L -hUwJzVha6TT4Vel5y1DEPYIUK3FJllTBQYkAlQMFEDnumt18S2dtoA4VYwEBNh8D -/Rdov1S+koATxQAb/8uLK8rYnmDL3PfoAhogrpQgz+9G8O5mwJtzoHJVYGGVEzTV -3L/okFn6UlX4Hms0RR2JYlcwaL+D4aZKV6vhgVh23yh3xaV+wPwzHqtjPxyWKapO -g153Fn/UquFaX62DzzWcRxtd3Fi9tiGtdyOVmQQlaV4qiQCVAwUQOe6a4dbgof5P -virdAQH7XQP+JI0HzuV4ycNw2rnLU4iNrINsC4ur5hTW48CQcX8/HFkTuygzFKVn -AlrKEytdfJPaFMt6UAqUPB+NPJ6fwtJkU0cNsjCsZIGBh8AumyT560BWYm3iIac4 -Zn/9dKslg+SRJZU0T/A+Iip+3oFz8cl7BrkPgI1mLvUTOuBj4Kre/7k= -=aSn9 ------END PGP PUBLIC KEY BLOCK----- - -Type Bits KeyID Created Expires Algorithm Use -sec+ 1024 0x5BA052C3 1997-12-08 ---------- DSS Sign & Encrypt -f20 Fingerprint20 = F829 B805 207D 14C7 7197 7832 D8CA 3171 5BA0 52C3 -sub 2048 0xB4E60EA1 1997-12-08 ---------- Diffie-Hellman -f20 Fingerprint20 = EF87 710B A12A 93F0 3529 E578 173D A3CD B4E6 0EA1 -uid Bruce A. Mah <bmah@ca.sandia.gov> -uid Bruce A. Mah <bmah@acm.org> -uid Bruce A. Mah <bmah@ieee.org> -uid Bruce A. Mah <bmah@cisco.com> -uid Bruce A. Mah <bmah@employees.org> -uid Bruce A. Mah <bmah@freebsd.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQGiBDSMdS0RBADQE42S0MDRcjiuM4mPH4NL2m60OMHgq3mYuIzrNkRE4jSzZJiG -8jBMl5VysnTkdvL61gH4aihIqioULOUq3L9XEtlrLbx1HDXEEdAdhARzqPapD4x2 -FbHpjb0wjxQ7RmXXvLHDlPa8x8K48BJjZ+9WhPs6TKu78+I+9cqZ0u1KKQCg/2ls -GAGht29FiOtHrHFVMKl3WXMD/R6wl33Xsb7mwFROBWoYxExqSAZ9xeI5KUtQ5f2U -eYSbUfxCTkcBIImjf6UhtjLTs6Rc0ouYLHOHu7wxVVzA0x3UpcEWUkNXWsy4PO+S -j7PdzKi52BzR2LY62DoBTUARAaIsvp3fV126NPBHR2Isflo2OlEvwKGJ40IJMLGN -d3xBA/43QdXUcxa/FFAeCroYr/BkWPYz7Oh1HFBTa9xxrKL5sLDJChp/yLFoVhsG -0t4w595cbD8L1n1PckcaKVK2Y8vjafJKL5k5Ea/CnF0kO7+Q3RaydqzOcS2yP0n2 -ZLQ+sorNz1huY6hrJemH9SjWnYKg4xbxfQzRBcfRxGQv3usvC7QhQnJ1Y2UgQS4g -TWFoIDxibWFoQGNhLnNhbmRpYS5nb3Y+iQBLBBARAgALBQI0jHUtBAsDAQIACgkQ -2MoxcVugUsPDfwCdE4eVXsgKeXGph2UjRJ08bcm07KoAn3wjzXJ3OAugV3xd/P16 -L6EvLE6QiQCVAwUQNI10l6jOOi0j7CY9AQHawAP9Hv0fwpPbQC90t8sreFT+ObRl -zYSQnOHV+XYcqi0DJ+nbZYB+60CzPxHkchhfqLi0zsNYbqlfyTCJabMS8d3n4aVR -ke+eMpD8UwsBGcfOg+3H9aFfsNDF9qC46eaN2ZEbMpsMaPzEMvdvzIWY5pF1uziJ -s+hqPNpndOv9bg9mr+qJAEYEEBECAAYFAjeDt00ACgkQITxeNPGCC1UxUgCg1lWZ -vk7ci99tGLN8YwlkmNHWfGQAoOvmztFkBb4Joy4KcMOM3/QPedw0iQA/AwUQN4US -PK+iAUnWOX+nEQK/RQCg/Q34D+y74SwbsDKq1PFzRKRIbUwAniLwxuIjOT4+Jx/6 -GbUf6BfFafUqiQA/AwUQN9n/OWlM93/mX/l7EQLDZQCfaV51kpxPgnf6Phq5748s -gmarZroAn3NskDMAtcSHqTyYfFu7SNOxgWIdiQBGBBARAgAGBQI57ofmAAoJECAV -MdWEXf7doVsAnR6nzyVm9sFceFaDLaHeUUbUPbRdAJ9nnNWEsxbnqeAwenSNtyz9 -OL6EOIkAPwMFEDnzsYN3zinFj6EuIBECrjMAnRIxFEDvi0bBwYtYbADEFulWY8zn -AKCwfvI7YsVOkMDtk4nEuWwK6bKCzIkARgQQEQIABgUCOe6NVQAKCRCI4Xsd/OVl -YfzcAJ90xj1zsCx/77XSTRhjOth7YuT55ACfQJZMfNge3GcyXVSRAKsP4TQ9zYqJ -AEYEEBECAAYFAjnujVoACgkQGPUDgCTCeAL1GQCdH87/riGhtvgx0QqEmCOmoTn7 -46MAoIYOCTUpM3bHKXjC2+ategzNcCPftBtCcnVjZSBBLiBNYWggPGJtYWhAYWNt -Lm9yZz6JAEsEEBECAAsFAjd7oEIECwMBAgAKCRDYyjFxW6BSw7j+AJ9+VDcZ4K6n -Ic+Ap8WKSTMXXKFvAwCfQOokhn2SUd1xYY/PZxYcDs9I8YKJAEYEEBECAAYFAjnu -jVYACgkQiOF7HfzlZWFVvwCg1TprYy84hGQ0cYsnopjkMtnENKQAn32dSqKRg4zo -tR8It3Yh+XUpjjsDiQBGBBARAgAGBQI57o1dAAoJEBj1A4AkwngCSKcAoMilohdk -KkIrvKxf09b7f+0vuc1rAKCeDKdjlNY/AR1nVp5096/oz/f4ebQcQnJ1Y2UgQS4g -TWFoIDxibWFoQGllZWUub3JnPokASwQQEQIACwUCN3ugVwQLAwECAAoJENjKMXFb -oFLD2YsAn2OXLa+VlHLnWVraRVjB4vdjUMPoAJ0emVwKCho+tJ4DueuSTSx35kr6 -RYkARgQQEQIABgUCOe6NVgAKCRCI4Xsd/OVlYYxFAKCf6zxIGbP2FJ3w55jBiyMX -RYc9pgCfRCnEPNt967dKXbeMb0V84i7yxumJAEYEEBECAAYFAjnujV0ACgkQGPUD -gCTCeALFVgCeOGHzQYS8qwb2R1Rv92gkTynYEhsAoPVrNmjEyL6kgfaGzimUvujK -p/j3tB1CcnVjZSBBLiBNYWggPGJtYWhAY2lzY28uY29tPokAVgQTEQIAFgUCOUVo -NwQLCgQDAxUDAgMWAgECF4AACgkQ2MoxcVugUsMScgCg0OaBootiOUwm8MtGV2lf -Pjbq+WAAoPVcDuDNno9T5lkBIj/Ko7crIwjViQBGBBARAgAGBQI57o1WAAoJEIjh -ex385WVhuYEAn0KTZ+sr6nbvOM8wQbLfpeoYWWjkAJ9kiU8uESWXramTTKYKEHyR -fjEVG4kARgQQEQIABgUCOe6NXQAKCRAY9QOAJMJ4AjlXAKCZLs8uBMTSG3Dnpw7p -ZLVPD8yhdgCeIFoHT6HrRiq3b715bc5GZhhFlhC0IUJydWNlIEEuIE1haCA8Ym1h -aEBlbXBsb3llZXMub3JnPokAVgQTEQIAFgUCOUVoWgQLCgQDAxUDAgMWAgECF4AA -CgkQ2MoxcVugUsMR9ACffGTZ5+6qgLC0RFqatxkJ5YwqwgIAoKgsCGMJsAIpxhNb -XG5pelXhrQA9iQBGBBARAgAGBQI57o1WAAoJEIjhex385WVhNHUAn1SHRpqXn1uq -q/EzqxDVzN/R6JaHAJoC+Q3Rv52FH1FD+i60ubtPwNgbxIkARgQQEQIABgUCOe6N -XQAKCRAY9QOAJMJ4AqaaAJ49VuRD0CycI76yqRns1hx0rktP1QCg1TdP2OAy+dbm -AMpNokTLzjvuroW0H0JydWNlIEEuIE1haCA8Ym1haEBmcmVlYnNkLm9yZz6JAEoE -EBECAAsFAjmwMzUECwoEAwAKCRDYyjFxW6BSw5rBAJi1vpq8RU0pn43HT4VJWybp -BuTdAKDXv2O9eGilbPVRjmEgOclE3B09JokARgQQEQIABgUCOe6H6AAKCRAgFTHV -hF3+3TefAJ4qgtByxD6QehEnn8kCqUVZaU3AvgCgiMtlhatZQJLGAdf3WDFOfsM8 -YpGJAEYEEBECAAYFAjnujVYACgkQiOF7HfzlZWH2gQCgqZAhZ/6HGYl/siyRgDNd -QRSLXBEAnjMVjCjTh4pXuxsMdc8dHXel9lbRiQBGBBARAgAGBQI57o1dAAoJEBj1 -A4AkwngCtb4AoKY5S5sCQCbn19SraaSTPVBmImyfAJ9fG/FSYHCMNt194t9uixew -oBCLrLkCDQQ0jHUuEAgA9kJXtwh/CBdyorrWqULzBej5UxE5T7bxbrlLOCDaAadW -oxTpj0BV89AHxstDqZSt90xkhkn4DIO9ZekX1KHTUPj1WV/cdlJPPT2N286Z4VeS -Wc39uK50T8X8dryDxUcwYc58yWb/Ffm7/ZFexwGq01uejaClcjrUGvC/RgBYK+X0 -iP1YTknbzSC0neSRBzZrM2w4DUUdD3yIsxx8Wy2O9vPJI8BD8KVbGI2Ou1WMuF04 -0zT9fBdXQ6MdGGzeMyEstSr/POGxKUAYEY18hKcKctaGxAMZyAcpesqVDNmWn6vQ -ClCbAkbTCD1mpF1Bn5x8vYlLIhkmuquiXsNV6TILOwACAgf6A0oIHx7GA/Wg+7Xy -+rZVKyrOQ+bxzDQbpNNwDBP5mZ4NoG6tgX9LLpLkihRlmL76JsNHhQxaSHOU9mjm -uAZgNVlYRE+O/fTIlLkRrBkgn0colEMy0EFx8/UsTPu8j/RBURcrAD+ony+vXyl9 -cb2HEfpeUWhGQC/WdIhPwRKCK2fIZ75Szjkd4tgD9+yYUEfGCbpw7bRwqHRDEdVy -7qx7nHcTH5Xq+vdqJ7ZlsaNMNhDukS3RunILkTW5q9WeW9eabSSyY4uCY81YP2bR -F/U/FPM/mYbWNUELgSmN/YkSwWLGgfjcCObTwgd0FOW7XZuJ71R7ytBEn5kDt3bc -vULsB4kAPwMFGDSMdS7YyjFxW6BSwxECd5YAoKUcWpHjSL1KbOH3Ud52avzESk7C -AKCOQUeC622jsKntTOR5R9Vv4wyyKQ== -=L8Lf ------END PGP PUBLIC KEY BLOCK----- - </programlisting> - </sect2> - - <sect2> - <title>&a.rich;</title> - - <programlisting> -Rich Murphey <rich@FreeBSD.org> -fingerprint = AF A0 60 C4 84 D6 0C 73 D1 EF C0 E9 9D 21 DB E4 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAy97V+MAAAEEALiNM3FCwm3qrCe81E20UOSlNclOWfZHNAyOyj1ahHeINvo1 -FBF2Gd5Lbj0y8SLMno5yJ6P4F4r+x3jwHZrzAIwMs/lxDXRtB0VeVWnlj6a3Rezs -wbfaTeSVyh5JohEcKdoYiMG5wjATOwK/NAwIPthB1RzRjnEeer3HI3ZYNEOpAAUR -tCRSaWNoIE11cnBoZXkgPHJpY2hAbGFtcHJleS51dG1iLmVkdT6JAJUDBRAve15W -vccjdlg0Q6kBAZTZBACcNd/LiVnMFURPrO4pVRn1sVQeokVX7izeWQ7siE31Iy7g -Sb97WRLEYDi686osaGfsuKNA87Rm+q5F+jxeUV4w4szoqp60gGvCbD0KCB2hWraP -/2s2qdVAxhfcoTin/Qp1ZWvXxFF7imGA/IjYIfB42VkaRYu6BwLEm3YAGfGcSw== -=QoiM ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.obrien;</title> - - <programlisting> -Type Bits KeyID Created Expires Algorithm Use -sec+ 1024 0x34F9F9D5 1995-04-23 ---------- RSA Sign & Encrypt -f16 Fingerprint16 = B7 4D 3E E9 11 39 5F A3 90 76 5D 69 58 D9 98 7A - David E. O'Brien <obrien@NUXI.com> - David E. O'Brien <obrien@FreeBSD.org> - David E. O'Brien <obrien@cs.ucdavis.edu> - David E. O'Brien <dobrien@seas.gwu.edu> - David E. O'Brien <obrien@elsewhere.roanoke.va.us> - David E. O'Brien <whois Do38> - -sec+ 1024 0x7F9A9BA2 1998-06-10 ---------- DSS Sign & Encrypt -f20 Fingerprint20 = 02FD 495F D03C 9AF2 5DB7 F496 6FC8 DABD 7F9A 9BA2 -sub 3072 0xBA32C20D 1998-06-10 ---------- Diffie-Hellman -f20 Fingerprint20 = 0700 6058 CE6C 1C51 D0A3 45E6 26E1 A405 BA32 C20D - "David E. O'Brien" <obrien@NUXI.com> - "David E. O'Brien" <obrien@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQGiBDV+M04RBADXKeFCmXsTfVxqwiVHv7MWoP9uzUuILtt7QIDGLyEWdhDkqUXq -Ux9yrH6B1y4q38XI7Z2OFh6KEXDDZyOR9ntsA0RF9+h+e92RfN6Co6F3SOyTuBuA -Q+jV+Hl0mbh7Sqjl5SjTMjT3AvHnKM21Zac0zmjhhXFprSSILcMp1HBchwCg/7hP -kuoubQUxdH5SjVKrsystWf0D+wWQ5PxKzz4lLDG2TZAgCD5C+a/IaXnGYvXjOfc2 -ktLChwVIxf7Z9cEARDOWEHPfwkjn0OEhtX7teUiOx34h3/wIVPN5IfqhHVCcEUQT -R+ZwYAYACqfihfyYdzttVDGvHMmUwUgu2zr19N2olREqPA25hls7w7F6UlN4d+PF -zljWA/wMHDG25k9UnDibKbCXQOhDARusL6YoFN3JneA4y/TM3rgoUQpBkk99218v -LlaSz2TXH7ne+nxldX8IigN/SG9u6K6eWJ/LKSUuLyeo1r4oxGafCzteQSaBBOuQ -hXbpX2xEK3wQ64NdnXlBZfBy5JEa+3SWpTO2iQC7JNtI0nLjm7QkIkRhdmlkIEUu -IE8nQnJpZW4iIDxvYnJpZW5ATlVYSS5jb20+iQBLBBARAgALBQI1fjNOBAsDAQIA -CgkQb8javX+am6LP8gCfXYmb3/0O/9viAhq4mXOMRM7GEygAoJCRiRmhfz84yCC7 -GSY/Li2Bi63TiQCVAwUQNX4zzWVgqaw0+fnVAQF21wP+PK9MlfIcaOAuQVMgQhsD -Wqlj/DdxtsxT1GOnlHp3JGxdThyxdBDrxmiU22a6216s01fN5Ac25USeKRCcSVyG -0+G/Xd3VfWDCEQCLNBwblAGKW9BEZfJhS1xOuTEYxgbmuvrlLTdvWm+MwPetv8ka -yhD1LM4rVovMxenaPYUub2S0JyJEYXZpZCBFLiBPJ0JyaWVuIiA8b2JyaWVuQEZy -ZWVCU0Qub3JnPokASwQQEQIACwUCNmOeXQQLAwECAAoJEG/I2r1/mpuiv3oAoOBm -ZIDRolksEb0iNP46X96pRsU8AJ9nTPnCjxfj9oP0wQBslElAS8awfIkAlQMFEDZj -ny5lYKmsNPn51QEBkUcEALYsZckj5fs7uUzjSgyzF/2RrHJ5gGrpNBwikiy1+wdZ -6bz8CQ6kcYC3Dap3iHSc9KWTn6sK5ZvYXcYD9k7is8V8zuitUrrSGWpY96qmNsCT -vPSwfwIcyhYSIJYjdqmv4EnKo2mwkY3zqOV9DT1ABFLSI9Eyy8ILeuhrm9jWEXs0 -tCoiRGF2aWQgRS4gTydCcmllbiIgPG9icmllbkBjcy51Y2RhdmlzLmVkdT6JAEsE -EBECAAsFAjZjnroECwMBAgAKCRBvyNq9f5qbopXDAJ9VboPXKbLDYCS2jYZg+X7Z -or1ZOQCfV+u96L4zxj10Z5bHhpJXaXsq1Aq5Aw0ENX4zUBAMAMwdd1ckOErixPDo -jhNnl06SE2H22+slDhf99pj3yHx5sHIdOHX79sFzxIMRJitDYMPj6NYK/aEoJguu -qa6zZQ+iAFMBoHzWq6MSHvoPKs4fdIRPyvMX86RA6dfSd7ZCLQI2wSbLaF6dfJgJ -Co1+Le3kXXn11JJPmxiO/CqnS3wy9kJXtwh/CBdyorrWqULzBej5UxE5T7bxbrlL -OCDaAadWoxTpj0BV89AHxstDqZSt90xkhkn4DIO9ZekX1KHTUPj1WV/cdlJPPT2N -286Z4VeSWc39uK50T8X8dryDxUcwYc58yWb/Ffm7/ZFexwGq01uejaClcjrUGvC/ -RgBYK+X0iP1YTknbzSC0neSRBzZrM2w4DUUdD3yIsxx8Wy2O9vPJI8BD8KVbGI2O -u1WMuF040zT9fBdXQ6MdGGzeMyEstSr/POGxKUAYEY18hKcKctaGxAMZyAcpesqV -DNmWn6vQClCbAkbTCD1mpF1Bn5x8vYlLIhkmuquiXsNV6UwybwACAgwAm1JzkDnM -N7PqTh/hWMfxpsl1WzwQ0LecB/15UEKvqUZeRFcTCPh/6lVvJL64K2O4mVwTUnX4 -9EYDjccK/DQQEpEJ3XfOt/vMGFQXXO8frj4ulxeSQAaodmrJsfBexeLIatFidkHy -5pN+5dpnQZhcoRrjpbK+mdu9gW4oImUKInFV7mIpVFK2sYQlkP52WZuPwXtkWjoa -l+43oD7vGZpIdT6iqCI/hwF64bP6NtbVRaI3mbXOn+S2qdLf5YRROBavVa7yvBrZ -7lOp71aGb9TjpOpxPWoISvKj9uzhFtuzh+k8ABv0hPNyF3iKaBWaeNEVpYlR3hOu -ojcLG+6+X/GTbFbcFxeybbajkcksIs1oNSpRaNqHVpgBsbN59w7Tmva62bLz2R5U -XhbmRuqvQujAwT2+6PcD1Ra/QG1QNyoM/leLhLjOjQGZ+SvlxDhDsgX+W3Y1QXX3 -e2Ual4c1K6itgvR02hKOR+IOl+IFB6dsd47cjyh0xuhKpjsEsE36aFk1iQA/AwUY -NX4zUG/I2r1/mpuiEQIDyQCeOvK/V0VRBNZNAYknb2GfVTKVJWYAoMXeTJABkMDL -P7bUxAmeYnY7l0UmmQCNAy+ZtI0AAAEEAMPph+5fYQ4pUXUCgsXGqWi1LuxtqSP3 -WC/20zlqOUq35T2e/3dEqFXB1Rbzz7rhI8hraDyGybexiO9OcQMbxSKBha+BnMyq -hoTM7bmzSZCRSWtIQ3ugC5Q0O6RUkrHL3k88h/Q/9IrqCXIesMaeeWOIit7tJ9dY -gWVgqaw0+fnVAAURtChEYXZpZCBFLiBPJ0JyaWVuIDxvYnJpZW5AY3MudWNkYXZp -cy5lZHU+iQCVAwUQNHYnL6v/B7RG8yEtAQE2QwP/blDA0lFO0AH1/Dhvlc1ylPEG -mQw0FDldz40N4ni5e3gRPdTy03AWrCDQMX7xLJ5Zd9HOA+IiPkDkj8OQkA9WUrPh -HhAUMy2yh2PSnt2mIJ8dv4M5eH4H6IJPjMu6z08UvkKdXlpd9Ku2aRgyshV9dHFV -ikMCMLTdk/i3RIApY0iJAJUDBRAykexbym8rg/wMAtUBAQSRA/9zHA9hUeLO2nVm -d37pndP40JYiklLyw9mapz4xHQ8bsEVdERXQ6MdVNPa46j1RM1VdZMI7fBlK9aX+ -c7GW6swzEFC1eWtVnzeMMh46MEQLkAoYVOFRWkXH9hzGdEVcaJn9sSuoQ+KiFu72 -LVNg7KJI6v48CuWKep0H47nhuKPwbokAlQMFEDH/SvU/2TrIQc4JiQEBl88D/1d/ -WSV3W6RwZQUnbSp1GELg5knB87imzxf3t328/vzRRFUgAeB9qcW9fYRwdhZDs4ff -UASm2fXSbXocnRdGDJMKaFZooJpYK95vZFc0irLhI92w2RjLH1tF/W0TCopWMLN4 -KuqYX3PLMzQEcj08w3BcwWXwD0UuVD91d4WeljRZiQCVAwUQMZSmW2Vgqaw0+fnV -AQEkAwP8Dre9osgnIJLvVQlPLbuSExdrG8+m9mae8vaZVuFJFgo1x372oaZok0Vx -ZHOkulspC6Mo0B8cPCI7BkfyfthHHZwh83Fr+MNfwjiG/JQEobvaTok+aU3cwQjz -anQkBQZX/f0tYxTx7/tTWxMeR35CW7sIYgAsutBhKSPGC4VAe82JAJUDBRAx9B35 -V0EEo6SepNkBAT6YBACwTyfKQ019/Qgg04I0gEtJCiV2xa1ms7xpOVQj0TF/rzfN -Z45BzbOKOtolsSGP72ddjqpgjsZ/7g3Z4VG83c+QDJVwEBpUe1D9DX8cEKMTBjZO -JTTmGS0FIRrszddnLLf5gqNCWPYlImq8DR8Mjsy/vGsotkSLfKs7sdnzE7o0k7Qy -RGF2aWQgRS4gTydCcmllbiA8ZGVmdW5jdCAtIG9icmllbkBTZWEuTGVnZW50LmNv -bT6JAJUDBRAzZsMkZWCprDT5+dUBAcE/BACFUS0dN3dp6+sYxhTav9QfqOpWb/ay -hwcUKoxuo/4c1IUDZ8sCkANIRLnFUjC8irF0oND67KNU2vZWRaqwJ6ghQIkrfRHf -wUHRWAcoE1AFypHgOnE/KXuwmqkqHFmE4xpn0Ozpdcwc+KOSUFjToBgpAIwcZfIG -3e8o1e0dj4PJD7QnRGF2aWQgRS4gTydCcmllbiA8ZG9icmllbkBzZWFzLmd3dS5l -ZHU+iQCVAwUQMPa62j/ZOshBzgmJAQGY5gP/ZXM8VadFIywFzN43xK0L9nc6SwwI -k0FaddKYvmvJgMz1Qp5gn3DcuH0CWyJwH3uRQvIMQXvQ57Iy3x4eb5WcwxwDaW6u -TzC1uQtooAaAINCJuEaXrw4Q+uuGYGIAeh1x4TwUgdxmmq56cfkeiaXwwaJUoOga -IiDd6vpM37ZU2gyJAHUDBRAv5F+Q0/I/Qidq6hEBAThXAwCnHV6THDI8Prkg8DXN -KYzhGJH56WlujCpzqNKm8AC5rkp/5dtfiXsqadZK/VXlip/bXFB7nAR8k87MMXrt -tYyPylFCEc7kLLqYJ6KeS8jTa6Q48W0LzbogSF/owFUL8bGJAJUDBRAvpRUNx4uq -hJJkHpkBAWiSA/0b3F9ZwqMLFsSv1MAQOwoiw2QpAoQWV+oa4CNJVY4GoQjIbRZv -WlkRAocjfv1oQr2dU1KxDmZCT8TolG9gQ232rm4n2anr7A9RVi3zdgvu6/VgklLL -vzy12vV6y62CIB4s2Y0yY6BHDe/PyIpgmjOZLINIr8fAdLvNnZD0rmGkMIkAlQMF -EC+ga/DKbyuD/AwC1QEBMWMD/2HyNJHmnL3A/LpaSOxhBuaXwHZ9WOwvOhBswj5v -kgVh4ORFgtOdIskrO4rzMefVoV5ciEPQJFjk8L2MwC7zgjn2IT3TH3m4s8AfTStI -lqbaASo+i9FhyKcAOW6K85NcYCfmo31sqWZ2wU0swgWz+uiGcgVpvvAbf636L7xh -hjZgiQCVAwUQL5rlIWVgqaw0+fnVAQH+0QQAspRF9vtjuZ60MfHmhXkvJtbJXxxM -kog1SWVfwcOfPrNlDtsxiVDSqypGoQgMykyTW2iNP78cji17bW5bRP8UJ6Z2buV5 -kzqDfw17fnwvyNj/fiLPRsgV5mMPMug4pbkLzC0b83zy+iITSCtVHd6IUSa3BZPm -VFpX4OYphDiRfEC0MURhdmlkIEUuIE8nQnJpZW4gPG9icmllbkBlbHNld2hlcmUu -cm9hbm9rZS52YS51cz6JAJUDBRAyZskiZWCprDT5+dUBAQ1RA/4ml0nJM5iZkpYu -BJd/kUMLCsv3k+ApsMxB/ZBZWCfqmGBN7SBu6FTIgZCjC4/eUJPcLdMTF6NTbA+D -7BQziV38lHCfo5d48Bq2hq6Fb7ti2/9FIgvalz5jSnmKKUAq7MHceRFJAJi1wOJY -Hz0tYBHhD0EFSmzHNgwV4VA7m6m3c7QxRGF2aWQgRS4gTydCcmllbiA8ZGVmdW5j -dCAtIG9icmllbkBtZWRpYS5zcmEuY29tPokAlQMFEDNmwwtlYKmsNPn51QEBphkE -AK70I7FWzJfGMmtej7gN1rMliBxsfxxmy1DZVSVP0T7xkniIvgfmoiq+2Sn14iJl -2Lb+i+/3ADS5XQxl09LciSq6YqvPhQZvAuRj5UxMO0nC4zO1+Jr6pxXH8cu5kx+5 -MAH9/K4ktbmL2RvtffJRJuv/0nyn7h1rRHVgyP+Yq6x6tB1EYXZpZCBFLiBPJ0Jy -aWVuIDx3aG9pcyBEbzM4PokAlQMFEDHR+5BlYKmsNPn51QEBzMAD/R+ridxhjUWo -JKpAfecs7rSTPq+ajwiVMjtykv97nbVOpFM4roctdiudUEjj0P6g331MsZOVST6M -6sdztj+OzQhEtmQpw1SyXclUgaK2HsA9opIWQxU0XsGsiOochbPI+4ezXDvPeHgG -YVRNDuFzb1BiVbauATXaq/HB6xDsHagdiQCVAwUQNmQ33T/ZOshBzgmJAQGrCwP+ -NNVRnjjcNo41qkTsRW8bhqhbHrHBOlAfq+3kT/gM1xUAcYsQOKurgBGNMAr3wew8 -ApsUz7QgatFLTgxBNX/vS6/7hUuqNJhBAwpCG6i4lUFmJKONY9YND9tP6VhNMdBL -F76yUhxORPu4vcxPOqchN/Jgkevjf9ONnIYDeV/hySm0IkRhdmlkIEUuIE8nQnJp -ZW4gPG9icmllbkBOVVhJLmNvbT6JAJUDBRA0didEq/8HtEbzIS0BAf5oA/43tqeI -pgkuyKvCg28bX0YtQBSJo64ohFsSgQN2FANfpghH8dhfQt3/AXH3jOisHA7ESTNx -ZT8yxPl3T4ZhZ3VILlldeuAM4g1U/ZDS+IPJMu7Rzwt4XYy725X+fLVeWoPIuIgp -vX8+8hc7v6NkV2nwBMgbRGoblAzas2K79skXvIkAlQMFEDMWkrZD7IadE0shMQEB -PbAD/06rmYrMb/Q/arblxzZ9DOpwuksv9ColF/vheexCLPzBcqtqxQ2li6f02CWA -RH34P23gC5m2wUj7I5+5LvMOg1SFimSrlmvg8ZhgfKIvFjwbPG/g5rVq0/lcyNGQ -/lTPJAsREBwcnBhkr9oT/BeRS7uoWykN4NM01dnx12upXvX0iQCVAwUQMpEBMWVg -qaw0+fnVAQHeawP+M7BdBFis4zNe7H51+BA0i35yRoy1efj7bS7QBqPes+oxTpAi -hO+wxwbXjurdNjCruldi926NCls+MLcSsGczWCHhe+o+Gp/xppjN9QX7SvHBVtSH -nlUucwLpgdj4rOMcPjVIwLkH95JwaiDW2iO876rGuLbcn7oGT+3Ww1psEDGJAJUD -BRA2ZDeVP9k6yEHOCYkBAfVdBACNSHeqQjRkeX2pP1woHSW4AD77buMHma5bno2F -yChsCN7ZPdAlGixiscnwd41+nxuxiK2x/EyIuzs+9EYVtiikWeQCkR8ajGH0xXOK -H+W8Mun1RtN9S8HtJWxX5Pfz8LHOziT6Y+HwJmncAIIbY3N+Yhbvd9XAl2l6OQ8c -uSrrBIkAlQMFEDa+UHHKbyuD/AwC1QEBULYD/RgnK84Wf37e+5WGQbHgzUkrXXxz -fFpRTEV0owBSK5KA7+qlGVQVFZJ/Qz4dEwU0EAHj72uaxVuYAa+fCaOzD/G6VOv+ -4r9zout8dxPYfK1RLPMg/5hn0Jqf2Ce733ibK8NUYtjMY5z0F5wjEdiieSsLIsT9 -J4dB2ZODT2Hfe7brtCVEYXZpZCBFLiBPJ0JyaWVuIDxvYnJpZW5ARnJlZUJTRC5v -cmc+iQCVAwUQNHYnV6v/B7RG8yEtAQEkHgP7BSvndsqWiSDosBrnuD0R94ItlJKU -sCt/vu/AuhosrOx2hYtD3TxU2ZBlBtS3mS3c7Qe13H/NFM+SrNXa0pbRoDsPlcNY -nK/WV8G6/WDwLXrazm+iIwrPpbILKc/yfnWdGVdpIe3FaqUsEFDcgjMlcZ3gB6RA -YGdzHyjZdJh1DIuJAJUDBRAyxHKdZWCprDT5+dUBAenWA/93EfJZx5fuarjQ7AnQ -iPAjAi95v3Rlh13+N9vC34+C7RMi9pIj6B6PnWTNbVhg8RY8S6hB91J6GrN0KVLD -8yDpY6+U08Yc47fOfSWhPopNDfqgviGw7ONmc2QCWEKpcH4c1VD2jJIr7iewfVgJ -AiKdEB8kQhrutuQNDNNX1dCSCYkAlQMFEDWRdmGzWmLrWZ8yPQEBwswEAIRV9oAL -x9Ow9ZDtG/TLfae29TBSYEinPj/6n8d+hQDiX41rQ4nLGCLcdgBtINKfeQ6WUcBW -tWB9KqxdaV105QUhcEUpqMwK5U6DZBDipjuy4i6w7Ml0BLWtl/fANc33IPlnFAdD -oP6s3oHtoRLNW0ryDk4g5bfFnMzF/X9hZdTLiQCVAwUQNmQ4Kj/ZOshBzgmJAQHb -ZQP/Qs/Zefw9qxqrUihncZRIQbbnLsor4a0n2lH9cNTsSKU0H4a8rDlqYva+PFA1 -umFvVOon90dqoq8C6cykts4xRRKrPNnfiis+otwHgsKrzDIONyHWxnM9Ic/EjbOs -AHcBCBtLwxczFegWNgWbEy0FIVlzcmquRxO+7woxeW5MEHiJAJUDBRAzaSRDV0EE -o6SepNkBAfCOA/9e2DhVo6geSpWjdIXiv0yQC2Abv2TunPt2UiUxpgYkHzt+Ubk+ -k8cj2j723FZAfi+R7FobNSx7P4mCdrf2WEzaHdWLt6REr61rvqUc5ir/oHgUP1Ok -tgAUhy6TJUMklyzENkPRZG2hiQbfPQYVEh5m1Xmcp3Gel0eiinWui2Iv/okAlQMF -EDa+UHnKbyuD/AwC1QEB8CAD/2gYTjkPFcktVKkTX7w2O0Q3o7yLzbo9Y/USRsm+ -gVMMZjZ7QiiO1LGl6IIiKRtJIXi45PcHtYgSZlXKflqPHhEIrOhFwpV+C7uL5jnv -ATGhlLHxWuNLTlPAVD5FsdJdOHI7UdkJh19JpphV+usu/mihMFEfM/kOVJeTXed1 -0E4T -=Qwmg ------END PGP PUBLIC KEY BLOCK----- - </programlisting> - </sect2> - - <sect2> - <title>&a.jdp;</title> - - <programlisting> -John D. Polstra <jdp@polstra.com> -Fingerprint = 54 3A 90 59 6B A4 9D 61 BF 1D 03 09 35 8D F6 0D - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzMElMEAAAEEALizp6ZW9QifQgWoFmG3cXhzQ1+Gt+a4S1adC/TdHdBvw1M/ -I6Ok7TC0dKF8blW3VRgeHo4F3XhGn+n9MqIdboh4HJC5Iiy63m98sVLJSwyGO4oM -dkEGyyCLxqP6h/DU/tzNBdqFzetGtYvU4ftt3RO0a506cr2CHcdm8Q+/vPRJAAUR -tCFKb2huIEQuIFBvbHN0cmEgPGpkcEBwb2xzdHJhLmNvbT6JAJUDBRAzBNBE9RVb -+45ULV0BAWgiA/0WWO3+c3qlptPCHJ3DFm6gG/qNKsY94agL/mHOr0fxMP5l2qKX -O6a1bWkvGoYq0EwoKGFfn0QeHiCl6jVi3CdBX+W7bObMcoi+foqZ6zluOWBC1Jdk -WQ5/DeqQGYXqbYjqO8voCScTAPge3XlMwVpMZTv24u+nYxtLkE0ZcwtY9IkAlQMF -EDMEt/DHZvEPv7z0SQEBXh8D/2egM5ckIRpGz9kcFTDClgdWWtlgwC1iI2p9gEhq -aufy+FUJlZS4GSQLWB0BlrTmDC9HuyQ+KZqKFRbVZLyzkH7WFs4zDmwQryLV5wkN -C4BRRBXZfWy8s4+zT2WQD1aPO+ZsgRauYLkJgTvXTPU2JCN62Nsd8R7bJS5tuHEm -7HGmiQCVAwUQMwSvHB9/qQgDWPy9AQFAhAQAgJ1AlbKITrEoJ0+pLIsov3eQ348m -SVHEBGIkU3Xznjr8NzT9aYtq4TIzt8jplqP3QoV1ka1yYpZf0NjvfZ+ffYp/sIaU -wPbEpgtmHnVWJAebMbNs/Ad1w8GDvxEt9IaCbMJGZnHmfnEqOBIxF7VBDPHHoJxM -V31K/PIoYsHAy5w= -=cHFa ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.guido;</title> - - <programlisting> -Guido van Rooij <guido@gvr.win.tue.nl> -Fingerprint = 16 79 09 F3 C0 E4 28 A7 32 62 FA F6 60 31 C0 ED - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.2 - -mQCNAzGeO84AAAEEAKKAY91Na//DXwlUusr9GVESSlVwVP6DyH1wcZXhfN1fyZHq -SwhMCEdHYoojQds+VqD1iiZQvv1RLByBgj622PDAPN4+Z49HjGs7YbZsUNuQqPPU -wRPpP6ty69x1hPKq1sQIB5MS4radpCM+4wbZbhxv7l4rP3RWUbNaYutZnzI9AAUR -tCZHdWlkbyB2YW4gUm9vaWogPGd1aWRvQGd2ci53aW4udHVlLm5sPokAlQMFEDMG -Hcgff6kIA1j8vQEBbYgD/jm9xHuUuY+iXDkOzpCXBYACYEZDV913MjtyBAmaVqYo -Rh5HFimkGXe+rCo78Aau0hc57fFMTsJqnuWEqVt3GRq28hSK1FOZ7ni9/XibHcmN -rt2yugl3hYpClijo4nrDL1NxibbamkGW/vFGcljS0jqXz6NDVbGx5Oo7HBByxByz -iQCVAwUQMhmtVjt/x7zOdmsfAQFuVQQApsVUTigT5YWjQA9Nd5Z0+a/oVtZpyw5Z -OljLJP3vqJdMa6TidhfcatjHbFTve5x1dmjFgMX/MQTd8zf/+Xccy/PX4+lnKNpP -eSf1Y4aK+E8KHmBGd6GzX6CIboyGYLS9e3kGnN06F2AQtaLyJFgQ71wRaGuyKmQG -FwTn7jiKb1aJAJUDBRAyEOLXPt3iN6QQUSEBATwQA/9jqu0Nbk154+Pn+9mJX/YT -fYR2UqK/5FKCqgL5Nt/Deg2re0zMD1f8F9Dj6vuAAxq8hnOkIHKlWolMjkRKkzJi -mSPEWl3AuHJ31k948J8it4f8kq/o44usIA2KKVMlI63Q/rmNdfWCyiYQEVGcRbTm -GTdZIHYCOgV5dOo4ebFqgYkAlQMFEDIE1nMEJn15jgpJ0QEBW6kEAKqN8XSgzTqf -CrxFXT07MlHhfdbKUTNUoboxCGCLNW05vf1A8F5fdE5i14LiwkldWIzPxWD+Sa3L -fNPCfCZTaCiyGcLyTzVfBHA18MBAOOX6JiTpdcm22jLGUWBf/aJK3yz/nfbWntd/ -LRHysIdVp29lP5BF+J9/Lzbb/9LxP1taiQCVAwUQMgRXZ44CzbsJWQz9AQFf7gP/ -Qa2FS5S6RYKG3rYanWADVe/ikFV2lxuM1azlWbsmljXvKVWGe6cV693nS5lGGAjx -lbd2ADwXjlkNhv45HLWFm9PEveO9Jjr6tMuXVt8N2pxiX+1PLUN9CtphTIU7Yfjn -s6ryZZfwGHSfIxNGi5ua2SoXhg0svaYnxHxXmOtH24iJAJUDBRAyAkpV8qaAEa3W -TBkBARfQBAC+S3kbulEAN3SI7/A+A/dtl9DfZezT9C4SRBGsl2clQFMGIXmMQ/7v -7lLXrKQ7U2zVbgNfU8smw5h2vBIL6f1PyexSmc3mz9JY4er8KeZpcf6H0rSkHl+i -d7TF0GvuTdNPFO8hc9En+GG6QHOqbkB4NRZ6cwtfwUMhk2FHXBnjF4kAlQMFEDH5 -FFukUJAsCdPmTQEBe74EAMBsxDnbD9cuI5MfF/QeTNEG4BIVUZtAkDme4Eg7zvsP -d3DeJKCGeNjiCWYrRTCGwaCWzMQk+/+MOmdkI6Oml+AIurJLoHceHS9jP1izdP7f -N2jkdeJSBsixunbQWtUElSgOQQ4iF5kqwBhxtOfEP/L9QsoydRMR1yB6WPD75H7V -iQCVAwUQMZ9YNGtaZ42Bsqd5AQH0PAQAhpVlAc3ZM/KOTywBSh8zWKVlSk3q/zGn -k7hJmFThnlhH1723+WmXE8aAPJi+VXOWJUFQgwELJ6R8jSU2qvk2m1VWyYSqRKvc -VRQMqT2wjss0GE1Ngg7tMrkRHT0il7E2xxIb8vMrIwmdkbTfYqBUhhGnsWPHZHq7 -MoA1/b+rK7CJAJUDBRAxnvXh3IDyptUyfLkBAYTDA/4mEKlIP/EUX2Zmxgrd/JQB -hqcQlkTrBAaDOnOqe/4oewMKR7yaMpztYhJs97i03Vu3fgoLhDspE55ooEeHj0r4 -cOdiWfYDsjSFUYSPNVhW4OSruMA3c29ynMqNHD7hpr3rcCPUi7J2RncocOcCjjK2 -BQb/9IAUNeK4C9gPxMEZLokAlQMFEDGeO86zWmLrWZ8yPQEBEEID/2fPEUrSX3Yk -j5TJPFZ9MNX0lEo7AHYjnJgEbNI4pYm6C3PnMlsYfCSQDHuXmRQHAOWSdwOLvCkN -F8eDaF3M6u0urgeVJ+KVUnTz2+LZoZs12XSZKCte0HxjbvPpWMTTrYyimGezH79C -mgDVjsHaYOx3EXF0nnDmtXurGioEmW1J -=mSvM ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.wosch;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/2B7181AD 1997/08/09 Wolfram Schneider <wosch@FreeBSD.org> - Key fingerprint = CA 16 91 D9 75 33 F1 07 1B F0 B4 9F 3E 95 B6 09 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzPs+aEAAAEEAJqqMm2I9CxWMuHDvuVO/uh0QT0az5ByOktwYLxGXQmqPG1G -Q3hVuHWYs5Vfm/ARU9CRcVHFyqGQ3LepoRhDHk+JcASHan7ptdFsz7xk1iNNEoe0 -vE2rns38HIbiyQ/2OZd4XsyhFOFtExNoBuyDyNoe3HbHVBQT7TmN/mkrcYGtAAUR -tCVXb2xmcmFtIFNjaG5laWRlciA8d29zY2hARnJlZUJTRC5vcmc+iQCVAwUQNxnH -AzmN/mkrcYGtAQF5vgP/SLOiI4AwuPHGwUFkwWPRtRzYSySXqwaPCop5mVak27wk -pCxGdzoJO2UgcE812Jt92Qas91yTT0gsSvOVNATaf0TM3KnKg5ZXT1QIzYevWtuv -2ovAG4au3lwiFPDJstnNAPcgLF3OPni5RCUqBjpZFhb/8YDfWYsMcyn4IEaJKre0 -JFdvbGZyYW0gU2NobmVpZGVyIDxzY2huZWlkZXJAemliLmRlPokAlQMFEDcZxu85 -jf5pK3GBrQEBCRgD/jPj1Ogx4O769soiguL1XEHcxhqtrpKZkKwxmDLRa0kJFwLp -bBJ3Qz3vwaB7n5gQU0JiL1B2M7IxVeHbiIV5pKp7FD248sm+HZvBg6aSnCg2JPUh -sHd1tK5X4SB5cjFt3Cj0LIN9/c9EUxm3SoML9bovmze60DckErrRNOuTk1IntCJX -b2xmcmFtIFNjaG5laWRlciA8d29zY2hAYXBmZWwuZGU+iQEVAwUQNmfWXAjJLLJO -sC7dAQEASAgAnE4g2fwMmFkQy17ATivljEaDZN/m0GdXHctdZ8CaPrWk/9/PTNK+ -U6xCewqIKVwtqxVBMU1VpXUhWXfANWCB7a07D+2GrlB9JwO5NMFJ6g0WI/GCUXjC -xb3NTkNsvppL8Rdgc8wc4f23GG4CXVggdTD2oUjUH5Bl7afgOT4xLPAqePhS7hFB -UnMsbA94OfxPtHe5oqyaXt6cXH/SgphRhzPPZq0yjg0Ef+zfHVamvZ6Xl2aLZmSv -Cc/rb0ShYDYi39ly9OPPiBPGbSVw2Gg804qx3XAKiTFkLsbYQnRt7WuCPsOVjFkf -CbQS31TaclOyzenZdCAezubGIcrJAKZjMIkAlQMFEDPs+aE5jf5pK3GBrQEBlIAD -/3CRq6P0m1fi9fbPxnptuipnoFB/m3yF6IdhM8kSe4XlXcm7tS60gxQKZgBO3bDA -5QANcHdl41Vg95yBAZepPie6iQeAAoylRrONeIy6XShjx3S0WKmA4+C8kBTL+vwa -UqF9YJ1qesZQtsXlkWp/Z7N12RkueVAVQ7wRPwfnz6E3tC5Xb2xmcmFtIFNjaG5l -aWRlciA8d29zY2hAcGFua2UuZGUuZnJlZWJzZC5vcmc+iQCVAwUQNxnEqTmN/mkr -cYGtAQFnpQP9EpRZdG6oYN7d5abvIMN82Z9x71a4QBER+R62mU47wqdRG2b6jMMh -3k07b2oiprVuPhRw/GEPPQevb6RRT6SD9CPYAGfK3MDE8ZkMj4d+7cZDRJQ35sxv -gAzQwuA9l7kS0mt5jFRPcEg5/KpuyehRLckjx8jpEM7cEJDHXhBIuVg= -=3V1R ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.gshapiro;</title> - - <programlisting> -Type Bits KeyID Created Expires Algorithm Use -sec+ 1024 0x4FBE2ADD 2000-10-13 ---------- RSA Sign & Encrypt -f16 Fingerprint16 = 56 D5 FF A7 A6 54 A6 B5 59 10 00 B9 5F 5F 20 09 -uid Gregory Neil Shapiro <gshapiro@gshapiro.net> -uid Gregory Neil Shapiro <gshapiro@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAznnjPsAAAEEAL5gfaY7RP5vm89lqmjGAJRBFLM/qzHJKrYkRVDASeLZ0/JI -Bfypd8N1vQz80tnqzOh7aLgAskgluyx0O9EuZXTJUwm+ew6wA8vh8JA0kpI5g3N5 -wjXQNWPxSCeNIz1hbgAPtRunVLXXoaxxCQziU38bd2RvzlvgQdbgof5PvirdAAUR -tCxHcmVnb3J5IE5laWwgU2hhcGlybyA8Z3NoYXBpcm9AZ3NoYXBpcm8ubmV0PokA -lQMFEDnnjRPW4KH+T74q3QEBKlED/1F8UjkufYD0G9eV7X5ujAVffIBl6nvHVw4+ -/m+lXxnUmOInk8AUmHIxK62BJ9CPWHegf91BsGNMVA7cQiF+atdz8Yy4h1Snt7FB -OsL2Ak0g2WUrIDfB+N5SB/EjdK0BdURsccYbORGVIveveUNmxuW4jUZWcInCkDx4 -FTGRxzAFiQCVAwUQOeevO3xLZ22gDhVjAQHAVAP+NWdTbxipCQANnRf4BNl492mG -VN51MBZnlsy/lyMu2yckR3eacaXmp3zKardwex7Ajle5XC6sJ1H3twYv8g63eqJ4 -XuxC9Uxmer2mj7wibcO2srtwv2hgLMNVjJrClALolQ6WT7/6L1YENP0Ef26eJXnw -pwXdfaXurbwnv4tyOOGJAJUDBRA556+fvdqP1j/qff0BAVUtA/94+oMC9pJgXi+0 -tbwUsAu/pJqHByjCjO+LscH+gtqb4VhfxdEllHTVj5Cju7o+HcYZdtTRdggx2FqV -zaCp2kq1kbEGuQCJzwNHkG10I8C5YlyXUaYGwX1gEPImzTpOI0C3Any0UvK4KQsl -Crj0UmRARVwzulGYE7hxknivvkdbw7QrR3JlZ29yeSBOZWlsIFNoYXBpcm8gPGdz -aGFwaXJvQEZyZWVCU0Qub3JnPokAlQMFEDnnjPvW4KH+T74q3QEBMeYD/03sPgJ0 -QKQXzSRGyiVZBkZ4frsFj6nH2IP9+zCTRUlX0uyo6f1Z2RC3a++MbaKFR/LUmdZ8 -DkOfOTcvsoIQJ6BOQO1/XpOkppvhrYRUU7a6C9wM7ptWEJvx5IcmWk5oWxmx373e -cPb5MkhiXK85/NRxhlS5PG5kcz2ajJ7imYnuiQCVAwUQOeevZnxLZ22gDhVjAQGn -2AQAta7mxgLMyGKhq9msyQ2rITAhEvhoYM47OeOgyq5FKx0b0rEmIjC+sDx3YOsb -auw/Z5bAYzZnUmhe65KKA76eITqlnMt1ykaDu0jQLGKczXjuLCMCDT/JCZStoyt6 -XhG9R+R8PnXk80PtZlTJjHuJyghBq5fzrIKs0k2G7eVchnKJAJUDBRA556+nvdqP -1j/qff0BAWVdA/9m5bMpkhnxDcfApaDp6mF2hEdacuHXrMXOzsrTuFiFoJhByXfM -bMDM1T8Hq3FU8TJ3BQ/ydgoeiuvWJ5j0clBegCbxS7tH/FvlnZBikNeARFTD0m5H -hmG+vzIwhe2sjh7/0dqaj1RMwLPxrQVyukHGnzyFodjcDJy1jWEl1Onytw== -=i+mc ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.gshapiro;</title> - - <programlisting> -Type Bits KeyID Created Expires Algorithm Use -sec+ 1024 0xFCE56561 2000-10-14 2001-10-14 DSS Sign & Encrypt -f20 Fingerprint20 = 42C4 A87A FD85 C34F E77F 5EA1 88E1 7B1D FCE5 6561 -sub 1024 0x285DC8A0 2000-10-14 2001-10-14 Diffie-Hellman -f20 Fingerprint20 = 69AB 26D1 A244 51E3 2B6C 7091 BD19 FA76 285D C8A0 -uid Gregory Neil Shapiro <gshapiro@gshapiro.net> -uid Gregory Neil Shapiro <gshapiro@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQGiBDnnrJwRBACXxbriCa+0S4JY8rFJe9U160xXZ0hqJsvfIZtokLGDjC21G83K -4pTJRhdWlWa04HrehUtMIdT/EXKfUJCFl7vk/WGWT3/1H3xxEUQzxKu3xAJWQXJs -8t2r+Dkj0csrpLJvRyuZ5+mzzFbzFSIaWohlY8Q1Ou+39jORfyVPkGjizwCg5Czr -VDcXH2oTF3vMHsw/Bhfz3bMD/AhY8q/jmUiV09hCKb7XG6f0C+qpmBeByk5G/JFm -TRv5T34MkWQJodaUOhJtzoOsOjKQSect3c+XncIMADAGCnGPGP/6sxfuyLOgsuV6 -TXSxUvxi+E99zKTmKPFRTBuJCVATrTmHHAiLEqTZzE8DeJ6wK9kT1fRVnCKs4ycz -I7diA/44Ay2OW4PAuri2lJm7yXsiP54lNCP0eMXOQ8RSWBZhHKQl66o/pm+FsT9G -K5XloJrFa7+2XuiVoyNiva18dZkCFJzychda9pwfkkHjtidMRI97ACdUCPPQFVMB -7Dqr4wXp+qQ+tXScnZT3LMeotFwuiSfDl4VeNOswEw+F9ObCUbQsR3JlZ29yeSBO -ZWlsIFNoYXBpcm8gPGdzaGFwaXJvQGdzaGFwaXJvLm5ldD6JAFwEExECABwFAjnn -rJwFCQHhM4AECwoDBAMVAwIDFgIBAheAAAoJEIjhex385WVhDocAnjzccU2v9ekk -oUZZHoV7Bugs1npLAKDAmgzpoU3sU6zXwEQVEVq+wPpZD4kARgQQEQIABgUCOeet -DgAKCRAY9QOAJMJ4AkNKAJ93IfPLKQoBCm3TEkoQQeJWYNcRwwCdEzokbdvw/ZJw -xivyMefPJ3br/2+0K0dyZWdvcnkgTmVpbCBTaGFwaXJvIDxnc2hhcGlyb0BGcmVl -QlNELm9yZz6JAFwEExECABwFAjnnrPwFCQHhM4AECwoDBAMVAwIDFgIBAheAAAoJ -EIjhex385WVhktIAoMvD+IjOrWx+dJ3xmV+dVm+Bnu0aAJ0bSPAcx4cPpR/peHQF -JNrZgswER4kARgQQEQIABgUCOeetEgAKCRAY9QOAJMJ4AoxaAJ9OZYEXRzSmnbDo -Vukf+j5LB/fA2gCgpOQ8p/cw15Dmd27gDJ58DkTpyRi5AQ0EOeesnhAEAO9L5G1l -A3oDYFq62bifXtKS/zM2aiKND8yONxRaEuhcSqroNY5FrRy1wd4t14SA4/LzZ34D -siuNZ2+h2HD/3KTMDQ/qE/FBblNwE5ZH9cQ44a9WwGsWFDRgtuHV/7dHlZClPpwD -+tFVI7UGufhv+PPKAG3tTfRvWY2lReqVwsc3AAMFBADlrsLDoQFnE2ieS5pn3pB/ -aiMF2Z09U6fVTY+mdAdAU43xifQFGMi9vuzHNzwFGtJosK35BhfSshHTER3cT0yN -79HifRAAwKP+KIoxFhfgudZafG6BaaIOUlhPW8s9k+FtN04x6/jgRq9pz/E6MwVx -W0Rf6V5XAIFWWN3xd2JH5okATAQYEQIADAUCOeesngUJAeEzgAAKCRCI4Xsd/OVl -YeFIAKC//WKobq3b9vGn1zkBTuomGMPa3QCgm71DX+8oALnjNzj5f4+wH0CtV/iJ -AEwEGBECAAwFAjnnrJ4FCQHhM4AACgkQiOF7HfzlZWHhSACg1QVuMlj4R1DH6avL -pqMjQ7U7OMcAn2uyl3bEe476vV8RnKf83qQuw4uZ -=PgGN ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.ben;</title> - - <programlisting> -Type Bits KeyID Created Expires Algorithm Use -sec+ 1024 0x99392F7D 1998-08-23 ---------- RSA Sign & Encrypt -f16 Fingerprint16 = 3D 89 87 42 CE CA 93 4C 68 32 0E D5 36 05 3D 16 -uid Ben Smithurst <ben@scientia.demon.co.uk> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAzXffuQAAAEEAKXLh1Z3Bg5yrHVrmm9bFUKcg5VwwWyiY0M2LznqHOhhKSPd -yXkyWWaRZBSSZEa/KneVEYcUVM6CIwGrnO9h8drkxdZgPukrWqzkgwiI+zsOs8tS -XAMnnoukIrfcSq8Vcclb6YW6/nduakPLTuHvHpJXhNwP+ITp1CsPVtiZOS99AAUR -tChCZW4gU21pdGh1cnN0IDxiZW5Ac2NpZW50aWEuZGVtb24uY28udWs+iQCVAwUQ -Nd9+5CsPVtiZOS99AQGVFAP9G0tcrm8PK1MP57xbztNzPoWnP6h5MJmVH3nor7wE -dJwEHPXwGwqR92RptH4G+dHipbGSqsqWh65WyeTrzgm4pyX32Zb6AM2+Bbv+2NP0 -HdcY+qhlEYZyPsryuqySAWwUKSDxx22JD0cxQp1CDkeSdB8VBVCix5ZsPPMOm9/I -ZO0= -=IcyI ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.dcs;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/488A2DD5 2000/06/07 Daniel C. Sobral <dcs@freebsd.org> - Key fingerprint = AF 90 A6 A2 B5 8D 6C 28 37 F3 F4 47 8B 31 47 DF - Daniel C. Sobral <dcs@newsguy.com> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzk+tBAAAAEEAK5EJZPGnimL5cl9lFRpl3mYboOuN6K/ne/2oHt5CNlhBTuU -64VDPcBsM6ha+KJwSCdiO191AHnbpJSmIzNmL1VLHZunbZhJms2rf388pXO6nyu3 -GW7x2nmqg5qTTkVZAILcuqb8DF4ODF8FEwwCzDJ4ikhSxgXbsTN8YkBIii3VAAUR -tCJEYW5pZWwgQy4gU29icmFsIDxkY3NAZnJlZWJzZC5vcmc+iQCVAwUQOUVdXVUu -Hi5z0oilAQGl2gQAgWztCfCITJ7AF2e32Cq0FQkBSuh0jEIyEpZuGPJA9WbShDFL -gZW2xxLezaCHLx+tIwyT5I0oMDEY1GG5bk0Hv3X7YUZBWvdlmHMtBgW4BM/iIm9b -NHXhRecC9MEiwvUSCEXjpP6RDoP3GO3n3rraBDl/C1X89fDJMYB9gNwr+oCJAJUD -BRA5PrQQM3xiQEiKLdUBAfUBA/4vbs1IsfssAbgzoYxoxVojgaQuuipZW6bCCBgj -RSysFrNJiEi3Z9QsNKduFcZhSeYxhzwZxLb6bsoinqB60FJdZc9ivjho7ALaveYH -haZSniBayp3zQLllzfmbrbGmSD/Jvn1Qwj85ZMZ1T21VVLVhN1pqssaX7InoRYzu -oQKJVLQiRGFuaWVsIEMuIFNvYnJhbCA8ZGNzQG5ld3NndXkuY29tPokAlQMFEDk+ -vYUzfGJASIot1QEBPjAEAJMooQYQUef1jKBsYC9xh9WcvtQ45Hku+BKwU6tBlhLT -JMIn9n0guzXey4gsVcpgJcjmZEXAq+dbgL/ps63CXQAahomlszpdea9aumbak1aU -51eIEftheyZaqmM4stDvoC+pdQxWP5K3n2d/7itwFde19xQNuK9UD9iPjJnz2L47 -=oxOV ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.brian;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/666A7421 1997/04/30 Brian Somers <brian@awfulhak.org> - Key fingerprint = 2D 91 BD C2 94 2C 46 8F 8F 09 C4 FC AD 12 3B 21 - Brian Somers <brian@uk.OpenBSD.org> - Brian Somers <brian@uk.FreeBSD.org> - Brian Somers <brian@OpenBSD.org> - Brian Somers <brian@FreeBSD.org> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: 2.6.3ia - -mQCNAzNmogUAAAEEALdsjVsV2dzO8UU4EEo7z3nYuvB2Q6YJ8sBUYjB8/vfR5oZ9 -7aEQjgY5//pXvS30rHUB9ghk4kIFSljzeMudE0K2zH5n2sxpLbBKWZRDLS7xnrDC -I3j9CNKwQBzMPs0fUT46gp96nf1X8wPiJXkDUEia/c0bRbXlLw7tvOdmanQhAAUR -tCFCcmlhbiBTb21lcnMgPGJyaWFuQGF3ZnVsaGFrLm9yZz6JAJUDBRA4qXaPfU3G -z8mTvFkBASJ1A/4gAN3XvKJchXeH+mt/acNiA7+jxtAjmMfSjJiaIldYdaA9ESYi -XDamPbwQzuaMOslA3uhH+W0tNN8AbcaQ7wqWeKN1WZ7HFPzLUuaQTJhoiNTdWmaK -ZkhxiDNGA5ycJBXI5FwUb22QaB8Sj7u7vEXBpMo++zEcN+s6haSbAB8w6IkAlQMF -EDgdNQU/ZTB66ZtiFQEBBL0D/3PZ1au27HPVMN/69P3mstJLzO/a95w6koavXQph -3aRbtR7G/Gw5qRQMjwGrQ4derIcWPuONoOPXWFu2Hy7/7fYgEAsQ004MskEUImJ7 -gjCZbmASV/8CoJHtBtNTHC+63MRfD++YU0XXsN832u5+90pq1n/5c7d7jdKn/zRK -niQQiQCVAwUQNxY7OB9/qQgDWPy9AQGTsQQAk2dcz3WicxHU+AH63m0G2lOMrRHq -HZ1V2SJHPCJfiw5QzlACHpOT4Jx00TOMosHGbmEKwg0RYHTqH3BX0aNDw+5hhc3d -tqjxpm7x4gwQmAsoZZD11iA3qANXF++yZVNTRXctHWcLl+3LGjJaYwpDj3O/vOep -q+qUIuPM4+8mba2JAJUDBRA3FKmdnWdBAAxuEhUBARJtBAC9mwTXOL6cT64NwE3W -fz3pKS+pWI97PaQX/H+3mC16uN/AP8sIlpKy++IF8XGdhMvQB2Vvq2yT81G63zAI -D97lqG3krw8ikaNcLSp02B8vjhCGwSBw5iFLity+yrqQX+1gCOOkO358s9Lcb7Ua -7g4736Mpff00kXyCnGsNmiDYe4kAlQMFEDcMlqZnSj3xVLFxuQEBCKwEAJrpL9rv -YoXJztmWmpNuuSPoGKM7vm4gJ4HVzX4UxjHhMRc3c0PEHuxCboDKSAxJCatoKGN+ -bBorQ/qIElVhAo3FWxyADzNrvWsRRpSu3wzpppB9mVgzLcMdiOXWabN6toPZmNjv -QM+WKJKexlu74kqVlx00R8TrLmOms3u9VO0ViQB1AwUQNwwBLw7sAx9+veyxAQFk -RwL/V15Lm+poq/wwscyiNgBN7XpONJUX1OiLpI5f7s0/Rl3C97hIyHsIj08DfpOC -C/qnAhHb/FmYL/7TuOa+fSGULInDWkgLCl/+gsYWuh6LINY8OK43cs9d64GEYv56 -3quZiQCVAwUQNq9AjPafnz58Zbu1AQGDmwP+NLOUsBKV063jzu/AKFBRGuWeG4Ms -ZKU+wVW6upv6ELSudPV3tjNstF0y5HfOqF6Y8isxs1qvE+mUyjXRffuS4UtspScr -XT6tQIw5NgaHH31l+PqV50T4gul3DXWBokC/Dkx72REmEA4h3jH8APFnTMxStUfN -JyTMADWF4ySay82JAJUDBRAzbedc77OxBWZTbW0BAVtFA/42QelA3RBXYUtIcYGo -b+QsWkA1kGyBKQGPSS9coHdUVjClBRl3UZFmZhxAODb7cBRXmpvx2ZuMrhn/MpXT -MqPOJaE3FYm+5SoeArphsRU+T8XofxfLvRHkM3JURUjIVZdAQNvxxBso8NJG5Kay -P0Q96Vw+3sEwFK49jt14RCJy4IkAlQMFEDNzvb1sq+iWcxFJBQEBfZwD/R3KNFf9 -ype9Dea8j1YIeNZ1E3e03en1I8fMj6EmS1/L1WfFzMnfFCxZs7JgPtkBuB3CqP8f -+LOdDt6PHPqNakmI9E6fiuGfJZ3jFZYATXa0XKuIoxIJNKhqkpbF8ixJZFTxFwAA -wVYM3+sqr4qQ8FzVc5entxjyxPFNkwJwRWV+iQCVAwUQM2aiBQ7tvOdmanQhAQE7 -LgQAiN6Hz+zd8bh0nO6VizbJxWFRHPbrQWnJXGoMYyy88DyszAXC4zRshlyGUDQd -HeP/1DFCXDEu78GfDCLaJ1bm25yVR7kLxDZaEUQEbWqxfiwuzizAjkaxrW7dBbWI -LwWqrYF5TXClw+oUU/oIUW4t6t+GpAO18PLYhSMXVYErrAC0I0JyaWFuIFNvbWVy -cyA8YnJpYW5AdWsuT3BlbkJTRC5vcmc+iQCVAwUQOLfPRw7tvOdmanQhAQFzOwP/ -WAZvuOUvhsXwjI1ZGMVgQJTSBkup+kwZUUzUNAfn90YVLwgJLEkWZxp05uj3FD/C -3NW876w4/bPGrho09Tr0OsqQtY0ew+9Z7I0SGir4CwG7DxoxUjCk8GRcfi2xwswR -L0XEm+7WJyYPoLY121XM7ZUswm1rb+KkZ1Ya6LYq4fS0I0JyaWFuIFNvbWVycyA8 -YnJpYW5AdWsuRnJlZUJTRC5vcmc+iQCVAwUQNxS1nJ1nQQAMbhIVAQHGGAQAqLPZ -yhE7mh/s9odFrPiCGJjfRRJvMKT1HEJl+RhYXwVEPqyW35c79Iyf39mnPaiR4CCA -JSd6TJHzKVPFGBxLqFQnuGU1ObK+GXQWhfZKZtjq4hYGcCL+EAIu3QjLvWcBkbWd -/s9w0LFUmoLnI2UyHsk1EeivuxN2FwDUIznahWWJAJUDBRA3FKXkDu2852ZqdCEB -AeBxA/0btzY8FjtYJcRIi080aVN9UYdSM8NZYVTFSZCwBgcPYnkpI73SJLoaldYv -luMCgQpU9FDhNvCo6VmwSjxSAEkWMzeMksKaa7BuR+ORBUKLKL2Bvxz3DM11NhjI -9IsFU8ZzKuyPKB+fPBMR6nxDdgEQ954JgduPfa7shpduqVvwX7QgQnJpYW4gU29t -ZXJzIDxicmlhbkBPcGVuQlNELm9yZz6JAJUDBRA3FLVunWdBAAxuEhUBAUMLA/4/ -Qf5ZJbSHZ0HYzqkf23TgYCQrVH/dOcupA/pOJG8Xk9WAGgOuSidqP2Y/ovuvRdvg -VCf95GAe6aysLrdodHpNWbZ3BsaALEHRSeSUnjJMFGearRngplT2+ffij6t51Oqd -0SPAZ++xcyv/0MviFv1hVSW3/+jQjQm8kYkYz2xpf4kAlQMFEDcUpcgO7bznZmp0 -IQEBczAD/3b7bI98gQvrHosunwf50vjZygaH39xJL+exbGa2hreM/Z+LFutXssGo -kc7ipYR6qwxNe0kymnwTmldTbZe47O6IOSBT1jZVYdXCvrKQ5neueQ/KcrIc4gxe -n0gLKhn059+cZdt14zttDDCuOI+COVeqxMlAwQ65l+PSeejhZH8GtCBCcmlhbiBT -b21lcnMgPGJyaWFuQEZyZWVCU0Qub3JnPokAlQMFEDcUtWOdZ0EADG4SFQEBzwUD -/iDFJROA7RL0mRbRuGCvbrHx0pErSGn4fxfyc0rKnXHi2YMHLon23psO/UYb6oad -Asqe5LiNpBzt2tfZGd2V5Q5d1Q4ONUlf2eS8zcPb2mSrhf77RmpLTo2nOROWs51h -iAOXM8LEYMnRDnHfDlTzFDK3TVkSOl0TrZ22WkUsJg/GiQCVAwUQNxSlrg7tvOdm -anQhAQFlSQP+MdzI3kClfikKDupjsqCHA+BitQ41g7zRxroyWxRgZgEY6/zwptnK -uNnD8wcZ30YQn8hLzWnrDQdDYy40VP5u84slZ/dn5QMx6qplN+mhHaqKF1GNk97z -mM6PmzO1bSJ2qxtYlKsNRtfRoF1MFJD78vfnTSDP2mKCP3tCL9z/bro= -=Tq7h ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.gsutter;</title> - - <programlisting> -pub 1024D/845DFEDD 2000-10-10 Gregory S. Sutter <gsutter@zer0.org> - Key fingerprint = D161 E4EA 4BFA 2427 F3F9 5B1F 2015 31D5 845D FEDD -uid Gregory S. Sutter <gsutter@freebsd.org> -uid Gregory S. Sutter <gsutter@daemonnews.org> -uid Gregory S. Sutter <gsutter@pobox.com> -sub 2048g/0A37BBCE 2000-10-10 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Comment: '' - -mQGiBDnjW8sRBACtLAIsIja7+4PNGeKl3CWK1BDt8mJrNTU7yIpIFyU7kbGFzNDc -nKuTGXwFlI/1N964p17uvwVBq49dFTGFOzw2AEvgwl5Mb75Wsf5ztYVSir8ng0b7 -123nb09ZExWCQTMMbD6RXEVfTrIUEHazYMDIhuIU+/WkYVhNWuiaACvpJwCgjuEx -/8BANLXa9UkQt5ztgWwUUdkD/RvGakaQr4gAhVcm2mfDYjxLtm1+BxbzsDV9U2Nv -2nlXSfCyxvbTjwX+Bq4/bwR1a0KDIPvjqYAm2tQY+bsPGkjwBL0DUrHVTRK2PpPc -K/9avIFk+PYkpakPQx3saE9b67UbGk5rUCnbHU99mvqET3MtU5yRn9B8hu7owROi -EXFPA/92vhsPhcPsvTq9Wi4FlWF8MeDyZsEKA/lLUTl1A4QnbiRtC3bBvxOeoPPu -jQP25DskCdtWWcOuvHRZ6kE/WncID38oc00dqaB9xR+pi/ltnXZpOCjvU1Q0yMd5 -QcoD9Im6fLN8zo4gr2f2cwWC7TQ6TLxTYpifGK6sbC0ATdnFkbQkR3JlZ29yeSBT -LiBTdXR0ZXIgPGdzdXR0ZXJAemVyMC5vcmc+iFYEExECABYFAjnjW8sECwoDBAMV -AwIDFgIBAheAAAoJECAVMdWEXf7djlEAn2xtSRV2lRFi0H7zG9gL55Ud+NSKAJ4q -48/IHLPlbE2hXoesDXTvwBvYwIhGBBARAgAGBQI57nu4AAoJEF1SHIzmsVAWxCYA -ni+wfeykRrWXDjx6LEbwY3/tJ+vFAKDkDFVK859XVpmHin5cwYESpiWEuIhGBBAR -AgAGBQI57ovLAAoJELYkBuZbwVKhP9cAoJbEJSB3b7Gs4fhkohykCTdN6ofKAKCG -SbPBOt9GK7r+XVOPBVJBpZwHYYkAlQMFEDnujg5NVigheQUMEQEBxocEAJOVMLs6 -IKMMeWX6OiegkmdMaox86gHOOOS/94n78ClwTJ8kf4MVPF/qz9oLvCNYcSP0Ievl -MAAMgPQx4amUwwrdqO3lUWx01jrxO3L7r7PKLCT61gIfoVhjJSRvA4wVdGRBOhDF -Z18qzTkqUORDbjohknDSt6Ydxh6RwEKQM8EtiJwEEAEBAAYFAjnugY4ACgkQH3+p -CANY/L34TQP/e6VCd8sZhz8pqlaxk2zHmyCKR9gKHn1P34Fjd/wt+mMz16T7aJbr -6V0qpdvZdCkcmoQ9Q9btX9uu+GAQLUHPHLCn8bg7icw20d46LUmm1b3x3N1vOdBk -0AykVGei+TuSs7QLFQXWqwQCOfBWVk62Kw0fL1hMBVPKS0uHPotRqBOIRgQQEQIA -BgUCOe6NMAAKCRCI4Xsd/OVlYdj1AKCjZ04lHm8Dk56adtZkzdzBCx8C5gCgq3Qs -F46O590E55SsokQd7YD8kASIRgQQEQIABgUCOe6NOgAKCRAY9QOAJMJ4AlwIAJ98 -qRCL2U3KnYKrbPc+p8bzZxbTZQCglbkX8ciJVvy5oHzJO/5f+HIg0k6IRgQQEQIA -BgUCOe6TegAKCRDC/IaqJTlGi2/FAJ9l+bY/2GWpmUxtZYs0hdnejFC4IwCgivx3 -tjij0SfNTP79mbYFX3oJxo6IRgQQEQIABgUCOe6OpAAKCRBzh+KSrRDGxCeIAKDM -83nigOH0/v8H6M//+bS1LV/A0wCaAqGb5Nl+D8pnYK/hEER/YUCgVMKIRgQQEQIA -BgUCOe9ejAAKCRCTVeV2USQDllNdAJ9gmpeLdhkr5u0pWuO+o9GdUppyywCfQWuT -bYI1gUKl1z+19+YUo9+kJzWIPwMFEDnvZ0rjHjI9QK4wUhECp7YAnApxxvTZVLi4 -bsBqM+VDVnbPyVHfAJ9vj8pXkv400Zm7Mq8warkniGN45YhGBBARAgAGBQI59Hwc -AAoJEBoX/tg15TvDXCUAnR3ymarKUUkgdFBMzq/H9paGWz6xAKCOLwiMYhtecwGD -JX6s65DkkK1V6og/AwUQOfzDgnfOKcWPoS4gEQJPAQCgnvIv2HFf1nX7KoolPVvV -NYS7y+IAnA073e5i5N1HQ6+ZdDPMCm4G1wPgtCdHcmVnb3J5IFMuIFN1dHRlciA8 -Z3N1dHRlckBmcmVlYnNkLm9yZz6IVgQTEQIAFgUCOeOQigQLCgMEAxUDAgMWAgEC -F4AACgkQIBUx1YRd/t2vGACcC0MEXV6Nf9EStxuBBZJRuk112ZYAnjTE5LdyWOtg -jA6n7VgQAoYk4Ij9iEYEEBECAAYFAjnue8EACgkQXVIcjOaxUBZpNwCg7U9oUOaV -/ukWedDkV5UsUNQTfxQAn35HJBPhpAj7eszjGuAEdA9qLjuEiQCVAwUQOe6OKU1W -KCF5BQwRAQEkNAP+MszkQDMM+mcTaGzeVC5rQ9IlZ13OEWouY6vhr6W6OhhPYVtE -2KjBnpbypiUzcvlIPrjzwhM0/0M50EQX112kfNVnhq6ahBLLUwHOqAZLCw0atPJI -QrbRpvmNNduEo/xAi6VLZkhuF1VM7fdrwCx8NmHuelwQobFAORXIE+W+FbGInAQQ -AQEABgUCOe6BqAAKCRAff6kIA1j8vQc4BACOrAl4hvIfMp5aV8lkG5U+4BQVpGf6 -Ypv9X5SML382/TQ4s3ioSv+0NsiigItFphFbuGjzvCkrXucNEa3C/zzdJ7Sn8ByL -ciZuJIbUcC3/cYwi3yJ0WwqIF6ls95dJUu3Ohm6FTGYPfHJDTB5ASM9FpAHOSGOZ -J8zd9vkNpTGIDYhGBBARAgAGBQI57o0yAAoJEIjhex385WVh4cAAniRnFP7j8R0s -xXJwb+0sl5es8e6MAJ0WlFl0JlAHj7+ga56zKFPR/utduohGBBARAgAGBQI57o07 -AAoJEBj1A4AkwngC4E4An05K3XNo7BuRqdS89NeZg1A1eRq3AKCNAnLdP3ygeiLO -dtm+Em5VP8EuNohGBBARAgAGBQI57pN8AAoJEML8hqolOUaLnRQAni7rAcmZ18IN -m9t8VMarix/8LFWnAKC3RTTr8BN44zGQ/uiQ+XBtw2BmBIhGBBARAgAGBQI57o6n -AAoJEHOH4pKtEMbEensAnijhR0pU2R+DT2NR7LF0oUWn3J0GAJ0dnQ3dBIXCgnvY -DXc60qg3DFboeohGBBARAgAGBQI5716OAAoJEJNV5XZRJAOWUu8AnRVGIrjcoQyu -xTHYUPOYLPTHkSUfAJ466skILtnWEzBUYio/0PvjfSU+DIg/AwUQOe9ndOMeMj1A -rjBSEQJA3gCdFXWJQSVryXATTDQaFaWbaQZXarIAoILPRXC1iCa1d52o0zlDgPle -FwqYiQCVAwUQOe6BSgHbXdKX5jjdAQHpDQP+P3f9no+rtJeuAbQCLkDpvjBlgUiO -SpXAhF8uolfyjI9UKK63t2nov5wVc1+W2N6CPaH2f6p//xmZMu76iCX5vIbSJ9uL -sK0kaJgKRJv46PPsw6Jh+M4mtVCb4b7ad5jFF0Q2un0PZkdtBtTS7fsK51eW4/s8 -K5/94ONR6yFCSH6IPwMFEDn12AvYyjFxW6BSwxECfHQAoNf0o/mySHhQx5ipk9me -lpxpaiYrAJ402bEDRhC98dVqFR/fFpy9PD09eIg/AwUQOfO0aXfOKcWPoS4gEQL+ -KACgvfXBNMIEJWjvBlhM7VD/qE7O160AoL58uYfWHbKvVJB6ggZjip2mSFEhtCpH -cmVnb3J5IFMuIFN1dHRlciA8Z3N1dHRlckBkYWVtb25uZXdzLm9yZz6IVgQTEQIA -FgUCOeOQqQQLCgMEAxUDAgMWAgECF4AACgkQIBUx1YRd/t2fQACeLMOY1776b2k1 -PCnkkXabN+WBN5IAnjs6+dKbAq6ehSLKr7fFQYcpFOi7iEYEEBECAAYFAjnue8EA -CgkQXVIcjOaxUBY9mACgsoodTyhdveG2hFhyy5oewjYr1AYAn3dZ79qupRRZRW3q -bUO+3dRwOn/NiQCVAwUQOe6OPE1WKCF5BQwRAQFUmQP+IyI5OaPkuQx+E7KrwaM6 -LBOm6Hf5cpXqpKBZ7pVHwFajIg0g7Vg2H4p9ZkpgvqcvI3EX0cN2M59GDX92lqTF -ltqXUHkpTRwcR5HB97Yl34mlqV1L/LJGCV+QIxkpajnLkjisp2ixi7Cbd5UlYcfI -2gV+kPtjQ+yyIq1wyDFnux6InAQQAQEABgUCOe6BvAAKCRAff6kIA1j8vQ6rA/oD -ZzzfPvpnlqSxRMLVZVIX/gJgoEp3NE0TjPa4MLY7BMywS7j5l4ACOv9BTsH4/JMB -bmeSVEjH3UZtUDPqB5Kn4yot0bAokoV9JRxeRT24TIKMRbr0wp31J+QIMUZM8zJh -/VTCcfyJ2zfR9wpqDdnqocqs5WkJWp3OBoin8PvzX4hGBBARAgAGBQI57o0yAAoJ -EIjhex385WVhDSIAoM2eAx19zMc6FTzyogakO6JXxqGUAKCj2Y7nATGonAm6YJPU -KZ2Q3tjhuohGBBARAgAGBQI57o07AAoJEBj1A4AkwngCHqgAoKD+m2dlbkEG18Ej -SleHKzS6ptwVAJ9pfVOb2dyua2pkibU/3ZT6SN4dFIhGBBARAgAGBQI57pN8AAoJ -EML8hqolOUaL2HQAoI9MENn2chRdajyy+JQwbDgM0rjiAKDkviAQqwBZ+lftyr8p -R7ojLYpO2YhGBBARAgAGBQI57o6nAAoJEHOH4pKtEMbEtnoAmgMt8rPmEp2b7kI0 -yWMcqlKT1TopAKCWmeWrmJPC1/Kk/FV0P4vEbrGjx4hGBBARAgAGBQI5716OAAoJ -EJNV5XZRJAOWLpsAn1aUNLR42oidEr8QSkkq2D5vV4MuAJ9K2xS9Ye++PGcT+QIH -mITcRvGSkog/AwUQOe9nfuMeMj1ArjBSEQIa8QCeNgevIAW0INNQOKFXRXzmvUV9 -RoAAn3c4Ndwr18WojLPlG3C5faqjcOO7iD8DBRA5/MOxd84pxY+hLiARAq5wAJ95 -PeVc1G2UkrgPrCAJBxhg1cOvEQCgj5xB8X6Cm+tGWt1MppCDZ/2gXX60JUdyZWdv -cnkgUy4gU3V0dGVyIDxnc3V0dGVyQHBvYm94LmNvbT6IVgQTEQIAFgUCOeOjaQQL -CgMEAxUDAgMWAgECF4AACgkQIBUx1YRd/t2u0ACeOCvSo2zRds0L9Mika4NYlaSH -HHAAnj5OSdkKUEqUpk2OfwCybAg+lYDriEYEEBECAAYFAjnue8EACgkQXVIcjOax -UBbyaQCg7HZBHWJeCBAiScd3bgE0a1eUWnQAn1vL1vQioH2NjY2rbKX0bfEowSUK -iJwEEAEBAAYFAjnugc8ACgkQH3+pCANY/L282AP9GEpsdVGY5FQoQavTn1B7GmA3 -dhnFwT6TtP675ziDqfe7ob6qVgBq922/ERqAGAaKVhPdlCTk+3/ayzb6EJgkkQKH -X4SjfbTA8GuPE4KU7CLs3D6UgrlpxO0C3rTPEect8inwwmWtA9sgnndkAK2Wr6Fm -MZH8N3MW7W+qhRD71c2IRgQQEQIABgUCOe6NMgAKCRCI4Xsd/OVlYX+yAKCsDnbA -RHnXWJ+0URuk2+W1PV3ENwCgieqC11QPLwUWSpwsOQnQuwE1maCIRgQQEQIABgUC -Oe6NOwAKCRAY9QOAJMJ4AhgXAKCICWzasbpdixCKuH3ZHgjG/m4GIACeJEQb3+Q8 -hGMWO7DWb4Cqd79aNt+IRgQQEQIABgUCOe6TfAAKCRDC/IaqJTlGi3r9AKDhuCEr -DqwZ5ffHhS9YSCXDWKftqgCeJq9g4r01/JE0+XVVilkaPgaTsI2IRgQQEQIABgUC -Oe6OpwAKCRBzh+KSrRDGxIzzAKDaDR4685TLyRf4rdgUUpBv9XSnaQCfRWJk8Ix2 -t0qw/rLGGvbcc1fnLqmIPwMFEDnvZ1bjHjI9QK4wUhECso0AoIc66qQPaScOMZZ3 -kk1CjhpAWFxYAKDHmcPFKqZeTpFMYzBlhuagDnfTK4g/AwUQOfzDiXfOKcWPoS4g -EQI8qwCglgCDUoo6HeIzY7giTJjufcIr+p4AoKpx+vsJn+6V3kKUXMjEkZkjNP30 -uQINBDnjXC4QCAD0UBPSOUsYU8KA9uFCN/RNUtKzx/W16jjpYxqvCdKxbjb3pI7c -bmMQtwLHgIcwTC/jSHGxcJB8JcVHQeaf87XvHt06Gb4aOZAX+oAELe3T+nzSdQ1H -ttSplWPqzkH0AvoMdCf+ZmM738cTLrUHTIkgc/yGzUyXiV+m0bCsUBYgDSLgUwS2 -hCl96r8ELxPqAVVHrDJa6GPVH+zfywkWaQUknn1TiVnM8JjQiC9x7V+tix9xisys -GAG+XPH+jYn9c4q781NcpsD/hLG8IKd1AjlfSnxS9TD+WOg3g2VdzfcTy64e1z4o -6XC/XJssQQlPQYmsnVvx3LnfIZjlJSO+aTQ7AAMFCADKSxl7M4TC9nEkt3xzx9Wl -4qc73J1RqF3+tCNlj2EtzcbKBxynifjY/m3FJdJcDvbsaJUubBE3Kze+SZih9gU3 -5yZU81++Wq0KhqcpDK9LqnK3/+3YKqiXV64+Vq43dQXu1C2nsgzQ4vPZ15dgeRLb -K+4ez/Gt1fm/YJ86EA6tUGiZZo37N7wodPoBLfrL+8xRimC2kFK5vOCdsU50HZv4 -v55t2oHRi5FRWJN6GGUHeDORcCvzkeulvNxomKaAOyRMMLwzch/kF2eQs36veVwz -ENiKDub28PCuhrFXP7keq/Ybz19GIsJFSd7lemnzuTSkMoQhPjXmlshsLXhi3Km6 -iEYEGBECAAYFAjnjXC4ACgkQIBUx1YRd/t15/wCeK53sTVsgjbjDv984yiaHxGzK -z9sAn1jpwcaKsxGC0aycsTEQABKrEX0m -=Osmp ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.wollman;</title> - - <programlisting> -pub 1024D/0B92FAEA 2000-01-20 Garrett Wollman <wollman@FreeBSD.org> - Key fingerprint = 4627 19AF 4649 31BF DE2E 3C66 3ECF 741B 0B92 FAEA -sub 1024g/90D5EBC2 2000-01-20 - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: GnuPG v1.0.1 (FreeBSD) -Comment: For info see http://www.gnupg.org - -mQGiBDiHU3wRBADX+GS3fClPc0K3s2RePf2YeV+w7X3cmnWb0FLhAekfIzjLSHl8 -PWxXXQRtFyjR4KpsiwpGusX/nIJmaEoAdyqROKvpqYZPa3CjI2ldq1t1mj8lUOLo -+ktQvgR/fZoveOl+HT1yIRZDsLrQWYE96lC8Xx2Iiip/16whzhE4rJfWvwCgyb+G -a2jW0JaqmVRmyEqwzudoeqEEAKNUV5lmGRcs/GxwAJ7JRcxMI5QtoUBTfDKYyJZi -t6pudVC9STIpMoEw9m4c5KRFixdiHno/dbkECvSzpTA1qAHiC2WxeTXAz91ySTfk -iGNVlc670A+eC7Qi3ZGYhWKgKAvm0hOlYxOrU83u9naHKA+l4dOIGCQoZ7ElcfdO -77T8BADQG/nzZcaoS0o9za11YcYMAWDiEHX2JyWF7+O+qJc7UmAGMZ4YHeYOBTkT -6ybzjn5JhQtSr9YQglweYFjFYdeOmQAYow1MJxJvh0e0eoXwzOgdwJ8fzbxpHeAQ -W9uuI754sm3U80ag7RvzgeWRX7HdETCtbFF8ZCWHSE7sj29ZB7QlR2FycmV0dCBX -b2xsbWFuIDx3b2xsbWFuQEZyZWVCU0Qub3JnPohWBBMRAgAWBQI4h1N9BAsKBAMD -FQMCAxYCAQIXgAAKCRA+z3QbC5L66jfWAJ9QRUBS9u2D9s861txzAAGDur0x/gCd -ELqxcKVno9Q/l0DFb6c2ZIlkTT2IRgQQEQIABgUCOIdUpAAKCRAj54bpvu2UbtDT -AJ9anhNRzF+bPhzGsoVJG1M0+aqsWgCfV6grZerQHY0jrzh7AcGCMNNDNYaInAQQ -AQEABgUCOe58UwAKCRAff6kIA1j8vYq/BACbNYb6vCIi7/qEYF6dcBrEKf3sQ9mR -U+ign91BqI1XR6KWREzMb7C/j/8ClreLp+UYpzf2dGiMtg6wo05VM9/wNTgQ9XGQ -lm8VHRuMG6nKMxzMmugVhoKM16g4ongkLwV2GP7i/UULLl/YtBY0HHeZrvX5dFTI -e0I71GmWy38WDIkAlQMFEDnug1NNVigheQUMEQEBX6EEAKTQbXGBs5XC1NuI3UdO -DRvpRnzwY1KXlcJNWEUBFnwKqNdu23XyWT9VoMSHQwntTH1LkdYrrZJDQIlCchHS -bRoobiveoUEqqHtWx9enhADBbSyl+SeDanOd1rx3jieplg8rseeqS7j2k5EUCaus -wsk2W7zn4mpRNR25WuO8JOhjiD8DBRA57ojmGPUDgCTCeAIRAvbfAJ9SwgJaBMEF -FYpRIoNsgvnHRaBmvACfVf1DdCW4EiCwtstuphmkZU9uv0aIPwMFEDnuiMGI4Xsd -/OVlYRECVBkAnRJA6imAt+d9i2csxiReRI2xCrC/AKDjL3Wlp0ustkS1SkXiEZmX -OcGfk4hGBBARAgAGBQI57oOaAAoJECAVMdWEXf7dfowAn3es+GZFfAzNl1BY3IdA -kHBkpybbAJ0SghHeM67I6UvsD3OY4aKDu7D/g4hGBBARAgAGBQI57pd1AAoJEML8 -hqolOUaLhLEAoOj8APJHlYELhru0tPRZSfZYovDmAKD9rBzlJZzxeN36SfwkYiNW -nnl0A7kBDQQ4h1OiEAQAo095XW2DpNs2MBHGmIcaJh7oQIbfVoakZAbLXayW5h8N -OMzDXUcqHX22ZPw7pyj52D40l1S9pt2l13czy15jCVkwO1spLzMQWV/QOxjjTMFi -jqGXBCYXjWoH4Dmvm3uK2f0tfQJ1AwV0BgwoG15WGgQq0kbgJnzlUOFS1vtzqL8A -BAsD/2dT9ZClgApvVGpehgJZPkdaQEhjiUtpDsmJLdFb1fQQX2GsQ/uBNcaek+BR -JHUJNi8/vdav2+s+wgNBHf9sjbZtR5lRsjHOchUaI1N/ItC68X9H6NOoPnsMCF1x -BLma3RhBWsUKVk2f7ghYhntcLZxk/dQeBQxDcbiEPyG60sYDiEYEGBECAAYFAjiH -U6IACgkQPs90GwuS+upqQwCgtWA/+Cnjcmy99X/QfYquzh/5LJMAn3hLySDXDAZN -FBHY6YDvOcKAekCi -=Ws0Y ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - <sect2> - <title>&a.joerg;</title> - - <programlisting> -Type Bits/KeyID Date User ID -pub 1024/76A3F7B1 1996/04/27 Joerg Wunsch <joerg_wunsch@uriah.heep.sax.de> - Key fingerprint = DC 47 E6 E4 FF A6 E9 8F 93 21 E0 7D F9 12 D6 4E - Joerg Wunsch <joerg_wunsch@interface-business.de> - Joerg Wunsch <j@uriah.heep.sax.de> - Joerg Wunsch <j@interface-business.de> - ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGPfreeware 5.0i for non-commercial use - -mQCNAzGCFeAAAAEEAKmRBU2Nvc7nZy1Ouid61HunA/5hF4O91cXm71/KPaT7dskz -q5sFXvPJPpawwvqHPHfEbAK42ZaywyFp59L1GaYj87Pda+PlAYRJyY2DJl5/7JPe -ziq+7B8MdvbX6D526sdmcR+jPXPbHznASjkx9DPmK+7TgFujyXW7bjh2o/exAAUR -tCZKb2VyZyBXdW5zY2ggPGpAaW50ZXJmYWNlLWJ1c2luZXNzLmRlPokAlQMFEDHi -oSdlYKmsNPn51QEByz8D/10uMrwP7MdaXnptd1XNFhpaAPYTVAOcaKlYOGI/LLR9 -PiU3FbqXO+7INhaxFjBxa0Tw/p4au5Lq1+Mx81edHniJZNS8tz3I3goijIC3+jn2 -gnVAWnK5UZUTUVUn/JLVk/oSaIJNIMMDaw4J9xPVVkb+Fh1A+XqtPsVaYESrNp0+ -iQCVAwUQMwXkzcdm8Q+/vPRJAQEA4QQAgNNX1HFgXrMetDb+w6yEGQDkJCDAY9b6 -mA2HNeKLQAhsoZl4HwA1+iuQaCgo3lyFC+1Sf097OUTs74z5X1vCedqVoFw9CxI3 -xuctt3pJCbbN68flOlnq0WdYouWWGlFwLlh5PEy//VtwX9lqgsizlhzit+fX6BT4 -BgKi5baDhrWJAJUDBRAyCKveD9eCJxX4hUkBAebMA/9mRPy6K6i7TX2RjUKSl2p5 -oYrXPk12Zsw4ijuktslxzQhOCyMSCGK2UEC4UM9MXp1H1JZQxN/DcfnM7VaUt+Ve -0wZ6DC9gBSHJ1hKVxHe5XTj26mIr4rcXNy2XEDMK9QsnBxIAZnBVTjSOLdhqqSMp -3ULLOpBlRL2RYrqi27IXr4kAlQMFEDGpbnd1u244dqP3sQEBJnQD/RVSAzgf4uor -v3fpbosI0LE3LUufAYGBSJNJnskeKyudZkNkI5zGGDwVneH/cSkKT4ORooeqcTBx -KeMaMuXPVl30QahgNwWjfuTvl5OZ8orsQGGWIn5FhqYXsKkjEGxIOBOfvvlVQ0Ub -cR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPUiQCVAwUQNRkF14HR8QVbfEftAQHb6wQA -uXzEE+LHIk1kSINIgXX0+UcFpPc1rctiBkzZZhgzFvGC/kYrsI/GVYE4erL4sVXA -NJqZxaMC/AAaGfaduALRFXNidKinMJBrZg3NCtq7cqrc/3aDmZJ2IaHvxoS+XC/i -RVoeTk+jb6wcliqMkf41UlHsijyALtVK2Dd78T8GhJq0LUpvZXJnIFd1bnNjaCA8 -am9lcmdfd3Vuc2NoQHVyaWFoLmhlZXAuc2F4LmRlPokAlQMFEDQUWQGzWmLrWZ8y -PQEB8MID+gJ+SOuG9HBEKlIvySUnVgOhQl2bD6/iclynDc6lhdvAo48sKWwTsrco -JCxwd6Xtq5/3Wet6QDBute/0KWnRN6Bh4BA2PDm9n18vpRnmXd8fwTYYYDv6SqA1 -azUrECcbkZ1S8n2+LKtabx2pZEaj6WgNaVnXYvY6AAN+nuNVlMjWiQCVAwUQNA+s -uh9/qQgDWPy9AQHZdAQAr/5KxA8JP9fhEH88FvFSvbwakYkyfcBp8BoDemVjDedv -g41uoTD20m2h8CfhR4atqJbDycdhHYMDOgCNHo7O5fdO1RX7nsEjOtM8dw2RvqHx -8+4dT50XNH4s2g9oYmwV6i/rD5SDqpL3BrkUYMCBpGgsdLIHFxFWgJs4RpLlLkSJ -AJUDBRAzkGS1ZWCprDT5+dUBAYo/A/46JaGjdmbYYqmUSOJnnPHfLy6nNv6vVC61 -vTyOvYTCNrTiEuDR8Ku3oB3cOhWrF7g86CEimYczg7i1xb3ZMdCKXvQIvN8LG19R -zp4POg/eSsPX8bCmbaEauZgD1v97P36va8oFudSE+YKCXHml/UjMdT1HZfJDP1e7 -sUjZto5JmokAlQMFEDIIhZl1u244dqP3sQEBUzMD/jVUimHfqX7I71YYqQQH41ht -g7PZb+TKLviRcu8t1NdxFgVoJJk5FKxAo8Y0ys9lSgugArETbkCgKCXm2jCqv+wJ -y7QDQwy8l11S+VDZP7KVKkaZZyGqhcI3sV0bLGtnnPPHMsi+1yKjqRod3vpfHImm -W0IBK6l0PnecS3Ge7yxGiQCVAwUQNRkFNoHR8QVbfEftAQH59wP6Ar3emiJ3gseU -ayKAjx2SH9lDVMsvIJW8cZoeEsDfoHlTEbz448KLKuh5rKOBAU++WBFtXQoIbroi -4y+zVpJ7z2xJ6sHU/xo6M72QCvieahT4y3C6f1mPsZyjlMRpFoCpBddU+U8kbkqT -TBVjNF5DNyhj1keIR35DJNpevpCCE6q0MUpvZXJnIFd1bnNjaCA8am9lcmdfd3Vu -c2NoQGludGVyZmFjZS1idXNpbmVzcy5kZT6JAJUDBRAyCIX0dbtuOHaj97EBAVqC -A/0YQZvqrVvobtn6gI/XfAlYBCiboK8WSKV7gihbzvmwoELaILfRF/kyYeLPFFHX -BZMhCLvAk9gt0a69YK73JH8b604M0s77WMr9dO9l9xpFWPkpVDATAK3ZdajVtt6E -+0OefGo57Gi9OuVyeZux2nIE04pIqH2BvItbO067BHquj4kAlQMFEDWRxZdlYKms -NPn51QEBzt4D/RALkWpNJNTtlyKE0NBeSyRoci9OCfcYI42R+39HoJnLPAgT+aFc -EqinmEcsBvwECjJVrrwBN3f6/rESGp+JaYNiw5bz17lmouh27FEvWETy8QfcQl1+ -Ck7HJqkMs1rpcLwhWvMmWlx49gBPJAJwcVSmhsuSVQKp5iSFDn5pbZCTiQCVAwUQ -NRkFU4HR8QVbfEftAQH2vQP+PzI1rHZq4Q6/E9RS3zW/HDuzByASi3A9iM5MARqi -ACLug+plFatfHfEaWII8nKytqY+kC3gaDESZ8+PFvGRZvMCRBrD5nv9YUC7LJIAX -NFGklsyIEvDAtlO/Q94LjgCct3ta6ypA45ZxaMkRdCkZer1EPjSloLrUBRpDhMeA -otu0IkpvZXJnIFd1bnNjaCA8akB1cmlhaC5oZWVwLnNheC5kZT6JAJUDBRAxpL3U -PiAdBSUb0JkBAZg7BACE+mKhsrd39/P6NattCCOSg76Pf2CVgZdvbb7qK4SmsVGz -+58pi2OWM1M0rcHgNZKTIg9rBy47gui2KOnqOR7ZuyMVJJqyEZZywmWmfCy/sR4U -i1PehZNNNBAi09u03ItbozrEH6Msa1oC8mp86XOA70Et8e4DYtj5a9tVbjjtJYkA -lQMFEDGpZGx1u244dqP3sQEBcMED/j2vNkHlqSRNJu3+A13fw4mAL4fw3l1rbm9X -10PcqgC9d9Z/Ds7EizG9D8Bv6sma6SutbE92wL7VZTX7WsZrg+8mn9UlEN6zZrAa -uf6I7v9xChIhXOILbsmlxu+Mu8tVwEiLLXJP9G8n7ztreM9Ee3dUUZykWHgrKTHF -I2LIbKCXiQCVAwUQMYJQHfUVW/uOVC1dAQHkqAP+Igll7mUWQ+vYH8KvsEoxUGi3 -X8lK7Tk2weAlne4rXnDiZW009lwWL90puf6pEzosoMV78YXQdkP9kPUUm3zJCPMX -bDfjQH4XYYYQ7CcKWpkO0QCqcgHMz8QJBCof7oGLyCmQVmsWCDl443uKSqa6wOc6 -VhK0z8IF+ClJtHyQOYWJAD8DBRA0Pun7CKyxtqPXKpQRAlWJAKC+2KEpwmX/f5rO -+QXv4ldCIKQ+JgCgqcjGveuHvlv8ehkHrucnz8VrHjqJAJUDBRA1kcVlZWCprDT5 -+dUBAeX7A/0aZkBJdd0EKhje2rhXdoE99fr5jeg9utB0pACqgMb1hBcnVRi3SVZ4 -ZBQIfqY26LeZP+WLUqGfTx6BSsBys13WlBT9PZuicuWkDHUtGX9zUl4qMsxGQkGj -NXdmn0/eCnheZP5ROvYXD15A0kjd626PxxftbyQKTuhKTWCT2jSnsYkAlQMFEDGF -mgWB0fEFW3xH7QEBhr8D/2kclzpVUU2wvwMT+POA8M9iDKNcZAUBQI8/j+QVZ1VB -3laHKKkpdvGrTUl/PVLvt6tSHIdDQrAOuPq9M4DMLIqS1jZr16+BhZ+7ffZJ2JpO -bFVOK5wmzVSixigPB1ytIkKqhJ9JQpMZOUKJ24n2E6Mr79fLJK1a4EMWuHZ5uXNk -=grTK ------END PGP PUBLIC KEY BLOCK-----</programlisting> - </sect2> - - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml deleted file mode 100644 index 0b33eff446..0000000000 --- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml +++ /dev/null @@ -1,398 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml,v 1.17 2000/06/14 20:30:36 jim Exp $ ---> - -<chapter id="policies"> - <title>Source Tree Guidelines and Policies</title> - - <para><emphasis>Contributed by &a.phk;.</emphasis></para> - - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> - - <sect1 id="policies-maintainer"> - <title><makevar>MAINTAINER</makevar> on Makefiles</title> - - <para>June 1996.</para> - - <para>If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a - - <programlisting> -MAINTAINER= email-addresses</programlisting> - - line to the <filename>Makefile</filename>s covering this portion of the - source tree.</para> - - <para>The semantics of this are as follows:</para> - - <para>The maintainer owns and is responsible for that code. This means - that he is responsible for fixing bugs and answer problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate.</para> - - <para>Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try and have the - changes reviewed by someone else if at all possible.</para> - - <para>It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - doesn't have to be a committer and it can easily be a group of - people.</para> - </sect1> - - <sect1 id="policies-contributed"> - <title>Contributed Software</title> - - <para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para> - - <para>June 1996.</para> - - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are perl, gcc and patch.</para> - - <para>Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the <quote>official</quote> method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - <quote>official</quote> versions of the source by everyone (even without - cvs access). This will make it significantly easier to return changes - to the primary developers of the contributed software.</para> - - <para>Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions.</para> - - <note> - <para>Because of some unfortunate design limitations with the RCS file - format and CVS's use of vendor branches, minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch. <quote>Spelling - fixes</quote> are explicitly included here under the - <quote>cosmetic</quote> category and are to be avoided for files with - revision 1.1.x.x. The repository bloat impact from a single character - change can be rather dramatic.</para> - </note> - - <para>The <application>TCL</application> embedded programming - language will be used as example of how this model works:</para> - - <para><filename>src/contrib/tcl</filename> contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - <filename>mac</filename>, <filename>win</filename> and - <filename>compat</filename> subdirectories were eliminated before the - import</para> - - <para><filename>src/lib/libtcl</filename> contains only a "bmake style" - <filename>Makefile</filename> that uses the standard - <filename>bsd.lib.mk</filename> makefile rules to produce the library - and install the documentation.</para> - - <para><filename>src/usr.bin/tclsh</filename> contains only a bmake style - <filename>Makefile</filename> which will produce and install the - <command>tclsh</command> program and its associated man-pages using the - standard <filename>bsd.prog.mk</filename> rules.</para> - - <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of - shell-scripts that can be of help when the tcl software needs updating. - These are not part of the built or installed software.</para> - - <para>The important thing here is that the - <filename>src/contrib/tcl</filename> directory is created according to - the rules: It is supposed to contain the sources as distributed (on a - proper CVS vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. The 'easy-import' tool on - freefall will assist in doing the import, but if there are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it <quote>works out</quote>. CVS is not forgiving of - import accidents and a fair amount of effort is required to back out - major mistakes.</para> - - <para>Because of the previously mentioned design limitations with CVS's - vendor branches, it is required that <quote>official</quote> patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and "committed", as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts.</para> - - <para>Since many packages contain files that are meant for compatibility - with other architectures and environments that FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall <emphasis>not</emphasis> be removed.</para> - - <para>If it seems easier, the <command>bmake</command> - <filename>Makefile</filename>s can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - <filename>src/tools</filename> directory along with the port itself so - that it is available to future maintainers.</para> - - <para>In the <filename>src/contrib/tcl</filename> level directory, a file - called <filename>FREEBSD-upgrade</filename> should be added and it - should states things like:</para> - - <itemizedlist> - <listitem> - <para>Which files have been left out</para> - </listitem> - - <listitem> - <para>Where the original distribution was obtained from and/or the - official master site.</para> - </listitem> - - <listitem> - <para>Where to send patches back to the original authors</para> - </listitem> - - <listitem> - <para>Perhaps an overview of the FreeBSD-specific changes that have - been made.</para> - </listitem> - </itemizedlist> - - <para>However, please do not import <filename>FREEBSD-upgrade</filename> - with the contributed source. Rather you should <command>cvs add - FREEBSD-upgrade ; cvs ci</command> after the initial import. Example - wording from <filename>src/contrib/cpio</filename> is below:</para> - - <programlisting> -This directory contains virgin sources of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. New versions or -official-patch versions must be imported. Please remember to import with -"-ko" to prevent CVS from corrupting any vendor RCS Ids. - -For the import of GNU cpio 2.4.2, the following files were removed: - - INSTALL cpio.info mkdir.c - Makefile.in cpio.texi mkinstalldirs - -To upgrade to a newer version of cpio, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Remove the files listed above and any others that don't apply to - FreeBSD. - - 3. Use the command: - cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU cpio_<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -ko -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU cpio_2_4_2 - - 4. Follow the instructions printed out in step 3 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to cpio, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the GNU branch. - -All local changes should be submitted to "cpio@gnu.ai.mit.edu" for -inclusion in the next vendor release. - -obrien@FreeBSD.org - 30 March 1997</programlisting> - </sect1> - - <sect1 id="policies-encumbered"> - <title>Encumbered Files</title> - - <para>It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree.</para> - - <orderedlist> - <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> - </listitem> - - <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> - </listitem> - - <listitem> - <para>A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended).</para> - </listitem> - - <listitem> - <para>Any encumbered file requires specific approval from the <link - linkend="staff-core">Core team</link> before it is added to the - CVS repository.</para> - </listitem> - - <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> - </listitem> - - <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> - </listitem> - - <listitem> - <para>Object files are named - <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> - </listitem> - - <listitem> - <para>Kernel files;</para> - - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> - </listitem> - - <listitem> - <para>Should always be in <filename>LINT</filename>, but the <link - linkend="staff-core">Core team</link> decides per case if it - should be commented out or not. The <link - linkend="staff-core">Core team</link> can, of course, change - their minds later on.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides whether or not it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>User-land files;</para> - - <orderedlist> - <listitem> - <para>The <link linkend="staff-core">Core team</link> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <para>The <link linkend="staff-who">Release Engineer</link> - decides if it goes in to the release.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </sect1> - - <sect1 id="policies-shlib"> - <title>Shared Libraries</title> - - <para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 - December 1996.</emphasis></para> - - <para>If you are adding shared library support to a port or other piece of - software that doesn't have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software.</para> - - <para>The three principles of shared library building are:</para> - - <itemizedlist> - <listitem> - <para>Start from <literal>1.0</literal></para> - </listitem> - - <listitem> - <para>If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number)</para> - </listitem> - - <listitem> - <para>If there is an incompatible change, bump major number</para> - </listitem> - </itemizedlist> - - <para>For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax etc. will force the major version number to change.</para> - - <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out - dynamic linker does not handle version numbers of the form - <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> - well. Any version number after the <replaceable>y</replaceable> - (ie. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the <quote>micro</quote> revision, - <command>ld.so</command> will link with the higher one. Ie: if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(highest - available)</replaceable>.</para> - - <note> - <para><command>ld.so</command> will always use the highest - <quote>minor</quote> revision. Ie: it will use - <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> - </note> - - <para>In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our <filename>Makefile</filename>s "do the right thing" - based on the type of system.</para> - - <para>For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is - our policy to change the major shared library version number only once - between major OS releases. Ie: X.0 to (X+1).0. When you make a - change to a system library that requires the version number to be - bumped, check the <filename>Makefile</filename>'s commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml deleted file mode 100644 index 7dc3d3cb29..0000000000 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml +++ /dev/null @@ -1,1007 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.110 2000/06/09 18:08:44 nik Exp $ ---> - -<chapter id="ports"> - <title>Installing Applications: The Ports collection</title> - - <para><emphasis>Rewritten by &a.jim;, 22 November 1999. Original work - by various people.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>The FreeBSD Ports collection allows you to compile and install a - very wide range of applications with a minimum amount of - effort.</para> - - <para>In general, it is a group of <link - linkend="ports-skeleton">skeletons</link> - which contain a minimal set of items needed to make an application - compile and install cleanly on FreeBSD.</para> - - <para>Even with all the hype about open standards, getting a program - to compile on various UNIX platforms can be a tricky task. - Occasionally, you might be lucky enough to find that the program you - want compiles cleanly on your system, install everything into all - the right directories, and run flawlessly - <quote>out-of-the-box</quote>, but this behavior is somewhat rare. - Most of the time, you find yourself needing to make modifications in - order to get the program to work. This is where the FreeBSD Ports - collection comes to the rescue.</para> - - <para>The general idea behind the Ports collection is to eliminate all - of the messy steps involved with making things work properly so that - the installation is simple and very painless. With the Ports - collection, all of the hard work has already been done for you, and - you are able to install any of the Ports collection ports by simply - typing <command>make install</command>.</para> - </sect1> - - <sect1 id="ports-using"> - <title>Using the Ports Collection</title> - - <para>The following sections provide basic instructions on using the - ports collection to install or remove programs from your - system.</para> - - <sect2 id="ports-skeleton"> - <title>Installing Ports</title> - - <para>The first thing that should be explained - when it comes to the Ports collection is what is actually meant - by a <quote>skeleton</quote>. In a nutshell, a port skeleton is a - minimal set of files that are needed for a program to compile and - install cleanly on FreeBSD. Each port skeleton includes:</para> - - <itemizedlist> - <listitem> - <para>A <filename>Makefile</filename>. The - <filename>Makefile</filename> contains various statements that - specify how the application should be compiled and where it - should be installed on your system</para> - </listitem> - - <listitem> - <para>A <filename>files</filename> directory. The - <filename>files</filename> directory contains a file named - <filename>md5</filename>. This file is named after the MD5 - algorithm used to determine ports checksums. A checksum is a - number generated by adding up all the data in the file you - want to check. If any characters change, the checksum will - differ from the original and an error message will be - displayed so you are able to investigate the changes.</para> - - <para>The <filename>files</filename> directory can also contain - other files that are required by the port but do not belong - elsewhere in the directory structure.</para> - </listitem> - - <listitem> - <para>A <filename>patches</filename> directory. This directory - contains patches to make the program compile and install on - your FreeBSD system. Patches are basically small files that - specify changes to particular files. They are in plain text - format, and basically say <quote>Remove line 10</quote> or - <quote>Change line 26 to this ...</quote>. Patches are also - known as <quote>diffs</quote> because they are generated by the - <application>diff</application> program.</para> - </listitem> - - <listitem> - <para>A <filename>pkg</filename> directory. This directory - normally contains three files. Occasionally, there will be - more than three, but it depends on the port. Most only - require three. The files are:</para> - - <itemizedlist> - <listitem> - <para><filename>COMMENT</filename>. This is a one-line - description of the program.</para> - </listitem> - - <listitem> - <para><filename>DESCR</filename>. This is a more detailed, - often multiple-line, description of the program.</para> - </listitem> - - <listitem> - <para><filename>PLIST</filename>. This is a list of all the - files that will be installed by the port. It also tells - the ports system what files to remove upon - deinstallation.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - <para>Now that you have enough background information to know what - the Ports collection is used for, you are ready to install your - first port. There are two ways this can be done, and each is - explained below.</para> - - <para>Before we get into that however, you will need to choose a - port to install. There are a few ways to do this, with the - easiest method being the <ulink - url="http://www.freebsd.org/ports/">ports listing on the FreeBSD - web site</ulink>. You can browse through the ports listed there - or use the search function on the site. Each port also includes - a description so you can read a bit about each port before - deciding to install it.</para> - - <para>Another method is to use the <command>whereis</command> - command. To use <command>whereis</command>, simply type - <quote><command>whereis <program you want to - install></command></quote> at the prompt, and if it is found on - your system, you will be told where it is, like so:</para> - - <screen>&prompt.root; <userinput>whereis xchat</userinput> -xchat: /usr/ports/irc/xchat -&prompt.root;</screen> - - <para>This tells us that xchat (an irc client) can be found in the - <filename>/usr/ports/irc/xchat</filename> directory.</para> - - <para>Yet another way of finding a particular port is by using the - Ports collection's built-in search mechanism. To use the search - feature, you will need to be in the - <filename>/usr/ports</filename> directory. Once in that - directory, run <command>make search key=program-name</command> - where <quote>program-name</quote> is the name of the program you - want to find. For example, if you were looking for xchat:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make search key=xchat</userinput> -Port: xchat-1.3.8 -Path: /usr/ports/irc/xchat -Info: An X11 IRC client using the GTK+ toolkit, and optionally, GNOME -Maint: jim@FreeBSD.org -Index: irc -B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6 - imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1 -R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b - png-1.0.3 tiff-3.5.1</screen> - - <para>The part of the output you want to pay particular attention - to is the <quote>Path:</quote> line, since that tells you where to - find it. The other information provided is not needed in order - to install the port directly, so it will not be covered - here.</para> - - <note> - <para>You must be the <username>root</username> user to install - ports.</para> - </note> - - <para>Now that you have found a port you would like to install, you - are ready to do the actual installation.</para> - - <sect3 id="ports-cd"> - <title>Installing ports from a CDROM</title> - - <para>As you may have guessed from the title, everything - described in this section assumes you have a FreeBSD CDROM set. - If you do not, you can order one from the <ulink - url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.</para> - - <para>Assuming that your FreeBSD CDROM is in the drive and is - mounted on <filename>/cdrom</filename> (and the mount point - <emphasis>must</emphasis> be <filename>/cdrom</filename>), - you are ready to install the port. To begin, change directories - to the directory where the port you want to install lives:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/irc/xchat</userinput></screen> - - <para>Once inside the xchat directory, you will see the port - skeleton. The next step is to compile (also called build) the - port. This is done by simply typing <command>make</command> at - the prompt. Once you have done so, you should see something - like this:</para> - - <screen>&prompt.root; <userinput>make</userinput> ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from file:/cdrom/ports/distfiles/. -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -&prompt.root;</screen> - - <para>Take notice that once the compile is complete you are - returned to your prompt. The next step is to install the - port. In order to install it, you simply need to tack one word - onto the <command>make</command> command, and that word is - <command>install</command>:</para> - - <screen>&prompt.root; <userinput>make install</userinput> -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root;</screen> - - <para>Once you are returned to your prompt, you should be able to - run the application you just installed.</para> - - <note> - <para>You can save an extra step by just running <command>make - install</command> instead of <command>make</command> and - <command>make install</command> as two separate steps.</para> - </note> - - <note> - <para>Please be aware that the licenses of a few ports do not - allow for inclusion on the CDROM. This could be for various - reasons, including things such as as registration form needs - to be filled out before downloading, if redistribution is not - allowed, and so on. If you wish to install a port not - included on the CDROM, you will need to be online in order to - do so (see the <link linkend="ports-inet">next - section</link>).</para> - </note> - </sect3> - - <sect3 id="ports-inet"> - <title>Installing ports from the Internet</title> - - <para>As with the last section, this section makes an assumption - that you have a working Internet connection. If you do not, - you will need to do the <link linkend="ports-cd">CDROM - installation</link>.</para> - - <para>Installing a port from the Internet is done exactly the same - way as it would be if you were installing from a CDROM. The - only difference between the two is that the program's source - code is downloaded from the Internet instead of pulled from the - CDROM.</para> - - <para>The steps involved are identical:</para> - - <screen>&prompt.root; <userinput>make install</userinput> ->> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system. ->> Attempting to fetch from http://xchat.org/files/v1.3/. -Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100% -305543 bytes transferred in 2.9 seconds (102.81 Kbytes/s) -===> Extracting for xchat-1.3.8 ->> Checksum OK for xchat-1.3.8.tar.bz2. -===> xchat-1.3.8 depends on executable: bzip2 - found -===> xchat-1.3.8 depends on executable: gmake - found -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -===> Patching for xchat-1.3.8 -===> Applying FreeBSD patches for xchat-1.3.8 -===> Configuring for xchat-1.3.8 -... -[configure output snipped] -... -===> Building for xchat-1.3.8 -... -[compilation snipped] -... -===> Installing for xchat-1.3.8 -===> xchat-1.3.8 depends on shared library: gtk12.2 - found -===> xchat-1.3.8 depends on shared library: Imlib.5 - found -===> xchat-1.3.8 depends on shared library: X11.6 - found -... -[install routines snipped] -... -===> Generating temporary packing list -===> Installing xchat docs in /usr/X11R6/share/doc/xchat -===> Registering installation for xchat-1.3.8 -&prompt.root;</screen> - - <para>As you can see, the only difference is the line that tells - you where the system is fetching the port from.</para> - - <para>That about does it for installing ports onto your system. - In the section you will learn how to remove a port from your - system.</para> - </sect3> - </sect2> - - <sect2 id="ports-removing"> - <title>Removing Installed Ports</title> - - <para>Now that you know how to install ports, you are probably - wondering how to remove them, just in case you install one and - later on you decide that you installed the wrong port. The next - few paragraphs will cover just that.</para> - - <para>Now we will remove our previous example (which was xchat for - those of you not paying attention). As with installing ports, - the first thing you must do is change to the port directory, - which if you remember was - <filename>/usr/ports/irc/xchat</filename>. After you change - directories, you are ready to uninstall xchat. This is done with - the <command>make deinstall</command> command (makes sense - right?):</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/irc/xchat</userinput> -&prompt.root; <userinput>make deinstall</userinput> -===> Deinstalling for xchat-1.3.8 -&prompt.root;</screen> - - <para>That was easy enough. You have now managed to remove xchat - from your system. If you would like to reinstall it, you can do - so by running <command>make reinstall</command> from the - <filename>/usr/ports/irc/xchat</filename> directory.</para> - </sect2> - </sect1> - - <sect1 id="ports-trouble"> - <title>Troubleshooting</title> - - <para>The following sections cover some of the more frequently asked - questions about the Ports collection and some basic troubleshooting - techniques, and what do to if a <link - linkend="ports-broken">port is broken.</link></para> - - <sect2 id="ports-questions"> - <title>Some Questions and Answers</title> - - <qandaset> - <qandaentry> - <question> - <para>I thought this was going to be a discussion about - modems??!</para> - </question> - - <answer> - <para>Ah, you must be thinking of the serial ports on the back - of your computer. We are using <quote>port</quote> here to - mean the result of <quote>porting</quote> a program from one - version of UNIX to another.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I thought you were supposed to use packages to install - extra programs?</para> - </question> - - <answer> - <para>Yes, that is usually the quickest and easiest way of - doing it.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>So why bother with ports then?</para> - </question> - - <answer> - <para>Several reasons:</para> - - <orderedlist> - <listitem> - <para>The licensing conditions of some software - distributions forbid binary distribution. They must be - distributed as source code.</para> - </listitem> - - <listitem> - <para>Some people do not trust binary distributions. At - least with source code, you can (in theory) read through - it and look for potential problems yourself.</para> - </listitem> - - <listitem> - <para>If you have local patches, you will need the source in - order to apply them.</para> - </listitem> - - <listitem> - <para>You might have opinions on how a program should be - compiled that differ from the person who did the - package—some people have strong views on what - optimization settings should be used, whether to build - debug versions and then strip them or not, and so on.</para> - </listitem> - - <listitem> - <para>Packages are normally built with quite conservative - settings. If a port has a compilation option to use code - for a specific processor, or a particular add-on board you - can enable this yourself in the port, without the people - making the package having to produce many, many different - packaged versions.</para> - - <para>The most obvious exception to this rule is paper sizes. - If a package can be provided with default support for - different paper sizes we will often provide multiple - packages, one per paper size.</para> - </listitem> - - <listitem> - <para>Some people like having code around, so they can read - it if they get bored, hack it, borrow from it (license - permitting, of course), and so on.</para> - </listitem> - - <listitem> - <para>If you ain't got the source, it ain't software! - <!-- smiley -->;-)</para> - </listitem> - </orderedlist> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para id="ports-patch">What is a patch?</para> - </question> - - <answer> - <para>A patch is a small file that specifies how to go from - one version of a file to another. It contains plain text, - and basically says things like <quote>delete line 23</quote>, - <quote>add these two lines after line 468</quote>, or - <quote>change line 197 to this</quote>. They are also known - as diffs because they are generated by the - <application>diff</application> program.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para id="ports-tarball">What is all this about - tarballs?</para> - </question> - - <answer> - <para>It is a file ending in <filename>.tar</filename>, or - with variations such as <filename>.tar.gz</filename>, - <filename>.tar.Z</filename>, <filename>.tar.bz2</filename>, - and even <filename>.tgz</filename>.</para> - - <para>Basically, it is a directory tree that has been archived - into a single file (<filename>.tar</filename>) and - optionally compressed (<filename>.gz</filename>). This - technique was originally used for <emphasis>T</emphasis>ape - <emphasis>AR</emphasis>chives (hence the name - <command>tar</command>), but it is a widely used way of - distributing program source code around the Internet.</para> - - <para>You can see what files are in them, or even extract them - yourself by using the standard UNIX tar program, which comes - with the base FreeBSD system, like this:</para> - - <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput> -&prompt.user; <userinput>tar tvf foobar.tar</userinput> -&prompt.user; <userinput>tar xvf foobar.tar</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para id="ports-checksum">And a checksum?</para> - </question> - - <answer> - <para>It is a number generated by adding up all the data in - the file you want to check. If any of the characters - change, the checksum will no longer be equal to the total, - so a simple comparison will allow you to spot the - difference.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I did what you said for compiling ports from a CDROM and - it worked great until I tried to install the kermit - port.</para> - - <screen>&prompt.root; <userinput>make install</userinput> ->> cku190.tar.gz doesn't seem to exist on this system. ->> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen> - - <para>Why can it not be found? Have I got a dud CDROM?</para> - </question> - - <answer> - <para>As was explained in the <link - linkend="ports-cd">compiling ports from CDROM</link> - section, some ports cannot be put on the CDROM set - due to licensing restrictions. Kermit is an example of - that. The licensing terms for kermit do not allow us to put - the tarball for it on the CDROM, so you will have to fetch - it by hand—sorry!</para> - - <para>The reason why you got all those error messages was - because you were not connected to the Internet at the time. - Once you have downloaded it from any of the MASTER_SITES - (listed in the Makefile), you can restart the install - process.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I did that, but when I tried to put it into - <filename>/usr/ports/distfiles</filename> I got some error - about not having permission.</para> - </question> - - <answer> - <para>The ports mechanism looks for the tarball in - <filename>/usr/ports/distfiles</filename>, but you will not - be able to copy anything there because it is symlinked to - the CDROM, which is read-only. You can tell it to look - somewhere else by doing:</para> - - <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/where/you/put/it</replaceable> install</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Does the ports scheme only work if you have everything - in <filename>/usr/ports</filename>? My system administrator - says I must put everything under - <filename>/u/people/guests/wurzburger</filename>, but it - does not seem to work.</para> - </question> - - <answer> - <para>You can use the <makevar>PORTSDIR</makevar> and - <makevar>PREFIX</makevar> variables to tell the ports - mechanism to use different directories. For - instance,</para> - - <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen> - - <para>will compile the port in - <filename>/u/people/guests/wurzburger/ports</filename> and - install everything under - <filename>/usr/local</filename>.</para> - - <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen> - - <para>will compile it in <filename>/usr/ports</filename> and - install it in - <filename>/u/people/guests/wurzburger/local</filename>.</para> - - <para>And of course,</para> - - <screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen> - - <para>will combine the two (it is too long to write fully on - the page, but it should give you the general idea).</para> - - <para>If you do not fancy typing all that in every time you - install a port, it is a good idea to put these variables - into your environment. Read the man page for your shell for - instructions on doing so.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I do not have a FreeBSD CDROM, but I would like to have - all the tarballs handy on my system so I do not have to wait - for a download every time I install a port. Is there any - way to get them all at once?</para> - </question> - - <answer> - <para>To get every single tarball for the Ports collection, - do:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - <para>For all the tarballs for a single ports directory, - do:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> -&prompt.root; <userinput>make fetch</userinput></screen> - - <para>and for just one port—well, I think you have - guessed already.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I know it is probably faster to fetch the tarballs from - one of the FreeBSD mirror sites close by. Is there any way - to tell the port to fetch them from servers other than the - ones listed in the MASTER_SITES?</para> - </question> - - <answer> - <para>Yes. If you know, for example, that <hostid - role="fqdn">ftp.FreeBSD.org</hostid> is much closer to you - than the sites listed in <makevar>MASTER_SITES</makevar>, - do as follows:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> -&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \ -ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I want to know what files <command>make</command> is - going to need before it tries to pull them down.</para> - </question> - - <answer> - <para><command>make fetch-list</command> will display a list - of the files needed for a port.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is there any way to stop the port from compiling? I - want to do some hacking on the source before I install it, - but it is a bit tiresome to watch it and hit control-C every - time.</para> - </question> - - <answer> - <para>Doing <command>make extract</command> will stop it - after it has fetched and extracted the source code.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I am trying to make my own port and I want to be able - to stop it compiling until I have had a chance to see if my - patches worked properly. Is there something like - <command>make extract</command>, but for patches?</para> - </question> - - <answer> - <para>Yep, <command>make patch</command> is what you want. - You will probably find the <makevar>PATCH_DEBUG</makevar> - option useful as well. And by the way, thank you for your - efforts!</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I have heard that some compiler options can cause bugs. - Is this true? How can I make sure that I compile ports - with the right settings?</para> - </question> - - <answer> - <para>Yes, with version 2.6.3 of <command>gcc</command> (the - version shipped with FreeBSD 2.1.0 and 2.1.5), the - <option>-O2</option> option could result in buggy code - unless you used the <option>-fno-strength-reduce</option> - option as well. (Most of the ports do not use - <option>-O2</option>). You <emphasis>should</emphasis> be - able to specify the compiler options used by something - like:</para> - - <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen> - - <para>or by editing <filename>/etc/make.conf</filename>, but - unfortunately not all ports respect this. The surest way - is to do <command>make configure</command>, then go into - the source directory and inspect the Makefiles by hand, but - this can get tedious if the source has lots of - sub-directories, each with their own Makefiles.</para> - - <para>The default FreeBSD compiler options are quite conservative, - so if you have not changed them you should not have any - problems.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>There are so many ports it is hard to find the one I - want. Is there a list anywhere of what ports are - available?</para> - </question> - - <answer> - <para>Look in the <filename>INDEX</filename> file in - <filename>/usr/ports</filename>. If you would like to - search the ports collection for a keyword, you can do that - too. For example, you can find ports relevant to the LISP - programming language using:</para> - - <screen>&prompt.user; <userinput>cd /usr/ports</userinput> -&prompt.user; <userinput>make search key=lisp</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I went to install the <literal>foo</literal> port but - the system suddenly stopped compiling it and starting - compiling the <literal>bar</literal> port. What is going - on?</para> - </question> - - <answer> - <para>The <literal>foo</literal> port needs something that is - supplied with <literal>bar</literal> — for instance, - if <literal>foo</literal> uses graphics, - <literal>bar</literal> might have a library with useful - graphics processing routines. Or <literal>bar</literal> - might be a tool that is needed to compile the - <literal>foo</literal> port.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para id="ports-remove"> I installed the - <literal>grizzle</literal> program from the ports and - frankly it is a complete waste of disk space. I want to - delete it but I do not know where it put all the files. - Any clues?</para> - </question> - - <answer> - <para>No problem, just do:</para> - - <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen> - - <para>Alternatively, you can do:</para> - - <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput> -&prompt.root; <userinput>make deinstall</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Hang on a minute, you have to know the version number - to use that command. You do not seriously expect me to - remember that, do you??</para> - </question> - - <answer> - <para>Not at all, you can find it out by doing:</para> - - <screen>&prompt.root; <userinput>pkg_info -a | grep grizzle</userinput> -Information for grizzle-6.5: -grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up -arcade game.</screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Talking of disk space, the ports directory seems to be - taking up an awful lot of room. Is it safe to go in there - and delete things?</para> - </question> - - <answer> - <para>Yes, if you have installed the program and are fairly - certain you will not need the source again, there is no - point in keeping it hanging around. The best way to do - this is:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make clean</userinput></screen> - - <para>which will go through all the ports subdirectories and - delete everything except the skeletons for each - port.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I tried that and it still left all those tarballs or - whatever you called them in the - <filename>distfiles</filename> directory. Can I delete - those as well?</para> - </question> - - <answer> - <para>Yes, if you are sure you have finished with them, - those can go as well. They can be removed manually, or by - using <command>make distclean</command>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I like having lots and lots of programs to play with. - Is there any way of installing all the ports in one - go?</para> - </question> - - <answer> - <para>Just do:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make install</userinput></screen> - - <para>Be careful, as some ports may install files with the same - name. If you install two graphics ports and they both install - <filename>/usr/local/bin/plot</filename> then you will obviously - have problems.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, I tried that, but I thought it would take a very - long time so I went to bed and left it to get on with it. - When I looked at the computer this morning, it had only - done three and a half ports. Did something go - wrong?</para> - </question> - - <answer> - <para>No, the problem is that some of the ports need to ask - you questions that we cannot answer for you (e.g., <quote>Do - you want to print on A4 or US letter sized paper?</quote>) - and they need to have someone on hand to answer - them.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I really do not want to spend all day staring at the - monitor. Any better ideas?</para> - </question> - - <answer> - <para>OK, do this before you go to bed/work/the local - park:</para> - - <screen>&prompt.root <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DBATCH install</userinput></screen> - - <para>This will install every port that does - <emphasis>not</emphasis> require user input. Then, when - you come back, do:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports</userinput> -&prompt.root; <userinput>make -DIS_INTERACTIVE install</userinput></screen> - - <para>to finish the job.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>At work, we are using <literal>frobble</literal>, which - is in your Ports collection, but we have altered it quite a - bit to get it to do what we need. Is there any way of making - our own packages, so we can distribute it more easily around - our sites?</para> - </question> - - <answer> - <para>No problem, assuming you know how to make patches for - your changes:</para> - - <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></userinput> -&prompt.root; <userinput>make extract</userinput> -&prompt.root; <userinput>cd work/frobble-2.8</userinput> -[Apply your patches] -&prompt.root; <userinput>cd ../..</userinput> -&prompt.root; <userinput>make package</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>This ports stuff is really clever. I am desperate to - find out how you did it. What is the secret?</para> - </question> - - <answer> - <para>Nothing secret about it at all, just look at the - <filename>bsd.port.mk</filename> and - <filename>bsd.port.subdir.mk</filename> files in your - <ulink url="file://localhost/usr/ports/Mk/">makefiles - directory.</ulink></para> - - <para>(Readers with an aversion to intricate shell-scripts are - advised not to follow this link...)</para> - </answer> - </qandaentry> - </qandaset> - </sect2> - - <sect2 id="ports-broken"> - <title>Help! This port is broken!</title> - - <para>If you come across a port that doesn't work for you, there are - a few things you can do, including:</para> - - <orderedlist> - <listitem> - <para>Fix it! The <link linkend="porting"><quote>how to make a - port</quote></link> section should help you do this.</para> - </listitem> - - <listitem> - <para>Gripe—<emphasis>by email only!</emphasis> Send - email to the maintainer of the port first. Type <command>make - maintainer</command> or read the <filename>Makefile</filename> - to find the maintainer's email address. Remember to include - the name and version of the port (send the - <literal>$FreeBSD:</literal> line from the - <filename>Makefile</filename>) and the output leading up to the - error when you email the maintainer. If you do not get a - response from the maintainer, you can use - <command>send-pr</command> to submit a bug report.</para> - </listitem> - - <listitem> - <para>Forget about it. This is the easiest route—very - few ports can be classified as <quote>essential</quote>. There's - also a good chance any problems will be fixed in the next - version when the port is updated.</para> - </listitem> - - <listitem> - <para>Grab the package from an ftp site near you. The - <quote>master</quote> package collection is on <hostid - role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages - directory</ulink>, but be sure to check your local mirror - <emphasis>first!</emphasis> These are more likely to work - than trying to compile from source and are a lot faster as - well. Use the &man.pkg.add.1; program to install the package - on your system.</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 id="porting"> - <title>Advanced Topics</title> - - <para>The documentation that was here has been moved to its own <ulink - url="../porters-handbook/index.html">Porter's Handbook</ulink> for ease of - reference. Please go there if you wish to create and submit your own - ports.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml deleted file mode 100644 index af6741f0e8..0000000000 --- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml +++ /dev/null @@ -1,2632 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml,v 1.29 2000/10/13 21:07:01 jim Exp $ ---> - -<chapter id="ppp-and-slip"> - <title>PPP and SLIP</title> - - <para><emphasis>Restructured, reorganized, and updated by &a.jim;, - 1 March 2000.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>If you are connecting to the Internet via modem, or wish to - provide dial-up connections to the Internet for others using FreeBSD, - you have the option of using PPP or SLIP.</para> - - <para>This chapter covers three varieties of PPP; - <emphasis>user</emphasis>, <emphasis>kernel</emphasis>, and - <emphasis>PPPoE</emphasis> (PPP over Ethernet). It also covers - setting up a SLIP client and server.</para> - - <para>The first variety of PPP that will be covered is User PPP. User - PPP was introduced into FreeBSD in 2.0.5-RELEASE as an addition to - the already existing kernel implementation of PPP.</para> - - <para>You may be wondering what the main difference is between User - PPP and kernel PPP. The answer is simple; user PPP does not run as - a daemon, and can run as and when desired. No PPP interface needs - to be compiled into their kernel; it runs as a user process, and uses - the tunnel device driver (<devicename>tun</devicename>) to get data - into and out of the kernel.</para> - - <para>From here on out in this chapter, user ppp will simply be - referred to as ppp unless a distinction needs to be made between it - and and any other PPP software such as <command>pppd</command>. - Unless otherwise stated, all of the commands explained in this - section should be executed as root.</para> - </sect1> - - <sect1 id="userppp"> - <title>Using User PPP</title> - - <para><emphasis>Originally contributed by &a.brian;, with input - from &a.nik;, &a.dirkvangulik;, and &a.pjc;.</emphasis></para> - - <sect2> - <title>User PPP</title> - - <sect3> - <title>Assumptions</title> - - <para>This document assumes you have the following:</para> - - <itemizedlist> - <listitem> - <para>An account with an Internet Service Provider (ISP) which - you connect to using PPP. Further, you have a modem or - other device connected to your system and configured - correctly, which allows you to connect to your ISP.</para> - </listitem> - - <listitem> - <para>The dial-up number(s) of your ISP.</para> - </listitem> - - <listitem> - <para>Your login name and password. This can be either a - regular UNIX-style login and password pair, or a PAP or CHAP - login and password pair.</para> - </listitem> - - <listitem> - <para>The IP address(es) of one or more name servers. - Normally, you will be given two IP addresses by your ISP to - use for this. If they have not given you at least one, then - you can use the <command>enable dns</command> command in - your <filename>ppp.conf</filename> file to tell - <application>ppp</application> to set the name servers for - you.</para> - </listitem> - </itemizedlist> - - <para>The following information may be supplied by your ISP, but - is not completely necessary:</para> - - <itemizedlist> - <listitem> - <para>The IP address of your ISP's gateway. The gateway is - the machine to which you will connect and will be set up as - your <emphasis>default route</emphasis>. If you do not have - this information, we can make one up and your ISP's PPP - server will tell us the correct value when we connect.</para> - - <para>This IP number is referred to as - <literal>HISADDR</literal> by - <application>ppp</application>.</para> - </listitem> - - <listitem> - <para>The netmask you should use. If your ISP has not - provided you with one, you can safely use <hostid - role="netmask">255.255.255.0</hostid>.</para> - </listitem> - - <listitem> - <para>If your ISP provides you with a static IP address and - hostname, you can enter it. Otherwise, we simply let the - peer assign whatever IP address it sees fit.</para> - </listitem> - </itemizedlist> - - <para>If you do not have any of the required information, contact - your ISP and make sure they provide it to you.</para> - </sect3> - - <sect3> - <title>Preparing the Kernel</title> - - <para>As previously mentioned, <application>ppp</application> - uses the <devicename>tun</devicename> device, and whichever kernel - you are using must have <devicename>tun</devicename> configured. - The <devicename>tun</devicename> device is preconfigured - for the default <filename>GENERIC</filename> kernel that ships - with FreeBSD. However, if you have installed a custom kernel, - you must make sure your kernel is configured for ppp.</para> - - <para>To check, go to your kernel compile directory - (<filename>/sys/i386/conf</filename> or - <filename>/sys/pc98/conf</filename>) and examine your - configuration file. It should have the following line somewhere - in it:</para> - - <programlisting> -pseudo-device tun 1</programlisting> - - <para>If this line is not present, you will need to add it to the - configuration file and recompile your kernel. The stock - <filename>GENERIC</filename> kernel has this included, so if you - have not installed a custom kernel or do not have a - <filename>/sys</filename> directory, you do not have to change - anything. If you do need to recompile your kernel, please refer - to the <link linkend="kernelconfig">kernel configuration</link> - section for more information.</para> - - <para>You can check how many tunnel devices your current kernel - has by typing the following:</para> - - <screen>&prompt.root; <userinput>ifconfig -a</userinput> -tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff -tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576 -tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff -tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> - - <note> - <para>In FreeBSD 4.0 and later releases, you will only see any - <devicename>tun</devicename> devices which have already been - used. This means you might not see <emphasis>any</emphasis> - <devicename>tun</devicename> devices. If this is the case, do - not worry; the device should be created dynamically when - <command>ppp</command> attempts to use it.</para> - </note> - - <para>This case shows four tunnel devices, two of which are - currently configured and being used. It should be noted that - the <literal>RUNNING</literal> flag above indicates that the - interface has been used at some point—it is not an error - if your interface does not show up as - <literal>RUNNING</literal>.</para> - - <para>If for some reason you have a kernel that does not have the - <devicename>tun</devicename> device in it and cannot recompile - the kernel, all is not lost. You should be able to dynamically - load the code. Please refer to the appropriate - &man.modload.8; and &man.lkm.4; man pages for further - details.</para> - </sect3> - - <sect3> - <title>Check the <devicename>tun</devicename> device</title> - - <para>Under normal circumstances, most users will only require one - <devicename>tun</devicename> device - (<filename>/dev/tun0</filename>). If you have specified more - than one on the <literal>pseudo-device</literal> line for - <devicename>tun</devicename> in your kernel configuration file, - then alter all references to <devicename>tun0</devicename> below - to reflect whichever device number you are using (e.g., - <devicename>tun2</devicename>).</para> - - <para>The easiest way to make sure that the - <devicename>tun0</devicename> device is configured correctly, - is to remake the device. This process is quite easy. To remake - the device, do the following:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tun0</userinput></screen> - - <para>If you need 16 tunnel devices in your kernel, you will need - to create them. This can be done by executing the following - commands:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tun15</userinput></screen> - - <para>To confirm that the kernel is configured correctly, issue - the follow command and compare the results:</para> - - <screen>&prompt.root; <userinput>ifconfig tun0</userinput> -tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mut 1500</screen> - - <para>The <literal>RUNNING</literal> flag may not yet be set, in - which case you will see:</para> - - <screen>&prompt.root; <userinput>ifconfig tun0</userinput> -tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> - - <para>Remember from earlier that you might not see the device if it - has not been used yet, as <devicename>tun</devicename> devices are - created on demand in FreeBSD 4.0 and later releases.</para> - </sect3> - - <sect3> - <title>Name Resolution Configuration</title> - - <para>The resolver is the part of the system that turns IP - addresses into hostnames and vice versa. 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 - <filename>/etc/hosts</filename>. Read &man.hosts.5; for more - information. The second is the Internet Domain Name Service - (DNS), a distributed data base, the discussion of which is - beyond the scope of this document.</para> - - <para>The resolver is a set of system calls that do the name - mappings, but you have to tell them where to find their - information. You do this by first editing the file - <filename>/etc/host.conf</filename>. Do <emphasis>not</emphasis> - call this file <filename>/etc/hosts.conf</filename> (note the - extra <literal>s</literal>) as the results can be - confusing.</para> - - <sect4> - <title>Edit <filename>/etc/host.conf</filename></title> - - <para>This file should contain the following two lines (in this - order):</para> - - <programlisting> -hosts -bind</programlisting> - - <para>These instruct the resolver to first look in the file - <filename>/etc/hosts</filename>, and then to consult the DNS - if the name was not found.</para> - </sect4> - - <sect4> - <title>Edit <filename>/etc/hosts</filename></title> - - <para>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 your machine is called <hostid - role="fqdn">foo.bar.com</hostid> with the IP address <hostid - role="ipaddr">10.0.0.1</hostid>, - <filename>/etc/hosts</filename> should contain:</para> - - <programlisting> -127.0.0.1 localhost.bar.com localhost -127.0.0.1 localhost.bar.com. -10.0.0.1 foo.bar.com foo -10.0.0.1 foo.bar.com.</programlisting> - - <para>The first two lines define the alias - <hostid>localhost</hostid> as a synonym for the current - machine. Regardless of your own IP address, the IP address - for this line should always be <hostid - role="ipaddr">127.0.0.1</hostid>. The second two lines map - the name <hostid role="fqdn">foo.bar.com</hostid> (and the - shorthand <hostid>foo</hostid>) to the IP address <hostid - role="ipaddr">10.0.0.1</hostid>.</para> - - <para>If your provider allocates you a static IP address and - name, use them in place of the <hostid - role="ipaddr">10.0.0.1</hostid> entry.</para> - </sect4> - - <sect4> - <title>Edit <filename>/etc/resolv.conf</filename></title> - - <para>The <filename>/etc/resolv.conf</filename> file tells the - resolver how to behave. If you are running your own DNS, you - may leave this file empty. Normally, you will need to enter - the following line(s):</para> - - <programlisting> -domain <replaceable>bar.com</replaceable> -nameserver <replaceable>x.x.x.x</replaceable> -nameserver <replaceable>y.y.y.y</replaceable></programlisting> - - <para>The <hostid - role="ipaddr"><replaceable>x.x.x.x</replaceable></hostid> and - <hostid role="ipaddr"><replaceable>y.y.y.y</replaceable></hostid> - addresses are those given to you by your ISP. Add as many - <literal>nameserver</literal> lines as your ISP provides. The - <literal>domain</literal> line defaults to your hostname's - domain, and is probably unnecessary. Refer to the - &man.resolv.conf.5; manual page for details of other possible - entries in this file.</para> - - <para>If you are running PPP version 2 or greater, the - <command>enable dns</command> command will tell PPP to request - that your ISP confirms the nameserver values. If your ISP - supplies different addresses (or if there are no nameserver - lines in <filename>/etc/resolv.conf</filename>), PPP will - rewrite the file with the ISP-supplied values.</para> - </sect4> - </sect3> - - <sect3> - <title><application>PPP</application> Configuration</title> - - <para>Both <command>ppp</command> and <command>pppd</command> - (the kernel level implementation of PPP) use the configuration - files located in the <filename>/usr/share/examples/ppp</filename> directory. - The sample configuration files provided are a good reference, - so do not delete them.</para> - - <para>Configuring <command>ppp</command> requires that you edit a - number of files, depending on your requirements. What you put - in them depends to some extent on whether your ISP allocates IP - addresses statically (i.e., you get given one IP address, and - always use that one) or dynamically (i.e., your IP address - changes each time you connect to your ISP).</para> - - <sect4 id="userppp-staticIP"> - <title>PPP and Static IP Addresses</title> - - <para>You will need to create a configuration file called - <filename>/etc/ppp/ppp.conf</filename>. It should look - similar to the example below.</para> - - <note> - <para>Lines that end in a <literal>:</literal> start in the - first column, all other lines should be indented as shown - using spaces or tabs.</para> - </note> - - <programlisting> -1 default: -2 set device /dev/cuaa0 -3 set speed 115200 -4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT" -5 provider: -6 set phone "(123) 456 7890" -7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp" -8 set timeout 300 -9 set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.0 0.0.0.0 -10 add default HISADDR -11 enable dns</programlisting> - - <para>Do not include the line numbers, they are just for - reference in this discussion.</para> - - <variablelist> - <varlistentry> - <term>Line 1:</term> - - <listitem> - <para>Identifies the default entry. Commands in this - entry are executed automatically when ppp is run.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 2:</term> - - <listitem> - <para>Identifies the device to which the modem is - connected. <devicename>COM1</devicename> is - <filename>/dev/cuaa0</filename> and - <devicename>COM2</devicename> is - <filename>/dev/cuaa1</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 3:</term> - - <listitem> - <para>Sets the speed you want to connect at. If 115200 - does not work (it should with any reasonably new modem), - try 38400 instead.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 4:</term> - - <listitem> - <para>The dial string. User PPP uses an expect-send - syntax similar to the &man.chat.8; program. Refer to - the manual page for information on the features of this - language.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 5:</term> - - <listitem> - <para>Identifies an entry for a provider called - <quote>provider</quote>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 6:</term> - - <listitem> - <para>Sets the phone number for this provider. Multiple - phone numbers may be specified using the colon - (<literal>:</literal>) or pipe character - (<literal>|</literal>)as a separator. The difference - between the two separators is described in &man.ppp.8;. - To summarize, if you want to rotate through the numbers, - use a colon. If you want to always attempt to dial the - first number first and only use the other numbers if the - first number fails, use the pipe character. Always - quote the entire set of phone numbers as shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 7:</term> - - <listitem> - <para>The login string is of the same chat-like syntax as - the dial string. In this example, the string works for - a service whose login session looks like this:</para> - - <screen>J. Random Provider -login: <replaceable>foo</replaceable> -password: <replaceable>bar</replaceable> -protocol: ppp</screen> - - <para>You will need to alter this script to suit your own - needs. When you write this script for the first time, - you should enable <quote>chat</quote> logging to ensure - that the conversation is going as expected.</para> - - <para>If you are using PAP or CHAP, there will be no login - at this point, so your login string can be left blank. - See <link linkend="userppp-PAPnCHAP">PAP and CHAP - authentication</link> for further details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 8:</term> - - <listitem> - <para>Sets the default timeout (in seconds) for the - connection. Here, the connection will be closed - automatically after 300 seconds of inactivity. If you - never want to timeout, set this value to zero.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 9:</term> - - <listitem> - <para>Sets the interface addresses. The string - <replaceable>x.x.x.x</replaceable> should be replaced by - the IP address that your provider has allocated to you. - The string <replaceable>y.y.y.y</replaceable> should be - replaced by the IP address that your ISP indicated for - their gateway (the machine to which you connect). If - your ISP hasn't given you a gateway address, use <hostid - role="netmask">10.0.0.2/0</hostid>. If you need to use - a <quote>guessed</quote> address, make sure that you - create an entry in - <filename>/etc/ppp/ppp.linkup</filename> as per the - instructions for <link linkend="userppp-dynamicIP">PPP - and Dynamic IP addresses</link>. If this line is - omitted, <command>ppp</command> cannot run in - <option>-auto</option> or <option>-dynamic</option> - mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 10:</term> - - <listitem> - <para>Adds a default route to your ISP's gateway. The - special word <literal>HISADDR</literal> is replaced with - the gateway address specified on line 9. It is - important that this line appears after line 9, - otherwise <literal>HISADDR</literal> will not yet be - initialized.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 11:</term> - - <listitem> - <para>This line tells PPP to ask your ISP to confirm that - your nameserver addresses are correct. If your ISP - supports this facility, PPP can then update - <filename>/etc/resolv.conf</filename> with the correct - nameserver entries.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>It is not necessary to add an entry to - <filename>ppp.linkup</filename> when you have a static IP - address as your routing table entries are already correct - before you connect. You may however wish to create an entry - to invoke programs after connection. This is explained later - with the sendmail example.</para> - - <para>Example configuration files can be found in the - <filename>/usr/share/examples/ppp</filename> directory.</para> - </sect4> - - <sect4 id="userppp-dynamicIP"> - <title>PPP and Dynamic IP Addresses</title> - - <para>If your service provider does not assign static IP - addresses, <command>ppp</command> can be configured to - negotiate the local and remote addresses. This is done by - <quote>guessing</quote> an IP address and allowing - <command>ppp</command> to set it up correctly using the IP - Configuration Protocol (IPCP) after connecting. The - <filename>ppp.conf</filename> configuration is the same as - <link linkend="userppp-staticIP">PPP and Static IP - Addresses</link>, with the following change:</para> - - <programlisting> -9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0</programlisting> - - <para>Again, do not include the line numbers, they are just for - reference. Indentation of at least one space is - required.</para> - - <variablelist> - <varlistentry> - <term>Line 9:</term> - - <listitem> - <para>The number after the <literal>/</literal> character - is the number of bits of the address that ppp will - insist on. You may wish to use IP numbers more - appropriate to your circumstances, but the above example - will always work.</para> - - <para>The last argument (<literal>0.0.0.0</literal>) tells - PPP to negotiate using address <hostid - role="ipaddr">0.0.0.0</hostid> rather than <hostid - role="ipaddr">10.0.0.1</hostid>. Do not use - <literal>0.0.0.0</literal> as the first argument to - <command>set ifaddr</command> as it prevents PPP from - setting up an initial route in <option>-auto</option> - mode.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If you are running version 1.x of PPP, you will also need - to create an entry in <filename>/etc/ppp/ppp.linkup</filename>. - <filename>ppp.linkup</filename> is used after a connection has - been established. At this point, <command>ppp</command> will - know what IP addresses should <emphasis>really</emphasis> be - used. The following entry will delete the existing bogus - routes, and create correct ones:</para> - - <programlisting> -1 provider: -2 delete ALL -3 add 0 0 HISADDR</programlisting> - - <variablelist> - <varlistentry> - <term>Line 1:</term> - - <listitem> - <para>On establishing a connection, <command>ppp</command> - will look for an entry in <filename>ppp.linkup</filename> - according to the following rules: First, try to match - the same label as we used in - <filename>ppp.conf</filename>. If that fails, look for - an entry for the IP address of our gateway. This entry - is a four-octet IP style label. If we still have not - found an entry, look for the <literal>MYADDR</literal> - entry.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 2:</term> - - <listitem> - <para>This line tells <command>ppp</command> to delete all - of the existing routes for the acquired - <devicename>tun</devicename> interface (except the - direct route entry).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 3:</term> - - <listitem> - <para>This line tells <command>ppp</command> to add a - default route that points to <literal>HISADDR</literal>. - <literal>HISADDR</literal> will be replaced with the IP - number of the gateway as negotiated in the IPCP.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>See the pmdemand entry in the files - <filename>/usr/share/examples/ppp/ppp.conf.sample</filename> and - <filename>/usr/share/examples/ppp/ppp.linkup.sample</filename> for a - detailed example.</para> - - <para>Version 2 of PPP introduces <quote>sticky routes</quote>. - Any <literal>add</literal> or <literal>delete</literal> lines - that contain <literal>MYADDR</literal> or - <literal>HISADDR</literal> will be remembered, and any time - the actual values of <literal>MYADDR</literal> or - <literal>HISADDR</literal> change, the routes will be - reapplied. This removes the necessity of repeating these - lines in <filename>ppp.linkup</filename>.</para> - </sect4> - - <sect4> - <title>Receiving Incoming Calls</title> - - <para>When you configure <application>ppp</application> to - receive incoming calls on a machine connected to a LAN, you - must decide if you wish to forward packets to the LAN. If you - do, you should allocate the peer an IP number from your LAN's - subnet, and use the command <command>enable proxy</command> in - your <filename>/etc/ppp/ppp.conf</filename> file. You should - also confirm that the <filename>/etc/rc.conf</filename> file - contains the following:</para> - - <programlisting> -gateway="YES"</programlisting> - - <sect5> - <title>Which getty?</title> - - <para><link linkend="dialup">Configuring FreeBSD for Dial-up - Services</link> provides a good description on enabling - dial-up services using getty.</para> - - <para>An alternative to <command>getty</command> is <ulink - url="http://www.leo.org/~doering/mgetty/index.html">mgetty</ulink>, - a smarter version of <command>getty</command> designed with - dial-up lines in mind.</para> - - <para>The advantages of using <command>mgetty</command> is - that it actively <emphasis>talks</emphasis> to modems, - meaning if port is turned off in - <filename>/etc/ttys</filename> then your modem will not answer - the phone.</para> - - <para>Later versions of <command>mgetty</command> (from - 0.99beta onwards) also support the automatic detection of - PPP streams, allowing your clients script-less access to - your server.</para> - - <para>Refer to <link linkend="userppp-mgetty">Mgetty and - AutoPPP</link> for more information on - <command>mgetty</command>.</para> - </sect5> - - <sect5> - <title><application>PPP</application> Permissions</title> - - <para>The <command>ppp</command> command must normally be run - as user id 0. If however, you wish to allow - <command>ppp</command> to run in server mode as a normal - user by executing <command>ppp</command> as described below, - that user must be given permission to run - <command>ppp</command> by adding them to the - <username>network</username> group in - <filename>/etc/group</filename>.</para> - - <para>You will also need to give them access to one or more - sections of the configuration file using the - <command>allow</command> command:</para> - - <programlisting> -allow users fred mary</programlisting> - - <para>If this command is used in the <literal>default</literal> - section, it gives the specified users access to - everything.</para> - </sect5> - - <sect5> - <title>PPP Shells for Dynamic-IP Users</title> - - <para>Create a file called - <filename>/etc/ppp/ppp-shell</filename> containing the - following:</para> - - <programlisting> -#!/bin/sh -IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` -CALLEDAS="$IDENT" -TTY=`tty` - -if [ x$IDENT = xdialup ]; then - IDENT=`basename $TTY` -fi - -echo "PPP for $CALLEDAS on $TTY" -echo "Starting PPP for $IDENT" - -exec /usr/sbin/ppp -direct $IDENT</programlisting> - - <para>This script should be executable. Now make a symbolic - link called <filename>ppp-dialup</filename> to this script - using the following commands:</para> - - <screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen> - - <para>You should use this script as the - <emphasis>shell</emphasis> for all of your dialup users. - This is an example from <filename>/etc/password</filename> - for a dialup PPP user with username - <username>pchilds</username> (remember don't directly edit - the password file, use <command>vipw</command>).</para> - - <programlisting> -pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting> - - <para>Create a <filename>/home/ppp</filename> directory that - is world readable containing the following 0 byte - files:</para> - - <screen>-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin --r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts</screen> - - <para>which prevents <filename>/etc/motd</filename> from being - displayed.</para> - </sect5> - - <sect5> - <title>PPP shells for Static-IP Users</title> - - <para>Create the <filename>ppp-shell</filename> file as above - and for each account with statically assigned IPs create a - symbolic link to <filename>ppp-shell</filename>.</para> - - <para>For example, if you have three dialup customers - <username>fred</username>, <username>sam</username>, and - <username>mary</username>, that you route class C networks - for, you would type the following:</para> - - <screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput> -&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput> -&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen> - - <para>Each of these users dialup accounts should have their - shell set to the symbolic link created above (i.e., - <username>mary</username>'s shell should be - <filename>/etc/ppp/ppp-mary</filename>).</para> - </sect5> - - <sect5> - <title>Setting up ppp.conf for dynamic-IP users</title> - - <para>The <filename>/etc/ppp/ppp.conf</filename> file should - contain something along the lines of:</para> - - <programlisting> -default: - set debug phase lcp chat - set timeout 0 - -ttyd0: - set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 - enable proxy - -ttyd1: - set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 - enable proxy</programlisting> - - <note> - <para>The indenting is important.</para> - </note> - - <para>The <literal>default:</literal> section is loaded for - each session. For each dialup line enabled in - <filename>/etc/ttys</filename> create an entry similar to - the one for <literal>ttyd0:</literal> above. Each line - should get a unique IP address from your pool of IP - addresses for dynamic users.</para> - </sect5> - - <sect5> - <title>Setting up <filename>ppp.conf</filename> for static-IP - users</title> - - <para>Along with the contents of the sample - <filename>/usr/share/examples/ppp/ppp.conf</filename> above you should add - a section for each of the statically assigned dialup users. - We will continue with our <username>fred</username>, - <username>sam</username>, and <username>mary</username> - example.</para> - - <programlisting> -fred: - set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 - -sam: - set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 - -mary: - set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255</programlisting> - - <para>The file <filename>/etc/ppp/ppp.linkup</filename> should - also contain routing information for each static IP user if - required. The line below would add a route for the <hostid - role="ipaddr">203.14.101.0</hostid> class C via the - client's ppp link.</para> - - <programlisting> -fred: - add 203.14.101.0 netmask 255.255.255.0 HISADDR - -sam: - add 203.14.102.0 netmask 255.255.255.0 HISADDR - -mary: - add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting> - </sect5> - </sect4> - - <sect4> - <title>More on <command>mgetty</command>, AutoPPP, and MS - extensions</title> - - <sect5 id="userppp-mgetty"> - <title><command>mgetty</command> and AutoPPP</title> - - <para>Configuring and compiling <command>mgetty</command> with - the <literal>AUTO_PPP</literal> option enabled allows - <command>mgetty</command> to detect the LCP phase of PPP - connections and automatically spawn off a ppp shell. - However, since the default login/password sequence does not - occur it is necessary to authenticate users using either PAP - or CHAP.</para> - - <para>This section assumes the user has successfully - configured, compiled, and installed a version of - <command>mgetty</command> with the - <literal>AUTO_PPP</literal> option (v0.99beta or - later).</para> - - <para>Make sure your - <filename>/usr/local/etc/mgetty+sendfax/login.config</filename> - file has the following in it:</para> - - <programlisting> -/AutoPPP/ - - /etc/ppp/ppp-pap-dialup</programlisting> - - <para>This will tell <command>mgetty</command> to run the - <filename>ppp-pap-dialup</filename> script for detected PPP - connections.</para> - - <para>Create a file called - <filename>/etc/ppp/ppp-pap-dialup</filename> containing the - following (the file should be executable):</para> - - <programlisting> -#!/bin/sh -exec /usr/sbin/ppp -direct pap$IDENT</programlisting> - - <para>For each dialup line enabled in - <filename>/etc/ttys</filename>, create a corresponding entry - in <filename>/etc/ppp/ppp.conf</filename>. This will - happily co-exist with the definitions we created - above.</para> - - <programlisting> -pap: - enable pap - set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 - enable proxy</programlisting> - - <para>Each user logging in with this method will need to have - a username/password in - <filename>/etc/ppp/ppp.secret</filename> file, or - alternatively add the following option to authenticate users - via PAP from <filename>/etc/password</filename> file.</para> - - <programlisting> -enable passwdauth</programlisting> - - <para>If you wish to assign some users a static IP number, you - can specify the number as the third argument in - <filename>/etc/ppp/ppp.secret</filename>. See - <filename>/usr/share/examples/ppp/ppp.secret.sample</filename> for - examples.</para> - </sect5> - - <sect5> - <title>MS extensions</title> - - <para>It is possible to configure PPP to supply DNS and - NetBIOS nameserver addresses on demand.</para> - - <para>To enable these extensions with PPP version 1.x, the - following lines might be added to the relevant section of - <filename>/etc/ppp/ppp.conf</filename>.</para> - - <programlisting> -enable msext -set ns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5</programlisting> - - <para>And for PPP version 2 and above:</para> - - <programlisting> -accept dns -set dns 203.14.100.1 203.14.100.2 -set nbns 203.14.100.5</programlisting> - - <para>This will tell the clients the primary and secondary - name server addresses, and a netbios nameserver host.</para> - - <para>In version 2 and above, if the - <literal>set dns</literal> line is omitted, PPP will use the - values found in <filename>/etc/resolv.conf</filename>.</para> - </sect5> - </sect4> - - <sect4 id="userppp-PAPnCHAP"> - <title>PAP and CHAP authentication</title> - - <para>Some ISPs set their system up so that the authentication - part of your connection is done using either of the PAP or - CHAP authentication mechanisms. If this is the case, your ISP - will not give a <prompt>login:</prompt> prompt when you - connect, but will start talking PPP immediately.</para> - - <para>PAP is less secure than CHAP, but security is not normally - an issue here as passwords, although being sent as plain text - with PAP, are being transmitted down a serial line only. - There's not much room for crackers to - <quote>eavesdrop</quote>.</para> - - <para>Referring back to the <link linkend="userppp-staticIP">PPP - and Static IP addresses</link> or <link - linkend="userppp-dynamicIP">PPP and Dynamic IP addresses</link> - sections, the following alterations must be made:</para> - - <programlisting> -7 set login -… -12 set authname <replaceable>MyUserName</replaceable> -13 set authkey <replaceable>MyPassword</replaceable></programlisting> - - <para>As always, do not include the line numbers, they are just - for reference in this discussion. Indentation of at least one - space is required.</para> - - <variablelist> - <varlistentry> - <term>Line 7:</term> - - <listitem> - <para>Your ISP will not normally require that you log into - the server if you're using PAP or CHAP. You must - therefore disable your <quote>set login</quote> - string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 12:</term> - - <listitem> - <para>This line specifies your PAP/CHAP user name. You - will need to insert the correct value for - <replaceable>MyUserName</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Line 13:</term> - - <listitem> - <para>This line specifies your PAP/CHAP password. You - will need to insert the correct value for - <replaceable>MyPassword</replaceable>. You may want to - add an additional line, such as:</para> - - <programlisting> -15 accept PAP</programlisting> - - <para>or</para> - - <programlisting> -15 accept CHAP</programlisting> - - <para>to make it obvious that this is the intention, but - PAP and CHAP are both accepted by default.</para> - </listitem> - </varlistentry> - </variablelist> - </sect4> - - <sect4> - <title>Changing your <command>ppp</command> configuration on the - fly</title> - - <para>It is possible to talk to the <command>ppp</command> - program while it is running in the background, but only if a - suitable diagnostic port has been set up. To do this, add the - following line to your configuration:</para> - - <programlisting> -set server /var/run/ppp-tun%d DiagnosticPassword 0177</programlisting> - - <para>This will tell PPP to listen to the specified unix-domain - socket, asking clients for the specified password before - allowing access. The <literal>%d</literal> in the name is - replaced with the <devicename>tun</devicename> device number - that is in use.</para> - - <para>Once a socket has been set up, the &man.pppctl.8; program - may be used in scripts that wish to manipulate the running - program.</para> - </sect4> - </sect3> - - <sect3 id="userppp-final"> - <title>Final system configuration</title> - - <para>You now have <command>ppp</command> configured, but there - are a few more things to do before it is ready to work. They - all involve editing the <filename>/etc/rc.conf</filename> - file.</para> - - <para>Working from the top down in this file, make sure the - <literal>hostname=</literal> line is set, e.g.:</para> - - <programlisting> -hostname="foo.bar.com"</programlisting> - - <para>If your ISP has supplied you with a static IP address and - name, it's probably best that you use this name as your host - name.</para> - - <para>Look for the <literal>network_interfaces</literal> variable. - If you want to configure your system to dial your ISP on demand, - make sure the <devicename>tun0</devicename> device is added to - the list, otherwise remove it.</para> - - <programlisting> -network_interfaces="lo0 tun0" ifconfig_tun0=</programlisting> - - <note> - <para>The <literal>ifconfig_tun0</literal> variable should be - empty, and a file called - <filename>/etc/start_if.tun0</filename> should be created. - This file should contain the line:</para> - - <programlisting> -ppp -auto mysystem</programlisting> - - <para>This script is executed at network configuration time, - starting your ppp daemon in automatic mode. If you have a LAN - for which this machine is a gateway, you may also wish to use - the <option>-alias</option> switch. Refer to the manual page - for further details.</para> - </note> - - <para>Set the router program to <literal>NO</literal> with - following line in your <filename>/etc/rc.conf</filename>:</para> - - <programlisting> -router_enable="NO"</programlisting> - - <para>It is important that the <command>routed</command> daemon is - not started (it is started by default), as it - <command>routed</command> tends to delete the default routing - table entries created by <command>ppp</command>.</para> - - <para>It is probably worth your while ensuring that the - <literal>sendmail_flags</literal> line does not include the - <option>-q</option> option, otherwise - <command>sendmail</command> will attempt to do a network lookup - every now and then, possibly causing your machine to dial out. - You may try:</para> - - <programlisting> -sendmail_flags="-bd"</programlisting> - - <para>The downside of this is that you must force - <command>sendmail</command> to re-examine the mail queue - whenever the ppp link is up by typing:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen> - - <para>You may wish to use the <command>!bg</command> command in - <filename>ppp.linkup</filename> to do this automatically:</para> - - <programlisting> -1 provider: -2 delete ALL -3 add 0 0 HISADDR -4 !bg sendmail -bd -q30m</programlisting> - - <para>If you don't like this, it is possible to set up a - <quote>dfilter</quote> to block SMTP traffic. Refer to the - sample files for further details.</para> - - <para>Now the only thing left to do is reboot the machine.</para> - - <para>All that is left is to reboot the machine. After rebooting, - you can now either type:</para> - - <screen>&prompt.root; <userinput>ppp</userinput></screen> - - <para>and then <command>dial provider</command> to start the PPP - session, or, if you want <command>ppp</command> to establish - sessions automatically when there is outbound traffic (and - you have not created the <filename>start_if.tun0</filename> - script), type:</para> - - <screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen> - </sect3> - - <sect3> - <title>Summary</title> - - <para>To recap, the following steps are necessary when setting up - ppp for the first time:</para> - - <para>Client side:</para> - - <procedure> - <step> - <para>Ensure that the <devicename>tun</devicename> device is - built into your kernel.</para> - </step> - - <step> - <para>Ensure that the - <filename>tun<replaceable>X</replaceable></filename> device - file is available in the <filename>/dev</filename> - directory.</para> - </step> - - <step> - <para>Create an entry in - <filename>/etc/ppp/ppp.conf</filename>. The - <filename>pmdemand</filename> example should suffice for - most ISPs.</para> - </step> - - <step> - <para>If you have a dynamic IP address, create an entry in - <filename>/etc/ppp/ppp.linkup</filename>.</para> - </step> - - <step> - <para>Update your <filename>/etc/rc.conf</filename> - file.</para> - </step> - - <step> - <para>Create a <filename>start_if.tun0</filename> script if - you require demand dialing.</para> - </step> - </procedure> - - <para>Server side:</para> - - <procedure> - <step> - <para>Ensure that the <devicename>tun</devicename> device is - built into your kernel.</para> - </step> - - <step> - <para>Ensure that the - <filename>tun<replaceable>X</replaceable></filename> device - file is available in the <filename>/dev</filename> - directory.</para> - </step> - - <step> - <para>Create an entry in <filename>/etc/passwd</filename> - (using the &man.vipw.8; program).</para> - </step> - - <step> - <para>Create a profile in this users home directory that runs - <command>ppp -direct direct-server</command> or - similar.</para> - </step> - - <step> - <para>Create an entry in - <filename>/etc/ppp/ppp.conf</filename>. The - <filename>direct-server</filename> example should - suffice.</para> - </step> - - <step> - <para>Create an entry in - <filename>/etc/ppp/ppp.linkup</filename>.</para> - </step> - - <step> - <para>Update your <filename>/etc/rc.conf</filename> - file.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 id="ppp"> - <title>Using Kernel PPP</title> - - <para><emphasis>Parts originally contributed by &a.gena; and - &a.rhuff;.</emphasis></para> - - <sect2> - <title>Setting up Kernel PPP</title> - - <para>Before you start setting up PPP on your machine make sure - that <command>pppd</command> is located in - <filename>/usr/sbin</filename> and the directory - <filename>/etc/ppp</filename> exists.</para> - - <para><command>pppd</command> can work in two modes:</para> - - <orderedlist> - <listitem> - <para>As a <quote>client</quote>, i.e., you want to connect your - machine to the outside world via a PPP serial connection or - modem line.</para> - </listitem> - - <listitem> - <para>as a <quote>server</quote>, i.e. your machine is located on - the network and used to connect other computers using - PPP.</para> - </listitem> - </orderedlist> - - <para>In both cases you will need to set up an options file - (<filename>/etc/ppp/options</filename> or - <filename>~/.ppprc</filename> if you have more than one user on - your machine that uses PPP).</para> - - <para>You also will need some modem/serial software (preferably - kermit) so you can dial and establish a connection with the - remote host.</para> - </sect2> - - <sect2> - <title>Using <command>pppd</command> as a client</title> - - <para>I used the following <filename>/etc/ppp/options</filename> to - connect to CISCO terminal server PPP line.</para> - - <programlisting> -crtscts # enable hardware flow control -modem # modem control line -noipdefault # remote PPP server must supply your IP address. - # if the remote host doesn't send your IP during IPCP - # negotiation , remove this option -passive # wait for LCP packets -domain ppp.foo.com # put your domain name here - -:<remote_ip> # put the IP of remote PPP host here - # it will be used to route packets via PPP link - # if you didn't specified the noipdefault option - # change this line to <local_ip>:<remote_ip> - -defaultroute # put this if you want that PPP server will be your - # default router</programlisting> - - <para>To connect:</para> - - <procedure> - <step> - <para>Dial to the remote host using kermit (or some other modem - program), and enter your user name and password (or whatever - is needed to enable PPP on the remote host).</para> - </step> - - <step> - <para>Exit kermit (without hanging up the line).</para> - </step> - - <step> - <para>Enter the following:</para> - - <screen>&prompt.root; <userinput>/usr/src/usr.sbin/pppd.new/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen> - - <para>Be sure to use the appropriate speed and device name.</para> - </step> - </procedure> - - <para>Now your computer is connected with PPP. If the connection - fails, you can add the <option>debug</option> option to the - <filename>/etc/ppp/options</filename> file and check messages on - the console to track the problem.</para> - - <para>Following <filename>/etc/ppp/pppup</filename> script will make - all 3 stages automatically:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -ifconfig ppp0 down -ifconfig ppp0 delete - -kermit -y /etc/ppp/kermit.dial -pppd /dev/tty01 19200</programlisting> - - <para><filename>/etc/ppp/kermit.dial</filename> is a kermit script - that dials and makes all necessary authorization on the remote - host (an example of such a script is attached to the end of this - document).</para> - - <para>Use the following <filename>/etc/ppp/pppdown</filename> script - to disconnect the PPP line:</para> - - <programlisting> -#!/bin/sh -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ X${pid} != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill -TERM ${pid} -fi - -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -/sbin/ifconfig ppp0 down -/sbin/ifconfig ppp0 delete -kermit -y /etc/ppp/kermit.hup -/etc/ppp/ppptest</programlisting> - - <para>Check to see if PPP is still running by executing - <filename>/usr/etc/ppp/ppptest</filename>, which should look like - this:</para> - - <programlisting> -#!/bin/sh -pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` -if [ X${pid} != "X" ] ; then - echo 'pppd running: PID=' ${pid-NONE} -else - echo 'No pppd running.' -fi -set -x -netstat -n -I ppp0 -ifconfig ppp0</programlisting> - - <para>To hang up the modem, execute - <filename>/etc/ppp/kermit.hup</filename>, which should - contain:</para> - - <programlisting> -set line /dev/tty01 ; put your modem device here -set speed 19200 -set file type binary -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none - -pau 1 -out +++ -inp 5 OK -out ATH0\13 -echo \13 -exit</programlisting> - - <para>Here is an alternate method using <command>chat</command> - instead of <command>kermit</command>.</para> - - <para>The following two files are sufficient to accomplish a pppd - connection.</para> - - <para><filename>/etc/ppp/options</filename>:</para> - - <programlisting> -/dev/cuaa1 115200 - -crtscts # enable hardware flow control -modem # modem control line -connect "/usr/bin/chat -f /etc/ppp/login.chat.script" -noipdefault # remote PPP serve must supply your IP address. - # if the remote host doesn't send your IP during - # IPCP negotiation, remove this option -passive # wait for LCP packets -domain <your.domain> # put your domain name here - -: # put the IP of remote PPP host here - # it will be used to route packets via PPP link - # if you didn't specified the noipdefault option - # change this line to <local_ip>:<remote_ip> - -defaultroute # put this if you want that PPP server will be - # your default router</programlisting> - - <para><filename>/etc/ppp/login.chat.script</filename>:</para> - - <note> - <para>The following should go on a single line.</para> - </note> - - <programlisting> -ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number> - CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id> - TIMEOUT 5 sword: <password></programlisting> - - <para>Once these are installed and modified correctly, all you need - to do is run <command>pppd</command>, like so:</para> - - <screen>&prompt.root; <userinput>pppd</userinput></screen> - - <para>This sample is based primarily on information provided by: - Trev Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org> - and used with permission.</para> - </sect2> - - <sect2> - <title>Using <command>pppd</command> as a server</title> - - <para><filename>/etc/ppp/options</filename> should contain something - similar to the following:</para> - - <programlisting> -crtscts # Hardware flow control -netmask 255.255.255.0 # netmask ( not required ) -192.114.208.20:192.114.208.165 # ip's of local and remote hosts - # local ip must be different from one - # you assigned to the ethernet ( or other ) - # interface on your machine. - # remote IP is ip address that will be - # assigned to the remote machine -domain ppp.foo.com # your domain -passive # wait for LCP -modem # modem line</programlisting> - - <para>The following <filename>/etc/ppp/pppserv</filename> script - will enable tell <application>pppd</application> to behave as a - server:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi - -# reset ppp interface -ifconfig ppp0 down -ifconfig ppp0 delete - -# enable autoanswer mode -kermit -y /etc/ppp/kermit.ans - -# run ppp -pppd /dev/tty01 19200</programlisting> - - <para>Use this <filename>/etc/ppp/pppservdown</filename> script to - stop the server:</para> - - <programlisting> -#!/bin/sh -ps ax |grep pppd |grep -v grep -pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing pppd, PID=' ${pid} - kill ${pid} -fi -ps ax |grep kermit |grep -v grep -pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` -if [ "X${pid}" != "X" ] ; then - echo 'killing kermit, PID=' ${pid} - kill -9 ${pid} -fi -ifconfig ppp0 down -ifconfig ppp0 delete - -kermit -y /etc/ppp/kermit.noans</programlisting> - - <para>The following kermit script - (<filename>/etc/ppp/kermit.ans</filename>) will enable/disable - autoanswer mode on your modem. It should look like this:</para> - - <programlisting> -set line /dev/tty01 -set speed 19200 -set file type binary -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none - -pau 1 -out +++ -inp 5 OK -out ATH0\13 -inp 5 OK -echo \13 -out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable - ; autoanswer mod -inp 5 OK -echo \13 -exit</programlisting> - - <para>A script named <filename>/etc/ppp/kermit.dial</filename> is - used for dialing and authenticating on the remote host. You will - need to customize it for your needs. Put your login and password - in this script; you will also need to change the input statement - depending on responses from your modem and remote host.</para> - - <programlisting> -; -; put the com line attached to the modem here: -; -set line /dev/tty01 -; -; put the modem speed here: -; -set speed 19200 -set file type binary ; full 8 bit file xfer -set file names literal -set win 8 -set rec pack 1024 -set send pack 1024 -set block 3 -set term bytesize 8 -set command bytesize 8 -set flow none -set modem hayes -set dial hangup off -set carrier auto ; Then SET CARRIER if necessary, -set dial display on ; Then SET DIAL if necessary, -set input echo on -set input timeout proceed -set input case ignore -def \%x 0 ; login prompt counter -goto slhup - -:slcmd ; put the modem in command mode -echo Put the modem in command mode. -clear ; Clear unread characters from input buffer -pause 1 -output +++ ; hayes escape sequence -input 1 OK\13\10 ; wait for OK -if success goto slhup -output \13 -pause 1 -output at\13 -input 1 OK\13\10 -if fail goto slcmd ; if modem doesn't answer OK, try again - -:slhup ; hang up the phone -clear ; Clear unread characters from input buffer -pause 1 -echo Hanging up the phone. -output ath0\13 ; hayes command for on hook -input 2 OK\13\10 -if fail goto slcmd ; if no OK answer, put modem in command mode - -:sldial ; dial the number -pause 1 -echo Dialing. -output atdt9,550311\13\10 ; put phone number here -assign \%x 0 ; zero the time counter - -:look -clear ; Clear unread characters from input buffer -increment \%x ; Count the seconds -input 1 {CONNECT } -if success goto sllogin -reinput 1 {NO CARRIER\13\10} -if success goto sldial -reinput 1 {NO DIALTONE\13\10} -if success goto slnodial -reinput 1 {\255} -if success goto slhup -reinput 1 {\127} -if success goto slhup -if < \%x 60 goto look -else goto slhup - -:sllogin ; login -assign \%x 0 ; zero the time counter -pause 1 -echo Looking for login prompt. - -:slloop -increment \%x ; Count the seconds -clear ; Clear unread characters from input buffer -output \13 -; -; put your expected login prompt here: -; -input 1 {Username: } -if success goto sluid -reinput 1 {\255} -if success goto slhup -reinput 1 {\127} -if success goto slhup -if < \%x 10 goto slloop ; try 10 times to get a login prompt -else goto slhup ; hang up and start again if 10 failures - -:sluid -; -; put your userid here: -; -output ppp-login\13 -input 1 {Password: } -; -; put your password here: -; -output ppp-password\13 -input 1 {Entering SLIP mode.} -echo -quit - -:slnodial -echo \7No dialtone. Check the telephone line!\7 -exit 1 - -; local variables: -; mode: csh -; comment-start: "; " -; comment-start-skip: "; " -; end:</programlisting> - </sect2> - </sect1> - - <sect1 id="pppoe"> - <title>Using PPP over Ethernet (PPPoE)</title> - - <para><emphasis>Contributed by &a.jim; (from <ulink - url="http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html">node.to</ulink>) 10 Jan 2000.</emphasis></para> - - <para>The following describes how to set up PPP over Ethernet, a.k.a, - PPPoE.</para> - - <sect2> - <title>Prerequisites</title> - - <para>There are a few requirements that your system will need to meet - in order for PPPoE to function properly. They are:</para> - - <itemizedlist> - <listitem> - <para>Kernel source for FreeBSD 3.4 or later</para> - </listitem> - - <listitem> - <para><application>ppp</application> from FreeBSD 3.4 or later</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Kernel Configuration</title> - - <para>You will need to set the following options in your kernel - configuration file and then <link linkend="kernelconfig">compile a new - kernel</link>.</para> - - <itemizedlist> - <listitem> - <para>options NETGRAPH</para> - </listitem> - </itemizedlist> - - <para>Optionally, you can add</para> - - <itemizedlist> - <listitem> - <para>options NETGRAPH_PPPOE</para> - </listitem> - <listitem> - <para>options NETGRAPH_SOCKET</para> - </listitem> - </itemizedlist> - - <para> - although if this functionality is not available at runtime, - <application>ppp</application> will load the relevant modules - on demand - </para> - </sect2> - - <sect2> - <title>Setting up <filename>ppp.conf</filename></title> - - <para>Here is an example of a working - <filename>ppp.conf</filename>:</para> - - <programlisting> -default: # or name_of_service_provider - set device PPPoE:xl1 # replace xl1 with your ethernet device - set mru 1492 - set mtu 1492 - set authname YOURLOGINNAME - set authkey YOURPASSWORD - set log Phase tun command # you can add more detailed logging if you wish - set dial - set login - set ifaddr 10.0.0.1/0 10.0.0.2/0 - add default HISADDR - nat enable yes # if you want to enable nat for your local net - -papchap: - set authname YOURLOGINNAME - set authkey YOURPASSWORD</programlisting> - - <para> - Care should be taken when running <ulink - url="../FAQ/ppp.html#PPPoEwithNAT">PPPoE with the - <option>-nat</option> option</ulink>. - </para> - - </sect2> - - <sect2> - <title>Running <application>PPP</application></title> - - <para>As root, you can run:</para> - - <screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen> - - </sect2> - - <sect2> - <title>Starting <application>PPP</application> at Boot</title> - - <para>Add the following to your <filename>/etc/rc.conf</filename> - file:</para> - - <programlisting> -ppp_enable="YES" -ppp_mode="ddial" -ppp_nat="YES" -ppp_profile="default" # or your provider</programlisting> - </sect2> - </sect1> - - <sect1 id="slip"> - <title>Using SLIP</title> - - <para><emphasis>Originally contributed by &a.asami; and - &a.ghelmer;, with input from &a.wilko; and - &a.piero;.</emphasis></para> - - <sect2 id="slipc"> - <title>Setting up a SLIP Client</title> - - <para>The following is one way to set up a FreeBSD machine for SLIP - on a static host network. For dynamic hostname assignments (i.e., - your address changes each time you dial up), you probably need to - do something much fancier.</para> - - <para>First, determine which serial port your modem is connected to. - I have a symbolic link to <filename>/dev/modem</filename> from - <filename>/dev/cuaa1</filename>, and only use the modem name in - my configuration files. It can become quite cumbersome when you - need to fix a bunch of files in <filename>/etc</filename> and - <filename>.kermrc</filename>'s all over the system!</para> - - <note> - <para><filename>/dev/cuaa0</filename> is - <devicename>COM1</devicename>, <filename>cuaa1</filename> is - <devicename>COM2</devicename>, etc.</para> - </note> - - <para>Make sure you have the following in your kernel configuration - file:</para> - - <programlisting> -pseudo-device sl 1</programlisting> - - <para>It is included in the <filename>GENERIC</filename> kernel, so - this should not be a problem unless you have deleted it.</para> - - <sect3> - <title>Things you have to do only once</title> - - <procedure> - <step> - <para>Add your home machine, the gateway and nameservers to - your <filename>/etc/hosts</filename> file. Mine looks like - this:</para> - - <programlisting> -127.0.0.1 localhost loghost -136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia -136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway -128.32.136.9 ns1.Berkeley.edu ns1 -128.32.136.12 ns2.Berkeley.edu ns2</programlisting> - </step> - - <step> - <para>Make sure you have <option>hosts</option> before - <option>bind</option> in your - <filename>/etc/host.conf</filename>. Otherwise, funny - things may happen.</para> - </step> - - <step> - <para>Edit the <filename>/etc/rc.conf</filename> file.</para> - - <orderedlist> - <listitem> - <para>Set your hostname by editing the line that - says:</para> - - <programlisting> -hostname=<quote>myname.my.domain</quote></programlisting> - - <para>You should give it your full Internet - hostname.</para> - </listitem> - - <listitem> - <para>Add sl0 to the list of network interfaces by - changing the line that says:</para> - - <programlisting> -network_interfaces="lo0"</programlisting> - - <para>to:</para> - - <programlisting> -network_interfaces=<quote>lo0 sl0</quote></programlisting> - </listitem> - - <listitem> - <para>Set the startup flags of sl0 by adding a - line:</para> - - <programlisting> -ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"</programlisting> - </listitem> - - <listitem> - <para>Designate the default router by changing the - line:</para> - - <programlisting> -defaultrouter=<quote>NO</quote></programlisting> - - <para>to:</para> - - <programlisting> -defaultrouter=<quote>slip-gateway</quote></programlisting> - </listitem> - </orderedlist> - </step> - - <step> - <para>Make a file <filename>/etc/resolv.conf</filename> which - contains:</para> - - <programlisting> -domain HIP.Berkeley.EDU -nameserver 128.32.136.9 -nameserver 128.32.136.12</programlisting> - - <para>As you can see, these set up the nameserver hosts. Of - course, the actual domain names and addresses depend on your - environment.</para> - </step> - - <step> - <para>Set the password for root and toor (and any other - accounts that do not have a password). Use passwd or - &man.vipw.8;, do not edit the - <filename>/etc/passwd</filename> or - <filename>/etc/master.passwd</filename> files!</para> - </step> - - <step> - <para>Reboot your machine and make sure it comes up with the - correct hostname.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Making a SLIP connection</title> - - <procedure> - <step> - <para>Dial up, type <command>slip</command> at the prompt, - enter your machine name and password. The things you need - to enter depends on your environment. I use kermit, with a - script like this:</para> - - <programlisting> -# kermit setup -set modem hayes -set line /dev/modem -set speed 115200 -set parity none -set flow rts/cts -set terminal bytesize 8 -set file type binary -# The next macro will dial up and login -define slip dial 643-9600, input 10 =>, if failure stop, - -output slip\x0d, input 10 Username:, if failure stop, - -output silvia\x0d, input 10 Password:, if failure stop, - -output ***\x0d, echo \x0aCONNECTED\x0a</programlisting> - - <para>Of course, you have to change the hostname and password - to fit yours. After doing so, you can just type - <command>slip</command> from the kermit prompt to get - connected.</para> - - <note> - <para>Leaving your password in plain text anywhere in the - filesystem is generally a BAD idea. Do it at your own - risk.</para> - </note> - </step> - - <step> - <para>Leave the kermit there (you can suspend it by - <command>z</command>) and as root, type:</para> - - <screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen> - - <para>If you are able to <command>ping</command> hosts on the - other side of the router, you are connected! If it does not - work, you might want to try <option>-a</option> instead of - <option>-c</option> as an argument to slattach.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>How to shutdown the connection</title> - - <para>Do the following:</para> - - <screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen> - - <para>to kill slattach. Keep in mind you must be - <username>root</username> to do the above. Then go back to - kermit (<command>fg</command> if you suspended it) and exit from - it (<command>q</command>).</para> - - <para>The slattach man page says you have to use <command>ifconfig - sl0 down</command> to mark the interface down, but this does not - seem to make any difference for me. - (<command>ifconfig sl0</command> reports the same thing.)</para> - - <para>Some times, your modem might refuse to drop the carrier - (mine often does). In that case, simply start kermit and quit - it again. It usually goes out on the second try.</para> - </sect3> - - <sect3> - <title>Troubleshooting</title> - - <para>If it does not work, feel free to ask me. The things that - people tripped over so far:</para> - - <itemizedlist> - <listitem> - <para>Not using <option>-c</option> or <option>-a</option> in - slattach (I have no idea why this can be fatal, but adding - this flag solved the problem for at least one - person).</para> - </listitem> - - <listitem> - <para>Using <option>s10</option> instead of - <option>sl0</option> (might be hard to see the difference on - some fonts).</para> - </listitem> - - <listitem> - <para>Try <command>ifconfig sl0</command> to see your - interface status. I get:</para> - - <screen>&prompt.root; <userinput>ifconfig sl0</userinput> -sl0: flags=10<POINTOPOINT> - inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00</screen> - </listitem> - - <listitem> - <para>Also, <command>netstat -r</command> will give the - routing table, in case you get the <quote>no route to - host</quote> messages from ping. Mine looks like:</para> - - <screen>&prompt.root; <userinput>netstat -r</userinput> -Routing tables -Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: - -(root node) -(root node) - -Route Tree for Protocol Family inet: -(root node) => -default inr-3.Berkeley.EDU UG 8 224515 sl0 - - -localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438 -inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - - -silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438 -(root node)</screen> - - <para>This is after transferring a bunch of files, your - numbers should be smaller).</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - - <sect2 id="slips"> - <title>Setting up a SLIP Server</title> - - <para>This document provides suggestions for setting up SLIP Server - services on a FreeBSD system, which typically means configuring - your system to automatically startup connections upon login for - remote SLIP clients. The author has written this document based - on his experience; however, as your system and needs may be - different, this document may not answer all of your questions, and - the author cannot be responsible if you damage your system or lose - data due to attempting to follow the suggestions here.</para> - - <sect3 id="slips-prereqs"> - <title>Prerequisites</title> - - <para>This document is very technical in nature, so background - knowledge is required. It is assumed that you are familiar with - the TCP/IP network protocol, and in particular, network and node - addressing, network address masks, subnetting, routing, and - routing protocols, such as RIP. Configuring SLIP services on a - dial-up server requires a knowledge of these concepts, and if - you are not familiar with them, please read a copy of either - Craig Hunt's <emphasis>TCP/IP Network Administration</emphasis> - published by O'Reilly & Associates, Inc. (ISBN Number - 0-937175-82-X), or Douglas Comer's books on the TCP/IP - protocol.</para> - - <para>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 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 <ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink>. - You may also want to check the manual pages for &man.sio.4; for - information on the serial port device driver and &man.ttys.5;, - &man.gettytab.5;, &man.getty.8;, & &man.init.8; for - information relevant to configuring the system to accept logins - on modems, and perhaps &man.stty.1; for information on setting - serial port parameters (such as <literal>clocal</literal> for - directly-connected serial interfaces).</para> - </sect3> - - <sect3> - <title>Quick Overview</title> - - <para>In its typical configuration, using FreeBSD as a SLIP server - works as follows: a SLIP user dials up your FreeBSD SLIP Server - system and logs in with a special SLIP login ID that uses - <filename>/usr/sbin/sliplogin</filename> as the special user's - shell. The <command>sliplogin</command> program browses the - file <filename>/etc/sliphome/slip.hosts</filename> to find a - matching line for the special user, and if it finds a match, - connects the serial line to an available SLIP interface and then - runs the shell script - <filename>/etc/sliphome/slip.login</filename> to configure the - SLIP interface.</para> - - <sect4> - <title>An Example of a SLIP Server Login</title> - - <para>For example, if a SLIP user ID were - <username>Shelmerg</username>, <username>Shelmerg</username>'s - entry in <filename>/etc/master.passwd</filename> would look - something like this (except it would be all on one - line):</para> - - <programlisting> -Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting> - - <para>When <username>Shelmerg</username> logs in, - <command>sliplogin</command> will search - <filename>/etc/sliphome/slip.hosts</filename> for a line that - had a matching user ID; for example, there may be a line in - <filename>/etc/sliphome/slip.hosts</filename> that - reads:</para> - - <programlisting> -Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> - - <para><command>sliplogin</command> will find that matching line, - hook the serial line into the next available SLIP interface, - and then execute <filename>/etc/sliphome/slip.login</filename> - like this:</para> - - <programlisting> -/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> - - <para>If all goes well, - <filename>/etc/sliphome/slip.login</filename> will issue an - <command>ifconfig</command> for the SLIP interface to which - <command>sliplogin</command> attached itself (slip interface - 0,in the above example, which was the first parameter in the - list given to <filename>slip.login</filename>) to set the - local IP address (<hostid>dc-slip</hostid>), remote IP address - (<hostid>sl-helmer</hostid>), network mask for the SLIP - interface (<hostid role="netmask">0xfffffc00</hostid>), and - any additional flags (<literal>autocomp</literal>). If - something goes wrong, <command>sliplogin</command> usually - logs good informational messages via the - <literal>daemon</literal> syslog facility, which usually goes - into <filename>/var/log/messages</filename> (see the manual - pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps - check <filename>/etc/syslog.conf</filename> to see to which - files <command>syslogd</command> is logging).</para> - - <para>OK, enough of the examples — let us dive into - setting up the system.</para> - </sect4> - </sect3> - - <sect3> - <title>Kernel Configuration</title> - - <para>FreeBSD's default kernels usually come with two SLIP - interfaces defined (<devicename>sl0</devicename> and - <devicename>sl1</devicename>); you can use <command>netstat - -i</command> to see whether these interfaces are defined in your - kernel.</para> - - <para>Sample output from <command>netstat -i</command>:</para> - - <screen>Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll -ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133 -ed0 1500 138.247.224 ivory 291311 0 174209 0 133 -lo0 65535 <Link> 79 0 79 0 0 -lo0 65535 loop localhost 79 0 79 0 0 -sl0* 296 <Link> 0 0 0 0 0 -sl1* 296 <Link> 0 0 0 0 0</screen> - - <para>The <devicename>sl0</devicename> and - <devicename>sl1</devicename> interfaces shown in - <command>netstat -i</command>'s output indicate that there are - two SLIP interfaces built into the kernel. (The asterisks after - the <literal>sl0</literal> and <literal>sl1</literal> indicate - that the interfaces are <quote>down</quote>.)</para> - - <para>However, FreeBSD's default kernels do not come configured - to forward packets (ie, your FreeBSD machine will not act as a - router) due to Internet RFC requirements for Internet hosts (see - RFCs 1009 [Requirements for Internet Gateways], 1122 - [Requirements for Internet Hosts — Communication Layers], - and perhaps 1127 [A Perspective on the Host Requirements RFCs]), - so if you want your FreeBSD SLIP Server to act as a router, you - will have to edit the <filename>/etc/rc.conf</filename> file and - change the setting of the <literal>gateway_enable</literal> variable to - <option>YES</option>.</para> - - <para>You will then need to reboot for the new settings to take - effect.</para> - - <para>You will notice that near the end of the default kernel - configuration file (<filename>/sys/i386/conf/GENERIC</filename>) - is a line that reads:</para> - - <programlisting> -pseudo-device sl 2</programlisting> - - <para>This 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.</para> - - <para>Please refer to <link linkend="kernelconfig">Configuring the - FreeBSD Kernel</link> for help in reconfiguring your - kernel.</para> - </sect3> - - <sect3> - <title>Sliplogin Configuration</title> - - <para>As mentioned earlier, there are three files in the - <filename>/etc/sliphome</filename> directory that are part of - the configuration for <filename>/usr/sbin/sliplogin</filename> - (see &man.sliplogin.8; for the actual manual page for - <command>sliplogin</command>): <filename>slip.hosts</filename>, - which defines the SLIP users & their associated IP - addresses; <filename>slip.login</filename>, which usually just - configures the SLIP interface; and (optionally) - <filename>slip.logout</filename>, which undoes - <filename>slip.login</filename>'s effects when the serial - connection is terminated.</para> - - <sect4> - <title><filename>slip.hosts</filename> Configuration</title> - - <para><filename>/etc/sliphome/slip.hosts</filename> contains - lines which have at least four items, separated by - whitespace:</para> - - <itemizedlist> - <listitem> - <para>SLIP user's login ID</para> - </listitem> - - <listitem> - <para>Local address (local to the SLIP server) of the SLIP - link</para> - </listitem> - - <listitem> - <para>Remote address of the SLIP link</para> - </listitem> - - <listitem> - <para>Network mask</para> - </listitem> - </itemizedlist> - - <para>The local and remote addresses may be host names (resolved - to IP addresses by <filename>/etc/hosts</filename> or by the - domain name service, depending on your specifications in - <filename>/etc/host.conf</filename>), and I believe the - network mask may be a name that can be resolved by a lookup - into <filename>/etc/networks</filename>. On a sample system, - <filename>/etc/sliphome/slip.hosts</filename> looks like - this:</para> - - <programlisting> -# -# login local-addr remote-addr mask opt1 opt2 -# (normal,compress,noicmp) -# -Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting> - - <para>At the end of the line is one or more of the - options.</para> - - <itemizedlist> - <listitem> - <para><option>normal</option> — no header - compression</para> - </listitem> - - <listitem> - <para><option>compress</option> — compress - headers</para> - </listitem> - - <listitem> - <para><option>autocomp</option> — compress headers if - the remote end allows it</para> - </listitem> - - <listitem> - <para><option>noicmp</option> — disable ICMP packets - (so any <quote>ping</quote> packets will be dropped instead - of using up your bandwidth)</para> - </listitem> - </itemizedlist> - - <para>Note that <command>sliplogin</command> under early releases - of FreeBSD 2 ignored the options that FreeBSD 1.x recognized, - so the options <option>normal</option>, - <option>compress</option>, <option>autocomp</option>, and - <option>noicmp</option> had no effect until support was added - in FreeBSD 2.2 (unless your <filename>slip.login</filename> - script included code to make use of the flags).</para> - - <para>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 <quote>proxy ARP</quote> on - your SLIP server (it is not <quote>true</quote> proxy ARP, but - that is the terminology used in this document 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 - <link linkend="slips-prereqs">slips-prereqs</link> section - and/or consult your IP network manager.</para> - - <para>If you are going to use a separate subnet for your SLIP - clients, you will need to allocate the subnet number out of - your assigned IP network number and assign each of your SLIP - client's IP numbers out of that subnet. Then, you will - probably either need to configure a static route to the SLIP - subnet via your SLIP server on your nearest IP router, or - install <command>gated</command> on your FreeBSD SLIP server - and configure it to talk the appropriate routing protocols to - your other routers to inform them about your SLIP server's - route to the SLIP subnet.</para> - - <para>Otherwise, if you will use the <quote>proxy ARP</quote> - method, you will need to assign your SLIP client's IP - addresses out of your SLIP server's Ethernet subnet, and you - will also need to adjust your - <filename>/etc/sliphome/slip.login</filename> and - <filename>/etc/sliphome/slip.logout</filename> scripts to use - &man.arp.8; to manage the proxy-ARP entries in the SLIP - server's ARP table.</para> - </sect4> - - <sect4> - <title><filename>slip.login</filename> Configuration</title> - - <para>The typical <filename>/etc/sliphome/slip.login</filename> - file looks like this:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.login 5.1 (Berkeley) 7/1/90 - -# -# generic login file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting> - - <para>This <filename>slip.login</filename> file merely - <command>ifconfig</command>'s the appropriate SLIP interface - with the local and remote addresses and network mask of the - SLIP interface.</para> - - <para>If you have decided to use the <quote>proxy ARP</quote> - method (instead of using a separate subnet for your SLIP - clients), your <filename>/etc/sliphome/slip.login</filename> - file will need to look something like this:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.login 5.1 (Berkeley) 7/1/90 - -# -# generic login file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 inet $4 $5 netmask $6 -# Answer ARP requests for the SLIP client with our Ethernet addr -/usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting> - - <para>The additional line in this - <filename>slip.login</filename>, <command>arp -s - $5 00:11:22:33:44:55 pub</command>, creates an ARP entry - in the SLIP server's ARP table. This ARP entry causes the - SLIP server to respond with the SLIP server's Ethernet MAC - address whenever a another IP node on the Ethernet asks to - speak to the SLIP client's IP address.</para> - - <para>When using the example above, be sure to replace the - Ethernet MAC address (<hostid - role="mac">00:11:22:33:44:55</hostid>) with the MAC address of - your system's Ethernet card, or your <quote>proxy ARP</quote> - will definitely not work! You can discover your SLIP server's - Ethernet MAC address by looking at the results of running - <command>netstat -i</command>; the second line of the output - should look something like:</para> - - <screen>ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116</screen> - - <para>This indicates that this particular system's Ethernet MAC - address is <hostid role="mac">00:02:c1:28:5f:4a</hostid> - — the periods in the Ethernet MAC address given by - <command>netstat -i</command> must be changed to colons and - leading zeros should be added to each single-digit hexadecimal - number to convert the address into the form that &man.arp.8; - desires; see the manual page on &man.arp.8; for complete - information on usage.</para> - - <note> - <para>When you create - <filename>/etc/sliphome/slip.login</filename> and - <filename>/etc/sliphome/slip.logout</filename>, the - <quote>execute</quote> bit (ie, <command>chmod 755 - /etc/sliphome/slip.login /etc/sliphome/slip.logout</command>) - must be set, or <command>sliplogin</command> will be unable - to execute it.</para> - </note> - </sect4> - - <sect4> - <title><filename>slip.logout</filename> Configuration</title> - - <para><filename>/etc/sliphome/slip.logout</filename> is not - strictly needed (unless you are implementing <quote>proxy - ARP</quote>), but if you decide to create it, this is an - example of a basic - <filename>slip.logout</filename> script:</para> - - <programlisting> -#!/bin/sh - -# -# slip.logout - -# -# logout file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 down</programlisting> - - <para>If you are using <quote>proxy ARP</quote>, you will want to - have <filename>/etc/sliphome/slip.logout</filename> remove the - ARP entry for the SLIP client:</para> - - <programlisting> -#!/bin/sh - -# -# @(#)slip.logout - -# -# logout file for a slip line. sliplogin invokes this with -# the parameters: -# 1 2 3 4 5 6 7-n -# slipunit ttyspeed loginname local-addr remote-addr mask opt-args -# -/sbin/ifconfig sl$1 down -# Quit answering ARP requests for the SLIP client -/usr/sbin/arp -d $5</programlisting> - - <para>The <command>arp -d $5</command> removes the ARP entry - that the <quote>proxy ARP</quote> - <filename>slip.login</filename> added when the SLIP client - logged in.</para> - - <para>It bears repeating: make sure - <filename>/etc/sliphome/slip.logout</filename> has the execute - bit set for after you create it (ie, <command>chmod 755 - /etc/sliphome/slip.logout</command>).</para> - </sect4> - </sect3> - - <sect3> - <title>Routing Considerations</title> - - <para>If you are not using the <quote>proxy ARP</quote> method for - routing packets between your SLIP clients and the rest of your - network (and perhaps the Internet), you will probably either - have to add static routes to your closest default router(s) to - route your SLIP client subnet via your SLIP server, or you will - probably need to install and configure <command>gated</command> - on your FreeBSD SLIP server so that it will tell your routers - via appropriate routing protocols about your SLIP subnet.</para> - - <sect4> - <title>Static Routes</title> - - <para>Adding static routes to your nearest default routers can - be 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 which static routes to - tell other routers about, so some expertise and - troubleshooting/tweaking may be necessary to get - static-route-based routing to work.</para> - </sect4> - - <sect4> - <title>Running <command>gated</command></title> - - <para>An alternative to the headaches of static routes is to - install <command>gated</command> on your FreeBSD SLIP server - and configure it to use the appropriate routing protocols - (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP - subnet. You can use <command>gated</command> from the <link - linkend="ports">ports collection</link> or retrieve and build - it yourself from <ulink - url="ftp://ftp.gated.merit.edu/research.and.development/gated/">the - GateD anonymous ftp site</ulink>; I believe the current version - as of this writing is - <filename>gated-R3_5Alpha_8.tar.Z</filename>, which includes - support for FreeBSD <quote>out-of-the-box</quote>. Complete - information and documentation on <command>gated</command> is - available on the Web starting at <ulink - url="http://www.gated.merit.edu/">the Merit GateD - Consortium</ulink>. Compile and install it, and then write a - <filename>/etc/gated.conf</filename> file to configure your - gated; here is a sample, similar to what the author used on a - FreeBSD SLIP server:</para> - - <programlisting> -# -# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 -# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface -# -# -# tracing options -# -traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; - -rip yes { - interface sl noripout noripin ; - interface ed ripin ripout version 1 ; - traceoptions route ; -} ; - -# -# Turn on a bunch of tracing info for the interface to the kernel: -kernel { - traceoptions remnants request routes info interface ; -} ; - -# -# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP -# - -export proto rip interface ed { - proto direct { - <replaceable>xxx.xxx.yy</replaceable> mask 255.255.252.0 metric 1; # SLIP connections - } ; -} ; - -# -# Accept routes from RIP via ed Ethernet interfaces - -import proto rip interface ed { - all ; -} ;</programlisting> - - <para>The above sample <filename>gated.conf</filename> file - broadcasts routing information regarding the SLIP subnet - <replaceable>xxx.xxx.yy</replaceable> via RIP onto the - Ethernet; if you are using a different Ethernet driver than - the <devicename>ed</devicename> driver, you will need to - change the references to the <devicename>ed</devicename> - interface appropriately. This sample file also sets up - tracing to <filename>/var/tmp/gated.output</filename> for - debugging <command>gated</command>'s activity; you can - certainly turn off the tracing options if - <command>gated</command> works OK for you. You will need to - change the <replaceable>xxx.xxx.yy</replaceable>'s into the - network address of your own SLIP subnet (be sure to change the - net mask in the <literal>proto direct</literal> clause as - well).</para> - - <para>When you get <command>gated</command> built and installed - and create a configuration file for it, you will need to run - <command>gated</command> in place of <command>routed</command> - on your FreeBSD system; change the - <filename>routed/gated</filename> startup parameters in - <filename>/etc/netstart</filename> as appropriate for your - system. Please see the manual page for - <command>gated</command> for information on - <command>gated</command>'s command-line parameters.</para> - </sect4> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml deleted file mode 100644 index d403e08700..0000000000 --- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml +++ /dev/null @@ -1,4610 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/printing/chapter.sgml,v 1.29 2000/06/13 01:01:17 jim Exp $ ---> - -<chapter id="printing"> - <title>Printing</title> - - <para><emphasis>Contributed by &a.kelly;, 30 September 1995. - Restructured and updated by &a.jim;, March 2000.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>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 is the standard printer - control system in FreeBSD. This chapter introduces the LPD spooling - system, often simply called LPD, and will guide you through its - configuration.</para> - - <para>If you are already familiar with LPD or another printer spooling - system, you may wish to skip to section <link - linkend="printing-intro-setup">Setting up the spooling - system</link>.</para> - </sect1> - - <sect1 id="printing-intro-spooler"> - <title>Introduction</title> - - <para>LPD controls everything about a host's printers. It is - responsible for a number of things:</para> - - <itemizedlist> - <listitem> - <para>It controls access to attached printers and printers - attached to other hosts on the network.</para> - </listitem> - - <listitem> - <para>It enables users to submit files to be printed; these - submissions are known as <emphasis>jobs</emphasis>.</para> - </listitem> - - <listitem> - <para>It prevents multiple users from accessing a printer at the - same time by maintaining a <emphasis>queue</emphasis> for each - printer.</para> - </listitem> - - <listitem> - <para>It can print <emphasis>header pages</emphasis> (also known - as <emphasis>banner</emphasis> or <emphasis>burst</emphasis> - pages) so users can easily find jobs they have printed in a - stack of printouts.</para> - </listitem> - - <listitem> - <para>It takes care of communications parameters for printers - connected on serial ports.</para> - </listitem> - - <listitem> - <para>It can send jobs over the network to a LPD spooler on - another host.</para> - </listitem> - - <listitem> - <para>It can run special filters to format jobs to be printed for - various printer languages or printer capabilities.</para> - </listitem> - - <listitem> - <para>It can account for printer usage.</para> - </listitem> - </itemizedlist> - - <para>Through a configuration file - (<filename>/etc/printcap</filename>), and by providing the special - filter programs, you can enable the LPD system to do all or some - subset of the above for a great variety of printer hardware.</para> - - <sect2 id="printing-intro-why"> - <title>Why You Should Use the Spooler</title> - - <para>If you are the sole user of your system, you may be wondering - why you should bother with the spooler when you do not need access - control, header pages, or printer accounting. While it is - possible to enable direct access to a printer, you should use the - spooler anyway since:</para> - - <itemizedlist> - <listitem> - <para>LPD prints jobs in the background; you do not have to wait - for data to be copied to the printer.</para> - </listitem> - - <listitem> - <para>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 will not have to do these steps - manually.</para> - </listitem> - - <listitem> - <para>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 will more easily - support other software you may later add or already - have.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="printing-intro-setup"> - <title>Basic Setup</title> - - <para>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:</para> - - <itemizedlist> - <listitem> - <para>See section <link linkend="printing-simple">Simple Printer - Setup</link> to learn how to connect a printer, tell LPD how to - communicate with it, and print plain text files to the - printer.</para> - </listitem> - - <listitem> - <para>See section <link linkend="printing-advanced">Advanced - Printer Setup</link> to find out how to print a variety of - special file formats, to print header pages, to print across a - network, to control access to printers, and to do printer - accounting.</para> - </listitem> - </itemizedlist> - - <sect2 id="printing-simple"> - <title>Simple Printer Setup</title> - - <para>This section tells how to configure printer hardware and the - LPD software to use the printer. It teaches the basics:</para> - - <itemizedlist> - <listitem> - <para>Section <link linkend="printing-hardware">Hardware - Setup</link> gives some hints on connecting the printer to a - port on your computer.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-software">Software - Setup</link> shows how to setup the LPD spooler configuration - file (<filename>/etc/printcap</filename>).</para> - </listitem> - </itemizedlist> - - <para>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 <link linkend="printing-advanced-network-net-if">Printers With - Networked Data Stream Interfaces</link>.</para> - - <para>Although this section is called <quote>Simple Printer - Setup</quote>, 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 easy once you get the printer working.</para> - - <sect3 id="printing-hardware"> - <title>Hardware Setup</title> - - <para>This section tells about the various ways you can connect a - printer to your PC. It talks about the kinds of ports and - cables, and also the kernel configuration you may need to enable - FreeBSD to speak to the printer.</para> - - <para>If you have already connected your printer and have - successfully printed with it under another operating system, you - can probably skip to section <link - linkend="printing-software">Software Setup</link>.</para> - - <sect4 id="printing-ports"> - <title>Ports and Cables</title> - - <para>Nearly all printers you can get for a PC today support one - or both of the following interfaces:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Serial</emphasis> interfaces use a serial - port on your computer to send data to the printer. Serial - interfaces are common in the computer industry and cables - are readily available and also easy to construct. Serial - interfaces sometimes need special cables and might require - you to configure somewhat complex communications - options.</para> - </listitem> - - <listitem> - <para><emphasis>Parallel</emphasis> interfaces use a - parallel port on your computer to send data to the - printer. Parallel interfaces are common in the PC market. - Cables are readily available but more difficult to - construct by hand. There are usually no communications - options with parallel interfaces, making their - configuration exceedingly simple.</para> - - <para>Parallel interfaces are sometimes known as - <quote>Centronics</quote> interfaces, named after the - connector type on the printer.</para> - </listitem> - </itemizedlist> - - <para>In general, serial interfaces are slower than parallel - interfaces. Parallel interfaces usually offer just - one-way communication (computer to printer) while serial - gives you two-way. Many newer parallel ports and printers - can communicate in both directions under FreeBSD when a - IEEE1284 compliant cable is used.</para> - - <para>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 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 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.</para> - </sect4> - - <sect4 id="printing-parallel"> - <title>Parallel Ports</title> - - <para>To hook up a printer using a parallel interface, connect - the Centronics cable between the printer and the computer. - The instructions that came with the printer, the computer, or - both should give you complete guidance.</para> - - <para>Remember which parallel port you used on the computer. - The first parallel port is <filename>/dev/lpt0</filename> to - FreeBSD; the second is <filename>/dev/lpt1</filename>, and so - on.</para> - </sect4> - - <sect4 id="printing-serial"> - <title>Serial Ports</title> - - <para>To hook up a printer using a serial interface, connect the - proper serial cable between the printer and the computer. The - instructions that came with the printer, the computer, or both - should give you complete guidance.</para> - - <para>If you are unsure what the <quote>proper serial - cable</quote> is, you may wish to try one of the following - alternatives:</para> - - <itemizedlist> - <listitem> - <para>A <emphasis>modem</emphasis> cable connects each pin - of the connector on one end of the cable straight through - to its corresponding pin of the connector on the other - end. This type of cable is also known as a - <quote>DTE-to-DCE</quote> cable.</para> - </listitem> - - <listitem> - <para>A <emphasis>null-modem</emphasis> cable connects some - pins straight through, swaps others (send data to receive - data, for example), and shorts some internally in each - connector hood. This type of cable is also known as a - <quote>DTE-to-DTE</quote> cable.</para> - </listitem> - - <listitem> - <para>A <emphasis>serial printer</emphasis> cable, required - for some unusual printers, is like the null modem cable, - but sends some signals to their counterparts instead of - being internally shorted.</para> - </listitem> - </itemizedlist> - - <para>You should also set up the communications parameters for - the printer, usually through front-panel controls or DIP - switches on the printer. Choose the highest - <literal>bps</literal> (bits per second, sometimes - <emphasis>baud rate</emphasis>) rate that both your computer - and the printer can support. Choose 7 or 8 data bits; none, - even, or odd parity; and 1 or 2 stop bits. Also choose a flow - control protocol: either none, or XON/XOFF (also known as - <quote>in-band</quote> or <quote>software</quote>) flow control. - Remember these settings for the software configuration that - follows.</para> - </sect4> - </sect3> - - <sect3 id="printing-software"> - <title>Software Setup</title> - - <para>This section describes the software setup necessary to print - with the LPD spooling system in FreeBSD.</para> - - <para>Here is an outline of the steps involved:</para> - - <procedure> - <step> - <para>Configure your kernel, if necessary, for the port you - are using for the printer; section <link - linkend="printing-kernel">Kernel Configuration</link> tells - you what you need to do.</para> - </step> - - <step> - <para>Set the communications mode for the parallel port, if - you are using a parallel port; section <link - linkend="printing-parallel-port-mode">Setting the - Communication Mode for the Parallel Port</link> gives - details.</para> - </step> - - <step> - <para>Test if the operating system can send data to the printer. - Section <link linkend="printing-testing">Checking Printer - Communications</link> gives some suggestions on how to do - this.</para> - </step> - - <step> - <para>Set up LPD for the printer by modifying the file - <filename>/etc/printcap</filename>. You will find out how - to do this later in this chapter.</para> - </step> - </procedure> - - <sect4 id="printing-kernel"> - <title>Kernel Configuration</title> - - <para>The operating system kernel is compiled to work with a - 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 is not already configured for one.</para> - - <para>To find out if the kernel you are currently using supports - a serial interface, type:</para> - - <screen>&prompt.root; <userinput>dmesg | grep sio<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number of the - serial port, starting from zero. If you see output similar to - the following:</para> - - <screen>sio2 at 0x3e8-0x3ef irq 5 on isa -sio2: type 16550A</screen> - - <para>then the kernel supports the port.</para> - - <para>To find out if the kernel supports a parallel interface, - type:</para> - - <screen>&prompt.root; <userinput>dmesg | grep lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number of the - parallel port, starting from zero. If you see output similar - to the following <screen>lpt0 at 0x378-0x37f on isa</screen> - then the kernel supports the port.</para> - - <para>You might have to reconfigure your kernel in order for the - operating system to recognize and use the parallel or serial - port you are using for the printer.</para> - - <para>To add support for a serial port, see the section on - kernel configuration. To add support for a parallel port, see - that section <emphasis>and</emphasis> the section that - follows.</para> - </sect4> - </sect3> - - <sect3 id="printing-dev-ports"> - <title>Adding <filename>/dev</filename> Entries for the - Ports</title> - - <para>Even though the kernel may support communication along 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 is what entries in the - <filename>/dev</filename> directory are for.</para> - - <para><emphasis>To add a <filename>/dev</filename> entry for a - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with the &man.su.1; command. Enter the - root password when prompted.</para> - </step> - - <step> - <para>Change to the <filename>/dev</filename> - directory:</para> - - <screen>&prompt.root; cd <filename>/dev</filename></screen> - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>./MAKEDEV <replaceable>port</replaceable></userinput></screen> - - <para>Where <replaceable>port</replaceable> is the device - entry for the port you want to make. Use - <literal>lpt0</literal> for the first parallel port, - <literal>lpt1</literal> for the second, and so on; use - <literal>ttyd0</literal> for the first serial port, - <literal>ttyd1</literal> for the second, and so on.</para> - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>ls -l <replaceable>port</replaceable></userinput></screen> - - <para>to make sure the device entry got created.</para> - </step> - </procedure> - - <sect4 id="printing-parallel-port-mode"> - <title>Setting the Communication Mode for the Parallel - Port</title> - - <para>When you are using the parallel interface, you can choose - whether FreeBSD should use interrupt-driven or polled - communication with the printer.</para> - - <itemizedlist> - <listitem> - <para>The <emphasis>interrupt-driven</emphasis> method is - the default with the GENERIC kernel. With this method, - the operating system uses an IRQ line to determine when - the printer is ready for data.</para> - </listitem> - - <listitem> - <para>The <emphasis>polled</emphasis> method directs the - operating system to repeatedly ask the printer if it is - ready for more data. When it responds ready, the kernel - sends more data.</para> - </listitem> - </itemizedlist> - - <para>The interrupt-driven method is somewhat faster but uses up - a precious IRQ line. You should use whichever one - works.</para> - - <para>You can set the communications mode in two ways: by - configuring the kernel or by using the &man.lptcontrol.8; - program.</para> - - <para><emphasis>To set the communications mode by configuring - the kernel:</emphasis></para> - - <procedure> - <step> - <para>Edit your kernel configuration file. Look for or add - an <literal>lpt0</literal> entry. If you are setting up - the second parallel port, use <literal>lpt1</literal> - instead. Use <literal>lpt2</literal> for the third port, - and so on.</para> - - <itemizedlist> - <listitem> - <para>If you want interrupt-driven mode, add the - <literal>irq</literal> specifier:</para> - - <programlisting> -device lpt0 at isa? port? tty irq <replaceable>N</replaceable> vector lptintr</programlisting> - - <para>Where <replaceable>N</replaceable> is the IRQ - number for your computer's parallel port.</para> - </listitem> - - <listitem> - <para>If you want polled mode, do not add the - <literal>irq</literal> specifier:</para> - - <programlisting> -device lpt0 at isa? port? tty vector lptintr</programlisting> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Save the file. Then configure, build, and install the - kernel, then reboot. See <link - linkend="kernelconfig">kernel configuration</link> for - more details.</para> - </step> - </procedure> - - <para><emphasis>To set the communications mode with</emphasis> - &man.lptcontrol.8;:</para> - - <procedure> - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptcontrol -i -u <replaceable>N</replaceable></userinput></screen> - - <para>to set interrupt-driven mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> - </step> - - <step> - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptcontrol -p -u <replaceable>N</replaceable></userinput></screen> - - <para>to set polled-mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> - </step> - </procedure> - - <para>You could put these commands in your - <filename>/etc/rc.local</filename> file to set the mode each - time your system boots. See &man.lptcontrol.8; for more - information.</para> - </sect4> - - <sect4 id="printing-testing"> - <title>Checking Printer Communications</title> - - <para>Before proceeding to configure the spooling system, you - should make sure the operating system can successfully send - data to your printer. It is a lot easier to debug printer - communication and the spooling system separately.</para> - - <para>To test the printer, we will send some text to it. For - printers that can immediately print characters sent to them, - the program &man.lptest.1; is perfect: it generates all 96 - printable ASCII characters in 96 lines.</para> - - <para>For a PostScript (or other language-based) printer, we - will need a more sophisticated test. A small PostScript - program, such as the following, will suffice:</para> - - <programlisting> -%!PS -100 100 moveto 300 300 lineto stroke -310 310 moveto /Helvetica findfont 12 scalefont setfont -(Is this thing working?) show -showpage</programlisting> - - <note> - <para>When this document refers to a printer language, it is - 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 is the - kind of printer language for which we must make special - accommodations.</para> - </note> - - <sect5 id="printing-checking-parallel"> - <title>Checking a Parallel Printer</title> - - <para>This section tells you how to check if FreeBSD can - communicate with a printer connected to a parallel - port.</para> - - <para><emphasis>To test a printer on a parallel - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with &man.su.1;.</para> - </step> - - <step> - <para>Send data to the printer.</para> - - <itemizedlist> - <listitem> - <para>If the printer can print plain text, then use - &man.lptest.1;. Type:</para> - - <screen>&prompt.root; <userinput>lptest > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>N</replaceable> is the number - of the parallel port, starting from zero.</para> - </listitem> - - <listitem> - <para>If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type:</para> - - <screen>&prompt.root; <userinput>cat > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Then, line by line, type the program - <emphasis>carefully</emphasis> as you cannot edit a - line once you have pressed <literal>RETURN</literal> - or <literal>ENTER</literal>. When you have finished - entering the program, press - <literal>CONTROL+D</literal>, or whatever your end - of file key is.</para> - - <para>Alternatively, you can put the program in a file - and type:</para> - - <screen>&prompt.root; <userinput>cat <replaceable>file</replaceable> > /dev/lpt<replaceable>N</replaceable></userinput></screen> - - <para>Where <replaceable>file</replaceable> is the - name of the file containing the program you want to - send to the printer.</para> - </listitem> - </itemizedlist> - </step> - </procedure> - - <para>You should see something print. Do not worry if the - text does not look right; we will fix such things - later.</para> - </sect5> - - <sect5 id="printing-checking-serial"> - <title>Checking a Serial Printer</title> - - <para>This section tells you how to check if FreeBSD can - communicate with a printer on a serial port.</para> - - <para><emphasis>To test a printer on a serial - port:</emphasis></para> - - <procedure> - <step> - <para>Become root with &man.su.1;.</para> - </step> - - <step> - <para>Edit the file <filename>/etc/remote</filename>. Add - the following entry:</para> - - <programlisting> -printer:dv=/dev/<replaceable>port</replaceable>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting> - - <para>Where <replaceable>port</replaceable> is the device - entry for the serial port (<literal>ttyd0</literal>, - <literal>ttyd1</literal>, etc.), - <replaceable>bps-rate</replaceable> is the - bits-per-second rate at which the printer communicates, - and <replaceable>parity</replaceable> is the parity - required by the printer (either <literal>even</literal>, - <literal>odd</literal>, <literal>none</literal>, or - <literal>zero</literal>).</para> - - <para>Here is a sample entry for a printer connected via - a serial line to the third serial port at 19200 bps with - no parity:</para> - - <programlisting> -printer:dv=/dev/ttyd2:br#19200:pa=none</programlisting> - </step> - - <step> - <para>Connect to the printer with &man.tip.1;. - Type:</para> - - <screen>&prompt.root; <userinput>tip printer</userinput></screen> - - <para>If this step does not work, edit the file - <filename>/etc/remote</filename> again and try using - <filename>/dev/cuaa<replaceable>N</replaceable></filename> - instead of - <filename>/dev/ttyd<replaceable>N</replaceable></filename>.</para> - </step> - - <step> - <para>Send data to the printer.</para> - - <itemizedlist> - <listitem> - <para>If the printer can print plain text, then use - &man.lptest.1;. Type:</para> - - <screen><prompt>~</prompt><userinput>$lptest</userinput></screen> - </listitem> - - <listitem> - <para>If the printer understands PostScript or other - printer language, then send a small program to the - printer. Type the program, line by line, - <emphasis>very carefully</emphasis> as backspacing - or other editing keys may be significant to the - printer. You may also need to type a special - end-of-file key for the printer so it knows it - received the whole program. For PostScript - printers, press <literal>CONTROL+D</literal>.</para> - - <para>Alternatively, you can put the program in a file - and type:</para> - - <screen><prompt>~</prompt><userinput>><replaceable>file</replaceable></userinput></screen> - - <para>Where <replaceable>file</replaceable> is the - name of the file containing the program. After - &man.tip.1; sends the file, press any required - end-of-file key.</para> - </listitem> - </itemizedlist> - </step> - </procedure> - - <para>You should see something print. Do not worry if the - text does not look right; we will fix that later.</para> - </sect5> - </sect4> - </sect3> - - <sect3 id="printing-printcap"> - <title>Enabling the Spooler: The <filename>/etc/printcap</filename> - File</title> - - <para>At this point, your printer should be hooked up, your kernel - configured to communicate with it (if necessary), 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.</para> - - <para>You configure LPD by editing the file - <filename>/etc/printcap</filename>. The LPD spooling system - reads this file each time the spooler is used, so updates to the - file take immediate effect.</para> - - <para>The format of the &man.printcap.5; file is straightforward. - Use your favorite text editor to make changes to - <filename>/etc/printcap</filename>. The format is identical to - other capability files like - <filename>/usr/share/misc/termcap</filename> and - <filename>/etc/remote</filename>. For complete information - about the format, see the &man.cgetent.3;.</para> - - <para>The simple spooler configuration consists of the following - steps:</para> - - <procedure> - <step> - <para>Pick a name (and a few convenient aliases) for the - printer, and put them in the - <filename>/etc/printcap</filename> file; see the - <link linkend="printing-naming">Naming the Printer</link> - section for more information on naming.</para> - </step> - - <step> - <para>Turn off header pages (which are on by default) by - inserting the <literal>sh</literal> capability; see the - <link linkend="printing-no-header-pages">Suppressing Header - Pages</link> section for more information.</para> - </step> - - <step> - <para>Make a spooling directory, and specify its location with - the <literal>sd</literal> capability; see the <link - linkend="printing-spooldir">Making the Spooling - Directory</link> section for more information.</para> - </step> - - <step> - <para>Set the <filename>/dev</filename> entry to use for the - printer, and note it in <filename>/etc/printcap</filename> - with the <literal>lp</literal> capability; see the <link - linkend="printing-device">Identifying the Printer - Device</link> for more information. Also, if the printer is - on a serial port, set up the communication parameters with - the <literal>fs</literal>, <literal>fc</literal>, - <literal>xs</literal>, and <literal>xc</literal> - capabilities; which is discussed in the <link - linkend="printing-commparam">Configuring Spooler - Communications Parameters</link> section.</para> - </step> - - <step> - <para>Install a plain text input filter; see the <link - linkend="printing-textfilter">Installing the Text - Filter</link> section for details.</para> - </step> - - <step> - <para>Test the setup by printing something with the - &man.lpr.1; command. More details are available in the - <link linkend="printing-trying">Trying It Out</link> and - <link - linkend="printing-troubleshooting">Troubleshooting</link> - sections.</para> - </step> - </procedure> - - <note> - <para>Language-based printers, such as PostScript printers, - cannot directly print plain text. The simple setup outlined - above and described in the following sections assumes that if - you are installing such a printer you will print only files - that the printer can understand.</para> - </note> - - <para>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 are installing such a printer and want to be able to - print jobs in the printer language <emphasis>and</emphasis> - 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. The section entitled <link - linkend="printing-advanced-if-conversion">Accommodating Plain - Text Jobs on PostScript Printers</link> tells how to do - this.</para> - - <sect4 id="printing-naming"> - <title>Naming the Printer</title> - - <para>The first (easy) step is to pick a name for your printer - It really does not matter whether you choose functional or - whimsical names since you can also provide a number of aliases - for the printer.</para> - - <para>At least one of the printers specified in the - <filename>/etc/printcap</filename> should have the alias - <literal>lp</literal>. This is the default printer's name. - If users do not have the <envar>PRINTER</envar> environment - variable nor specify a printer name on the command line of any - of the LPD commands, then <literal>lp</literal> will be the - default printer they get to use.</para> - - <para>Also, it is common practice to make the last alias for a - printer be a full description of the printer, including make - and model.</para> - - <para>Once you have picked a name and some common aliases, put - them in the <filename>/etc/printcap</filename> file. The name - of the printer should start in the leftmost column. Separate - each alias with a vertical bar and put a colon after the last - alias.</para> - - <para>In the following example, we start with a skeletal - <filename>/etc/printcap</filename> that defines two printers - (a Diablo 630 line printer and a Panasonic KX-P4455 PostScript - laser printer):</para> - - <programlisting> -# -# /etc/printcap for host rose -# -rattan|line|diablo|lp|Diablo 630 Line Printer: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:</programlisting> - - <para>In this example, the first printer is named - <literal>rattan</literal> and has as aliases - <literal>line</literal>, <literal>diablo</literal>, - <literal>lp</literal>, and <literal>Diablo 630 Line - Printer</literal>. Since it has the alias - <literal>lp</literal>, it is also the default printer. The - second is named <literal>bamboo</literal>, and has as aliases - <literal>ps</literal>, <literal>PS</literal>, - <literal>S</literal>, <literal>panasonic</literal>, and - <literal>Panasonic KX-P4455 PostScript v51.4</literal>.</para> - </sect4> - - <sect4 id="printing-no-header-pages"> - <title>Suppressing Header Pages</title> - - <para>The LPD spooling system will by default print a - <emphasis>header page</emphasis> for each job. The header - page contains 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 will suppress - header pages.</para> - - <para>To suppress header pages, add the <literal>sh</literal> - capability to the entry for the printer in - <filename>/etc/printcap</filename>. Here is an example - <filename>/etc/printcap</filename> with <literal>sh</literal> - added:</para> - - <programlisting> -# -# /etc/printcap for host rose - no header pages anywhere -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:</programlisting> - - <para>Note how we used the correct format: the first line starts - in the leftmost column, and subsequent lines are indented with - a single TAB. Every line in an entry except the last ends in - a backslash character.</para> - </sect4> - - <sect4 id="printing-spooldir"> - <title>Making the Spooling Directory</title> - - <para>The next step in the simple spooler setup is to make a - <emphasis>spooling directory</emphasis>, a directory where - print jobs reside until they are printed, and where a number - of other spooler support files live.</para> - - <para>Because of the variable nature of spooling directories, it - is customary to put these directories under - <filename>/var/spool</filename>. It is not necessary to - backup the contents of spooling directories, either. - Recreating them is as simple as running &man.mkdir.1;.</para> - - <para>It is also customary to make the directory with a name - that is identical to the name of the printer, as shown - below:</para> - - <screen>&prompt.root; <userinput>mkdir /var/spool/<replaceable>printer-name</replaceable></userinput></screen> - - <para>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 - will do this for our two example printers - <literal>rattan</literal> and - <literal>bamboo</literal>:</para> - - <screen>&prompt.root; <userinput>mkdir /var/spool/lpd</userinput> -&prompt.root; <userinput>mkdir /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>mkdir /var/spool/lpd/bamboo</userinput></screen> - - <note> - <para>If you are concerned about the privacy of jobs that - users print, you might want to protect the 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 will do this for our example printers:</para> - - <screen>&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/bamboo</userinput></screen> - </note> - - <para>Finally, you need to tell LPD about these directories - using the <filename>/etc/printcap</filename> file. You - specify the pathname of the spooling directory with the - <literal>sd</literal> capability:</para> - - <programlisting> -# -# /etc/printcap for host rose - added spooling directories -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:</programlisting> - - <para>Note that the name of the printer starts in the first - column but all other entries describing the printer should be - indented with a tab and each line escaped with a - backslash.</para> - - <para>If you do not specify a spooling directory with - <literal>sd</literal>, the spooling system will use - <filename>/var/spool/lpd</filename> as a default.</para> - </sect4> - - <sect4 id="printing-device"> - <title>Identifying the Printer Device</title> - - <para>In the <link linkend="printing-dev-ports">Adding - <filename>/dev</filename> Entries for the Ports</link> - section, we identified which entry in the - <filename>/dev</filename> directory FreeBSD will use to - communicate with the printer. Now, we tell LPD that - information. When the spooling system has a job to print, it - will open the specified device on behalf of the filter program - (which is responsible for passing data to the printer).</para> - - <para>List the <filename>/dev</filename> entry pathname in the - <filename>/etc/printcap</filename> file using the - <literal>lp</literal> capability.</para> - - <para>In our running example, let us assume that - <hostid>rattan</hostid> is on the first parallel port, and - <hostid>bamboo</hostid> is on a sixth serial port; here are - the additions to <filename>/etc/printcap</filename>:</para> - - <programlisting> -# -# /etc/printcap for host rose - identified what devices to use -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:</programlisting> - - <para>If you do not specify the <literal>lp</literal> capability - for a printer in your <filename>/etc/printcap</filename> file, - LPD uses <filename>/dev/lp</filename> as a default. - <filename>/dev/lp</filename> currently does not exist in - FreeBSD.</para> - - <para>If the printer you are installing is connected to a - parallel port, skip to the section entitled, <link - linkend="printing-textfilter">Installing the Text - Filter</link>. Otherwise, be sure to follow the instructions - in the next section.</para> - </sect4> - - <sect4 id="printing-commparam"> - <title>Configuring Spooler Communication Parameters</title> - - <para>For printers on serial ports, LPD can set up the bps rate, - parity, and other serial communication parameters on behalf of - the filter program that sends data to the printer. This is - advantageous since:</para> - - <itemizedlist> - <listitem> - <para>It lets you try different communication parameters by - simply editing the <filename>/etc/printcap</filename> - file; you do not have to recompile the filter - program.</para> - </listitem> - - <listitem> - <para>It enables the spooling system to use the same filter - program for multiple printers which may have different - serial communication settings.</para> - </listitem> - </itemizedlist> - - <para>The following <filename>/etc/printcap</filename> - capabilities control serial communication parameters of the - device listed in the <literal>lp</literal> capability:</para> - - <variablelist> - <varlistentry> - <term><literal>br#<replaceable>bps-rate</replaceable></literal></term> - - <listitem> - <para>Sets the communications speed of the device to - <replaceable>bps-rate</replaceable>, where - <replaceable>bps-rate</replaceable> can be 50, 75, 110, - 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, - 19200, or 38400 bits-per-second.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>fc#<replaceable>clear-bits</replaceable></literal></term> - - <listitem> - <para>Clears the flag bits - <replaceable>clear-bits</replaceable> in the - <replaceable>sgttyb</replaceable> structure after - opening the device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>fs#<replaceable>set-bits</replaceable></literal></term> - - <listitem> - <para>Sets the flag bits - <replaceable>set-bits</replaceable> in the - <replaceable>sgttyb</replaceable> structure.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>xc#<replaceable>clear-bits</replaceable></literal></term> - - <listitem> - <para>Clears local mode bits - <replaceable>clear-bits</replaceable> after opening the - device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>xs#<replaceable>set-bits</replaceable></literal></term> - - <listitem> - <para>Sets local mode bits - <replaceable>set-bits</replaceable>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information on the bits for the - <literal>fc</literal>, <literal>fs</literal>, - <literal>xc</literal>, and <literal>xs</literal> capabilities, - see the file - <filename>/usr/include/sys/ioctl_compat.h</filename>.</para> - - <para>When LPD opens the device specified by the - <literal>lp</literal> capability, it reads the flag bits in - the <literal>sgttyb</literal> structure; it clears any bits in - the <literal>fc</literal> capability, then sets bits in the - <literal>fs</literal> capability, then applies the resultant - setting. It does the same for the local mode bits as - well.</para> - - <para>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 <literal>TANDEM</literal>, - <literal>ANYP</literal>, <literal>LITOUT</literal>, - <literal>FLUSHO</literal>, and <literal>PASS8</literal> flags. - For the local mode bits, we will set the - <literal>LITOUT</literal> and <literal>PASS8</literal> - flags:</para> - - <programlisting> -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:</programlisting> - </sect4> - - <sect4 id="printing-textfilter"> - <title>Installing the Text Filter</title> - - <para>We are now ready to tell LPD what text filter to use to - send jobs to the printer. A <emphasis>text filter</emphasis>, - also known as an <emphasis>input filter</emphasis>, is a - program that LPD runs when it has a job to print. When LPD - runs the text filter for a printer, it sets the filter's - standard input to the job to print, and its standard output to - the printer device specified with the <literal>lp</literal> - capability. The filter is expected to read the job from - standard input, perform any necessary translation for the - printer, and write the results to standard output, which will - get printed. For more information on the text filter, see - the <link linkend="printing-advanced-filters">Filters</link> - section.</para> - - <para>For our simple printer setup, the text filter can be a - small shell script that just executes - <command>/bin/cat</command> to send the job to the printer. - FreeBSD comes with another filter called - <filename>lpf</filename> that handles backspacing and - underlining for printers that might not deal with such - character streams well. And, of course, you can use any other - filter program you want. The filter <command>lpf</command> is - described in detail in section entitled <link - linkend="printing-advanced-lpf">lpf: a Text - Filter</link>.</para> - - <para>First, let us make the shell script - <filename>/usr/local/libexec/if-simple</filename> be a simple - text filter. Put the following text into that file with your - favorite text editor:</para> - - <programlisting> -#!/bin/sh -# -# if-simple - Simple text input filter for lpd -# Installed in /usr/local/libexec/if-simple -# -# Simply copies stdin to stdout. Ignores all filter arguments. - -/bin/cat && exit 0 -exit 2</programlisting> - - <para>Make the file executable:</para> - - <screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/if-simple</userinput></screen> - - <para>And then tell LPD to use it by specifying it with the - <literal>if</literal> capability in - <filename>/etc/printcap</filename>. We will add it to the two - printers we have so far in the example - <filename>/etc/printcap</filename>:</para> - - <programlisting> -# -# /etc/printcap for host rose - added text filter -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:\ - :if=/usr/local/libexec/if-simple:</programlisting> - </sect4> - - <sect4> - <title>Turn on LPD</title> - - <para>&man.lpd.8; is run from <filename>/etc/rc</filename>, - controlled by the <literal>lpd_enable</literal> variable. This - variable defaults to <literal>NO</literal>. If you have not done - so already, add the line:</para> - - <programlisting>lpd_enable="YES"</programlisting> - - <para>to <filename>/etc/rc.conf</filename>, and then either restart - your machine, or just run &man.lpd.8;.</para> - - <screen>&prompt.root; <userinput>lpd</userinput></screen> - </sect4> - - <sect4 id="printing-trying"> - <title>Trying It Out</title> - - <para>You have reached the end of the simple LPD setup. - Unfortunately, congratulations are not quite yet in 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 &man.lpr.1;, - which submits a job for printing.</para> - - <para>You can combine &man.lpr.1; with the &man.lptest.1; - program, introduced in section <link - linkend="printing-testing">Checking Printer - Communications</link> to generate some test text.</para> - - <para><emphasis>To test the simple LPD setup:</emphasis></para> - - <para>Type:</para> - - <screen>&prompt.root; <userinput>lptest 20 5 | lpr -P<replaceable>printer-name</replaceable></userinput></screen> - - <para>Where <replaceable>printer-name</replaceable> is a the - name of a printer (or an alias) specified in - <filename>/etc/printcap</filename>. To test the default - printer, type &man.lpr.1; without any <option>-P</option> - argument. Again, if you are testing a printer that expects - PostScript, send a PostScript program in that language instead - of using &man.lptest.1;. You can do so by putting the program - in a file and typing <command>lpr - <replaceable>file</replaceable></command>.</para> - - <para>For a PostScript printer, you should get the results of - the program. If you are using &man.lptest.1;, then your - results should look like the following:</para> - - <programlisting> -!"#$%&'()*+,-./01234 -"#$%&'()*+,-./012345 -#$%&'()*+,-./0123456 -$%&'()*+,-./01234567 -%&'()*+,-./012345678</programlisting> - - <para>To further test the printer, try downloading larger - programs (for language-based printers) or running - &man.lptest.1; with different arguments. For example, - <command>lptest 80 60</command> will produce 60 lines of 80 - characters each.</para> - - <para>If the printer did not work, see the <link - linkend="printing-troubleshooting">Troubleshooting</link> - section.</para> - </sect4> - </sect3> - </sect2> - </sect1> - - <sect1 id="printing-advanced"> - <title>Advanced Printer Setup</title> - - <para>This section describes filters for printing specially formatted - files, header pages, printing across networks, and restricting and - accounting for printer usage.</para> - - <sect2 id="printing-advanced-filter-intro"> - <title>Filters</title> - - <para>Although LPD handles network protocols, queuing, access control, - and other aspects of printing, most of the <emphasis>real</emphasis> - work happens in the <emphasis>filters</emphasis>. Filters are - programs that communicate with the printer and handle its device - dependencies and special requirements. In the simple printer setup, - we installed a plain text filter—an extremely simple one that - should work with most printers (section <link - linkend="printing-textfilter">Installing the Text - Filter</link>).</para> - - <para>However, in order to take advantage of format conversion, printer - accounting, specific printer quirks, and so on, you should understand - how filters work. It will ultimately be the filter's responsibility - to handle these aspects. And the bad news is that most of the time - <emphasis>you</emphasis> have to provide filters yourself. The good - news is that many are generally available; when they are not, they are - usually easy to write.</para> - - <para>Also, FreeBSD comes with one, - <filename>/usr/libexec/lpr/lpf</filename>, that works with many - printers that can print plain text. (It handles backspacing and tabs - in the file, and does accounting, but that is about all it does.) - There are also several filters and filter components in the FreeBSD - ports collection.</para> - - <para>Here is what you will find in this section:</para> - - <itemizedlist> - <listitem> - <para>Section <link linkend="printing-advanced-filters">How Filters - Work</link>, 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 is happening <quote>under the hood</quote> - when LPD uses filters. This knowledge could help you anticipate - and debug problems you might encounter as you install more and - more filters on each of your printers.</para> - </listitem> - - <listitem> - <para>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 cannot directly print plain text. - Section <link - linkend="printing-advanced-if-conversion">Accommodating - Plain Text Jobs on PostScript Printers</link> tells you what you - should do to overcome this problem. I recommend reading this - section if you have a PostScript printer.</para> - </listitem> - - <listitem> - <para>PostScript is a popular output format for many programs. Even - some people (myself included) write PostScript code directly. But - PostScript printers are expensive. Section <link - linkend="printing-advanced-ps">Simulating PostScript on - Non-PostScript Printers</link> tells how you can further modify - a printer's text filter to accept and print PostScript data on a - <emphasis>non-PostScript</emphasis> printer. I recommend reading - this section if you do not have a PostScript printer.</para> - </listitem> - - <listitem> - <para>Section <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> tells about a way you can automate the conversion - of specific file formats, such as graphic or typesetting data, - into formats your printer can understand. After reading this - section, you should be able to set up your printers such that - users can type <command>lpr -t</command> to print troff data, or - <command>lpr -d</command> to print TeX DVI data, or <command>lpr - -v</command> to print raster image data, and so forth. I - recommend reading this section.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-advanced-of">Output - Filters</link> tells all about a not often used feature of LPD: - output filters. Unless you are printing header pages (see <link - linkend="printing-advanced-header-pages">Header Pages</link>), - you can probably skip that section altogether.</para> - </listitem> - - <listitem> - <para>Section <link linkend="printing-advanced-lpf">lpf: a Text - Filter</link> describes <command>lpf</command>, a fairly - complete if simple text filter for line printers (and laser - printers that act like line printers) that comes with FreeBSD. If - you need a quick way to get printer accounting working for plain - text, or if you have a printer which emits smoke when it sees - backspace characters, you should definitely consider - <command>lpf</command>.</para> - </listitem> - </itemizedlist> - - <sect3 id="printing-advanced-filters"> - <title>How Filters Work</title> - - <para>As mentioned before, a filter is an executable program started - by LPD to handle the device-dependent part of communicating with the - printer.</para> - - <para>When LPD wants to print a file in a job, it starts a filter - program. It sets the filter's standard input to the file to print, - its standard output to the printer, and its standard error to the - error logging file (specified in the <literal>lf</literal> - capability in <filename>/etc/printcap</filename>, or - <filename>/dev/console</filename> by default).</para> - - <para>Which filter LPD starts and the filter's arguments depend on - what is listed in the <filename>/etc/printcap</filename> file and - what arguments the user specified for the job on the - &man.lpr.1; command line. For example, if the user typed - <command>lpr -t</command>, LPD would start the troff filter, listed - in the <literal>tf</literal> capability for the destination printer. - If the user wanted to print plain text, it would start the - <literal>if</literal> filter (this is mostly true: see <link - linkend="printing-advanced-of">Output Filters</link> for - details).</para> - - <para>There are three kinds of filters you can specify in - <filename>/etc/printcap</filename>:</para> - - <itemizedlist> - <listitem> - <para>The <emphasis>text filter</emphasis>, confusingly called the - <emphasis>input filter</emphasis> 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 is the text filter's job to make sure backspaces, tabs, - or other special characters do not confuse the printer. 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 lines per page the printer supports. The - text filter is started with the following argument list: - - <cmdsynopsis> - <command>filter-name</command> - <arg>-c</arg> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - <arg choice="plain">-i<replaceable>indent</replaceable></arg> - <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg choice="plain"><replaceable>acct-file</replaceable></arg> - </cmdsynopsis> - - where - - <variablelist> - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>appears if the job's submitted with <command>lpr - -l</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>width</replaceable></term> - - <listitem> - <para>is the value from the <literal>pw</literal> (page - width) capability specified in - <filename>/etc/printcap</filename>, default 132</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>length</replaceable></term> - - <listitem> - <para>is the value from the <literal>pl</literal> (page - length) capability, default 66</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>indent</replaceable></term> - - <listitem> - <para>is the amount of the indentation from <command>lpr - -i</command>, default 0</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>login</replaceable></term> - - <listitem> - <para>is the account name of the user printing the - file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>host</replaceable></term> - - <listitem> - <para>is the host name from which the job was - submitted</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>acct-file</replaceable></term> - - <listitem> - <para>is the name of the accounting file from the - <literal>af</literal> capability.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - </listitem> - - <listitem> - <para>A <emphasis>conversion filter</emphasis> converts a specific - file format into one the printer can render onto paper. 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 <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> tells all about them. Conversion filters also - need to do accounting, if you need printer accounting. - Conversion filters are started with the following arguments: - - <cmdsynopsis> - <command>filter-name</command> - <arg - choice="plain">-x<replaceable>pixel-width</replaceable></arg> - <arg choice="plain">-y<replaceable>pixel-height</replaceable></arg> - <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg choice="plain"><replaceable>acct-file</replaceable></arg> - </cmdsynopsis> - - where <replaceable>pixel-width</replaceable> is the value - from the <literal>px</literal> capability (default 0) and - <replaceable>pixel-height</replaceable> is the value from the - <literal>py</literal> capability (default 0).</para> - </listitem> - - <listitem> - <para>The <emphasis>output filter</emphasis> is used only if there - is no text filter, or if header pages are enabled. In my - experience, output filters are rarely used. Section <link - linkend="printing-advanced-of">Output Filters</link> describe - them. There are only two arguments to an output filter: - - <cmdsynopsis> - <command>filter-name</command> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - </cmdsynopsis> - - which are identical to the text filters <option>-w</option> and - <option>-l</option> arguments.</para> - </listitem> - </itemizedlist> - - <para>Filters should also <emphasis>exit</emphasis> with the - following exit status:</para> - - <variablelist> - <varlistentry> - <term>exit 0</term> - - <listitem> - <para>If the filter printed the file successfully.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>exit 1</term> - - <listitem> - <para>If the filter failed to print the file but wants LPD to - try to print the file again. LPD will restart a filter if it - exits with this status.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>exit 2</term> - - <listitem> - <para>If the filter failed to print the file and does not want - LPD to try again. LPD will throw out the file.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The text filter that comes with the FreeBSD release, - <filename>/usr/libexec/lpr/lpf</filename>, takes advantage of the - page width and length arguments to determine when to send a form - feed and how to account for printer usage. It uses the login, host, - and accounting file arguments to make the accounting entries.</para> - - <para>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 argument lists and exit codes.</para> - </sect3> - - <sect3 id="printing-advanced-if-conversion"> - <title>Accommodating Plain Text Jobs on PostScript Printers</title> - - <para>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 do not - need to worry about this section at all.</para> - - <para>But, if you would like to send both PostScript and plain 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 - <literal>%!</literal> (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 are not the first two characters in the file, then the filter - will convert the text into PostScript and print the result.</para> - - <para>How do we do this?</para> - - <para>If you have got a serial printer, a great way to do it is to - install <command>lprps</command>. <command>lprps</command> is a - PostScript printer filter which performs two-way communication with - the printer. It updates the printer's status file with verbose - information from the printer, so users and administrators can see - exactly what the state of the printer is (such as <errorname>toner - low</errorname> or <errorname>paper jam</errorname>). But more - importantly, it includes a program called <command>psif</command> - which detects whether the incoming job is plain text and calls - <command>textps</command> (another program that comes with - <command>lprps</command>) to convert it to PostScript. It then uses - <command>lprps</command> to send the job to the printer.</para> - - <para><command>lprps</command> is part of the FreeBSD ports collection - (see <link linkend="ports">The Ports Collection</link>). You can - fetch, build and install it yourself, of course. After installing - <command>lprps</command>, just specify the pathname to the - <command>psif</command> program that is part of - <command>lprps</command>. If you installed <command>lprps</command> - from the ports collection, use the following in the serial - PostScript printer's entry in - <filename>/etc/printcap</filename>:</para> - - <programlisting> -:if=/usr/local/libexec/psif:</programlisting> - - <para>You should also specify the <literal>rw</literal> capability; - that tells LPD to open the printer in read-write mode.</para> - - <para>If you have a parallel PostScript printer (and therefore cannot - use two-way communication with the printer, which - <command>lprps</command> needs), you can use the following shell - script as the text filter:</para> - - <programlisting> -#!/bin/sh -# -# psif - Print PostScript or plain text on a PostScript printer -# Script version; NOT the version that comes with lprps -# Installed in /usr/local/libexec/psif -# - -read first_line -first_two_chars=`expr "$first_line" : '\(..\)'` - -if [ "$first_two_chars" = "%!" ]; then - # - # PostScript job, print it. - # - echo "$first_line" && cat && printf "\004" && exit 0 - exit 2 -else - # - # Plain text, convert it, then print it. - # - ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0 - exit 2 -fi</programlisting> - - <para>In the above script, <command>textps</command> is a program we - installed separately to convert plain text to PostScript. You can - use any text-to-PostScript program you wish. The FreeBSD ports - collection (see <link linkend="ports">The Ports Collection</link>) - includes a full featured text-to-PostScript program called - <literal>a2ps</literal> that you might want to investigate.</para> - </sect3> - - <sect3 id="printing-advanced-ps"> - <title>Simulating PostScript on Non-PostScript Printers</title> - - <para>PostScript is the <emphasis>de facto</emphasis> standard for - high quality typesetting and printing. PostScript is, however, an - <emphasis>expensive</emphasis> standard. Thankfully, Alladin - Enterprises has a free PostScript work-alike called - <application>Ghostscript</application> that runs with FreeBSD. - Ghostscript can read most PostScript files and can render their - pages onto a variety of devices, including many brands of - non-PostScript printers. By installing Ghostscript and using a - special text filter for your printer, you can make your - non-PostScript printer act like a real PostScript printer.</para> - - <para>Ghostscript is in the FreeBSD ports collection, if you - would like to install it from there. You can fetch, build, and - install it quite easily yourself, as well.</para> - - <para>To simulate PostScript, we have the text filter detect if 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.</para> - - <para>Here is an example: the following script is a text filter - for Hewlett Packard DeskJet 500 printers. For other printers, - substitute the <option>-sDEVICE</option> argument to the - <command>gs</command> (Ghostscript) command. (Type <command>gs - -h</command> to get a list of devices the current installation of - Ghostscript supports.)</para> - - <programlisting> -#!/bin/sh -# -# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500 -# Installed in /usr/local/libexec/hpif - -# -# Treat LF as CR+LF: -# -printf "\033&k2G" || exit 2 - -# -# Read first two characters of the file -# -read first_line -first_two_chars=`expr "$first_line" : '\(..\)'` - -if [ "$first_two_chars" = "%!" ]; then - # - # It is PostScript; use Ghostscript to scan-convert and print it. - # - # Note that PostScript files are actually interpreted programs, - # and those programs are allowed to write to stdout, which will - # mess up the printed output. So, we redirect stdout to stderr - # and then make descriptor 3 go to stdout, and have Ghostscript - # write its output there. Exercise for the clever reader: - # capture the stderr output from Ghostscript and mail it back to - # the user originating the print job. - # - exec 3>&1 1>&2 - /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \ - -sOutputFile=/dev/fd/3 - && exit 0 - - # - /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \ - && exit 0 -else - # - # Plain text or HP/PCL, so just print it directly; print a form - # at the end to eject the last page. - # - echo $first_line && cat && printf "\033&l0H" && -exit 0 -fi - -exit 2</programlisting> - - <para>Finally, you need to notify LPD of the filter via the - <literal>if</literal> capability:</para> - - <programlisting> -:if=/usr/local/libexec/hpif:</programlisting> - - <para>That is it. You can type <command>lpr plain.text</command> and - <filename>lpr whatever.ps</filename> and both should print - successfully.</para> - </sect3> - - <sect3 id="printing-advanced-convfilters"> - <title>Conversion Filters</title> - - <para>After completing the simple setup described in <link - linkend="printing-simple">Simple Printer Setup</link>, the first - thing you will probably want to do is install conversion filters for - your favorite file formats (besides plain ASCII text).</para> - - <sect4> - <title>Why Install Conversion Filters?</title> - - <para>Conversion filters make printing various kinds of 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 cannot print it directly until - we convert the DVI file into PostScript. The command sequence - goes like this:</para> - - <screen>&prompt.user; <userinput>dvips seaweed-analysis.dvi</userinput> -&prompt.user; <userinput>lpr seaweed-analysis.ps</userinput></screen> - - <para>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 are just one step away from - printing it:</para> - - <screen>&prompt.user; <userinput>lpr -d seaweed-analysis.dvi</userinput></screen> - - <para>We got LPD to do the DVI file conversion for us by specifying - the <option>-d</option> option. Section <link - linkend="printing-lpr-options-format">Formatting and Conversion - Options</link> lists the conversion options.</para> - - <para>For each of the conversion options you want a printer to - support, install a <emphasis>conversion filter</emphasis> and - specify its pathname in <filename>/etc/printcap</filename>. A - conversion filter is like the text filter for the simple printer - setup (see section <link linkend="printing-textfilter">Installing - the Text Filter</link>) except that instead of printing plain - text, the filter converts the file into a format the printer can - understand.</para> - </sect4> - - <sect4> - <title>Which Conversions Filters Should I Install?</title> - - <para>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 have got plenty of troff to print out, then you - probably want a troff filter.</para> - - <para>The following table summarizes the filters that LPD works - with, their capability entries for the - <filename>/etc/printcap</filename> file, and how to invoke them - with the <command>lpr</command> command:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>File type</entry> - <entry><filename>/etc/printcap</filename> capability</entry> - <entry><command>lpr</command> option</entry> - </row> - </thead> - - <tbody> - <row> - <entry>cifplot</entry> - <entry><literal>cf</literal></entry> - <entry><option>-c</option></entry> - </row> - - <row> - <entry>DVI</entry> - <entry><literal>df</literal></entry> - <entry><option>-d</option></entry> - </row> - - <row> - <entry>plot</entry> - <entry><literal>gf</literal></entry> - <entry><option>-g</option></entry> - </row> - - <row> - <entry>ditroff</entry> - <entry><literal>nf</literal></entry> - <entry><option>-n</option></entry> - </row> - - <row> - <entry>FORTRAN text</entry> - <entry><literal>rf</literal></entry> - <entry><option>-f</option></entry> - </row> - - <row> - <entry>troff</entry> - <entry><literal>rf</literal></entry> - <entry><option>-f</option></entry> - </row> - - <row> - <entry>raster</entry> - <entry><literal>vf</literal></entry> - <entry><option>-v</option></entry> - </row> - - <row> - <entry>plain text</entry> - <entry><literal>if</literal></entry> - <entry>none, <option>-p</option>, or - <option>-l</option></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>In our example, using <command>lpr -d</command> means the - printer needs a <literal>df</literal> capability in its entry in - <filename>/etc/printcap</filename>.</para> - - <para>Despite what others might contend, formats like FORTRAN 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 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 - <literal>gf</literal> capability and then educate your users that - <command>lpr -g</command> mean <quote>print Printerleaf - files.</quote></para> - </sect4> - - <sect4> - <title>Installing Conversion Filters</title> - - <para>Since conversion filters are programs you install outside of - the base FreeBSD installation, they should probably go under - <filename>/usr/local</filename>. The directory - <filename>/usr/local/libexec</filename> is a popular location, - since they are specialized programs that only LPD will run; - regular users should not ever need to run them.</para> - - <para>To enable a conversion filter, specify its pathname under the - appropriate capability for the destination printer in - <filename>/etc/printcap</filename>.</para> - - <para>In our example, we will add the DVI conversion filter to the - entry for the printer named <literal>bamboo</literal>. Here is - the example <filename>/etc/printcap</filename> file again, with - the new <literal>df</literal> capability for the printer - <literal>bamboo</literal>.</para> - - <programlisting> -# -# /etc/printcap for host rose - added df filter for bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>The DVI filter is a shell script named - <filename>/usr/local/libexec/psdf</filename>. Here is that - script:</para> - - <programlisting> -#!bin/sh -# -# psdf - DVI to PostScript printer filter -# Installed in /usr/local/libexec/psdf -# -# Invoked by lpd when user runs lpr -d -# -exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"</programlisting> - - <para>This script runs <command>dvips</command> in filter mode (the - <option>-f</option> argument) on standard input, which is the job - to print. It then starts the PostScript printer filter - <command>lprps</command> (see section <link - linkend="printing-advanced-if-conversion">Accommodating Plain - Text Jobs on PostScript Printers</link>) with the arguments LPD - passed to this script. <command>lprps</command> will use those - arguments to account for the pages printed.</para> - </sect4> - - <sect4> - <title>More Conversion Filter Examples</title> - - <para>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.</para> - - <para>This example script is a raster (well, GIF file, actually) - conversion filter for a Hewlett Packard LaserJet III-Si - printer:</para> - - <programlisting> -#!/bin/sh -# -# hpvf - Convert GIF files into HP/PCL, then print -# Installed in /usr/local/libexec/hpvf - -PATH=/usr/X11R6/bin:$PATH; export PATH -giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ - && exit 0 \ - || exit 2</programlisting> - - <para>It works by converting the GIF file into a portable anymap, - converting that into a portable graymap, converting that into a - portable bitmap, and converting that into LaserJet/PCL-compatible - data.</para> - - <para>Here is the <filename>/etc/printcap</filename> file with an - entry for a printer using the above filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:\ - :vf=/usr/local/libexec/hpvf:</programlisting> - - <para>The following script is a conversion filter for troff data - from the groff typesetting system for the PostScript printer named - <literal>bamboo</literal>:</para> - - <programlisting> -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops | /usr/local/libexec/lprps "$@"</programlisting> - - <para>The above script makes use of <command>lprps</command> again - to handle the communication with the printer. If the printer were - on a parallel port, we would use this script instead:</para> - - <programlisting> -#!/bin/sh -# -# pstf - Convert groff's troff data into PS, then print. -# Installed in /usr/local/libexec/pstf -# -exec grops</programlisting> - - <para>That is it. Here is the entry we need to add to - <filename>/etc/printcap</filename> to enable the filter:</para> - - <programlisting> -:tf=/usr/local/libexec/pstf:</programlisting> - - <para>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 - <literal>teak</literal>:</para> - - <programlisting> -#!/bin/sh -# -# hprf - FORTRAN text filter for LaserJet 3si: -# Installed in /usr/local/libexec/hprf -# - -printf "\033&k2G" && fpr && printf "\033&l0H" && - exit 0 -exit 2</programlisting> - - <para>And we will add this line to the - <filename>/etc/printcap</filename> for the printer - <literal>teak</literal> to enable this filter:</para> - - <programlisting> -:rf=/usr/local/libexec/hprf:</programlisting> - - <para>Here is one final, somewhat complex example. We will add a - DVI filter to the LaserJet printer <literal>teak</literal> - introduced earlier. First, the easy part: updating - <filename>/etc/printcap</filename> with the location of the DVI - filter:</para> - - <programlisting> -:df=/usr/local/libexec/hpdf:</programlisting> - - <para>Now, for the hard part: making the filter. For that, we need - a DVI-to-LaserJet/PCL conversion program. The FreeBSD ports - collection (see <link linkend="ports">The Ports Collection</link>) - has one: <command>dvi2xx</command> is the name of the package. - Installing this package gives us the program we need, - <command>dvilj2p</command>, which converts DVI into LaserJet IIp, - LaserJet III, and LaserJet 2000 compatible codes.</para> - - <para><command>dvilj2p</command> makes the filter - <command>hpdf</command> quite complex since - <command>dvilj2p</command> cannot read from standard input. It - wants to work with a filename. What is worse, the filename has to - end in <filename>.dvi</filename> so using - <filename>/dev/fd/0</filename> for standard input is problematic. - We can get around that problem by linking (symbolically) a - temporary file name (one that ends in <filename>.dvi</filename>) - to <filename>/dev/fd/0</filename>, thereby forcing - <command>dvilj2p</command> to read from standard input.</para> - - <para>The only other fly in the ointment is the fact that we cannot - use <filename>/tmp</filename> for the temporary link. Symbolic - links are owned by user and group <username>bin</username>. The - filter runs as user <username>daemon</username>. And the - <filename>/tmp</filename> directory has the sticky bit set. The - filter can create the link, but it will not be able clean up when - done and remove it since the link will belong to a different - user.</para> - - <para>Instead, the filter will make the symbolic link in the current - working directory, which is the spooling directory (specified by - the <literal>sd</literal> capability in - <filename>/etc/printcap</filename>). This is a perfect place for - filters to do their work, especially since there is (sometimes) - more free disk space in the spooling directory than under - <filename>/tmp</filename>.</para> - - <para>Here, finally, is the filter:</para> - - <programlisting> -#!/bin/sh -# -# hpdf - Print DVI data on HP/PCL printer -# Installed in /usr/local/libexec/hpdf - -PATH=/usr/local/bin:$PATH; export PATH - -# -# Define a function to clean up our temporary files. These exist -# in the current directory, which will be the spooling directory -# for the printer. -# -cleanup() { - rm -f hpdf$$.dvi -} - -# -# Define a function to handle fatal errors: print the given message -# and exit 2. Exiting with 2 tells LPD to do not try to reprint the -# job. -# -fatal() { - echo "$@" 1>&2 - cleanup - exit 2 -} - -# -# If user removes the job, LPD will send SIGINT, so trap SIGINT -# (and a few other signals) to clean up after ourselves. -# -trap cleanup 1 2 15 - -# -# Make sure we are not colliding with any existing files. -# -cleanup - -# -# Link the DVI input file to standard input (the file to print). -# -ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" - -# -# Make LF = CR+LF -# -printf "\033&k2G" || fatal "Cannot initialize printer" - -# -# Convert and print. Return value from dvilj2p does not seem to be -# reliable, so we ignore it. -# -dvilj2p -M1 -q -e- dfhp$$.dvi - -# -# Clean up and exit -# -cleanup -exit 0</programlisting> - </sect4> - - <sect4 id="printing-advanced-autoconv"> - <title>Automated Conversion: An Alternative To Conversion - Filters</title> - - <para>All these conversion filters accomplish a lot for your - printing environment, but at the cost forcing the user to specify - (on the &man.lpr.1; command line) which one to use. - If your users are not particularly computer literate, having to - specify a filter option will become 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.</para> - - <para>Rather than install conversion filters at all, you might 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 - <command>file</command> can be of help here. Of course, it will - be hard to determine the differences between - <emphasis>some</emphasis> file types—and, of course, you can - still provide conversion filters just for them.</para> - - <para>The FreeBSD ports collection has a text filter that performs - automatic conversion called <command>apsfilter</command>. It can - detect plain text, PostScript, and DVI files, run the proper - conversions, and print.</para> - </sect4> - </sect3> - - <sect3 id="printing-advanced-of"> - <title>Output Filters</title> - - <para>The LPD spooling system supports one other type of 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 are using an output filter but no - text filter, then:</para> - - <itemizedlist> - <listitem> - <para>LPD starts an output filter once for the entire job instead - of once for each file in the job.</para> - </listitem> - - <listitem> - <para>LPD does not make any provision to identify the start or the - end of files within the job for the output filter.</para> - </listitem> - - <listitem> - <para>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:</para> - - <cmdsynopsis> - <command>filter-name</command> - <arg choice="plain">-w<replaceable>width</replaceable></arg> - <arg choice="plain">-l<replaceable>length</replaceable></arg> - </cmdsynopsis> - - <para>Where <replaceable>width</replaceable> is from the - <literal>pw</literal> capability and - <replaceable>length</replaceable> is from the - <literal>pl</literal> capability for the printer in - question.</para> - </listitem> - </itemizedlist> - - <para>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 <emphasis>will not work</emphasis>. Use a text filter (also - known as an input filter); see section <link - linkend="printing-textfilter">Installing the Text Filter</link>. - Furthermore, an output filter is actually <emphasis>more - complex</emphasis> in that it has to examine the byte stream being - sent to it for special flag characters and must send signals to - itself on behalf of LPD.</para> - - <para>However, an output filter is <emphasis>necessary</emphasis> 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 - is also <emphasis>futile</emphasis> if you want to charge header - pages to the requesting user's account, since LPD does not give any - user or host information to the output filter.)</para> - - <para>On a single printer, LPD allows both an output filter and text - or other filters. In such cases, LPD will start the output filter - to print the header page (see section <link - linkend="printing-advanced-header-pages">Header Pages</link>) - only. LPD then expects the output filter to <emphasis>stop - itself</emphasis> 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 will restart the output filter by - sending SIGCONT to it.</para> - - <para>If there is an output filter but <emphasis>no</emphasis> 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 intervening form - feeds or other paper advancement, and this is probably - <emphasis>not</emphasis> what you want. In almost all cases, you - need a text filter.</para> - - <para>The program <command>lpf</command>, 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 do not want to write the byte - detection and signal sending code, try <command>lpf</command>. You - can also wrap <command>lpf</command> in a shell script to handle any - initialization codes the printer might require.</para> - </sect3> - - <sect3 id="printing-advanced-lpf"> - <title><command>lpf</command>: a Text Filter</title> - - <para>The program <filename>/usr/libexec/lpr/lpf</filename> that comes - with FreeBSD binary distribution is a text filter (input filter) - that can indent output (job submitted with <command>lpr - -i</command>), allow literal characters to pass (job submitted - with <command>lpr -l</command>), adjust the printing position for - backspaces and tabs in the job, and account for pages printed. It - can also act like an output filter.</para> - - <para><command>lpf</command> is suitable for many printing - environments. And although it has no capability to send - initialization sequences to a printer, it is easy to write a shell - script to do the needed initialization and then execute - <command>lpf</command>.</para> - - <para>In order for <command>lpf</command> to do page accounting - correctly, it needs correct values filled in for the - <literal>pw</literal> and <literal>pl</literal> capabilities in the - <filename>/etc/printcap</filename> file. It uses these values to - determine how much text can fit on a page and how many pages were in - a user's job. For more information on printer accounting, see <link - linkend="printing-advanced-acct">Accounting for Printer - Usage</link>.</para> - </sect3> - </sect2> - - <sect2 id="printing-advanced-header-pages"> - <title>Header Pages</title> - - <para>If you have <emphasis>lots</emphasis> of users, all of them using - various printers, then you probably want to consider <emphasis>header - pages</emphasis> as a necessary evil.</para> - - <para>Header pages, also known as <emphasis>banner</emphasis> or - <emphasis>burst pages</emphasis> 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 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. (Note that header pages go with each job, not each file in a - job, so the paper waste might not be that bad.)</para> - - <para>The LPD system can provide header pages automatically for your - printouts <emphasis>if</emphasis> your printer can directly print - plain text. If you have a PostScript printer, you will need an - external program to generate the header page; see <link - linkend="printing-advanced-header-pages-ps">Header Pages on - PostScript Printers</link>.</para> - - <sect3 id="printing-advanced-header-pages-enabling"> - <title>Enabling Header Pages</title> - - <para>In the <link linkend="printing-simple">Simple Printer - Setup</link>, we turned off header pages by specifying - <literal>sh</literal> (meaning <quote>suppress header</quote>) in the - <filename>/etc/printcap</filename> file. To enable header pages for - a printer, just remove the <literal>sh</literal> capability.</para> - - <para>Sounds too easy, right?</para> - - <para>You are right. You <emphasis>might</emphasis> have to provide - an output filter to send initialization strings to the printer. - Here is an example output filter for Hewlett Packard PCL-compatible - printers:</para> - - <programlisting> -#!/bin/sh -# -# hpof - Output filter for Hewlett Packard PCL-compatible printers -# Installed in /usr/local/libexec/hpof - -printf "\033&k2G" || exit 2 -exec /usr/libexec/lpr/lpf</programlisting> - - <para>Specify the path to the output filter in the - <literal>of</literal> capability. See <link - linkend="printing-advanced-of">Output Filters</link> for more - information.</para> - - <para>Here is an example <filename>/etc/printcap</filename> file for - the printer <literal>teak</literal> that we introduced earlier; we - enabled header pages and added the above output filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:\ - :vf=/usr/local/libexec/hpvf:\ - :of=/usr/local/libexec/hpof:</programlisting> - - <para>Now, when users print jobs to <literal>teak</literal>, they get - a header page with each job. If users want to spend time searching - for their printouts, they can suppress header pages by submitting - the job with <command>lpr -h</command>; see <link - linkend="printing-lpr-options-misc">Header Page Options</link> for - more &man.lpr.1; options.</para> - - <note> - <para>LPD prints a form feed character after the header page. If - your printer uses a different character or sequence of characters - to eject a page, specify them with the <literal>ff</literal> - capability in <filename>/etc/printcap</filename>.</para> - </note> - </sect3> - - <sect3 id="printing-advanced-header-pages-controlling"> - <title>Controlling Header Pages</title> - - <para>By enabling header pages, LPD will produce a <emphasis>long - header</emphasis>, a full page of large letters identifying the - user, host, and job. Here is an example (kelly printed the job - named outline from host rose):</para> - - <programlisting> - k ll ll - k l l - k l l - k k eeee l l y y - k k e e l l y y - k k eeeeee l l y y - kk k e l l y y - k k e e l l y yy - k k eeee lll lll yyy y - y - y y - yyyy - - - ll - t l i - t l - oooo u u ttttt l ii n nnn eeee - o o u u t l i nn n e e - o o u u t l i n n eeeeee - o o u u t l i n n e - o o u uu t t l i n n e e - oooo uuu u tt lll iii n n eeee - - - - - - - - - - r rrr oooo ssss eeee - rr r o o s s e e - r o o ss eeeeee - r o o ss e - r o o s s e e - r oooo ssss eeee - - - - - - - - Job: outline - Date: Sun Sep 17 11:04:58 1995</programlisting> - - <para>LPD appends a form feed after this text so the job starts on a - new page (unless you have <literal>sf</literal> (suppress form - feeds) in the destination printer's entry in - <filename>/etc/printcap</filename>).</para> - - <para>If you prefer, LPD can make a <emphasis>short header</emphasis>; - specify <literal>sb</literal> (short banner) in the - <filename>/etc/printcap</filename> file. The header page will look - like this:</para> - - <programlisting> -rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995</programlisting> - - <para>Also by default, LPD prints the header page first, then the job. - To reverse that, specify <literal>hl</literal> (header last) in - <filename>/etc/printcap</filename>.</para> - </sect3> - - <sect3 id="printing-advanced-header-pages-accounting"> - <title>Accounting for Header Pages</title> - - <para>Using LPD's built-in header pages enforces a particular paradigm - when it comes to printer accounting: header pages must be - <emphasis>free of charge</emphasis>.</para> - - <para>Why?</para> - - <para>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 is not provided with any <emphasis>user or - host</emphasis> information or an accounting file, so it has no - idea whom to charge for printer use. It is also not enough to just - <quote>add one page</quote> to the text filter or any of the - conversion filters (which do have user and host information) since - users can suppress header pages with <command>lpr -h</command>. - They could still be charged for header pages they did not print. - Basically, <command>lpr -h</command> will be the preferred option of - environmentally-minded users, but you cannot offer any incentive to - use it.</para> - - <para>It is <emphasis>still not enough</emphasis> 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 <command>lpr -h</command>, they will still get - them and be charged for them since LPD does not pass any knowledge - of the <option>-h</option> option to any of the filters.</para> - - <para>So, what are your options?</para> - - <para>You can:</para> - - <itemizedlist> - <listitem> - <para>Accept LPD's paradigm and make header pages free.</para> - </listitem> - - <listitem> - <para>Install an alternative to LPD, such as LPRng. Section - <link linkend="printing-lpd-alternatives">Alternatives to the - Standard Spooler</link> tells more about other spooling - software you can substitute for LPD.</para> - </listitem> - - <listitem> - <para>Write a <emphasis>smart</emphasis> output filter. Normally, - an output filter is not meant to do anything more than - initialize a printer or do some simple character 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 - the header pages. And the output filter can parse the 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 does not know what - accounting file to use (it is not passed the name of the file - from the <literal>af</literal> capability), but if you have a - well-known accounting file, you can hard-code that into the - output filter. To facilitate the parsing step, use the - <literal>sh</literal> (short header) capability in - <filename>/etc/printcap</filename>. Then again, all that might - be too much trouble, and users will certainly appreciate the - more generous system administrator who makes header pages - free.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3 id="printing-advanced-header-pages-ps"> - <title>Header Pages on PostScript Printers</title> - - <para>As described above, LPD can generate a plain text header page - suitable for many printers. Of course, PostScript cannot directly - print plain text, so the header page feature of LPD is - useless—or mostly so.</para> - - <para>One obvious way to get header pages is to have every conversion - filter and the text filter generate the header page. The filters - should should use the user and host arguments to generate a suitable - header page. The drawback of this method is that users will always - get a header page, even if they submit jobs with <command>lpr - -h</command>.</para> - - <para>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:</para> - - <programlisting> -#!/bin/sh -# -# make-ps-header - make a PostScript header page on stdout -# Installed in /usr/local/libexec/make-ps-header -# - -# -# These are PostScript units (72 to the inch). Modify for A4 or -# whatever size paper you are using: -# -page_width=612 -page_height=792 -border=72 - -# -# Check arguments -# -if [ $# -ne 3 ]; then - echo "Usage: `basename $0` <user> <host> <job>" 1>&2 - exit 1 -fi - -# -# Save these, mostly for readability in the PostScript, below. -# -user=$1 -host=$2 -job=$3 -date=`date` - -# -# Send the PostScript code to stdout. -# -exec cat <<EOF -%!PS - -% -% Make sure we do not interfere with user's job that will follow -% -save - -% -% Make a thick, unpleasant border around the edge of the paper. -% -$border $border moveto -$page_width $border 2 mul sub 0 rlineto -0 $page_height $border 2 mul sub rlineto -currentscreen 3 -1 roll pop 100 3 1 roll setscreen -$border 2 mul $page_width sub 0 rlineto closepath -0.8 setgray 10 setlinewidth stroke 0 setgray - -% -% Display user's login name, nice and large and prominent -% -/Helvetica-Bold findfont 64 scalefont setfont -$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto -($user) show - -% -% Now show the boring particulars -% -/Helvetica findfont 14 scalefont setfont -/y 200 def -[ (Job:) (Host:) (Date:) ] { -200 y moveto show /y y 18 sub def } -forall - -/Helvetica-Bold findfont 14 scalefont setfont -/y 200 def -[ ($job) ($host) ($date) ] { - 270 y moveto show /y y 18 sub def -} forall - -% -% That is it -% -restore -showpage -EOF</programlisting> - - <para>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 is the DVI conversion filter from earlier in this - document, modified to make a header page:</para> - - <programlisting> -#!/bin/sh -# -# psdf - DVI to PostScript printer filter -# Installed in /usr/local/libexec/psdf -# -# Invoked by lpd when user runs lpr -d -# - -orig_args="$@" - -fail() { - echo "$@" 1>&2 - exit 2 -} - -while getopts "x:y:n:h:" option; do - case $option in - x|y) ;; # Ignore - n) login=$OPTARG ;; - h) host=$OPTARG ;; - *) echo "LPD started `basename $0` wrong." 1>&2 - exit 2 - ;; - esac -done - -[ "$login" ] || fail "No login name" -[ "$host" ] || fail "No host name" - -( /usr/local/libexec/make-ps-header $login $host "DVI File" - /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args</programlisting> - - <para>Notice how the filter has to parse the argument list in order to - determine the user and host name. The parsing for the other - conversion filters is identical. The text filter takes a slightly - different set of arguments, though (see section <link - linkend="printing-advanced-filters">How Filters - Work</link>).</para> - - <para>As we have mentioned before, the above scheme, though fairly - simple, disables the <quote>suppress header page</quote> option (the - <option>-h</option> option) to <command>lpr</command>. If users - wanted to save a tree (or a few pennies, if you charge for header - pages), they would not be able to do so, since every filter's going - to print a header page with every job.</para> - - <para>To allow users to shut off header pages on a per-job basis, you - will need to use the trick introduced in section <link - linkend="printing-advanced-header-pages-accounting">Accounting for - Header Pages</link>: write an output filter that parses the - LPD-generated header page and produces a PostScript version. If the - user submits the job with <command>lpr -h</command>, 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.</para> - - <para>If you have a PostScript printer on a serial line, you can make - use of <command>lprps</command>, which comes with an output filter, - <command>psof</command>, which does the above. Note that - <command>psof</command> does not charge for header pages.</para> - </sect3> - </sect2> - - <sect2 id="printing-advanced-network-printers"> - <title>Networked Printing</title> - - <para>FreeBSD supports networked printing: sending jobs to remote - printers. Networked printing generally refers to two different - things:</para> - - <itemizedlist> - <listitem> - <para>Accessing a printer attached to a remote host. You install a - printer that has a conventional serial or parallel interface on - one host. Then, you set up LPD to enable access to the printer - from other hosts on the network. Section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link> tells how to do this.</para> - </listitem> - - <listitem> - <para>Accessing a printer attached directly to a network. The - printer has a network interface in addition (or in place of) a - more conventional serial or parallel interface. Such a printer - might work as follows:</para> - - <itemizedlist> - <listitem> - <para>It might understand the LPD protocol and can even queue - jobs from remote hosts. In this case, it acts just like a - regular host running LPD. Follow the same procedure in - section <link linkend="printing-advanced-network-rm">Printers - Installed on Remote Hosts</link> to set up such a - printer.</para> - </listitem> - - <listitem> - <para>It might support a data stream network connection. In this - case, you <quote>attach</quote> the printer to one host on the - network by making that host responsible for spooling jobs and - sending them to the printer. Section <link - linkend="printing-advanced-network-net-if">Printers with - Networked Data Stream Interfaces</link> gives some - suggestions on installing such printers.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - <sect3 id="printing-advanced-network-rm"> - <title>Printers Installed on Remote Hosts</title> - - <para>The LPD spooling system has built-in support for sending jobs to - other hosts also running LPD (or are compatible with LPD). This - feature enables you to install a printer on one host and make it - accessible from other hosts. It also works with printers that have - network interfaces that understand the LPD protocol.</para> - - <para>To enable this kind of remote printing, first install a printer - on one host, the <emphasis>printer host</emphasis>, using the simple - printer setup described in <link linkend="printing-simple">Simple - Printer Setup</link>. Do any advanced setup in <link - linkend="printing-advanced">Advanced Printer Setup</link> that you - need. Make sure to test the printer and see if it works with the - features of LPD you have enabled. Also ensure that the - <emphasis>local host</emphasis> has authorization to use the LPD - service in the <emphasis>remote host</emphasis> (see <link - linkend="printing-advanced-restricting-remote">Restricting Jobs - from Remote Printers</link>).</para> - - <para>If you are using a printer with a network interface that is - compatible with LPD, then the <emphasis>printer host</emphasis> in - the discussion below is the printer itself, and the - <emphasis>printer name</emphasis> is the name you configured for the - printer. See the documentation that accompanied your printer and/or - printer-network interface.</para> - - <tip> - <para>If you are using a Hewlett Packard Laserjet then the printer - name <literal>text</literal> will automatically perform the LF to - CRLF conversion for you, so you will not require the - <filename>hpif</filename> script.</para> - </tip> - - <para>Then, on the other hosts you want to have access to the printer, - make an entry in their <filename>/etc/printcap</filename> files with - the following:</para> - - <orderedlist> - <listitem> - <para>Name the entry anything you want. For simplicity, though, - you probably want to use the same name and aliases as on the - printer host.</para> - </listitem> - - <listitem> - <para>Leave the <literal>lp</literal> capability blank, explicitly - (<literal>:lp=:</literal>).</para> - </listitem> - - <listitem> - <para>Make a spooling directory and specify its location in the - <literal>sd</literal> capability. LPD will store jobs here - before they get sent to the printer host.</para> - </listitem> - - <listitem> - <para>Place the name of the printer host in the - <literal>rm</literal> capability.</para> - </listitem> - - <listitem> - <para>Place the printer name on the <emphasis>printer - host</emphasis> in the <literal>rp</literal> - capability.</para> - </listitem> - </orderedlist> - - <para>That is it. You do not need to list conversion filters, page - dimensions, or anything else in the - <filename>/etc/printcap</filename> file.</para> - - <para>Here is an example. The host <hostid>rose</hostid> has two - printers, <literal>bamboo</literal> and <literal>rattan</literal>. - We will enable users on the host orchid to print to those printers. - Here is the <filename>/etc/printcap</filename> file for - <hostid>orchid</hostid> (back from section <link - linkend="printing-advanced-header-pages-enabling">Enabling Header - Pages</link>). It already had the entry for the printer - <literal>teak</literal>; we have added entries for the two printers - on the host rose:</para> - - <programlisting> -# -# /etc/printcap for host orchid - added (remote) printers on rose -# - -# -# 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:\ - :if=/usr/local/libexec/ifhp:\ - :vf=/usr/local/libexec/vfhp:\ - :of=/usr/local/libexec/ofhp: - -# -# rattan is connected to rose; send jobs for rattan to rose: -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: - -# -# bamboo is connected to rose as well: -# -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:</programlisting> - - <para>Then, we just need to make spooling directories on - <hostid>orchid</hostid>:</para> - - <screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> -&prompt.root; <userinput>chown daemon.daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput></screen> - - <para>Now, users on <hostid>orchid</hostid> can print to - <literal>rattan</literal> and <literal>bamboo</literal>. If, for - example, a user on orchid typed - - <screen>&prompt.user; <userinput>lpr -P bamboo -d sushi-review.dvi</userinput></screen> - - the LPD system on orchid would copy the job to the spooling - directory <filename>/var/spool/lpd/bamboo</filename> and note that - it was a DVI job. As soon as the host rose has room in its - <hostid>bamboo</hostid> spooling directory, the two LPDs would - transfer the file to rose. The file would wait in rose's queue - until it was finally printed. It would be converted from DVI to - PostScript (since bamboo is a PostScript printer) on rose.</para> - </sect3> - - <sect3 id="printing-advanced-network-net-if"> - <title>Printers with Networked Data Stream Interfaces</title> - - <para>Often, when you buy a network interface card for a printer, you - can get two versions: one which emulates a spooler (the more - expensive version), or one which just 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 one, see the previous section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link>.</para> - - <para>The format of the <filename>/etc/printcap</filename> file lets - you specify what serial or parallel interface to use, and (if you - are using a serial interface), what baud rate, whether to use flow - control, delays for tabs, conversion of 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.</para> - - <para>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 is one such example: the script - <command>netprint</command> 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 to which to - connect as the second argument to <command>netprint</command>. Note - that this supports one-way communication only (FreeBSD to printer); - many network printers support two-way communication, and you might - want to take advantage of that (to get printer status, perform - accounting, etc.).</para> - - <programlisting> -#!/usr/bin/perl -# -# netprint - Text filter for printer attached to network -# Installed in /usr/local/libexec/netprint -# -$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>"; - -$printer_host = $ARGV[0]; -$printer_port = $ARGV[1]; - -require 'sys/socket.ph'; - -($ignore, $ignore, $protocol) = getprotobyname('tcp'); -($ignore, $ignore, $ignore, $ignore, $address) - = gethostbyname($printer_host); - -$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address); - -socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol) - || die "Can't create TCP/IP stream socket: $!"; -connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!"; -while (<STDIN>) { print PRINTER; } -exit 0;</programlisting> - - <para>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 is the text filter for the - printer:</para> - - <programlisting> -#!/bin/sh -# -# diablo-if-net - Text filter for Diablo printer `scrivener' listening -# on port 5100. Installed in /usr/local/libexec/diablo-if-net -# -exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</programlisting> - </sect3> - </sect2> - - <sect2 id="printing-advanced-restricting"> - <title>Restricting Printer Usage</title> - - <para>This section gives information on restricting printer usage. The - LPD system lets you control who can access a printer, both locally or - remotely, whether they can print multiple copies, how large their jobs - can be, and how large the printer queues can get.</para> - - <sect3 id="printing-advanced-restricting-copies"> - <title>Restricting Multiple Copies</title> - - <para>The LPD system makes it easy for users to print multiple copies - of a file. Users can print jobs with <command>lpr -#5</command> - (for example) and get five copies of each file in the job. Whether - this is a good thing is up to you.</para> - - <para>If you feel multiple copies cause unnecessary wear and tear on - your printers, you can disable the <option>-#</option> option to - &man.lpr.1; by adding the <literal>sc</literal> capability to the - <filename>/etc/printcap</filename> file. When users submit jobs - with the <option>-#</option> option, they will see:</para> - - <screen>lpr: multiple copies are not allowed</screen> - - - <para>Note that if you have set up access to a printer remotely (see - section <link linkend="printing-advanced-network-rm">Printers - Installed on Remote Hosts</link>), you need the - <literal>sc</literal> capability on the remote - <filename>/etc/printcap</filename> files as well, or else users will - still be able to submit multiple-copy jobs by using another - host.</para> - - <para>Here is an example. This is the - <filename>/etc/printcap</filename> file for the host - <hostid>rose</hostid>. The printer <literal>rattan</literal> is - quite hearty, so we will allow multiple copies, but the laser - printer <literal>bamboo</literal>'s a bit more delicate, so we will - disable multiple copies by adding the <literal>sc</literal> - capability:</para> - - <programlisting> -# -# /etc/printcap for host rose - restrict multiple copies on bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Now, we also need to add the <literal>sc</literal> capability on - the host <hostid>orchid</hostid>'s - <filename>/etc/printcap</filename> (and while we are at it, let us - disable multiple copies for the printer - <literal>teak</literal>):</para> - - <programlisting> -# -# /etc/printcap for host orchid - no multiple copies for local -# printer teak or remote printer bamboo -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\ - :if=/usr/local/libexec/ifhp:\ - :vf=/usr/local/libexec/vfhp:\ - :of=/usr/local/libexec/ofhp: - -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:</programlisting> - - <para>By using the <literal>sc</literal> capability, we prevent the - use of <command>lpr -#</command>, but that still does not prevent - users from running &man.lpr.1; - multiple times, or from submitting the same file multiple times in - one job like this:</para> - - <screen>&prompt.user; <userinput>lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</userinput></screen> - - <para>There are many ways to prevent this abuse (including ignoring - it) which you are free to explore.</para> - </sect3> - - <sect3 id="printing-advanced-restricting-access"> - <title>Restricting Access To Printers</title> - - <para>You can control who can print to what printers by using the UNIX - group mechanism and the <literal>rg</literal> capability in - <filename>/etc/printcap</filename>. Just place the users you want - to have access to a printer in a certain group, and then name that - group in the <literal>rg</literal> capability.</para> - - <para>Users outside the group (including root) will be greeted with - - <errorname>lpr: Not a member of the restricted group</errorname> - - if they try to print to the controlled printer.</para> - - <para>As with the <literal>sc</literal> (suppress multiple copies) - capability, you need to specify <literal>rg</literal> on remote - hosts that also have access to your printers, if you feel it is - appropriate (see section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link>).</para> - - <para>For example, we will let anyone access the printer - <literal>rattan</literal>, but only those in group - <literal>artists</literal> can use <literal>bamboo</literal>. Here - is the familiar <filename>/etc/printcap</filename> for host - <hostid>rose</hostid>:</para> - - <programlisting> -# -# /etc/printcap for host rose - restricted group for bamboo -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Let us leave the other example - <filename>/etc/printcap</filename> file (for the host - <hostid>orchid</hostid>) alone. Of course, anyone on - <hostid>orchid</hostid> can print to <literal>bamboo</literal>. It - might be the case that we only allow certain logins on - <hostid>orchid</hostid> anyway, and want them to have access to the - printer. Or not.</para> - - <note> - <para>There can be only one restricted group per printer.</para> - </note> - </sect3> - - <sect3 id="printing-advanced-restricting-sizes"> - <title>Controlling Sizes of Jobs Submitted</title> - - <para>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 is only so much free space on the - filesystem that houses the spooling directories, and you also need - to make sure there is room for the jobs of other users.</para> - - <para>LPD enables you to limit the maximum byte size a file in a job - can be with the <literal>mx</literal> capability. The units are in - BUFSIZ blocks, which are 1024 bytes. If you put a zero for this - capability, there will be no limit on file size; however, if no - <literal>mx</literal> capability is specified, then a default limit - of 1000 blocks will be used.</para> - - <note> - <para>The limit applies to <emphasis>files</emphasis> in a job, and - <emphasis>not</emphasis> the total job size.</para> - </note> - - <para>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.</para> - - <para>Let us add limits to our example printers - <literal>rattan</literal> and <literal>bamboo</literal>. Since - those artists' PostScript files tend to be large, we will limit them - to five megabytes. We will put no limit on the plain text line - printer:</para> - - <programlisting> -# -# /etc/printcap for host rose -# - -# -# No limit on job size: -# -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:mx#0:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple: - -# -# Limit of five megabytes: -# -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>Again, the limits apply to the local users only. If you have - set up access to your printers remotely, remote users will not get - those limits. You will need to specify the <literal>mx</literal> - capability in the remote <filename>/etc/printcap</filename> files as - well. See section <link - linkend="printing-advanced-network-rm">Printers Installed on - Remote Hosts</link> for more information on remote - printing.</para> - - <para>There is another specialized way to limit job sizes from remote - printers; see section <link - linkend="printing-advanced-restricting-remote">Restricting Jobs - from Remote Printers</link>.</para> - </sect3> - - <sect3 id="printing-advanced-restricting-remote"> - <title>Restricting Jobs from Remote Printers</title> - - <para>The LPD spooling system provides several ways to restrict print - jobs submitted from remote hosts:</para> - - <variablelist> - <varlistentry> - <term>Host restrictions</term> - - <listitem> - <para>You can control from which remote hosts a local LPD - accepts requests with the files - <filename>/etc/hosts.equiv</filename> and - <filename>/etc/hosts.lpd</filename>. LPD checks to see if an - incoming request is from a host listed in either one of these - files. If not, LPD refuses the request.</para> - - <para>The format of these files is simple: one host name per - line. Note that the file - <filename>/etc/hosts.equiv</filename> is also used by the - &man.ruserok.3; protocol, and affects programs like - &man.rsh.1; and &man.rcp.1;, so be careful.</para> - - <para>For example, here is the - <filename>/etc/hosts.lpd</filename> file on the host - <hostid>rose</hostid>:</para> - - <programlisting> -orchid -violet -madrigal.fishbaum.de</programlisting> - - <para>This means <hostid>rose</hostid> will accept requests from - the hosts <hostid>orchid</hostid>, <hostid>violet</hostid>, - and <hostid role="fqdn">madrigal.fishbaum.de</hostid>. If any - other host tries to access <hostid>rose</hostid>'s - LPD, the job will be refused.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Size restrictions</term> - - <listitem> - <para>You can control how much free space there needs to remain - on the filesystem where a spooling directory resides. Make a - file called <filename>minfree</filename> in the spooling - directory for the local printer. Insert in that file a number - representing how many disk blocks (512 bytes) of free space - there has to be for a remote job to be accepted.</para> - - <para>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 will be able to queue jobs long after the - free disk space has fallen below the amount specified in the - <filename>minfree</filename> file.</para> - - <para>For example, let us add a <filename>minfree</filename> - file for the printer <hostid>bamboo</hostid>. We examine - <filename>/etc/printcap</filename> to find the spooling - directory for this printer; here is <hostid>bamboo</hostid>'s - entry:</para> - - <programlisting> -bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ - :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:mx#5000:\ - :if=/usr/local/libexec/psif:\ - :df=/usr/local/libexec/psdf:</programlisting> - - <para>The spooling directory is the given in the - <literal>sd</literal> 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:</para> - - <screen>&prompt.root; <userinput>echo 6144 > /var/spool/lpd/bam -boo/minfree</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term>User restrictions</term> - - <listitem> - <para>You can control which remote users can print to local - printers by specifying the <literal>rs</literal> capability in - <filename>/etc/printcap</filename>. When - <literal>rs</literal> appears in the entry for a - locally-attached printer, LPD will accept jobs from remote - hosts <emphasis>if</emphasis> the user submitting the job also - has an account of the same login name on the local host. - Otherwise, LPD refuses the job.</para> - - <para>This capability is particularly useful in an environment - where there are (for example) different 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 would - rather allow them to use <emphasis>only</emphasis> your - printers and not your compute resources, you can give them - <quote>token</quote> accounts, with no home directory and a - useless shell like <filename>/usr/bin/false</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2 id="printing-advanced-acct"> - <title>Accounting for Printer Usage</title> - - <para>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 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?</para> - - <para>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 - <emphasis>your</emphasis> requirements in charging for printer - usage.</para> - - <para>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 cannot get away with using the simple output - filter, since it cannot do accounting. See section <link - linkend="printing-advanced-filter-intro">Filters</link>.</para> - - <para>Generally, there are two ways to do accounting:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Periodic accounting</emphasis> is the more common - way, 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 accounting files for the - various printers, tally up the pages printed by users, and charge - for usage. Then you truncate all the logging files, starting with - a clean slate for the next period.</para> - </listitem> - - <listitem> - <para><emphasis>Timely accounting</emphasis> is less common, - probably 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 their account goes in the red, - and might provide a way for users to check and adjust their - <quote>print quotas.</quote> But this method requires some database - code to track users and their quotas.</para> - </listitem> - </itemizedlist> - - <para>The LPD spooling system supports both methods easily: since you - have to provide the filters (well, most of the time), you also have to - provide the accounting code. But there is a bright side: you have - enormous flexibility in your accounting methods. For example, you - choose whether to use periodic or timely accounting. You choose what - information to log: user names, host names, job types, pages printed, - square footage of paper used, how long the job took to print, and so - forth. And you do so by modifying the filters to save this - information.</para> - - <sect3> - <title>Quick and Dirty Printer Accounting</title> - - <para>FreeBSD comes with two programs that can get you set up with - simple periodic accounting right away. They are the text filter - <command>lpf</command>, described in section <link - linkend="printing-advanced-lpf">lpf: a Text Filter</link>, and - &man.pac.8;, a program to gather and total - entries from printer accounting files.</para> - - <para>As mentioned in the section on filters (<link - linkend="printing-advanced-filters">Filters</link>), LPD starts - the text and the conversion filters with the name of the accounting - file to use on the filter command line. The filters can use this - argument to know where to write an accounting file entry. The name - of this file comes from the <literal>af</literal> capability in - <filename>/etc/printcap</filename>, and if not specified as an - absolute path, is relative to the spooling directory.</para> - - <para>LPD starts <command>lpf</command> with page width and length - arguments (from the <literal>pw</literal> and <literal>pl</literal> - capabilities). <command>lpf</command> uses these arguments to - determine how much paper will be used. After sending the file to - the printer, it then writes an accounting entry in the accounting - file. The entries look like this:</para> - - <programlisting> -2.00 rose:andy -3.00 rose:kelly -3.00 orchid:mary -5.00 orchid:mary -2.00 orchid:zhang</programlisting> - - <para>You should use a separate accounting file for each printer, as - <command>lpf</command> has no file locking logic built into it, and - two <command>lpf</command>s might corrupt each other's entries if - they were to write to the same file at the same time. A easy way to - insure a separate accounting file for each printer is to use - <literal>af=acct</literal> in <filename>/etc/printcap</filename>. - Then, each accounting file will be in the spooling directory for a - printer, in a file named <filename>acct</filename>.</para> - - <para>When you are ready to charge users for printouts, run the - &man.pac.8; program. Just change to the spooling directory for - the printer you want to collect on and type <literal>pac</literal>. - You will get a dollar-centric summary like the following:</para> - - <screen> Login pages/feet runs price -orchid:kelly 5.00 1 $ 0.10 -orchid:mary 31.00 3 $ 0.62 -orchid:zhang 9.00 1 $ 0.18 -rose:andy 2.00 1 $ 0.04 -rose:kelly 177.00 104 $ 3.54 -rose:mary 87.00 32 $ 1.74 -rose:root 26.00 12 $ 0.52 - -total 337.00 154 $ 6.74</screen> - - <para>These are the arguments &man.pac.8; expects:</para> - - <variablelist> - <varlistentry> - <term><option>-P<replaceable>printer</replaceable></option></term> - - <listitem> - <para>Which <replaceable>printer</replaceable> to summarize. - This option works only if there is an absolute path in the - <literal>af</literal> capability in - <filename>/etc/printcap</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Sort the output by cost instead of alphabetically by user - name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - - <listitem> - <para>Ignore host name in the accounting files. With this - option, user <username>smith</username> on host - <hostid>alpha</hostid> is the same user - <username>smith</username> on host <hostid>gamma</hostid>. - Without, they are different users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p<replaceable>price</replaceable></option></term> - - <listitem> - <para>Compute charges with <replaceable>price</replaceable> - dollars per page or per foot instead of the price from the - <literal>pc</literal> capability in - <filename>/etc/printcap</filename>, or two cents (the - default). You can specify <replaceable>price</replaceable> as - a floating point number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - - <listitem> - <para>Reverse the sort order.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - - <listitem> - <para>Make an accounting summary file and truncate the - accounting file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>name</replaceable> - <replaceable>…</replaceable></term> - - <listitem> - <para>Print accounting information for the given user - <replaceable>names</replaceable> only.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In the default summary that &man.pac.8; produces, you see the - number of pages printed by each user from various hosts. If, at - your site, host does not matter (because users can use any host), - run <command>pac -m</command>, to produce the following - summary:</para> - - <screen> Login pages/feet runs price -andy 2.00 1 $ 0.04 -kelly 182.00 105 $ 3.64 -mary 118.00 35 $ 2.36 -root 26.00 12 $ 0.52 -zhang 9.00 1 $ 0.18 - -total 337.00 154 $ 6.74</screen> - - - <para>To compute the dollar amount due, - &man.pac.8; uses the <literal>pc</literal> capability in the - <filename>/etc/printcap</filename> file (default of 200, or 2 cents - per page). Specify, in hundredths of cents, the price per page or - per foot you want to charge for printouts in this capability. You - can override this value when you run &man.pac.8; with the - <option>-p</option> option. The units for the <option>-p</option> - option are in dollars, though, not hundredths of cents. For - example, - - <screen>&prompt.root; <userinput>pac -p1.50</userinput></screen> - - makes each page cost one dollar and fifty cents. You can really - rake in the profits by using this option.</para> - - <para>Finally, running <command>pac -s</command> will save the summary - information in a summary accounting file, which is named the same as - the printer's accounting file, but with <literal>_sum</literal> - appended to the name. It then truncates the accounting file. When - you run &man.pac.8; again, it rereads the - summary file to get starting totals, then adds information from the - regular accounting file.</para> - </sect3> - - <sect3> - <title>How Can You Count Pages Printed?</title> - - <para>In order to perform even remotely accurate accounting, you need - to be able to determine how much paper a job uses. This is the - essential problem of printer accounting.</para> - - <para>For plain text jobs, the problem is 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. 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.</para> - - <para>The text filter <command>lpf</command> (introduced in <link - linkend="printing-advanced-lpf">lpf: a Text Filter</link>) takes - into account these things when it does accounting. If you are - writing a text filter which needs to do accounting, you might want - to examine <command>lpf</command>'s source code.</para> - - <para>How do you handle other file formats, though?</para> - - <para>Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you - can have your filter parse the diagnostic output of - <command>dvilj</command> or <command>dvips</command> and look to see - how many pages were converted. You might be able to do similar - things with other file formats and conversion programs.</para> - - <para>But these methods suffer from the fact that the printer may not - actually print all those pages. For example, it could jam, run out - of toner, or explode—and the user would still get - charged.</para> - - <para>So, what can you do?</para> - - <para>There is only one <emphasis>sure</emphasis> way to do - <emphasis>accurate</emphasis> accounting. Get a printer that can - tell you how much paper it uses, and attach it via a serial line or - a network connection. Nearly all PostScript printers support this - notion. Other makes and models do as well (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 - <emphasis>only</emphasis>. There is no line counting nor - error-prone file examination required.</para> - - <para>Of course, you can always be generous and make all printouts - free.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="printing-using"> - <title>Using Printers</title> - - <para>This section tells you how to use printers you have setup with - FreeBSD. Here is an overview of the user-level commands:</para> - - <variablelist> - <varlistentry> - <term>&man.lpr.1;</term> - - <listitem> - <para>Print jobs</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&man.lpq.1;</term> - - <listitem> - <para>Check printer queues</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&man.lprm.1;</term> - - <listitem> - <para>Remove jobs from a printer's queue</para> - </listitem> - </varlistentry> - </variablelist> - - <para>There is also an administrative command, &man.lpc.8;, described in - the section <link linkend="printing-lpc">Administrating the LPD - Spooler</link>, used to control printers and their queues.</para> - - <para>All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; - accept an option <option>-P - <replaceable>printer-name</replaceable></option> to specify on which - printer/queue to operate, as listed in the - <filename>/etc/printcap</filename> file. This enables you to submit, - remove, and check on jobs for various printers. If you do not use the - <option>-P</option> option, then these commands use the printer - specified in the <envar>PRINTER</envar> environment variable. Finally, - if you do not have a <envar>PRINTER</envar> environment variable, these - commands default to the printer named <literal>lp</literal>.</para> - - <para>Hereafter, the terminology <emphasis>default printer</emphasis> - means the printer named in the <envar>PRINTER</envar> environment - variable, or the printer named <literal>lp</literal> when there is no - <envar>PRINTER</envar> environment variable.</para> - - <sect2 id="printing-lpr"> - <title>Printing Jobs</title> - - <para>To print files, type:</para> - - <screen>&prompt.user; <userinput>lpr <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen> - - <para>This prints each of the listed files to the default printer. If - you list no files, &man.lpr.1; reads data to - print from standard input. For example, this command prints some - important system files:</para> - - <screen>&prompt.user; <userinput>lpr /etc/host.conf /etc/hosts.equiv</userinput></screen> - - <para>To select a specific printer, type:</para> - - <screen>&prompt.user; <userinput>lpr -P <replaceable>printer-name</replaceable> <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen> - - <para>This example prints a long listing of the current directory to the - printer named <literal>rattan</literal>:</para> - - <screen>&prompt.user; <userinput>ls -l | lpr -P rattan</userinput></screen> - - <para>Because no files were listed for the - &man.lpr.1; command, <command>lpr</command> read the data to print - from standard input, which was the output of the <command>ls - -l</command> command.</para> - - <para>The &man.lpr.1; command can also accept a wide variety of options - to control formatting, apply file conversions, generate multiple - copies, and so forth. For more information, see the section <link - linkend="printing-lpr-options">Printing Options</link>.</para> - </sect2> - - <sect2 id="printing-lpq"> - <title>Checking Jobs</title> - - <para>When you print with &man.lpr.1;, the data you wish to print is put - together in a package called a <quote>print job</quote>, which is sent - to the LPD spooling system. Each printer has a queue of jobs, and - your job waits in that queue along with other jobs from yourself and - from other users. The printer prints those jobs in a first-come, - first-served order.</para> - - <para>To display the queue for the default printer, type &man.lpq.1;. - For a specific printer, use the <option>-P</option> option. For - example, the command - - <screen>&prompt.user; <userinput>lpq -P bamboo</userinput></screen> - - shows the queue for the printer named <hostid>bamboo</hostid>. Here - is an example of the output of the <command>lpq</command> - command:</para> - - <screen>bamboo is ready and printing -Rank Owner Job Files Total Size -active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes -2nd kelly 10 (standard input) 1635 bytes -3rd mary 11 ... 78519 bytes</screen> - - <para>This shows three jobs in the queue for <literal>bamboo</literal>. - The first job, submitted by user kelly, got assigned <quote>job - number</quote> 9. Every job for a printer gets a unique job number. - Most of the time you can ignore the job number, but you will need it - if you want to cancel the job; see section <link - linkend="printing-lprm">Removing Jobs</link> for details.</para> - - <para>Job number nine consists of two files; multiple files given on the - &man.lpr.1; command line are treated as part of a single job. It - is the currently active job (note the word <literal>active</literal> - under the <quote>Rank</quote> column), which means the printer should - be currently printing that job. The second job consists of data - passed as the standard input to the &man.lpr.1; command. The third - job came from user <username>mary</username>; it is a much larger - job. The pathname of the files she's trying to print is too long to - fit, so the &man.lpq.1; command just shows three dots.</para> - - <para>The very first line of the output from &man.lpq.1; is also useful: - it tells what the printer is currently doing (or at least what LPD - thinks the printer is doing).</para> - - <para>The &man.lpq.1; command also support a <option>-l</option> option - to generate a detailed long listing. Here is an example of - <command>lpq -l</command>:</para> - - <screen>waiting for bamboo to become ready (offline ?) -kelly: 1st [job 009rose] - /etc/host.conf 73 bytes - /etc/hosts.equiv 15 bytes - -kelly: 2nd [job 010rose] - (standard input) 1635 bytes - -mary: 3rd [job 011rose] - /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen> - </sect2> - - <sect2 id="printing-lprm"> - <title>Removing Jobs</title> - - <para>If you change your mind about printing a job, you can remove the - job from the queue with the &man.lprm.1; command. Often, you can - even use &man.lprm.1; to remove an active job, but some or all of the - job might still get printed.</para> - - <para>To remove a job from the default printer, first use - &man.lpq.1; to find the job number. Then type:</para> - - <screen>&prompt.user; <userinput>lprm <replaceable>job-number</replaceable></userinput></screen> - - <para>To remove the job from a specific printer, add the - <option>-P</option> option. The following command removes job number - 10 from the queue for the printer <hostid>bamboo</hostid>:</para> - - <screen>&prompt.user; <userinput>lprm -P bamboo 10</userinput></screen> - - <para>The &man.lprm.1; command has a few shortcuts:</para> - - <variablelist> - <varlistentry> - <term>lprm -</term> - - <listitem> - <para>Removes all jobs (for the default printer) belonging to - you.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>lprm <replaceable>user</replaceable></term> - - <listitem> - <para>Removes all jobs (for the default printer) belonging to - <replaceable>user</replaceable>. The superuser can remove other - users' jobs; you can remove only your own jobs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>lprm</term> - - <listitem> - <para>With no job number, user name, or <option>-</option> - appearing on the command line, - &man.lprm.1; removes the currently active job on the - default printer, if it belongs to you. The superuser can remove - any active job.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Just use the <option>-P</option> option with the above shortcuts - to operate on a specific printer instead of the default. For example, - the following command removes all jobs for the current user in the - queue for the printer named <literal>rattan</literal>:</para> - - <screen>&prompt.user; <userinput>lprm -P rattan -</userinput></screen> - - <note> - <para>If you are working in a networked environment, &man.lprm.1; 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 - demonstrates this:</para> - - <screen>&prompt.user; <userinput>lpr -P rattan myfile</userinput> -&prompt.user; <userinput>rlogin orchid</userinput> -&prompt.user; <userinput>lpq -P rattan</userinput> -Rank Owner Job Files Total Size -active seeyan 12 ... 49123 bytes -2nd kelly 13 myfile 12 bytes -&prompt.user; <userinput>lprm -P rattan 13</userinput> -rose: Permission denied -&prompt.user; <userinput>logout</userinput> -&prompt.user; <userinput>lprm -P rattan 13</userinput> -dfA013rose dequeued -cfA013rose dequeued - </screen> - </note> - </sect2> - - <sect2 id="printing-lpr-options"> - <title>Beyond Plain Text: Printing Options</title> - - <para>The &man.lpr.1; command supports a number of options that control - formatting text, converting graphic and other file formats, producing - multiple copies, handling of the job, and more. This section - describes the options.</para> - - <sect3 id="printing-lpr-options-format"> - <title>Formatting and Conversion Options</title> - - <para>The following &man.lpr.1; options control formatting of the - files in the job. Use these options if the job does not contain - plain text or if you want plain text formatted through the - &man.pr.1; utility.</para> - - <para>For example, the following command prints a DVI file (from the - TeX typesetting system) named <filename>fish-report.dvi</filename> - to the printer named <literal>bamboo</literal>:</para> - - <screen>&prompt.user; <userinput>lpr -P bamboo -d fish-report.dvi</userinput></screen> - - <para>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.</para> - - <note> - <para>All of these options except <option>-p</option> and - <option>-T</option> require conversion filters installed for the - destination printer. For example, the <option>-d</option> option - requires the DVI conversion filter. Section <link - linkend="printing-advanced-convfilters">Conversion - Filters</link> gives details.</para> - </note> - - <variablelist> - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Print cifplot files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - - <listitem> - <para>Print DVI files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - - <listitem> - <para>Print FORTRAN text files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Print plot data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i <replaceable>number</replaceable></option></term> - - <listitem> - <para>Indent the output by <replaceable>number</replaceable> - columns; if you omit <replaceable>number</replaceable>, indent - by 8 columns. This option works only with certain conversion - filters.</para> - - <note> - <para>Do not put any space between the <option>-i</option> and - the number.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - - <listitem> - <para>Print literal text data, including control - characters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - - <listitem> - <para>Print ditroff (device independent troff) data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-p</term> - - <listitem> - <para>Format plain text with &man.pr.1; before printing. See - &man.pr.1; for more information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-T <replaceable>title</replaceable></option></term> - - <listitem> - <para>Use <replaceable>title</replaceable> on the - &man.pr.1; header instead of the file name. This option has - effect only when used with the <option>-p</option> - option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option></term> - - <listitem> - <para>Print troff data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v</option></term> - - <listitem> - <para>Print raster data.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Here is an example: this command prints a nicely formatted - version of the &man.ls.1; manual page on the default printer:</para> - - <screen>&prompt.user; <userinput>zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t</userinput></screen> - - <para>The &man.zcat.1; command uncompresses the source of the - &man.ls.1; manual page and passes it to the &man.troff.1; - command, which formats that source and makes GNU troff - output and passes it to &man.lpr.1;, which submits the job - to the LPD spooler. Because we used the <option>-t</option> - option to &man.lpr.1;, the spooler will convert the GNU - troff output into a format the default printer can - understand when it prints the job.</para> - </sect3> - - <sect3 id="printing-lpr-options-job-handling"> - <title>Job Handling Options</title> - - <para>The following options to &man.lpr.1; tell LPD to handle the job - specially:</para> - - <variablelist> - <varlistentry> - <term>-# <replaceable>copies</replaceable></term> - - <listitem> - <para>Produce a number of <replaceable>copies</replaceable> of - each file in the job instead of just one copy. An - administrator may disable this option to reduce printer - wear-and-tear and encourage photocopier usage. See section - <link - linkend="printing-advanced-restricting-copies">Restricting - Multiple Copies</link>.</para> - - <para>This example prints three copies of - <filename>parser.c</filename> followed by three copies of - <filename>parser.h</filename> to the default printer:</para> - - <screen>&prompt.user; <userinput>lpr -#3 parser.c parser.h</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term>-m</term> - - <listitem> - <para>Send mail after completing the print job. With this - option, the LPD system will send mail to your account when it - finishes handling your job. In its message, it will tell you - if the job completed successfully or if there was an error, - and (often) what the error was.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-s</term> - - <listitem> - <para>Do not copy the files to the spooling directory, but make - symbolic links to them instead.</para> - - <para>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 - will not have to copy each and every byte of your job to the - spooling directory.</para> - - <para>There is a drawback, though: since LPD will refer to the - original files directly, you cannot modify or remove them - until they have been printed.</para> - - <note> - <para>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 <option>-s</option> option will save - space only on the local spooling directory, not the remote. - It is still useful, though.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>-r</term> - - <listitem> - <para>Remove the files in the job after copying them to the - spooling directory, or after printing them with the - <option>-s</option> option. Be careful with this - option!</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3 id="printing-lpr-options-misc"> - <title>Header Page Options</title> - - <para>These options to &man.lpr.1; adjust the text that normally - appears on a job's header page. If header pages are suppressed for - the destination printer, these options have no effect. See section - <link linkend="printing-advanced-header-pages">Header Pages</link> - for information about setting up header pages.</para> - - <variablelist> - <varlistentry> - <term>-C <replaceable>text</replaceable></term> - - <listitem> - <para>Replace the hostname on the header page with - <replaceable>text</replaceable>. The hostname is normally the - name of the host from which the job was submitted.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-J <replaceable>text</replaceable></term> - - <listitem> - <para>Replace the job name on the header page with - <replaceable>text</replaceable>. The job name is normally the - name of the first file of the job, or - <filename>stdin</filename> if you are printing standard - input.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-h</term> - - <listitem> - <para>Do not print any header page.</para> - - <note> - <para>At some sites, this option may have no effect due to the - way header pages are generated. See <link - linkend="printing-advanced-header-pages">Header - Pages</link> for details.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - </sect3> - </sect2> - - <sect2 id="printing-lpc"> - <title>Administrating Printers</title> - - <para>As an administrator for your printers, you have had to install, - set up, and test them. Using the &man.lpc.8; command, you - can interact with your printers in yet more ways. With &man.lpc.8;, - you can</para> - - <itemizedlist> - <listitem> - <para>Start and stop the printers</para> - </listitem> - - <listitem> - <para>Enable and disable their queues</para> - </listitem> - - <listitem> - <para>Rearrange the order of the jobs in each queue.</para> - </listitem> - </itemizedlist> - - <para>First, a note about terminology: if a printer is - <emphasis>stopped</emphasis>, it will not print anything in its queue. - Users can still submit jobs, which will wait in the queue until the - printer is <emphasis>started</emphasis> or the queue is - cleared.</para> - - <para>If a queue is <emphasis>disabled</emphasis>, no user (except root) - can submit jobs for the printer. An <emphasis>enabled</emphasis> - queue allows jobs to be submitted. A printer can be - <emphasis>started</emphasis> for a disabled queue, in which case it - will continue to print jobs in the queue until the queue is - empty.</para> - - <para>In general, you have to have root privileges to use the - &man.lpc.8; command. Ordinary users can use the &man.lpc.8; command - to get printer status and to restart a hung printer only.</para> - - <para>Here is a summary of the &man.lpc.8; commands. Most of the - commands takes a <replaceable>printer-name</replaceable> argument to - tell on which printer to operate. You can use <literal>all</literal> - for the <replaceable>printer-name</replaceable> to mean all printers - listed in <filename>/etc/printcap</filename>.</para> - - <variablelist> - <varlistentry> - <term><command>abort - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Cancel the current job and stop the printer. Users can - still submit jobs if the queue's enabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>clean - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Remove old files from the printer's spooling directory. - 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 do not belong in the spooling directory and - removes them.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>disable - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Disable queuing of new jobs. If the printer's started, it - will continue to print any jobs remaining in the queue. The - superuser (root) can always submit jobs, even to a disabled - queue.</para> - - <para>This command is useful while you are testing a new printer - or filter installation: disable the queue and 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 - <command>enable</command> command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>down <replaceable>printer-name</replaceable> - <replaceable>message</replaceable></command></term> - - <listitem> - <para>Take a printer down. Equivalent to - <command>disable</command> followed by <command>stop</command>. - The <replaceable>message</replaceable> appears as the printer's - status whenever a user checks the printer's queue with - &man.lpq.1; or status with <command>lpc - status</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>enable - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Enable the queue for a printer. Users can submit jobs but - the printer will not print anything until it is started.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>help - <replaceable>command-name</replaceable></command></term> - - <listitem> - <para>Print help on the command - <replaceable>command-name</replaceable>. With no - <replaceable>command-name</replaceable>, print a summary of the - commands available.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>restart - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Start the printer. Ordinary users can use this command if - some extraordinary circumstance hangs LPD, but they cannot start - a printer stopped with either the <command>stop</command> or - <command>down</command> commands. The - <command>restart</command> command is equivalent to - <command>abort</command> followed by - <command>start</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>start - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Start the printer. The printer will print jobs in its - queue.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>stop - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Stop the printer. The printer will finish the current 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>topq <replaceable>printer-name</replaceable> - <replaceable>job-or-username</replaceable></command></term> - - <listitem> - <para>Rearrange the queue for - <replaceable>printer-name</replaceable> by placing the jobs with - the listed <replaceable>job</replaceable> numbers or the jobs - belonging to <replaceable>username</replaceable> at the top of - the queue. For this command, you cannot use - <literal>all</literal> as the - <replaceable>printer-name</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>up - <replaceable>printer-name</replaceable></command></term> - - <listitem> - <para>Bring a printer up; the opposite of the - <command>down</command> command. Equivalent to - <command>start</command> followed by - <command>enable</command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>&man.lpc.8; accepts the above commands on the command line. If - you do not enter any commands, &man.lpc.8; enters an interactive mode, - where you can enter commands until you type <command>exit</command>, - <command>quit</command>, or end-of-file.</para> - </sect2> - </sect1> - - <sect1 id="printing-lpd-alternatives"> - <title>Alternatives to the Standard Spooler</title> - - <para>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: - <quote>What other spooling systems are out there (and work with - FreeBSD)?</quote></para> - - <variablelist> - <varlistentry> - <term>LPRng</term> - - <listitem> - <para>LPRng, which purportedly means <quote>LPR: the Next - Generation</quote> is a complete rewrite of PLP. Patrick Powell - and Justin Mason (the principal maintainer of PLP) collaborated to - make LPRng. The main site for LPRng is <ulink - url="http://www.astart.com/lprng/LPRng.html">http://www.astart.com/lprng/LPRng.html</ulink>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="printing-troubleshooting"> - <title>Troubleshooting</title> - - <para>After performing the simple test with &man.lptest.1;, you might - have gotten one of the following results instead of the correct - printout:</para> - - <variablelist> - <varlistentry> - <term>It worked, after awhile; or, it did not eject a full - sheet.</term> - - <listitem> - <para>The printer printed the above, but it sat for awhile and - did nothing. In fact, you might have needed to press a - PRINT REMAINING or FORM FEED button on the printer to get any - results to appear.</para> - - <para>If this is the case, the printer was probably waiting to - see if there was any more data for your job before it printed - anything. To fix this problem, you can have the text filter - send a FORM 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 is also useful to make sure each print job ends on a full - sheet, so the next job does not start somewhere on the middle - of the last page of the previous job.</para> - - <para>The following replacement for the shell script - <filename>/usr/local/libexec/if-simple</filename> prints a - form feed after it sends the job to the printer:</para> - - <programlisting> -#!/bin/sh -# -# if-simple - Simple text input filter for lpd -# Installed in /usr/local/libexec/if-simple -# -# Simply copies stdin to stdout. Ignores all filter arguments. -# Writes a form feed character (\f) after printing job. - -/bin/cat && printf "\f" && exit 0 -exit 2</programlisting> - </listitem> - </varlistentry> - - <varlistentry> - <term>It produced the <quote>staircase effect.</quote></term> - - <listitem> - <para>You got the following on paper:</para> - - <programlisting> -!"#$%&'()*+,-./01234 - "#$%&'()*+,-./012345 - #$%&'()*+,-./0123456</programlisting> - - <para>You have become another victim of the <emphasis>staircase - effect</emphasis>, caused by conflicting interpretations of - what characters should indicate a new line. UNIX-style - operating systems use a single character: ASCII code 10, the - line feed (LF). MS-DOS, OS/2, and others uses a pair of - characters, ASCII code 10 <emphasis>and</emphasis> ASCII code - 13 (the carriage return or CR). Many printers use the MS-DOS - convention for representing new-lines.</para> - - <para>When you print with FreeBSD, your text used just the 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 is what the carriage return is for: to move - the location of the next character to print to the left edge - of the paper.</para> - - <para>Here is what FreeBSD wants your printer to do:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry>Printer received CR</entry> - <entry>Printer prints CR</entry> - </row> - - <row> - <entry>Printer received LF</entry> - <entry>Printer prints CR + LF</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Here are some ways to achieve this:</para> - - <itemizedlist> - <listitem> - <para>Use the printer's configuration switches or control - panel to alter its interpretation of these characters. - Check your printer's manual to find out how to do - this.</para> - - <note> - <para>If you boot your system into other operating systems - besides FreeBSD, you may have to - <emphasis>reconfigure</emphasis> the printer to use a an - interpretation for CR and LF characters that those other - operating systems use. You might prefer one of the other - solutions, below.</para> - </note> - </listitem> - - <listitem> - <para>Have FreeBSD's serial line driver automatically - convert LF to CR+LF. Of course, this works with printers - on serial ports <emphasis>only</emphasis>. To enable this - feature, set the CRMOD bit in <literal>fs</literal> - capability in the <filename>/etc/printcap</filename> file - for the printer.</para> - </listitem> - - <listitem> - <para>Send an <emphasis>escape code</emphasis> to the - printer to have it temporarily treat LF characters - differently. Consult your printer's manual for escape - codes that your printer might support. When you find the - proper escape code, modify the text filter to send the - code first, then send the print job.</para> - - <para>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 job; then it sends a form feed to - eject the last page of the job. It should work with - nearly all Hewlett Packard printers.</para> - - <programlisting> -#!/bin/sh -# -# hpif - Simple text input filter for lpd for HP-PCL based printers -# Installed in /usr/local/libexec/hpif -# -# Simply copies stdin to stdout. Ignores all filter arguments. -# Tells printer to treat LF as CR+LF. Ejects the page when done. - -printf "\033&k2G" && cat && printf "\033&l0H" && exit 0 -exit 2</programlisting> - - <para>Here is an example <filename>/etc/printcap</filename> - from a host called orchid. It has a single printer - attached to its first parallel port, a Hewlett Packard - LaserJet 3Si named <hostid>teak</hostid>. It is using the - above script as its text filter:</para> - - <programlisting> -# -# /etc/printcap for host orchid -# -teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ - :if=/usr/local/libexec/hpif:</programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>It overprinted each line.</term> - - <listitem> - <para>The printer never advanced a line. All of the lines of - text were printed on top of each other on one line.</para> - - <para>This problem is the <quote>opposite</quote> of the - staircase effect, described above, and is much rarer. - Somewhere, the LF characters that FreeBSD uses to end a line - are being treated as CR characters to return the print - location to the left edge of the paper, but not also down a - line.</para> - - <para>Use the printer's configuration switches or control panel - to enforce the following interpretation of LF and CR - characters:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Printer receives</entry> - <entry>Printer prints</entry> - </row> - </thead> - - <tbody> - <row> - <entry>CR</entry> - <entry>CR</entry> - </row> - - <row> - <entry>LF</entry> - <entry>CR + LF</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </varlistentry> - - <varlistentry> - <term>The printer lost characters.</term> - - <listitem> - <para>While printing, the printer did not print a few characters - in each line. The problem might have gotten worse as the - printer ran, losing more and more characters.</para> - - <para>The problem is that the printer cannot keep up with the - speed at which the computer sends data over a serial line - (this problem should not occur with printers on parallel - ports). There are two ways to overcome the problem:</para> - - <itemizedlist> - <listitem> - <para>If the printer supports XON/XOFF flow control, have - FreeBSD use it by specifying the TANDEM bit in the - <literal>fs</literal> capability.</para> - </listitem> - - <listitem> - <para>If the printer supports carrier flow control, specify - the MDMBUF bit in the <literal>fs</literal> capability. - Make sure the cable connecting the printer to the computer - is correctly wired for carrier flow control.</para> - </listitem> - - <listitem> - <para>If the printer does not support any flow control, use - some combination of the NLDELAY, TBDELAY, CRDELAY, VTDELAY, - and BSDELAY bits in the <literal>fs</literal> capability - to add appropriate delays to the stream of data sent to - the printer.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>It printed garbage.</term> - - <listitem> - <para>The printer printed what appeared to be random garbage, - but not the desired text.</para> - - <para>This is usually another symptom of incorrect - communications parameters with a serial printer. Double-check - the bps rate in the <literal>br</literal> capability, and the - parity bits in the <literal>fs</literal> and - <literal>fc</literal> capabilities; make sure the printer is - using the same settings as specified in the - <filename>/etc/printcap</filename> file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Nothing happened.</term> - - <listitem> - <para>If nothing happened, the problem is probably within - FreeBSD and not the hardware. Add the log file - (<literal>lf</literal>) capability to the entry for the - printer you are debugging in the - <filename>/etc/printcap</filename> file. For example, here is - the entry for <literal>rattan</literal>, with the - <literal>lf</literal> capability:</para> - - <programlisting> -rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=/var/spool/lpd/rattan:\ - :lp=/dev/lpt0:\ - :if=/usr/local/libexec/if-simple:\ - :lf=/var/log/rattan.log</programlisting> - - <para>Then, try printing again. Check the log file (in our - example, <filename>/var/log/rattan.log</filename>) to see any - error messages that might appear. Based on the messages you - see, try to correct the problem.</para> - - <para>If you do not specify a <literal>lf</literal> capability, - LPD uses <filename>/dev/console</filename> as a - default.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - - diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml deleted file mode 100644 index f04f4c3ef6..0000000000 --- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml +++ /dev/null @@ -1,2690 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/security/chapter.sgml,v 1.37 2000/09/24 07:01:52 kris Exp $ ---> - -<chapter id="security"> - <title>Security</title> - - <para><emphasis>Much of this chapter has been taken from the - &man.security.7; man page, originally written by - &a.dillon;.</emphasis></para> - - <sect1> - <title>Synopsis</title> - - <para>The following chapter will provide a basic introduction to - system security concepts, some general good rules of thumb, and some - advanced topics such as S/Key, OpenSSL, Kerberos, and others.</para> - </sect1> - - <sect1 id="security-intro"> - <title>Introduction</title> - - <para>Security is a function that begins and ends with the system - administrator. While all BSD UNIX multi-user systems have some - inherent security, the job of building and maintaining additional - security mechanisms to keep those users <quote>honest</quote> is - probably one of the single largest undertakings of the sysadmin. - Machines are only as secure as you make them, and security concerns - are ever competing with the human necessity for convenience. UNIX - systems, in general, are capable of running a huge number of - simultaneous processes and many of these processes operate as - servers – meaning that external entities can connect and talk - to them. As yesterday's mini-computers and mainframes become - today's desktops, and as computers become networked and - internetworked, security becomes an ever bigger issue.</para> - - <para>Security is best implemented through a layered - <quote>onion</quote> approach. In a nutshell, what you want to do is - to create as many layers of security as are convenient and then - carefully monitor the system for intrusions. You do not want to - overbuild your security or you will interfere with the detection - side, and detection is one of the single most important aspects of - any security mechanism. For example, it makes little sense to set - the schg flags (see &man.chflags.1;) on every system binary because - while this may temporarily protect the binaries, it prevents an - attacker who has broken in from making an easily detectable change - that may result in your security mechanisms not detecting the attacker - at all.</para> - - <para>System security also pertains to dealing with various forms of - attack, including attacks that attempt to crash or otherwise make a - system unusable but do not attempt to break root. Security concerns - can be split up into several categories:</para> - - <orderedlist> - <listitem> - <para>Denial of service attacks.</para> - </listitem> - - <listitem> - <para>User account compromises.</para> - </listitem> - - <listitem> - <para>Root compromise through accessible servers.</para> - </listitem> - - <listitem> - <para>Root compromise via user accounts.</para> - </listitem> - - <listitem> - <para>Backdoor creation.</para> - </listitem> - </orderedlist> - - <para>A denial of service attack is an action that deprives the - machine of needed resources. Typically, D.O.S. attacks are - brute-force mechanisms that attempt to crash or otherwise make a - machine unusable by overwhelming its servers or network stack. Some - D.O.S. attacks try to take advantages of bugs in the networking - stack to crash a machine with a single packet. The latter can only - be fixed by applying a bug fix to the kernel. Attacks on servers - can often be fixed by properly specifying options to limit the load - the servers incur on the system under adverse conditions. - Brute-force network attacks are harder to deal with. A - spoofed-packet attack, for example, is nearly impossible to stop - short of cutting your system off from the internet. It may not be - able to take your machine down, but it can fill up internet - pipe.</para> - - <para>A user account compromise is even more common then a D.O.S. - attack. Many sysadmins still run standard telnetd, rlogind, rshd, - and ftpd servers on their machines. These servers, by default, do - not operate over encrypted connections. The result is that if you - have any moderate-sized user base, one or more of your users logging - into your system from a remote location (which is the most common - and convenient way to login to a system) will have his or her - password sniffed. The attentive system admin will analyze his - remote access logs looking for suspicious source addresses even for - successful logins.</para> - - <para>One must always assume that once an attacker has access to a - user account, the attacker can break root. However, the reality is - that in a well secured and maintained system, access to a user - account does not necessarily give the attacker access to root. The - distinction is important because without access to root the attacker - cannot generally hide his tracks and may, at best, be able to do - nothing more then mess with the user's files or crash the machine. - User account compromises are very common because users tend not to - take the precautions that sysadmins take.</para> - - <para>System administrators must keep in mind that there are - potentially many ways to break root on a machine. The attacker - may know the root password, the attacker may find a bug in a - root-run server and be able to break root over a network - connection to that server, or the attacker may know of a bug in - an suid-root program that allows the attacker to break root once - he has broken into a user's account. If an attacker has found a - a way to break root on a machine, the attacker may not have a need - to install a backdoor. Many of the root holes - found and closed to date involve a considerable amount of work - by the attacker to cleanup after himself, so most attackers install - backdoors. Backdoors provide the attacker with a way to easily - regain root access to the system, but it also gives the smart - system administrator a convenient way to detect the intrusion. - Making it impossible for an attacker to install a backdoor may - actually be detrimental to your security because it will not - close off the hole the attacker found to break in the first - place.</para> - - <para>Security remedies should always be implemented with a - multi-layered <quote>onion peel</quote> approach and can be - categorized as follows:</para> - - <orderedlist> - <listitem> - <para>Securing root and staff accounts.</para> - </listitem> - - <listitem> - <para>Securing root – root-run servers and suid/sgid - binaries.</para> - </listitem> - - <listitem> - <para>Securing user accounts.</para> - </listitem> - - <listitem> - <para>Securing the password file.</para> - </listitem> - - <listitem> - <para>Securing the kernel core, raw devices, and - filesystems.</para> - </listitem> - - <listitem> - <para>Quick detection of inappropriate changes made to the - system.</para> - </listitem> - - <listitem> - <para>Paranoia.</para> - </listitem> - </orderedlist> - - <para>The next section of this chapter will cover the above bullet - items in greater depth.</para> - </sect1> - - <sect1 id="securing-freebsd"> - <title>Securing FreeBSD</title> - - <para>The sections that follow will cover the methods of securing your - FreeBSD system that were mentioned in the <link - linkend="security-intro">last section</link> of this chapter.</para> - - <sect2 id="securing-root-and-staff"> - <title>Securing the root account and staff accounts</title> - - <para>First off, do not bother securing staff accounts if you have - not secured the root account. Most systems have a password - assigned to the root account. The first thing you do is assume - that the password is <emphasis>always</emphasis> compromised. - This does not mean that you should remove the password. The - password is almost always necessary for console access to the - machine. What it does mean is that you should not make it - possible to use the password outside of the console or possibly - even with the &man.su.1; command. For example, make sure that - your pty's are specified as being unsecure in the - <filename>/etc/ttys</filename> file so that direct root logins - via <command>telnet</command> or <command>rlogin</command> are - disallowed. If using other login services such as - <application>sshd</application>, make sure that direct root logins - are disabled there as well. Consider every access method – - services such as FTP often fall through the cracks. Direct root - logins should only be allowed via the system console.</para> - - <para>Of course, as a sysadmin you have to be able to get to root, - so we open up a few holes. But we make sure these holes require - additional password verification to operate. One way to make root - accessible is to add appropriate staff accounts to the - <literal>wheel</literal> group (in - <filename>/etc/group</filename>). The staff members placed in the - <literal>wheel</literal> group are allowed to - <literal>su</literal> to root. You should never give staff - members native wheel access by putting them in the - <literal>wheel</literal> group in their password entry. Staff - accounts should be placed in a <literal>staff</literal> group, and - then added to the <literal>wheel</literal> group via the - <filename>/etc/group</filename> file. Only those staff members - who actually need to have root access should be placed in the - <literal>wheel</literal> group. It is also possible, when using - an authentication method such as kerberos, to use kerberos' - <filename>.k5login</filename> file in the root account to allow a - &man.ksu.1; to root without having to place anyone at all in the - <literal>wheel</literal> group. This may be the better solution - since the <literal>wheel</literal> mechanism still allows an - intruder to break root if the intruder has gotten hold of your - password file and can break into a staff account. While having - the <literal>wheel</literal> mechanism is better then having - nothing at all, it is not necessarily the safest option.</para> - - <para>An indirect way to secure the root account is to secure your - staff accounts by using an alternative login access method and - <literal>*</literal>'ing out the crypted password for the staff - accounts. This way an intruder may be able to steal the password - file but will not be able to break into any staff accounts (or, - indirectly, root, even if root has a crypted password associated - with it). Staff members get into their staff accounts through a - secure login mechanism such as &man.kerberos.1; or &man.ssh.1; - using a private/public key pair. When you use something like - kerberos, you generally must secure the machines which run the - kerberos servers and your desktop workstation. When you use a - public/private key pair with <application>ssh</application>, you - must generally secure the machine you are logging in - <emphasis>from</emphasis> (typically your workstation), but you - can also add an additional layer of protection to the key pair by - password protecting the keypair when you create it with - &man.ssh-keygen.1;. Being able to <literal>*</literal> out the - passwords for staff accounts also guarantees that staff members can - only login through secure access methods that you have setup. You - can thus force all staff members to use secure, encrypted - connections for all of their sessions which closes an important - hole used by many intruders: That of sniffing the network from an - unrelated, less secure machine.</para> - - <para>The more indirect security mechanisms also assume that you are - logging in from a more restrictive server to a less restrictive - server. For example, if your main box is running all sorts of - servers, your workstation should not be running any. In order for - your workstation to be reasonably secure you should run as few - servers as possible, up to and including no servers at all, and - you should run a password-protected screen blanker. Of course, - given physical access to a workstation an attacker can break any - sort of security you put on it. This is definitely a problem that - you should consider but you should also consider the fact that the - vast majority of break-ins occur remotely, over a network, from - people who do not have physical access to your workstation or - servers.</para> - - <para>Using something like kerberos also gives you the ability to - disable or change the password for a staff account in one place - and have it immediately effect all the machine the staff member - may have an account on. If a staff member's account gets - compromised, the ability to instantly change his password on all - machines should not be underrated. With discrete passwords, - changing a password on N machines can be a mess. You can also - impose re-passwording restrictions with kerberos: not only can a - kerberos ticket be made to timeout after a while, but the kerberos - system can require that the user choose a new password after a - certain period of time (say, once a month).</para> - </sect2> - - <sect2> - <title>Securing Root-run Servers and SUID/SGID Binaries</title> - - <para>The prudent sysadmin only runs the servers he needs to, no - more, no less. Be aware that third party servers are often the - most bug-prone. For example, running an old version of imapd or - popper is like giving a universal root ticket out to the entire - world. Never run a server that you have not checked out - carefully. Many servers do not need to be run as root. For - example, the <application>ntalk</application>, - <application>comsat</application>, and - <application>finger</application> daemons can be run in special - user <literal>sandboxes</literal>. A sandbox isn't perfect unless - you go to a large amount of trouble, but the onion approach to - security still stands: If someone is able to break in through - a server running in a sandbox, they still have to break out of the - sandbox. The more layers the attacker must break through, the - lower the likelihood of his success. Root holes have historically - been found in virtually every server ever run as root, including - basic system servers. If you are running a machine through which - people only login via <application>sshd</application> and never - login via <application>telnetd</application> or - <application>rshd</application> or - <application>rlogind</application>, then turn off those - services!</para> - - <para>FreeBSD now defaults to running - <application>ntalkd</application>, - <application>comsat</application>, and - <application>finger</application> in a sandbox. Another program - which may be a candidate for running in a sandbox is &man.named.8;. - The default <filename>rc.conf</filename> includes the arguments - necessary to run <application>named</application> in a sandbox in a - commented-out form. Depending on whether you are installing a new - system or upgrading an existing system, the special user accounts - used by these sandboxes may not be installed. The prudent - sysadmin would research and implement sandboxes for servers - whenever possible.</para> - - <para>There are a number of other servers that typically do not run - in sandboxes: <application>sendmail</application>, - <application>popper</application>, - <application>imapd</application>, <application>ftpd</application>, - and others. There are alternatives to some of these, but - installing them may require more work then you are willing to - perform (the convenience factor strikes again). You may have to - run these servers as root and rely on other mechanisms to detect - break-ins that might occur through them.</para> - - <para>The other big potential root hole in a system are the - suid-root and sgid binaries installed on the system. Most of - these binaries, such as <application>rlogin</application>, reside - in <filename>/bin</filename>, <filename>/sbin</filename>, - <filename>/usr/bin</filename>, or <filename>/usr/sbin</filename>. - While nothing is 100% safe, the system-default suid and sgid - binaries can be considered reasonably safe. Still, root holes are - occasionally found in these binaries. A root hole was found in - <literal>Xlib</literal> in 1998 that made - <application>xterm</application> (which is typically suid) - vulnerable. It is better to be safe then sorry and the prudent - sysadmin will restrict suid binaries that only staff should run to - a special group that only staff can access, and get rid of - (<command>chmod 000</command>) any suid binaries that nobody uses. - A server with no display generally does not need an - <application>xterm</application> binary. Sgid binaries can be - almost as dangerous. If an intruder can break an sgid-kmem binary - the intruder might be able to read <filename>/dev/kmem</filename> - and thus read the crypted password file, potentially compromising - any passworded account. Alternatively an intruder who breaks - group <literal>kmem</literal> can monitor keystrokes sent through - pty's, including pty's used by users who login through secure - methods. An intruder that breaks the tty group can write to - almost any user's tty. If a user is running a terminal program or - emulator with a keyboard-simulation feature, the intruder can - potentially generate a data stream that causes the user's terminal - to echo a command, which is then run as that user.</para> - </sect2> - - <sect2 id="secure-users"> - <title>Securing User Accounts</title> - - <para>User accounts are usually the most difficult to secure. While - you can impose Draconian access restrictions on your staff and - <literal>*</literal> out their passwords, you may not be able to - do so with any general user accounts you might have. If you do - have sufficient control then you may win out and be able to secure - the user accounts properly. If not, you simply have to be more - vigilant in your monitoring of those accounts. Use of - <application>ssh</application> and kerberos for user accounts is - more problematic due to the extra administration and technical - support required, but still a very good solution compared to a - crypted password file.</para> - </sect2> - - <sect2> - <title>Securing the Password File</title> - - <para>The only sure fire way is to <literal>*</literal> out as many - passwords as you can and use <application>ssh</application> or - kerberos for access to those accounts. Even though the crypted - password file (<filename>/etc/spwd.db</filename>) can only be read - by root, it may be possible for an intruder to obtain read access - to that file even if the attacker cannot obtain root-write - access.</para> - - <para>Your security scripts should always check for and report - changes to the password file (see <link - linkend="security-integrity">Checking file integrity</link> - below).</para> - </sect2> - - <sect2> - <title>Securing the Kernel Core, Raw Devices, and - Filesystems</title> - - <para>If an attacker breaks root he can do just about anything, but - there are certain conveniences. For example, most modern kernels - have a packet sniffing device driver built in. Under FreeBSD it - is called the <devicename>bpf</devicename> device. An intruder - will commonly attempt to run a packet sniffer on a compromised - machine. You do not need to give the intruder the capability and - most systems should not have the bpf device compiled in.</para> - - <para>But even if you turn off the bpf device, you still have - <filename>/dev/mem</filename> and <filename>/dev/kmem</filename> - to worry about. For that matter, the intruder can still write to - raw disk devices. Also, there is another kernel feature called - the module loader, &man.kldload.8;. An enterprising intruder can - use a KLD module to install his own bpf device or other sniffing - device on a running kernel. To avoid these problems you have to - run the kernel at a higher secure level, at least securelevel 1. - The securelevel can be set with a <command>sysctl</command> on - the <literal>kern.securelevel</literal> variable. Once you have - set the securelevel to 1, write access to raw devices will be - denied and special chflags flags, such as <literal>schg</literal>, - will be enforced. You must also ensure that the - <literal>schg</literal> flag is set on critical startup binaries, - directories, and script files – everything that gets run up - to the point where the securelevel is set. This might be overdoing - it, and upgrading the system is much more difficult when you - operate at a higher secure level. You may compromise and run the - system at a higher secure level but not set the - <literal>schg</literal> flag for every system file and directory - under the sun. Another possibility is to simply mount - <filename>/</filename> and <filename>/usr</filename> read-only. - It should be noted that being too draconian in what you attempt to - protect may prevent the all-important detection of an - intrusion.</para> - </sect2> - - <sect2 id="security-integrity"> - <title>Checking File Integrity: Binaries, Configuration Files, - Etc.</title> - - <para>When it comes right down to it, you can only protect your core - system configuration and control files so much before the - convenience factor rears its ugly head. For example, using - <command>chflags</command> to set the <literal>schg</literal> bit - on most of the files in <filename>/</filename> and - <filename>/usr</filename> is probably counterproductive because - while it may protect the files, it also closes a detection window. - The last layer of your security onion is perhaps the most - important – detection. The rest of your security is pretty - much useless (or, worse, presents you with a false sense of - safety) if you cannot detect potential incursions. Half the job - of the onion is to slow down the attacker rather then stop him in - order to give the detection side of the equation a chance to catch - him in the act.</para> - - <para>The best way to detect an incursion is to look for modified, - missing, or unexpected files. The best way to look for modified - files is from another (often centralized) limited-access system. - Writing your security scripts on the extra-secure limited-access - system makes them mostly invisible to potential attackers, and this - is important. In order to take maximum advantage you generally - have to give the limited-access box significant access to the - other machines in the business, usually either by doing a - read-only NFS export of the other machines to the limited-access - box, or by setting up <application>ssh</application> keypairs to - allow the limit-access box to <application>ssh</application> to - the other machines. Except for its network traffic, NFS is the - least visible method – allowing you to monitor the - filesystems on each client box virtually undetected. If your - limited-access server is connected to the client boxes through a - switch, the NFS method is often the better choice. If your - limited-access server is connected to the client boxes through a - hub or through several layers of routing, the NFS method may be - too insecure (network-wise) and using - <application>ssh</application> may be the better choice even with - the audit-trail tracks that <application>ssh</application> - lays.</para> - - <para>Once you give a limit-access box at least read access to the - client systems it is supposed to monitor, you must write scripts - to do the actual monitoring. Given an NFS mount, you can write - scripts out of simple system utilities such as &man.find.1; and - &man.md5.1;. It is best to physically md5 the client-box files - boxes at least once a day, and to test control files such as those - found in <filename>/etc</filename> and - <filename>/usr/local/etc</filename> even more often. When - mismatches are found relative to the base md5 information the - limited-access machine knows is valid, it should scream at a - sysadmin to go check it out. A good security script will also - check for inappropriate suid binaries and for new or deleted files - on system partitions such as <filename>/</filename> and - <filename>/usr</filename>.</para> - - <para>When using <application>ssh</application> rather then NFS, - writing the security script is much more difficult. You - essentially have to scp the scripts to the client box in order to - run them, making them visible, and for safety you also need to - <command>scp</command> the binaries (such as find) that those - scripts use. The <application>ssh</application> daemon on the - client box may already be compromised. All in all, using - <application>ssh</application> may be necessary when running over - unsecure links, but it's also a lot harder to deal with.</para> - - <para>A good security script will also check for changes to user and - staff members access configuration files: - <filename>.rhosts</filename>, <filename>.shosts</filename>, - <filename>.ssh/authorized_keys</filename> and so forth… - files that might fall outside the purview of the - <literal>MD5</literal> check.</para> - - <para>If you have a huge amount of user disk space it may take too - long to run through every file on those partitions. In this case, - setting mount flags to disallow suid binaries and devices on those - partitions is a good idea. The <literal>nodev</literal> and - <literal>nosuid</literal> options (see &man.mount.8;) are what you - want to look into. I would scan them anyway at least once a week, - since the object of this layer is to detect a break-in whether or - not the break-in is effective.</para> - - <para>Process accounting (see &man.accton.8;) is a relatively - low-overhead feature of the operating system which I recommend - using as a post-break-in evaluation mechanism. It is especially - useful in tracking down how an intruder has actually broken into - a system, assuming the file is still intact after the break-in - occurs.</para> - - <para>Finally, security scripts should process the log files and the - logs themselves should be generated in as secure a manner as - possible – remote syslog can be very useful. An intruder - tries to cover his tracks, and log files are critical to the - sysadmin trying to track down the time and method of the initial - break-in. One way to keep a permanent record of the log files is - to run the system console to a serial port and collect the - information on a continuing basis through a secure machine - monitoring the consoles.</para> - </sect2> - - <sect2> - <title>Paranoia</title> - - <para>A little paranoia never hurts. As a rule, a sysadmin can add - any number of security features as long as they do not effect - convenience, and can add security features that do effect - convenience with some added thought. Even more importantly, a - security administrator should mix it up a bit – if you use - recommendations such as those given by this document verbatim, you - give away your methodologies to the prospective attacker who also - has access to this document.</para> - </sect2> - - <sect2> - <title>Denial of Service Attacks</title> - - <para>This section covers Denial of Service attacks. A DOS attack - is typically a packet attack. While there is not much you can do - about modern spoofed packet attacks that saturate your network, - you can generally limit the damage by ensuring that the attacks - cannot take down your servers.</para> - - <orderedlist> - <listitem> - <para>Limiting server forks.</para> - </listitem> - - <listitem> - <para>Limiting springboard attacks (ICMP response attacks, ping - broadcast, etc.).</para> - </listitem> - - <listitem> - <para>Kernel Route Cache.</para> - </listitem> - </orderedlist> - - <para>A common DOS attack is against a forking server that attempts - to cause the server to eat processes, file descriptors, and memory - until the machine dies. Inetd (see &man.inetd.8;) has several - options to limit this sort of attack. It should be noted that - while it is possible to prevent a machine from going down it is - not generally possible to prevent a service from being disrupted - by the attack. Read the inetd manual page carefully and pay - specific attention to the <option>-c</option>, <option>-C</option>, - and <option>-R</option> options. Note that spoofed-IP attacks - will circumvent the <option>-C</option> option to inetd, so - typically a combination of options must be used. Some standalone - servers have self-fork-limitation parameters.</para> - - <para><application>Sendmail</application> has its - <option>-OMaxDaemonChildren</option> option which tends to work - much better than trying to use sendmail's load limiting options - due to the load lag. You should specify a - <literal>MaxDaemonChildren</literal> parameter when you start - <application>sendmail</application> high enough to handle your - expected load but no so high that the computer cannot handle that - number of <application>sendmails</application> without falling on - its face. It is also prudent to run sendmail in queued mode - (<option>-ODeliveryMode=queued</option>) and to run the daemon - (<command>sendmail -bd</command>) separate from the queue-runs - (<command>sendmail -q15m</command>). If you still want real-time - delivery you can run the queue at a much lower interval, such as - <option>-q1m</option>, but be sure to specify a reasonable - <literal>MaxDaemonChildren</literal> option for that sendmail to - prevent cascade failures.</para> - - <para><application>Syslogd</application> can be attacked directly - and it is strongly recommended that you use the <option>-s</option> - option whenever possible, and the <option>-a</option> option - otherwise.</para> - - <para>You should also be fairly careful with connect-back services - such as <application>tcpwrapper</application>'s reverse-identd, - which can be attacked directly. You generally do not want to use - the reverse-ident feature of - <application>tcpwrappers</application> for this reason.</para> - - <para>It is a very good idea to protect internal services from - external access by firewalling them off at your border routers. - The idea here is to prevent saturation attacks from outside your - LAN, not so much to protect internal services from network-based - root compromise. Always configure an exclusive firewall, i.e., - <quote>firewall everything <emphasis>except</emphasis> ports A, B, - C, D, and M-Z</quote>. This way you can firewall off all of your - low ports except for certain specific services such as - <application>named</application> (if you are primary for a zone), - <application>ntalkd</application>, - <application>sendmail</application>, and other internet-accessible - services. If you try to configure the firewall the other way - – as an inclusive or permissive firewall, there is a good - chance that you will forget to <quote>close</quote> a couple of - services or that you will add a new internal service and forget - to update the firewall. You can still open up the high-numbered - port range on the firewall to allow permissive-like operation - without compromising your low ports. Also take note that FreeBSD - allows you to control the range of port numbers used for dynamic - binding via the various <literal>net.inet.ip.portrange</literal> - <command>sysctl</command>'s (<command>sysctl -a | fgrep - portrange</command>), which can also ease the complexity of your - firewall's configuration. I usually use a normal first/last range - of 4000 to 5000, and a hiport range of 49152 to 65535, then block - everything under 4000 off in my firewall (except for certain - specific internet-accessible ports, of course).</para> - - <para>Another common DOS attack is called a springboard attack - – to attack a server in a manner that causes the server to - generate responses which then overload the server, the local - network, or some other machine. The most common attack of this - nature is the <emphasis>ICMP ping broadcast attack</emphasis>. - The attacker spoofs ping packets sent to your LAN's broadcast - address with the source IP address set to the actual machine they - wish to attack. If your border routers are not configured to - stomp on ping's to broadcast addresses, your LAN winds up - generating sufficient responses to the spoofed source address to - saturate the victim, especially when the attacker uses the same - trick on several dozen broadcast addresses over several dozen - different networks at once. Broadcast attacks of over a hundred - and twenty megabits have been measured. A second common - springboard attack is against the ICMP error reporting system. - By constructing packets that generate ICMP error responses, an - attacker can saturate a server's incoming network and cause the - server to saturate its outgoing network with ICMP responses. This - type of attack can also crash the server by running it out of - mbuf's, especially if the server cannot drain the ICMP responses - it generates fast enough. The FreeBSD kernel has a new kernel - compile option called ICMP_BANDLIM which limits the effectiveness - of these sorts of attacks. The last major class of springboard - attacks is related to certain internal inetd services such as the - udp echo service. An attacker simply spoofs a UDP packet with the - source address being server A's echo port, and the destination - address being server B's echo port, where server A and B are both - on your LAN. The two servers then bounce this one packet back and - forth between each other. The attacker can overload both servers - and their LANs simply by injecting a few packets in this manner. - Similar problems exist with the internal chargen port. A - competent sysadmin will turn off all of these inetd-internal test - services.</para> - - <para>Spoofed packet attacks may also be used to overload the kernel - route cache. Refer to the <literal>net.inet.ip.rtexpire</literal>, - <literal>rtminexpire</literal>, and <literal>rtmaxcache</literal> - <command>sysctl</command> parameters. A spoofed packet attack - that uses a random source IP will cause the kernel to generate a - temporary cached route in the route table, viewable with - <command>netstat -rna | fgrep W3</command>. These routes - typically timeout in 1600 seconds or so. If the kernel detects - that the cached route table has gotten too big it will dynamically - reduce the rtexpire but will never decrease it to less then - rtminexpire. There are two problems:</para> - - <orderedlist> - <listitem> - <para>The kernel does not react quickly enough when a lightly - loaded server is suddenly attacked.</para> - </listitem> - - <listitem> - <para>The <literal>rtminexpire</literal> is not low enough for - the kernel to survive a sustained attack.</para> - </listitem> - </orderedlist> - - <para>If your servers are connected to the internet via a T3 or - better it may be prudent to manually override both - <literal>rtexpire</literal> and <literal>rtminexpire</literal> - via &man.sysctl.8;. Never set either parameter to zero (unless - you want to crash the machine <!-- smiley -->:-). Setting both - parameters to 2 seconds should be sufficient to protect the route - table from attack.</para> - </sect2> - - <sect2> - <title>Access Issues with Kerberos and SSH</title> - - <para>There are a few issues with both kerberos and - <application>ssh</application> that need to be addressed if - you intend to use them. Kerberos V is an excellent - authentication protocol but there are bugs in the kerberized - <application>telnet</application> and - <application>rlogin</application> applications that make them - unsuitable for dealing with binary streams. Also, by default - kerberos does not encrypt a session unless you use the - <option>-x</option> option. <application>ssh</application> - encrypts everything by default.</para> - - <para><application>ssh</application> works quite well in every - respect except that it forwards encryption keys by default. What - this means is that if you have a secure workstation holding keys - that give you access to the rest of the system, and you - <application>ssh</application> to an unsecure machine, your keys - becomes exposed. The actual keys themselves are not exposed, but - <application>ssh</application> installs a forwarding port for the - duration of your login and if a attacker has broken root on the - unsecure machine he can utilize that port to use your keys to gain - access to any other machine that your keys unlock.</para> - - <para>We recommend that you use <application>ssh</application> in - combination with kerberos whenever possible for staff logins. - <application>ssh</application> can be compiled with kerberos - support. This reduces your reliance on potentially exposable - <application>ssh</application> keys while at the same time - protecting passwords via kerberos. <application>ssh</application> - keys should only be used for automated tasks from secure machines - (something that kerberos is unsuited to). We also recommend that - you either turn off key-forwarding in the - <application>ssh</application> configuration, or that you make use - of the <literal>from=IP/DOMAIN</literal> option that - <application>ssh</application> allows in its - <filename>authorized_keys</filename> file to make the key only - usable to entities logging in from specific machines.</para> - </sect2> - </sect1> - - <sect1 id="crypt"> - <title>DES, MD5, and Crypt</title> - - <para><emphasis>Parts rewritten and updated by &a.unfurl;, 21 March - 2000.</emphasis></para> - - <para>Every user on a UNIX system has a password associated with - their account. It seems obvious that these passwords need to be - known only to the user and the actual operating system. In - order to keep these passwords secret, they are encrypted with - what is known as a <quote>one-way hash</quote>, that is, they can - only be easily encrypted but not decrypted. In other words, what - we told you a moment ago was obvious is not even true: the - operating system itself does not <emphasis>really</emphasis> know - the password. It only knows the <emphasis>encrypted</emphasis> - form of the password. The only way to get the - <quote>plain-text</quote> password is by a brute force search of the - space of possible passwords.</para> - - <para>Unfortunately the only secure way to encrypt passwords when - UNIX came into being was based on DES, the Data Encryption - Standard. This is not such a problem for users that live in - the US, but since the source code for DES could not be exported - outside the US, FreeBSD had to find a way to both comply with - US law and retain compatibility with all the other UNIX - variants that still use DES.</para> - - <para>The solution was to divide up the encryption libraries - so that US users could install the DES libraries and use - DES but international users still had an encryption method - that could be exported abroad. This is how FreeBSD came to - use MD5 as its default encryption method. MD5 is believed to - be more secure than DES, so installing DES is offered primarily - for compatibility reasons.</para> - - <sect2> - <title>Recognizing your crypt mechanism</title> - - <para>It is pretty easy to identify which encryption method - FreeBSD is set up to use. Examining the encrypted passwords in - the <filename>/etc/master.passwd</filename> file is one way. - Passwords encrypted with the MD5 hash are longer than those with - encrypted with the DES hash and also begin with the characters - <literal>$1$</literal>. DES password strings do not - have any particular identifying characteristics, but they are - shorter than MD5 passwords, and are coded in a 64-character - alphabet which does not include the <literal>$</literal> - character, so a relatively short string which does not begin with - a dollar sign is very likely a DES password.</para> - - <para>The libraries can identify the passwords this way as well. - As a result, the DES libraries are able to identify MD5 - passwords, and use MD5 to check passwords that were encrypted - that way, and DES for the rest. They are able to do this - because the DES libraries also contain MD5. Unfortunately, the - reverse is not true, so the MD5 libraries cannot authenticate - passwords that were encrypted with DES.</para> - - <para>Identifying which library is being used by the programs on - your system is easy as well. Any program that uses crypt is linked - against libcrypt which for each type of library is a symbolic link - to the appropriate implementation. For example, on a system using - the DES versions:</para> - - <screen>&prompt.user; <userinput>ls -l /usr/lib/libcrypt*</userinput> -lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a -lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0 -lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.a</screen> - - <para>On a system using the MD5-based libraries, the same links will - be present, but the target will be <filename>libscrypt</filename> - rather than <filename>libdescrypt</filename>.</para> - - <para>If you have installed the DES-capable crypt library - <filename>libdescrypt</filename> (e.g. by installing the - "crypto" distribution), then which password format will be used - for new passwords is controlled by the - <quote>passwd_format</quote> login capability in - <filename>/etc/login.conf</filename>, which takes values of - either <quote>des</quote> or <quote>md5</quote>. See the - login.conf(5) manpage for more information about login - capabilities.</para> - </sect2> - </sect1> - - <sect1 id="skey"> - <title>S/Key</title> - - <para>S/Key is a one-time password scheme based on a one-way hash - function. FreeBSD uses the MD4 hash for compatibility but other - systems have used MD5 and DES-MAC. S/Key has been part of the - FreeBSD base system since version 1.1.5 and is also used on a - growing number of other operating systems. S/Key is a registered - trademark of Bell Communications Research, Inc.</para> - - <para>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 will call this a <quote>UNIX password</quote>. - The second sort is the one-time password which is generated by the - S/Key <command>key</command> program and accepted by the - <command>keyinit</command> program and the login prompt; we will - call this a <quote>one-time password</quote>. The final sort of - password is the secret password which you give to the - <command>key</command> program (and sometimes the - <command>keyinit</command> program) which it uses to generate - one-time passwords; we will call it a <quote>secret password</quote> - or just unqualified <quote>password</quote>.</para> - - <para>The secret password does not have anything to do with your UNIX - password; they can be the same but this is not recommended. S/Key - secret passwords are not limited to 8 characters like UNIX passwords, - they can be as long as you like. Passwords of six or seven word - long phrases are fairly common. For the most part, the S/Key system - operates completely independently of the UNIX password - system.</para> - - <para>Besides the password, there are two other pieces of data that - are important to S/Key. One is what is known as the - <quote>seed</quote> or <quote>key</quote> and consists of two letters - and five digits. The other is what is called the <quote>iteration - count</quote> and is a number between 1 and 100. S/Key creates the - one-time password by concatenating the seed and the secret password, - then applying the MD4 hash as many times as specified by the - iteration count and turning the result into six short English words. - These six English words are your one-time password. The - <command>login</command> and <command>su</command> programs keep - track of the last one-time password used, and the user is - authenticated if the hash of the user-provided password is equal to - the previous password. Because a one-way hash is used it is - impossible to generate future one-time passwords if a successfully - used password is captured; the iteration count is decremented after - each successful login to keep the user and the login program in - sync. When the iteration count gets down to 1 S/Key must be - reinitialized.</para> - - <para>There are four programs involved in the S/Key system which we - will discuss below. The <command>key</command> program accepts an - iteration count, a seed, and a secret password, and generates a - one-time password. The <command>keyinit</command> program is used - to initialized S/Key, and to change passwords, iteration counts, or - seeds; it takes either a secret password, or an iteration count, - seed, and one-time password. The <command>keyinfo</command> program - examines the <filename>/etc/skeykeys</filename> file and prints out - the invoking user's current iteration count and seed. Finally, the - <command>login</command> and <command>su</command> programs contain - the necessary logic to accept S/Key one-time passwords for - authentication. The <command>login</command> program is also - capable of disallowing the use of UNIX passwords on connections - coming from specified addresses.</para> - - <para>There are four different sorts of operations we will cover. The - first is using the <command>keyinit</command> program over a secure - connection to set up S/Key for the first time, or to change your - password or seed. The second operation is using the - <command>keyinit</command> program over an insecure connection, in - conjunction with the <command>key</command> program over a secure - connection, to do the same. The third is using the - <command>key</command> program to log in over an insecure - connection. The fourth is using the <command>key</command> program - to generate a number of keys which can be written down or printed - out to carry with you when going to some location without secure - connections to anywhere.</para> - - <sect2> - <title>Secure connection initialization</title> - - <para>To initialize S/Key for the first time, change your password, - or change your seed while logged in over a secure connection - (e.g., on the console of a machine or via ssh), use the - <command>keyinit</command> command without any parameters while - logged in as yourself:</para> - - <screen>&prompt.user; <userinput>keyinit</userinput> -Adding unfurl: -Reminder - Only use this method if you are directly connected. -If you are using telnet or rlogin exit with no password and use keyinit -s. -Enter secret password: -Again secret password: - -ID unfurl s/key is 99 to17757 -DEFY CLUB PRO NASH LACE SOFT</screen> - - <para>At the <prompt>Enter secret password:</prompt> prompt you - should enter a password or phrase. Remember, this is not the - password that you will use to login with, this is used to generate - your one-time login keys. The <quote>ID</quote> line 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 - 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.</para> - </sect2> - - <sect2> - <title>Insecure connection initialization</title> - - <para>To initialize S/Key or change your secret password over an - insecure connection, you will need to already have a secure - connection to some place where you can run the - <command>key</command> program; this might be in the form of a - desk accessory on a Macintosh, or a shell prompt on a machine you - trust. 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 <command>keyinit - -s</command> command:</para> - - <screen>&prompt.user; <userinput>keyinit -s</userinput> -Updating unfurl: -Old key: to17758 -Reminder you need the 6 English words from the key command. -Enter sequence count from 1 to 9999: <userinput>100</userinput> -Enter new key [default to17759]: -s/key 100 to 17759 -s/key access password:</screen> - - <para>To accept the default seed (which the - <command>keyinit</command> program confusingly calls a - <literal>key</literal>), press return. Then before entering an - access password, move over to your secure connection or S/Key desk - accessory, and give it the same parameters:</para> - - <screen>&prompt.user; <userinput>key 100 to17759</userinput> -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: <userinput><secret password></userinput> -CURE MIKE BANE HIM RACY GORE</screen> - - <para>Now switch back over to the insecure connection, and copy the - one-time password generated by <command>key</command> over to the - <command>keyinit</command> program:</para> - - <screen>s/key access password:<userinput>CURE MIKE BANE HIM RACY GORE</userinput> -ID unfurl s/key is 100 to17759 -CURE MIKE BANE HIM RACY GORE</screen> - - <para>The rest of the description from the previous section applies - here as well.</para> - </sect2> - - <sect2> - <title>Generating a single one-time password</title> - - <para>Once you've initialized S/Key, when you login you will be - presented with a prompt like this:</para> - -<screen>&prompt.user; <userinput>telnet example.com</userinput> -Trying 10.0.0.1... -Connected to example.com -Escape character is '^]'. - -FreeBSD/i386 (example.com) (ttypa) - -login: <userinput><username></userinput> -s/key 97 fw13894 -Password: </screen> - - <para>As a side note, the S/Key prompt has a useful feature - (not shown here): if you press return at the password prompt, the - login program will turn echo on, so you can see what you are - typing. This can be extremely useful if you are attempting to - type in an S/Key by hand, such as from a printout. Also, if this - machine were configured to disallow UNIX passwords over a - connection from my machine, the prompt would have also included - the annotation <literal>(s/key required)</literal>, indicating - that only S/Key one-time passwords will be accepted.</para> - - <para>At this point you need to generate your one-time password to - answer this login prompt. This must be done on a trusted system - that you can run the <command>key</command> command on. (There - are versions of the <command>key</command> program from DOS, - Windows and MacOS as well.) The <command>key</command> program - needs both the iteration count and the seed as command line - options. You can cut-and-paste these right from the login prompt - on the machine that you are logging in to.</para> - - <para>On the trusted system:</para> - - <screen>&prompt.user; <userinput>key 97 fw13894</userinput> -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: -WELD LIP ACTS ENDS ME HAAG</screen> - - <para>Now that you have your one-time password you can continue - logging in:</para> - - <screen>login: <userinput><username></userinput> -s/key 97 fw13894 -Password: <userinput><return to enable echo></userinput> -s/key 97 fw13894 -Password [echo on]: WELD LIP ACTS ENDS ME HAAG -Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... </screen> - - <para>This is the easiest mechanism <emphasis>if</emphasis> you have - a trusted machine. There is a Java S/Key <command>key</command> - applet, <ulink - url="http://www.cs.umd.edu/~harry/jotp/src.html">The Java OTP - Calculator</ulink>, that you can download and run locally on any - Java supporting browser.</para> - </sect2> - - <sect2> - <title>Generating multiple one-time passwords</title> - - <para>Sometimes you have have to go places where you do not have - access to a trusted machine or secure connection. In this case, - it is possible to use the <command>key</command> command to - generate a number of one-time passwords before hand to be printed - out and taken with you. For example:</para> - - <screen>&prompt.user; <userinput>key -n 5 30 zz99999</userinput> -Reminder - Do not use this program while logged in via telnet or rlogin. -Enter secret password: <userinput><secret password></userinput> -26: SODA RUDE LEA LIND BUDD SILT -27: JILT SPY DUTY GLOW COWL ROT -28: THEM OW COLA RUNT BONG SCOT -29: COT MASH BARR BRIM NAN FLAG -30: CAN KNEE CAST NAME FOLK BILK</screen> - - <para>The <option>-n 5</option> requests five keys in sequence, the - <option>30</option> specifies what the last iteration number - should be. Note that these are printed out in - <emphasis>reverse</emphasis> 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 <command>lpr</command>. Note - that each line shows both the iteration count and the one-time - password; you may still find it handy to scratch off passwords as - you use them.</para> - </sect2> - - <sect2> - <title>Restricting use of UNIX passwords</title> - - <para>Restrictions can be placed on the use of UNIX passwords based - on the host name, user name, terminal port, or IP address of a - login session. These restrictions can be found in the - configuration file <filename>/etc/skey.access</filename>. The - &man.skey.access.5; manual page has more info on the complete - format of the file and also details some security cautions to be - aware of before depending on this file for security.</para> - - <para>If there is no <filename>/etc/skey.access</filename> file - (this is the FreeBSD default), then all users will be allowed to - use UNIX passwords. If the file exists, however, then all users - will be required to use S/Key unless explicitly permitted to do - otherwise by configuration statements in the - <filename>skey.access</filename> file. In all cases, UNIX - passwords are permitted on the console.</para> - - <para>Here is a sample configuration file which illustrates the - three most common sorts of configuration statements:</para> - - <programlisting> -permit internet 192.168.0.0 255.255.0.0 -permit user fnord -permit port ttyd0</programlisting> - - <para>The first line (<literal>permit internet</literal>) allows - users whose IP source address (which is vulnerable to spoofing) - matches the specified value and mask, to use UNIX passwords. This - should not be considered a security mechanism, but rather, a means - to remind authorized users that they are using an insecure network - and need to use S/Key for authentication.</para> - - <para>The second line (<literal>permit user</literal>) allows the - specified username, in this case <literal>fnord</literal>, to use - UNIX passwords at any time. Generally speaking, this should only - be used for people who are either unable to use the - <command>key</command> program, like those with dumb terminals, or - those who are uneducable.</para> - - <para>The third line (<literal>permit port</literal>) allows all - users logging in on the specified terminal line to use UNIX - passwords; this would be used for dial-ups.</para> - </sect2> - </sect1> - - <sect1 id="kerberos"> - <title>Kerberos</title> - - <para><emphasis>Contributed by &a.markm; (based on contribution by - &a.md;).</emphasis></para> - - <para>Kerberos is a network add-on system/protocol that allows users to - authenticate themselves through the services of a secure server. - Services such as remote login, remote copy, secure inter-system file - copying and other high-risk tasks are made considerably safer and more - controllable.</para> - - <para>The following instructions can be used as a guide on how to set up - Kerberos as distributed for FreeBSD. However, you should refer to the - relevant manual pages for a complete description.</para> - - <para>In FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite, - distribution, but eBones, which had been previously ported to FreeBSD - 1.1.5.1, and was sourced from outside the USA/Canada, and was thus - available to system owners outside those countries during the era - of restrictive export controls on cryptographic code from the USA.</para> - - <sect2> - <title>Creating the initial database</title> - - <para>This is done on the Kerberos server only. First make sure that - you do not have any old Kerberos databases around. You should change - to the directory <filename>/etc/kerberosIV</filename> and check that - only the following files are present:</para> - - <screen>&prompt.root; <userinput>cd /etc/kerberosIV</userinput> -&prompt.root; <userinput>ls</userinput> -README krb.conf krb.realms</screen> - - <para>If any additional files (such as <filename>principal.*</filename> - or <filename>master_key</filename>) exist, then use the - <command>kdb_destroy</command> command to destroy the old Kerberos - database, of if Kerberos is not running, simply delete the extra - files.</para> - - <para>You should now edit the <filename>krb.conf</filename> and - <filename>krb.realms</filename> files to define your Kerberos realm. - In this case the realm will be <filename>GRONDAR.ZA</filename> and the - server is <filename>grunt.grondar.za</filename>. We edit or create - the <filename>krb.conf</filename> file:</para> - - <screen>&prompt.root; <userinput>cat krb.conf</userinput> -GRONDAR.ZA -GRONDAR.ZA grunt.grondar.za admin server -CS.BERKELEY.EDU okeeffe.berkeley.edu -ATHENA.MIT.EDU kerberos.mit.edu -ATHENA.MIT.EDU kerberos-1.mit.edu -ATHENA.MIT.EDU kerberos-2.mit.edu -ATHENA.MIT.EDU kerberos-3.mit.edu -LCS.MIT.EDU kerberos.lcs.mit.edu -TELECOM.MIT.EDU bitsy.mit.edu -ARC.NASA.GOV trident.arc.nasa.gov</screen> - - <para>In this case, the other realms do not need to be there. They are - here as an example of how a machine may be made aware of multiple - realms. You may wish to not include them for simplicity.</para> - - <para>The first line names the realm in which this system works. The - other lines contain realm/host entries. The first item on a line is a - realm, and the second is a host in that realm that is acting as a - <quote>key distribution center</quote>. The words <literal>admin - server</literal> following a hosts name means that host also - provides an administrative database server. For further explanation - of these terms, please consult the Kerberos man pages.</para> - - <para>Now we have to add <hostid role="fqdn">grunt.grondar.za</hostid> - to the <filename>GRONDAR.ZA</filename> realm and also add an entry to - put all hosts in the <hostid role="domainname">.grondar.za</hostid> - domain in the <filename>GRONDAR.ZA</filename> realm. The - <filename>krb.realms</filename> file would be updated as - follows:</para> - - <screen>&prompt.root; <userinput>cat krb.realms</userinput> -grunt.grondar.za GRONDAR.ZA -.grondar.za GRONDAR.ZA -.berkeley.edu CS.BERKELEY.EDU -.MIT.EDU ATHENA.MIT.EDU -.mit.edu ATHENA.MIT.EDU</screen> - - <para>Again, the other realms do not need to be there. They are here as - an example of how a machine may be made aware of multiple realms. You - may wish to remove them to simplify things.</para> - - <para>The first line puts the <emphasis>specific</emphasis> system into - the named realm. The rest of the lines show how to default systems of - a particular subdomain to a named realm.</para> - - <para>Now we are ready to create the database. This only needs to run - on the Kerberos server (or Key Distribution Center). Issue the - <command>kdb_init</command> command to do this:</para> - - <screen>&prompt.root; <userinput>kdb_init</userinput> -<prompt>Realm name [default ATHENA.MIT.EDU ]:</prompt> <userinput>GRONDAR.ZA</userinput> -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password. - -<prompt>Enter Kerberos master key:</prompt> </screen> - - <para>Now we have to save the key so that servers on the local machine - can pick it up. Use the <command>kstash</command> command to do - this.</para> - - <screen>&prompt.root; <userinput>kstash</userinput> - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE!</screen> - - <para>This saves the encrypted master password in - <filename>/etc/kerberosIV/master_key</filename>.</para> - </sect2> - - <sect2> - <title>Making it all run</title> - - <para>Two principals need to be added to the database for - <emphasis>each</emphasis> system that will be secured with Kerberos. - Their names are <literal>kpasswd</literal> and <literal>rcmd</literal> - These two principals are made for each system, with the instance being - the name of the individual system.</para> - - <para>These daemons, <command>kpasswd</command> and - <command>rcmd</command> allow other systems to change Kerberos - passwords and run commands like <command>rcp</command>, - <command>rlogin</command> and <command>rsh</command>.</para> - - <para>Now let's add these entries:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>passwd</userinput> -<prompt>Instance:</prompt> <userinput>grunt</userinput> - -<Not found>, <prompt>Create [y] ?</prompt> <userinput>y</userinput> - -Principal: passwd, Instance: grunt, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter RANDOM here -Verifying password - -<prompt>New Password:</prompt> <---- enter RANDOM here - -<prompt>Random password [y] ?</prompt> <userinput>y</userinput> - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <userinput>rcmd</userinput> -<prompt>Instance:</prompt> <userinput>grunt</userinput> - -<Not found>, <prompt>Create [y] ?</prompt> - -Principal: rcmd, Instance: grunt, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter RANDOM here -Verifying password - -<prompt>New Password:</prompt> <---- enter RANDOM here - -<prompt>Random password [y] ?</prompt> - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - </sect2> - - <sect2> - <title>Creating the server file</title> - - <para>We now have to extract all the instances which define the services - on each machine. For this we use the <command>ext_srvtab</command> - command. This will create a file which must be copied or moved - <emphasis>by secure means</emphasis> to each Kerberos client's - /etc/kerberosIV directory. This file must be present on each server - and client, and is crucial to the operation of Kerberos.</para> - - - <screen>&prompt.root; <userinput>ext_srvtab grunt</userinput> -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Generating 'grunt-new-srvtab'....</screen> - - <para>Now, this command only generates a temporary file which must be - renamed to <filename>srvtab</filename> so that all the server can pick - it up. Use the <command>mv</command> command to move it into place on - the original system:</para> - - <screen>&prompt.root; <userinput>mv grunt-new-srvtab srvtab</userinput></screen> - - <para>If the file is for a client system, and the network is not deemed - safe, then copy the - <filename><replaceable>client</replaceable>-new-srvtab</filename> to - removable media and transport it by secure physical means. Be sure to - rename it to <filename>srvtab</filename> in the client's - <filename>/etc/kerberosIV</filename> directory, and make sure it is - mode 600:</para> - - <screen>&prompt.root; <userinput>mv grumble-new-srvtab srvtab</userinput> -&prompt.root; <userinput>chmod 600 srvtab</userinput></screen> - </sect2> - - <sect2> - <title>Populating the database</title> - - <para>We now have to add some user entries into the database. First - let's create an entry for the user <username>jane</username>. Use the - <command>kdb_edit</command> command to do this:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>jane</userinput> -<prompt>Instance:</prompt> - -<Not found>, <prompt>Create [y] ?</prompt> <userinput>y</userinput> - -Principal: jane, Instance: , kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter a secure password here -Verifying password - -<prompt>New Password:</prompt> <---- re-enter the password here -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - </sect2> - - <sect2> - <title>Testing it all out</title> - - <para>First we have to start the Kerberos daemons. NOTE that if you - have correctly edited your <filename>/etc/rc.conf</filename> then this - will happen automatically when you reboot. This is only necessary on - the Kerberos server. Kerberos clients will automagically get what - they need from the <filename>/etc/kerberosIV</filename> - directory.</para> - - <screen>&prompt.root; <userinput>kerberos &</userinput> -Kerberos server starting -Sleep forever on error -Log file is /var/log/kerberos.log -Current Kerberos master key version is 1. - -Master key entered. BEWARE! - -Current Kerberos master key version is 1 -Local realm: GRONDAR.ZA -&prompt.root; <userinput>kadmind -n &</userinput> -KADM Server KADM0.0A initializing -Please do not use 'kill -9' to kill this job, use a -regular kill instead - -Current Kerberos master key version is 1. - -Master key entered. BEWARE!</screen> - - <para>Now we can try using the <command>kinit</command> command to get a - ticket for the id <username>jane</username> that we created - above:</para> - - <screen>&prompt.user; <userinput>kinit jane</userinput> -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane" -<prompt>Password:</prompt> </screen> - - <para>Try listing the tokens using <command>klist</command> to see if we - really have them:</para> - - <screen>&prompt.user; <userinput>klist</userinput> -Ticket file: /tmp/tkt245 -Principal: jane@GRONDAR.ZA - - Issued Expires Principal -Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZA</screen> - - <para>Now try changing the password using <command>passwd</command> to - check if the kpasswd daemon can get authorization to the Kerberos - database:</para> - - <screen>&prompt.user; <userinput>passwd</userinput> -realm GRONDAR.ZA -<prompt>Old password for jane:</prompt> -<prompt>New Password for jane:</prompt> -Verifying password -<prompt>New Password for jane:</prompt> -Password changed.</screen> - </sect2> - - <sect2> - <title>Adding <command>su</command> privileges</title> - - <para>Kerberos allows us to give <emphasis>each</emphasis> user who - needs root privileges their own <emphasis>separate</emphasis> - <command>su</command>password. We could now add an id which is - authorized to <command>su</command> to <username>root</username>. - This is controlled by having an instance of <username>root</username> - associated with a principal. Using <command>kdb_edit</command> we can - create the entry <literal>jane.root</literal> in the Kerberos - database:</para> - - <screen>&prompt.root; <userinput>kdb_edit</userinput> -Opening database... - -<prompt>Enter Kerberos master key:</prompt> - -Current Kerberos master key version is 1. - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -<prompt>Principal name:</prompt> <userinput>jane</userinput> -<prompt>Instance:</prompt> <userinput>root</userinput> - -<Not found>, Create [y] ? y - -Principal: jane, Instance: root, kdc_key_ver: 1 -<prompt>New Password:</prompt> <---- enter a SECURE password here -Verifying password - -<prompt>New Password:</prompt> <---- re-enter the password here - -Principal's new key version = 1 -<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt> -<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> <userinput>12</userinput> <--- Keep this short! -<prompt>Attributes [ 0 ] ?</prompt> -Edit O.K. -<prompt>Principal name:</prompt> <---- null entry here will cause an exit</screen> - - <para>Now try getting tokens for it to make sure it works:</para> - - <screen>&prompt.root; <userinput>kinit jane.root</userinput> -MIT Project Athena (grunt.grondar.za) -Kerberos Initialization for "jane.root" -<prompt>Password:</prompt></screen> - - <para>Now we need to add the user to root's <filename>.klogin</filename> - file:</para> - - <screen>&prompt.root; <userinput>cat /root/.klogin</userinput> -jane.root@GRONDAR.ZA</screen> - - <para>Now try doing the <command>su</command>:</para> - - <screen>&prompt.user; <prompt>su</prompt> -<prompt>Password:</prompt></screen> - - <para>and take a look at what tokens we have:</para> - - <screen>&prompt.root; klist -Ticket file: /tmp/tkt_root_245 -Principal: jane.root@GRONDAR.ZA - - Issued Expires Principal -May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA</screen> - </sect2> - - <sect2> - <title>Using other commands</title> - - <para>In an earlier example, we created a principal called - <literal>jane</literal> with an instance <literal>root</literal>. - This was based on a user with the same name as the principal, and this - is a Kerberos default; that a - <literal><principal>.<instance></literal> of the form - <literal><username>.</literal><literal>root</literal> will allow - that <literal><username></literal> to <command>su</command> to - root if the necessary entries are in the <filename>.klogin</filename> - file in <username>root</username>'s home directory:</para> - - <screen>&prompt.root; <userinput>cat /root/.klogin</userinput> -jane.root@GRONDAR.ZA</screen> - - <para>Likewise, if a user has in their own home directory lines of the - form:</para> - - <screen>&prompt.user; <userinput>cat ~/.klogin</userinput> -jane@GRONDAR.ZA -jack@GRONDAR.ZA</screen> - - <para>This allows anyone in the <filename>GRONDAR.ZA</filename> realm - who has authenticated themselves to <username>jane</username> or - <username>jack</username> (via <command>kinit</command>, see above) - access to <command>rlogin</command> to <username>jane</username>'s - account or files on this system (<hostid>grunt</hostid>) via - <command>rlogin</command>, <command>rsh</command> or - <command>rcp</command>.</para> - - <para>For example, Jane now logs into another system, using - Kerberos:</para> - - <screen>&prompt.user; <userinput>kinit</userinput> -MIT Project Athena (grunt.grondar.za) -<prompt>Password:</prompt> -%prompt.user; <userinput>rlogin grunt</userinput> -Last login: Mon May 1 21:14:47 from grumble -Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. - -FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen> - - <para>Or Jack logs into Jane's account on the same machine (Jane having - set up the <filename>.klogin</filename> file as above, and the person - in charge of Kerberos having set up principal - <emphasis>jack</emphasis> with a null instance:</para> - - <screen>&prompt.user; <userinput>kinit</userinput> -&prompt.user; <userinput>rlogin grunt -l jane</userinput> -MIT Project Athena (grunt.grondar.za) -<prompt>Password:</prompt> -Last login: Mon May 1 21:16:55 from grumble -Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. -FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen> - </sect2> - </sect1> - - <sect1 id="firewalls"> - <title>Firewalls</title> - - <para><emphasis>Contributed by &a.gpalmer; and Alex Nash.</emphasis></para> - - <para>Firewalls are an area of increasing interest for people who are - connected to the Internet, and are even finding applications on private - networks to provide enhanced security. This section will hopefully - explain what firewalls are, how to use them, and how to use the - facilities provided in the FreeBSD kernel to implement them.</para> - - <note> - <para>People often think that having a firewall between your - internal network and the <quote>Big Bad Internet</quote> will solve all - your security problems. It may help, but a poorly setup firewall - system is more of a security risk than not having one at all. A - firewall can add another layer of security to your systems, but it - cannot stop a really determined cracker from penetrating your internal - network. If you let internal security lapse because you believe your - firewall to be impenetrable, you have just made the crackers job that - much easier.</para> - </note> - - <sect2> - <title>What is a firewall?</title> - - <para>There are currently two distinct types of firewalls in common use - on the Internet today. The first type is more properly called a - <emphasis>packet filtering router</emphasis>, where the kernel on a - multi-homed machine chooses whether to forward or block packets based - on a set of rules. The second type, known as a <emphasis>proxy - server</emphasis>, relies on daemons to provide authentication and to - forward packets, possibly on a multi-homed machine which has kernel - packet forwarding disabled.</para> - - <para>Sometimes sites combine the two types of firewalls, so that only a - certain machine (known as a <emphasis>bastion host</emphasis>) is - allowed to send packets through a packet filtering router onto an - internal network. Proxy services are run on the bastion host, which - are generally more secure than normal authentication - mechanisms.</para> - - <para>FreeBSD comes with a kernel packet filter (known as - <application>IPFW</application>), which is what the rest of this - section will concentrate on. Proxy servers can be built on FreeBSD - from third party software, but there is such a variety of proxy - servers available that it would be impossible to cover them in this - document.</para> - - <sect3 id="firewalls-packet-filters"> - <title>Packet filtering routers</title> - - <para>A router is a machine which forwards packets between two or more - 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 within it that defaults to - forwarding all packets. To enable the filters, you need to define a - set of rules for the filtering code so it can decide if the - packet should be allowed to pass or not.</para> - - <para>To decide whether a packet should be passed on, the code looks - 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 the first match counts, as the rules are searched in order. - Hence, the list of rules can be referred to as a <quote>rule - chain</quote>.</para> - - <para>The packet matching criteria varies depending on the software - used, but typically you can specify rules which depend on the source - IP address of the packet, the destination IP address, the source - port number, the destination port number (for protocols which - support ports), or even the packet type (UDP, TCP, ICMP, - etc).</para> - </sect3> - - <sect3 id="firewalls-proxy-servers"> - <title>Proxy servers</title> - - <para>Proxy servers are machines which have had the normal system - daemons (telnetd, ftpd, etc) replaced with special servers. These - servers are called <emphasis>proxy servers</emphasis> as they - normally only allow onward connections to be made. This enables you - to run (for example) a proxy telnet server on your firewall host, - and people can telnet in to your firewall from the outside, go - through some authentication mechanism, and then gain access to the - internal network (alternatively, proxy servers can be used for - signals coming from the internal network and heading out).</para> - - <para>Proxy servers are normally more secure than normal servers, and - often have a wider variety of authentication mechanisms available, - including <quote>one-shot</quote> password systems so that even if - someone manages to discover what password you used, they will not be - able to use it to gain access to your systems as the password - instantly expires. As they do not actually give users access to the - host machine, it becomes a lot more difficult for someone to install - backdoors around your security system.</para> - - <para>Proxy servers often have ways of restricting access further, so - that only certain hosts can gain access to the servers, and often - they can be set up so that you can limit which users can talk to - which destination machine. Again, what facilities are available - depends largely on what proxy software you choose.</para> - </sect3> - </sect2> - - <sect2> - <title>What does IPFW allow me to do?</title> - - <para><application>IPFW</application>, the software supplied with - FreeBSD, is a packet filtering and accounting system which resides in - the kernel, and has a user-land control utility, - &man.ipfw.8;. Together, they allow you to define and query the - rules currently used by the kernel in its routing decisions.</para> - - <para>There are two related parts to <application>IPFW</application>. - The firewall section allows you to perform packet filtering. There is - also an IP accounting section which allows you to track usage of your - router, based on similar rules to the firewall section. This allows - you to see (for example) how much traffic your router is getting from - a certain machine, or how much WWW (World Wide Web) traffic it is - forwarding.</para> - - <para>As a result of the way that <application>IPFW</application> is - designed, you can use <application>IPFW</application> on non-router - machines to perform packet filtering on incoming and outgoing - connections. This is a special case of the more general use of - <application>IPFW</application>, and the same commands and techniques - should be used in this situation.</para> - </sect2> - - <sect2> - <title>Enabling IPFW on FreeBSD</title> - - <para>As the main part of the <application>IPFW</application> system - lives in the kernel, you will need to add one or more options to your - kernel configuration file, depending on what facilities you want, and - recompile your kernel. See <link linkend="kernelconfig">reconfiguring - the kernel</link> for more details on how to recompile your - kernel.</para> - - <para>There are currently three kernel configuration options relevant to - IPFW:</para> - - <variablelist> - <varlistentry> - <term><literal>options IPFIREWALL</literal></term> - - <listitem> - <para>Compiles into the kernel the code for packet - filtering.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE</literal></term> - - <listitem> - <para>Enables code to allow logging of packets through - &man.syslogd.8;. Without this option, even if you specify - that packets should be logged in the filter rules, nothing will - happen.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE_LIMIT=10</literal></term> - - <listitem> - <para>Limits the number of packets logged through - &man.syslogd.8; on a per entry basis. You may wish to use - this option in hostile environments in which you want to log - firewall activity, but do not want to be open to a denial of - service attack via syslog flooding.</para> - - <para>When a chain entry reaches the packet limit specified, - logging is turned off for that particular entry. To resume - logging, you will need to reset the associated counter using the - &man.ipfw.8; utility:</para> - - <screen>&prompt.root; <userinput>ipfw zero 4500</userinput></screen> - <para>Where 4500 is the chain entry you wish to continue - logging.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Previous versions of FreeBSD contained an - <literal>IPFIREWALL_ACCT</literal> option. This is now obsolete as - the firewall code automatically includes accounting - facilities.</para> - </sect2> - - <sect2> - <title>Configuring IPFW</title> - - <para>The configuration of the <application>IPFW</application> software - is done through the &man.ipfw.8; utility. The syntax for this - command looks quite complicated, but it is relatively simple once you - understand its structure.</para> - - <para>There are currently four different command categories used by the - utility: addition/deletion, listing, flushing, and clearing. - Addition/deletion is used to build the rules that control how packets - are accepted, rejected, and logged. Listing is used to examine the - contents of your rule set (otherwise known as the chain) and packet - counters (accounting). Flushing is used to remove all entries from - the chain. Clearing is used to zero out one or more accounting - entries.</para> - - <sect3> - <title>Altering the IPFW rules</title> - - <para>The syntax for this form of the command is: - <cmdsynopsis> - <command>ipfw</command> - <arg>-N</arg> - <arg choice="plain">command</arg> - <arg>index</arg> - <arg choice="plain">action</arg> - <arg>log</arg> - <arg choice="plain">protocol</arg> - <arg choice="plain">addresses</arg> - <arg>options</arg> - </cmdsynopsis></para> - - <para>There is one valid flag when using this form of the - command:</para> - - <variablelist> - <varlistentry> - <term>-N</term> - - <listitem> - <para>Resolve addresses and service names in output.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <emphasis>command</emphasis> given can be shortened to the - shortest unique form. The valid <emphasis>commands</emphasis> - are:</para> - - <variablelist> - <varlistentry> - <term>add</term> - - <listitem> - <para>Add an entry to the firewall/accounting rule list</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>delete</term> - - <listitem> - <para>Delete an entry from the firewall/accounting rule - list</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Previous versions of <application>IPFW</application> used - separate firewall and accounting entries. The present version - provides packet accounting with each firewall entry.</para> - - <para>If an <emphasis>index</emphasis> value is supplied, it used to - place the entry at a specific point in the chain. Otherwise, the - entry is placed at the end of the chain at an index 100 greater than - the last chain entry (this does not include the default policy, rule - 65535, deny).</para> - - <para>The <literal>log</literal> option causes matching rules to be - output to the system console if the kernel was compiled with - <literal>IPFIREWALL_VERBOSE</literal>.</para> - - <para>Valid <emphasis>actions</emphasis> are:</para> - - <variablelist> - <varlistentry> - <term>reject</term> - - <listitem> - <para>Drop the packet, and send an ICMP host or port unreachable - (as appropriate) packet to the source.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>allow</term> - - <listitem> - <para>Pass the packet on as normal. (aliases: - <literal>pass</literal> and - <literal>accept</literal>)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>deny</term> - - <listitem> - <para>Drop the packet. The source is not notified via an - ICMP message (thus it appears that the packet never - arrived at the destination).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>count</term> - - <listitem> - <para>Update packet counters but do not allow/deny the packet - based on this rule. The search continues with the next chain - entry.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Each <emphasis>action</emphasis> will be recognized by the - shortest unambiguous prefix.</para> - - <para>The <emphasis>protocols</emphasis> which can be specified - are:</para> - - <variablelist> - <varlistentry> - <term>all</term> - - <listitem> - <para>Matches any IP packet</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>icmp</term> - - <listitem> - <para>Matches ICMP packets</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tcp</term> - - <listitem> - <para>Matches TCP packets</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>udp</term> - - <listitem> - <para>Matches UDP packets</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <emphasis>address</emphasis> specification is:</para> - - <cmdsynopsis> - <arg choice="plain">from</arg> - <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg> - <arg choice="plain">to</arg> - <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg> - <arg>via <replaceable>interface</replaceable></arg> - </cmdsynopsis> - - <para>You can only specify <replaceable>port</replaceable> in - conjunction with <emphasis>protocols</emphasis> which support ports - (UDP and TCP).</para> - - <para>The <option>via</option> is optional and may specify the IP - address or domain name of a local IP interface, or an interface name - (e.g. <devicename>ed0</devicename>) to match only packets coming - through this interface. Interface unit numbers can be specified - with an optional wildcard. For example, <literal>ppp*</literal> - would match all kernel PPP interfaces.</para> - - <para>The syntax used to specify an - <replaceable>address/mask</replaceable> is: - - <screen><replaceable>address</replaceable></screen> - - or - - <screen><replaceable>address</replaceable>/<replaceable>mask-bits</replaceable></screen> - - or - - <screen><replaceable>address</replaceable>:<replaceable>mask-pattern</replaceable></screen> - </para> - - <para>A valid hostname may be specified in place of the IP address. - <option><replaceable>mask-bits</replaceable></option> is a decimal - number representing how many bits in the address mask should be set. - e.g. specifying <literal>192.216.222.1/24</literal> will create a - mask which will allow any address in a class C subnet (in this case, - 192.216.222) to be matched. - <option><replaceable>mask-pattern</replaceable></option> is an IP - address which will be logically AND'ed with the address given. The - keyword <literal>any</literal> may be used to specify <quote>any IP - address</quote>.</para> - - <para>The port numbers to be blocked are specified as: - - <cmdsynopsis> - <arg choice="plain"><replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>…</arg></arg></arg></arg> - </cmdsynopsis> - - to specify either a single port or a list of ports, or - - <cmdsynopsis> - <arg choice="plain"><replaceable>port</replaceable>-<replaceable>port</replaceable></arg> - </cmdsynopsis> - - to specify a range of ports. You may also combine a single range - with a list, but the range must always be specified first.</para> - - <para>The <emphasis>options</emphasis> available are:</para> - - <variablelist> - <varlistentry> - <term>frag</term> - - <listitem> - <para>Matches if the packet is not the first fragment of the - datagram.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>in</term> - - <listitem> - <para>Matches if the packet is on the way in.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>out</term> - - <listitem> - <para>Matches if the packet is on the way out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ipoptions <replaceable>spec</replaceable></term> - - <listitem> - <para>Matches if the IP header contains the comma separated list - of options specified in <replaceable>spec</replaceable>. The - supported list of IP options are: <literal>ssrr</literal> - (strict source route), <literal>lsrr</literal> (loose source - route), <literal>rr</literal> (record packet route), and - <literal>ts</literal> (time stamp). The absence of a - particular option may be denoted with a leading - <literal>!</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>established</term> - - <listitem> - <para>Matches if the packet is part of an already established - TCP connection (i.e. it has the RST or ACK bits set). You can - optimize the performance of the firewall by placing - <emphasis>established</emphasis> rules early in the - chain.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>setup</term> - - <listitem> - <para>Matches if the packet is an attempt to establish a TCP - connection (the SYN bit set is set but the ACK bit is - not).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>tcpflags <replaceable>flags</replaceable></term> - - <listitem> - <para>Matches if the TCP header contains the comma separated - list of <replaceable>flags</replaceable>. The supported flags - are <literal>fin</literal>, <literal>syn</literal>, - <literal>rst</literal>, <literal>psh</literal>, - <literal>ack</literal>, and <literal>urg</literal>. The - absence of a particular flag may be indicated by a leading - <literal>!</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>icmptypes <replaceable>types</replaceable></term> - - <listitem> - <para>Matches if the ICMP type is present in the list - <replaceable>types</replaceable>. The list may be specified - as any combination of ranges and/or individual types separated - by commas. Commonly used ICMP types are: <literal>0</literal> - echo reply (ping reply), <literal>3</literal> destination - unreachable, <literal>5</literal> redirect, - <literal>8</literal> echo request (ping request), and - <literal>11</literal> time exceeded (used to indicate TTL - expiration as with &man.traceroute.8;).</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>Listing the IPFW rules</title> - - <para>The syntax for this form of the command is: - <cmdsynopsis> - <command>ipfw</command> - <arg>-a</arg> - <arg>-t</arg> - <arg>-N</arg> - <arg choice="plain">l</arg> - </cmdsynopsis></para> - - <para>There are three valid flags when using this form of the - command:</para> - - <variablelist> - <varlistentry> - <term>-a</term> - - <listitem> - <para>While listing, show counter values. This option is the - only way to see accounting counters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-t</term> - - <listitem> - <para>Display the last match times for each chain entry. The - time listing is incompatible with the input syntax used by the - &man.ipfw.8; utility.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>-N</term> - - <listitem> - <para>Attempt to resolve given addresses and service - names.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>Flushing the IPFW rules</title> - - <para>The syntax for flushing the chain is: - <cmdsynopsis> - <command>ipfw</command> - <arg choice="plain">flush</arg> - </cmdsynopsis></para> - - <para>This causes all entries in the firewall chain to be removed - except the fixed default policy enforced by the kernel (index - 65535). Use caution when flushing rules, the default deny policy - will leave your system cut off from the network until allow entries - are added to the chain.</para> - </sect3> - - <sect3> - <title>Clearing the IPFW packet counters</title> - - <para>The syntax for clearing one or more packet counters is: - <cmdsynopsis> - <command>ipfw</command> - <arg choice="plain">zero</arg> - <arg choice="opt"><replaceable>index</replaceable></arg> - </cmdsynopsis></para> - - <para>When used without an <replaceable>index</replaceable> argument, - all packet counters are cleared. If an - <replaceable>index</replaceable> is supplied, the clearing operation - only affects a specific chain entry.</para> - </sect3> - </sect2> - - <sect2> - <title>Example commands for ipfw</title> - - <para>This command will deny all packets from the host <hostid - role="fqdn">evil.crackers.org</hostid> to the telnet port of the - host <hostid role="fqdn">nice.people.org</hostid>:</para> - - <screen>&prompt.root <userinput>ipfw add deny tcp from evil.crackers.org to nice.people.org 23</userinput></screen> - - <para>The next example denies and logs any TCP traffic from the entire - <hostid role="domainname">crackers.org</hostid> network (a class C) to - the <hostid role="fqdn">nice.people.org</hostid> machine (any - port).</para> - - <screen>&prompt.root; <userinput>ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org</userinput></screen> - - <para>If you do not want people sending X sessions to your internal - network (a subnet of a class C), the following command will do the - necessary filtering:</para> - - <screen>&prompt.root; <userinput>ipfw add deny tcp from any to my.org/28 6000 setup</userinput></screen> - - <para>To see the accounting records: - - <screen>&prompt.root; <userinput>ipfw -a list</userinput></screen> - - or in the short form - - <screen>&prompt.root; <userinput>ipfw -a l</userinput></screen> - </para> - - <para>You can also see the last time a chain entry was matched - with:</para> - - <screen>&prompt.root; <userinput>ipfw -at l</userinput></screen> - </sect2> - - <sect2> - <title>Building a packet filtering firewall</title> - - <note> - <para>The following suggestions are just that: suggestions. The - requirements of each firewall are different and I cannot tell you - how to build a firewall to meet your particular requirements.</para> - </note> - - <para>When initially setting up your firewall, unless you have a test - bench setup where you can configure your firewall host in a controlled - environment, I strongly recommend you use the logging version of the - commands and enable logging in the kernel. This will allow you to - quickly identify problem areas and cure them without too much - disruption. Even after the initial setup phase is complete, I - recommend using the logging for `deny' as it allows tracing of - possible attacks and also modification of the firewall rules if your - requirements alter.</para> - - <note> - <para>If you use the logging versions of the <command>accept</command> - command, it can generate <emphasis>large</emphasis> amounts of log - data as one log line will be generated for every packet that passes - through the firewall, so large ftp/http transfers, etc, will really - slow the system down. It also increases the latencies on those - packets as it requires more work to be done by the kernel before the - packet can be passed on. syslogd with also start using up a lot - more processor time as it logs all the extra data to disk, and it - could quite easily fill the partition <filename>/var/log</filename> - is located on.</para> - </note> - - <para>You should enable your firewall from - <filename>/etc/rc.conf.local</filename> or - <filename>/etc/rc.conf</filename>. The associated man page explains - which knobs to fiddle and lists some preset firewall configurations. - If you do not use a preset configuration, <command>ipfw list</command> - will output the current ruleset into a file that you can - pass to <filename>rc.conf</filename>. If you do not use - <filename>/etc/rc.conf.local</filename> or - <filename>/etc/rc.conf</filename> to enable your firewall, - it is important to make sure your firewall is enabled before - any IP interfaces are configured. - </para> - - <para>The next problem is what your firewall should actually - <emphasis>do</emphasis>! This is largely dependent on what access to - your network you want to allow from the outside, and how much access - to the outside world you want to allow from the inside. Some general - rules are:</para> - - <itemizedlist> - <listitem> - <para>Block all incoming access to ports below 1024 for TCP. This is - where most of the security sensitive services are, like finger, - SMTP (mail) and telnet.</para> - </listitem> - - <listitem> - <para>Block <emphasis>all</emphasis> incoming UDP traffic. There - are very few useful services that travel over UDP, and what useful - traffic there is is normally a security threat (e.g. Suns RPC and - NFS protocols). This has its disadvantages also, since UDP is a - connectionless protocol, denying incoming UDP traffic also blocks - the replies to outgoing UDP traffic. This can cause a problem for - people (on the inside) using external archie (prospero) servers. - If you want to allow access to archie, you'll have to allow - packets coming from ports 191 and 1525 to any internal UDP port - through the firewall. ntp is another service you may consider - allowing through, which comes from port 123.</para> - </listitem> - - <listitem> - <para>Block traffic to port 6000 from the outside. Port 6000 is the - port used for access to X11 servers, and can be a security threat - (especially if people are in the habit of doing <command>xhost - +</command> on their workstations). X11 can actually use a - range of ports starting at 6000, the upper limit being how many X - displays you can run on the machine. The upper limit as defined - by RFC 1700 (Assigned Numbers) is 6063.</para> - </listitem> - - <listitem> - <para>Check what ports any internal servers use (e.g. SQL servers, - etc). It is probably a good idea to block those as well, as they - normally fall outside the 1-1024 range specified above.</para> - </listitem> - </itemizedlist> - - <para>Another checklist for firewall configuration is available from - CERT at <ulink - url="ftp://ftp.cert.org/pub/tech_tips/packet_filtering">ftp://ftp.cert.org/pub/tech_tips/packet_filtering</ulink></para> - - <para>As I said above, these are only <emphasis>guidelines</emphasis>. - You will have to decide what filter rules you want to use on your - firewall yourself. I cannot accept ANY responsibility if someone - breaks into your network, even if you follow the advice given - above.</para> - </sect2> - </sect1> - - <sect1 id="openssl"> - <title>OpenSSL</title> - - <para>As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base - system. <ulink url="http://www.openssl.org/">OpenSSL</ulink> - provides a general-purpose cryptography library, as well as the - Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer - Security v1 (TLSv1) network security protocols.</para> - - <para>However, one of the algorithms (specifically IDEA) - included in OpenSSL is protected by patents in the USA and - elsewhere, and is not available for unrestricted use. - IDEA is included in the OpenSSL sources in FreeBSD, but it is not - built by default. If you wish to use it, and you comply with the - license terms, enable the MAKE_IDEA switch in /etc/make.conf and - rebuild your sources using 'make world'.</para> - - <para>Today, the RSA algorithm is free for use in USA and other - countries. In the past it was protected by a patent.</para> - - <sect2> - <title>Source Code Installations</title> - - <para>OpenSSL is part of the <literal>src-crypto</literal> and - <literal>src-secure</literal> cvsup collections. See the <link - linkend="mirrors">Obtaining FreeBSD</link> section for more - information about obtaining and updating FreeBSD source - code.</para> - </sect2> - </sect1> - - <sect1 id="ipsec"> - <title>IPsec</title> - <para><emphasis>Contributed by &a.shin;, 5 March - 2000.</emphasis></para> - - <para>IPsec mechanism provides secure communication either for IP - layer and socket layer communication. This section should - explain how to use them. About IPsec implementation, please - refer <link linkend="ipsec-implementation">section 23.5.4</link>.</para> - - <para>The current IPsec implementation supports both transport mode - and tunnel mode. However, tunnel mode comes with some restrictions. - <ulink url="http://www.kame.net/newsletter/">http://www.kame.net/newsletter/ - </ulink> has more comprehensive examples.</para> - - <para>Please be aware that in order to use this functionality, you - must have the following options compiled into your kernel:</para> - - <programlisting> -options IPSEC #IP security -options IPSEC_ESP #IP security (crypto; define w/IPSEC)</programlisting> - - <sect2> - <title>Transport mode example with IPv4</title> - - <para>Let's setup security association to deploy a secure channel - between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little - complicated example. From HOST A to HOST B, only old AH is used. - From HOST B to HOST A, new AH and new ESP are combined.</para> - - <para>Now we should choose algorithm to be used corresponding to - "AH"/"new AH"/"ESP"/"new ESP". Please refer to the &man.setkey.8; man - page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1 - for new AH, and new-DES-expIV with 8 byte IV for new ESP.</para> - - <para>Key length highly depends on each algorithm. For example, key - length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1, - and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET", - "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively.</para> - - <para>OK, let's assign SPI (Security Parameter Index) for each protocol. - Please note that we need 3 SPIs for this secure channel since three - security headers are produced (one for from HOST A to HOST B, two for - from HOST B to HOST A). Please also note that SPI MUST be greater - than or equal to 256. We choose, 1000, 2000, and 3000, respectively. - </para> - - <screen> - - (1) - HOST A ------> HOST B - - (1)PROTO=AH - ALG=MD5(RFC1826) - KEY=MYSECRETMYSECRET - SPI=1000 - - (2.1) - HOST A <------ HOST B - <------ - (2.2) - - (2.1) - PROTO=AH - ALG=new-HMAC-SHA1(new AH) - KEY=KAMEKAMEKAMEKAMEKAME - SPI=2000 - - (2.2) - PROTO=ESP - ALG=new-DES-expIV(new ESP) - IV length = 8 - KEY=PASSWORD - SPI=3000 - - </screen> - - <para>Now, let's setup security association. Execute &man.setkey.8; - on both HOST A and B:</para> - - <screen> - -&prompt.root; <command>setkey -c</command> -add 10.2.3.4 10.6.7.8 ah-old 1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ; -add 10.6.7.8 10.2.3.4 ah 2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ; -add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ; -^D - - </screen> - - <para>Actually, IPsec communication doesn't process until security policy - entries will be defined. In this case, you must setup each host.</para> - - <screen> - -At A: - -&prompt.root; <command>setkey -c</command> -spdadd 10.2.3.4 10.6.7.8 any -P out ipsec - ah/transport/10.2.3.4-10.6.7.8/require ; -^D - -At B: - -&prompt.root; <command>setkey -c</command> -spdadd 10.6.7.8 10.2.3.4 any -P out ipsec - esp/transport/10.6.7.8-10.2.3.4/require ; -spdadd 10.6.7.8 10.2.3.4 any -P out ipsec - ah/transport/10.6.7.8-10.2.3.4/require ; -^D - - - HOST A --------------------------------------> HOST E - 10.2.3.4 10.6.7.8 - | | - ========== old AH keyed-md5 ==========> - - <========= new AH hmac-sha1 =========== - <========= new ESP des-cbc ============ - - </screen> - </sect2> - - <sect2> - <title>Transport mode example with IPv6</title> - - <para>Another example using IPv6.</para> - - <para>ESP transport mode is recommended for TCP port number 110 between - Host-A and Host-B.</para> - - <screen> - - ============ ESP ============ - | | - Host-A Host-B - fec0::10 -------------------- fec0::11 - - </screen> - - <para>Encryption algorithm is blowfish-cbc whose key is "kamekame", and - authentication algorithm is hmac-sha1 whose key is "this is the test - key". Configuration at Host-A:</para> - - <screen> - - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec - esp/transport/fec0::10-fec0::11/use ; - spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec - esp/transport/fec0::11-fec0::10/use ; - add fec0::10 fec0::11 esp 0x10001 - -m transport - -E blowfish-cbc "kamekame" - -A hmac-sha1 "this is the test key" ; - add fec0::11 fec0::10 esp 0x10002 - -m transport - -E blowfish-cbc "kamekame" - -A hmac-sha1 "this is the test key" ; - EOF - - </screen> - - <para>and at Host-B:</para> - - <screen> - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec - esp/transport/fec0::11-fec0::10/use ; - spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec - esp/transport/fec0::10-fec0::11/use ; - add fec0::10 fec0::11 esp 0x10001 -m transport - -E blowfish-cbc "kamekame" - -A hmac-sha1 "this is the test key" ; - add fec0::11 fec0::10 esp 0x10002 -m transport - -E blowfish-cbc "kamekame" - -A hmac-sha1 "this is the test key" ; - EOF - - </screen> - - <para>Note the direction of SP.</para> - </sect2> - - <sect2> - <title>Tunnel mode example with IPv4</title> - - <para>Tunnel mode between two security gateways</para> - - <para>Security protocol is old AH tunnel mode, i.e. specified by - RFC1826, with keyed-md5 whose key is "this is the test" as - authentication algorithm.</para> - - <screen> - - ======= AH ======= - | | - Network-A Gateway-A Gateway-B Network-B - 10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24 - - </screen> - - <para>Configuration at Gateway-A:</para> - - <screen> - - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec - ah/tunnel/172.16.0.1-172.16.0.2/require ; - spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec - ah/tunnel/172.16.0.2-172.16.0.1/require ; - add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any - -A keyed-md5 "this is the test" ; - add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any - -A keyed-md5 "this is the test" ; - - EOF - - </screen> - - <para>If port number field is omitted such above then "[any]" is - employed. `-m' specifies the mode of SA to be used. "-m any" means - wild-card of mode of security protocol. You can use this SA for both - tunnel and transport mode.</para> - - <para>and at Gateway-B:</para> - - <screen> - - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec - ah/tunnel/172.16.0.2-172.16.0.1/require ; - spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec - ah/tunnel/172.16.0.1-172.16.0.2/require ; - add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any - -A keyed-md5 "this is the test" ; - add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any - -A keyed-md5 "this is the test" ; - - EOF - - </screen> - - <para>Making SA bundle between two security gateways</para> - - <para>AH transport mode and ESP tunnel mode is required between - Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first, - and AH transport mode is next.</para> - - <screen> - - ========== AH ========= - | ======= ESP ===== | - | | | | - Network-A Gateway-A Gateway-B Network-B - fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64 - - </screen> - </sect2> - - <sect2> - <title>Tunnel mode example with IPv6</title> - - <para>Encryption algorithm is 3des-cbc, and authentication algorithm - for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5. - Configuration at Gateway-A:</para> - - <screen> - - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec - esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require - ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ; - spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec - esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require - ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ; - add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel - -E 3des-cbc "kamekame12341234kame1234" - -A hmac-sha1 "this is the test key" ; - add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport - -A hmac-md5 "this is the test" ; - add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel - -E 3des-cbc "kamekame12341234kame1234" - -A hmac-sha1 "this is the test key" ; - add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport - -A hmac-md5 "this is the test" ; - - EOF - - </screen> - - <para>Making SAs with the different end</para> - - <para>ESP tunnel mode is required between Host-A and Gateway-A. Encryption - algorithm is cast128-cbc, and authentication algorithm for ESP is - hmac-sha1. ESP transport mode is recommended between Host-A and Host-B. - Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is - hmac-md5.</para> - - <screen> - - ================== ESP ================= - | ======= ESP ======= | - | | | | - Host-A Gateway-A Host-B - fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2 - - </screen> - - <para>Configuration at Host-A:</para> - - <screen> - - &prompt.root; <command>setkey -c</command> <<<filename>EOF</filename> - spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec - esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use - esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ; - spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec - esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use - esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ; - add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001 - -m transport - -E cast128-cbc "12341234" - -A hmac-sha1 "this is the test key" ; - add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002 - -E rc5-cbc "kamekame" - -A hmac-md5 "this is the test" ; - add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003 - -m transport - -E cast128-cbc "12341234" - -A hmac-sha1 "this is the test key" ; - add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004 - -E rc5-cbc "kamekame" - -A hmac-md5 "this is the test" ; - - EOF - - </screen> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml deleted file mode 100644 index 3cb7be6640..0000000000 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml +++ /dev/null @@ -1,2742 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml,v 1.18 2000/06/08 01:56:19 jim Exp $ ---> - -<chapter id="serialcomms"> - <title>Serial Communications</title> - - <sect1> - <title>Synopsis</title> - - <para>UNIX has always had support for serial communications. In fact, - the very first UNIX machines relied on serial lines for user input - and output. Things have changed a lot from the days when the average - <quote>terminal</quote> consisted of a 10-character-per-second serial - printer and a keyboard. This chapter will cover some of the ways in - which FreeBSD uses serial communications.</para> - </sect1> - - <sect1 id="serial"> - <title>Serial Basics</title> - - <para><emphasis>Assembled from FAQ.</emphasis></para> - - <para>This section should give you some general information about serial - ports. If you do not find what you want here, check into the Terminal - and Dial-up sections of the handbook.</para> - - <para>The <filename>ttyd<replaceable>X</replaceable></filename> (or - <filename>cuaa<replaceable>X</replaceable></filename>) device is the - regular device you will want to open for your applications. When a - process opens the device, it will have a default set of terminal I/O - settings. You can see these settings with the command</para> - - <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen> - - <para>When you change the settings to this device, the settings are in - effect until the device is closed. When it is reopened, it goes back to - the default set. To make changes to the default set, you can open and - adjust the settings of the <quote>initial state</quote> device. For - example, to turn on <acronym>CLOCAL</acronym> mode, 8 bits, and - <emphasis>XON/XOFF</emphasis> flow control by default for ttyd5, - do:</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen> - - <para>A good place to do this is in <filename>/etc/rc.serial</filename>. - Now, an application will have these settings by default when it opens - <filename>ttyd5</filename>. It can still change these settings to its - liking, though.</para> - - <para>You can also prevent certain settings from being changed by an - application by making adjustments to the <quote>lock state</quote> - device. For example, to lock the speed of <filename>ttyd5</filename> to - 57600 bps, do</para> - - <screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen> - - <para>Now, an application that opens <filename>ttyd5</filename> and tries - to change the speed of the port will be stuck with 57600 bps.</para> - - <para>Naturally, you should make the initial state and lock state devices - writable only by <username>root</username>. The - <filename>MAKEDEV</filename> script does <emphasis>not</emphasis> do - this when it creates the device entries.</para> - </sect1> - - <sect1 id="term"> - <title>Terminals</title> - - <para><emphasis>Contributed by &a.kelly; 28 July 1996</emphasis></para> - - <para>Terminals provide a convenient and low-cost way to access the power - of your FreeBSD system when you are not at the computer's console or on - a connected network. This section describes how to use terminals with - FreeBSD.</para> - - <sect2 id="term-uses"> - <title>Uses and Types of Terminals</title> - - <para>The original Unix systems did not have consoles. Instead, people - logged in and ran programs through terminals that were connected to - the computer's serial ports. It is quite similar to using a modem and - some terminal software to dial into a remote system to do text-only - work.</para> - - <para>Today's PCs have consoles capable of high quality graphics, but - the ability to establish a login session on a serial port still exists - in nearly every Unix-style operating system today; FreeBSD is no - exception. By using a terminal attached to a unused serial port, you - can log in and run any text program that you would normally run on the - console or in an <command>xterm</command> window in the X Window - System.</para> - - <para>For the business user, you can attach many terminals to a FreeBSD - system and place them on your employees' desktops. For a home user, a - spare computer such as an older IBM PC or a Macintosh can be a - terminal wired into a more powerful computer running FreeBSD. You can - turn what might otherwise be a single-user computer into a powerful - multiple user system.</para> - - <para>For FreeBSD, there are three kinds of terminals:</para> - - <itemizedlist> - <listitem> - <para><link linkend="term-dumb">Dumb terminals</link></para> - </listitem> - - <listitem> - <para><link linkend="term-pcs">PCs acting as terminals</link></para> - </listitem> - - <listitem> - <para><link linkend="term-x">X terminals</link></para> - </listitem> - </itemizedlist> - - <para>The remaining subsections describe each kind.</para> - - <sect3 id="term-dumb"> - <title>Dumb Terminals</title> - - <para>Dumb terminals are specialized pieces of hardware that let you - connect to computers over serial lines. They are called - <quote>dumb</quote> because they have only enough computational power - to display, send, and receive text. You cannot run any programs on - them. It is the computer to which you connect them that has all the - power to run text editors, compilers, email, games, and so - forth.</para> - - <para>There are hundreds of kinds of dumb terminals made by many - manufacturers, including Digital Equipment Corporation's VT-100 and - Wyse's WY-75. Just about any kind will work with FreeBSD. Some - high-end terminals can even display graphics, but only certain - software packages can take advantage of these advanced - features.</para> - - <para>Dumb terminals are popular in work environments where workers do - not need access to graphic applications such as those provided by - the X Window System.</para> - </sect3> - - <sect3 id="term-pcs"> - <title>PCs Acting As Terminals</title> - - <para>If a <link linkend="term-dumb">dumb terminal</link> has just - enough ability to display, send, and receive text, then certainly - any spare personal computer can be a dumb terminal. All you need is - the proper cable and some <emphasis>terminal emulation</emphasis> - software to run on the computer.</para> - - <para>Such a configuration is popular in homes. For example, if your - spouse is busy working on your FreeBSD system's console, you can do - some text-only work at the same time from a less powerful personal - computer hooked up as a terminal to the FreeBSD system.</para> - </sect3> - - <sect3 id="term-x"> - <title>X Terminals</title> - - <para>X terminals are the most sophisticated kind of terminal - available. Instead of connecting to a serial port, they usually - connect to a network like Ethernet. Instead of being relegated to - text-only applications, they can display any X application.</para> - - <para>We introduce X terminals just for the sake of completeness. - However, this chapter does <emphasis>not</emphasis> cover setup, - configuration, or use of X terminals.</para> - </sect3> - </sect2> - - <sect2 id="term-cables-ports"> - <title>Cables and Ports</title> - - <para>To connect a terminal to your FreeBSD system, you need the right - kind of cable and a serial port to which to connect it. This section - tells you what to do. If you are already familiar with your terminal - and the cable it requires, skip to <link - linkend="term-config">Configuration</link>.</para> - - <sect3 id="term-cables"> - <title>Cables</title> - - <para>Because terminals use serial ports, you need to use - serial—also known as RS-232C—cables to connect the - terminal to the FreeBSD system.</para> - - <para>There are a couple of kinds of serial cables. Which one - you'll use depends on the terminal you want to connect:</para> - - <itemizedlist> - <listitem> - <para>If you are connecting a personal computer to act as a - terminal, use a <link linkend="term-null">null-modem</link> - cable. A null-modem cable connects two computers or terminals - together.</para> - </listitem> - - <listitem> - <para>If you have an actual terminal, your best source of - information on what cable to use is the documentation that - accompanied the terminal. If you do not have the documentation, - then try a <link linkend="term-null">null-modem</link> cable. - If that does not work, then try a <link - linkend="term-std">standard</link> cable.</para> - </listitem> - </itemizedlist> - - <para>Also, the serial port on <emphasis>both</emphasis> the terminal - and your FreeBSD system must have connectors that will fit the cable - you are using.</para> - - <sect4 id="term-null"> - <title>Null-modem cables</title> - - <para>A null-modem cable passes some signals straight through, like - <quote>signal ground,</quote> but switches other signals. For - example, the <quote>send data</quote> pin on one end goes to the - <quote>receive data</quote> pin on the other end.</para> - - <para>If you like making your own cables, here is a table showing a - recommended way to construct a null-modem cable for use with - terminals. This table shows the RS-232C signal names and the pin - numbers on a DB-25 connector.</para> - - <informaltable frame="none"> - <tgroup cols="5"> - <thead> - <row> - <entry>Signal</entry> - <entry>Pin #</entry> - <entry></entry> - <entry>Pin #</entry> - <entry>Signal</entry> - </row> - </thead> - - <tbody> - <row> - <entry>TxD</entry> - <entry>2</entry> - <entry>connects to</entry> - <entry>3</entry> - <entry>RxD</entry> - </row> - - <row> - <entry>RxD</entry> - <entry>3</entry> - <entry>connects to</entry> - <entry>2</entry> - <entry>TxD</entry> - </row> - - <row> - <entry>DTR</entry> - <entry>20</entry> - <entry>connects to</entry> - <entry>6</entry> - <entry>DSR</entry> - </row> - - <row> - <entry>DSR</entry> - <entry>6</entry> - <entry>connects to</entry> - <entry>20</entry> - <entry>DTR</entry> - </row> - - <row> - <entry>SG</entry> - <entry>7</entry> - <entry>connects to</entry> - <entry>7</entry> - <entry>SG</entry> - </row> - - <row> - <entry>DCD</entry> - <entry>8</entry> - <entry>connects to</entry> - <entry>4</entry> - <entry>RTS</entry> - </row> - - <row> - <entry>RTS</entry> - <entry>4</entry> - <entry></entry> - <entry>5</entry> - <entry>CTS</entry> - </row> - - <row> - <entry>CTS</entry> - <entry>5</entry> - <entry>connects to</entry> - <entry>8</entry> - <entry>DCD</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>For DCD to RTS, connect pins 4 to 5 internally in the - connector hood, and then to pin 8 in the remote - hood.</para> - </note> - </sect4> - - <sect4 id="term-std"> - <title>Standard RS-232C Cables</title> - - <para>A standard serial cable passes all the RS-232C signals - straight-through. That is, the <quote>send data</quote> pin on one - end of the cable goes to the <quote>send data</quote> pin on the - other end. This is the type of cable to connect a modem to your - FreeBSD system, and the type of cable needed for some - terminals.</para> - </sect4> - </sect3> - - <sect3 id="term-ports"> - <title>Ports</title> - - <para>Serial ports are the devices through which data is transferred - between the FreeBSD host computer and the terminal. This section - describes the kinds of ports that exist and how they are addressed - in FreeBSD.</para> - - <sect4 id="term-portkinds"> - <title>Kinds of Ports</title> - - <para>Several kinds of serial ports exist. Before you purchase or - construct a cable, you need to make sure it will fit the ports on - your terminal and on the FreeBSD system.</para> - - <para>Most terminals will have DB25 ports. Personal computers, - including PCs running FreeBSD, will have DB25 or DB9 ports. If you - have a multiport serial card for your PC, you may have RJ-12 or - RJ-45 ports.</para> - - <para>See the documentation that accompanied the hardware for - specifications on the kind of port in use. A visual inspection of - the port often works, too.</para> - </sect4> - - <sect4 id="term-portnames"> - <title>Port Names</title> - - <para>In FreeBSD, you access each serial port through an entry in - the <filename>/dev</filename> directory. There are two different - kinds of entries:</para> - - <itemizedlist> - <listitem> - <para>Call-in ports are named - <filename>/dev/ttyd<replaceable>X</replaceable></filename> - where <replaceable>X</replaceable> is the port number, - starting from zero. Generally, you use the call-in port for - terminals. Call-in ports require that the serial line assert - the data carrier detect (DCD) signal to work.</para> - </listitem> - - <listitem> - <para>Call-out ports are named - <filename>/dev/cuaa<replaceable>X</replaceable></filename>. - You usually do not use the call-out port for terminals, just - for modems. You may use the call-out port if the serial cable - or the terminal does not support the carrier detect - signal.</para> - </listitem> - </itemizedlist> - - <para>See the &man.sio.4; manual page for more information.</para> - - <para>If you have connected a terminal to the first serial port - (<devicename>COM1</devicename> in DOS parlance), then you want to - use <filename>/dev/ttyd0</filename> to refer to the terminal. If - it is on the second serial port (also known as - <devicename>COM2</devicename>), it is - <filename>/dev/ttyd1</filename>, and so forth.</para> - - <para>Note that you may have to configure your kernel to support - each serial port, especially if you have a multiport serial card. - See <link linkend="kernelconfig">Configuring the FreeBSD - Kernel</link> for more information.</para> - </sect4> - </sect3> - </sect2> - - <sect2 id="term-config"> - <title>Configuration</title> - - <para>This section describes what you need to configure on your FreeBSD - system to enable a login session on a terminal. It assumes you have - already configured your kernel to support the serial port to which the - terminal is connected—and that you have connected it.</para> - - <para>In a nutshell, you need to tell the <command>init</command> - process, which is responsible for process control and initialization, - to start a <command>getty</command> process, which is responsible for - reading a login name and starting the <command>login</command> - program.</para> - - <para>To do so, you have to edit the <filename>/etc/ttys</filename> - file. First, use the <command>su</command> command to become root. - Then, make the following changes to - <filename>/etc/ttys</filename>:</para> - - <procedure> - <step> - <para>Add an line to <filename>/etc/ttys</filename> for the entry in - the <filename>/dev</filename> directory for the serial port if it - is not already there.</para> - </step> - - <step> - <para>Specify that <filename>/usr/libexec/getty</filename> be run on - the port, and specify the appropriate - <replaceable>getty</replaceable> type from the - <filename>/etc/gettytab</filename> file.</para> - </step> - - <step> - <para>Specify the default terminal type.</para> - </step> - - <step> - <para>Set the port to <quote>on.</quote></para> - </step> - - <step> - <para>Specify whether the port should be - <quote>secure.</quote></para> - </step> - - <step> - <para>Force <command>init</command> to reread the - <filename>/etc/ttys</filename> file.</para> - </step> - </procedure> - - <para>As an optional step, you may wish to create a custom - <replaceable>getty</replaceable> type for use in step 2 by making an - entry in <filename>/etc/gettytab</filename>. This document does - not explain how to do so; you are encouraged to see the - &man.gettytab.5; and the &man.getty.8; manual pages for more - information.</para> - - <para>The remaining sections detail how to do these steps. We will use - a running example throughout these sections to illustrate what we need - to do. In our example, we will connect two terminals to the system: a - Wyse-50 and a old 286 IBM PC running Procomm terminal software - emulating a VT-100 terminal. We connect the Wyse to the second serial - port and the 286 to the sixth serial port (a port on a multiport - serial card).</para> - - <para>For more information on the <filename>/etc/ttys</filename> - file, see the &man.ttys.5; manual page.</para> - - <sect3 id="term-etcttys"> - <title>Adding an Entry to <filename>/etc/ttys</filename></title> - - <para>First, you need to add an entry to the - <filename>/etc/ttys</filename> file, unless one is already - there.</para> - - <para>The <filename>/etc/ttys</filename> file lists all of the ports - on your FreeBSD system where you want to allow logins. For example, - the first virtual console <filename>ttyv0</filename> has an entry in - this file. You can log in on the console using this entry. This - file contains entries for the other virtual consoles, serial ports, - and pseudo-ttys. For a hardwired terminal, just list the serial - port's <filename>/dev</filename> entry without the - <filename>/dev</filename> part.</para> - - <para>When you installed your FreeBSD system, the - <filename>/etc/ttys</filename> file included entries for the first - four serial ports: <filename>ttyd0</filename> through - <filename>ttyd3</filename>. If you are attaching a terminal on one - of those ports, you do not need to add an entry.</para> - - <para>In our example, we attached a Wyse-50 to the second serial port, - <filename>ttyd1</filename>, which is already in the file. We need - to add an entry for the 286 PC connected to the sixth serial port. - Here is an excerpt of the <filename>/etc/ttys</filename> file after - we add the new entry:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.9600" unknown off secure -ttyd5</programlisting> - </sect3> - - <sect3 id="term-getty"> - <title>Specifying the <replaceable>getty</replaceable> Type</title> - - <para>Next, we need to specify what program will be run to handle the - logins on a terminal. For FreeBSD, the standard program to do that - is <filename>/usr/libexec/getty</filename>. It is what provides the - <prompt>login:</prompt> prompt.</para> - - <para>The program <command>getty</command> takes one (optional) - parameter on its command line, the <replaceable>getty</replaceable> - type. A <replaceable>getty</replaceable> type tells about - characteristics on the terminal line, like bps rate and parity. The - <command>getty</command> program reads these characteristics from - the file <filename>/etc/gettytab</filename>.</para> - - <para>The file <filename>/etc/gettytab</filename> contains lots of - entries for terminal lines both old and new. In almost all cases, - the entries that start with the text <literal>std</literal> will - work for hardwired terminals. These entries ignore parity. There is - a <literal>std</literal> entry for each bps rate from 110 to 115200. - Of course, you can add your own entries to this file. The manual - page &man.gettytab.5; provides more - information.</para> - - <para>When setting the <replaceable>getty</replaceable> type in the - <filename>/etc/ttys</filename> file, make sure that the - communications settings on the terminal match.</para> - - <para>For our example, the Wyse-50 uses no parity and connects at - 38400 bps. The 286 PC uses no parity and connects at 19200 bps. - Here is the <filename>/etc/ttys</filename> file so far (showing just - the two terminals in which we are interested):</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" unknown off secure -ttyd5 "/usr/libexec/getty std.19200"</programlisting> - - <para>Note that the second field—where we specify what program - to run—appears in quotes. This is important, otherwise the - type argument to <command>getty</command> might be interpreted as - the next field.</para> - </sect3> - - <sect3 id="term-deftermtype"> - <title>Specifying the Default Terminal Type</title> - - <para>The third field in the <filename>/etc/ttys</filename> file lists - the default terminal type for the port. For dial-up ports, you - typically put <literal>unknown</literal> or - <literal>dialup</literal> in this field because users may dial up - with practically any kind of terminal or software. For hardwired - terminals, the terminal type does not change, so you can put a real - terminal type in this field.</para> - - <para>Users will usually use the <command>tset</command> program in - their <filename>.login</filename> or <filename>.profile</filename> - files to check the terminal type and prompt for one if necessary. - By setting a terminal type in the <filename>/etc/ttys</filename> - file, users can forego such prompting.</para> - - <para>To find out what terminal types FreeBSD supports, see the - file <filename>/usr/share/misc/termcap</filename>. It lists - about 600 terminal types. You can add more if you wish. See - the &man.termcap.5; manual page for information.</para> - - <para>In our example, the Wyse-50 is a Wyse-50 type of terminal - (although it can emulate others, we will leave it in Wyse-50 mode). - The 286 PC is running Procomm which will be set to emulate a VT-100. - Here are the pertinent yet unfinished entries from the - <filename>/etc/ttys</filename> file:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 off secure -ttyd5 "/usr/libexec/getty std.19200" vt100</programlisting> - </sect3> - - <sect3 id="term-enable"> - <title>Enabling the Port</title> - - <para>The next field in <filename>/etc/ttys</filename>, the fourth - field, tells whether to enable the port. Putting - <literal>on</literal> here will have the <command>init</command> - process start the program in the second field, - <command>getty</command>, which will prompt for a login. If you put - <literal>off</literal> in the fourth field, there will be no - <command>getty</command>, and hence no logins on the port.</para> - - <para>So, naturally, you want an <literal>on</literal> in this field. - Here again is the <filename>/etc/ttys</filename> file. We have - turned each port <literal>on</literal>.</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 on secure -ttyd5 "/usr/libexec/getty std.19200" vt100 on</programlisting> - </sect3> - - <sect3 id="term-secure"> - <title>Specifying Secure Ports</title> - - <para>We have arrived at the last field (well, almost: there is an - optional <literal>window</literal> specifier, but we will ignore - that). The last field tells whether the port is secure.</para> - - <para>What does <quote>secure</quote> mean?</para> - - <para>It means that the root account (or any account with a user ID of - 0) may login on the port. Insecure ports do not allow root to - login.</para> - - <para>How do you use secure and insecure ports?</para> - - <para>By marking a port as insecure, the terminal to which it is - connected will not allow root to login. People who know the root - password to your FreeBSD system will first have to login using a - regular user account. To gain superuser privileges, they will then - have to use the <command>su</command> command.</para> - - <para>Because of this, you will have two records to help track down - possible compromises of root privileges: both the - <command>login</command> and the <command>su</command> command make - records in the system log (and logins are also recorded in the - <filename>wtmp</filename> file).</para> - - <para>By marking a port as secure, the terminal will allow root in. - People who know the root password will just login as root. You will - not have the potentially useful login and <command>su</command> - command records.</para> - - <para>Which should you use?</para> - - <para>Just use <quote>insecure.</quote> Use <quote>insecure</quote> - <emphasis>even</emphasis> for terminals <emphasis>not</emphasis> in - public user areas or behind locked doors. It is quite easy to login - and use <command>su</command> if you need superuser - privileges.</para> - - <para>Here finally are the completed entries in the - <filename>/etc/ttys</filename> file, with comments added to describe - where the terminals are:</para> - - <programlisting> -ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen -ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom</programlisting> - </sect3> - - <sect3 id="term-hup"> - <title>Force <command>init</command> to Reread - <filename>/etc/ttys</filename></title> - - <para>When you boot FreeBSD, the first process, - <command>init</command>, will read the - <filename>/etc/ttys</filename> file and start the programs listed - for each enabled port to prompt for logins.</para> - - <para>After you edit <filename>/etc/ttys</filename>, you do not want - to have to reboot your system to get <command>init</command> to see - the changes. So, <command>init</command> will reread - <filename>/etc/ttys</filename> if it receives a SIGHUP (hangup) - signal.</para> - - <para>So, after you have saved your changes to - <filename>/etc/ttys</filename>, send <literal>SIGHUP</literal> to - <command>init</command> by typing:</para> - - <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> - - <para>(The <command>init</command> process <emphasis>always</emphasis> - has process ID 1.)</para> - - <para>If everything is set up correctly, all cables are in place, and - the terminals are powered up, you should see login prompts. Your - terminals are ready for their first logins!</para> - </sect3> - </sect2> - - <sect2 id="term-debug"> - <title>Debugging your connection</title> - - <para>Even with the most meticulous attention to detail, something could - still go wrong while setting up a terminal. Here is a list of - symptoms and some suggested fixes.</para> - - <variablelist> - <varlistentry> - <term>No login prompt appears</term> - - <listitem> - <para>Make sure the terminal is plugged in and powered up. If it - is a personal computer acting as a terminal, make sure it is - running terminal emulation software on the correct serial - port.</para> - - <para>Make sure the cable is connected firmly to both the terminal - and the FreeBSD computer. Make sure it is the right kind of - cable.</para> - - <para>Make sure the terminal and FreeBSD agree on the bps rate and - parity settings. If you have a video display terminal, make - sure the contrast and brightness controls are turned up. If it - is a printing terminal, make sure paper and ink are in good - supply.</para> - - <para>Make sure that a <command>getty</command> process is running - and serving the terminal. Type <screen>&prompt.root; - <userinput>ps -axww|grep getty</userinput></screen> to get a - list of running <command>getty</command> processes. You should - see an entry for the terminal. For example, the display - - <screen>22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1</screen> - - shows that a <command>getty</command> is running on the second - serial port <literal>ttyd1</literal> and is using the - <literal>std.38400</literal> entry in - <filename>/etc/gettytab</filename>.</para> - - <para>If no <command>getty</command> process is running, make sure - you have enabled the port in <filename>/etc/ttys</filename>. - Make sure you have run <command>kill -HUP 1</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Garbage appears instead of a login prompt</term> - - <listitem> - <para>Make sure the terminal and FreeBSD agree on the bps rate and - parity settings. Check the getty processes to make sure the - correct <replaceable>getty</replaceable> type is in use. If - not, edit <filename>/etc/ttys</filename> and run <command>kill - -HUP 1</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Characters appear doubled; the password appears when - typed</term> - - <listitem> - <para>Switch the terminal (or the terminal emulation software) - from <quote>half duplex</quote> or <quote>local echo</quote> to - <quote>full duplex.</quote></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="dialup"> - <title>Dial-in Service</title> - - <para><emphasis>Contributed by &a.ghelmer;.</emphasis></para> - - <para>This document provides suggestions for configuring a FreeBSD system - to handle dial-up modems. This document is written based on the author's - experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience - with dial-up modems on other UNIX-like operating systems); however, this - document may not answer all of your questions or provide examples - specific enough to your environment. The author cannot be responsible if - you damage your system or lose data due to attempting to follow the - suggestions here.</para> - - <sect2 id="dialup-prereqs"> - <title>Prerequisites</title> - - <para>To begin with, the author assumes you have some basic knowledge of - FreeBSD. You need to have FreeBSD installed, know how to edit files - in a UNIX-like environment, and how to look up manual pages on the - system. As discussed below, you will need certain versions of - FreeBSD, and knowledge of some terminology & modem and - cabling.</para> - - <sect3> - <title>FreeBSD Version</title> - - <para>First, it is assumed that you are using FreeBSD version 1.1 or - higher (including versions 2.x). FreeBSD version 1.0 included two - different serial drivers, which complicates the situation. Also, - the serial device driver (<devicename>sio</devicename>) has improved - in every release of FreeBSD, so more recent versions of FreeBSD are - assumed to have better and more efficient drivers than earlier - versions.</para> - </sect3> - - <sect3> - <title>Terminology</title> - - <para>A quick rundown of terminology:</para> - - <variablelist> - <varlistentry> - <term>bps</term> - - <listitem> - <para>Bits per Second — the rate at which data is - transmitted</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DTE</term> - - <listitem> - <para>Data Terminal Equipment — for example, your - computer</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DCE</term> - - <listitem> - <para>Data Communications Equipment — your modem</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RS-232</term> - - <listitem> - <para>EIA standard for serial communications via hardware</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If you need more information about these terms and data - communications in general, the author remembers reading that - <emphasis>The RS-232 Bible</emphasis> (anybody have an ISBN?) is a - good reference.</para> - - <para>When talking about communications data rates, the author does - not use the term <quote>baud</quote>. Baud refers to the number of - electrical state transitions that may be made in a period of time, - while <quote>bps</quote> (bits per second) is the - <quote>correct</quote> term to use (at least it does not seem to - bother the curmudgeons quite a much).</para> - </sect3> - - <sect3> - <title>External v.s. Internal Modems</title> - - <para>External modems seem to be more convenient for dial-up, because - external modems often can be semi-permanently configured via - parameters stored in non-volatile RAM and they usually provide - lighted indicators that display the state of important RS-232 - signals. Blinking lights impress visitors, but lights are also very - useful to see whether a modem is operating properly.</para> - - <para>Internal modems usually lack non-volatile RAM, so their - configuration may be limited only to setting DIP switches. If your - internal modem has any signal indicator lights, it is probably - difficult to view the lights when the system's cover is in - place.</para> - </sect3> - - <sect3> - <title>Modems and Cables</title> - - <para>A background knowledge of these items is assumed</para> - - <itemizedlist> - <listitem> - <para>You know how to connect your modem to your computer so that - the two can communicate (unless you have an internal modem, - which does not need such a cable)</para> - </listitem> - - <listitem> - <para>You are familiar with your modem's command set, or know - where to look up needed commands</para> - </listitem> - - <listitem> - <para>You know how to configure your modem (probably via a - terminal communications program) so you can set the non-volatile - RAM parameters</para> - </listitem> - </itemizedlist> - - <para>The first, connecting your modem, is usually simple — most - straight-through serial cables work without any problems. You need - to have a cable with appropriate connectors (DB-25 or DB-9, male or - female) on each end, and the cable must be a DCE-to-DTE cable with - these signals wired:</para> - - <itemizedlist> - <listitem> - <para>Transmitted Data (<acronym>SD</acronym>)</para> - </listitem> - - <listitem> - <para>Received Data (<acronym>RD</acronym>)</para> - </listitem> - - <listitem> - <para>Request to Send (<acronym>RTS</acronym>)</para> - </listitem> - - <listitem> - <para>Clear to Send (<acronym>CTS</acronym>)</para> - </listitem> - - <listitem> - <para>Data Set Ready (<acronym>DSR</acronym>)</para> - </listitem> - - <listitem> - <para>Data Terminal Ready (<acronym>DTR</acronym>)</para> - </listitem> - - <listitem> - <para>Carrier Detect (<acronym>CD</acronym>)</para> - </listitem> - - <listitem> - <para>Signal Ground (<acronym>SG</acronym>)</para> - </listitem> - </itemizedlist> - - <para>FreeBSD needs the <acronym>RTS</acronym> and - <acronym>CTS</acronym> signals for flow-control at speeds above - 2400bps, the <acronym>CD</acronym> signal to detect when a call has - been answered or the line has been hung up, and the - <acronym>DTR</acronym> signal to reset the modem after a session is - complete. Some cables are wired without all of the needed signals, - so if you have problems, such as a login session not going away when - the line hangs up, you may have a problem with your cable.</para> - - <para>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 to use as a reference for your own modem's - commands.</para> - - <para>Lastly, you will need to know how to setup your modem so that it - will work well with FreeBSD. Like other UNIX-like operating - systems, FreeBSD uses the hardware signals to find out when a call - has been answered or a line has been hung up and to hangup and reset - the modem after a call. FreeBSD avoids sending commands to the - modem or watching for status reports from the modem. If you are - familiar with connecting modems to PC-based bulletin board systems, - this may seem awkward.</para> - </sect3> - - <sect3> - <title>Serial Interface Considerations</title> - - <para>FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based - EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and - 16450 devices have single-character buffers. The 16550 device - provides a 16-character buffer, which allows for better system - performance. (Bugs in plain 16550's prevent the use of the - 16-character buffer, so use 16550A's if possible). Because - single-character-buffer devices require more work by the operating - system than the 16-character-buffer devices, 16550A-based serial - interface cards are much preferred. If the system has many active - serial ports or will have a heavy load, 16550A-based cards are - better for low-error-rate communications.</para> - </sect3> - </sect2> - - <sect2> - <title>Quick Overview</title> - - <para>Here is the process that FreeBSD follows to accept dial-up logins. - A <command>getty</command> process, spawned by - <command>init</command>, patiently waits to open the assigned serial - port (<filename>/dev/ttyd0</filename>, for our example). The command - <command>ps ax</command> might show this:</para> - - <screen> 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0</screen> - - <para>When a user dials the modem's line and the modems connect, the - <acronym>CD</acronym> line is asserted by the modem. The kernel - notices that carrier has been detected and completes - <command>getty</command>'s open of the port. <command>getty</command> - sends a <prompt>login:</prompt> prompt at the specified initial line - speed. <command>getty</command> watches to see if legitimate - characters are received, and, in a typical configuration, if it finds - junk (probably due to the modem's connection speed being different - than <command>getty</command>'s speed), <command>getty</command> tries - adjusting the line speeds until it receives reasonable - characters.</para> - - <para>We hope <command>getty</command> finds the correct speed and the - user sees a <prompt>login:</prompt> prompt. After the user enters - his/her login name, <command>getty</command> executes - <filename>/usr/bin/login</filename>, which completes the login by - asking for the user's password and then starting the user's - shell.</para> - - <para>Let's dive into the configuration...</para> - </sect2> - - <sect2> - <title>Kernel Configuration</title> - - <para>FreeBSD kernels typically come prepared to search for four serial - ports, known in the PC-DOS world as <devicename>COM1:</devicename>, - <devicename>COM2:</devicename>, <devicename>COM3:</devicename>, and - <devicename>COM4:</devicename>. FreeBSD can presently also handle - <quote>dumb</quote> multiport serial interface cards, such as the Boca - Board 1008 and 2016 (please see the manual page &man.sio.4; for kernel - configuration information if you have a multiport serial card). The - default kernel only looks for the standard COM ports, though.</para> - - <para>To see if your kernel recognizes any of your serial ports, watch - for messages while the kernel is booting, or use the - <command>/sbin/dmesg</command> command to replay the kernel's boot - messages. In particular, look for messages that start with the - characters <literal>sio</literal>. Hint: to view just the messages - that have the word <literal>sio</literal>, use the command:</para> - - <screen>&prompt.root; <userinput>/sbin/dmesg | grep 'sio'</userinput></screen> - - <para>For example, on a system with four serial ports, these are the - serial-port specific kernel boot messages:</para> - - <screen>sio0 at 0x3f8-0x3ff irq 4 on isa -sio0: type 16550A -sio1 at 0x2f8-0x2ff irq 3 on isa -sio1: type 16550A -sio2 at 0x3e8-0x3ef irq 5 on isa -sio2: type 16550A -sio3 at 0x2e8-0x2ef irq 9 on isa -sio3: type 16550A</screen> - - <para>If your kernel does not recognize all of your serial ports, you - will probably need to configure a custom FreeBSD kernel for your - system.</para> - - <para>Please see the BSD System Manager's Manual chapter on - <quote>Building Berkeley Kernels with Config</quote> [the source for - which is in <filename>/usr/src/share/doc/smm</filename>] and - <quote>FreeBSD Configuration Options</quote> [in - <filename>/sys/conf/options</filename> and in - <filename>/sys/<replaceable>arch</replaceable>/conf/options.<replaceable>arch</replaceable></filename>, - with <emphasis>arch</emphasis> for example being - <filename>i386</filename>] for more information on configuring and - building kernels. You may have to unpack the kernel source - distribution if have not installed the system sources already - (<filename>srcdist/srcsys.??</filename> in FreeBSD 1.1, - <filename>srcdist/sys.??</filename> in FreeBSD 1.1.5.1, or the entire - source distribution in FreeBSD 2.0) to be able to configure and build - kernels.</para> - - <para>Create a kernel configuration file for your system (if you have - not already) by <command>cd</command>ing to - <filename>/sys/i386/conf</filename>. Then, if you are creating a new - custom configuration file, copy the file - <filename>GENERICAH</filename> (or <filename>GENERICBT</filename>, if - you have a BusTek SCSI controller on FreeBSD 1.x) to - <filename>YOURSYS</filename>, where <filename>YOURSYS</filename> is - the name of your system, but in upper-case letters. Edit the file, - and change the device lines:</para> - - <programlisting> -device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr -device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr -device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr -device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr</programlisting> - - <para>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 &man.sio.4; man page for complete - information on how to write configuration lines for multiport boards. - Be careful if you are using a configuration file that was previously - used for a different version of FreeBSD because the device flags have - changed between versions.</para> - - <note> - <para><literal>port "IO_COM1"</literal> is a substitution for - <literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is - <literal>0x2f8</literal>, <literal>IO_COM3</literal> is - <literal>0x3e8</literal>, and <literal>IO_COM4</literal> is - <literal>0x2e8</literal>, 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 - <emphasis>cannot</emphasis> 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).</para> - </note> - - <para>When you are finished adjusting the kernel configuration file, use - the program <command>config</command> as documented in <quote>Building - Berkeley Kernels with Config</quote> and the - &man.config.8; manual page to prepare a kernel building directory, - then build, install, and test the new kernel.</para> - </sect2> - - <sect2> - <title>Device Special Files</title> - - <para>Most devices in the kernel are accessed through <quote>device - special files</quote>, which are located in the - <filename>/dev</filename> directory. The <devicename>sio</devicename> - devices are accessed through the - <filename>/dev/ttyd<replaceable>?</replaceable></filename> (dial-in) - and <filename>/dev/cua0<replaceable>?</replaceable></filename> - (call-out) devices. On FreeBSD version 1.1.5 and higher, there are - also initialization devices - (<filename>/dev/ttyid<replaceable>?</replaceable></filename> and - <filename>/dev/cuai0<replaceable>?</replaceable></filename>) and - locking devices - (<filename>/dev/ttyld<replaceable>?</replaceable></filename> and - <filename>/dev/cual0<replaceable>?</replaceable></filename>). The - initialization devices are used to initialize communications port - parameters each time a port is opened, such as - <literal>crtscts</literal> for modems which use - <literal>CTS/RTS</literal> signaling for flow control. The locking - devices are used to lock flags on ports to prevent users or programs - changing certain parameters; see the manual pages &man.termios.4;, - &man.sio.4;, and &man.stty.1; for - information on the terminal settings, locking & initializing - devices, and setting terminal options, respectively.</para> - - <sect3> - <title>Making Device Special Files</title> - - <para>A shell script called <command>MAKEDEV</command> in the - <filename>/dev</filename> directory manages the device special - files. (The manual page for &man.MAKEDEV.8; on FreeBSD 1.1.5 is - fairly bogus in its discussion of <acronym>COM</acronym> ports, so - ignore it.) To use <command>MAKEDEV</command> to make dial-up device - special files for <devicename>COM1:</devicename> (port 0), - <command>cd</command> to <filename>/dev</filename> and issue the - command <command>MAKEDEV ttyd0</command>. Likewise, to make dial-up - device special files for <devicename>COM2:</devicename> (port 1), - use <command>MAKEDEV ttyd1</command>.</para> - - <para><command>MAKEDEV</command> not only creates the - <filename>/dev/ttyd<replaceable>?</replaceable></filename> device - special files, but also creates the - <filename>/dev/cua0<replaceable>?</replaceable></filename> (and all - of the initializing and locking special files under FreeBSD 1.1.5 - and up) and removes the hardwired terminal special file - <filename>/dev/tty0<replaceable>?</replaceable></filename>, if it - exists.</para> - - <para>After making new device special files, be sure to check the - permissions on the files (especially the - <filename>/dev/cua*</filename> files) to make sure that only users - who should have access to those device special files can read & - write on them — you probably do not want to allow your average - user to use your modems to dial-out. The default permissions on the - <filename>/dev/cua*</filename> files should be sufficient:</para> - - <screen>crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01 -crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01 -crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01</screen> - - <para>These permissions allow the user <username>uucp</username> and - users in the group <username>dialer</username> to use the call-out - devices.</para> - </sect3> - </sect2> - - <sect2> - <title>Configuration Files</title> - - <para>There are three system configuration files in the - <filename>/etc</filename> directory that you will probably need to - edit to allow dial-up access to your FreeBSD system. The first, - <filename>/etc/gettytab</filename>, contains configuration information - for the <filename>/usr/libexec/getty</filename> daemon. Second, - <filename>/etc/ttys</filename> holds information that tells - <filename>/sbin/init</filename> what <filename>tty</filename> devices - should have <command>getty</command> processes running on them. - Lastly, you can place port initialization commands in the - <filename>/etc/rc.serial</filename> script if you have FreeBSD 1.1.5.1 - or higher; otherwise, you can initialize ports in the - <filename>/etc/rc.local</filename> script.</para> - - <para>There are two schools of thought regarding dial-up modems on UNIX. - One group likes to configure their modems and system so that no matter - at what speed a remote user dials in, the local computer-to-modem - RS-232 interface runs at a locked speed. The benefit of this - configuration is that the remote user always sees a system login - prompt immediately. The downside is that the system 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.</para> - - <para>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 - <command>getty</command> does not understand any particular modem's - connection speed reporting, <command>getty</command> gives a - <prompt>login:</prompt> message at an initial speed and watches the - characters that come back in response. If the user sees junk, it is - assumed that they know they should press the - <literal><Enter></literal> key until they see a recognizable - prompt. If the data rates do not match, <command>getty</command> sees - anything the user types as <quote>junk</quote>, tries going to the next - speed and gives the <prompt>login:</prompt> 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 does not look as clean as the former - <quote>locked-speed</quote> method, but a user on a low-speed - connection should receive better interactive response from full-screen - programs.</para> - - <para>The author will try to give balanced configuration information, - but is biased towards having the modem's data rate follow the - connection rate.</para> - - <sect3> - <title><filename>/etc/gettytab</filename></title> - - <para><filename>/etc/gettytab</filename> is a &man.termcap.5;-style - file of configuration information for &man.getty.8;. Please see the - &man.gettytab.5; manual page for complete information on the - format of the file and the list of capabilities.</para> - - <sect4> - <title>Locked-Speed Config</title> - - <para>If you are locking your modem's data communications rate at a - particular speed, you probably will not need to make any changes - to <filename>/etc/gettytab</filename>.</para> - </sect4> - - <sect4> - <title>Matching-Speed Config</title> - - <para>You will need to setup an entry in - <filename>/etc/gettytab</filename> to give - <command>getty</command> information about the speeds you wish to - use for your modem. If you have a 2400 bps modem, you can - probably use the existing <literal>D2400</literal> entry. This - entry already exists in the FreeBSD 1.1.5.1 - <filename>gettytab</filename> file, so you do not need to add it - unless it is missing under your version of FreeBSD:</para> - - <programlisting> -# -# Fast dialup terminals, 2400/1200/300 rotary (can start either way) -# -D2400|d2400|Fast-Dial-2400:\ - :nx=D1200:tc=2400-baud: -3|D1200|Fast-Dial-1200:\ - :nx=D300:tc=1200-baud: -5|D300|Fast-Dial-300:\ - :nx=D2400:tc=300-baud:</programlisting> - - <para>If you have a higher speed modem, you will probably need to - add an entry in <filename>/etc/gettytab</filename>; here is an - entry you could use for a 14.4 Kbps modem with a top interface - speed of 19.2 Kbps:</para> - - <programlisting> -# -# Additions for a V.32bis Modem -# -um|V300|High Speed Modem at 300,8-bit:\ - :nx=V19200:tc=std.300: -un|V1200|High Speed Modem at 1200,8-bit:\ - :nx=V300:tc=std.1200: -uo|V2400|High Speed Modem at 2400,8-bit:\ - :nx=V1200:tc=std.2400: -up|V9600|High Speed Modem at 9600,8-bit:\ - :nx=V2400:tc=std.9600: -uq|V19200|High Speed Modem at 19200,8-bit:\ - :nx=V9600:tc=std.19200:</programlisting> - - <para>On FreeBSD 1.1.5 and later, this will result in 8-bit, no - parity connections. Under FreeBSD 1.1, add - <literal>:np:</literal> parameters to the - <literal>std.<replaceable>xxx</replaceable></literal> entries at - the top of the file for 8 bits, no parity; otherwise, the default - is 7 bits, even parity.</para> - - <para>The example above starts the communications rate at 19.2 Kbps - (for a V.32bis connection), then cycles through 9600 bps (for - V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. - Communications rate cycling is implemented with the - <literal>nx=</literal> (<quote>next table</quote>) capability. - Each of the lines uses a <literal>tc=</literal> (<quote>table - continuation</quote>) entry to pick up the rest of the - <quote>standard</quote> settings for a particular data rate.</para> - - <para>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 is an example of - a <filename>gettytab</filename> entry starting a 57.6 Kbps:</para> - - <programlisting> -# -# Additions for a V.32bis or V.34 Modem -# Starting at 57.6 Kbps -# -vm|VH300|Very High Speed Modem at 300,8-bit:\ - :nx=VH57600:tc=std.300: -vn|VH1200|Very High Speed Modem at 1200,8-bit:\ - :nx=VH300:tc=std.1200: -vo|VH2400|Very High Speed Modem at 2400,8-bit:\ - :nx=VH1200:tc=std.2400: -vp|VH9600|Very High Speed Modem at 9600,8-bit:\ - :nx=VH2400:tc=std.9600: -vq|VH57600|Very High Speed Modem at 57600,8-bit:\ - :nx=VH9600:tc=std.57600:</programlisting> - - <para>If you have a slow CPU or a heavily loaded system and you do - not have 16550A-based serial ports, you may receive sio - <quote>silo</quote> errors at 57.6 Kbps.</para> - </sect4> - </sect3> - - <sect3 id="dialup-ttys"> - <title><filename>/etc/ttys</filename></title> - - <para><filename>/etc/ttys</filename> is the list of - <filename>ttys</filename> for <command>init</command> to monitor. - <filename>/etc/ttys</filename> also provides security information to - <command>login</command> (user <username>root</username> may only - login on ttys marked <literal>secure</literal>). See the manual - page for - &man.ttys.5; for more information.</para> - - <para>You will need to either modify existing lines in - <filename>/etc/ttys</filename> or add new lines to make - <command>init</command> run <command>getty</command> processes - automatically on your new dial-up ports. The general format of the - line will be the same, whether you are using a locked-speed or - matching-speed configuration:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty xxx" dialup on</programlisting> - - <para>The first item in the above line is the device special file for - this entry — <literal>ttyd0</literal> means - <filename>/dev/ttyd0</filename> is the file that this - <command>getty</command> will be watching. The second item, - <literal>"/usr/libexec/getty - <replaceable>xxx</replaceable>"</literal> - (<replaceable>xxx</replaceable> will be replaced by the initial - <filename>gettytab</filename> capability) is the process - <command>init</command> will run on the device. The third item, - <literal>dialup</literal>, is the default terminal type. The fourth - parameter, <literal>on</literal>, indicates to - <command>init</command> that the line is operational. There can be - a fifth parameter, <literal>secure</literal>, but it should only be - used for terminals which are physically secure (such as the system - console).</para> - - <para>The default terminal type (<literal>dialup</literal> in the - example above) may depend on local preferences. - <literal>dialup</literal> is the traditional default terminal type - on dial-up lines so that users may customize their login scripts to - notice when the terminal is <literal>dialup</literal> and - automatically adjust their terminal type. However, the author finds - it easier at his site to specify <literal>vt102</literal> as the - default terminal type, since the users just use VT102 emulation on - their remote systems.</para> - - <para>After you have made changes to <filename>/etc/ttys</filename>, - you may send the <command>init</command> process a - <acronym>HUP</acronym> signal to re-read the file. You can use the - command <screen>&prompt.root; <userinput>kill -1 - 1</userinput></screen> to send the signal. If this is your - first time setting up the system, though, you may want to wait until - your modem(s) are properly configured and connected before signaling - <command>init</command>.</para> - - <sect4> - <title>Locked-Speed Config</title> - - <para>For a locked-speed configuration, your - <filename>ttys</filename> entry needs to have a fixed-speed entry - provided to <command>getty</command>. For a modem whose port - speed is locked at 19.2 Kbps, the <filename>ttys</filename> entry - might look like this:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty std.19200" dialup on</programlisting> - - <para>If your modem is locked at a different data rate, substitute - the appropriate name for the - <literal>std.<replaceable>speed</replaceable></literal> entry for - <literal>std.19200</literal> from - <filename>/etc/gettytab</filename> for your modem's data - rate.</para> - </sect4> - - <sect4> - <title>Matching-Speed Config</title> - - <para>In a matching-speed configuration, your - <filename>ttys</filename> entry needs to reference the appropriate - beginning <quote>auto-baud</quote> (sic) entry in - <filename>/etc/gettytab</filename>. For example, if you added the - above suggested entry for a matching-speed modem that starts at - 19.2 Kbps (the <filename>gettytab</filename> entry containing the - <literal>V19200</literal> starting point), your - <filename>ttys</filename> entry might look like this:</para> - - <programlisting> -ttyd0 "/usr/libexec/getty V19200" dialup on</programlisting> - </sect4> - </sect3> - - <sect3> - <title><filename>/etc/rc.serial</filename> or - <filename>/etc/rc.local</filename></title> - - <para>High-speed modems, like V.32, V.32bis, and V.34 modems, need to - use hardware (<filename>RTS/CTS</filename>) flow control. You can - add <command>stty</command> commands to - <filename>/etc/rc.serial</filename> on FreeBSD 1.1.5.1 and up, or - <filename>/etc/rc.local</filename> on FreeBSD 1.1, to set the - hardware flow control flag in the FreeBSD kernel for the modem - ports.</para> - - <para>For example, on a sample FreeBSD 1.1.5.1 system, - <filename>/etc/rc.serial</filename> reads:</para> - - <programlisting> -#!/bin/sh -# -# Serial port initial configuration - -stty -f /dev/ttyid1 crtscts -stty -f /dev/cuai01 crtscts</programlisting> - - <para>This sets the <literal>termios</literal> flag - <literal>crtscts</literal> on serial port #1's - (<devicename>COM2:</devicename>) dial-in and dial-out initialization - devices.</para> - - <para>On an old FreeBSD 1.1 system, these entries were added to - <filename>/etc/rc.local</filename> to set the - <literal>crtscts</literal> flag on the devices:</para> - - <programlisting> -# Set serial ports to use RTS/CTS flow control -stty -f /dev/ttyd0 crtscts -stty -f /dev/ttyd1 crtscts -stty -f /dev/ttyd2 crtscts -stty -f /dev/ttyd3 crtscts</programlisting> - - <para>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 are not cleared by a miscreant.</para> - </sect3> - </sect2> - - <sect2> - <title>Modem Settings</title> - - <para>If you have a modem whose parameters may be permanently set in - non-volatile RAM, you will need to use a terminal program (such as - Telix under PC-DOS or <command>tip</command> under FreeBSD) to set the - parameters. Connect to the modem using the same communications speed - as the initial speed <command>getty</command> will use and configure - the modem's non-volatile RAM to match these requirements:</para> - - <itemizedlist> - <listitem> - <para><acronym>CD</acronym> asserted when connected</para> - </listitem> - - <listitem> - <para><acronym>DTR</acronym> asserted for operation; dropping DTR - hangs up line & resets modem</para> - </listitem> - - <listitem> - <para><acronym>CTS</acronym> transmitted data flow control</para> - </listitem> - - <listitem> - <para>Disable <acronym>XON/XOFF</acronym> flow control</para> - </listitem> - - <listitem> - <para><acronym>RTS</acronym> received data flow control</para> - </listitem> - - <listitem> - <para>Quiet mode (no result codes)</para> - </listitem> - - <listitem> - <para>No command echo</para> - </listitem> - </itemizedlist> - - <para>Please read the documentation for your modem to find out what - commands and/or DIP switch settings you need to give it.</para> - - <para>For example, to set the above parameters on a USRobotics - Sportster 14,400 external modem, one could give these commands to - the modem:</para> - - <programlisting> -ATZ -AT&C1&D2&H1&I0&R2&W</programlisting> - - <para>You might also want to take this opportunity to adjust other - settings in the modem, such as whether it will use V.42bis and/or MNP5 - compression.</para> - - <para>The USR Sportster 14,400 external modem also has some DIP switches - that need to be set; for other modems, perhaps you can use these - settings as an example:</para> - - <itemizedlist> - <listitem> - <para>Switch 1: UP — DTR Normal</para> - </listitem> - - <listitem> - <para>Switch 2: Do not care (Verbal Result Codes/Numeric Result - Codes)</para> - </listitem> - - <listitem> - <para>Switch 3: UP — Suppress Result Codes</para> - </listitem> - - <listitem> - <para>Switch 4: DOWN — No echo, offline commands</para> - </listitem> - - <listitem> - <para>Switch 5: UP — Auto Answer</para> - </listitem> - - <listitem> - <para>Switch 6: UP — Carrier Detect Normal</para> - </listitem> - - <listitem> - <para>Switch 7: UP — Load NVRAM Defaults</para> - </listitem> - - <listitem> - <para>Switch 8: Do not care (Smart Mode/Dumb Mode)</para> - </listitem> - </itemizedlist> - - <para>Result codes should be disabled/suppressed for dial-up modems to - avoid problems that can occur if <command>getty</command> mistakenly - gives a <prompt>login:</prompt> prompt to a modem that is in command - mode and the modem echoes the command or returns a result code. I - have heard this sequence can result in a extended, silly conversation - between <command>getty</command> and the modem.</para> - - <sect3> - <title>Locked-speed Config</title> - - <para>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 to issue the commands:</para> - - <programlisting> -ATZ -AT&B1&W</programlisting> - </sect3> - - <sect3> - <title>Matching-speed Config</title> - - <para>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 the commands, but allow the serial port rate to vary for - non-error-corrected connections:</para> - - <programlisting> -ATZ -AT&B2&W</programlisting> - </sect3> - - <sect3> - <title>Checking the Modem's Configuration</title> - - <para>Most high-speed modems provide commands to view the modem's - current operating parameters in a somewhat human-readable fashion. - On the USR Sportster 14,400 external modems, the command - <command>ATI5</command> displays the settings that are stored in the - non-volatile RAM. To see the true operating parameters of the modem - (as influenced by the USR's DIP switch settings), use the commands - <command>ATZ</command> and then <command>ATI4</command>.</para> - - <para>If you have a different brand of modem, check your modem's - manual to see how to double-check your modem's configuration - parameters.</para> - </sect3> - </sect2> - - <sect2> - <title>Troubleshooting</title> - - <para>Here are a few steps you can follow to check out the dial-up modem - on your system.</para> - - <sect3> - <title>Checking out the FreeBSD system</title> - - <para>Hook up your modem to your FreeBSD system, boot the system, and, - if your modem has status indication lights, watch to see whether the - modem's <acronym>DTR</acronym> indicator lights when the - <prompt>login:</prompt> prompt appears on the system's console - — if it lights up, that should mean that FreeBSD has started a - <command>getty</command> process on the appropriate communications - port and is waiting for the modem to accept a call.</para> - - <para>If the <acronym>DTR</acronym> indicator doesn't light, login to - the FreeBSD system through the console and issue a <command>ps - ax</command> to see if FreeBSD is trying to run a - <command>getty</command> process on the correct port. You should see - a lines like this among the processes displayed:</para> - - <screen> 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 - 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1</screen> - - <para>If you see something different, like this:</para> - - <screen> 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0</screen> - - <para>and the modem has not accepted a call yet, this means that - <command>getty</command> has completed its open on the - communications port. This could indicate a problem with the cabling - or a mis-configured modem, because <command>getty</command> should - not be able to open the communications port until - <acronym>CD</acronym> (carrier detect) has been asserted by the - modem.</para> - - <para>If you do not see any <command>getty</command> processes waiting - to open the desired - <filename>ttyd<replaceable>?</replaceable></filename> port, - double-check your entries in <filename>/etc/ttys</filename> to see - if there are any mistakes there. Also, check the log file - <filename>/var/log/messages</filename> to see if there are any log - messages from <command>init</command> or <command>getty</command> - regarding any problems. If there are any messages, triple-check the - configuration files <filename>/etc/ttys</filename> and - <filename>/etc/gettytab</filename>, as well as the appropriate - device special files <filename>/dev/ttyd?</filename>, for any - mistakes, missing entries, or missing device special files.</para> - </sect3> - - <sect3> - <title>Try Dialing In</title> - - <para>Try dialing into the system; be sure to use 8 bits, no parity, 1 - stop bit on the remote system. If you do not get a prompt right - away, or get garbage, try pressing <literal><Enter></literal> - about once per second. If you still do not see a - <prompt>login:</prompt> prompt after a while, try sending a - <command>BREAK</command>. If you are using a high-speed modem to do - the dialing, try dialing again after locking the dialing modem's - interface speed (via <command>AT&B1</command> on a USR - Sportster, for example).</para> - - <para>If you still cannot get a <prompt>login:</prompt> prompt, check - <filename>/etc/gettytab</filename> again and double-check - that</para> - - <itemizedlist> - <listitem> - <para>The initial capability name specified in - <filename>/etc/ttys</filename> for the line matches a name of a - capability in <filename>/etc/gettytab</filename></para> - </listitem> - - <listitem> - <para>Each <literal>nx=</literal> entry matches another - <filename>gettytab</filename> capability name</para> - </listitem> - - <listitem> - <para>Each <literal>tc=</literal> entry matches another - <filename>gettytab</filename> capability name</para> - </listitem> - </itemizedlist> - - <para>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 - <acronym>DTR</acronym> is asserted. If the modem seems to be - configured correctly, verify that the <acronym>DTR</acronym> line is - asserted by checking the modem's indicator lights (if it has - any).</para> - - <para>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 your problem, and the good - folks on the list will try to help.</para> - </sect3> - </sect2> - - <sect2> - <title>Acknowledgments</title> - - <para>Thanks to these people for comments and advice:</para> - - <variablelist> - <varlistentry> - <term>&a.kelly;</term> - - <listitem> - <para>for a number of good suggestions</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="dialout"> - <title>Dial-out Service</title> - - <para><emphasis>Information integrated from FAQ.</emphasis></para> - - <para>The following are tips to getting your host to be able to connect - over the modem to another computer. This is appropriate for - establishing a terminal session with a remote host.</para> - - <para>This is useful to log onto a BBS.</para> - - <para>This kind of connection can be extremely helpful to get a file on - the Internet if you have problems with PPP. If you need to FTP - something and PPP is broken, use the terminal session to FTP it. Then - use zmodem to transfer it to your machine.</para> - - <sect2> - <title>Why cannot I run <command>tip</command> or - <command>cu</command>?</title> - - <para>On your system, the programs <command>tip</command> and - <command>cu</command> are probably executable only by - <username>uucp</username> and group <username>dialer</username>. You - can use the group <username>dialer</username> to control who has - access to your modem or remote systems. Just add yourself to group - dialer.</para> - - <para>Alternatively, you can let everyone on your system run - <command>tip</command> and <command>cu</command> by typing:</para> - - <screen>&prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen> - - <para>You do not have to run this command for <command>cu</command>, - since <command>cu</command> is just a hard link to - <command>tip</command>.</para> - </sect2> - - <sect2> - <title>My stock Hayes modem is not supported, what can I do?</title> - - <para>Actually, the man page for <command>tip</command> is out of date. - There is a generic Hayes dialer already built in. Just use - <literal>at=hayes</literal> in your <filename>/etc/remote</filename> - file.</para> - - <para>The Hayes driver is not smart enough to recognize some of the - advanced features of newer modems—messages like - <literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or - <literal>CONNECT 115200</literal> will just confuse it. You should - turn those messages off when you use <command>tip</command> (using - <command>ATX0&W</command>).</para> - - <para>Also, the dial timeout for <command>tip</command> is 60 seconds. - Your modem should use something less, or else tip will think there is - a communication problem. Try <command>ATS7=45&W</command>.</para> - - <para>Actually, as shipped <command>tip</command> does not yet support - it fully. The solution is to edit the file - <filename>tipconf.h</filename> in the directory - <filename>/usr/src/usr.bin/tip/tip</filename> Obviously you need the - source distribution to do this.</para> - - <para>Edit the line <literal>#define HAYES 0</literal> to - <literal>#define HAYES 1</literal>. Then <command>make</command> and - <command>make install</command>. Everything works nicely after - that.</para> - </sect2> - - <sect2 id="direct-at"> - <title>How am I expected to enter these AT commands?</title> - - <para>Make what is called a <quote>direct</quote> entry in your - <filename>/etc/remote</filename> file. For example, if your modem is - hooked up to the first serial port, <filename>/dev/cuaa0</filename>, - then put in the following line:</para> - - <programlisting> -cuaa0:dv=/dev/cuaa0:br#19200:pa=none</programlisting> - - <para>Use the highest bps rate your modem supports in the br capability. - Then, type <command>tip cuaa0</command> and you will be connected to - your modem.</para> - - <para>If there is no <filename>/dev/cuaa0</filename> on your system, do - this:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>MAKEDEV cuaa0</userinput></screen> - - <para>Or use cu as root with the following command:</para> - - <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen> - - <para><replaceable>line</replaceable> is the serial port - (e.g.<filename>/dev/cuaa0</filename>) and - <replaceable>speed</replaceable> is the speed - (e.g.<literal>57600</literal>). When you are done entering the AT - commands hit <command>~.</command> to exit.</para> - </sect2> - - <sect2> - <title>The <literal>@</literal> sign for the pn capability does not - work!</title> - - <para>The <literal>@</literal> sign in the phone number capability tells - tip to look in <filename>/etc/phones</filename> for a phone number. - But the <literal>@</literal> sign is also a special character in - capability files like <filename>/etc/remote</filename>. Escape it - with a backslash:</para> - - <programlisting> -pn=\@</programlisting> - </sect2> - - <sect2> - <title>How can I dial a phone number on the command line?</title> - - <para>Put what is called a <quote>generic</quote> entry in your - <filename>/etc/remote</filename> file. For example:</para> - - <programlisting> -tip115200|Dial any phone number at 115200 bps:\ - :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: -tip57600|Dial any phone number at 57600 bps:\ - :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>Then you can things like:</para> - - <screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen> - - <para>If you prefer <command>cu</command> over <command>tip</command>, - use a generic cu entry:</para> - - <programlisting> -cu115200|Use cu to dial any number at 115200bps:\ - :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:</programlisting> - - <para>and type:</para> - - <screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen> - </sect2> - - <sect2> - <title>Do I have to type in the bps rate every time I do that?</title> - - <para>Put in an entry for <literal>tip1200</literal> or - <literal>cu1200</literal>, but go ahead and use whatever bps rate is - appropriate with the br capability. <command>tip</command> thinks a - good default is 1200 bps which is why it looks for a - <literal>tip1200</literal> entry. You do not have to use 1200 bps, - though.</para> - </sect2> - - <sect2> - <title>I access a number of hosts through a terminal server.</title> - - <para>Rather than waiting until you are connected and typing - <command>CONNECT <host></command> each time, use tip's - <literal>cm</literal> capability. For example, these entries in - <filename>/etc/remote</filename>:</para> - - <programlisting> -pain|pain.deep13.com|Forrester's machine:\ - :cm=CONNECT pain\n:tc=deep13: -muffin|muffin.deep13.com|Frank's machine:\ - :cm=CONNECT muffin\n:tc=deep13: -deep13:Gizmonics Institute terminal server:\ - :dv=/dev/cua02:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting> - - <para>will let you type <command>tip pain</command> or <command>tip - muffin</command> to connect to the hosts pain or muffin; and - <command>tip deep13</command> to get to the terminal server.</para> - </sect2> - - <sect2> - <title>Can tip try more than one line for each site?</title> - - <para>This is often a problem where a university has several modem lines - and several thousand students trying to use them...</para> - - <para>Make an entry for your university in - <filename>/etc/remote</filename> and use <literal>@</literal> for the - <literal>pn</literal> capability:</para> - - <programlisting> -big-university:\ - :pn=\@:tc=dialout -dialout:\ - :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:</programlisting> - - <para>Then, list the phone numbers for the university in - <filename>/etc/phones</filename>:</para> - - <programlisting> -big-university 5551111 -big-university 5551112 -big-university 5551113 -big-university 5551114</programlisting> - - <para><command>tip</command> will try each one in the listed order, then - give up. If you want to keep retrying, run <command>tip</command> in - a while loop.</para> - </sect2> - - <sect2> - <title>Why do I have to hit CTRL+P twice to send CTRL+P once?</title> - - <para>CTRL+P is the default <quote>force</quote> character, used to tell - <command>tip</command> that the next character is literal data. You - can set the force character to any other character with the - <command>~s</command> escape, which means <quote>set a - variable.</quote></para> - - <para>Type - <command>~sforce=<replaceable>single-char</replaceable></command> - followed by a newline. <replaceable>single-char</replaceable> is any - single character. If you leave out - <replaceable>single-char</replaceable>, then the force character is - the nul character, which you can get by typing CTRL+2 or CTRL+SPACE. - A pretty good value for <replaceable>single-char</replaceable> is - SHIFT+CTRL+6, which I have seen only used on some terminal - servers.</para> - - <para>You can have the force character be whatever you want by - specifying the following in your <filename>$HOME/.tiprc</filename> - file:</para> - - <programlisting> -force=<single-char></programlisting> - </sect2> - - <sect2> - <title>Suddenly everything I type is in UPPER CASE??</title> - - <para>You must have pressed CTRL+A, <command>tip</command>'s - <quote>raise character,</quote> specially designed for people with - broken caps-lock keys. Use <command>~s</command> as above and set the - variable <literal>raisechar</literal> to something reasonable. In - fact, you can set it to the same as the force character, if you never - expect to use either of these features.</para> - - <para>Here is a sample .tiprc file perfect for Emacs users who need to - type CTRL+2 and CTRL+A a lot:</para> - - <programlisting> -force=^^ -raisechar=^^</programlisting> - - <para>The ^^ is SHIFT+CTRL+6.</para> - </sect2> - - <sect2> - <title>How can I do file transfers with <command>tip</command>?</title> - - <para>If you are talking to another UNIX system, you can send and - receive files with <command>~p</command> (put) and - <command>~t</command> (take). These commands run - <command>cat</command> and <command>echo</command> on the remote - system to accept and send files. The syntax is:</para> - - <cmdsynopsis> - <command>~p</command> - <arg choice="plain">local-file</arg> - <arg choice="opt">remote-file</arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>~t</command> - <arg choice="plain">remote-file</arg> - <arg choice="opt">local-file</arg> - </cmdsynopsis> - - <para>There is no error checking, so you probably should use another - protocol, like zmodem.</para> - </sect2> - - <sect2> - <title>How can I run zmodem with <command>tip</command>?</title> - - <para>To receive files, start the sending program on the remote end. - Then, type <command>~C rz</command> to begin receiving them - locally.</para> - - <para>To send files, start the receiving program on the remote end. - Then, type <command>~C sz <replaceable>files</replaceable></command> - to send them to the remote system.</para> - </sect2> - </sect1> - - <sect1 id="serialconsole-setup"> - <title>Setting Up the Serial Console</title> - - <para><emphasis>&a.yokota; and &a.wpaul;:</emphasis></para> - - <para><emphasis>The text is heavily based on - <filename>/sys/i386/boot/biosboot/README.serial</filename> written by - &a.wpaul;.</emphasis></para> - - <sect2 id="serialconsole-intro"> - <title>Introduction</title> - - <para>The FreeBSD/i386 operating system can boot on a system with only - a dumb terminal on a serial port as a console. Such a configuration - should be useful for two classes of people; system administrators who - wish to install FreeBSD on a dedicated file/compute/terminal server - machines that have no keyboard or monitor attached, and developers who - want to debug the kernel or device drivers.</para> - - <para>Starting from version 3.1, FreeBSD/i386 employs a three stage - bootstrap. The first two stages are in the boot block code which is - stored at the beginning of the FreeBSD slice on the boot disk. The - boot block will then load and run the boot loader - (<filename>/boot/loader</filename>) as the third stage code. (See - &man.boot.8; and &man.loader.8; for more details on the boot - process.)</para> - - <para>In order to set up the serial console you must configure the boot - block code, the boot loader code and the kernel.</para> - - <para>In FreeBSD version 3.0, the boot loader does not exist and there - are only two stages in the bootstrap; the boot blocks directly load - the kernel into memory. If you are using FreeBSD 3.0, then you should - disregard any reference to the boot loader in this section. You can - still use the serial port as a console.</para> - - <para>FreeBSD versions 2.X are quite different from 3.X, in that the - serial port driver, &man.sio.4;, must be configured in a different - way. This chapter will not describe the settings for version 2.X - systems. If you are using these older versions of FreeBSD, please - consult <filename>/sys/i386/boot/biosboot/README.serial</filename> - instead.</para> - </sect2> - - <sect2 id="serialconsole-howto"> - <title>6 Steps to Set up the Serial Console</title> - - <procedure> - <step> - <para>Prepare a serial cable.</para> - - <para>You will need either a null-modem cable or a standard serial - cable and a null-modem adapter. See <xref linkend="term"> for - a discussion on serial cables.</para> - </step> - - <step> - <para>Unplug your keyboard.</para> - - <para>Most PC systems probe for the keyboard during the Power-On - Self-Test (POST) and will generate an error if the keyboard is not - detected. Some machines complain loudly about the lack of a - keyboard and will not continue to boot until it is plugged - in.</para> - - <para>If your computer complains about the error, but boots anyway, - then you do not have to do anything special. (One machine with a - Phoenix BIOS that I have here merely says <errorname>Keyboard - failed</errorname> then continues to boot normally.)</para> - - <para>If your computer refuses to boot without a keyboard attached - then you will have to configure the BIOS so that it ignores this - error (if it can). Consult your motherboard's manual for details - on how to do this.</para> - - <tip> - <para>Setting the keyboard to <quote>Not installed</quote> in the - BIOS setup does <emphasis>not</emphasis> mean that you will not - be able to use your keyboard. All this does is tell the BIOS - not to probe for a keyboard at power-on so that it will not - complain if the keyboard is not plugged in. You can leave the - keyboard plugged in even with this flag set to <quote>Not - installed</quote> and the keyboard will still work.</para> - </tip> - - <note> - <para>If your system has a PS/2 mouse, chances are very good that - you may have to unplug your mouse as well as your keyboard. - This is because PS/2 mice share some hardware with the keyboard, - and leaving the mouse plugged in can fool the keyboard probe - into thinking the keyboard is still there. It is said that a - Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves - this way. In general this is not a problem since the mouse is - not much good without the keyboard anyway.</para> - </note> - </step> - - <step> - <para>Plug a dumb terminal into <devicename>COM1:</devicename> - (<devicename>sio0</devicename>).</para> - - <para>If you do not have a dumb terminal, you can use an old PC/XT - with a modem program, or the serial port on another UNIX box. If - you do not have a <devicename>COM1:</devicename> - (<devicename>sio0</devicename>), get one. At this time, there is - no way to select a port other than <devicename>COM1:</devicename> - for the boot blocks without recompiling the boot blocks. If you - are already using <devicename>COM1:</devicename> for another - device, you will have to temporarily remove that device and - install a new boot block and kernel once you get FreeBSD up and - running. (It is assumed that <devicename>COM1:</devicename> will - be available on a file/compute/terminal server anyway; if you - really need <devicename>COM1:</devicename> for something else - (and you can not switch that something else to - <devicename>COM2:</devicename> (<devicename>sio1</devicename>)), - then you probably should not even be bothering with all this in - the first place.)</para> - </step> - - <step> - <para>Make sure the configuration file of your kernel has - appropriate flags set for <devicename>COM1:</devicename> - (<devicename>sio0</devicename>).</para> - - <para>Relevant flags are:</para> - - <variablelist> - <varlistentry> - <term><literal>0x10</literal></term> - - <listitem> - <para>Enables console support for this unit. The other - console flags are ignored unless this is set. Currently, at - most one unit can have console support; the first one (in - config file order) with this flag set is preferred. This - option alone will not make the serial port the console. Set - the following flag or use the <option>-h</option> option - described below, together with this flag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>0x20</literal></term> - - <listitem> - <para>Forces this unit to be the console (unless there is - another higher priority console), regardless of the - <option>-h</option> option discussed below. This flag - replaces the <literal>COMCONSOLE</literal> option in FreeBSD - versions 2.X. The flag <literal>0x20</literal> must be used - together with the <option>0x10</option> flag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>0x40</literal></term> - - <listitem> - <para>Reserves this unit (in conjunction with - <literal>0x10</literal>) and makes the unit unavailable for - normal access. You should not set this flag to the serial - port unit which you want to use as the serial console. The - only use of this flag is to designate the unit for kernel - remote debugging. See <xref linkend="kerneldebug"> for more - information on remote debugging.</para> - - <note> - <para>In FreeBSD 4.0-CURRENT or later the semantics of the - flag <literal>0x40</literal> are slightly different and - there is another flag to specify a serial port for remote - debugging.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - - <para>Example:</para> - - <programlisting> -device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting> - - <para>See &man.sio.4; for more details.</para> - - <para>If the flags were not set, you need to run UserConfig (on a - different console) or recompile the kernel.</para> - </step> - - <step> - <para>Create <filename>boot.config</filename> in the root directory - of the <literal>a</literal> partition on the boot drive.</para> - - <para>This file will instruct the boot block code how you would like - to boot the system. In order to activate the serial console, you - need one or more of the following options—if you want - multiple options, include them all on the same line:</para> - - <variablelist> - <varlistentry> - <term><option>-h</option></term> - - <listitem> - <para>Toggles internal and serial consoles. You can use this - to switch console devices. For instance, if you boot from - the internal (video) console, you can use - <option>-h</option> to direct the boot loader and the kernel - to use the serial port as its console device. Alternatively, - if you boot from the serial port, you can use the - <option>-h</option> to tell the boot loader and the kernel - to use the video display as the console instead.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-D</option></term> - - <listitem> - <para>Toggles single and dual console configurations. In the - single configuration the console will be either the internal - console (video display) or the serial port, depending on the - state of the <option>-h</option> option above. In the dual - console configuration, both the video display and the - serial port will become the console at the same time, - regardless of the state of the <option>-h</option> option. - However, that the dual console configuration takes effect - only during the boot block is running. Once the boot loader - gets control, the console specified by the - <option>-h</option> option becomes the only console.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-P</option></term> - - <listitem> - <para>Makes the boot block probe the keyboard. If no keyboard - is found, the <option>-D</option> and <option>-h</option> - options are automatically set.</para> - - <note> - <para>Due to space constraints in the current version of the - boot blocks, the <option>-P</option> option is capable of - detecting extended keyboards only. Keyboards with less - than 101 keys (and without F11 and F12 keys) may not be - detected. Keyboards on some laptop computers may not be - properly found because of this limitation. If this is to - be the case with your system, you have to abandon using - the <option>-P</option> option. Unfortunately there is no - workaround for this problem.</para> - </note> - </listitem> - </varlistentry> - </variablelist> - - <para>Use either the <option>-P</option> option to select the - console automatically, or the <option>-h</option> option to - activate the serial console.</para> - - <para>You may include other options described in &man.boot.8; as - well.</para> - - <para>The options, except for <option>-P</option>, will be passed to - the boot loader (<filename>/boot/loader</filename>). The boot - loader will determine which of the internal video or the serial - port should become the console by examining the state of the - <option>-h</option> option alone. This means that if you specify - the <option>-D</option> option but not the <option>-h</option> - option in <filename>/boot.config</filename>, you can use the - serial port as the console only during the boot block; the boot - loader will use the internal video display as the console.</para> - </step> - - <step> - <para>Boot the machine.</para> - - <para>When you start your FreeBSD box, the boot blocks will echo the - contents of <filename>/boot.config</filename> to the console. For - example;</para> - - <screen>/boot.config: -P -Keyboard: no</screen> - - <para>The second line appears only if you put <option>-P</option> in - <filename>/boot.config</filename> and indicates presence/absence - of the keyboard. These messages go to either serial or internal - console, or both, depending on the option in - <filename>/boot.config</filename>.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Options</entry> - <entry>Message goes to</entry> - </row> - </thead> - - <tbody> - <row> - <entry>none</entry> - <entry>internal console</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial console</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal consoles</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal consoles</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal console</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial console</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>After the above messages, there will be a small pause before - the boot blocks continue loading the boot loader and before any - further messages printed to the console. Under normal - circumstances, you do not need to interrupt the boot blocks, but - you may want to do so in order to make sure things are set up - correctly.</para> - - <para>Hit any key, other than Enter/Return, at the console to - interrupt the boot process. The boot blocks will then prompt you - for further action. You should now see something like:</para> - - <screen>>> FreeBSD/i386 BOOT -Default: 0:wd(0,a)/boot/loader -boot:</screen> - - <para>Verify the above message appears on either the serial or - internal console or both, according to the options you put in - <filename>/boot.config</filename>. If the message appears in the - correct console, hit Enter/Return to continue the boot - process.</para> - - <para>If you want the serial console but you do not see the prompt - on the serial terminal, something is wrong with your settings. In - the meantime, you enter <option>-h</option> and hit Enter/Return - (if possible) to tell the boot block (and then the boot loader and - the kernel) to choose the serial port for the console. Once the - system is up, go back and check what went wrong.</para> - </step> - </procedure> - - <para>After the boot loader is loaded and you are in the third stage of - the boot process you can still switch between the internal console and - the serial console by setting appropriate environment variables in the - boot loader. See <xref linkend="serialconsole-loader">.</para> - </sect2> - - <sect2 id="serialconsole-summary"> - <title>Summary</title> - - <para>Here is the summary of various settings discussed in this section - and the console eventually selected.</para> - - <sect3> - <title>Case 1: You set the flags to 0x10 for sio0</title> - - <programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Options in /boot.config</entry> - <entry>Console during boot blocks</entry> - <entry>Console during boot loader</entry> - <entry>Console in kernel</entry> - </row> - </thead> - - <tbody> - <row> - <entry>nothing</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>internal</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3> - <title>Case 2: You set the flags to 0x30 for sio0</title> - - <programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting> - - <informaltable frame="none"> - <tgroup cols="4"> - <thead> - <row> - <entry>Options in /boot.config</entry> - <entry>Console during boot blocks</entry> - <entry>Console during boot loader</entry> - <entry>Console in kernel</entry> - </row> - </thead> - - <tbody> - <row> - <entry>nothing</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-h</option></entry> - <entry>serial</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-D</option></entry> - <entry>serial and internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-Dh</option></entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard present</entry> - <entry>internal</entry> - <entry>internal</entry> - <entry>serial</entry> - </row> - - <row> - <entry><option>-P</option>, keyboard absent</entry> - <entry>serial and internal</entry> - <entry>serial</entry> - <entry>serial</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - </sect2> - - <sect2 id="serialconsole-tips"> - <title>Tips for the Serial Console</title> - - <sect3> - <title>Setting A Faster Serial Port Speed</title> - - <para>By default the serial port settings are set to 9600 baud, 8 - bits, no parity, 1 stop bit. If you wish to change the speed, you - need to recompile at least the boot blocks. Add the following line - to <filename>/etc/make.conf</filename> and compile new boot - blocks:</para> - - <programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting> - - <para>If the serial console is configured in some other way than by - booting with <option>-h</option>, or if the serial console used by - the kernel is different from the one used by the boot blocks, then - you must also add the following option to the kernel configuration - file and compile a new kernel:</para> - - <programlisting>options CONSPEED=19200</programlisting> - </sect3> - - <sect3 id="serialconsole-com2"> - <title>Using Serial Port Other Than <devicename>sio0</devicename> For - The Console</title> - - <para>Using a port other than <devicename>sio0</devicename> as the - console requires some recompiling. If you want to use another - serial port for whatever reasons, recompile the boot blocks, the - boot loader and the kernel as follows.</para> - - <procedure> - <step> - <para>Get the kernel source.</para> - </step> - - <step> - <para>Edit <filename>/etc/make.conf</filename> and set - <literal>BOOT_COMCONSOLE_PORT</literal> to the address of the - port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only - <devicename>sio0</devicename> through - <devicename>sio3</devicename> (<devicename>COM1:</devicename> - through <devicename>COM4:</devicename>) can be used; multiport - serial cards will not work. No interrupt setting is - needed.</para> - </step> - - <step> - <para>Create a custom kernel configuration file and add - appropriate flags for the serial port you want to use. For - example, if you want to make <devicename>sio1</devicename> - (<devicename>COM2:</devicename>) the console:</para> - - <programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting> - - <para>or</para> - - <programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting> - - <para>The console flags for the other serial ports should not be - set.</para> - </step> - - <step> - <para>Recompile and install the boot blocks:</para> - - <screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </step> - - <step> - <para>Recompile and install the boot loader:</para> - - <screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </step> - - <step> - <para>Rebuild and install the kernel.</para> - </step> - - <step> - <para>Write the boot blocks to the boot disk with - &man.disklabel.8; and boot from the new kernel.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Entering the DDB Debugger from the Serial Line</title> - - <para>If you wish to drop into the kernel debugger from the serial - console (useful for remote diagnostics, but also dangerous if you - generate a spurious BREAK on the serial port!) then you should - compile your kernel with the following options:</para> - - <programlisting>options BREAK_TO_DEBUGGER -options DDB</programlisting> - </sect3> - - <sect3> - <title>Getting a Login Prompt on the Serial Console</title> - - <para>While this is not required, you may wish to get a - <emphasis>login</emphasis> prompt over the serial line, now that you - can see boot messages and can enter the kernel debugging session - through the serial console. Here is how to do it.</para> - - <para>Open the file <filename>/etc/ttys</filename> with an editor - and locate the lines:</para> - - <programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure -ttyd1 "/usr/libexec/getty std.9600" unknown off secure -ttyd2 "/usr/libexec/getty std.9600" unknown off secure -ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> - - <para><literal>ttyd0</literal> through <literal>ttyd3</literal> - corresponds to <devicename>COM1</devicename> through - <devicename>COM4</devicename>. Change <literal>off</literal> to - <literal>on</literal> for the desired port. If you have changed the - speed of the serial port, you need to change - <literal>std.9600</literal> to match the current setting, e.g. - <literal>std.19200</literal>.</para> - - <para>You may also want to change the terminal type from - <literal>unknown</literal> to the actual type of your serial - terminal.</para> - - <para>After editing the file, you must <command>kill -HUP 1</command> - to make this change take effect.</para> - </sect3> - </sect2> - - <sect2 id="serialconsole-loader"> - <title>Changing Console from the Boot Loader</title> - - <para>Previous sections described how to set up the serial console by - tweaking the boot block. This section shows that you can specify the - console by entering some commands and environment variables in the - boot loader. As the boot loader is invoked as the third stage of the - boot process, after the boot block, the settings in the boot loader - will override the settings in the boot block.</para> - - <sect3> - <title>Setting Up the Serial Console</title> - - <para>You can easily specify the boot loader and the kernel to use the - serial console by writing just one line in - <filename>/boot/loader.rc</filename>:</para> - - <programlisting>set console=comconsole</programlisting> - - <para>This will take effect regardless of the settings in the boot - block discussed in the previous section.</para> - - <para>You had better put the above line as the first line of - <filename>/boot/loader.rc</filename> so as to see boot messages on - the serial console as early as possible.</para> - - <para>Likewise, you can specify the internal console as:</para> - - <programlisting>set console=vidconsole</programlisting> - - <para>If you do not set the boot loader environment variable - <envar>console</envar>, the boot loader, and subsequently the - kernel, will use whichever console indicated by the - <option>-h</option> option in the boot block.</para> - - <para>In versions 3.2 or later, you may specify the console in - <filename>/boot/loader.conf.local</filename> or - <filename>/boot/loader.conf</filename>, rather than in - <filename>/boot/loader.rc</filename>. In this method your - <filename>/boot/loader.rc</filename> should look like:</para> - - <programlisting>include /boot/loader.4th -start</programlisting> - - <para>Then, create <filename>/boot/loader.conf.local</filename> and - put the following line there.</para> - - <programlisting>console=comconsole</programlisting> - - <para>or</para> - - <programlisting>console=vidconsole</programlisting> - - <para>See &man.loader.conf.5; for more information.</para> - - <note> - <para>At the moment, the boot loader has no option equivalent to the - <option>-P</option> option in the boot block, and there is no - provision to automatically select the internal console and the - serial console based on the presence of the keyboard.</para> - </note> - </sect3> - - <sect3> - <title>Using Serial Port Other than <devicename>sio0</devicename> for - the Console</title> - - <para>You need to recompile the boot loader to use a serial port other - than <devicename>sio0</devicename> for the serial console. Follow the - procedure described in <xref linkend="serialconsole-com2">.</para> - </sect3> - </sect2> - - <sect2 id="serialconsole-caveats"> - <title>Caveats</title> - - <para>The idea here is to allow people to set up dedicated servers that - require no graphics hardware or attached keyboards. Unfortunately, - while (most?) every system will let you boot without a keyboard, there - are quite a few that will not let you boot without a graphics adapter. - Machines with AMI BIOSes can be configured to boot with no graphics - adapter installed simply by changing the `graphics adapter' setting in - the CMOS configuration to `Not installed.'</para> - - <para>However, many machines do not support this option and will refuse - to boot if you have no display hardware in the system. With these - machines, you'll have to leave some kind of graphics card plugged in, - (even if it's just a junky mono board) although you will not have to - attach a monitor into it. You might also try installing an AMI - BIOS.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/staff/chapter.sgml b/en_US.ISO8859-1/books/handbook/staff/chapter.sgml deleted file mode 100644 index 9eea3900cc..0000000000 --- a/en_US.ISO8859-1/books/handbook/staff/chapter.sgml +++ /dev/null @@ -1,1251 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml,v 1.175 2000/11/16 14:49:19 phantom Exp $ ---> - -<!-- - Please try to keep the CVSROOT/access file in sync with the list of - FreeBSD developers. ---> - -<appendix id="staff"> - <title>FreeBSD Project Staff</title> - - <para>The FreeBSD Project is managed and operated by the following groups of - people:</para> - - <sect1 id="staff-core"> - <title>The FreeBSD Core Team</title> - - <para>The FreeBSD core team constitutes the project's <quote>Board of - Directors</quote>, responsible for deciding the project's overall goals - and direction as well as managing <link linkend="staff-who">specific - areas</link> of the FreeBSD project landscape.</para> - - <para>(in alphabetical order by last name):</para> - - <itemizedlist> - <listitem> - <para>&a.asami;</para> - </listitem> - - <listitem> - <para>&a.dg;</para> - </listitem> - - <listitem> - <para>&a.jkh;</para> - </listitem> - - <listitem> - <para>&a.grog;</para> - </listitem> - - <listitem> - <para>&a.imp;</para> - </listitem> - - <listitem> - <para>&a.dfr;</para> - </listitem> - - <listitem> - <para>&a.msmith;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.peter;</para> - </listitem> - </itemizedlist> - </sect1> - -<!-- - This list is sorted by last name, not by entity or tenure. ---> - - <sect1 id="staff-committers"> - <title>The FreeBSD Developers</title> - - <para>These are the people who have commit privileges and do the - engineering work on the FreeBSD source tree. All core team members are - also developers.</para> - - <itemizedlist> - <listitem> - <para>&a.akiyama;</para> - </listitem> - - <listitem> - <para>&a.jmas;</para> - </listitem> - - <listitem> - <para>&a.will;</para> - </listitem> - - <listitem> - <para>&a.ugen;</para> - </listitem> - - <listitem> - <para>&a.toshi;</para> - </listitem> - - <listitem> - <para>&a.babkin;</para> - </listitem> - - <listitem> - <para>&a.dbaker;</para> - </listitem> - - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.mbarkah;</para> - </listitem> - - <listitem> - <para>&a.dougb;</para> - </listitem> - - <listitem> - <para>&a.stb;</para> - </listitem> - - <listitem> - <para>&a.pb;</para> - </listitem> - - <listitem> - <para>&a.abial;</para> - </listitem> - - <listitem> - <para>&a.jb;</para> - </listitem> - - <listitem> - <para>&a.nbm;</para> - </listitem> - - <listitem> - <para>&a.jmb;</para> - </listitem> - - <listitem> - <para>&a.torstenb;</para> - </listitem> - - <listitem> - <para>&a.wilko;</para> - </listitem> - - <listitem> - <para>&a.jake;</para> - </listitem> - - <listitem> - <para>&a.dburr;</para> - </listitem> - - <listitem> - <para>&a.adrian;</para> - </listitem> - - <listitem> - <para>&a.charnier;</para> - </listitem> - - <listitem> - <para>&a.jon;</para> - </listitem> - - <listitem> - <para>&a.luoqi;</para> - </listitem> - - <listitem> - <para>&a.ache;</para> - </listitem> - - <listitem> - <para>&a.ejc;</para> - </listitem> - - <listitem> - <para>&a.kjc;</para> - </listitem> - - <listitem> - <para>&a.cjh;</para> - </listitem> - - <listitem> - <para>&a.archie;</para> - </listitem> - - <listitem> - <para>&a.chris;</para> - </listitem> - - <listitem> - <para>&a.alc;</para> - </listitem> - - <listitem> - <para>&a.cracauer;</para> - </listitem> - - <listitem> - <para>&a.dec;</para> - </listitem> - - <listitem> - <para>&a.adam;</para> - </listitem> - - <listitem> - <para>&a.bsd;</para> - </listitem> - - <listitem> - <para>&a.jwd;</para> - </listitem> - - <listitem> - <para>&a.dillon;</para> - </listitem> - - <listitem> - <para>&a.mdodd;</para> - </listitem> - - <listitem> - <para>&a.gad;</para> - </listitem> - - <listitem> - <para>&a.dufault;</para> - </listitem> - - <listitem> - <para>&a.uhclem;</para> - </listitem> - - <listitem> - <para>&a.tegge;</para> - </listitem> - - <listitem> - <para>&a.deischen;</para> - </listitem> - - <listitem> - <para>&a.eivind;</para> - </listitem> - - <listitem> - <para>&a.julian;</para> - </listitem> - - <listitem> - <para>&a.rse;</para> - </listitem> - - <listitem> - <para>&a.ru;</para> - </listitem> - - <listitem> - <para>&a.se;</para> - </listitem> - - <listitem> - <para>&a.bde;</para> - </listitem> - - <listitem> - <para>&a.jasone;</para> - </listitem> - - <listitem> - <para>&a.sef;</para> - </listitem> - - <listitem> - <para>&a.jedgar;</para> - </listitem> - - <listitem> - <para>&a.green;</para> - </listitem> - - <listitem> - <para>&a.fenner;</para> - </listitem> - - <listitem> - <para>&a.lioux;</para> - </listitem> - - <listitem> - <para>&a.jfieber;</para> - </listitem> - - <listitem> - <para>&a.jfitz;</para> - </listitem> - - <listitem> - <para>&a.scrappy;</para> - </listitem> - - <listitem> - <para>&a.lars;</para> - </listitem> - - <listitem> - <para>&a.dirk;</para> - </listitem> - - <listitem> - <para>&a.shige;</para> - </listitem> - - <listitem> - <para>&a.billf;</para> - </listitem> - - <listitem> - <para>&a.gallatin;</para> - </listitem> - - <listitem> - <para>&a.patrick;</para> - </listitem> - - <listitem> - <para>&a.tg;</para> - </listitem> - - <listitem> - <para>&a.gibbs;</para> - </listitem> - - <listitem> - <para>&a.brandon;</para> - </listitem> - - <listitem> - <para>&a.gioria;</para> - </listitem> - - <listitem> - <para>&a.graichen;</para> - </listitem> - - <listitem> - <para>&a.cg;</para> - </listitem> - - <listitem> - <para>&a.rgrimes;</para> - </listitem> - - <listitem> - <para>&a.jmg;</para> - </listitem> - - <listitem> - <para>&a.hanai;</para> - </listitem> - - <listitem> - <para>&a.roger;</para> - </listitem> - - <listitem> - <para>&a.mharo;</para> - </listitem> - - <listitem> - <para>&a.dannyboy;</para> - </listitem> - - <listitem> - <para>&a.thepish;</para> - </listitem> - - <listitem> - <para>&a.jhay;</para> - </listitem> - - <listitem> - <para>&a.sheldonh;</para> - </listitem> - - <listitem> - <para>&a.helbig;</para> - </listitem> - - <listitem> - <para>&a.ghelmer;</para> - </listitem> - - <listitem> - <para>&a.erich;</para> - </listitem> - - <listitem> - <para>&a.nhibma;</para> - </listitem> - - <listitem> - <para>&a.flathill;</para> - </listitem> - - <listitem> - <para>&a.pho;</para> - </listitem> - - <listitem> - <para>&a.horikawa;</para> - </listitem> - - <listitem> - <para>&a.hosokawa;</para> - </listitem> - - <listitem> - <para>&a.jeh;</para> - </listitem> - - <listitem> - <para>&a.hsu;</para> - </listitem> - - <listitem> - <para>&a.foxfair;</para> - </listitem> - - <listitem> - <para>&a.tom;</para> - </listitem> - - <listitem> - <para>&a.mph;</para> - </listitem> - - <listitem> - <para>&a.shin;</para> - </listitem> - - <listitem> - <para>&a.itojun;</para> - </listitem> - - <listitem> - <para>&a.iwasaki;</para> - </listitem> - - <listitem> - <para>&a.mjacob;</para> - </listitem> - - <listitem> - <para>&a.keith;</para> - </listitem> - - <listitem> - <para>&a.gj;</para> - </listitem> - - <listitem> - <para>&a.nsj;</para> - </listitem> - - <listitem> - <para>&a.trevor;</para> - </listitem> - - <listitem> - <para>&a.phk;</para> - </listitem> - - <listitem> - <para>&a.joe;</para> - </listitem> - - <listitem> - <para>&a.cokane;</para> - </listitem> - - <listitem> - <para>&a.kato;</para> - </listitem> - - <listitem> - <para>&a.kris;</para> - </listitem> - - <listitem> - <para>&a.kiri;</para> - </listitem> - - <listitem> - <para>&a.andreas;</para> - </listitem> - - <listitem> - <para>&a.motoyuki;</para> - </listitem> - - <listitem> - <para>&a.jkoshy;</para> - </listitem> - - <listitem> - <para>&a.kuriyama;</para> - </listitem> - - <listitem> - <para>&a.alex;</para> - </listitem> - - <listitem> - <para>&a.reg;</para> - </listitem> - - <listitem> - <para>&a.jlemon;</para> - </listitem> - - <listitem> - <para>&a.truckman;</para> - </listitem> - - <listitem> - <para>&a.lile;</para> - </listitem> - - <listitem> - <para>&a.kevlo;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.ade;</para> - </listitem> - - <listitem> - <para>&a.jmacd;</para> - </listitem> - - <listitem> - <para>&a.smace;</para> - </listitem> - - <listitem> - <para>&a.bmah;</para> - </listitem> - - <listitem> - <para>&a.dwmalone;</para> - </listitem> - - <listitem> - <para>&a.mckay;</para> - </listitem> - - <listitem> - <para>&a.mckusick;</para> - </listitem> - - <listitem> - <para>&a.ken;</para> - </listitem> - - <listitem> - <para>&a.hm;</para> - </listitem> - - <listitem> - <para>&a.sanpei;</para> - </listitem> - - <listitem> - <para>&a.bmilekic;</para> - </listitem> - - <listitem> - <para>&a.non;</para> - </listitem> - - <listitem> - <para>&a.jim;</para> - </listitem> - - <listitem> - <para>&a.marcel;</para> - </listitem> - - <listitem> - <para>&a.dan;</para> - </listitem> - - <listitem> - <para>&a.amurai;</para> - </listitem> - - <listitem> - <para>&a.markm;</para> - </listitem> - - <listitem> - <para>&a.rich;</para> - </listitem> - - <listitem> - <para>&a.knu;</para> - </listitem> - - <listitem> - <para>&a.nakai;</para> - </listitem> - - <listitem> - <para>&a.max;</para> - </listitem> - - <listitem> - <para>&a.newton;</para> - </listitem> - - <listitem> - <para>&a.rnordier;</para> - </listitem> - - <listitem> - <para>&a.davidn;</para> - </listitem> - - <listitem> - <para>&a.obrien;</para> - </listitem> - - <listitem> - <para>&a.danny;</para> - </listitem> - - <listitem> - <para>&a.okazaki;</para> - </listitem> - - <listitem> - <para>&a.ljo;</para> - </listitem> - - <listitem> - <para>&a.onoe;</para> - </listitem> - - <listitem> - <para>&a.marko;</para> - </listitem> - - <listitem> - <para>&a.gpalmer;</para> - </listitem> - - <listitem> - <para>&a.fsmp;</para> - </listitem> - - <listitem> - <para>&a.smpatel;</para> - </listitem> - - <listitem> - <para>&a.cp;</para> - </listitem> - - <listitem> - <para>&a.wpaul;</para> - </listitem> - - <listitem> - <para>&a.alfred;</para> - </listitem> - - <listitem> - <para>&a.wes;</para> - </listitem> - - <listitem> - <para>&a.cpiazza;</para> - </listitem> - - <listitem> - <para>&a.jdp;</para> - </listitem> - - <listitem> - <para>&a.bp;</para> - </listitem> - - <listitem> - <para>&a.steve;</para> - </listitem> - - <listitem> - <para>&a.mpp;</para> - </listitem> - - <listitem> - <para>&a.jraynard;</para> - </listitem> - - <listitem> - <para>&a.darrenr;</para> - </listitem> - - <listitem> - <para>&a.csgr;</para> - </listitem> - - <listitem> - <para>&a.martin;</para> - </listitem> - - <listitem> - <para>&a.paul;</para> - </listitem> - - <listitem> - <para>&a.roberto;</para> - </listitem> - - <listitem> - <para>&a.chuckr;</para> - </listitem> - - <listitem> - <para>&a.jesusr;</para> - </listitem> - - <listitem> - <para>&a.guido;</para> - </listitem> - - <listitem> - <para>&a.groudier;</para> - </listitem> - - <listitem> - <para>&a.dima;</para> - </listitem> - - <listitem> - <para>&a.asmodai;</para> - </listitem> - - <listitem> - <para>&a.ps;</para> - </listitem> - - <listitem> - <para>&a.sada;</para> - </listitem> - - <listitem> - <para>&a.hrs;</para> - </listitem> - - <listitem> - <para>&a.wsanchez;</para> - </listitem> - - <listitem> - <para>&a.sos;</para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>&a.wosch;</para> - </listitem> - - <listitem> - <para>&a.dick;</para> - </listitem> - - <listitem> - <para>&a.jseger;</para> - </listitem> - - <listitem> - <para>&a.gshapiro;</para> - </listitem> - - <listitem> - <para>&a.simokawa;</para> - </listitem> - - <listitem> - <para>&a.vanilla;</para> - </listitem> - - <listitem> - <para>&a.shafeeq;</para> - </listitem> - - <listitem> - <para>&a.demon;</para> - </listitem> - - <listitem> - <para>&a.msmith;</para> - </listitem> - - <listitem> - <para>&a.ben;</para> - </listitem> - - <listitem> - <para>&a.benno;</para> - </listitem> - - <listitem> - <para>&a.des;</para> - </listitem> - - <listitem> - <para>&a.sobomax;</para> - </listitem> - - <listitem> - <para>&a.dcs;</para> - </listitem> - - <listitem> - <para>&a.brian;</para> - </listitem> - - <listitem> - <para>&a.mks;</para> - </listitem> - - <listitem> - <para>&a.stark;</para> - </listitem> - - <listitem> - <para>&a.sumikawa;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.gsutter;</para> - </listitem> - - <listitem> - <para>&a.unfurl;</para> - </listitem> - - <listitem> - <para>&a.nyan;</para> - </listitem> - - <listitem> - <para>&a.tanimura;</para> - </listitem> - - <listitem> - <para>&a.taoka;</para> - </listitem> - - <listitem> - <para>&a.mtaylor;</para> - </listitem> - - <listitem> - <para>&a.dt;</para> - </listitem> - - <listitem> - <para>&a.cwt;</para> - </listitem> - - <listitem> - <para>&a.pst;</para> - </listitem> - - <listitem> - <para>&a.ume;</para> - </listitem> - - <listitem> - <para>&a.rv;</para> - </listitem> - - <listitem> - <para>&a.hoek;</para> - </listitem> - - <listitem> - <para>&a.nectar;</para> - </listitem> - - <listitem> - <para>&a.jayanth;</para> - </listitem> - - <listitem> - <para>&a.swallace;</para> - </listitem> - - <listitem> - <para>&a.takawata;</para> - </listitem> - - <listitem> - <para>&a.assar;</para> - </listitem> - - <listitem> - <para>&a.dwhite;</para> - </listitem> - - <listitem> - <para>&a.nate;</para> - </listitem> - - <listitem> - <para>&a.wollman;</para> - </listitem> - - <listitem> - <para>&a.joerg;</para> - </listitem> - - <listitem> - <para>&a.kbyanc;</para> - </listitem> - - <listitem> - <para>&a.yokota;</para> - </listitem> - - <listitem> - <para>&a.andy;</para> - </listitem> - - <listitem> - <para>&a.phantom;</para> - </listitem> - - <listitem> - <para>&a.jmz;</para> - </listitem> - - <listitem> - <para>&a.issei;</para> - </listitem> - - </itemizedlist> - </sect1> - - <sect1 id="staff-doc"> - - - <title>The FreeBSD Documentation Project</title> - - <para>The <ulink url="http://www.FreeBSD.org/docproj.html">FreeBSD - Documentation Project</ulink> is responsible for a number of different - services, each service being run by an individual and his - <emphasis>deputies</emphasis> (if any):</para> - - <variablelist> - <varlistentry> - <term>Documentation Project Architect</term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Webmaster</term> - - <listitem> - <para>&a.wosch;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook Editor</term> - - <listitem> - <para>&a.jim;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ Editor</term> - - <listitem> - <para>&a.faq;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>News Editor</term> - - <listitem> - <para>&a.jim;</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>In the Press Editor</term> - - <listitem> - <para>&a.jkoshy;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD Really-Quick NewsLetter Editor</term> - - <listitem> - <para>Chris Coleman <email>chrisc@vmunix.com</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Gallery Editor</term> - - <listitem> - <para>&a.phantom;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Commercial Editor</term> - - <listitem> - <para>&a.phantom;</para> - </listitem> - </varlistentry> - -<![ %not.published; [ - - <varlistentry> - <term>Web Changes Editor</term> - - <listitem> - <para>&a.www;</para> - </listitem> - </varlistentry> - -]]> - - <varlistentry> - <term>User Groups Editor</term> - - <listitem> - <para>&a.grog;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD Projects and Tasklist Editor</term> - - <listitem> - <para>&a.asmodai;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD Java Project</term> - - <listitem> - <para>&a.patrick;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LinuxDoc to DocBook conversion</term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="staff-who"> - <title>Who is Responsible for What</title> - - <variablelist> - <varlistentry> - <term><ulink - url="http://www.FreeBSD.org/docproj/docproj.html">Documentation - Project Manager</ulink></term> - - <listitem> - <para>&a.nik;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="boot-blocks">Boot blocks</link></term> - - <listitem> - <para>&a.rnordier;, &a.jhb;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="boot-loader">Boot loader</link></term> - - <listitem> - <para>&a.dcs;</para> - <para>&a.jhb;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="l10n">Internationalization</link></term> - - <listitem> - <para>&a.ache;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="eresources-mail">Postmaster</link></term> - - <listitem> - <para>&a.jmb;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Release Coordinator</term> - - <listitem> - <para>&a.jkh;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Public Relations & Corporate Liaison</term> - - <listitem> - <para>&a.jkh;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/security/">Security - Officer</ulink></term> - - <listitem> - <para>&a.kris;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/support.html#cvs">Source - Repository Managers</ulink></term> - - <listitem> - <para>Principal: &a.peter;</para> - - <para>Assistant: &a.jdp;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/ports/">Ports - Manager</ulink></term> - - <listitem> - <para>&a.asami;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Standards</term> - - <listitem> - <para>&a.wollman;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XFree86 Project, Inc. Liaison</term> - - <listitem> - <para>&a.rich;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><link linkend="eresources-news">Usenet Support</link></term> - - <listitem> - <para>&a.joerg;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.FreeBSD.org/support.html#gnats">GNATS - Administrator</ulink></term> - - <listitem> - <para>&a.steve;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink - url="http://www.FreeBSD.org/internal/">Webmaster</ulink></term> - - <listitem> - <para>&a.wosch;</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> - diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.sgml b/en_US.ISO8859-1/books/handbook/users/chapter.sgml deleted file mode 100644 index 6955bf5d47..0000000000 --- a/en_US.ISO8859-1/books/handbook/users/chapter.sgml +++ /dev/null @@ -1,425 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/users/chapter.sgml,v 1.3 2000/06/12 17:10:36 alex Exp $ ---> - -<chapter id="users"> - <title>Users and Basic Account Management</title> - - <sect1 id="users-synopsis"> - <title>Synopsis</title> - - <para><emphasis>Contributed by &a.nbm; February 2000</emphasis>.</para> - - <para>All access to the system is achieved via accounts, and all - processes are run by users, so user and account management are - of integral importance on FreeBSD systems.</para> - - <para>There are three main types of accounts; the <link - linkend="users-superuser">Superuser</link>, <link - linkend="users-system">system users</link>, and <link - linkend="users-user">user accounts</link>. The Superuser - account, usually called <username>root</username>, is used to - manage the system with no limitations on privileges. System - users run services. Finally, user accounts are used by real - people, who log on, read mail, and so forth.</para> - </sect1> - - <sect1 id="users-superuser"> - <title>The Superuser Account</title> - - <para>The superuser account, usually called - <username>root</username>, comes preconfigured, and facilitates - system administration, and should not be used for day-to-date - tasks like sending and receiving mail, general exploration of - the system, or programming.</para> - - <para>This is because the superuser, unlike normal user accounts, - can operate without limits, and misuse of the superuser account - may result in spectacular disasters. User accounts are unable - to destroy the system by mistake, so it is generally best to use - normal user accounts whenever possible, unless you especially - need the extra privilege.</para> - - <para>In addition, always double and triple-check commands you - issue as the superuser, since an extra space or missing - character can mean irreparable data loss. Those extra - privileges you needed when you decided to change to the - superuser mean that the safeguards of your normal user account - no longer apply.</para> - - <para>So, the first thing you should do after reading this - chapter, is to create an unprivileged user account for yourself - for general usage, if you haven't already. This applies equally - whether you're running a multi-user or single-user machine. - Later in this chapter, we discuss how to create additional - accounts, and how to change between the normal user and - superuser.</para> - </sect1> - - <sect1 id="users-system"> - <title>System Accounts</title> - - <para>System users are those used to run services such as DNS, - mail, web servers, and so forth. The reason for this is - security, as if all services ran as the superuser, they could - act without restriction.</para> - - <para>Examples of system users are <username>daemon</username>, - <username>operator</username>, <username>bind</username> (for - the Domain Name Service), and <username>news</username>. Often - sysadmins create <username>httpd</username> to run web servers - they install.</para> - - <para><username>nobody</username> is the generic unprivileged - system user, but the more services that use - <username>nobody</username>, the more privileged it - becomes.</para> - </sect1> - - <sect1 id="users-user"> - <title>User Accounts</title> - - <para>User accounts are the primary means of access for real - people to the system, and these accounts insulate the user and - the environment, preventing the users from damaging the system - or other users, and allowing users to customize their - environment without affecting others.</para> - - <para>Every person accessing your system should have their own - unique user account. This allows you to find out who is doing - what, and prevent people from clobbering each others' settings, - and reading mail meant for the other, and so forth.</para> - - <para>Each user can set up their own environment to accommodate - their use of the system, by using alternate shells, editors, key - bindings, and language.</para> - </sect1> - - <sect1 id="users-modifying"> - <title>Modifying Accounts</title> - - <para><application>pw</application> is a powerful and flexible - means to modify accounts, but <application>adduser</application> - is recommended for creating new accounts, and - <application>rmuser</application> for deleting accounts.</para> - - <para><application>chpass</application> allows both the system - administrator and normal users to adjust passwords, shells, and - personal information. <application>passwd</application> is the - more common means to change passwords specifically, - however.</para> - - - <sect2 id="users-adduser"> - <title>adduser</title> - - <para><application>adduser</application> is a simple program for - adding new users. It creates <filename>passwd</filename> and - <filename>group</filename> entries for the user, as well as - creating their home directory, copy in some default dotfiles - from <filename>/usr/share/skel</filename>, and can optionally - mail the user a welcome message.</para> - - <para>To create the initial configuration file, use - <command>adduser -s -config_create</command>. - <footnote> - <para>The <option>-s</option> makes adduser default to - quiet. We use <option>-v</option> later when we want to - change defaults.</para> - </footnote>Next, we configure adduser defaults, and create our - first user account, since using root for normal usage is evil - and nasty.</para> - - <example> - <title>Changing the configuration for adduser</title> - - <screen>&prompt.root; <userinput>adduser -v</userinput> -Use option ``-silent'' if you don't want to see all warnings and questions. -Check /etc/shells -Check /etc/master.passwd -Check /etc/group -Enter your default shell: csh date no sh tcsh [sh]: <userinput>tcsh</userinput> -Your default shell is: tcsh -> /usr/local/bin/tcsh -Enter your default HOME partition: [/home]: -Copy dotfiles from: /usr/share/skel no [/usr/share/skel]: -Send message from file: /etc/adduser.message no -[/etc/adduser.message]: <userinput>no</userinput> -Do not send message -Use passwords (y/n) [y]: <userinput>y</userinput> - -Write your changes to /etc/adduser.conf? (y/n) [n]: <userinput>y</userinput> - -Ok, let's go. -Don't worry about mistakes. I will give you the chance later to correct any input. -Enter username [a-z0-9_-]: <userinput>jru</userinput> -Enter full name []: <userinput>J. Random User</userinput> -Enter shell csh date no sh tcsh [tcsh]: -Enter home directory (full path) [/home/jru]: -Uid [1001]: -Enter login class: default []: -Login group jru [jru]: -Login group is ``jru''. Invite jru into other groups: guest no -[no]: <userinput>wheel</userinput> -Enter password []: -Enter password again []: - -Name: jru -Password: **** -Fullname: J. Random User -Uid: 1007 -Gid: 1007 (jru) -Class: -Groups: jru wheel -HOME: /home/jru -Shell: /usr/local/bin/tcsh -OK? (y/n) [y]: <userinput>y</userinput> -Added user ``jru'' -Copy files from /usr/share/skel to /home/jru -Add another user? (y/n) [y]: <userinput>n</userinput> -Goodbye! -&prompt.root;</screen> - </example> - - <para>In summary, we changed the default shell to - <application>tcsh</application> (an additional shell found in - packages), and turned off the sending of a welcome mail to - added users. We then saved the configuration, and then - created an account for <username>jru</username>, and we made - sure <username>jru</username> is in <username>wheel</username> - group (which we'll see is important later).</para> - - <note> - <para>The password you type in isn't echoed, nor are asterisks - displayed. Make sure you don't mistype the password twice - :-)</para> - </note> - - <note> - <para>Just use <command>adduser</command> without arguments - from now on, and you won't have to go through changing the - defaults. If the program asks you to change the defaults, - exit the program, and try the <option>-s</option> - option.</para> - </note> - </sect2> - - <sect2 id="users-rmuser"> - <title>rmuser</title> - - <para><application>rmuser</application> removes users from the - system, including any traces beyond the user database.</para> - - <para><application>rmuser</application> performs the following - steps:</para> - - <procedure> - <step> - <para>Removes the user's &man.crontab.1; entry (if - any).</para> - </step> - <step> - <para>Removes any &man.at.1; jobs belonging to the - user.</para> - </step> - <step> - <para>Kills all processes owned by the user</para> - </step> - <step> - <para>Removes the user from the system's local password - file.</para> - </step> - <step> - <para>Removes the user's home directory (if it is owned by - the user)</para> - </step> - <step> - <para>Removes the incoming mail files belonging to the user - from <filename>/var/mail</filename>.</para> - </step> - <step> - <para>Removes all files owned by the user from temporary - file storage areas such as <filename>/tmp</filename>.</para> - </step> - <step> - <para>Finally, removes the username from all groups to which - it belongs in <filename>/etc/group</filename>. - - <note> - <para>If a group becomes empty and the group name is the - same as the username, the group is removed; this - complements the per-user unique groups created by - &man.adduser.8;.</para> - </note> - </para> - </step> - </procedure> - - <para><application>rmuser</application> can't be used to remove - superuser accounts, since that is almost always an indication - of massive destruction.</para> - - <para>By default, an interactive mode is used, which attempts to - make sure you know what you're doing.</para> - - <example> - <title>rmuser interactive account removal</title> - - <screen>&prompt.root; <userinput>rmuser jru</userinput> -Matching password entry: -jru:*:1000:1000::0:0:J. Random User:/home/jru:/usr/local/bin/tcsh -Is this the entry you wish to remove? <userinput>y</userinput> -Remove user's home directory (/home/jru)? <userinput>y</userinput> -Updating password file, updating databases, done. -Updating group file: trusted (removing group jru -- personal group is empty) done. -Removing user's incoming mail file /var/mail/jru: done. -Removing files belonging to jru from /tmp: done. -Removing files belonging to jru from /var/tmp: done. -Removing files belonging to jru from /var/tmp/vi.recover: done. -&prompt.root;</screen> - </example> - </sect2> - - <sect2 id="users-pw"> - <title>pw</title> - - <para><application>pw</application> is a command line utility to - create, remove, modify, and display users and groups, and - functions as an editor of the system user and group - files.</para> - - <para>It is designed to be useful both as a directly executed - command and for use from shell scripts.</para> - - <para>&man.pw.8; has all the information.</para> - </sect2> - - <sect2 id="users-chpass"> - <title>chpass</title> - - <para><application>chpass</application> changes user database - information such as passwords, shells, and personal - information.</para> - - <para>Only system administrators, as the superuser, may change - other users' information and passwords with chpass.</para> - - <para>Passed no options, besides the optional username, - <application>chpass</application> displays an editor - containing user information, and upon exit from the editor, - attempts to change the information in the user - database.</para> - - <example> - <title>Interactive chpass by Superuser</title> - - <screen>#Changing user database information for jru. -Login: jru -Password: * -Uid [#]: 1000 -Gid [# or name]: 1000 -Change [month day year]: -Expire [month day year]: -Class: -Home directory: /home/jru -Shell: /usr/local/bin/tcsh -Full Name: J. Random User -Office Location: -Office Phone: -Home Phone: -Other information:</screen> - </example> - - <para>The normal user can change only a small subsection of this - information, and only for themselves.</para> - - <example> - <title>Interactive chpass by Normal User</title> - - <screen>#Changing user database information for jru. -Shell: /usr/local/bin/tcsh -Full Name: J. Random User -Office Location: -Office Phone: -Home Phone: -Other information:</screen> - </example> - - <note> - <para><command>chfn</command> and <command>chsh</command> are - just links to chpass, as are <command>ypchpass</command>, - <command>ypchfn</command>, and - <command>ypchsh</command>. NIS support is automatic, so - specifying the <literal>yp</literal> before the command is - not necessary.</para> - </note> - </sect2> - <sect2 id="users-passwd"> - <title>passwd</title> - - <para><application>passwd</application> is the usual way to - change your own password as a user, or another user's password - as the superuser.</para> - - <note> - <para>Users must type in their original password before - changing their password, to prevent an unauthorized person - from changing their password when the user is away from - their console.</para> - </note> - - <example> - <title>passwd</title> - - <screen>&prompt.user; <userinput>passwd</userinput> -Changing local password for jru. -Old password: -New password: -Retype new password: -passwd: updating the database... -passwd: done - -&prompt.root; <userinput>passwd jru</userinput> -Changing local password for jru. -New password: -Retype new password: -passwd: updating the database... -passwd: done</screen> - </example> - - <note> - <para><command>yppasswd</command> is just a link to - <command>passwd</command>. NIS support is automatic, so - specifying the <literal>yp</literal> before the command is - not necessary.</para> - </note> - </sect2> - </sect1> - - <sect1 id="users-limiting-and-personalizing"> - <title>Limiting and Personalizing Users</title> - - <para>Quotas allow the system administrator to set disk usage - maximums, and users to check their disk usage, if quotas are - used on the system. Quotas are discussed in their <link - linkend="quotas">own chapter</link>.</para> - - <para>Localization is an environment set up by the system - administrator or user to accommodate different languages, - character sets, date and time standards, and so on. This is - discussed in the <link linkend="l10n">localization</link> - chapter.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml deleted file mode 100644 index 659c9f3d07..0000000000 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml +++ /dev/null @@ -1,1400 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/x11/chapter.sgml,v 1.12 2000/06/14 20:30:40 jim Exp $ ---> - -<chapter id="x11"> - <title>The X Window System</title> - - <para><emphasis>This chapter has been graciously donated by &a.grog; - from his book, <ulink - url="http://www.cdrom.com/titles/freebsd/bsdcomp_bkx.phtml">The - Complete FreeBSD</ulink>, and remains copyright of him. - Modifications for the handbook made by &a.jim;. The section on - fonts in XFree86 was contributed by &a.murray;.</emphasis></para> - - <sect1> - <title>Synopsis</title> - <para>The following chapter will cover installing and configuring X11 - on your system. For more information on X11 and to see whether your - video card is supported, check the <ulink - url="http://www.xfree86.org/">XFree86</ulink> web site.</para> - </sect1> - - <sect1 id="x-overview"> - <title>Overview</title> - - <para>FreeBSD comes with XFree86, a port of X11R6 that supports - several versions of Intel-based UNIX. This chapter describes how - to set up your XFree86 server. It is based on material supplied - with the FreeBSD release, specifically the files README.FreeBSD - and README.Config in the directory - <filename>/usr/X11R6/lib/X11/doc</filename>. If you find any - discrepancy, the material in those files will be more up-to-date - than this description. In addition, the file - <filename>/usr/X11R6/lib/X11/doc/RELNOTES</filename> contains - OS-independent information about the current release.</para> - - <para>X uses a lot of memory. In order to run X, your system should - have an absolute minimum of 8 MB of memory, but performance will be - painful with so little memory. A more practical minimum is 16 MB, - and you can improve performance by adding more memory. If you use - X intensively, you will continue seeing performance improvement by - increasing to as much as 128 MB of RAM.</para> - - <para>There is lots of useful information in the rest of this chapter, - but maybe you are not interested in information right now. You just - want to get your X server up and running. However, be warned:</para> - - <warning> - <para>An incorrect installation can burn out your monitor or your - video board.</para> - </warning> - - <para>However, if you know you are in spec, and you have a standard - Super VGA board and a good multi-frequency monitor, then you can - probably get things up and running without reading this - chapter.</para> - </sect1> - - <sect1 id="x-install"> - <title>Installing XFree86</title> - - <para>The easiest way to install XFree86 is with the sysinstall - program, either when you are installing the system, or later by - starting the program <command>/stand/sysinstall</command>. In the - rest of this chapter, we will look at what makes up the - distribution, and we will also take a look at manually installing - X11.</para> - - <sect2> - <title>The XFree86 Distribution</title> - - <para>XFree86 is distributed as a bewildering number of archives. - In the following section, we will take a look at what you should - install. Do not worry too much, though; if you cannot decide - what to pick and you have 200MB of disk space free, it's safe to - unpack everything.</para> - - <para>At a minimum you need to unpack the archives in the - following table and at least one server that matches your VGA - board. You will need 10Mb for the minimum required run-time - binaries only, and between 1.7 and 3 MB for the server.</para> - - <para>Below is a table of the required components.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>Xbin.tgz</filename></entry> - <entry>All the executable X client applications and shared - libraries.</entry> - </row> - - <row> - <entry><filename>Xfnts.tgz</filename></entry> - <entry>The misc and 75 dpi fonts.</entry> - </row> - - <row> - <entry><filename>Xlib.tgz</filename></entry> - <entry>Data files and libraries needed at runtime.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>The X Server</title> - - <para>In addition to the archives above, you need at least one - server, which will take up about 3 MB of disk. The choice - depends primarily on what kind of display board you have. The - default server name is <filename>/usr/X11R6/bin/X</filename>, and - it is a link to a specific server binary - <filename>/usr/X11R6/bin/XF86_xxxx</filename>. You will find the - server archives for the standard PC architecture in - <filename>/cdrom/XF86336/Servers</filename>, and the servers for - the Japanese PC98 architecture in - <filename>/cdrom/XF86336/PC98-Servers</filename> if you have the - CD set. Alternatively, they are available on our FTP site at - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/Servers/">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/Servers/</ulink> or <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/PC98-Servers/">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/PC98-Servers/</ulink></para> - - <para>Available X servers for the standard PC architecture:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>X8514.tgz</filename></entry> - <entry>8-bit color for IBM 8514 and true - compatibles.</entry> - </row> - - <row> - <entry><filename>XAGX.tgz</filename></entry> - <entry>8 and 16-bit color for AGX and XGA boards.</entry> - </row> - - <row> - <entry><filename>XI128.tgz</filename></entry> - <entry>8 and 16-bit color for I128 boards.</entry> - </row> - - <row> - <entry><filename>XMa32.tgz</filename></entry> - <entry>8 and 16-bit color for ATI Mach32 boards.</entry> - </row> - - <row> - <entry><filename>XMa64.tgz</filename></entry> - <entry>8, 16, and 32-bit color fot ATI Mach64 - boards.</entry> - </row> - - <row> - <entry><filename>XMa8.tgz</filename></entry> - <entry>8-bit color for ATI Mach8 boards.</entry> - </row> - - <row> - <entry><filename>XMono.tgz</filename></entry> - <entry>1-bit monochrome for VGA, Super-VGA, Hercules, and - others.</entry> - </row> - - <row> - <entry><filename>XP9K.tgz</filename></entry> - <entry>8, 16, and 32-bit color for Weitek P9000 boards - (Diamond Viper).</entry> - </row> - - <row> - <entry><filename>XS3.tgz</filename></entry> - <entry>8, 16, and 32-bit color for S3 boards.</entry> - </row> - - <row> - <entry><filename>XS3V.tgz</filename></entry> - <entry>8 and 16-bit color for S3 ViRGE boards.</entry> - </row> - - <row> - <entry><filename>XSVGA.tgz</filename></entry> - <entry>>=8-bit color for Super-VGA cards.</entry> - </row> - - <row> - <entry><filename>XVG16.tgz</filename></entry> - <entry>4-bit color for VGA and Super-VGA cards.</entry> - </row> - - <row> - <entry><filename>XW32.tgz</filename></entry> - <entry>8-bit color for ET4000/W32, /W32i, /W32p, and - ET6000 cards.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Available X servers for the Japanese PC98 architecture:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>X9GAN.tgz</filename></entry> - <entry>8-bit color for PC98 GA-98NB/WAP boards.</entry> - </row> - - <row> - <entry><filename>X9GA9.tgz</filename></entry> - <entry>8, 16, and 32-bit color for PC98 S3 GA-968 - boards.</entry> - </row> - - <row> - <entry><filename>X9480.tgz</filename></entry> - <entry>8-bit color for PC98 PEGC</entry> - </row> - - <row> - <entry><filename>X9NKV.tgz</filename></entry> - <entry>8-bit color for PC98 NEC-CIRRUS/EPSON NKV/NKV2 - boards.</entry> - </row> - - <row> - <entry><filename>X9WBS.tgz</filename></entry> - <entry>8-bit color for PC98 WAB-S boards.</entry> - </row> - - <row> - <entry><filename>X9WEP.tgz</filename></entry> - <entry>8-bit color for PC98 WAB-EP boards.</entry> - </row> - - <row> - <entry><filename>X9WSN.tgz</filename></entry> - <entry>8-bit color for PC98 WSN-A2F boards.</entry> - </row> - - <row> - <entry><filename>X9EGC.tgz</filename></entry> - <entry>4-bit color for PC98 EGC.</entry> - </row> - - <row> - <entry><filename>X9TGU.tgz</filename></entry> - <entry>8 and 16-bit color for PC98 Trident Cyber9320/9680 - boards.</entry> - </row> - - <row> - <entry><filename>X9NS3.tgz</filename></entry> - <entry>8 and 16-bit color for PC98 NEC S3 boards.</entry> - </row> - - <row> - <entry><filename>X9SPW.tgz</filename></entry> - <entry>8 and 16-bit color for PC98 S3 PW/PCSKB - boards.</entry> - </row> - - <row> - <entry><filename>X9LPW.tgz</filename></entry> - <entry>8 and 16-bit color for PC98 S3 PW/LB boards.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Each of these servers includes a manual page which contains - details of supported chipsets and server-specific configuration - options.</para> - - <para>There are also a number of archives are provided for X - programmers:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>Xprog.tgz</filename></entry> - <entry>Config, <filename>lib*.a</filename>, and - <filename>*.h</filename> files needed for compiling - clients.</entry> - </row> - - <row> - <entry><filename>Xctrb.tgz</filename></entry> - <entry>Contributed sources.</entry> - </row> - - <row> - <entry><filename>Xlk98.tgz</filename></entry> - <entry>The <quote>link kit</quote> for building servers, - Japanese PC98 version.</entry> - </row> - - <row> - <entry><filename>Xlkit.tgz</filename></entry> - <entry>The <quote>link kit</quote> for building servers, - normal PC architecture.</entry> - </row> - - <row> - <entry><filename>Xsrc-1.tgz</filename></entry> - <entry>Part 1 of the complete sources.</entry> - </row> - - <row> - <entry><filename>Xsrc-2.tgz</filename></entry> - <entry>Part 2 of the complete sources.</entry> - </row> - - <row> - <entry><filename>Xsrc-3.tgz</filename></entry> - <entry>Part 3 of the complete sources.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>You will need <filename>Xprog.tgz</filename> if you intend - to install ports of X software.</para> - </note> - - <para>XFree86 also includes a number of optional parts, such as - documentation, and setup programs.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>Xdoc.tgz</filename></entry> - <entry>READMEs</entry> - </row> - - <row> - <entry><filename>Xjdoc.tgz</filename></entry> - <entry>READMEs in Japanese.</entry> - </row> - - <row> - <entry><filename>Xps.tgz</filename></entry> - <entry>READMEs in PostScript.</entry> - </row> - - <row> - <entry><filename>Xhtml.tgz</filename></entry> - <entry>READMEs in HTML.</entry> - </row> - - <row> - <entry><filename>Xman.tgz</filename></entry> - <entry>Manual pages.</entry> - </row> - - <row> - <entry><filename>Xcfg.tgz</filename></entry> - <entry>Customizable <command>xinit</command> and - <command>xdm</command> runtime configuration - files.</entry> - </row> - - <row> - <entry><filename>Xset.tgz</filename></entry> - <entry>The <filename>X86Setup</filename> utility; a - graphical version of the <filename>xf86config</filename> - utility.</entry> - </row> - - <row> - <entry><filename>Xjset.tgz</filename></entry> - <entry>The <filename>XF86Setup</filename> utility, - Japanese version, for the normal PC architecture.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para><filename>XF86Setup</filename> is a graphical mode setup - program for XFree86, and you may prefer it to the standard setup - program <filename>xf86config</filename>. You do not need any - special archives for <filename>xf86config</filename>; it is - included in <filename>Xbin.tgz</filename>.</para> - - <para>The first time you install, you will need - <filename>Xcfg.tgz</filename> to create your initial configuration - files. Do not use it when upgrading; it overwrites your - configuration files.</para> - - <para>There are also additional fonts that are available with - XFree86:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>Xf100.tgz</filename></entry> - <entry>100 dpi fonts.</entry> - </row> - - <row> - <entry><filename>Xfscl.tgz</filename></entry> - <entry>Speedo and Type1 fonts.</entry> - </row> - - <row> - <entry><filename>Xfnon.tgz</filename></entry> - <entry>Japanese, Chinese, and other non-english - fonts.</entry> - </row> - - <row> - <entry><filename>Xfcyr.tgz</filename></entry> - <entry>Cyrillic fonts.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Unlike the X servers described above, the archives for the - following servers are all in the main directory.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Archive</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>Xfsrv.tgz</filename></entry> - <entry>The font server.</entry> - </row> - - <row> - <entry><filename>Xnest.tgz</filename></entry> - <entry>A nested server running as a client window on - another display.</entry> - </row> - - <row> - <entry><filename>Xprt.tgz</filename></entry> - <entry>The print server.</entry> - </row> - - <row> - <entry><filename>Xvfb.tgz</filename></entry> - <entry>The Virtual Framebuffer X server, which renders - into memory or an mmapped file.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Installing XFree86 Manually</title> - - <para>If you do not use sysinstall to install X, you need to perform - a number of steps:</para> - - <procedure> - <step> - <para>Create the directories and unpack the required - archives.</para> - </step> - - <step> - <para>Choose and install an X server.</para> - </step> - - <step> - <para>Set up the environment to be able to access X.</para> - </step> - - <step> - <para>Find a virtual terminal in which to run X.</para> - </step> - - <step> - <para>Configure X for your hardware.</para> - </step> - </procedure> - - <para>This sounds like a lot of work, but if you approach it - methodically, it is not too bad. In the rest of this section, - we will look at each step in turn.</para> - - <sect3> - <title>Unpacking the Archives</title> - - <para>You must unpack the archives as root, since a number of - the executables are set-user-id (they run as root even when - started by other users). If you unpack the server as an - ordinary user, it may abort when you try to run it. You must - also use a umask value of 022 (permissions rwxr-xr-x), because - the X server requires special permissions.</para> - - <screen>&prompt.user; <userinput>su</userinput> -Password: -&prompt.root; <userinput>umask 022</userinput></screen> - - <para>If you do not have enough space in the - <filename>/usr</filename> file system, create a directory on - another partition and symlink it to /usr. For example, if you - have a file system <filename>/home</filename> with adequate - space, you could do:</para> - - <screen>&prompt.root; <userinput>cd /home</userinput> -&prompt.root; <userinput>mkdir X11R6</userinput> -&prompt.root; <userinput>ln -s /home/X11R6 /usr/X11R6</userinput></screen> - - <para>Next, decide which archives you want to install. For a - minimal installation, choose <filename>Xbin.tgz</filename>, - <filename>Xfnts.tgz</filename>, <filename>Xlib.tgz</filename>, - and <filename>Xcfg.tgz</filename>. If you have already - configured X for your hardware, you can omit - <filename>Xcfg.tgz</filename>.</para> - - <para>If you are using sh, unpack like this:</para> - - <screen>&prompt.root; <userinput>mkdir -p /usr/X11R6</userinput> -&prompt.root; <userinput>cd /usr/X11R6</userinput> -&prompt.root; <userinput>for i in bin fnts lib cfg; do</userinput> -&prompt.root; <userinput> tar xzf X$i.tgz</userinput> -&prompt.root; <userinput>done</userinput></screen> - - <para>If you are using csh, enter:</para> - - <screen>&prompt.root; <userinput>mkdir -p /usr/X11R6</userinput> -&prompt.root; <userinput>cd /usr/X11R6</userinput> -&prompt.root; <userinput>foreach i (bin fnts lib cfg)</userinput> -<prompt>?</prompt> <userinput> tar xzf X$i.tgz</userinput> -<prompt>?</prompt> <userinput>end</userinput></screen> - </sect3> - - <sect3> - <title>Installing the Server</title> - - <para>Choose a server archive corresponding to your VGA board. - If the table in the section above does not give you enough - information, check the server man pages, - <filename>/usr/X11R6/man/man1/XF86_*</filename>, which list - the VGA chipsets supported by each server. For example, if - you have an ET4000 based board you will use the - <filename>XF86_SVGA</filename> server. In this case you - would enter:</para> - - <screen>&prompt.root; <userinput>cd /usr/X11R6</userinput> -&prompt.root; <userinput>tar xzf XSVGA.tgz [substitute your server name here]</userinput></screen> - </sect3> - - <sect3> - <title>Setting up the environment</title> - - <para>Next, you may wish to create a symbolic link - <filename>/usr/X11/bin/X</filename> that points to the server - that matches your video board. In this example, it is the - <filename>XF86_SVGA</filename> server:</para> - - <screen>&prompt.root; <userinput>cd /usr/X11R6/bin</userinput> -&prompt.root; <userinput>rm X</userinput> -&prompt.root; <userinput>ln -s XF86_SVGA X</userinput></screen> - - <para>X needs this symbolic link in order to be able to work - correctly, but you have the option of setting it when you run - <filename>xf86config</filename> – see below.</para> - - <para>Next, check that the directory - <filename>/usr/X11R6/bin</filename> is in the default path for - sh in <filename>/etc/profile</filename> and for csh in - <filename>/etc/csh.login</filename>, and add it if it is not. - It is best to do this with an editor, but if you want to take - a shortcut, you can enter:</para> - - <screen>&prompt.root; <userinput>echo 'PATH=$PATH:/usr/X11R6/bin' >>/etc/profile</userinput></screen> - - <para>or:</para> - - <screen>&prompt.root; <userinput>echo 'set path = ($path /usr/X11R6/bin)' >>/etc/csh.login</userinput></screen> - - <para>Alternatively, make sure everybody who uses X puts - <filename>/usr/X11R6/bin</filename> in their shell's - <envar>PATH</envar> variable.</para> - - <para>Next, invoke ldconfig to put the shared libraries in - <filename>ld.so</filename>'s cache:</para> - - <screen>&prompt.root; <userinput>ldconfig -m /usr/X11R6/lib</userinput></screen> - - <para>You can omit invoking <command>ldconfig</command> if you - plan to reboot before using X.</para> - - <para>You do not need to uncompress the font files, but if you - do, you must run <command>mkfontdir</command> in the - corresponding font directory, otherwise your server will abort - with the message <quote>could not open default font - `fixed'</quote>.</para> - </sect3> - - <sect3> - <title>Assigning a virtual terminal to X</title> - - <para>Next, make sure you have a spare virtual console which is - running a getty. First check how many virtual consoles you - have:</para> - - <screen>&prompt.root; <userinput>dmesg | grep virtual</userinput> -sc0: VGA color <16 virtual consoles, flags=0x0></screen> - - <para>Then check <filename>/etc/ttys</filename> to make sure - there is at least one virtual terminal (ttyvxx device) which - does not have a getty enabled. Look for the keyword - <literal>off</literal>:</para> - - <screen>&prompt.root; <userinput>grep ttyv /etc/ttys</userinput> -ttyv0 "/usr/libexec/getty Pc" cons25 on secure -ttyv1 "/usr/libexec/getty Pc" cons25 on secure -ttyv2 "/usr/libexec/getty Pc" cons25 on secure -ttyv3 "/usr/libexec/getty Pc" cons25 off secure</screen> - - <para>In this case, <filename>/dev/ttyv3</filename> is - available, if your kernel has least 4 VTs. If not, either - disable a getty in <filename>/etc/ttys</filename> by - changing on to off, or build another kernel with more virtual - terminals.</para> - </sect3> - - <sect3> - <title>Configuring X for Your Hardware</title> - - <para>After installing the X software, you will need to - customize the file <filename>XF86Config</filename>, which - tells the X server about your hardware and how you want to - run it.</para> - - <para>In order to set up <filename>XF86Config</filename>, you - will need the following hardware information:</para> - - <itemizedlist> - <listitem> - <para>Your mouse type, the bit rate if it is a serial mouse, - and the name of the device to which it is connected. This - will typically be <filename>/dev/ttyd0</filename> or - <filename>/dev/ttyd1</filename> for a serial mouse, - <filename>/dev/psm0</filename> for a PS/2 mouse, or - <filename>/dev/mse0</filename> for a bus mouse.</para> - </listitem> - - <listitem> - <para>The type of the video board and the amount of display - memory. If it is a no-name board, establish what VGA chip - set it uses.</para> - </listitem> - - <listitem> - <para>The parameters of your monitor; vertical and - horizontal frequency.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Identifying the hardware</title> - - <para>How do you decide what your hardware is? The manufacturer - should tell you, but very often the information you get about - your display board and monitor is pitiful; <quote>Super VGA - board with 76 Hz refresh rate and 16,777,216 colors</quote>. - This tells you the maximum pixel depth (24 bits – - the - number of colors is 2(pixel depth)), but it doesn't tell you - anything else about the display board.</para> - - <para>As we will see later, the real parameters you need to know - are the maximum horizontal frequency, the dot clock range, the - chipset and the amount of display memory.</para> - - <para>You could be unlucky trying to get some of this - information, but you can get some with the - <command>SuperProbe</command> program. It should always be - able to tell you the chipset and the amount of memory on - board.</para> - - <para>Occasionally <command>SuperProbe</command> can crash your - system. Make sure you are not doing anything important when - you run it. Running SuperProbe looks like this:</para> - - <screen>&prompt.root; <userinput>SuperProbe</userinput> -(warnings and acknowledgments omitted) -First video: Super-VGA - Chipset: Tseng ET4000 (Port Probed) - Memory: 1024 Kbytes - RAMDAC: Generic 8-bit pseudo-color DAC - (with 6-bit wide lookup tables (or in 6-bit mode))</screen> - - <para><command>SuperProbe</command> is very finicky about - running at all, and you will often get messages like:</para> - - <screen>SuperProbe: Cannot be run while an X server is running -SuperProbe: If an X server is not running, unset $DISPLAY and try again -SuperProbe: Cannot open video</screen> - - <para>In other words, even if no X server is running, - <command>SuperProbe</command> will not work if you have the - environment variable <envar>DISPLAY</envar> set. How do you - unset it? With Bourne-style shells, you enter:</para> - - <screen>&prompt.root; <userinput>unset DISPLAY</userinput></screen> - - <para>In the C shell, you enter:</para> - - <screen>&prompt.root; <userinput>unsetenv DISPLAY</userinput></screen> - </sect3> - - <sect3> - <title>Running <command>xf86config</command></title> - - <para>The easy way to create your configuration file is with one - of the utilities <command>xf86config</command> (note the lower - case name) or <command>XF86Setup</command>. Both lead you - through the configuration step by step. - <command>xf86config</command> runs in character mode, while - <command>XF86Setup</command> runs in a graphical mode. - <command>XF86Setup</command> can have problems with unusual - hardware, so I personally prefer - <command>xf86config</command>.</para> - - <para>You can also use sysinstall, but this does not change - much; <application>sysinstall</application> just starts - <command>xf86config</command> for you, and it is easier to - start it directly. In this section, we will use an example to - illustrate configuration via <command>xf86config</command>. - We are installing X for an ancient Diamond SpeedStar with 1 MB - of display memory, a Logitech MouseMan mouse, and an ADI - MicroScan 5AP monitor. The mouse is connected to the system - via the first serial port, - <filename>/dev/ttyd0</filename>.</para> - - <para>To run <command>xf86config</command>, type in the name. If - <filename>/usr/X11R6/bin</filename> is included in your - <envar>PATH</envar> environment variable, you just need to type - <command>xf86config</command>. If it is not, you need to type - out the full path to <command>xf86config</command>, like - so:</para> - - <screen>&prompt.root; <userinput>/usr/X11R6/bin/xf86config</userinput></screen> - - <para>This program will create a basic - <filename>XF86Config</filename>file, based on menu selections - you make.</para> - - <para>The <filename>XF86Config</filename> file usually resides - in <filename>/usr/X11R6/lib/X11</filename> or - <filename>/etc</filename>. A sample - <filename>XF86Config</filename> file is supplied with XFree86; - it is configured for a standard VGA card and monitor with - 640x480 resolution. This program will ask for a pathname when - it is ready to write the file.</para> - - <para>You can either take the sample - <filename>XF86Config</filename> as a base and edit it for your - configuration, or let this program produce a base - <filename>XF86Config</filename> file for your configuration - and fine-tune it. Refer to - <filename>/usr/X11R6/lib/X11/doc/README.Config</filename> for - a detailed overview of the configuration process.</para> - - <para>For accelerated servers (including accelerated drivers in - the SVGA server), there are many chipset and card-specific - options and settings. This program does not know about these. - On some configurations some of these settings must be - specified. Refer to the server man pages and chipset-specific - READMEs.</para> - - <para>Before continuing with this program, make sure you know - the chipset and amount of video memory on your video card. - <command>SuperProbe</command> can help with this. It is also - helpful if you know what server you want to run.</para> - - <screen>Press enter to continue, or ctrl-c to abort. ENTER - -First specify a mouse protocol type. Choose one from the following list: - - 1. Microsoft compatible (2-button protocol) - 2. Mouse Systems (3-button protocol) - 3. Bus Mouse - 4. PS/2 Mouse - 5. Logitech Mouse (serial, old type, Logitech protocol) - 6. Logitech MouseMan (Microsoft compatible) - 7. MM Series - 8. MM HitTablet - 9. Microsoft IntelliMouse</screen> - - <para>If you have a two-button mouse, it is most likely of type - 1, and if you have a three-button mouse, it can probably - support both protocol 1 and 2. There are two main varieties - of the latter type; mice with a switch to select the protocol, - and mice that default to 1 and require a button to be held at - boot-time to select protocol 2. Some mice can be convinced to - do 2 by sending a special sequence to the serial port (see the - ClearDTR/ClearRTS options).</para> - - <screen>Enter a protocol number: 6 Logitech MouseMan - -You have selected a Logitech MouseMan type mouse. You might want to enable -ChordMiddle which could cause the third button to work. - -Please answer the following question with either 'y' or 'n'. -Do you want to enable ChordMiddle? n</screen> - - <para>You definitely want to enable the third button on your - mouse, since many X clients use it. With a genuine Logitech - mouse, however, you don't need to enable - <literal>ChordMiddle</literal> in order to use the button. If - you find that the third button does not work when you start X, - you can enable <literal>ChordMiddle</literal> by editing the - configuration file – it is much easier and less - error-prone than re-running <command>XF86Setup</command>.</para> - - <para>Continuing through the setup:</para> - - <screen>If your mouse has only two buttons, it is recommended that you enable Emulate3Buttons. - -Please answer the following question with either 'y' or 'n'. -Do you want to enable Emulate3Buttons? n - -Now give the full device name that the mouse is connected to, for example -/dev/tty00. Just pressing enter will use the default, /dev/mouse. - -Mouse device: /dev/ttyd1</screen> - - <para>Be very careful about this entry. You must specify the - correct name for the device to which the mouse is connected. - <command>xf86config</command> is not specific to FreeBSD, and - the suggested example is just plain wrong for FreeBSD. Use - the names <filename>/dev/ttyd0</filename> through - <filename>/dev/ttyd3</filename> for serial mice, - <filename>/dev/psm0</filename> for PS/2 mice or - <filename>/dev/mse0</filename> for a bus mouse.</para> - - <para>Continuing, we see:</para> - - <screen>Beginning with XFree86 3.1.2D, you can use the new X11R6.1 -XKEYBOARD extension to manage the keyboard layout. If you answer 'n' to the -following question, the server will use the old method, and you have to -adjust your keyboard layout with xmodmap. - -Please answer the following question with either 'y' or 'n'. -Do you want to use XKB? y - -The following dialogue will allow you to select from a list of already -preconfigured keymaps. If you don't find a suitable keymap in the list, -the program will try to combine a keymap from additional information you -are asked then. Such a keymap is by default untested and may require -manual tuning. Please report success or required changes for such a -keymap to XFREE86@XFREE86.ORG for addition to the list of preconfigured -keymaps in the future. - -Press enter to continue, or ctrl-c to abort. - -List of preconfigured keymaps: - - 1 Standard 101-key, US encoding - 2 Microsoft Natural, US encoding - 3 KeyTronic FlexPro, US encoding - 4 Standard 101-key, US encoding with ISO9995-3 extensions - 5 Standard 101-key, German encoding - 6 Standard 101-key, French encoding - 7 Standard 101-key, Thai encoding - 8 Standard 101-key, Swiss/German encoding - 9 Standard 101-key, Swiss/French encoding - 10 None of the above - -Enter a number to choose the keymap. - -1 Choose the standard US keyboard</screen> - - <para>Now we want to set the specifications of the monitor. The - two critical parameters are the vertical refresh rate, which - is the rate at which the the whole screen is refreshed, and - most importantly the horizontal sync rate, which is the rate - at which scanlines are displayed.</para> - - <para>The valid range for horizontal sync and vertical sync - should be documented in the manual of your monitor. If in - doubt, check the monitor database - <filename>/usr/X11R6/lib/X11/doc/Monitors</filename> to see if - your monitor is there.</para> - - <screen>Press enter to continue, or ctrl-c to abort. ENTER - -You must indicate the horizontal sync range of your monitor. You can either -select one of the predefined ranges below that correspond to industry- -standard monitor types, or give a specific range. - -It is VERY IMPORTANT that you do not specify a monitor type with a horizontal -sync range that is beyond the capabilities of your monitor. If in doubt, -choose a conservative setting. - - hsync in kHz; monitor type with characteristic modes - 1 31.5; Standard VGA, 640x480 @@ 60 Hz - 2 31.5 - 35.1; Super VGA, 800x600 @@ 56 Hz - 3 31.5, 35.5; 8514 Compatible, 1024x768 @@ 87 Hz interlaced (no 800x600) - 4 31.5, 35.15, 35.5; Super VGA, 1024x768 @@ 87 Hz interlaced, 800x600 @@ 56 Hz - 5 31.5 - 37.9; Extended Super VGA, 800x600 @@ 60 Hz, 640x480 @@ 72 Hz - 6 31.5 - 48.5; Non-Interlaced SVGA, 1024x768 @@ 60 Hz, 800x600 @@ 72 Hz - 7 31.5 - 57.0; High Frequency SVGA, 1024x768 @@ 70 Hz - 8 31.5 - 64.3; Monitor that can do 1280x1024 @@ 60 Hz - 9 31.5 - 79.0; Monitor that can do 1280x1024 @@ 74 Hz -10 31.5 - 82.0; Monitor that can do 1280x1024 @@ 76 Hz -11 Enter your own horizontal sync range - -Enter your choice (1-11):</screen> - - <para>Unfortunately, our monitor is not mentioned in the file - <filename>/usr/X11R6/lib/X11/doc/Monitors</filename>, but by - chance the manual does specify the frequency range in the - Technical Data section. The horizontal frequency range is - from 30 to 64 kHz, and the vertical frequency range is from - 50 to 100 Hz. The horizontal frequency range is almost - exactly covered by choice 8, but that setting threatens to go - 0.3 kHz higher in frequency than the technical data state. Do - you want to risk it? Doing so will most likely not be a - problem, since it is unlikely that the monitor will die at - such a small deviation from the specs, and it is also unlikely - that your <filename>XF86Config</filename> will actually - generate a horizontal frequency between 64.0 and 64.3 kHz. - However, there is no need to take even this slight risk. Just - specify the real values:</para> - - <screen>Enter your choice (1-11): 11 - -Please enter the horizontal sync range of your monitor, in the format used -in the table of monitor types above. You can either specify one or more -continuous ranges (e.g. 15-25, 30-50), or one or more fixed sync -frequencies. - -Horizontal sync range: 30-64</screen> - - <para>Next, we select the vertical frequency range:</para> - - <screen>You must indicate the vertical sync range of your monitor. -You can either select one of the predefined ranges below that correspond -to industry-standard monitor types, or give a specific range. For -interlaced modes, the number that counts is the high one (e.g., 87 Hz -rather than 43 Hz). - - 1 50-70 - 2 50-90 - 3 50-100 - 4 40-150 - 5 Enter your own vertical sync range - -Enter your choice: 3 exactly the range of the monitor</screen> - - <para>The next step is to specify identification strings. You - can think out names if you want, but unless you are juggling a - lot of different hardware, you can let - <command>xf86config</command> do it for you:</para> - - <screen>You must now enter a few identification/description strings, -namely an identifier, a vendor name, and a model name. Just pressing enter -will fill in default names. - -The strings are free-form, spaces are allowed. -Enter an identifier for your monitor definition: ENTER -Enter the vendor name of your monitor: ENTER -Enter the model name of your monitor: ENTER</screen> - - <para>Next comes the choice of the video board. We have an - elderly Diamond SpeedStar Plus with an ET4000 chip, and - unknown Ramdac and Clock Chip. Let's see how we fare:</para> - - <screen>Now we must configure video card specific settings. At -this point you can choose to make a selection out of a database of video -card definitions. Because there can be variation in Ramdacs and clock -generators even between cards of the same model, it is not sensible to -blindly copy the settings (e.g., a Device section). For this reason, -after you make a selection, you will still be asked about the components -of the card, with the settings from the chosen database entry presented as -a strong hint. - -The database entries include information about the chipset, what server to -run, the Ramdac and ClockChip, and comments that will be included in the -Device section. However, a lot of definitions only hint about what server -to run (based on the chipset the card uses) and are untested. - -If you can't find your card in the database, there's nothing to worry about. -You should only choose a database entry that is exactly the same model as -your card; choosing one that looks similar is just a bad idea (e.g. a -GemStone Snail 64 may be as different from a GemStone Snail 64+ in terms of -hardware as can be). - -Do you want to look at the card database? y - 0 2 the Max MAXColor S3 Trio64V+ S3 Trio64V+ - 1 928Movie S3 928 - 2 AGX (generic) AGX-014/15/16 - 3 ALG-5434(E) CL-GD5434 - 4 ASUS 3Dexplorer RIVA128 - 5 ASUS PCI-AV264CT ATI-Mach64 - 6 ASUS PCI-V264CT ATI-Mach64 - 7 ASUS Video Magic PCI V864 S3 864 - 8 ASUS Video Magic PCI VT64 S3 Trio64 - 9 AT25 Alliance AT3D - 10 AT3D Alliance AT3D - 11 ATI 3D Pro Turbo ATI-Mach64 - 12 ATI 3D Xpression ATI-Mach64 - 13 ATI 3D Xpression+ PC2TV ATI-Mach64 - 14 ATI 8514 Ultra (no VGA) ATI-Mach8 - 15 ATI All-in-Wonder ATI-Mach64 - 16 ATI Graphics Pro Turbo ATI-Mach64 - 17 ATI Graphics Pro Turbo 1600 ATI-Mach64 - -Enter a number to choose the corresponding card definition. -Press enter for the next page, q to continue configuration. -ENTER</screen> - - <para>Dozens of board definitions come in alphabetic order. - Finally we see:</para> - - <screen>108 DSV3325 S3 ViRGE -109 DSV3326 S3 Trio64V+ -110 DataExpert DSV3325 S3 ViRGE -111 DataExpert DSV3365 S3 Trio64V+ -112 Dell S3 805 S3 801/805 -113 Dell onboard ET4000 ET4000 -114 Diamond Edge 3D nv1 -115 Diamond Multimedia Stealth 3D 2000 S3 ViRGE -116 Diamond Multimedia Stealth 3D 2000 PRO S3 ViRGE/DX -117 Diamond SpeedStar (Plus) ET4000 -118 Diamond SpeedStar 24 ET4000 -119 Diamond SpeedStar 24X (not fully supported) WD90C31 -120 Diamond SpeedStar 64 CL-GD5434 -121 Diamond SpeedStar HiColor ET4000 -122 Diamond SpeedStar Pro (not SE) CL-GD5426/28 -123 Diamond SpeedStar Pro 1100 CL-GD5420/2/4/6/8/9 -124 Diamond SpeedStar Pro SE (CL-GD5430/5434) CL-GD5430/5434 -125 Diamond SpeedStar64 Graphics 2000/2200 CL-GD5434 - -Enter a number to choose the corresponding card definition. -Press enter for the next page, q to continue configuration. - -117 - -Your selected card definition: - -Identifier: Diamond SpeedStar (Plus) -Chipset: ET4000 -Server: XF86_SVGA - -Press enter to continue, or ctrl-c to abort.ENTER - -Now you must determine which server to run. Refer to the man pages and -other documentation. The following servers are available (they may not -all be installed on your system): - - 1 The XF86_Mono server. This a monochrome server that should work on any - VGA-compatible card, in 640x480 (more on some SVGA chipsets). - 2 The XF86_VGA16 server. This is a 16-color VGA server that should work on - any VGA-compatible card. - 3 The XF86_SVGA server. This is a 256 color SVGA server that supports - a number of SVGA chipsets. On some chipsets it is accelerated or - supports higher color depths. - 4 The accelerated servers. These include XF86_S3, XF86_Mach32, XF86_Mach8, - XF86_8514, XF86_P9000, XF86_AGX, XF86_W32, XF86_Mach64, XF86_I128 and - XF86_S3V. - -These four server types correspond to the four different "Screen" sections in -XF86Config (vga2, vga16, svga, accel). - - 5 Choose the server from the card definition, XF86_SVGA. - -Which one of these screen types do you intend to run by default (1-5)?</screen> - - <para>The system already chose XF86_SVGA for us. Do we want to - change? We would need a good reason. In this case, we do not - have a reason, so we will keep the server from the card - definition:</para> - - <screen>Which one of these screen types do you intend to run by default (1-5)? 5 - -The server to run is selected by changing the symbolic link 'X'. For example, -the SVGA server. - -Please answer the following question with either 'y' or 'n'. -Do you want me to set the symbolic link? y</screen> - - <para>All the programs that start X (xinit, startx, and xdm) - start a program <filename>/usr/X11R6/bin/X</filename>. This - symbolic link makes <filename>/usr/X11R6/bin/X</filename> - point to your X server. If you don't have a link, you will - not be able to start X.</para> - - <screen>Now you must give information about your video card. This -will be used for the "Device" section of your video card in XF86Config. - -You must indicate how much video memory you have. It is probably a good -idea to use the same approximate amount as that detected by the server you -intend to use. If you encounter problems that are due to the used server -not supporting the amount memory you have (e.g. ATI Mach64 is limited to -1024K with the SVGA server), specify the maximum amount supported by the -server. - -How much video memory do you have on your video card: - - 1 256K - 2 512K - 3 1024K - 4 2048K - 5 4096K - 6 Other - -Enter your choice: 3 - -You must now enter a few identification/description strings, namely an -identifier, a vendor name, and a model name. Just pressing enter will fill -in default names (possibly from a card definition). - -Your card definition is Diamond SpeedStar (Plus). - -The strings are free-form, spaces are allowed. -Enter an identifier for your video card definition: ENTER -You can simply press enter here if you have a generic card, or want to -describe your card with one string. -Enter the vendor name of your video card: ENTER -Enter the model (board) name of your video card: ENTER - -Especially for accelerated servers, Ramdac, Dacspeed and ClockChip settings -or special options may be required in the Device section. - -The RAMDAC setting only applies to the S3, AGX, W32 servers, and some -drivers in the SVGA servers. Some RAMDAC's are auto-detected by the server. -The detection of a RAMDAC is forced by using a Ramdac "identifier" line in -the Device section. The identifiers are shown at the right of the following -table of RAMDAC types: - - 1 AT&T 20C490 (S3 and AGX servers, ARK driver) att20c490 - 2 AT&T 20C498/21C498/22C498 (S3, autodetected) att20c498 - 3 AT&T 20C409/20C499 (S3, autodetected) att20c409 - 4 AT&T 20C505 (S3) att20c505 - 5 BrookTree BT481 (AGX) bt481 - 6 BrookTree BT482 (AGX) bt482 - 7 BrookTree BT485/9485 (S3) bt485 - 8 Sierra SC15025 (S3, AGX) sc15025 - 9 S3 GenDAC (86C708) (autodetected) s3gendac - 10 S3 SDAC (86C716) (autodetected) s3_sdac - 11 STG-1700 (S3, autodetected) stg1700 - 12 STG-1703 (S3, autodetected) stg1703 - - -Enter a number to choose the corresponding RAMDAC. -Press enter for the next page, q to quit without selection of a RAMDAC. - - -q We don't need this - - -A Clockchip line in the Device section forces the detection of a -programmable clock device. With a clockchip enabled, any required -clock can be programmed without requiring probing of clocks or a -Clocks line. Most cards don't have a programmable clock chip. -Choose from the following list: - - 1 Chrontel 8391 ch8391 - 2 ICD2061A and compatibles (ICS9161A, DCS2824) icd2061a - 3 ICS2595 ics2595 - 4 ICS5342 (similar to SDAC, but not completely compatible) ics5342 - 5 ICS5341 ics5341 - 6 S3 GenDAC (86C708) and ICS5300 (autodetected) s3gendac - 7 S3 SDAC (86C716) s3_sdac - 8 STG 1703 (autodetected) stg1703 - 9 Sierra SC11412 sc11412 -10 TI 3025 (autodetected) ti3025 -11 TI 3026 (autodetected) ti3026 -12 IBM RGB 51x/52x (autodetected) ibm_rgb5xx - -Just press enter if you don't want a Clockchip setting. -What Clockchip setting do you want (1-12)? ENTER - -For most configurations, a Clocks line is useful since it prevents the slow -and nasty sounding clock probing at server start-up. Probed clocks are -displayed at server startup, along with other server and hardware -configuration info. You can save this information in a file by running -imprecise; some clocks may be slightly too high (varies per run). - -At this point I can run X -probeonly, and try to extract the clock information -from the output. It is recommended that you do this yourself and add a clocks -line (note that the list of clocks may be split over multiple Clocks lines) to -your Device section afterwards. Be aware that a clocks line is not -appropriate for drivers that have a fixed set of clocks and don't probe by -default (e.g. Cirrus). Also, for the P9000 server you must simply specify -clocks line that matches the modes you want to use. For the S3 server with -a programmable clock chip you need a 'ClockChip' line and no Clocks line. - -You must be root to be able to run X -probeonly now. - -Do you want me to run 'X -probeonly' now?</screen> - - <para>This last question is worth thinking about. You should - run X -probeonly at some point, but it requires some extra - work. We'll take the recommendation and try it later.</para> - - <screen>Do you want me to run 'X -probeonly' now? n - -For each depth, a list of modes (resolutions) is defined. The default -resolution that the server will start-up with will be the first listed -mode that can be supported by the monitor and card. -Currently it is set to: - -"640x480" "800x600" "1024x768" for 8bpp -"640x480" "800x600" for 16bpp -"640x480" for 24bpp -"640x400" for 32bpp - -Note that 16, 24 and 32bpp are only supported on a few configurations. -Modes that cannot be supported due to monitor or clock constraints will -be automatically skipped by the server. - - 1 Change the modes for 8pp (256 colors) - 2 Change the modes for 16bpp (32K/64K colors) - 3 Change the modes for 24bpp (24-bit color, packed pixel) - 4 Change the modes for 32bpp (24-bit color) - 5 The modes are OK, continue. - -Enter your choice: 5 accept the defaults - -You can have a virtual screen (desktop), which is screen area that is larger -than the physical screen and which is panned by moving the mouse to the edge -of the screen. If you don't want virtual desktop at a certain resolution, -you cannot have modes listed that are larger. Each color depth can have a -differently-sized virtual screen - -Please answer the following question with either 'y' or 'n'. -Do you want a virtual screen that is larger than the physical screen? n</screen> - - <para>It is difficult to decide whether you want a virtual - screen larger than the physical screen. I find it extremely - disturbing, so I suggest you answer n. You might find it - useful, especially if your highest resolution is small.</para> - - <para>Now the configuration is complete, and - <application>sysinstall</application> just need to write the - configuration file:</para> - - <screen>I am going to write the XF86Config file now. Make sure -you don't accidently overwrite a previously configured one. - -Shall I write it to /etc/XF86Config? y - -File has been written. Take a look at it before running 'startx'. Note that -the XF86Config file must be in one of the directories searched by the server -(e.g. /usr/X11R6/lib/X11) in order to be used. Within the server press -ctrl, alt and '+' simultaneously to cycle video resolutions. Pressing ctrl, -alt and backspace simultaneously immediately exits the server (use if -the monitor doesn't sync for a particular mode). - -For further configuration, refer to /usr/X11R6/lib/X11/doc/README.Config.</screen> - - <para>Once you have completed this configuration, you are ready to - start X.</para> - </sect3> - </sect2> - </sect1> - - <sect1 id="x-fonts"> - <title>Using Fonts in XFree86</title> - - <sect2 id="truetype"> - <title>TrueType Fonts</title> - - <para>The default fonts that ship with - <application>XFree86</application> are less than ideal for typical - desktop publishing applications. Large presentation fonts show up - jagged and unprofessional looking and small fonts in Netscape are - almost completely unintelligable. Fortunately, - <application>XFree86</application> can be configured to use - TrueType fonts with a minimum of effort.</para> - - <para><application>XFree86</application> 4.0 has built in support - for rendering TrueType fonts. There are two different modules - that can enable this functionality. The "freetype" module is used - in this example because it is more consistent with the other font - rendering backends. To enable the freetype module just add the - following line to the module section of your - <filename>/etc/X11/XF86Config</filename> file. -<screen> - Load "freetype" -</screen> - </para> - - <para>For <application>XFree86</application> 3.3.X you will need - to run a seperate TrueType font - server. <application>Xfstt</application> is commonly used for this - purpose. To install <application>Xfstt</application> on your - FreeBSD system simply install the port from - <filename>/usr/ports/x11-servers/Xfstt</filename></para> - - <para>You should now make a directory for your TrueType fonts - (e.g. <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>) and - copy all of your TrueType fonts into this directory. Keep in mind - that you can not take TrueType fonts directly from a Macintosh; - they must be in Unix/DOS/Windows format for use by - <application>XFree86</application>. Once you have copied the files - into this directory you need to use - <application>ttmkfdir</application> to create a - <filename>fonts.dir</filename> file so that the X font renderer - knows that you've installed these new files. There is a FreeBSD - port for <application>ttmkfdir</application> in - <filename>/usr/ports/x11-fonts/ttmkfdir</filename>.</para> -<screen> - &prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput> - &prompt.root; <userinput>ttmkfdir > fonts.dir</userinput> -</screen> - - <para>Now you need to add your TrueType directory to your fonts - path. The easiest way to do this is to add the following entries - into your <filename>~/.xinitrc</filename> file.</para> -<screen> - &prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput> - &prompt.user; <userinput>xset fp rehash</userinput> -</screen> - - <para>That's it. Now Netscape, Gimp, StarOffice, and all of your - other X applications should now recognize your installed TrueType - fonts. Extremely small fonts (as with text in a high resolution - display on a web page) and extremely large fonts (within - StarOffice) will look much better now.</para> - - <para>One Caveat : XFree86 does not currently support anti-aliased - font rendering. This is less of an issue at higher screen resolutions - but the output is still less than optimal when compared with MacOS or - Microsoft Windows.</para> - - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO8859-1/books/porters-handbook/Makefile b/en_US.ISO8859-1/books/porters-handbook/Makefile deleted file mode 100644 index 4557e616bf..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/books/porter-handbook/Makefile,v 1.1 2000/04/22 23:47:57 nik Exp $ -# -# Build the FreeBSD Porter's Handbook. -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml - -# Use the local DSSSL file -DSLHTML?= ${.CURDIR}/freebsd.dsl -DSLPRINT?= ${.CURDIR}/freebsd.dsl - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml deleted file mode 100644 index ae62a53b4b..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ /dev/null @@ -1,4399 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v 1.131 2000/10/03 22:29:31 bmah Exp $ ---> - -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> -%bookinfo; - -<!ENTITY % authors SYSTEM "../handbook/authors.ent"> %authors; -<!ENTITY % mailing-lists SYSTEM "../handbook/mailing-lists.ent"> -%mailing-lists; - -]> - -<book> - <bookinfo> - <title>FreeBSD Porter's Handbook</title> - - <authorgroup> - <corpauthor>The FreeBSD Documentation Project</corpauthor> - </authorgroup> - - <pubdate>April 2000</pubdate> - - <copyright> - <year>2000</year> - <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation - Project</holder> - </copyright> - - &bookinfo.legalnotice; - </bookinfo> - - - <chapter> - <title>Making a port yourself</title> - - <para>So, now you are interested in making your own port or - upgrading an existing one? Great!</para> - - <para>What follows are some guidelines for creating a new port for - FreeBSD. If you want to upgrade an existing port, you should - read this and then read <xref linkend="port-upgrading">.</para> - - <para>When this document is not sufficiently detailed, you should - refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which - all port Makefiles include. Even if you do not hack Makefiles - daily, it is well commented, and you will still gain much - knowledge from it. Additionally, you may send specific questions - to the &a.ports;.</para> - - <note> - <para>Only a fraction of the variables - (<makevar><replaceable>VAR</replaceable></makevar>) that can be - overridden are mentioned in this document. Most (if not all) - are documented at the start of <filename>bsd.port.mk</filename>. - This file uses a non-standard tab setting. - <application>Emacs</application> and - <application>Vim</application> should recognize the setting on - loading the file. Both <command>vi</command> and - <command>ex</command> can be set to use the correct value by - typing <command>:set tabstop=4</command> once the file has been - loaded.</para> - </note> - </chapter> - - <chapter id="quick-porting"> - <title>Quick Porting</title> - - <para>This section tells you how to do a quick port. In many cases, it - is not enough, but we will see.</para> - - <para>First, get the original tarball and put it into - <makevar>DISTDIR</makevar>, which defaults to - <filename>/usr/ports/distfiles</filename>.</para> - - <note> - <para>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 will - have to refer to the next section too.</para> - </note> - - <sect1> - <title>Writing the <filename>Makefile</filename></title> - - <para>The minimal <filename>Makefile</filename> would look something - like this:</para> - - <programlisting> -# New ports collection makefile for: oneko -# Date created: 5 December 1994 -# Whom: asami -# -# $FreeBSD$ -# - -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= asami@FreeBSD.org - -MAN1= oneko.1 -MANCOMPRESSED= yes -USE_IMAKE= yes - -.include <bsd.port.mk></programlisting> - - <para>See if you can figure it out. Do not worry about the contents - of the <literal>$FreeBSD$</literal> line, it will be - filled in automatically by CVS when the port is imported to our main - ports tree. You can find a more detailed example in the <link - linkend="porting-samplem">sample Makefile</link> section.</para> - </sect1> - - <sect1> - <title>Writing the description files</title> - - <para>There are three description files that are required for - any port, whether they actually package or not. They are - <filename>pkg-comment</filename>, - <filename>pkg-descr</filename>, and - <filename>pkg-plist</filename>, and their - <filename>pkg-</filename> prefix distinguishes them from - other files.</para> - - <sect2> - <title><filename>pkg-comment</filename></title> - - <para>This is the one-line description of the port. - <emphasis>Please</emphasis> do not include the package name (or - version number of the software) in the comment. The comment - should begin with a capital, and end without a period. Here - is an example:</para> - - <programlisting> -A cat chasing a mouse all over the screen</programlisting> - </sect2> - - <sect2> - <title><filename>pkg-descr</filename></title> - - <para>This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient.</para> - - <note> - <para>This is <emphasis>not</emphasis> a manual or an in-depth - description on how to use or compile the port! <emphasis>Please - be careful if you are copying from the - <filename>README</filename> or manpage</emphasis>; too often - they are not a concise description of the port or are in an - awkward format (e.g., manpages have justified spacing). If the - ported software has an official WWW homepage, you should list it - here. Prefix <emphasis>one</emphasis> of the websites with - <literal>WWW:</literal> so that automated tools will work - correctly.</para> - </note> - - <para>It is recommended that you sign your name at the end of this - file, as in:</para> - - <programlisting> -This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/ - -- Satoshi -asami@cs.berkeley.edu</programlisting> - </sect2> - - <sect2> - <title><filename>pkg-plist</filename></title> - - <para>This file lists all the files installed by the port. It is - also called the “packing list” because the package is - generated by packing the files listed here. The pathnames are - relative to the installation prefix (usually - <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename>). If you are using the - <makevar>MAN<replaceable>n</replaceable></makevar> variables (as - you should be), do not list any manpages here.</para> - - <para>Here is a small example:</para> - - <programlisting> -bin/oneko -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko</programlisting> - - <para>Refer to the &man.pkg.create.1; man page for details on the - packing list.</para> - - <note> - <para>You should list all the files, but not the name directories, - in the list. Also, if the port creates directories for itself - during installation, make sure to add <literal>@dirrm</literal> - lines as necessary to remove them when the port is - deleted.</para> - - <para>It is recommended that you keep all the filenames in this - file sorted alphabetically. It will make verifying the changes - when you upgrade the port much easier.</para> - - <para>Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, <link - linkend="porting-autoplist">creating the packing list - automatically</link> might save time.</para> - </note> - </sect2> - </sect1> - - <sect1> - <title>Creating the checksum file</title> - - <para>Just type <command>make makesum</command>. The ports make rules - will automatically generate the file - <filename>distinfo</filename>.</para> - </sect1> - - <sect1 id="porting-testing"> - <title>Testing the port</title> - - <para>You should make sure that the port rules do exactly what you - want them to do, including packaging up the port. These are the - important points you need to verify.</para> - - <itemizedlist> - <listitem> - <para><filename>pkg-plist</filename> does not contain anything not - installed by your port</para> - </listitem> - - <listitem> - <para><filename>pkg-plist</filename> contains everything that is - installed by your port</para> - </listitem> - - <listitem> - <para>Your port can be installed multiple times using the - <maketarget>reinstall</maketarget> target</para> - </listitem> - - <listitem> - <para>Your port <link linkend="porting-cleaning">cleans up</link> - after itself upon deinstall</para> - </listitem> - </itemizedlist> - - <procedure> - <title>Recommended test ordering</title> - - <step> - <para><command>make install</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>pkg_add <replaceable>package-name</replaceable> - </command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>make reinstall</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - </procedure> - - <para>Make sure that there are not any warnings issued in any of the - <maketarget>package</maketarget> and - <maketarget>deinstall</maketarget> stages. After step 3, check to - see if all the new directories are correctly deleted. Also, try - using the software after step 4, to ensure that it works correctly - when installed from a package.</para> - </sect1> - - <sect1 id="porting-portlint"> - <title>Checking your port with <command>portlint</command></title> - - <para>Please use <command>portlint</command> to see if your port - conforms to our guidelines. The <command>portlint</command> program - is part of the ports collection. In particular, you may want to - check if the <link linkend="porting-samplem">Makefile</link> is in - the right shape and the <link - linkend="porting-pkgname">package</link> is named - appropriately.</para> - </sect1> - - <sect1 id="porting-submitting"> - <title>Submitting the port</title> - - <para>First, make sure you have read the <link - linkend="porting-dads">DOs and DON'Ts</link> section.</para> - - <para>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. We do not need your <filename>work</filename> - directory or the <filename>pkgname.tgz</filename> package, so delete - them now. Next, simply include the output of <command>shar `find - port_dir`</command> in a bug report and send it with the - &man.send-pr.1; program (see <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink> for more information about - &man.send-pr.1;. If the uncompressed port is larger than 20KB, - you should compress it into a tarfile and use &man.uuencode.1; - before including it in the bug report (uuencoded tarfiles are - acceptable even if the bug report is smaller than 20KB but are not - preferred). Be sure to classify the bug report as category - <literal>ports</literal> and class - <literal>change-request</literal> (Do not mark the report - <literal>confidential</literal>!). - Also add a short description of the program you ported - to the <quote>Description</quote> field of the PR and - the shar or uuencoded tarfile to the - <quote>Fix</quote> field. The latter one helps the committers - a lot, who use scripts for the ports-work.</para> - - <para>One more time, <emphasis>do not include the original source - distfile, the <filename>work</filename> directory, or the package - you built with <command>make package</command></emphasis>.</para> - - <note> - <para>In the past, we asked you to upload new port submissions in - our ftp site (<hostid role="fqdn">ftp.FreeBSD.org</hostid>). This - is no longer recommended as read access is turned off on the - <filename>incoming/</filename> directory of that site due to the - large amount of pirated software showing up there.</para> - </note> - - <para>We will look at your port, get back to you if necessary, and put - it in the tree. Your name will also appear in the list of - “Additional FreeBSD contributors” in the FreeBSD - Handbook and other files. Isn't that great?!? <!-- smiley - -->:-)</para> - - <note> - <para>You can make our work a lot easier, if you use a good - description in the synopsis of the problem report. - We prefer something like - “New port: <short description of the port>” for - new ports and - “Update port: <category>/<port> <short description - of the update>” for port updates. - If you stick to this scheme, the chance that one takes a look at - your PR soon is much bigger.</para> - </note> - </sect1> - </chapter> - - <chapter> - <title>Slow Porting</title> - - <para>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.</para> - - <sect1> - <title>How things work</title> - - <para>First, this is the sequence of events which occurs when the user - first types <command>make</command> in your port's directory. - You may find that having <filename>bsd.port.mk</filename> in another - window while you read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people do... - <!-- smiley --><emphasis>:-></emphasis></para> - - <procedure> - - <step> - <para>The <maketarget>fetch</maketarget> target is run. The - <maketarget>fetch</maketarget> target is responsible for making - sure that the tarball exists locally in - <makevar>DISTDIR</makevar>. If <maketarget>fetch</maketarget> - cannot find the required files in <makevar>DISTDIR</makevar> it - will look up the URL <makevar>MASTER_SITES</makevar>, which is - set in the Makefile, as well as our main ftp site at <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</ulink>, - where we put sanctioned distfiles as backup. It will then - attempt to fetch the named distribution file with - <makevar>FETCH</makevar>, assuming that the requesting site has - direct access to the Internet. If that succeeds, it will save - the file in <makevar>DISTDIR</makevar> for future use and - proceed.</para> - </step> - - <step> - <para>The <maketarget>extract</maketarget> target is run. It - looks for your port's distribution file (typically a gzip'd - tarball) in <makevar>DISTDIR</makevar> and unpacks it into a - temporary subdirectory specified by <makevar>WRKDIR</makevar> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <maketarget>patch</maketarget> target is run. First, - any patches defined in <makevar>PATCHFILES</makevar> are - applied. Second, if any patch files named - <filename>patch-<replaceable>*</replaceable></filename> are found in - <makevar>PATCHDIR</makevar> (defaults to the - <filename>files</filename> subdirectory), they are applied at - this time in alphabetical order.</para> - </step> - - <step> - <para>The <maketarget>configure</maketarget> target is run. This - can do any one of many different things.</para> - - <orderedlist> - <listitem> - <para>If it exists, <filename>scripts/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> is - run.</para> - </listitem> - - <listitem> - <para>If <makevar>USE_IMAKE</makevar> is set, - <makevar>XMKMF</makevar> (default: <command>xmkmf - -a</command>) is run.</para> - </listitem> - </orderedlist> - </step> - - <step> - <para>The <maketarget>build</maketarget> target is run. This is - responsible for descending into the port's private working - directory (<makevar>WRKSRC</makevar>) and building it. If - <makevar>USE_GMAKE</makevar> is set, GNU <command>make</command> - will be used, otherwise the system <command>make</command> will - be used.</para> - </step> - </procedure> - - <para>The above are the default actions. In addition, you can define - targets - <maketarget>pre-<replaceable>something</replaceable></maketarget> or - <maketarget>post-<replaceable>something</replaceable></maketarget>, - or put scripts with those names, in the <filename>scripts</filename> - subdirectory, and they will be run before or after the default - actions are done.</para> - - <para>For example, if you have a <maketarget>post-extract</maketarget> - target defined in your Makefile, and a file - <filename>pre-build</filename> in the <filename>scripts</filename> - subdirectory, the <maketarget>post-extract</maketarget> target will - be called after the regular extraction actions, and the - <filename>pre-build</filename> script will be executed before the - default build rules are done. It is recommended that you use - <filename>Makefile</filename> targets if the actions are simple - enough, because it will be easier for someone to figure out what - kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets - <maketarget>do-<replaceable>something</replaceable></maketarget>. - For example, the commands to extract a port are in the target - <maketarget>do-extract</maketarget>. If you are not happy with the - default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> - target in your <filename>Makefile</filename>.</para> - - <note> - <para>The “main” targets (e.g., - <maketarget>extract</maketarget>, - <maketarget>configure</maketarget>, etc.) do nothing more than - make sure all the stages up to that one are completed and call - the real targets or scripts, and they are not intended to be - changed. If you want to fix the extraction, fix - <maketarget>do-extract</maketarget>, but never ever touch - <maketarget>extract</maketarget>!</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make</command>, let us go through the recommended steps to - create the perfect port.</para> - </sect1> - - <sect1> - <title>Getting the original sources</title> - - <para>Get the original sources (normally) as a compressed tarball - (<filename><replaceable>foo</replaceable>.tar.gz</filename> or - <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy - it into <makevar>DISTDIR</makevar>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>If you cannot find a ftp/http site that is well-connected to the - net, or can only find sites that have irritatingly non-standard - formats, you might want to put a copy on a reliable ftp or http - server that you control (e.g., your home page). Make sure you set - <makevar>MASTER_SITES</makevar> to reflect your choice.</para> - - <para>If you cannot find somewhere convenient and reliable to put the - distfile - we can “house” it ourselves - on <hostid>ftp.FreeBSD.org</hostid>. - The distfile must be placed into - <filename>~/public_distfiles/</filename> of someone's - <hostid>freefall</hostid> account. - Ask the person who commits your port to do this. - This person will also set <makevar>MASTER_SITES</makevar> to - <makevar>MASTER_SITE_LOCAL</makevar> and - <makevar>MASTER_SITE_SUBDIR</makevar> to their - <hostid>freefall</hostid> username.</para> - - <para>If your port's distfile changes all the time for no good reason, - consider putting the distfile in your home page and listing it as - the first <makevar>MASTER_SITES</makevar>. This will prevent users - from getting <errorname>checksum mismatch</errorname> errors, and - also reduce the workload of maintainers of our ftp site. Also, if - there is only one master site for the port, it is recommended that - you house a backup at your site and list it as the second - <makevar>MASTER_SITES</makevar>.</para> - - <para>If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - <makevar>DISTDIR</makevar>. Do not worry if they come from a site - other than where you got the main source tarball, we have a way to - handle these situations (see the description of <link - linkend="porting-patchfiles">PATCHFILES</link> below).</para> - </sect1> - - <sect1> - <title>Modifying the port</title> - - <para>Unpack a copy of the tarball in a private directory and make - whatever changes are necessary to get the port to compile properly - under the current version of FreeBSD. Keep <emphasis>careful - track</emphasis> of everything you do, as you will be automating - the process shortly. Everything, including the deletion, addition, - or modification of files should be doable using an automated script - or patch file when your port is finished.</para> - - <para>If your port requires significant user interaction/customization - to compile or install, you should take a look at one of Larry Wall's - classic <application>Configure</application> scripts and perhaps do - something similar yourself. The goal of the new ports collection is - to make each port as “plug-and-play” as possible for the - end-user while using a minimum of disk space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and other - files you have created and contributed to the FreeBSD ports - collection are assumed to be covered by the standard BSD copyright - conditions.</para> - </note> - </sect1> - - <sect1> - <title>Patching</title> - - <para>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. Each set of patches you wish to apply should be collected - into a file named - <filename>patch-<replaceable>*</replaceable></filename> where - <replaceable>*</replaceable> denotes the sequence in which the - patches will be applied — these are done in - <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal> - first, <literal>ab</literal> second and so on. If you wish, - you can use names that indicate the pathnames of the files that - are patched, such as <filename>patch-Imakefile</filename> or - <filename>patch-src-config.h</filename>. These files should - be stored in <makevar>PATCHDIR</makevar>, from where they will be - automatically applied. All patches should be relative to - <makevar>WRKSRC</makevar> (generally the directory your port's - tarball unpacks itself into, that being where the build is done). - To make fixes and upgrades easier, you should avoid having more than - one patch fix the same file (e.g., <filename>patch-aa</filename> and - <filename>patch-ab</filename> both changing - <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para> - </sect1> - - <sect1> - <title>Configuring</title> - - <para>Include any additional customization commands in your - <filename>configure</filename> script and save it in the - <filename>scripts</filename> subdirectory. As mentioned above, you - can also do this with <filename>Makefile</filename> targets and/or - scripts with the name <filename>pre-configure</filename> or - <filename>post-configure</filename>.</para> - </sect1> - - <sect1> - <title>Handling user input</title> - - <para>If your port requires user input to build, configure, or install, - then set <makevar>IS_INTERACTIVE</makevar> in your Makefile. This - will allow “overnight builds” to skip your port if the - user sets the variable <envar>BATCH</envar> in his environment (and - if the user sets the variable <envar>INTERACTIVE</envar>, then - <emphasis>only</emphasis> those ports requiring interaction are - built).</para> - - <para>It is also recommended that if there are reasonable default - answers to the questions, you check the - <makevar>PACKAGE_BUILDING</makevar> variable and turn off the - interactive script when it is set. This will allow us to build the - packages for CD-ROMs and ftp.</para> - </sect1> - </chapter> - - <chapter> - <title>Configuring the Makefile</title> - - <para>Configuring the Makefile is pretty simple, and again we suggest - that you look at existing examples before starting. Also, there is a - <link linkend="porting-samplem">sample Makefile</link> in this - handbook, so take a look and please follow the ordering of variables - and sections in that template to make your port easier for others to - read.</para> - - <para>Now, consider the following problems in sequence as you design - your new Makefile:</para> - - <sect1> - <title>The original source</title> - - <para>Does it live in <makevar>DISTDIR</makevar> as a standard - gzip'd tarball named something like - <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on - to the next step. If not, you should look at overriding any of - the <makevar>DISTNAME</makevar>, <makevar>EXTRACT_CMD</makevar>, - <makevar>EXTRACT_BEFORE_ARGS</makevar>, - <makevar>EXTRACT_AFTER_ARGS</makevar>, - <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> - variables, depending on how alien a format your port's - distribution file is. (The most common case is - <literal>EXTRACT_SUFX=.tar.Z</literal>, when the tarball is - condensed by regular <command>compress</command>, not - <command>gzip</command>.)</para> - - <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override the - default, though this should be rarely, if ever, - necessary.</para> - </sect1> - - <sect1> - <title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title> - - <para>You should set <makevar>PORTNAME</makevar> to the - base name of your port, and <makevar>PORTVERSION</makevar> - to the version number of the port.</para> - </sect1> - - <sect1> - <title><makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar></title> - - <sect2> - <title><makevar>PORTREVISION</makevar></title> - - <para>The <makevar>PORTREVISION</makevar> variable is a - monotonically increasing value which is reset to 0 with - every increase of <makevar>PORTVERSION</makevar> (i.e. - every time a new official vendor release is made), and - appended to the package name if non-zero. - <makevar>PORTREVISION</makevar> is increased each time a - change is made to the FreeBSD port which significantly - affects the content or stucture of the derived - package.</para> - - <para>Examples of when PORTREVISION should be bumped:</para> - - <itemizedlist> - <listitem> - <para>Addition of patches to correct security - vulnerabilities, bugs, or to add new functionality to - the FreeBSD port.</para> - </listitem> - - <listitem> - <para>Changes to the port makefile to enable or disable - compile-time options in the package.</para> - </listitem> - - <listitem> - <para>Changes in the packing list or the install-time - behaviour of the package (e.g. change to a script - which generates initial data for the package, like ssh - host keys).</para> - </listitem> - - <listitem> - <para>Version bump of a port's shared library dependency - (in this case, someone trying to install the old - package after installing a newer version of the - dependency will fail since it will look for the old - libfoo.x instead of libfoo.(x+1)).</para> - </listitem> - - <listitem> - <para>Silent changes to the port distfile which have - significant functional differences, i.e. changes to - the distfile requiring a correction to - <filename>distinfo</filename> with no corresponding change to - <makevar>PORTVERSION</makevar>, where a <command>diff - -ru</command> of the old and new versions shows - non-trivial changes to the code.</para> - </listitem> - </itemizedlist> - - <para>Examples of changes which do not require a - <makevar>PORTREVISION</makevar> bump:</para> - - <itemizedlist> - <listitem> - <para>Style changes to the port skeleton with no - functional change to what appears in the resulting - package.</para> - </listitem> - - <listitem> - <para>Changes to <makevar>MASTER_SITES</makevar> or - other functional changes to the port which do not - effect the resulting package.</para> - </listitem> - - <listitem> - <para>Trivial patches to the distfile such as correction - of typos, which are not important enough that users of - the package should go to the trouble of - upgrading.</para> - </listitem> - - <listitem> - <para>Build fixes which cause a package to become - compilable where it was previously failing (as long as - the changes do not introduce any functional change on - any other platforms on which the port did previously - build). Since <makevar>PORTREVISION</makevar> reflects - the content of the package, if no package was - previously buildable then there is no need to increase - <makevar>PORTREVISION</makevar> to mark a - change.</para> - </listitem> - </itemizedlist> - - <para>A rule of thumb is to ask yourself whether a change - committed to a port is something which someone, somewhere, - would benefit from having (either because of an - enhancement, fix, or by virtue that the new package will - actually work for them). If yes, the - <makevar>PORTREVISION</makevar> should be bumped so that - automated tools (e.g. <command>pkg_version</command>) - will highlight the fact that a new package is - available.</para> - </sect2> - - <sect2> - <title><makevar>PORTEPOCH</makevar></title> - - <para>From time to time a software vendor or FreeBSD porter - will do something silly and release a version of their - software which is actually numerically less than the - previous version. An example of this is a port which goes - from foo-20000801 to foo-1.0 (the former will be - incorrectly treated as a newer version since 20000801 is a - numerically greater value than 1).</para> - - <para>In situations such as this, the - <makevar>PORTEPOCH</makevar> version should be increased. - If <makevar>PORTEPOCH</makevar> is nonzero it is appended - to the package name as described in section 0 above. - <makevar>PORTEPOCH</makevar> is never decreased or reset - to zero, because that would cause comparison to a package - from an earlier epoch to fail (i.e. the package would not - be detected as out of date): the new version number (e.g. - <literal>1.0,1</literal> in the above example) is still - numerically less than the previous version (2000801), but - the <literal>,1</literal> suffix is treated specially by - automated tools and found to be greater than the implied - suffix ",0" on the earlier package)</para> - - <para>It is expected that <makevar>PORTEPOCH</makevar> will - not be used for the majority of ports, and that sensible - use of <makevar>PORTVERSION</makevar> can often pre-empt - it becoming necessary if a future release of the software - should change the version structure. However, care is - needed by FreeBSD porters when a vendor release is made - without an official version number - such as a code - "snapshot" release. The temptation is to label the - release with the release date, which will cause problems - as in the example above when a new "official" release is - made.</para> - - <para>For example, if a snapshot release is made on the date - 20000917, and the previous version of the software was - version 1.2, the snapshot release should be given a - <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar, - not 20000917, so that the succeeding release, say 1.3, is - still a numerically greater value.</para> - </sect2> - - <sect2> - <title>Example of <makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar> usage</title> - - <para>The gtkmumble port, version 0.10, is committed to the - ports collection.</para> - - <programlisting> -PORTNAME= gtkmumble -PORTVERSION= 0.10</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.10</literal>.</para> - - <para>A security hole is discovered which requires a local - FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped - accordingly.</para> - - <programlisting> -PORTNAME= gtkmumble -PORTVERSIOn= 0.10 -PORTREVISION= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.10_1</literal></para> - - <para>A new version is released by the vendor, numbered 0.2 - (it turns out the author actually intended - <literal>0.10</literal> to actually mean - <literal>0.1.0</literal>, not <quote>what comes after - 0.9</quote> - oops, too late now). Since the new minor - version <literal>2</literal> is numerically less than the - previous version <literal>10</literal> the - <makevar>PORTEPOCH</makevar> must be bumped to manually - force the new package to be detected as "newer". Since it - is a new vendor release of the code, - <makevar>PORTREVISION</makevar> is reset to 0 (or removed - from the makefile).</para> - - <programlisting> -PORTNAME= gtkmumble -PORTVERSION= 0.2 -PORTEPOCH= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.2,1</literal></para> - - <para>The next release is 0.3. Since - <makevar>PORTEPOCH</makevar> never decreases, the version - variables are now:</para> - - <programlisting> -PORTNAME= gtkmumble -PORTVERSION= 0.3 -PORTEPOCH= 1</programlisting> - - <para><makevar>PKGNAME</makevar> becomes - <literal>gtkmumble-0.3,1</literal></para> - - <note> - <para>If <makevar>PORTEPOCH</makevar> were reset - to <literal>0</literal> with this upgrade, someone who had - installed the gtkmumble-0.10_1 package would not detect - the gtkmumble-0.3 package as newer, since - <literal>3</literal> is still numerically less than - <literal>10</literal>.</para> - </note> - </sect2> - </sect1> - - <sect1> - <title><makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar></title> - - <para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar>, are combined with - <makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar> to - form <makevar>PKGNAME</makevar> as - <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. - Make sure this conforms to our <link - linkend="porting-pkgname">guidelines for a good package - name</link>. In particular, you are not allowed to use a - hyphen (<literal>-</literal>) in - <makevar>PORTVERSION</makevar>. Also, if the package name - has the <replaceable>language-</replaceable> or the - <replaceable>compiled.specifics</replaceable> part, use - <makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make - them part of <makevar>PORTNAME</makevar>.</para> - </sect1> - - <sect1> - <title><makevar>DISTNAME</makevar></title> - - <para><makevar>DISTNAME</makevar> is the name of the port as - called by the authors of the software. - <makevar>DISTNAME</makevar> defaults to - <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it if necessary. - <makevar>DISTNAME</makevar> is only used in two places. - First, the distribution file list - (<makevar>DISTFILES</makevar>) defaults to - <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>. - Second, the distribution file is expected to extract into a - subdirectory named <makevar>WRKSRC</makevar>, which defaults - to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para> - - <note> - <para><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar> do not affect - <makevar>DISTNAME</makevar>. Also note that when - <makevar>WRKSRC</makevar> is equal to - <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename> - while the original source archive is named something other than - <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>, - you should probably leave <makevar>DISTNAME</makevar> - alone— you are better off defining - <makevar>DISTFILES</makevar> than having to set both - <makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar> - (and possibly <makevar>EXTRACT_SUFX</makevar>).</para> - </note> - </sect1> - - <sect1> - <title><makevar>CATEGORIES</makevar></title> - - <para>When a package is created, it is put under - <filename>/usr/ports/packages/All</filename> and links are made from - one or more subdirectories of - <filename>/usr/ports/packages</filename>. The names of these - subdirectories are specified by the variable - <makevar>CATEGORIES</makevar>. It is intended to make life easier - for the user when he is wading through the pile of packages on the - ftp site or the CD-ROM. Please take a look at the existing <link - linkend="porting-categories">categories</link> and pick the ones - that are suitable for your port.</para> - - <para>This list also determines where in the ports tree the port is - imported. If you put more than one category here, it is assumed - that the port files will be put in the subdirectory with the name in - the first category. See the <link - linkend="porting-categories">categories</link> section for more - discussion about how to pick the right categories.</para> - - <para>If your port truly belongs to something that is different from - all the existing ones, you can even create a new category name. In - that case, please send mail to the &a.ports; to propose a new - category.</para> - </sect1> - - <sect1> - <title><makevar>MASTER_SITES</makevar></title> - - <para>Record the directory part of the ftp/http-URL pointing at the - original tarball in <makevar>MASTER_SITES</makevar>. Do not forget - the trailing slash (<filename>/</filename>)!</para> - - <para>The <command>make</command> macros will try to use this - specification for grabbing the distribution file with - <makevar>FETCH</makevar> if they cannot find it already on the - system.</para> - - <para>It is recommended that you put multiple sites on this list, - preferably from different continents. This will safeguard against - wide-area network problems, and we are even planning to add support - for automatically determining the closest master site and fetching - from there!</para> - - <para>If the original tarball is part of one of the popular - archives such as X-contrib, GNU, or Perl CPAN, you may be able - refer to those sites in an easy compact form using - <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar> - (e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and - <makevar>MASTER_SITE_PERL_GNU</makevar>). Simply set - <makevar>MASTER_SITES</makevar> to one of these variables and - <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the - archive. Here is an example:</para> - - <programlisting> -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> - - <para>These variables are defined in - <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are - new archives added all the time, so make sure to check the - latest version of this file before submitting a port.</para> - - <para>The user can also set the <makevar>MASTER_SITE_*</makevar> - variables in <filename>/etc/make.conf</filename> to override our - choices, and use their favorite mirrors of these popular archives - instead.</para> - </sect1> - - <sect1 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></title> - - <para>If your port requires some additional patches that are available - by ftp or http, set <makevar>PATCHFILES</makevar> to the names of - the files and <makevar>PATCH_SITES</makevar> to the URL of the - directory that contains them (the format is the same as - <makevar>MASTER_SITES</makevar>).</para> - - <para>If the patch is not relative to the top of the source tree - (i.e., <makevar>WRKSRC</makevar>) because it contains some extra - pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly. For - instance, if all the pathnames in the patch have an extra - <literal>foozolix-1.0/</literal> in front of the filenames, then set - <literal>PATCH_DIST_STRIP=-p1</literal>.</para> - - <para>Do not worry if the patches are compressed; they will be - decompressed automatically if the filenames end with - <filename>.gz</filename> or <filename>.Z</filename>.</para> - - <para>If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you cannot just use - <makevar>PATCHFILES</makevar>. If that is the case, add the name - and the location of the patch tarball to - <makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>. - Then, use the <makevar>EXTRA_PATCHES</makevar> variable to - point to those files and <filename>bsd.port.mk</filename> - will automatically apply them for you. In particular, do - <emphasis>not</emphasis> copy patch files into the - <makevar>PATCHDIR</makevar> directory—that directory may - not be writable.</para> - - <note> - <para>Note that the tarball will have been extracted alongside the - regular source by then, so there is no need to explicitly extract - it if it is a regular gzip'd or compress'd tarball. If you do the - latter, take extra care not to overwrite something that already - exists in that directory. Also, do not forget to add a command to - remove the copied patch in the <maketarget>pre-clean</maketarget> - target.</para> - </note> - </sect1> - - <sect1> - <title><makevar>MAINTAINER</makevar></title> - - <para>Set your mail-address here. Please. <!-- smiley - --><emphasis>:-)</emphasis></para> - - <para>For a detailed description of the responsibilities of maintainers, - refer to the <ulink url="../handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on - Makefiles</ulink> section.</para> - </sect1> - - <sect1> - <title>Dependencies</title> - - <para>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. There are also some pre-supported dependency - variables for common cases, plus a few more to control the behaviour - of dependencies.</para> - - <sect2> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>This variable specifies the shared libraries this port depends - on. It is a list of - <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples where <replaceable>lib</replaceable> is the name of the - shared library, <replaceable>dir</replaceable> is the - directory in which to find it in case it is not available, and - <replaceable>target</replaceable> is the target to call in that - directory. For example, <programlisting> LIB_DEPENDS= - jpeg.9:${PORTSDIR}/graphics/jpeg:install</programlisting> - will check for a shared jpeg library with major version 9, and - descend into the <filename>graphics/jpeg</filename> subdirectory - of your ports tree to build and install it if it is not found. - The <replaceable>target</replaceable> part can be omitted if it is - equal to <makevar>DEPENDS_TARGET</makevar> (which defaults to - <literal>install</literal>).</para> - - <note> - <para>The <replaceable>lib</replaceable> part is an argument given - to <command>ldconfig -r | grep -wF</command>. There shall be no - regular expressions in this variable.</para> - </note> - - <para>The dependency is checked twice, once from within the - <maketarget>extract</maketarget> target and then from within the - <maketarget>install</maketarget> target. Also, the name of the - dependency is put into the package so that - <command>pkg_add</command> will automatically install it if it is - not on the user's system.</para> - </sect2> - - <sect2> - <title><makevar>RUN_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port depends - on during run-time. It is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples where <replaceable>path</replaceable> is the name of the - executable or file, <replaceable>dir</replaceable> is the - directory in which to find it in case it is not available, and - <replaceable>target</replaceable> is the target to call in that - directory. If <replaceable>path</replaceable> starts with a slash - (<literal>/</literal>), it is treated as a file and its existence - is tested with <command>test -e</command>; otherwise, it is - assumed to be an executable, and <command>which -s</command> is - used to determine if the program exists in the user's search - path.</para> - - <para>For example,</para> - - <programlisting> -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting> - - <para>will check if the file or directory - <filename>/usr/local/etc/innd</filename> exists, and build and - install it from the <filename>news/inn</filename> subdirectory of - the ports tree if it is not found. It will also see if an - executable called <command>wish8.0</command> is in your search - path, and descend into the <filename>x11-toolkits/tk80</filename> - subdirectory of your ports tree to build and install it if it is - not found.</para> - - <note> - <para>In this case, <command>innd</command> is actually an - executable; if an executable is in a place that is not expected - to be in a normal user's search path, you should use the full - pathname.</para> - </note> - - <para>The dependency is checked from within the - <maketarget>install</maketarget> target. Also, the name of the - dependency is put in to the package so that - <command>pkg_add</command> will automatically install it if it is - not on the user's system. The <replaceable>target</replaceable> - part can be omitted if it is the same as - <makevar>DEPENDS_TARGET</makevar>.</para> - </sect2> - - <sect2> - <title><makevar>BUILD_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is a - list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples. For example, <programlisting> BUILD_DEPENDS= - unzip:${PORTSDIR}/archivers/unzip</programlisting> will check - for an executable called <command>unzip</command>, and descend - into the <filename>archivers/unzip</filename> subdirectory of your - ports tree to build and install it if it is not found.</para> - - <note> - <para>“build” here means everything from extraction to - compilation. The dependency is checked from within the - <maketarget>extract</maketarget> target. The - <replaceable>target</replaceable> part can be omitted if it is - the same as <makevar>DEPENDS_TARGET</makevar></para> - </note> - </sect2> - - <sect2> - <title><makevar>FETCH_DEPENDS</makevar></title> - - <para>This variable specifies executables or files this port - requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> - tuples. For example, <programlisting> FETCH_DEPENDS= - ncftp2:${PORTSDIR}/net/ncftp2</programlisting> will check for an - executable called <command>ncftp2</command>, and descend into the - <filename>net/ncftp2</filename> subdirectory of your ports tree to - build and install it if it is not found.</para> - - <para>The dependency is checked from within the - <maketarget>fetch</maketarget> target. The - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect2> - - <sect2> - <title><makevar>DEPENDS</makevar></title> - - <para>If there is a dependency that does not fall into either of the - above four categories, or your port requires having the source of - the other port extracted in addition to having it installed, - then use this variable. This is a list of - <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, - as there is nothing to check, unlike the previous four. The - <replaceable>target</replaceable> part can be omitted if it is the - same as <makevar>DEPENDS_TARGET</makevar>.</para> - </sect2> - - <sect2> - <title>Common dependency variables</title> - - <para>Define <literal>USE_XLIB=yes</literal> if your port requires - the X Window System to be installed (it is implied by - <makevar>USE_IMAKE</makevar>). Define - <literal>USE_GMAKE=yes</literal> if your port requires GNU - <command>make</command> instead of BSD <command>make</command>. - Define <literal>USE_AUTOCONF=yes</literal> if your port requires - GNU autoconf to be run. Define <literal>USE_QT=yes</literal> if - your port uses the latest qt toolkit. Use - <literal>USE_PERL5=yes</literal> if your port requires version 5 - of the perl language. (The last is especially important since - some versions of FreeBSD have perl5 as part of the base system - while others do not.)</para> - </sect2> - - <sect2> - <title>Notes on dependencies</title> - - <para>As mentioned above, the default target to call when a - dependency is required is <maketarget>DEPENDS_TARGET</maketarget>. - It defaults to <literal>install</literal>. This is a user - variable; it is never defined in a port's - <filename>Makefile</filename>. If your port needs a special way - to handle a dependency, use the <literal>:target</literal> part of - the <makevar>*_DEPENDS</makevar> variables instead of redefining - <makevar>DEPENDS_TARGET</makevar>.</para> - - <para>When you type <command>make clean</command>, its dependencies - are automatically cleaned too. If you do not wish this to happen, - define the variable <makevar>NOCLEANDEPENDS</makevar> in your - environment.</para> - - <para>To depend on another port unconditionally, use the - variable <makevar>${NONEXISTENT}</makevar> as the first field - of <makevar>BUILD_DEPENDS</makevar> or - <makevar>RUN_DEPENDS</makevar>. Use this only when you need to - the to get to the source of the other port. You can often save - compilation time by specifying the target too. For - instance - - <programlisting> -BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting> - - will always descend to the JPEG port and extract it.</para> - - <para>Do not use <makevar>DEPENDS</makevar> unless there is no other - way the behaviour you want can be accomplished. It will cause the - other port to always be built (and installed, by default), and the - dependency will go into the packages as well. If this is really - what you need, I recommend you write it as - <literal>BUILD_DEPENDS</literal> and - <literal>RUN_DEPENDS</literal> instead—at least the - intention will be clear.</para> - </sect2> - </sect1> - - <sect1> - <title>Building mechanisms</title> - - <para>If your package uses GNU <command>make</command>, set - <literal>USE_GMAKE=yes</literal>. If your package uses - <command>configure</command>, set - <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU - <command>configure</command>, set - <literal>GNU_CONFIGURE=yes</literal> (this implies - <literal>HAS_CONFIGURE</literal>). If you want to give some extra - arguments to <command>configure</command> (the default argument list - <literal>--prefix=${PREFIX}</literal> for GNU - <command>configure</command> and empty for non-GNU - <command>configure</command>), set those extra arguments in - <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU - <command>autoconf</command>, set - <literal>USE_AUTOCONF=yes</literal>. This implies - <makevar>GNU_CONFIGURE</makevar>, and will cause - <command>autoconf</command> to be run before - <command>configure</command>.</para> - - <para>If your package is an X application that creates - <filename>Makefile</filename>s from <filename>Imakefile</filename>s - using <command>imake</command>, then set - <literal>USE_IMAKE=yes</literal>. This will cause the configure - stage to automatically do an <command>xmkmf -a</command>. If the - <option>-a</option> flag is a problem for your port, set - <literal>XMKMF=xmkmf</literal>. If the port uses - <command>imake</command> but does not understand the - <maketarget>install.man</maketarget> target, - <literal>NO_INSTALL_MANPAGES=yes</literal> should be set. In - addition, the author of the original port should be shot. <!-- - smiley --><emphasis>:-></emphasis></para> - - <para>If your port's source <filename>Makefile</filename> has - something else than <maketarget>all</maketarget> as the main build - target, set <makevar>ALL_TARGET</makevar> accordingly. Same goes - for <maketarget>install</maketarget> and - <makevar>INSTALL_TARGET</makevar>.</para> - </sect1> - </chapter> - - <chapter> - <title>Special considerations</title> - - <para>There are some more things you have to take into account when you - create a port. This section explains the most common of those.</para> - - <sect1 id="porting-shlibs"> - <title>Shared Libraries</title> - - <para>If your port installs one or more shared libraries, define a - <makevar>INSTALLS_SHLIB</makevar> make variable, which will instruct - a <filename>bsd.port.mk</filename> to run - <literal>${LDCONFIG} -m</literal> on the directory where the - new library is installed (usually - <filename><makevar>PREFIX</makevar>/lib</filename>) during - <maketarget>post-install</maketarget> target to register it into the - shared library cache. This variable, when defined, will also - facilitate addition of an appropriate - <literal>@exec /sbin/ldconfig -m</literal> and - <literal>@unexec /sbin/ldconfig -R</literal> pair into your - <filename>pkg-plist</filename> file, so that a user who installed - the package can start using the shared library immediately and - deinstallation will not cause the system to still believe the - library is there.</para> - - <para>If you need, you can override default location where the new - library is installed by defining <makevar>LDCONFIG_DIRS</makevar> - make variable, which should contain a list of directories into which - shared libraries are to be installed. For example if your port - installs shared libraries into - <filename><makevar>PREFIX</makevar>/lib/foo</filename> and - <filename><makevar>PREFIX</makevar>/lib/bar</filename> directories - you could use the following in your - <filename>Makefile</filename>:</para> - - <programlisting> -INSTALLS_SHLIB= yes -LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting> - - <para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed - through &man.sed.1; just like the rest of <filename>pkg-plist</filename>, - so <makevar>PLIST_SUB</makevar> substitutions also apply here. It is - recommended that you use <literal>%%PREFIX%%</literal> for - <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for - <makevar>LOCALBASE</makevar> and <literal>%%X11BASE%%</literal> for - <makevar>X11BASE</makevar>.</para> - </sect1> - </chapter> - -<!-- - - <chapter> - <title>ELF support</title> - - <para>Since FreeBSD changed to an ELF binary format shortly after - 3.0-RELEASE, we need to convert many ports that build shared - libraries to support ELF. Complicating this task is that a 3.0 - system can run as both ELF and a.out, and we wish to unofficially - support the 2.2 branch as long as possible. Below are the guidelines on - how to convert a.out only ports to support both a.out and ELF - compilation.</para> - - <para>Some part of this list is only applicable during the conversion, - but will be left here for a while for reference in case you have come - across some old port you wish to upgrade.</para> - - <sect1> - <title>Moving a.out libraries out of the way</title> - - <para>Any a.out libraries should be moved out of - <filename>/usr/local/lib</filename> and similar to an - <filename>aout</filename> subdirectory. (If you do not move them out - of the way, ELF ports will happily overwrite a.out libraries.) The - <maketarget>move-aout-libs</maketarget> target in the 3.0-CURRENT - <filename>src/Makefile</filename> (called from - <maketarget>aout-to-elf</maketarget>) will do this for you. It will - only move a.out libs so it is safe to call it on a system with both - ELF and a.out libs in the standard directories.</para> - </sect1> - - <sect1> - <title>Format</title> - - <para>The ports tree will build packages in the format the machine is - in. This means a.out for 2.2 and a.out or ELF for 3.0 depending on - what <command>`objformat`</command> returns. Also, once users move - a.out libraries to a subdirectory, building a.out libraries will be - unsupported. (I.e., it may still work if you know what you are - doing, but you are on your own.)</para> - - <note> - <para>If a port only works for a.out, set - <makevar>BROKEN_ELF</makevar> to a string describing the reason - why. Such ports will be skipped during a build on an ELF - system.</para> - </note> - </sect1> - - <sect1> - <title><makevar>PORTOBJFORMAT</makevar></title> - - <para><filename>bsd.port.mk</filename> will set - <makevar>PORTOBJFORMAT</makevar> to <literal>aout</literal> or - <literal>elf</literal> and export it in the environments - <envar>CONFIGURE_ENV</envar>, <envar>SCRIPTS_ENV</envar> and - <envar>MAKE_ENV</envar>. (It's always going to be - <literal>aout</literal> in 2.2-STABLE). It is also passed to - <maketarget>PLIST_SUB</maketarget> as - <literal>PORTOBJFORMAT=${PORTOBJFORMAT}</literal>. (See comment on - <literal>ldconfig</literal> lines below.)</para> - - <para>The variable is set using this line in - <filename>bsd.port.mk</filename>:</para> - - <programlisting> -PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</programlisting> - - <para>Ports' make processes should use this variable to decide what to - do. However, if the port's <filename>configure</filename> script - already automatically detects an ELF system, it is not necessary to - refer to <makevar>PORTOBJFORMAT</makevar>.</para> - </sect1> - - <sect1> - <title>Building shared libraries</title> - - <para>The following are differences in handling shared libraries for - a.out and ELF.</para> - - <itemizedlist> - <listitem> - <para>Shared library versions</para> - - <para>An ELF shared library should be called - <filename>libfoo.so.<replaceable>M</replaceable></filename> - where <replaceable>M</replaceable> is the single version number, - and an a.out library should be called - <filename>libfoo.so.<replaceable>M</replaceable>.<replaceable>N</replaceable></filename> - where <replaceable>M</replaceable> is the major version and - <replaceable>N</replaceable> is the the minor version number. - Do not mix those; <emphasis>never</emphasis> install an ELF - shared library called - <filename>libfoo.so.<replaceable>N</replaceable>.<replaceable>M</replaceable></filename> - or an a.out shared library (or symlink) called - <filename>libfoo.so.<replaceable>N</replaceable></filename>.</para> - </listitem> - - <listitem> - <para>Linker command lines</para> - - <para>Assuming <command>cc -shared</command> is used rather than - <command>ld</command> directly, the only difference is that you - need to add - <option>-Wl,-<replaceable>soname,libfoo.so.M</replaceable></option -> - on the command line for ELF.</para> - </listitem> - </itemizedlist> - - <para>You need to install a symlink from - <filename>libfoo.so</filename> to - <filename>libfoo.so.<replaceable>N</replaceable></filename> to make - ELF linkers happy. Since it should be listed in - <filename>pkg-plist</filename> too, and it won't hurt in the a.out case - (some ports even require the link for dynamic loading), you should - just make this link regardless of the setting of - <makevar>PORTOBJFORMAT</makevar>.</para> - </sect1> - - <sect1> - <title><makevar>LIB_DEPENDS</makevar></title> - - <para>All port Makefiles are edited to remove minor numbers from - <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support - removed. (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes - <literal>foo.2</literal>.) They will be matched using <command>grep - -wF</command>.</para> - </sect1> - - <sect1> - <title><filename>pkg-plist</filename></title> - - <para><filename>pkg-plist</filename> should contain the short (ELF) shlib - names if the a.out minor number is zero, and the long (a.out) names - otherwise. <filename>bsd.port.mk</filename> will automatically add - <literal>.0</literal> to the end of short shlib lines if - <makevar>PORTOBJFORMAT</makevar> equals <literal>aout</literal>, and - will delete the minor number from long shlib names if - <makevar>PORTOBJFORMAT</makevar> equals - <literal>elf</literal>.</para> - - <para>In cases where you really need to install shlibs with two - versions on an ELF system or those with one version on an a.out - system (for instance, ports that install compatibility libraries for - other operating systems), define the variable - <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing - of <filename>pkg-plist</filename> mentioned in the previous - paragraph.</para> - </sect1> - - <sect1> - <title><literal>ldconfig</literal></title> - - <para>The <literal>ldconfig</literal> line in Makefiles should - read:</para> - - <programlisting> -${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> - - <para>In <filename>pkg-plist</filename> it should read;</para> - - <programlisting> -@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... -@unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R</programlisting> - - <para>This is to ensure that the correct <command>ldconfig</command> - will be called depending on the format of the package, not the - default format of the system.</para> - </sect1> - </chapter> - ---> - - <chapter id="porting-masterdir"> - <title><makevar>MASTERDIR</makevar></title> - - <para>If your port needs to build slightly different versions of - packages by having a variable (for instance, resolution, or paper - size) take different values, create one subdirectory per package to - make it easier for users to see what to do, but try to share as many - files as possible between ports. Typically you only need a very short - <filename>Makefile</filename> in all but one of the directories if you - use variables cleverly. In the sole <filename>Makefiles</filename>, - you can use <makevar>MASTERDIR</makevar> to specify the directory - where the rest of the files are. Also, use a variable as part of - <link linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> so - the packages will have different names.</para> - - <para>This will be best demonstrated by an example. This is part of - <filename>japanese/xdvi300/Makefile</filename>;</para> - - <programlisting> -PORTNAME= xdvi -PORTVERSION= 17 -PKGNAMEPREFIX= ja- -PKGNAMESUFFIX= ${RESOLUTION} - : -# default -RESOLUTION?= 300 -.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ - ${RESOLUTION} != 300 && ${RESOLUTION} != 400 - @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" - @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." - @${FALSE} -.endif</programlisting> - - <para><filename>japanese/xdvi300</filename> also has all the regular - patches, package files, etc. If you type <command>make</command> - there, it will take the default value for the resolution (300) and - build the port normally.</para> - - <para>As for other resolutions, this is the <emphasis>entire</emphasis> - <filename>xdvi118/Makefile</filename>:</para> - - <programlisting> -RESOLUTION= 118 -MASTERDIR= ${.CURDIR}/../xdvi300 - -.include ${MASTERDIR}/Makefile</programlisting> - - <para>(<filename>xdvi240/Makefile</filename> and - <filename>xdvi400/Makefile</filename> are similar). The - <makevar>MASTERDIR</makevar> definition tells - <filename>bsd.port.mk</filename> that the regular set of - subdirectories like <makevar>FILESDIR</makevar> and - <makevar>SCRIPTDIR</makevar> are to be found under - <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> - line will override the <literal>RESOLUTION=300</literal> line in - <filename>xdvi300/Makefile</filename> and the port will be built with - resolution set to 118.</para> - </chapter> - - <chapter> - <title>Shared library versions</title> - - <para>Please read our <ulink url="../handbook/policies-shlib.html">policy on - shared library versioning</ulink> to understand what to do with - shared library versions in general. Do not blindly assume software - authors know what they are doing; many of them do not. It is very - important that these details are carefully considered, as we have - quite a unique situation where we are trying to have dozens of - potentially incompatible software pairs co-exist. Careless port - imports have caused great trouble regarding shared libraries in the - past (ever wondered why the port <filename>jpeg-6b</filename> has a - shared library version of 9?). If in doubt, send a message to the - &a.ports;. Most of the time, your job ends by determining the right - shared library version and making appropriate patches to implement - it.</para> - -<!-- - <para>However, if there is a port which is a different version of the - same software already in the tree, the situation is much more complex. - In short, the FreeBSD implementation does not allow the user to - specify to the linker which version of shared library to link against - (the linker will always pick the highest numbered version). This - means, if there is a <filename>libfoo.so.3.2</filename> and - <filename>libfoo.so.4.0</filename> in the system, there is no way to - tell the linker to link a particular application to - <filename>libfoo.so.3.2</filename>. It is essentially completely - overshadowed in terms of compilation-time linkage. In this case, the - only solution is to rename the <emphasis>base</emphasis> part of the - shared library. For instance, change - <filename>libfoo.so.4.0</filename> to - <filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be - linked from other ports.</para> ---> - </chapter> - - <chapter id="porting-manpages"> - <title>Manpages</title> - - <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add - any manpages to <filename>pkg-plist</filename> (this means you must - <emphasis>not</emphasis> list manpages in the - <filename>pkg-plist</filename>—see <link - linkend="porting-plist">generating PLIST</link> for more). It also - makes the install stage automatically compress or uncompress manpages - depending on the setting of <makevar>NOMANCOMPRESS</makevar> in - <filename>/etc/make.conf</filename>.</para> - - <para>If your port tries to install multiple names for manpages using - symlinks or hardlinks, you must use the <makevar>MLINKS</makevar> - variable to identify these. The link installed by your port will - be destroyed and recreated by <filename>bsd.port.mk</filename> - to make sure it points to the correct file. Any manpages - listed in MLINKS must not be listed in the - <filename>pkg-plist</filename>.</para> - - <para>To specify whether the manpages are compressed upon installation, - use the <makevar>MANCOMPRESSED</makevar> variable. This variable can - take three values, <literal>yes</literal>, <literal>no</literal> and - <literal>maybe</literal>. <literal>yes</literal> means manpages are - already installed compressed, <literal>no</literal> means they are - not, and <literal>maybe</literal> means the software already respects - the value of <makevar>NOMANCOMPRESS</makevar> so - <filename>bsd.port.mk</filename> does not have to do anything - special.</para> - - <para><makevar>MANCOMPRESSED</makevar> is automatically set to - <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and - <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to - <literal>no</literal> otherwise. You do not have to explicitly define - it unless the default is not suitable for your port.</para> - - <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use the - <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in - certain sections go in a non-standard place, such as some Perl modules - ports, you can set individual man paths using - <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where - <replaceable>sect</replaceable> is one of <literal>1-9</literal>, - <literal>L</literal> or <literal>N</literal>).</para> - - <para>If your manpages go to language-specific subdirectories, set the - name of the languages to <makevar>MANLANG</makevar>. The value of - this variable defaults to <literal>""</literal> (i.e., English - only).</para> - - <para>Here is an example that puts it all together.</para> - - <programlisting> -MAN1= foo.1 -MAN3= bar.3 -MAN4= baz.4 -MLINKS= foo.1 alt-name.8 -MANLANG= "" ja -MAN3PREFIX= ${PREFIX}/share/foobar -MANCOMPRESSED= yes</programlisting> - - <para>This states that six files are installed by this port;</para> - - <programlisting> -${PREFIX}/man/man1/foo.1.gz -${PREFIX}/man/ja/man1/foo.1.gz -${PREFIX}/share/foobar/man/man3/bar.3.gz -${PREFIX}/share/foobar/man/ja/man3/bar.3.gz -${PREFIX}/man/man4/baz.4.gz -${PREFIX}/man/ja/man4/baz.4.gz</programlisting> - - <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename> - may or may not be installed by your port. Regardless, a - symlink will be made to join the foo(1) manpage and - alt-name(8) manpage.</para> - - </chapter> - - <chapter id="porting-motif"> - <title>Ports that require Motif</title> - - <para>There are many programs that require a Motif library (available - from several commercial vendors, while there is a free clone reported - to be able to run many applications in - <filename>x11-toolkits/lesstif</filename>) to compile. Since it is a - popular toolkit and their licenses usually permit redistribution of - statically linked binaries, we have made special provisions for - handling ports that require Motif in a way that we can easily compile - binaries linked either dynamically (for people who are compiling from - the port) or statically (for people who distribute packages).</para> - - <sect1> - <title><makevar>REQUIRES_MOTIF</makevar></title> - - <para>If your port requires Motif, define this variable in the - Makefile. This will prevent people who do not own a copy of Motif - from even attempting to build it.</para> - </sect1> - - <sect1> - <title><makevar>MOTIFLIB</makevar></title> - - <para>This variable will be set by <filename>bsd.port.mk</filename> to - be the appropriate reference to the Motif library. Please patch the - source to use this wherever the Motif library is referenced in the - <filename>Makefile</filename> or - <filename>Imakefile</filename>.</para> - - <para>There are two common cases:</para> - - <itemizedlist> - <listitem> - <para>If the port refers to the Motif library as - <literal>-lXm</literal> in its <filename>Makefile</filename> or - <filename>Imakefile</filename>, simply substitute - <literal>${MOTIFLIB}</literal> for it.</para> - </listitem> - - <listitem> - <para>If the port uses <literal>XmClientLibs</literal> in its - <filename>Imakefile</filename>, change it to - <literal>${MOTIFLIB} ${XTOOLLIB} - ${XLIB}</literal>.</para> - </listitem> - - </itemizedlist> - - <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to - <literal>-L/usr/X11R6/lib -lXm</literal> or - <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need to - add <literal>-L</literal> or <literal>-l</literal> in front.</para> - </sect1> - </chapter> - - <chapter> - <title>X11 fonts</title> - - <para>If your port installs fonts for the X Window system, put them in - <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>. - This directory is new to XFree86 release 3.3.3. If it does not exist, - please create it, and print out a message urging the user to update - their XFree86 to 3.3.3 or newer, or at least add this directory to the - font path in <filename>/etc/XF86Config</filename>.</para> - </chapter> - - <chapter id="porting-info"> - <title>Info files</title> - - <para>The new version of texinfo (included in 2.2.2-RELEASE and onwards) - contains a utility called <command>install-info</command> to add and - delete entries to the <filename>dir</filename> file. If your port - installs any info documents, please follow these instructions so your - port/package will correctly update the user's - <filename><makevar>PREFIX</makevar>/info/dir</filename> file. (Sorry - for the length of this section, but is it imperative to weave all the - info files together. If done correctly, it will produce a - <emphasis>beautiful</emphasis> listing, so please bear with me!</para> - - <para>First, this is what you (as a porter) need to know</para> - - <screen>&prompt.user; <userinput>install-info --help</userinput> -install-info [OPTION]... [INFO-FILE [DIR-FILE]] - Install INFO-FILE in the Info directory file DIR-FILE. - -Options: ---delete Delete existing entries in INFO-FILE; - don't insert any new entries. - : ---entry=TEXT Insert TEXT as an Info directory entry. - : ---section=SEC Put this file's entries in section SEC of the directory. :</screen> - - <note> - <para>This program will not actually <emphasis>install</emphasis> info - files; it merely inserts or deletes entries in the - <filename>dir</filename> file.</para> - </note> - - <para>Here's a seven-step procedure to convert ports to use - <command>install-info</command>. I will use - <filename>editors/emacs</filename> as an example.</para> - - <procedure> - <step> - <para>Look at the texinfo sources and make a patch to insert - <literal>@dircategory</literal> and <literal>@direntry</literal> - statements to files that do not have them. This is part of my - patch:</para> - - <programlisting> ---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 -+++ ./man/vip.texi Tue May 20 01:28:33 1997 -@@ -2,6 +2,10 @@ - - @setfilename ../info/vip - @settitle VIP -+@dircategory The Emacs editor and associated tools -+@direntry -+* VIP: (vip). A VI-emulation for Emacs. -+@end direntry - - @iftex - @finalout - :</programlisting> - - <para>The format should be self-explanatory. Many authors leave a - <filename>dir</filename> file in the source tree that contains all - the entries you need, so look around before you try to write your - own. Also, make sure you look into related ports and make the - section names and entry indentations consistent (we recommend that - all entry text start at the 4th tab stop).</para> - - <note> - <para>Note that you can put only one info entry per file because - of a bug in <command>install-info --delete</command> that - deletes only the first entry if you specify multiple entries in - the <email>@direntry</email> section.</para> - </note> - - <para>You can give the <literal>dir</literal> entries to - <command>install-info</command> as arguments - (<option>--section</option> and <option>--entry</option>) instead - of patching the texinfo sources. I do not think this is a good - idea for ports because you need to duplicate the same information - in <emphasis>three</emphasis> places - (<filename>Makefile</filename> and - <literal>@exec</literal>/<literal>@unexec</literal> of - <filename>pkg-plist</filename>; see below). However, if you have - Japanese (or other multibyte encoding) info files, you will have - to use the extra arguments to <command>install-info</command> - because <command>makeinfo</command> cannot handle those texinfo - sources. (See <filename>Makefile</filename> and - <filename>pkg-plist</filename> of <filename>japanese/skk</filename> - for examples on how to do this).</para> - </step> - - <step> - <para>Go back to the port directory and do a <command>make clean; - make</command> and verify that the info files are regenerated - from the texinfo sources. Since the texinfo sources are newer than - the info files, they should be rebuilt when you type - <command>make</command>; but many <filename>Makefile</filename>s - do not include correct dependencies for info files. In - <command>emacs</command>' case, I had to patch the main - <filename>Makefile.in</filename> so it will descend into the - <filename>man</filename> subdirectory to rebuild the info - pages.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Tue Apr 15 00:15:28 1997 -@@ -184,7 +184,7 @@ - # Subdirectories to make recursively. `lisp' is not included - # because the compiled lisp files are part of the distribution - # and you cannot remake them without installing Emacs first. --SUBDIR = lib-src src -+SUBDIR = lib-src src man - - # The makefiles of the directories in $SUBDIR. - SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile - lwlib/Makefile ---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 -+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 -@@ -66,6 +66,7 @@ - ${srcdir}/gnu1.texi \ - ${srcdir}/glossary.texi - -+all: info - info: $(INFO_TARGETS) - - dvi: $(DVI_TARGETS)</programlisting> - - <para>The second hunk was necessary because the default target in - the <filename>man</filename> subdir is called - <maketarget>info</maketarget>, while the main - <filename>Makefile</filename> wants to call - <maketarget>all</maketarget>. I also deleted the installation of - the <filename>info</filename> info file because we already have - one with the same name in <filename>/usr/share/info</filename> - (that patch is not shown here).</para> - </step> - - <step> - <para>If there is a place in the <filename>Makefile</filename> that - is installing the <filename>dir</filename> file, delete it. Your - port may not be doing it. Also, remove any commands that are - otherwise mucking around with the <filename>dir</filename> - file.</para> - - <programlisting> ---- ./Makefile.in.org Mon Aug 19 21:12:19 1996 -+++ ./Makefile.in Mon Apr 14 23:38:07 1997 -@@ -368,14 +368,8 @@ - if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ - then \ - (cd ${infodir}; \ -- if [ -f dir ]; then \ -- if [ ! -f dir.old ]; then mv -f dir dir.old; \ -- else mv -f dir dir.bak; fi; \ -- fi; \ - cd ${srcdir}/info ; \ -- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); -\ -- (cd $${thisdir}; chmod a+r ${infodir}/dir); \ - for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ - (cd $${thisdir}; \ - ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ - chmod a+r ${infodir}/$$f); \</programlisting> - </step> - - <step> - <para>(This step is only necessary if you are modifying an existing - port.) Take a look at <filename>pkg-plist</filename> and delete - anything that is trying to patch up <filename>info/dir</filename>. - They may be in <filename>pkg-install</filename> or some other - file, so search extensively.</para> - - <programlisting> -Index: pkg-plist -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v -retrieving revision 1.15 -diff -u -r1.15 pkg-plist ---- pkg-plist 1997/03/04 08:04:00 1.15 -+++ pkg-plist 1997/04/15 06:32:12 -@@ -15,9 +15,6 @@ - man/man1/emacs.1.gz - man/man1/etags.1.gz - man/man1/ctags.1.gz --@unexec cp %D/info/dir %D/info/dir.bak --info/dir --@unexec cp %D/info/dir.bak %D/info/dir - info/cl - info/cl-1 - info/cl-2</programlisting> - </step> - - <step> - <para>Add a <maketarget>post-install</maketarget> target to the - <filename>Makefile</filename> to call - <maketarget>install-info</maketarget> with the installed - info files. (It is no longer necessary to create the - <filename>dir</filename> file yourself; - <command>install-info</command> automatically creates this - file if it does not exist.)</para> - - <programlisting> -Index: Makefile -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/Makefile,v -retrieving revision 1.26 -diff -u -r1.26 Makefile ---- Makefile 1996/11/19 13:14:40 1.26 -+++ Makefile 1997/05/20 10:25:09 1.28 -@@ -20,5 +20,8 @@ - post-install: - .for file in emacs-19.34 emacsclient etags ctags b2m - strip ${PREFIX}/bin/${file} - .endfor -+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode -+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir -+.endfor - - .include <bsd.port.mk></programlisting> - </step> - - <step> - <para>Edit <filename>pkg-plist</filename> and add equivalent - <literal>@exec</literal> statements and also - <literal>@unexec</literal> for - <command>pkg_delete</command>.</para> - - <programlisting> -Index: pkg-plist -=================================================================== -RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v -retrieving revision 1.15 -diff -u -r1.15 pkg-plist ---- pkg-plist 1997/03/04 08:04:00 1.15 -+++ pkg-plist 1997/05/20 10:25:12 1.17 -@@ -16,7 +14,14 @@ - man/man1/etags.1.gz - man/man1/ctags.1.gz -+@unexec install-info --delete %D/info/emacs %D/info/dir - : -+@unexec install-info --delete %D/info/ccmode %D/info/dir - info/cl - info/cl-1 -@@ -87,6 +94,18 @@ - info/viper-3 - info/viper-4 -+@exec install-info %D/info/emacs %D/info/dir - : -+@exec install-info %D/info/ccmode %D/info/dir - libexec/emacs/19.34/i386--freebsd/cvtmail - libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting> - - <note> - <para>The <literal>@unexec install-info --delete</literal> - commands have to be listed before the info files themselves so - they can read the files. Also, the <literal>@exec - install-info</literal> commands have to be after the info - files and the <literal>@exec</literal> command that creates the - the <filename>dir</filename> file.</para> - </note> - </step> - - <step> - <para><link linkend="porting-testing">Test</link> and admire your - work. <!-- smiley --><emphasis>:-)</emphasis>. Check the - <filename>dir</filename> file before and after each step.</para> - </step> - </procedure> - </chapter> - - <chapter> - <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title> - - <para>There are some tricks we have not mentioned yet about the - <filename>pkg-<replaceable>*</replaceable></filename> files - that come in handy sometimes.</para> - - <sect1 id="porting-message"> - <title><filename>pkg-message</filename></title> - - <para>If you need to display a message to the installer, you may place - the message in <filename>pkg-message</filename>. This capability is - often useful to display additional installation steps to be taken - after a <command>pkg_add</command> or to display licensing - information.</para> - - <note> - <para>The <filename>pkg-message</filename> file does not need to be - added to <filename>pkg-plist</filename>. Also, it will not get - automatically printed if the user is using the port, not the - package, so you should probably display it from the - <maketarget>post-install</maketarget> target yourself.</para> - </note> - </sect1> - - <sect1> - <title><filename>pkg-install</filename></title> - - <para>If your port needs to execute commands when the binary package - is installed with <command>pkg_add</command> you can do this via the - <filename>pkg-install</filename> script. This script will - automatically be added to the package, and will be run twice by - <command>pkg_add</command>. The first time as - <literal>${SH} pkg-install ${PKGNAME} - PRE-INSTALL</literal> and the second time as - <literal>${SH} pkg-install ${PKGNAME} POST-INSTALL</literal>. - <literal>$2</literal> can be tested to determine which mode - the script is being run in. The <envar>PKG_PREFIX</envar> - environmental variable will be set to the package installation - directory. See &man.pkg.add.1; for - additional information.</para> - - <note> - <para>This script is not run automatically if you install the port - with <command>make install</command>. If you are depending on it - being run, you will have to explicitly call it from your port's - <filename>Makefile</filename>.</para> - </note> - </sect1> - - <sect1> - <title><filename>pkg-req</filename></title> - - <para>If your port needs to determine if it should install or not, you - can create a <filename>pkg-req</filename> “requirements” - script. It will be invoked automatically at - installation/deinstallation time to determine whether or not - installation/deinstallation should proceed.</para> - </sect1> - - <sect1 id="porting-plist"> - <title>Changing <filename>pkg-plist</filename> based on make - variables</title> - - <para>Some ports, particularly the p5- ports, need to change their - <filename>pkg-plist</filename> depending on what options they are - configured with (or version of perl, in the case of p5- ports). To - make this easy, any instances in the <filename>pkg-plist</filename> of - <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and - <literal>%%PERL_VERSION%%</literal> will be substituted for - appropriately. The value of <literal>%%OSREL%%</literal> is the - numeric revision of the operating system (e.g., - <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is - the full version number of perl (e.g., <literal>5.00502</literal>) - and <literal>%%PERL_VER%%</literal> is the perl version number minus - the patchlevel (e.g., <literal>5.005</literal>).</para> - - <para>If you need to make other substitutions, you can set the - <makevar>PLIST_SUB</makevar> variable with a list of - <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> - pairs and instances of - <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be - substituted with <replaceable>VALUE</replaceable> in the - <filename>pkg-plist</filename>.</para> - - <para>For instance, if you have a port that installs many files in a - version-specific subdirectory, you can put something like - - <programlisting> -OCTAVE_VERSION= 2.0.13 -PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> - - in the <filename>Makefile</filename> and use - <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up - in <filename>pkg-plist</filename>. That way, when you upgrade the port, - you will not have to change dozens (or in some cases, hundreds) of - lines in the <filename>pkg-plist</filename>.</para> - - <para>This substitution (as well as addition of any <link - linkend="porting-manpages">man pages</link>) will be done between - the <maketarget>do-install</maketarget> and - <maketarget>post-install</maketarget> targets, by reading from - <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar> - (default: - <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So if - your port builds <makevar>PLIST</makevar> on the fly, do so in or - before <maketarget>do-install</maketarget>. Also, if your port - needs to edit the resulting file, do so in - <maketarget>post-install</maketarget> to a file named - <makevar>TMPPLIST</makevar>.</para> - </sect1> - - <sect1> - <title id="porting-pkgfiles">Changing the names of - <filename>pkg-<replaceable>*</replaceable></filename> files</title> - - <para>All the names of <filename>pkg-<replaceable>*</replaceable></filename> files - are defined using variables so you can change them in your - <filename>Makefile</filename> if need be. This is especially useful - when you are sharing the same <filename>pkg-<replaceable>*</replaceable></filename> files - among several ports or have to write to one of the above files (see - <link linkend="porting-wrkdir">writing to places other than - <makevar>WRKDIR</makevar></link> for why it is a bad idea to write - directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para> - - <para>Here is a list of variable names and their default - values. (<makevar>PKGDIR</makevar> defaults to - <makevar>${MASTERDIR}</makevar>.)</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Default value</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>COMMENT</makevar></entry> - <entry><literal>${PKGDIR}/pkg-comment</literal></entry> - </row> - - <row> - <entry><makevar>DESCR</makevar></entry> - <entry><literal>${PKGDIR}/pkg-descr</literal></entry> - </row> - - <row> - <entry><makevar>PLIST</makevar></entry> - <entry><literal>${PKGDIR}/pkg-plist</literal></entry> - </row> - - <row> - <entry><makevar>PKGINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/pkg-install</literal></entry> - </row> - - <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> - <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> - </row> - - <row> - <entry><makevar>PKGREQ</makevar></entry> - <entry><literal>${PKGDIR}/pkg-req</literal></entry> - </row> - - <row> - <entry><makevar>PKGMESSAGE</makevar></entry> - <entry><literal>${PKGDIR}/pkg-message</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Please change these variables rather than overriding - <makevar>PKG_ARGS</makevar>. If you change - <makevar>PKG_ARGS</makevar>, those files will not correctly be - installed in <filename>/var/db/pkg</filename> upon install from a - port.</para> - </sect1> - </chapter> - - <chapter> - <title>Licensing Problems</title> - - <para>Some software packages have restrictive licenses or can be in - violation of the law in some countries (such as violating a patent). - What we can do with - them varies a lot, depending on the exact wordings of the respective - licenses.</para> - - <note> - <para>It is your responsibility as a porter to read the licensing - terms of the software and make sure that the FreeBSD project will - not be held accountable for violating them by redistributing the - source or compiled binaries either via ftp or CD-ROM. If in doubt, - please contact the &a.ports;.</para> - </note> - - <para>There are two variables you can set in the Makefile to handle the - situations that arise frequently:</para> - - <orderedlist> - <listitem> - <para>If the port has a “do not sell for profit” type of - license, set the variable <makevar>NO_CDROM</makevar> to a string - describing the reason why. We will make sure such ports will not go - into the CD-ROM come release time. The distfile and package will - still be available via ftp.</para> - </listitem> - - <listitem> - <para>If the resulting package needs to be built uniquely for each - site, or the resulting binary package cannot be distributed due to - licensing; set the variable <makevar>NO_PACKAGE</makevar> to a - string describing the reason why. We will make sure such packages - will not go on the ftp site, nor into the CD-ROM come release time. - The distfile will still be included on both however.</para> - </listitem> - - <listitem> - <para>If the port has legal restrictions on who can use it (e.g., - patented stuff) or has a “no commercial use” license, - set the variable <makevar>RESTRICTED</makevar> to be the string - describing the reason why. For such ports, the distfiles/packages - will not be available even from our ftp sites.</para> - </listitem> - </orderedlist> - - <note> - <para>The GNU General Public License (GPL), both version 1 and 2, - should not be a problem for ports.</para> - </note> - - <note> - <para>If you are a committer, make sure you update the - <filename>ports/LEGAL</filename> file too.</para> - </note> - </chapter> - - <chapter id="port-upgrading"> - <title>Upgrading</title> - - <para>When you notice that a port is out of date compared to the latest - version from the original authors, first make sure you have the latest - port. You can find them in the - <filename>ports/ports-current</filename> directory of the ftp mirror - sites. You may also use CVSup to keep your whole ports collection - up-to-date, as described in <ulink url="../handbook/synching.html#CVSUP-CONFIG">the Handbook</ulink>.</para> - - <para>The next step is to send a mail to the maintainer, if one is - listed in the port's <filename>Makefile</filename>. That person may - already be working on an upgrade, or have a reason to not upgrade the - port right now (because of, for example, stability problems of the new - version).</para> - - <para>If the maintainer asks you to do the upgrade or there is not any - such person to begin with, please make the upgrade and send the - recursive diff (either unified or context diff is fine, but port - committers appear to prefer unified diff more) of the new and old - ports directories to us (e.g., if your modified port directory is - called <filename>superedit</filename> and the original as in our tree - is <filename>superedit.bak</filename>, then send us the result of - <command>diff -ruN superedit.bak superedit</command>). Please examine - the output to make sure all the changes make sense. The best way to - send us the diff is by including it via &man.send-pr.1; (category - <literal>ports</literal>). Please mention any added or deleted files - in the message, as they have to be explicitly specified to CVS when - doing a commit. If the diff is more than about 20KB, please compress - and uuencode it; otherwise, just include it in the PR as is.</para> - - <note> - <para>Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports!</para> - </note> - </chapter> - - <chapter> - <title><anchor id="porting-dads">Dos and Don'ts</title> - - <para>Here is a list of common dos and don'ts that you encounter during - the porting process.You should check your own port against this list, - but you can also check ports in the PR database that others have - submitted. Submit any comments on ports you check as described in - <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General - Commentary</ulink>. Checking ports in the PR database will both make - it faster for us to commit them, and prove that you know what you are - doing.</para> - - <sect1> - <title>Strip Binaries</title> - - <para>Do strip binaries. If the original source already strips the - binaries, fine; otherwise you should add a - <literal>post-install</literal> rule to to it yourself. Here is an - example:</para> - - <programlisting> -post-install: - strip ${PREFIX}/bin/xdl</programlisting> - - <para>Use the &man.file.1; command on the installed executable to - check whether the binary is stripped or not. If it does not say - <literal>not stripped</literal>, it is stripped.</para> - </sect1> - - <sect1> - <title>INSTALL_* macros</title> - - <para>Do use the macros provided in <filename>bsd.port.mk</filename> - to ensure correct modes and ownership of files in your own - <maketarget>*-install</maketarget> targets.</para> - - <itemizedlist> - <listitem> - <para><makevar>INSTALL_PROGRAM</makevar> is a command to install - binary executables.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_SCRIPT</makevar> is a command to install - executable scripts.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_DATA</makevar> is a command to install - sharable data.</para> - </listitem> - - <listitem> - <para><makevar>INSTALL_MAN</makevar> is a command to install - manpages and other documentation (it does not compress - anything).</para> - </listitem> - </itemizedlist> - - <para>These are basically the <command>install</command> command with - all the appropriate flags. See below for an example on how to use - them.</para> - </sect1> - - <sect1 id="porting-wrkdir"> - <title><makevar>WRKDIR</makevar></title> - - <para>Do not write anything to files outside - <makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the only - place that is guaranteed to be writable during the port build (see - <ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an - example of building ports from a read-only tree). If you need to - modify one of the <filename>pkg-<replaceable>*</replaceable></filename> - files, do so by <link - linkend="porting-pkgfiles">redefining a variable</link>, not by - writing over it.</para> - </sect1> - - <sect1 id="porting-wrkdirprefix"> - <title><makevar>WRKDIRPREFIX</makevar></title> - - <para>Make sure your port honors <makevar>WRKDIRPREFIX</makevar>. - Most ports do not have to worry about this. In particular, if you - are referring to a <makevar>WRKDIR</makevar> of another port, note - that the correct location is - <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> not <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or some such.</para> - - <para>Also, if you are defining <makevar>WRKDIR</makevar> yourself, - make sure you prepend - <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in the - front.</para> - </sect1> - - <sect1 id="porting-versions"> - <title>Differentiating operating systems and OS versions</title> - - <para>You may come across code that needs modifications or 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 1.x systems and cross-port - to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, - NetBSD, and OpenBSD.</para> - - <para>The preferred way to tell 4.3BSD/Reno (1990) and newer versions - of the BSD code apart is by using the <literal>BSD</literal> macro - defined in <filename><sys/param.h></filename>. Hopefully that - file is already included; if not, add the code:</para> - - <programlisting> -#if (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif</programlisting> - - <para>to the proper place in the <filename>.c</filename> file. We - believe that every system that defines these two symbols has - <filename>sys/param.h</filename>. If you find a system that - does not, we would like to know. Please send mail to the - &a.ports;.</para> - - <para>Another way is to use the GNU Autoconf style of doing - this:</para> - - <programlisting> -#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif</programlisting> - - <para>Do not forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to the - <makevar>CFLAGS</makevar> in the <filename>Makefile</filename> for - this method.</para> - - <para>Once you have <filename>sys/param.h</filename> included, you may - use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199103))</programlisting> - - <para>to detect if the code is being compiled on a 4.3 Net2 code base - or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 - 1.1 and below).</para> - - <para>Use:</para> - - <programlisting> -#if (defined(BSD) && (BSD >= 199306))</programlisting> - - <para>to detect if the code is being compiled on a 4.4 code base or - newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or - above).</para> - - <para>The value of the <literal>BSD</literal> macro is - <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is - stated for informational purposes only. It should not be used to - distinguish between versions of FreeBSD based only on 4.4-Lite vs. - versions that have merged in changes from 4.4-Lite2. The - <literal>__FreeBSD__</literal> macro should be used instead.</para> - - <para>Use sparingly:</para> - - <itemizedlist> - <listitem> - <para><literal>__FreeBSD__</literal> is defined in all versions of - FreeBSD. Use it if the change you are making - <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like - the use of <literal>sys_errlist[]</literal> vs - <function>strerror()</function> are Berkeleyisms, not FreeBSD - changes.</para> - </listitem> - - <listitem> - <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to - be <literal>2</literal>. In earlier versions, it is - <literal>1</literal>. Later versions will bump it to match - their major version number.</para> - </listitem> - - <listitem> - <para>If you need to tell the difference between a FreeBSD 1.x - system and a FreeBSD 2.x or 3.x system, usually the right answer - is to use the <literal>BSD</literal> macros described above. If - there actually is a FreeBSD specific change (such as special - shared library options when using <command>ld</command>) then it - is OK to use <literal>__FreeBSD__</literal> and <literal>#if - __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x and later - system. If you need more granularity in detecting FreeBSD - systems since 2.0-RELEASE you can use the following:</para> - - <programlisting> -#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif</programlisting> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Release</entry> - <entry><literal>__FreeBSD_version</literal></entry> - </row> - </thead> - - <tbody> - <row> - <entry>2.0-RELEASE</entry> - <entry>119411</entry> - </row> - - <row> - <entry>2.1-CURRENT</entry> - <entry>199501, 199503</entry> - </row> - - <row> - <entry>2.0.5-RELEASE</entry> - <entry>199504</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1</entry> - <entry>199508</entry> - </row> - - <row> - <entry>2.1.0-RELEASE</entry> - <entry>199511</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.5</entry> - <entry>199512</entry> - </row> - - <row> - <entry>2.1.5-RELEASE</entry> - <entry>199607</entry> - </row> - - <row> - <entry>2.2-CURRENT before 2.1.6</entry> - <entry>199608</entry> - </row> - - <row> - <entry>2.1.6-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.1.7-RELEASE</entry> - <entry>199612</entry> - </row> - - <row> - <entry>2.2-RELEASE</entry> - <entry>220000</entry> - </row> - - <row> - <entry>2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.1-RELEASE</entry> - <entry>220000 (no change)</entry> - </row> - - <row> - <entry>2.2-STABLE after texinfo-3.9</entry> - <entry>221001</entry> - </row> - - <row> - <entry>2.2-STABLE after top</entry> - <entry>221002</entry> - </row> - - <row> - <entry>2.2.2-RELEASE</entry> - <entry>222000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.2-RELEASE</entry> - <entry>222001</entry> - </row> - - <row> - <entry>2.2.5-RELEASE</entry> - <entry>225000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.5-RELEASE</entry> - <entry>225001</entry> - </row> - - <row> - <entry>2.2-STABLE after ldconfig -R merge</entry> - <entry>225002</entry> - </row> - - <row> - <entry>2.2.6-RELEASE</entry> - <entry>226000</entry> - </row> - - <row> - <entry>2.2.7-RELEASE</entry> - <entry>227000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.7-RELEASE</entry> - <entry>227001</entry> - </row> - - <row> - <entry>2.2-STABLE after semctl(2) change</entry> - <entry>227002</entry> - </row> - - <row> - <entry>2.2.8-RELEASE</entry> - <entry>228000</entry> - </row> - - <row> - <entry>2.2-STABLE after 2.2.8-RELEASE</entry> - <entry>228001</entry> - </row> - - <row> - <entry>3.0-CURRENT before mount(2) change</entry> - <entry>300000</entry> - </row> - - <row> - <entry>3.0-CURRENT after mount(2) change</entry> - <entry>300001</entry> - </row> - - <row> - <entry>3.0-CURRENT after semctl(2) change</entry> - <entry>300002</entry> - </row> - - <row> - <entry>3.0-CURRENT after ioctl arg changes</entry> - <entry>300003</entry> - </row> - - <row> - <entry>3.0-CURRENT after ELF conversion</entry> - <entry>300004</entry> - </row> - - <row> - <entry>3.0-RELEASE</entry> - <entry>300005</entry> - </row> - - <row> - <entry>3.0-CURRENT after 3.0-RELEASE</entry> - <entry>300006</entry> - </row> - - <row> - <entry>3.0-STABLE after 3/4 branch</entry> - <entry>300007</entry> - </row> - - <row> - <entry>3.1-RELEASE</entry> - <entry>310000</entry> - </row> - - <row> - <entry>3.1-STABLE after 3.1-RELEASE</entry> - <entry>310001</entry> - </row> - - <row> - <entry>3.1-STABLE after C++ constructor/destructor order - change</entry> - <entry>310002</entry> - </row> - - <row> - <entry>3.2-RELEASE</entry> - <entry>320000</entry> - </row> - - <row> - <entry>3.2-STABLE</entry> - <entry>320001</entry> - </row> - - <row> - <entry>3.2-STABLE after binary-incompatible IPFW and - socket changes</entry> - <entry>320002</entry> - </row> - - <row> - <entry>3.3-RELEASE</entry> - <entry>330000</entry> - </row> - - <row> - <entry>3.3-STABLE</entry> - <entry>330001</entry> - </row> - - <row> - <entry>3.3-STABLE after adding mkstemps() to libc</entry> - <entry>330002</entry> - </row> - - <row> - <entry>3.4-RELEASE</entry> - <entry>340000</entry> - </row> - - <row> - <entry>3.4-STABLE</entry> - <entry>340001</entry> - </row> - - <row> - <entry>4.0-CURRENT after 3.4 branch</entry> - <entry>400000</entry> - </row> - - <row> - <entry>4.0-CURRENT after change in dynamic linker - handling</entry> - <entry>400001</entry> - </row> - - <row> - <entry>4.0-CURRENT after C++ constructor/destructor - order change</entry> - <entry>400002</entry> - </row> - - <row> - <entry>4.0-CURRENT after functioning dladdr(3)</entry> - <entry>400003</entry> - </row> - - <row> - <entry>4.0-CURRENT after __deregister_frame_info dynamic - linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 - integration) - </entry> - <entry>400004</entry> - </row> - - <row> - <entry>4.0-CURRENT after suser(9) API change - (also 4.0-CURRENT after newbus)</entry> - <entry>400005</entry> - </row> - - <row> - <entry>4.0-CURRENT after cdevsw registration change</entry> - <entry>400006</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of so_cred for - socket level credentials</entry> - <entry>400007</entry> - </row> - - <row> - <entry>4.0-CURRENT after the addition of a poll syscall - wrapper to libc_r</entry> - <entry>400008</entry> - </row> - - <row> - <entry>4.0-CURRENT after the change of the kernel's - <literal>dev_t</literal> type to <literal>struct - specinfo</literal> pointer</entry> - <entry>400009</entry> - </row> - - <row> - <entry>4.0-CURRENT after fixing a hole in jail(2)</entry> - <entry>400010</entry> - </row> - - <row> - <entry>4.0-CURRENT after the <literal>sigset_t</literal> - datatype change</entry> - <entry>400011</entry> - </row> - - <row> - <entry>4.0-CURRENT after the cutover to the GCC 2.95.2 - compiler</entry> - <entry>400012</entry> - </row> - - <row> - <entry>4.0-CURRENT after adding pluggable linux-mode - ioctl handlers</entry> - <entry>400013</entry> - </row> - - <row> - <entry>4.0-CURRENT after importing OpenSSL</entry> - <entry>400014</entry> - </row> - - <row> - <entry>4.0-CURRENT after the C++ ABI change in GCC 2.95.2 - from -fvtable-thunks to -fno-vtable-thunks by - default</entry> - <entry>400015</entry> - </row> - - <row> - <entry>4.0-CURRENT after importing OpenSSH</entry> - <entry>400016</entry> - </row> - - <row> - <entry>4.0-RELEASE</entry> - <entry>400017</entry> - </row> - - <row> - <entry>4.0-STABLE after 4.0-RELEASE</entry> - <entry>400018</entry> - </row> - - <row> - <entry>4.0-STABLE after merging libxpg4 code into - libc.</entry> - <entry>400020</entry> - </row> - - <row> - <entry>4.0-STABLE after upgrading Binutils to 2.10.0, ELF - branding changes, and tcsh in the base system.</entry> - <entry>400021</entry> - </row> - - <row> - <entry>4.1-RELEASE</entry> - <entry>410000</entry> - </row> - - <row> - <entry>4.1-STABLE after 4.1-RELEASE</entry> - <entry>410001</entry> - </row> - - <row> - <entry>4.1-STABLE after setproctitle() moved from - libutil to libc.</entry> - <entry>410002</entry> - </row> - - <row> - <entry>4.1.1-RELEASE</entry> - <entry>411000</entry> - </row> - - <row> - <entry>4.1.1-STABLE after 4.1.1-RELEASE</entry> - <entry>411001</entry> - </row> - - <row> - <entry>5.0-CURRENT</entry> - <entry>500000</entry> - </row> - - <row> - <entry>5.0-CURRENT after adding addition ELF header fields, - and changing our ELF binary branding method.</entry> - <entry>500001</entry> - </row> - - <row> - <entry>5.0-CURRENT after kld metadata changes.</entry> - <entry>500002</entry> - </row> - - <row> - <entry>5.0-CURRENT after buf/bio changes.</entry> - <entry>500003</entry> - </row> - - <row> - <entry>5.0-CURRENT after binutils upgrade.</entry> - <entry>500004</entry> - </row> - - <row> - <entry>5.0-CURRENT after merging libxpg4 code into - libc and after TASKQ interface introduction.</entry> - <entry>500005</entry> - </row> - - <row> - <entry>5.0-CURRENT after the addition of AGP - interfaces.</entry> - <entry>500006</entry> - </row> - - <row> - <entry>5.0-CURRENT after Perl upgrade to 5.6.0</entry> - <entry>500007</entry> - </row> - - <row> - <entry>5.0-CURRENT after the update of KAME code to - 2000/07 sources.</entry> - <entry>500008</entry> - </row> - - <row> - <entry>5.0-CURRENT after ether_ifattach() and - ether_ifdetach() changes.</entry> - <entry>500009</entry> - </row> - - <row> - <entry>5.0-CURRENT after changing mtree defaults - back to original variant, adding -L to follow - symlinks.</entry> - <entry>500010</entry> - </row> - - <row> - <entry>5.0-CURRENT after kqueue API changed.</entry> - <entry>500011</entry> - </row> - - <row> - <entry>5.0-CURRENT after setproctitle() moved from - libutil to libc.</entry> - <entry>500012</entry> - </row> - - <row> - <entry>5.0-CURRENT after the first SMPng commit.</entry> - <entry>500013</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </listitem> - </itemizedlist> - - <note> - <para>Note that 2.2-STABLE sometimes identifies itself as - “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern - used to be year followed by the month, but we decided to change it - to a more straightforward major/minor system starting from 2.2. - This is because the parallel development on several branches made - it infeasible to classify the releases simply by their real - release dates. If you are making a port now, you do not have to - worry about old -CURRENTs; they are listed here just for your - reference.</para> - </note> - - <para>In the hundreds of ports that have been done, there have only - been one or two cases where <literal>__FreeBSD__</literal> should - have been used. Just because an earlier port screwed up and used it - in the wrong place does not mean you should do so too.</para> - </sect1> - - <sect1> - <title>Writing something after - <filename>bsd.port.mk</filename></title> - - <para>Do not write anything after the <literal>.include - <bsd.port.mk></literal> line. It usually can be avoided by - including <filename>bsd.port.pre.mk</filename> somewhere in the - middle of your <filename>Makefile</filename> and - <filename>bsd.port.post.mk</filename> at the end.</para> - - <note> - <para>You need to include either the - <filename>pre.mk</filename>/<filename>post.mk</filename> pair or - <filename>bsd.port.mk</filename> only; do not mix these two.</para> - </note> - - <para><filename>bsd.port.pre.mk</filename> only defines a few - variables, which can be used in tests in the - <filename>Makefile</filename>, <filename>bsd.port.post.mk</filename> - defines the rest.</para> - - <para>Here are some important variables defined in - <filename>bsd.port.pre.mk</filename> (this is not the complete list, - please read <filename>bsd.port.mk</filename> for the complete - list).</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><makevar>ARCH</makevar></entry> - <entry>The architecture as returned by <command>uname - -m</command> (e.g., <literal>i386</literal>)</entry> - </row> - - <row> - <entry><makevar>OPSYS</makevar></entry> - <entry>The operating system type, as returned by - <command>uname -s</command> (e.g., - <literal>FreeBSD</literal>)</entry> - </row> - - <row> - <entry><makevar>OSREL</makevar></entry> - <entry>The release version of the operating system (e.g., - <literal>2.1.5</literal> or - <literal>2.2.7</literal>)</entry> - </row> - - <row> - <entry><makevar>OSVERSION</makevar></entry> - <entry>The numeric version of the operating system, same as - <link - linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry> - </row> - - <row> - <entry><makevar>PORTOBJFORMAT</makevar></entry> - <entry>The object format of the system - (<literal>aout</literal> or <literal>elf</literal>)</entry> - </row> - - <row> - <entry><makevar>LOCALBASE</makevar></entry> - <entry>The base of the “local” tree (e.g., - <literal>/usr/local/</literal>)</entry> - </row> - - <row> - <entry><makevar>X11BASE</makevar></entry> - <entry>The base of the “X11” tree (e.g., - <literal>/usr/X11R6</literal>)</entry> - </row> - - <row> - <entry><makevar>PREFIX</makevar></entry> - <entry>Where the port installs itself (see <link - linkend="porting-prefix">more on - <makevar>PREFIX</makevar></link>).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>If you have to define the variables - <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>, or - <makevar>MASTERDIR</makevar>, do so before including - <filename>bsd.port.pre.mk</filename>.</para> - </note> - - <para>Here are some examples of things you can write after - <filename>bsd.port.pre.mk</filename>:</para> - - <programlisting> -# no need to compile lang/perl5 if perl5 is already in system -.if ${OSVERSION} > 300003 -BROKEN= perl is in system -.endif - -# only one shlib version number for ELF -.if ${PORTOBJFORMAT} == "elf" -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} -.else -TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} -.endif - -# software already makes link for ELF, but not for a.out -post-install: -.if ${PORTOBJFORMAT} == "aout" - ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so -.endif</programlisting> - </sect1> - - <sect1> - <title>Install additional documentation</title> - - <para>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 <filename><makevar>PREFIX</makevar>/share/doc</filename>. - This can be done, like the previous item, in the - <maketarget>post-install</maketarget> target.</para> - - <para>Create a new directory for your port. The directory name should - reflect what the port is. This usually means - <makevar>PORTNAME</makevar>. However, if you - think the user might want different versions of the port to be - installed at the same time, you can use the whole - <makevar>PKGNAME</makevar>.</para> - - <para>Make the installation dependent to the variable - <makevar>NOPORTDOCS</makevar> so that users can disable it in - <filename>/etc/make.conf</filename>, like this:</para> - - <programlisting> -post-install: -.if !defined(NOPORTDOCS) - ${MKDIR} ${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv -.endif</programlisting> - - <para>Do not forget to add them to <filename>pkg-plist</filename> too. - (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is - currently no way for the packages to read variables from - <filename>/etc/make.conf</filename>.)</para> - - <para>You can also use the <filename>pkg-message</filename> file to - display messages upon installation. See the <link - linkend="porting-message">using - <filename>pkg-message</filename></link> section for - details.</para> - - <note> - <para><filename>pkg-message</filename> does not need to be added to - <filename>pkg-plist</filename>.</para> - </note> - </sect1> - - <sect1> - <title><makevar>DIST_SUBDIR</makevar></title> - - <para>Do not let your port clutter - <filename>/usr/ports/distfiles</filename>. If your port requires a - lot of files to be fetched, or contains a file that has a name that - might conflict with other ports (e.g., - <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> - to the name of the port (<literal>${PORTNAME}</literal> or - <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> - should work fine). This will change - <makevar>DISTDIR</makevar> from the default - <filename>/usr/ports/distfiles</filename> to - <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>, - and in effect puts everything that is required for your port into - that subdirectory.</para> - - <para>It will also look at the subdirectory with the same name on the - backup master site at <filename>ftp.FreeBSD.org</filename>. - (Setting <makevar>DISTDIR</makevar> explicitly in your - <makevar>Makefile</makevar> will not accomplish this, so please use - <makevar>DIST_SUBDIR</makevar>.)</para> - - <note> - <para>This does not affect the <makevar>MASTER_SITES</makevar> you - define in your Makefile.</para> - </note> - </sect1> - - <sect1> - <title>Package information</title> - - <para>Do include package information, i.e. - <filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and - <filename>pkg-plist</filename>.</para> - - <note> - <para>Note that these files are not used only for packaging anymore, - and are <emphasis>mandatory</emphasis> now, even if - <makevar>NO_PACKAGE</makevar> is set.</para> - </note> - </sect1> - - <sect1> - <title>RCS strings</title> - - <para>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 (<literal>$</literal>) signs, and - typically start with <literal>$Id</literal> or - <literal>$RCS</literal>.</para> - </sect1> - - <sect1> - <title>Recursive diff</title> - - <para>Using the recurse (<option>-r</option>) option to - <command>diff</command> to generate patches is fine, but please take - a look at the resulting patches to make sure you do not have any - unnecessary junk in there. In particular, diffs between two backup - files, <filename>Makefiles</filename> when the port uses - <command>Imake</command> or GNU <command>configure</command>, etc., - are unnecessary and should be deleted. If you had to edit - <filename>configure.in</filename> and run - <command>autoconf</command> to regenerate - <command>configure</command>, do not take the diffs of - <command>configure</command> (it often grows to a few thousand - lines!); define <literal>USE_AUTOCONF=yes</literal> and take the - diffs of <filename>configure.in</filename>.</para> - - <para>Also, if you had to delete a file, then you can do it in the - <maketarget>post-extract</maketarget> target rather than as part of - the patch. Once you are happy with the resulting diff, please split - it up into one source file per patch file.</para> - </sect1> - - <sect1 id="porting-prefix"> - <title><makevar>PREFIX</makevar></title> - - <para>Do try to make your port install relative to - <makevar>PREFIX</makevar>. (The value of this variable will be set - to <makevar>LOCALBASE</makevar> (default - <filename>/usr/local</filename>), unless - <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is - set, in which case it will be <makevar>X11BASE</makevar> (default - <filename>/usr/X11R6</filename>).)</para> - - <para>Not hard-coding <filename>/usr/local</filename> or - <filename>/usr/X11R6</filename> 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 <command>imake</command>, this is - automatic; otherwise, this can often be done by simply replacing the - occurrences of <filename>/usr/local</filename> (or - <filename>/usr/X11R6</filename> for X ports that do not use imake) - in the various scripts/Makefiles in the port to read - <makevar>PREFIX</makevar>, as this variable is automatically passed - down to every stage of the build and install processes.</para> - - <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port - truly requires it (i.e., it links against X libs or it needs to - reference files in <makevar>X11BASE</makevar>).</para> - - <para>The variable <makevar>PREFIX</makevar> can be reassigned in your - <filename>Makefile</filename> or in the user's environment. - However, it is strongly discouraged for individual ports to set this - variable explicitly in the <filename>Makefiles</filename>.</para> - - <para>Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For instance, if - your port requires a macro <literal>PAGER</literal> to be the full - pathname of <command>less</command>, use the compiler flag: - - <programlisting> --DPAGER=\"${PREFIX}/bin/less\"</programlisting> - - or - - <programlisting> --DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - - if this is an X port, instead of - <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will - have a better chance of working if the system administrator has - moved the whole `/usr/local' tree somewhere else.</para> - </sect1> - - <sect1> - <title>Subdirectories</title> - - <para>Try to let the port put things in the right subdirectories of - <makevar>PREFIX</makevar>. Some ports lump everything and put it in - the subdirectory with the port's name, which is incorrect. Also, - many ports put everything except binaries, header files and manual - pages in the a subdirectory of <filename>lib</filename>, which does - not bode well with the BSD paradigm. Many of the files should be - moved to one of the following: <filename>etc</filename> - (setup/configuration files), <filename>libexec</filename> - (executables started internally), <filename>sbin</filename> - (executables for superusers/managers), <filename>info</filename> - (documentation for info browser) or <filename>share</filename> - (architecture independent files). See man &man.hier.7; for details, - the rules governing - <filename>/usr</filename> pretty much apply to - <filename>/usr/local</filename> too. The exception are ports - dealing with USENET “news”. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a destination - for their files.</para> - </sect1> - - <sect1 id="porting-cleaning"> - <title>Cleaning up empty directories</title> - - <para>Do make your ports clean up after themselves when they are - deinstalled. This is usually accomplished by adding - <literal>@dirrm</literal> lines for all directories that are - specifically created by the port. You need to delete subdirectories - before you can delete parent directories.</para> - - <programlisting> - : -lib/X11/oneko/pixmaps/cat.xpm -lib/X11/oneko/sounds/cat.au - : -@dirrm lib/X11/oneko/pixmaps -@dirrm lib/X11/oneko/sounds -@dirrm lib/X11/oneko</programlisting> - - <para>However, sometimes <literal>@dirrm</literal> will give you - errors because other ports also share the same subdirectory. You - can call <command>rmdir</command> from <literal>@unexec</literal> to - remove only empty directories without warning.</para> - - <programlisting> -@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting> - - <para>This will neither print any error messages nor cause - <command>pkg_delete</command> to exit abnormally even if - <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is not - empty due to other ports installing some files in there.</para> - </sect1> - - <sect1> - <title>UIDs</title> - - <para>If your port requires a certain user to be on the installed - system, let the <filename>pkg-install</filename> script call - <command>pw</command> to create it automatically. Look at - <filename>net/cvsup-mirror</filename> for an example.</para> - - <para>If your port must use the same user/group ID number when it is - installed as a binary package as when it was compiled, then you must - choose a free UID from 50 to 99 and register it below. Look at - <filename>japanese/Wnn</filename> for an example.</para> - - <para>Make sure you do not use a UID already used by the system or - other ports. This is the current list of UIDs between 50 and - 99.</para> - - <programlisting> -majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent -cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent -gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh -uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico -xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent -pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent -wnn:*:69:7:Wnn:/nonexistent:/nonexistent -ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent -pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh -ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent -alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent -qmaill:*:83:81:QMail user:/var/qmail:/nonexistent -qmaild:*:82:81:QMail user:/var/qmail:/nonexistent -qmailq:*:85:82:QMail user:/var/qmail:/nonexistent -qmails:*:87:82:QMail user:/var/qmail:/nonexistent -qmailp:*:84:81:QMail user:/var/qmail:/nonexistent -qmailr:*:86:82:QMail user:/var/qmail:/nonexistent -msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh -mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin -vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting> - - <para>Please include a notice when you submit a port (or an upgrade) - that reserves a new UID or GID in this range. This allows us to - keep the list of reserved IDs up to date.</para> - </sect1> - - <sect1> - <title>Do things rationally</title> - - <para>The <filename>Makefile</filename> should do things simply and - reasonably. If you can make it a couple of lines shorter or more - readable, then do so. Examples include using a make - <literal>.if</literal> construct instead of a shell - <literal>if</literal> construct, not redefining - <maketarget>do-extract</maketarget> if you can redefine - <makevar>EXTRACT*</makevar> instead, and using - <makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS - += --prefix=${PREFIX}</literal>.</para> - </sect1> - - <sect1> - <title>Respect <makevar>CFLAGS</makevar></title> - - <para>The port should respect the <makevar>CFLAGS</makevar> variable. - If it does not, please add <literal>NO_PACKAGE=ignores - cflags</literal> to the <filename>Makefile</filename>.</para> - - <para>An example of a <filename>Makefile</filename> respecting - the <makevar>CFLAGS</makevar> variable follows. Note the - <makevar>+=</makevar>:</para> - - <programlisting>CFLAGS += -Wall -Werror</programlisting> - - <para>Here is an example which does not respect the - <makevar>CFLAGS</makevar> variable:</para> - - <programlisting>CFLAGS = -Wall -Werror</programlisting> - - <para>The <makevar>CFLAGS</makevar> variable is defined on - FreeBSD systems in <filename>/etc/make.conf</filename>. The - first example appends additional flags to the - <makevar>CFLAGS</makevar> variable, preserving any system-wide - definitions. The second example clobbers anything previously - defined.</para> - </sect1> - - <sect1> - <title>Configuration files</title> - - <para>If your port requires some configuration files in - <filename><makevar>PREFIX</makevar>/etc</filename>, do - <emphasis>not</emphasis> just install them and list them in - <filename>pkg-plist</filename>. That will cause - <command>pkg_delete</command> to delete files carefully edited by - the user and a new installation to wipe them out.</para> - - <para>Instead, install sample files with a suffix - (<filename><replaceable>filename</replaceable>.sample</filename> - will work well) and print out a <link - linkend="porting-message">message</link> pointing out that the - user has to copy and edit the file before the software can be made - to work.</para> - </sect1> - - <sect1> - <title>Portlint</title> - - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> - before you submit or commit it.</para> - </sect1> - - <sect1> - <title>Feedback</title> - - <para>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.</para> - </sect1> - - <sect1> - <title><filename>README.html</filename></title> - - <para>Do not include the <filename>README.html</filename> file. This - file is not part of the cvs collection but is generated using the - <command>make readme</command> command. - </para> - </sect1> - - <sect1> - <title>Miscellanea</title> - - <para>The files <filename>pkg-comment</filename>, - <filename>pkg-descr</filename>, and <filename>pkg-plist</filename> - should each be double-checked. If you are reviewing a port and feel - they can be worded better, do so.</para> - - <para>Do not copy more copies of the GNU General Public License into - our system, please.</para> - - <para>Please be careful to note any legal issues! Do not let us - illegally distribute software!</para> - </sect1> - - <sect1> - <title>If you are stuck…</title> - - <para>Do look at existing examples and the - <filename>bsd.port.mk</filename> file before asking us questions! - <!-- smiley --><emphasis>;-)</emphasis></para> - - <para>Do ask us questions if you have any trouble! Do not just beat - your head against a wall! <!-- smiley - --><emphasis>:-)</emphasis></para> - </sect1> - </chapter> - - <chapter id="porting-samplem"> - <title>A Sample <filename>Makefile</filename></title> - - <para>Here is a sample <filename>Makefile</filename> that you can use to - create a new port. Make sure you remove all the extra comments (ones - between brackets)!</para> - - <para>It is recommended that you follow this format (ordering of - variables, empty lines between sections, etc.). This format is - designed so that the most important information is easy to locate. We - recommend that you use <link - linkend="porting-portlint">portlint</link> to check the - <filename>Makefile</filename>.</para> - - <programlisting> -[the header...just to make it easier for us to identify the ports.] -# New ports collection makefile for: xdvi -[the "version required" line is only needed when the PORTVERSION - variable is not specific enough to describe the port.] -# Version required: pl18 + japanization patches 18.1 and 18.2 -[this is the date when the first version of this Makefile was created. -Never change this when doing an update of the port.] -# Date created: 26 May 1995 -[this is the person who did the original port to FreeBSD, in particular, the -person who wrote the first version of this Makefile. Remember, this should -not be changed when upgrading the port later.] -# Whom: Satoshi Asami <asami@FreeBSD.org> -# -# $FreeBSD$ -[ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS -when it is committed to our repository. If upgrading a port, do not alter -this line back to "$FreeBSD$". CVS deals with it automatically.] -# - -[section to describe the port itself and the master site - PORTNAME - and PORTVERSION are always first, followed by CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. - Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then - EXTRACT_ONLY, as necessary.] -PORTNAME= xdvi -PORTVERSION= 18.2 -CATEGORIES= print -[do not forget the trailing slash ("/")! - if you are not using MASTER_SITE_* macros] -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications -PKGNAMEPREFIX= ja- -DISTNAME= xdvi-pl18 -[set this if the source is not in the standard ".tar.gz" form] -EXTRACT_SUFX= .tar.Z - -[section for distributed patches -- can be empty] -PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ -PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz - -[maintainer; *mandatory*! This is the person (preferably with commit - privileges) whom 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 do not want to have - your address here, set it to "ports@FreeBSD.org".] -MAINTAINER= asami@FreeBSD.org - -[dependencies -- can be empty] -RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript -LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm - -[this section is for other standard bsd.port.mk variables that do not - belong to any of the above] -[If it asks questions during configure, build, install...] -IS_INTERACTIVE= yes -[If it extracts to a directory other than ${DISTNAME}...] -WRKSRC= ${WRKDIR}/xdvi-new -[If the distributed patches were not made relative to ${WRKSRC}, you - may need to tweak this] -PATCH_DIST_STRIP= -p1 -[If it requires a "configure" script generated by GNU autoconf to be run] -GNU_CONFIGURE= yes -[If it requires GNU make, not /usr/bin/make, to build...] -USE_GMAKE= yes -[If it is an X application and requires "xmkmf -a" to be run...] -USE_IMAKE= yes -[et cetera.] - -[non-standard variables to be used in the rules below] -MY_FAVORITE_RESPONSE= "yeah, right" - -[then the special rules, in the order they are called] -pre-fetch: - i go fetch something, yeah - -post-patch: - i need to do something after patch, great - -pre-install: - and then some more stuff before installing, wow - -[and then the epilogue] -.include <bsd.port.mk></programlisting> - </chapter> - - <chapter id="porting-autoplist"> - <title>Automated package list creation</title> - - <para>First, make sure your port is almost complete, with only - <filename>pkg-plist</filename> missing. Create an empty - <filename>pkg-plist</filename>.</para> - - <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen> - - <para>Next, create a new set of directories which your port can be - installed, and install any dependencies.</para> - - <screen>&prompt.root; <userinput>mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/<replaceable>port-name</replaceable></userinput> -&prompt.root; <userinput>make depends PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> - - <para>Store the directory structure in a new file.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * -type d) > OLD-DIRS</userinput></screen> - - <para>If your port honors <makevar>PREFIX</makevar> (which it should) - you can then install the port and create the package list.</para> - - <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput> -&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) > pkg-plist</userinput></screen> - - <para>You must also add any newly created directories to the packing - list.</para> - - <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' >> pkg-plist</replaceable></userinput></screen> - - <para>Finally, you need to tidy up the packing list by hand. I lied - when I said this was all automated. Manual pages should be listed in - the port's <filename>Makefile</filename> under - <makevar>MAN<replaceable>n</replaceable></makevar>, and not in the - package list. User configuration files should be removed, or - installed as - <filename><replaceable>filename</replaceable>.sample</filename>. - The <filename>info/dir</filename> file should not be listed - and appropriate <filename>install-info</filename> lines should - be added as noted in the <link linkend="porting-info">info - files</link> section. Any - libraries installed by the port should be listed as specified in the - <link linkend="porting-shlibs">shared libraries</link> section.</para> - </chapter> - - <chapter id="porting-pkgname"> - <title>Package Names</title> - - <para>The following are the conventions you should follow in naming your - packages. This is to have our package directory easy to scan, as - there are already lots and lots of packages and users are going to - turn away if they hurt their eyes!</para> - - <para>The package name should look like - <filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>.</para> - - <para>The package name is defined as - <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. - Make sure to set the variables to conform to that format.</para> - - <orderedlist> - <listitem> - <para>FreeBSD strives to support the native language of its users. - The <replaceable>language-</replaceable> part should be a two - letter abbreviation of the natural language defined by ISO-639 if - the port is specific to a certain language. Examples are - <literal>ja</literal> for Japanese, <literal>ru</literal> for - Russian, <literal>vi</literal> for Vietnamese, - <literal>zh</literal> for Chinese, <literal>ko</literal> for - Korean and <literal>de</literal> for German.</para> - - <para>If the port is specific to a certain region within the - language area, add the two letter country code as well. - Examples are <literal>en_US</literal> for US English and - <literal>fr_CH</literal> for Swiss French.</para> - - <para>The <replaceable>language-</replaceable> part should - be set in the <makevar>PKGNAMEPREFIX</makevar> variable.</para> - </listitem> - - <listitem> - <para>The first letter of <filename>name</filename> part - should be lowercase. (The rest of the name can contain - capital letters, so use your own descretion when you are - converting a software name that has some capital letters in it.) - There is a tradition of naming Perl 5 modules by - prepending <literal>p5-</literal> and converting the double-colon - separator to a hyphen; for example, the - <literal>Data::Dumper</literal> module becomes - <literal>p5-Data-Dumper</literal>. If the software in question - has numbers, hyphens, or underscores in its name, you may include - them as well (like <literal>kinput2</literal>).</para> - </listitem> - - <listitem> - <para>If the port can be built with different <link - linkend="porting-masterdir">hardcoded defaults</link> (usually - part of the directory name in a family of ports), the - <replaceable>-compiled.specifics</replaceable> part should state - the compiled-in defaults (the hyphen is optional). Examples are - papersize and font units.</para> - - <para>The <replaceable>compiled.specifics</replaceable> part - should be set in the <makevar>PKGNAMESUFFIX</makevar> - variable.</para> - </listitem> - - <listitem> - <para>The version string should follow a dash - (<literal>-</literal>) and be a period-separated list of - integers and single lowercase alphabetics. In particular, - it is not permissible to have another dash inside the - version string. The only exception is the string - <literal>pl</literal> (meaning `patchlevel'), which can be - used <emphasis>only</emphasis> when there are no major and - minor version numbers in the software. If the software - version has strings like "alpha", "beta", or "pre", take - the first letter and put it immediately after a period. - If the version string continues after those names, the - numbers should follow the single alphabet without an extra - period between them.</para> - - <para>The idea is to make it easier to sort ports by looking - at the version string. In particular, make sure version - number components are always delimited by a period, and - if the date is part of the string, use the - <literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> - format, not - <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> - or the non-Y2K compliant - <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> - format.</para> - </listitem> - </orderedlist> - - <para>Here are some (real) examples on how to convert the name - as called by the software authors to a suitable package - name:</para> - - <informaltable frame="none"> - <tgroup cols="6"> - <thead> - <row> - <entry>Distribution Name</entry> - <entry><makevar>PKGNAMEPREFIX</makevar></entry> - <entry><makevar>PORTNAME</makevar></entry> - <entry><makevar>PKGNAMESUFFIX</makevar></entry> - <entry><makevar>PORTVERSION</makevar></entry> - <entry>Reason</entry> - </row> - </thead> - - <tbody> - <row> - <entry>mule-2.2.2</entry> - <entry>(empty)</entry> - <entry>mule</entry> - <entry>(empty)</entry> - <entry>2.2.2</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>XFree86-3.3.6</entry> - <entry>(empty)</entry> - <entry>XFree86</entry> - <entry>(empty)</entry> - <entry>3.3.6</entry> - <entry>No changes required</entry> - </row> - - <row> - <entry>EmiClock-1.0.2</entry> - <entry>(empty)</entry> - <entry>emiclock</entry> - <entry>(empty)</entry> - <entry>1.0.2</entry> - <entry>No uppercase names for single programs</entry> - </row> - - <row> - <entry>rdist-1.3alpha</entry> - <entry>(empty)</entry> - <entry>rdist</entry> - <entry>(empty)</entry> - <entry>1.3.a</entry> - <entry>No strings like <literal>alpha</literal> - allowed</entry> - </row> - - <row> - <entry>es-0.9-beta1</entry> - <entry>(empty)</entry> - <entry>es</entry> - <entry>(empty)</entry> - <entry>0.9.b1</entry> - <entry>No strings like <literal>beta</literal> - allowed</entry> - </row> - - <row> - <entry>v3.3beta021.src</entry> - <entry>(empty)</entry> - <entry>tiff</entry> - <entry>(empty)</entry> - <entry>3.3</entry> - <entry>What the heck was that anyway?</entry> - </row> - - <row> - <entry>tvtwm</entry> - <entry>(empty)</entry> - <entry>tvtwm</entry> - <entry>(empty)</entry> - <entry>pl11</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>piewm</entry> - <entry>(empty)</entry> - <entry>piewm</entry> - <entry>(empty)</entry> - <entry>1.0</entry> - <entry>Version string always required</entry> - </row> - - <row> - <entry>xvgr-2.10pl1</entry> - <entry>(empty)</entry> - <entry>xvgr</entry> - <entry>(empty)</entry> - <entry>2.10.1</entry> - <entry><literal>pl</literal> allowed only when no - major/minor version numbers</entry> - </row> - - <row> - <entry>gawk-2.15.6</entry> - <entry>ja-</entry> - <entry>gawk</entry> - <entry>(empty)</entry> - <entry>2.15.6</entry> - <entry>Japanese language version</entry> - </row> - - <row> - <entry>psutils-1.13</entry> - <entry>(empty)</entry> - <entry>psutils</entry> - <entry>-letter</entry> - <entry>1.13</entry> - <entry>Papersize hardcoded at package build time</entry> - </row> - - <row> - <entry>pkfonts</entry> - <entry>(empty)</entry> - <entry>pkfonts</entry> - <entry>300</entry> - <entry>1.0</entry> - <entry>Package for 300dpi fonts</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If there is absolutely no trace of version information in the - original source and it is unlikely that the original author will ever - release another version, just set the version string to - <literal>1.0</literal> (like the piewm example above). Otherwise, ask - the original author or use the date string - (<literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) - as the version.</para> - </chapter> - - <chapter id="porting-categories"> - <title>Categories</title> - - <para>As you already know, ports are classified in several categories. - But for this to work, it is important that porters and users understand - what each category is for and how we decide what to put in each - category.</para> - - <sect1> - <title>Current list of categories</title> - - <para>First, this is the current list of port categories. Those - marked with an asterisk (<literal>*</literal>) are - <emphasis>virtual</emphasis> categories—those that do not have - a corresponding subdirectory in the ports tree.</para> - - <note> - <para>For non-virtual categories, you will find a one-line - description in the <filename>pkg/COMMENT</filename> file in that - subdirectory (e.g., - <filename>archivers/pkg/COMMENT</filename>).</para> - </note> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Category</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><filename>afterstep*</filename></entry> - <entry>Ports to support the AfterStep window manager.</entry> - </row> - - <row> - <entry><filename>archivers</filename></entry> - <entry>Archiving tools.</entry> - </row> - - <row> - <entry><filename>astro</filename></entry> - <entry>Astronomical ports.</entry> - </row> - - <row> - <entry><filename>audio</filename></entry> - <entry>Sound support.</entry> - </row> - - <row> - <entry><filename>benchmarks</filename></entry> - <entry>Benchmarking utilities.</entry> - </row> - - <row> - <entry><filename>biology</filename></entry> - <entry>Biology-related software.</entry> - </row> - - <row> - <entry><filename>cad</filename></entry> - <entry>Computer aided design tools.</entry> - </row> - - <row> - <entry><filename>chinese</filename></entry> - <entry>Chinese language support.</entry> - </row> - - <row> - <entry><filename>comms</filename></entry> - <entry>Communication software. Mostly software to talk to - your serial port.</entry> - </row> - - <row> - <entry><filename>converters</filename></entry> - <entry>Character code converters.</entry> - </row> - - <row> - <entry><filename>databases</filename></entry> - <entry>Databases.</entry> - </row> - - <row> - <entry><filename>deskutils</filename></entry> - <entry>Things that used to be on the desktop before - computers were invented.</entry> - </row> - - <row> - <entry><filename>devel</filename></entry> - <entry>Development utilities. Do not put libraries here just - because they are libraries—unless they truly do not - belong anywhere else, they should not be in this - category.</entry> - </row> - - <row> - <entry><filename>editors</filename></entry> - <entry>General editors. Specialized editors go in the section - for those tools (e.g., a mathematical-formula editor will go - in <filename>math</filename>).</entry> - </row> - - <row> - <entry><filename>elisp*</filename></entry> - <entry>Emacs-lisp ports.</entry> - </row> - - <row> - <entry><filename>emulators</filename></entry> - <entry>Emulators for other operating systems. Terminal - emulators do <emphasis>not</emphasis> belong - here—X-based ones should go to - <filename>x11</filename> and text-based ones to either - <filename>comms</filename> or <filename>misc</filename>, - depending on the exact functionality.</entry> - </row> - - <row> - <entry><filename>french</filename></entry> - <entry>French language support.</entry> - </row> - - <row> - <entry><filename>ftp</filename></entry> - <entry>FTP client and server utilities. If your - port speaks both FTP and HTTP, put it in - <filename>ftp</filename> with a secondary - category of <filename>www</filename>.</entry> - </row> - - <row> - <entry><filename>games</filename></entry> - <entry>Games.</entry> - </row> - - <row> - <entry><filename>german</filename></entry> - <entry>German language support.</entry> - </row> - - <row> - <entry><filename>gnome*</filename></entry> - <entry>Ports from the GNU Object Model Environment (GNOME) - Project.</entry> - </row> - - <row> - <entry><filename>graphics</filename></entry> - <entry>Graphics utilities.</entry> - </row> - - <row> - <entry><filename>hebrew</filename></entry> - <entry>Hebrew language support.</entry> - </row> - - <row> - <entry><filename>irc</filename></entry> - <entry>Internet Relay Chat utilities.</entry> - </row> - - <row> - <entry><filename>ipv6*</filename></entry> - <entry>IPv6 related software.</entry> - </row> - - <row> - <entry><filename>japanese</filename></entry> - <entry>Japanese language support.</entry> - </row> - - <row> - <entry><filename>java</filename></entry> - <entry>Java language support.</entry> - </row> - - <row> - <entry><filename>kde*</filename></entry> - <entry>Ports from the K Desktop Environment (KDE) - Project.</entry> - </row> - - <row> - <entry><filename>korean</filename></entry> - <entry>Korean language support.</entry> - </row> - - <row> - <entry><filename>lang</filename></entry> - <entry>Programming languages.</entry> - </row> - - <row> - <entry><filename>linux*</filename></entry> - <entry>Linux applications and support utilities.</entry> - </row> - - <row> - <entry><filename>mail</filename></entry> - <entry>Mail software.</entry> - </row> - - <row> - <entry><filename>math</filename></entry> - <entry>Numerical computation software and other utilities - for mathematics.</entry> - </row> - - <row> - <entry><filename>mbone</filename></entry> - <entry>MBone applications.</entry> - </row> - - <row> - <entry><filename>misc</filename></entry> - <entry>Miscellaneous utilities—basically things that - do not belong anywhere else. This is the only category - that should not appear with any other non-virtual category. - If you have <literal>misc</literal> with something else in - your <makevar>CATEGORIES</makevar> line, that means you can - safely delete <literal>misc</literal> and just put the port - in that other subdirectory!</entry> - </row> - - <row> - <entry><filename>net</filename></entry> - <entry>Miscellaneous networking software.</entry> - </row> - - <row> - <entry><filename>news</filename></entry> - <entry>USENET news software.</entry> - </row> - - <row> - <entry><filename>offix*</filename></entry> - <entry>Ports from the OffiX suite.</entry> - </row> - - <row> - <entry><filename>palm</filename></entry> - <entry>Software support for the 3Com Palm(tm) series.</entry> - </row> - - <row> - <entry><filename>perl5*</filename></entry> - <entry>Ports that require perl version 5 to run.</entry> - </row> - - <row> - <entry><filename>plan9*</filename></entry> - <entry>Various programs from Plan9.</entry> - </row> - - <row> - <entry><filename>print</filename></entry> - <entry>Printing software. Desktop publishing tools - (previewers, etc.) belong here too.</entry> - </row> - - <row> - <entry><filename>python*</filename></entry> - <entry>Software written in python.</entry> - </row> - - <row> - <entry><filename>ruby*</filename></entry> - <entry>Software written in ruby.</entry> - </row> - - <row> - <entry><filename>russian</filename></entry> - <entry>Russian language support.</entry> - </row> - - <row> - <entry><filename>security</filename></entry> - <entry>Security utilities.</entry> - </row> - - <row> - <entry><filename>shells</filename></entry> - <entry>Command line shells.</entry> - </row> - - <row> - <entry><filename>sysutils</filename></entry> - <entry>System utilities.</entry> - </row> - - <row> - <entry><filename>tcl76*</filename></entry> - <entry>Ports that use Tcl version 7.6 to run.</entry> - </row> - - <row> - <entry><filename>tcl80*</filename></entry> - <entry>Ports that use Tcl version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tcl81*</filename></entry> - <entry>Ports that use Tcl version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>tcl82*</filename></entry> - <entry>Ports that use Tcl version 8.2 to run.</entry> - </row> - - <row> - <entry><filename>textproc</filename></entry> - <entry>Text processing utilities. It does not include - desktop publishing tools, which go to print/.</entry> - </row> - - <row> - <entry><filename>tk42*</filename></entry> - <entry>Ports that use Tk version 4.2 to run.</entry> - </row> - - <row> - <entry><filename>tk80*</filename></entry> - <entry>Ports that use Tk version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>tk81*</filename></entry> - <entry>Ports that use Tk version 8.1 to run.</entry> - </row> - - <row> - <entry><filename>tk82*</filename></entry> - <entry>Ports that use Tk version 8.2 to run.</entry> - </row> - - <row> - <entry><filename>tkstep80*</filename></entry> - <entry>Ports that use TkSTEP version 8.0 to run.</entry> - </row> - - <row> - <entry><filename>vietnamese</filename></entry> - <entry>Vietnamese language support.</entry> - </row> - - <row> - <entry><filename>windowmaker*</filename></entry> - <entry>Ports to support the WindowMaker window - manager</entry> - </row> - - <row> - <entry><filename>www</filename></entry> - <entry>Software related to the World Wide Web. HTML language - support belongs here too.</entry> - </row> - - <row> - <entry>x11</entry> - <entry>The X window system and friends. This category is only - for software that directly supports the window system. Do not - put regular X applications here. If your port is an X - application, define <makevar>USE_XLIB</makevar> (implied by - <makevar>USE_IMAKE</makevar>) and put it in the appropriate - categories. Also, many of them go into other - <filename>x11-*</filename> categories (see below).</entry> - </row> - - <row> - <entry><filename>x11-clocks</filename></entry> - <entry>X11 clocks.</entry> - </row> - - <row> - <entry><filename>x11-fm</filename></entry> - <entry>X11 file managers.</entry> - </row> - - <row> - <entry><filename>x11-fonts</filename></entry> - <entry>X11 fonts and font utilities.</entry> - </row> - - <row> - <entry><filename>x11-servers</filename></entry> - <entry>X11 servers.</entry> - </row> - - <row> - <entry><filename>x11-toolkits</filename></entry> - <entry>X11 toolkits.</entry> - </row> - - <row> - <entry><filename>x11-wm</filename></entry> - <entry>X11 window managers.</entry> - </row> - - <row> - <entry><filename>zope*</filename></entry> - <entry>Zope support.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Choosing the right category</title> - - <para>As many of the categories overlap, you often have to choose - which of the categories should be the primary category of your port. - There are several rules that govern this issue. Here is the list of - priorities, in decreasing order of precedence.</para> - - <itemizedlist> - <listitem> - <para>Language specific categories always come first. For - example, if your port installs Japanese X11 fonts, then your - <makevar>CATEGORIES</makevar> line would read <literal>japanese - x11-fonts</literal>.</para> - </listitem> - - <listitem> - <para>Specific categories win over less-specific ones. For - instance, an HTML editor should be listed as <literal>www - editors</literal>, not the other way around. Also, you do not - need to list <literal>net</literal> when the port belongs to - any of <literal>irc</literal>, <literal>mail</literal>, - <literal>mbone</literal>, <literal>news</literal>, - <literal>security</literal>, or <literal>www</literal>.</para> - </listitem> - - <listitem> - <para><literal>x11</literal> is used as a secondary category only - when the primary category is a natural language. In particular, - you should not put <literal>x11</literal> in the category line - for X applications.</para> - </listitem> - - <listitem> - <para><application>Emacs</application> modes should be - placed in the same ports category as the application - supported by the mode, not in - <filename>editors</filename>. For example, an - <application>Emacs</application> mode to edit source - files of some programming language should go into - <filename>lang</filename>. - </para> - </listitem> - - <listitem> - <para>If your port truly does not belong anywhere else, put it in - <literal>misc</literal>.</para> - </listitem> - </itemizedlist> - - <para>If you are not sure about the category, please put a comment to - that effect in your <command>send-pr</command> submission so we can - discuss it before we import it. If you are a committer, send a note - to the &a.ports; so we can discuss it first—too often new ports are - imported to the wrong category only to be moved right away.</para> - </sect1> - </chapter> - - <chapter> - <title>Changes to this document and the ports system</title> - - <para>If you maintain a lot of ports, you should consider following the - &a.ports;. Important changes to the way ports work will be announced - there. You can always find more detailed information on the latest - changes by looking at <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk"> the - bsd.port.mk CVS log</ulink>.</para> - </chapter> - - <chapter> - <title>That is It, Folks!</title> - - <para>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really. Now that you know how to do a port, - have at it and convert everything in the world into ports! That - is the easiest way to start contributing to the FreeBSD Project! - <!-- smiley --><emphasis>:-)</emphasis></para> - </chapter> -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/books/porters-handbook/freebsd.dsl b/en_US.ISO8859-1/books/porters-handbook/freebsd.dsl deleted file mode 100644 index 015ec7d482..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/freebsd.dsl +++ /dev/null @@ -1,41 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/books/porters-handbook/freebsd.dsl,v 1.1 2000/05/09 00:30:11 nik Exp $ --> - -<!-- Local DSSSL file for the Porter's Handbook. This is so we can include - a link to the -ports mailing list at the bottom of the HTML files, - rather than the -questions mailing list. --> - -<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ -<!ENTITY freebsd.dsl SYSTEM "../../share/sgml/freebsd.dsl" CDATA DSSSL> -]> - -<style-sheet> - <style-specification use="docbook"> - <style-specification-body> - - <![ %output.html; [ - (define ($email-footer$) - (make sequence - (literal "For questions about the FreeBSD ports system, e-mail <") - (make element gi: "a" - attributes: (list (list "href" "mailto:ports@freebsd.org")) - (literal "ports@freebsd.org")) - (literal ">.") - (make empty-element gi: "br") - (literal "For questions about this documentation, e-mail <") - (make element gi: "a" - attributes: (list (list "href" "mailto:doc@freebsd.org")) - (literal "doc@freebsd.org")) - (literal ">."))) - - <!-- Convert " ... " to `` ... '' in the HTML output. --> - (element quote - (make sequence - (literal "``") - (process-children) - (literal "''"))) - ]]> - </style-specification-body> - </style-specification> - - <external-specification id="docbook" document="freebsd.dsl"> -</style-sheet> diff --git a/en_US.ISO8859-1/books/ppp-primer/Makefile b/en_US.ISO8859-1/books/ppp-primer/Makefile deleted file mode 100644 index 769be1a879..0000000000 --- a/en_US.ISO8859-1/books/ppp-primer/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/books/faq/Makefile,v 1.6 1999/09/06 06:52:39 peter Exp $ -# -# Build the PPP PrimerQ -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/ppp-primer/book.sgml b/en_US.ISO8859-1/books/ppp-primer/book.sgml deleted file mode 100644 index 66e5d87e8f..0000000000 --- a/en_US.ISO8859-1/books/ppp-primer/book.sgml +++ /dev/null @@ -1,2359 +0,0 @@ -<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> -<book> - -<bookinfo> -<title>PPP - Pedantic PPP Primer</title> - -<authorgroup> -<author> -<firstname>Steve</firstname> -<surname>Sims</surname> -<affiliation> -<address><email>SimsS@IBM.net</email></address> -</affiliation> -</author> -</authorgroup> - -<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v 1.4 2000/07/26 01:14:22 ben Exp $</pubdate> - -<abstract><para>This is a step-by-step guide for configuring FreeBSD systems to act as -a dial-up router/gateway in a Local Area Environment. All entries may -be assumed to be relevant to FreeBSD 2.2+, unless otherwise noted.</para></abstract> - -</bookinfo> - -<preface> -<title>Overview:</title> - -<para>The User-Mode PPP dialer in FreeBSD Version 2.2 (also known as: -<emphasis remap=it>"IIJ-PPP"</emphasis> ) now supports Packet Aliasing for dial up -connections to the Internet. This feature, also known as -"<emphasis remap=it>Masquerading</emphasis>", "<emphasis remap=it>IP Aliasing</emphasis>", or "<emphasis remap=it>Network Address -Translation</emphasis>", allows a FreeBSD system to act as a dial- on-demand -router between an Ethernet-based Local Area Network and an Internet -Service Provider. Systems on the LAN can use the FreeBSD system to -forward information between the Internet by means of a single -dial-connection.</para> - -<para>This guide explains how to: -<itemizedlist> - -<listitem> -<para>Configure the FreeBSD system to support dial-out connections,</para> -</listitem> - -<listitem> -<para>Share a dial-out connection with other systems in a network,</para> -</listitem> - -<listitem> -<para>Configure Windows platforms to use the FreeBSD system as a gateway to the Internet.</para> -</listitem> - -</itemizedlist> -</para> - -<para>While the focus of this guide is to assist in configuring IP Aliasing, -it also includes specific examples of the configuration steps necessary -to configure and install each individual component; each section stands -alone and may be used to assist in the configuration of various aspects -of FreeBSD internetworking.</para> - -</preface> - -<chapter> -<title>Building the Local Area Network</title> - -<para> While the ppp program can, and usually is, be configured to provide -services to <emphasis>only</emphasis> the local FreeBSD box it can also be used to serve as a -"Gateway" (or "router") between other LAN-connected resources and the Internet or -other Dial-Up service.</para> - - -<sect1> -<title>Typical Network Topology</title> - -<para>This guide assumes a typical Local Area Network lashed together as -follows: -<programlisting> -+---------+ ----> Dial-Up Internet Connection -| FreeBSD | \ (i.e.: NetCom, AOL, AT&T, EarthLink, -etc) -| |-------- -| "Curly" | -| | -+----+----+ - | -|----+-------------+-------------+----| <-- Ethernet Network - | | | - | | | -+----+----+ +----+----+ +----+----+ -| | | | | | -| Win95 | | WFW | | WinNT | -| "Larry" | | "Moe" | | "Shemp" | -| | | | | | -+---------+ +---------+ +---------+</programlisting> -</para> - -</sect1> - -<sect1> -<title>Assumptions about the Local Area Network</title> - -<para>Some specific assumptions about this sample network are:</para> - -<para>Three workstations and a Server are connected with Ethernet -cabling: -<itemizedlist> - -<listitem> -<para>a FreeBSD Server ("Curly") with an NE-2000 adapter configured as -'ed0'</para> -</listitem> - -<listitem> -<para>a Windows-95 workstation ("Larry") with Microsoft's "native" -32-bit TCP/IP drivers</para> -</listitem> - -<listitem> -<para>a Windows for Workgroups workstation ("Moe") with Microsoft's -16-bit TCP/IP extensions</para> -</listitem> - -<listitem> -<para>a Windows NT workstation ("Shemp") with Microsoft's "native" -32-bit TCP/IP drivers</para> -</listitem> - -</itemizedlist> - </para> - -<para>The IP addresses on the Ethernet side of this sample LAN have been -taken from a pool addresses proposed reserved by RFC 1918 for use on -private LANs, so you are free to use these actual IP addresses on your -own LAN if you want. IP addresses are assigned as follows:</para> - -<informaltable> - <tgroup cols=3> - <thead> - <row> - <entry>Name</entry> - <entry>IP Address</entry> - <entry>Comment</entry> - </row> - </thead> - - <tbody> - <row> - <entry><hostid>Curly</hostid></entry> - <entry><hostid role="ipaddr">192.168.1.1</hostid></entry> - <entry>The FreeBSD box</entry> - </row> - - <row> - <entry><hostid>Larry</hostid></entry> - <entry><hostid role="ipaddr">192.168.1.2</hostid></entry> - <entry>The Win'95 box</entry> - </row> - - <row> - <entry><hostid>Moe</hostid></entry> - <entry><hostid role="ipaddr">192.168.1.3</hostid></entry> - <entry>The WfW box</entry> - </row> - - <row> - <entry><hostid>Shemp</hostid></entry> - <entry><hostid role="ipaddr">192.168.1.4</hostid></entry> - <entry>The Windows NT box</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<para>This guide assumes that the modem on the FreeBSD box is connected -to the first serial port ('<filename>/dev/cuaa0</filename>' or '<emphasis remap=tt>COM1:</emphasis>' in -DOS-terms).</para> - -<para>Finally, we'll also assume that your Internet Service Provider (ISP) -automatically provides the IP addresses of both your PPP/FreeBSD side -as well as the ISP's side. (i.e.: Dynamic IP Addresses on both ends -of the link.) Specific details for configuring the Dial-Out side of -PPP will be addressed in Section 2, "Configuring the FreeBSD System".</para> - -</sect1> -</chapter> - -<chapter id="system-config"> -<title>FreeBSD System Configuration</title> - -<para>There are three basic pieces of information that must be known to -the FreeBSD box before you can proceed with integrating the sample -Local Area Network:</para> - -<para> -<itemizedlist> - -<listitem> -<para>The Host Name of the FreeBSD system; in our example it's "Curly",</para> -</listitem> - -<listitem> -<para>The Network configuration,</para> -</listitem> - -<listitem> -<para>The <filename>/etc/hosts</filename> file (which lists the names and IP addresses of -the other systems in your network)</para> -</listitem> - -</itemizedlist> -</para> - -<para>If you performed the installation of FreeBSD over a network -connection some of this information may already be configured into -your FreeBSD system.</para> - -<para>Even if you believe that the FreeBSD system was properly configured -when it was installed you should at least verify each of these bits of -information to prevent trouble in subsequent steps.</para> - - -<sect1> -<title>Verifying the FreeBSD Host Name</title> - -<para>It's possible that the FreeBSD host name was specified and saved -when the system was initially installed. To verify that it was, enter -the following command at a prompt:</para> - -<para> -<informalexample> -<screen># hostname</screen> -</informalexample> -</para> - -<para>The name of the host FreeBSD system will be displayed on a single -line. If the name looks correct (this is very subjective :-) skip -ahead to <xref linkend="verify-ether-if-config">.</para> - -<para>For example, in our sample network, we would see 'curly.my.domain' -as a result of the `hostname` command if the name had been set -correctly during, or after, installation. (At this point, don't worry -too much about the ".my.domain" part, we'll sort this out later. The -important part is the name up to the first dot.)</para> - -<para>If a host name wasn't specified when FreeBSD was installed you'll -probably see 'myname.my.domain` as a response. You'll need to edit -<filename>/etc/rc.conf</filename> to set the name of the machine.</para> - - -<sect2> -<title>Configuring the FreeBSD Host Name</title> - -<para><emphasis><emphasis remap=bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</emphasis></emphasis></para> - -<para><emphasis><emphasis remap=bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</emphasis></emphasis></para> - -<para>The configuration file that specifies the FreeBSD system's host -name when the system boots is in <filename>/etc/rc.conf</filename>. Use the -default text editor ('<emphasis remap=tt>ee</emphasis>') to edit this file.</para> - -<para>Logged in as user 'root' load <filename>/etc/rc.conf</filename> into the -editor with the following command: -<informalexample> -<screen># ee /etc/rc.conf</screen> -</informalexample> -</para> - -<para>Using the arrow keys, scroll down until you find the line that -specifies the host name of the FreeBSD system. By default, this -section says: -<informalexample> -<screen>--- -### Basic network options: ### -hostname="myname.my.domain" # Set this! ----</screen> -</informalexample> - -Change this section to say (in our example): -<informalexample> -<screen>--- -### Basic network options: ### -hostname="curly.my.domain" # Set this! ----</screen> -</informalexample> -</para> - -<para>Once the change to the host name has been made, press the 'Esc' key to -access the command menu. Select "leave editor" and make sure to -specify "save changes" when prompted.</para> - -</sect2> -</sect1> - -<sect1 id="verify-ether-if-config"> -<title>Verifying the Ethernet Interface Configuration</title> - -<para>To reiterate our basic assumption, this guide assumes that the -Ethernet Interface in the FreeBSD system is named '<emphasis remap=tt>ed0</emphasis>'. This is -the default for NE-1000, NE-2000, WD/SMC models 8003, 8013 and Elite -Ultra (8216) network adapters.</para> - -<para>Other models of network adapters may have different device names in -FreeBSD. Check the FAQ for specifics about your network adapter. If -you're not sure of the device name of your adapter, check the FreeBSD -FAQ to determine the device name for the card you have and substitute -that name (i.e.: '<emphasis remap=tt>de0</emphasis>', '<emphasis remap=tt>zp0</emphasis>', or similar) in the following -steps.</para> - -<para>As was the case with the host name, the configuration for the -FreeBSD system's Ethernet Interface may have been specified when the -system was installed.</para> - -<para>To display the configuration for the interfaces in your -FreeBSD system (Ethernet and others), enter the following command: -<informalexample> -<screen># ifconfig -a</screen> -</informalexample> - -(In layman's terms: "Show me the <emphasis remap=bf>I</emphasis>nter<emphasis remap=bf>F</emphasis>ace <acronym>CONFIG</acronym>uration -for my network devices.") </para> - -<para>An example: -<informalexample> -<screen># ifconfig -a - ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu -1500 - inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255 - ether 01:02:03:04:05:06 - lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 - tun0: flags=8050<POINTOPOINT,RUNNING, MULTICAST> mtu 1500 - sl0: flags=c010<POINTOPOINT,LINK2,MULTICAST> mtu 552 - ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 - lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 - inet 127.0.0.1 netmask 0xff000000 -# _</screen> -</informalexample> -</para> - -<para>In this example, the following devices were displayed:</para> - -<para><emphasis remap=tt>ed0:</emphasis> The Ethernet Interface</para> - -<para><emphasis remap=tt>lp0:</emphasis> The Parallel Port Interface (ignored in this guide)</para> - -<para><emphasis remap=tt>tun0:</emphasis> The "tunnel" device; <emphasis>This is the one user-mode ppp uses!</emphasis></para> - -<para><emphasis remap=tt>sl0:</emphasis> The SL/IP device (ignored in this guide)</para> - -<para><emphasis remap=tt>ppp0:</emphasis> Another PPP device (for kernel ppp; ignored in this guide)</para> - -<para><emphasis remap=tt>lo0:</emphasis> The "Loopback" device (ignored in this guide)</para> - -<para>In this example, the 'ed0' device is up and running. The key -indicators are: -<orderedlist> - -<listitem> -<para>Its status is "<acronym>UP</acronym>",</para> -</listitem> - -<listitem> -<para>It has an Internet ("<emphasis remap=tt>inet</emphasis>") address, (in this case, 192.168.1.1)</para> -</listitem> - -<listitem> -<para>It has a valid Subnet Mask ("netmask"; 0xffffff00 is the same as -255.255.255.0), and</para> -</listitem> - -<listitem> -<para>It has a valid broadcast address (in this case, 192.168.1.255).</para> -</listitem> - -</orderedlist> -</para> - -<para>If the line for the Ethernet card had shown something similar to: -<informalexample> -<screen>ed0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 - ether 01:02:03:04:05:06</screen> -</informalexample> - -then the Ethernet card hasn't been configured yet.</para> - -<para>If the configuration for the Ethernet interface is correct you can -skip forward to <xref linkend="list-lan-hosts">.</para> - -<sect2 > -<title>Configuring your Ethernet Interface</title> - -<para><emphasis><emphasis remap=bf>Reminder: You must be logged in as 'root' to edit the -system configuration files!</emphasis></emphasis></para> - -<para><emphasis><emphasis remap=bf>CAUTION: If you mangle the system configuration files, -chances are your system WILL NOT BOOT correctly! Be careful!</emphasis></emphasis></para> - -<para>The configuration file that specifies settings for the network -interfaces when the system boots is in <filename>/etc/rc.conf</filename>. Use -the default text editor ('ee') to edit this file.</para> - -<para>Logged in as user 'root' load <filename>/etc/rc.conf</filename> into the -editor with the following command:</para> - -<para><command> # ee /etc/rc.conf</command></para> - -<para>About 20 lines from the top of <filename>/etc/rc.conf</filename> is the section -that describes which network interfaces should be activated when the -system boots. In the default configuration file the specific line -that controls this is:</para> - -<para> -<informalexample> -<screen>network_interfaces="lo0" # List of network interfaces (lo0 is loopback).</screen> -</informalexample> -</para> - -<para>You'll need to amend this line to tell FreeBSD that you want to add -another device, namely the '<emphasis remap=tt>ed0</emphasis>' device. Change this line to -read:</para> - -<para> -<informalexample> -<screen>network_interfaces="lo0 ed0" # List of network interfaces (lo0 is loopback).</screen> -</informalexample> -</para> - -<para>(Note the space between the definition for the loopback device -("<emphasis remap=tt>lo0</emphasis>") -and the Ethernet device ("<emphasis remap=tt>ed0</emphasis>")! </para> - -<para><emphasis><emphasis remap=bf> Reminder: If your Ethernet card isn't named '<emphasis remap=tt>ed0</emphasis>', specify -the correct device name here instead.</emphasis></emphasis></para> - -<para>If you performed the installation of FreeBSD over a network -connection then the '<literal>network_interfaces=</literal>' line may already -include a reference to your Ethernet adapter. If it is, verify that -it is the correct device name.</para> - -<para>Specify the Interface Settings for the Ethernet device -('<emphasis remap=tt>ed0</emphasis>'):</para> - -<para>Beneath the line that specifies which interfaces should be -activated are the lines that specify the actual settings for each -interface. In the default <filename>/etc/rc.conf</filename> file is a single -line that says:</para> - -<para> -<informalexample> -<screen>ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration.</screen> -</informalexample> -</para> - -<para>You'll need to add another line after that to specify the settings -for your '<emphasis remap=tt>ed0</emphasis>' device.</para> - -<para>If you performed the installation of FreeBSD over a network -connection then there may already be an '<literal>ifconfig_ed0=</literal>' line -after the loopback definition. If so, verify that it has the correct -values.</para> - -<para>For our sample configuration we'll insert a line immediately after -the loopback device definition that says:</para> - -<para> -<informalexample> -<screen>ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0"</screen> -</informalexample> -</para> - -<para>When you've finished editing <filename>/etc/rc.conf</filename> to specify and -configure the network interfaces the section should look really close -to:</para> - -<para> -<informalexample> -<screen>--- -network_interfaces="ed1 lo0" # List of network interfaces (lo0 is loopback). -ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration. -ifconfig_ed1="inet 192.168.1.1 netmask 255.255.255.0" ----</screen> -</informalexample> -</para> - -<para>Once all of the necessary changes to <filename>/etc/rc.conf</filename> have -been made, press the 'Esc' key to invoke the control menu. Select -"leave editor" and be sure to select "save changes" when prompted.</para> - -</sect2> -</sect1> - -<sect1> -<title>Enabling Packet Forwarding</title> - -<para>By default the FreeBSD system will not forward IP packets between -various network interfaces. In other words, routing functions (also -known as gateway functions) are disabled.</para> - -<para>If your intent is to use a FreeBSD system as stand-alone Internet -workstation and not as a gateway between LAN nodes and your ISP you -should skip forward to <xref linkend="list-lan-hosts">.</para> - -<para>If you intend for the PPP program to service the local FreeBSD box -as well as LAN workstations (as a router) you'll need to enable IP -forwarding.</para> - -<para>To enable IP Packet forwarding you'll need to edit the -<filename>/etc/rc.conf</filename> file.</para> - - <para>This file contains overrides of the defaults in - <filename>/etc/defaults/rc.conf</filename>. The default gateway - setting is controlled by the line</para> - - <programlisting>gateway_enable="NO"</programlisting> - - <para>in that file. To override it, add a line like</para> - - <programlisting>gateway_enable="YES"</programlisting> - - <para><filename>/etc/rc.conf</filename>.</para> - -<para><emphasis><emphasis remap=bf>NOTE: This line may already be set to -'<literal>gateway_enable="YES"</literal>' if IP forwarding was enabled when the -FreeBSD system was installed.</emphasis></emphasis></para> - -</sect1> - -<sect1 id="list-lan-hosts"> -<title>Creating the List of other LAN Hosts(<filename>/etc/hosts</filename>)</title> - -<para>The final step in configuring the LAN side of the FreeBSD system is -to create a list of the names and TCP/IP addresses of the various -systems that are connected to the Local Area Network. This list is -stored in the '<filename>/etc/hosts</filename>' file.</para> - -<para>The default version of this file has only a single host name -listing in it: the name and address of the loopback device ('lo0'). -By networking convention, this device is always named "localhost" and -always has an IP address of 127.0.0.1. <xref - linkend="verify-ether-if-config">.</para> - - -<para>To edit the <filename>/etc/hosts</filename> file enter the following command: -<informalexample> -<screen> # ee /etc/hosts </screen> -</informalexample> -</para> - -<para>Scroll all the way to the bottom of the file (paying attention to -the comments along the way; there's some good information there!) and -enter (assuming our sample network) the following IP addresses and -host names: -<informalexample> -<screen>192.168.1.1 curly curly.my.domain # FreeBSD System -192.168.1.2 larry larry.my.domain # Windows '95 System -192.168.1.3 moe moe.my.domain # Windows for Workgroups -System -192.168.1.4 shemp shemp.my.domain # Windows NT System</screen> -</informalexample> -</para> - -<para>(No changes are needed to the line for the '<emphasis remap=tt>127.0.0.1 -localhost</emphasis>' entry.)</para> - -<para>Once you've entered these lines, press the 'Esc' key to invoke the -control menu. Select "leave editor" and be sure to select "save -changes" when prompted.</para> - -</sect1> - -<sect1> -<title>Testing the FreeBSD system</title> - -<para>Congratulations! Once you've made it to this point, the FreeBSD -system is configured as a network-connected UNIX system! If you made -any changes to the <filename>/etc/rc.conf</filename> file you should probably -re-boot your FreeBSD system. This will accomplish two important -objectives: -<itemizedlist> - -<listitem> -<para>Allow the changes to the interface configurations to be applied, and</para> -</listitem> - -<listitem> -<para>Verify that the system restarts without any glaring configuration errors.</para> -</listitem> - -</itemizedlist> -</para> - -<para>Once the system has been rebooted you should test the network -interfaces.</para> - - -<sect2> -<title>Verifying the operation of the loopback device</title> - -<para>To verify that the loopback device is configured correctly, log in as -'root' and enter: -<informalexample> -<screen># ping localhost</screen> -</informalexample> -</para> - -<para>You should see: -<informalexample> -<screen># ping localhost -PING localhost.my.domain. (127.0.0.1): 56 data bytes -64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms -64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m -[...]</screen> -</informalexample> - -messages scroll by until you hit Ctrl-C to stop the madness.</para> - -</sect2> - -<sect2> -<title>Verifying the operation of the Ethernet Device</title> - -<para>To verify that the Ethernet device is configured correctly, enter:</para> - -<para> -<informalexample> -<screen># ping curly</screen> -</informalexample> -</para> - -<para>You should see: -<informalexample> -<screen># ping curly -PING curly.my.domain. (192.168.1.1): 56 data bytes -64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms -64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms -[...]</screen> -</informalexample> - -messages.</para> - -<para>One important thing to look at in these two examples is that the -names (loopback and curly) correctly correlate to their IP addresses -(127.0.0.1 and 192.168.1.1). This verifies that the -<filename>/etc/hosts</filename> files is correct.</para> - -<para>If the IP address for "curly" isn't 192.168.1.1 or the address for -"localhost" isn't 127.0.0.1, return to <xref linkend="list-lan-hosts"> and review your -entries in '<filename>/etc/hosts</filename>'.</para> - -<para>If the names and addresses are indicated correctly in the result of -the ping command but there are errors displayed then something is -amiss with the interface configuration(s). Return to <xref linkend="system-config"> and -verify everything again.</para> - -<para>If everything here checks out, proceed with the next section.</para> - -</sect2> -</sect1> -</chapter> - -<chapter> -<title>Configuring the PPP Dial-Out Connection</title> - -<para>There are two basic modes of operation of the ppp driver: -"Interactive" and "Automatic".</para> - -<para>In Interactive mode you:</para> - -<para> -<itemizedlist> - -<listitem> -<para>Manually establish a connection to your ISP,</para> -</listitem> - -<listitem> -<para>Browse, surf, transfer files and mail, etc...,</para> -</listitem> - -<listitem> -<para>Manually disconnect from your ISP.</para> -</listitem> - -</itemizedlist> -</para> - -<para>In Automatic mode, the PPP program silently watches what goes on -inside the FreeBSD system and automagically connects and disconnects -with your ISP as required to make the Internet a seamless element of -your network.</para> - -<para>In this section we'll address the configuration(s) for both modes -with emphasis on configuring your `ppp` environment to operate in -"Automatic" mode.</para> - - -<sect1> -<title>Backing up the original PPP configuration files</title> - - <note> - <para>More recent versions of FreeBSD have the examples files in - <filename>/usr/share/examples/ppp</filename>, so this step may not - be necessary.</para> - </note> - -<para>Before making any changes to the files which are used by PPP you -should make a copy of the default files that were created when the -FreeBSD system was installed.</para> - -<para>Log in as the 'root' user and perform the following steps:</para> - -<para>Change to the '<filename>/etc</filename> directory:</para> - -<para><emphasis remap=tt># cd /etc</emphasis></para> - -<para>Make a backup copy the original files in the 'ppp' directory:</para> - -<para><emphasis remap=tt># cp -R ppp ppp.ORIGINAL</emphasis></para> - -<para>You should now be able to see both a '<emphasis remap=tt>ppp</emphasis>' and a -'<filename>ppp.ORIGINAL</filename>' subdirectory -in the '<filename>/etc</filename>' directory.</para> - -</sect1> - -<sect1> -<title>Create your own PPP configuration files</title> - -<para>By default, the FreeBSD installation process creates a number of -sample configuration files in the <filename>/etc/ppp</filename> -and <filename>/usr/share/examples/ppp</filename> directories. Please take -some time to review these files; they were derived from working -systems and represent the features and capabilities of the PPP -program.</para> - -<para>I <emphasis>strongly</emphasis> encourage you to learn from these sample files and -apply them to your own configuration as necessary.</para> - -<para>For detailed information about the `ppp` program, read the ppp -manpage: -<informalexample> -<screen># man ppp</screen> -</informalexample> -</para> - -<para>For detailed information about the `chat` scripting language used by -the PPP dialer, read the chat manpage: -<informalexample> -<screen># man chat</screen> -</informalexample> -</para> - -<para>The remainder of this section describes the recommended contents of -the PPP configuration files.</para> - - -<sect2> -<title>The '<filename>/etc/ppp/ppp.conf</filename>' file</title> - -<para>The '<filename>/etc/ppp/ppp.conf</filename>' file contains the information and -settings required to set up a dial-out PPP connection. More than one -configuration may be contained in this file. The FreeBSD handbook -(XXX URL? XXX) describes the contents and syntax of this file in -detail.</para> - -<para>This section will describe only the minimal configuration to get a -dial-out connection working.</para> - -<para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a -dial-out Internet gateway for our example LAN: -<programlisting> -################################################################ -# PPP Configuration File ('/etc/ppp/ppp.conf') -# -# Default settings; These are always executed always when PPP -# is invoked and apply to all system configurations. -################################################################ -default: - set device /dev/cuaa0 - set speed 57600 - disable pred1 - deny pred1 - disable lqr - deny lqr - set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" - set redial 3 10 -# -# -################################################################ -# -# For interactive mode use this configuration: -# -# Invoke with `ppp -alias interactive` -# -################################################################ -interactive: - set authname Your_User_ID_On_Remote_System - set authkey Your_Password_On_Remote_System - set phone 1-800-123-4567 - set timeout 300 - set openmode active - accept chap -# -################################################################ -# -# For demand-dial (automatic) mode we'll use this configuration: -# -# Invoke with: 'ppp -auto -alias demand' -# -################################################################ -demand: - set authname Your_User_ID_On_Remote_System - set authkey Your_Password_On_Remote_System - set phone 1-800-123-4567 - set timeout 300 - set openmode active - accept chap - set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 - add 0 0 127.2.2.2 -################################################################ -# End of /etc/ppp/ppp.conf -</programlisting> - -This file, taken verbatim from a working system, has three relevant -configuration sections:</para> - - -<sect3> -<title>The "<emphasis remap=tt>default</emphasis>" Section</title> - -<para>The '<emphasis remap=tt>default:</emphasis>' section contains the values and settings -used by every other section in the file. Essentially, this section is -implicitly added to the configuration lines to each other section.</para> - -<para>This is a good place to put "global defaults" applicable to all -dial-up sessions; especially modem settings and dialing prefixes which -typically don't change based on which destination system you're -connecting to.</para> - -<para>Following are the descriptions of each line in the "default" section -of the sample '<filename>/etc/ppp/ppp.conf</filename>' file: -<informalexample> -<screen>set device /dev/cuaa0</screen> -</informalexample> - -This statement informs the PPP program that it should use the first -serial port. -Under FreeBSD the '<filename>/dev/cuaa0</filename>' device is the same port that's -known as "<emphasis remap=tt>COM1:</emphasis>" under DOS, Windows, Windows 95, etc....</para> - -<para>If your modem is on <emphasis remap=tt>COM2:</emphasis> you should specify -'<filename>/dev/cua01</filename>; <emphasis remap=tt>COM3:</emphasis> would be '<filename>/dev/cua02</filename>'.</para> - -<para> -<informalexample> -<screen>set speed 57600 </screen> -</informalexample> -</para> - -<para>This line sets the transmit and receive speed for the connection -between the serial port and the modem. While the modem used for this -configuration is only a 28.8 device, setting this value to 57600 lets -the serial link run at a higher rate to accommodate higher throughput -as a result of the data compression built into late-model modems.</para> - -<para>If you have trouble communicating with your modem, try setting this -value to 38400 or even as low as 19200.</para> - -<para> -<informalexample> -<screen>disable pred1 -deny pred1</screen> -</informalexample> -</para> - -<para>These two lines disable the "CCP/Predictor type 1" compression -features of the PPP program. The current version of `ppp` supports -data compression in accordance with draft Internet standards. -Unfortunately many ISPs use equipment that does not support this -capability. Since most modems try to perform on-the-fly compression -anyway you're probably not losing much performance by disabling this -feature on the FreeBSD side and denying the remote side from forcing -it on you.</para> - -<para> -<informalexample> -<screen>disable lqr -deny lqr</screen> -</informalexample> -</para> - -<para>These two lines control the "Line Quality Reporting" functions which -are part of the complete Point-to-Point (PPP) protocol specification. -(See RFC-1989 for details.)</para> - -<para>The first line, "disable lqr", instructs the PPP program to not -attempt to report line quality status to the device on the remote end.</para> - -<para>The second line, "deny lqr", instructs the PPP program to deny any -attempts by the remote end to reports line quality.</para> - -<para>As most modern dial-up modems have automatic error correction and -detection and LQR reporting is not fully implemented in many vendor's -products it's generally a safe bet to include these two lines in the -default configuration.</para> - -<para> -<informalexample> -<screen>set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 -OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT"</screen> -</informalexample> -</para> - -<para><emphasis>NOTE: (This statement should appear on a single line; ignore any -line wrapping that may appear in this document.)</emphasis></para> - -<para>This line instructs the PPP program how to dial the modem and -specifies some rudimentary guidelines for doing so: -<itemizedlist> - -<listitem> -<para>Attempts to dial should fail if the modem returns a "BUSY" result code,</para> -</listitem> - -<listitem> -<para>Attempts to dial should also fail if the modem returns a "NO CARRIER" result code,</para> -</listitem> - -<listitem> -<para>The PPP program should expect each of the following events to complete within a -5-second timeout period: -<itemizedlist> - -<listitem> -<para>The PPP program will initially expect nothing (specified above -by the \"\" portion of the statement) from the modem </para> -</listitem> - -<listitem> -<para>The program -will send the modem initialization string "ATE1Q0M0" to the modem and -await a response of "OK". If a response is not received, the program -should send an attention command to the modem ("AT") and look again -for a response of "OK", </para> -</listitem> - -<listitem> -<para>The program should delay for one second -(specified by the "\\d" part of the statement, and send the dialing -string to the modem. The "ATDT" portion of the statement is the -standard modem prefix to dial using tone-dialing; if you do not have -touch-tone service on your local phone line, replace the "ATDT" with -"ATDP". The "\\T" string is a placeholder for the actual phone number -(which will be automatically inserted as specified by the "set dial -123-4567").</para> -</listitem> - -</itemizedlist> -</para> -</listitem> - -<listitem> -<para>Finally, before a (maximum) timeout of 40 seconds, the PPP -program should expect to see a "CONNECT" result code returned from the -modem.</para> -</listitem> - -</itemizedlist> -</para> - -<para>A failure at any point in this dialog will be interpreted as a dialing -failure and the PPP program will fail to connect.</para> - -<para>(For a detailed description of the mini-scripting language used by the -PPP dialer, refer to the "chat" manpage.)</para> - -<para> -<informalexample> -<screen>set redial 3 10</screen> -</informalexample> - -This line specifies that if a dial connection cannot immediately be made -the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds -between redialing attempts.</para> - -</sect3> - -<sect3> -<title>The "<emphasis remap=tt>interactive</emphasis>" Section</title> - -<para>The '<emphasis remap=tt>interactive:</emphasis>' section contains the values and -settings used to set up an "interactive" PPP session with a specific -remote system. Settings in this section will have the lines included -in the "default" section included automatically.</para> - -<para>The example cited in this section of the guide presumes that you'll -be connecting to a remote system that understands how to authenticate -a user without any fancy scripting language. That is, this sample -uses the CHAP protocol to set up the connection.</para> - -<para>A good rule of thumb is that if the Windows '95 dialer can set up a -connection by just clicking the "Connect" button this sample -configuration should work OK.</para> - -<para>If, on the other hand, when you connect to your ISP using Microsoft -Windows '95 Dial-Up Networking you need to resort to using the "Dial -Up Scripting Tool" from the Microsoft Plus! pack or you have to select -"Bring up a terminal windows after dialing" in the Windows '95 -connection options then you'll need to look at the sample PPP -configuration files and the ppp manpage for examples of "expect / -response" scripting to make your ISP connection. The "set login" -command is used for this purpose.</para> - -<para>Or even better, find an ISP who knows how to provide PAP or CHAP -authentication!</para> - -<para>The configuration examples shown here have been successfully used to -connect to: -<itemizedlist> - -<listitem> -<para>Various Shiva LanRovers</para> -</listitem> - -<listitem> -<para>The IBM Network (<ulink URL="http://www.ibm.net">http://www.ibm.net</ulink>)</para> -</listitem> - -<listitem> -<para>AT&T WorldNet (<ulink URL="http://att.com/worldnet">http://att.com/worldnet</ulink>)</para> -</listitem> - -<listitem> -<para>Erol's (<ulink URL="http://www.erols.com">http://www.erols.com</ulink>)</para> -</listitem> - -</itemizedlist> -</para> - -<para>Following are descriptions for each line in the "interactive" section -of the sample '<filename>/etc/ppp/ppp.conf</filename>' file:</para> - -<para> -<informalexample> -<screen>set authname Your_User_ID_On_Remote_System</screen> -</informalexample> - -This line specifies the name you would use to log in to the remote -system. </para> - -<para> -<informalexample> -<screen>set authkey Your_Password_On_Remote_System</screen> -</informalexample> - -This is the password you'd use to log in to the remote system.</para> - -<para> -<informalexample> -<screen>set phone 1-800-123-4567</screen> -</informalexample> - -This is the phone number of the remote system. If you're inside a PBX -you can -prepend '<emphasis remap=tt>9, </emphasis>' to the number here.</para> - -<para> -<informalexample> -<screen>set timeout 300</screen> -</informalexample> - -This tells the PPP program that it should automatically hang up the -phone if no data has -be exchanged for 300 seconds (5 minutes). You may wish to tailor this -number to your -specific requirements.</para> - -<para> -<informalexample> -<screen>set openmode active</screen> -</informalexample> - -This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection.</para> - - - -<screen>accept chap</screen> - - -<para>This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above.</para> - -</sect3> - -<sect3> -<title>The "<emphasis remap=tt>demand</emphasis>" Section</title> - -<para>The "<emphasis remap=tt>demand</emphasis>" section contains the values and settings used -to set up a "Dial-on-demand" PPP session with a specific remote -system. Settings in this section will also have the lines included in -the "default" section included automatically.</para> - -<para>Except for the last two lines in this section it is identical to -the configuration section which defines the "interactive" -configuration.</para> - -<para>As noted earlier, the examples cited in this section of -the guide presume that you'll be connecting to a remote system that -understands how to use the CHAP protocol to set up the connection.</para> - -<para>Following are descriptions for each line in the "demand" section of -the sample '<filename>/etc/ppp/ppp.conf</filename>' file:</para> - -<para> -<informalexample> -<screen>set authname Your_User_ID_On_Remote_System</screen> -</informalexample> - -This line specifies the name you would use to log in to the remote -system. </para> - -<para> -<informalexample> -<screen>set authkey Your_Password_On_Remote_System</screen> -</informalexample> - -This is the password you'd use to log in to the remote system.</para> - -<para> -<informalexample> -<screen>set phone 1-800-123-4567</screen> -</informalexample> - -This is the phone number of the remote system.</para> - -<para> -<informalexample> -<screen>set timeout 300</screen> -</informalexample> -</para> - -<para>This tells the PPP program that it should automatically hang up the -phone if no data has be exchanged for 300 seconds (5 minutes). You -may wish to tailor this number to your specific requirements.</para> - -<para> -<informalexample> -<screen>set openmode active</screen> -</informalexample> -</para> - -<para>This tells the PPP program that once the modems are connected it -should immediately attempt to negotiate the connection. Some remote -sites do this automatically, some don't. This instructs your side of -the link to take the initiative and try to set up the connection.</para> - -<para> -<informalexample> -<screen>accept chap</screen> -</informalexample> -</para> - -<para>This tells the PPP program to use the "Challenge-Handshake -Authentication Protocol" to authenticate you. The values exchanged -between the local and remote side for UserID and password are taken -from the 'authname' and 'authkey' entries above.</para> - -<para> -<informalexample> -<screen>set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0</screen> -</informalexample> -</para> - -<para>This command sets up a pair of "fake" IP addresses for the local and -remote sides of the PPP link. It instructs the PPP program to create -an IP address of 127.1.1.1 for the local side of the '<emphasis remap=tt>tun0</emphasis>' -(tunnel) device -and 127.2.2.2 for the remote side. Appending '<filename>/0</filename>' to -each address tells the PPP program that zero of the bits that make up -these addresses are significant and can (in fact, must!) be negotiated -between the local and remote systems when the link is established. -The 255.255.255.0 string tells the PPP program what Subnet mask to -apply to these pseudo-interfaces.</para> - -<para>Remember, we've assumed that your ISP provides the IP addresses for -both ends of the link! If your ISP assigned you a specific IP address -that you should use on your side when configuring your system, enter -that IP address here <emphasis>instead</emphasis> of <emphasis remap=tt>127.1.1.1</emphasis>.</para> - -<para>Conversly, if your ISP gave you a specific IP address that he uses on -his end you should enter that IP address here <emphasis>instead</emphasis> of -<emphasis remap=tt>127.2.2.2</emphasis>.</para> - -<para>In both cases, it's probably a good idea to leave the '<filename>/0</filename>' on -the end of each address. This gives the PPP program the opportunity -to change the address(es) of the link if it <emphasis>has</emphasis> to.</para> - -<para> -<informalexample> -<screen>add 0 0 127.2.2.2</screen> -</informalexample> -</para> - -<para>This last line tells the PPP program that it should add a default -route for IP traffic that points to the (fake) IP address of the ISP's -system.</para> - -<para><emphasis><emphasis remap=bf>Note: If you used an ISP-specified address instead of -<emphasis remap=tt>127.2.2.2</emphasis> on the preceeding line, use the same number here -instead of <emphasis remap=tt>127.2.2.2</emphasis></emphasis></emphasis>.</para> - -<para>By adding this "fake" route for IP traffic, the PPP program can, -while idle: -<itemizedlist> - -<listitem> -<para>Accept packets that FreeBSD doesn't already know how to forward,</para> -</listitem> - -<listitem> -<para>Establish a connection to the ISP "<emphasis>on-the-fly</emphasis>",</para> -</listitem> - -<listitem> -<para>Reconfigure the IP addresses of the local and remote side of the link,</para> -</listitem> - -<listitem> -<para>Forward packets between your workstation and the ISP.</para> -</listitem> - -</itemizedlist> - -automatically!</para> - -<para>Once the number of seconds specified by the timeout value in the -"default" section have elapsed without any TCP/IP traffic the PPP -program will automatically close the dial-up connection and the -process will begin again.</para> - -</sect3> -</sect2> - -<sect2> -<title>The '<filename>/etc/ppp/ppp.linkup</filename>' file</title> - -<para>The other file needed to complete the PPP configuration is found in -'<filename>/etc/ppp/ppp.linkup</filename>'. This file contains instructions for -the PPP program on what actions to take after a dial-up link is -established.</para> - -<para>In the case of dial-on-demand configurations the PPP program will need -to delete the default route that was created to the fake IP address of -the remote side (127.2.2.2 in our example in the previous section) and -install a new default route that points the actual IP address of the -remote end (discovered during the dial-up connection setup).</para> - -<para>A representative '<filename>/etc/ppp/ppp.linkup</filename>' file: -<informalexample> -<screen>#########################################################################= - -# PPP Link Up File ('/etc/ppp/ppp.linkup') -# -# This file is checked after PPP establishes a network connection. -# -# This file is searched in the following order. -# -# 1) First, the IP address assigned to us is searched and -# the associated command(s) are executed. -# -# 2) If the IP Address is not found, then the label name specified at - -# PPP startup time is searched and the associated command(s) -# are executed. -# -# 3) If neither of the above are found then commands under the label -# 'MYADDR:' are executed. -# -#########################################################################= - -# -# This section is used for the "demand" configuration in -# /etc/ppp/ppp.conf: -demand: - delete ALL - add 0 0 HISADDR -# -# All other configurations in /etc/ppp/ppp.conf use this: -# -MYADDR: - add 0 0 HISADDR -######################################################################## -# End of /etc/ppp/ppp.linkup</screen> -</informalexample> - -Notice that there is a section in this file named "demand:", identical -to the configuration name used in the '<filename>/etc/ppp/ppp.conf</filename>' -file. This section instructs the PPP program that once a link is -established using this configuration, it must: -<orderedlist> - -<listitem> -<para>Remove any IP routing information that the PPP program has created</para> -</listitem> - -<listitem> -<para>Add a default route the remote end's actual address.</para> -</listitem> - -</orderedlist> -</para> - -<para>It's critical that those configurations in -'<filename>/etc/ppp/ppp.conf</filename>' which include the '<emphasis remap=tt>set ifaddr</emphasis>' and -'<emphasis remap=tt>add 0 0</emphasis>' statements (i.e.: those configurations used for -Dial-on-Demand configurations) execute the "delete ALL" and "add 0 0 -HISADDR" commands in <filename>/etc/ppp/ppp.linkup</filename>.</para> - -<para><emphasis><emphasis remap=bf>This is the mechanism that controls the actual on-demand -configuration of the link.</emphasis></emphasis></para> - -<para>All configurations not explicitly named in -<filename>/etc/ppp/ppp.linkup</filename> will use whatever commands are in the -"MYADDR:" section of the file. This is where non-Demand-Dial -configurations (such as our "interactive:" sample) will fall through -to. This section simply adds a default route to the ISP's IP address -(at the remote end).</para> - -</sect2> -</sect1> - -<sect1> -<title>IP Aliasing</title> - -<para>All of the configuration steps described thus far are relevant to -any FreeBSD system which will be used to connect to an ISP via dial-up -connection.</para> - -<para>If your sole objective in reading this guide is to connect your -FreeBSD box to the Internet using dial-out ppp you can proceed to -<xref linkend="testing-the-network">.</para> - -<para>One very attractive feature of the PPP program in on-demand mode is -its ability to route IP traffic between other systems on the Local -Area Network automatically. This feature is known by various names, -"<emphasis>IP Aliasing</emphasis>", "<emphasis>Network Address Translation</emphasis>", "<emphasis>Address -Masquerading</emphasis>" or "<emphasis>Transparent Proxying</emphasis>".</para> - -<para>Regardless of the terminology used, this mode is not, however, -automatic. If the PPP program is started normally then the program -will not forward packets between LAN interface(s) and the dial-out -connection. In effect, only the FreeBSD system is connected to the -ISP; other workstations cannot "share" the same connection.</para> - -<para>For example, if the program is started with either of the following -command lines:</para> - -<para><emphasis remap=tt># ppp interactive (Interactive mode)</emphasis></para> - -<para> or</para> - -<para><emphasis remap=tt># ppp -auto demand (Dial-on-Demand mode)</emphasis></para> - -<para>then the system will function as an Internet-connected workstation -<emphasis>only</emphasis> for the -FreeBSD box.</para> - -<para>To start the PPP program as a gateway between LAN resources and the -Internet, one of the following command lines would be used instead:</para> - -<para><emphasis remap=tt># ppp -alias interactive (Interactive mode)</emphasis></para> - -<para> or</para> - -<para><emphasis remap=tt># ppp -auto -alias demand (Dial-on-Demand mode)</emphasis></para> - -<para>You can alternatively use the command <emphasis remap=tt>``alias enable yes''</emphasis> -in your ppp configuration file (refer to the man page for details).</para> - -<para>Keep this in mind if you intend to proceed with <xref - linkend="config-window-system">.</para> - -</sect1> -</chapter> - -<chapter id="config-window-system"> -<title>Configuring Windows Systems</title> - -<para>As indicated in Section 1, our example network consists of a -FreeBSD system ("Curly") which acts as a gateway (or router) between a -Local Area Network consisting of two different flavors of Windows -Workstations. In order for the LAN nodes to use Curly as a router -they need to be properly configured. Note that this section does not -explain how to configure the Windows workstations for Dial-Up -networking. If you need a good explanation of that procedure, I -recommend <ulink URL="http://www.aladdin.co.uk/techweb">http://www.aladdin.co.uk/techweb</ulink>.</para> - - -<sect1> -<title> Configuring Windows 95</title> - -<para>Configuring Windows 95 to act as an attached resource on your LAN -is relatively simple. The Windows 95 network configuration must be -slightly modified to use the FreeBSD system as the default gateway to -the ISP. Perform the following steps:</para> - -<para><emphasis remap=bf>Create the Windows 95 "hosts" file:</emphasis></para> - -<para>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in <xref linkend="list-lan-hosts">. -<itemizedlist> - -<listitem> -<para>Click the "Start" button; select "Run..."; enter "notepad -\WINDOWS\HOSTS" (without the quotes) and click "OK"</para> -</listitem> - -<listitem> -<para>In the editor, enter the addresses and system names from the hosts -file shown in <xref linkend="list-lan-hosts">.</para> -</listitem> - -<listitem> -<para>When finished editing, close the notepad application (making sure -that you save the file!).</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Windows 95 TCP/IP Network Configuation -settings</emphasis>: -<itemizedlist> - -<listitem> -<para>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". </para> -</listitem> - -<listitem> -<para>Double-click the "Network" icon to open it.</para> - -<para> -The settings for all Network Elements are displayed.</para> -</listitem> - -<listitem> -<para>With the "Configuration" tab selected, scroll down the list of -installed components and highlight the "TCP/IP-><emphasis>YourInterfaceType</emphasis>" line -(where "<emphasis>YourInterfaceType</emphasis>" is the name or type of Ethernet adapter in your system). -</para> - -<para>If TCP/IP is not listed in the list of installed network -components, click the "Add" button and install it before proceeding.</para> - -<para>(Hint: "Add | Protocol | Microsoft | TCP/IP | OK")</para> -</listitem> - -<listitem> -<para>Click on the "Properties" button to display a list of the -settings associated with the TCP component.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the IP Address Information:</emphasis> -<itemizedlist> - -<listitem> -<para>Click the "IP Address" tab</para> -</listitem> - -<listitem> -<para>Click the "Specify an IP address" radio button. -</para> - -<para>(In our example LAN the Windows 95 system is the one we've called "Larry".)</para> -</listitem> - -<listitem> -<para>In the "IP Address" field enter "192.168.1.2".</para> -</listitem> - -<listitem> -<para>Enter 255.255.255.0 in the "Subnet Mask" field.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Gateway information:</emphasis> -<itemizedlist> - -<listitem> -<para>Click on the "Gateway" tab -</para> - -<para>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection. Enter the IP address of the FreeBSD -Ethernet interface, 192.168.1.1, in the "New gateway" field and click -the "Add" button. If any other gateways are defined in the "Installed -gateways" list you may wish to consider removing them.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the DNS Information:</emphasis></para> - -<para>This guide assumes that your Internet Service Provider has given -you a list of Domain Name Servers (or "DNS Servers") that you should -use. If you wish to run a DNS server on your local FreeBSD system, -refer to Section 6, "Exercise for the Interested Student" for tips on -setting up DNS on your FreeBSD system.</para> - -<para> -<itemizedlist> - -<listitem> -<para>Click the "DNS Configuration" tab</para> -</listitem> - -<listitem> -<para>Make sure that the "Enable DNS" radio button is selected. -</para> - -<para>(If this button is not selected only the entries that -we put in the host file(s) will be available and your Net-Surfing -will not work as you expect!)</para> -</listitem> - -<listitem> -<para>In the "Host" field enter the name of the Windows 95 box, in this -case: "Larry".</para> -</listitem> - -<listitem> -<para>In the "Domain" field enter the name of our local network, in this -case: "my.domain"</para> -</listitem> - -<listitem> -<para>In the "DNS Server Search Order" section, enter the IP address -of the DNS server(s) that your ISP provided, clicking the "Add" button -after every address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Other Windows 95 TCP/IP options:</emphasis></para> - -<para>For our purposes the settings under the "Advanced", "WINS -Configuration" and "Bindings" tabs are not necessary.</para> - -<para>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <ulink URL="http://www.localnet.org">http://www.localnet.org</ulink> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet.</para> - -<para><emphasis remap=bf>Mopping up:</emphasis> -<itemizedlist> - -<listitem> -<para>Click on the "OK" button to close the TCP/IP Properties window.</para> -</listitem> - -<listitem> -<para>Click on the "OK" button to close the Network Control Panel. </para> -</listitem> - -<listitem> -<para>Reboot your computer if prompted to do so. </para> -</listitem> - -</itemizedlist> -</para> - -<para> That's it!</para> - -</sect1> - -<sect1> -<title>Configuring Windows NT</title> - -<para>Configuring Windows NT to act as a LAN resource is also relatively -straightforward. The procedures for configuring Windows NT are -similar to Windows 95 with minor exceptions in the user interface.</para> - -<para>The steps shown here are appropriate for a Windows NT 4.0 -Workstation, but the principles are the same for NT 3.5x. You may -wish to refer to the "Configuring Windows for Workgroups" section if -you're configuring Windows NT 3.5<emphasis remap=it>x</emphasis>, since the user interface is -the same for NT 3.5 and WfW.</para> - -<para>Perform the following steps: </para> - -<para><emphasis remap=bf>Create the Windows NT "hosts" file:</emphasis></para> - -<para>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4 -<itemizedlist> - -<listitem> -<para>Click the "Start" button; select "Run..."; enter "notepad -\WINNT\SYSTEM32\DRIVERS\ETC\HOSTS" (without the quotes) and click -"OK"</para> -</listitem> - -<listitem> -<para>In the editor, enter the addresses and system names from Section -3.4.</para> -</listitem> - -<listitem> -<para>When finished editing, close the notepad application (making sure -that you save the file!).</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Windows NT TCP/IP Network Configuation -settings</emphasis>: -<itemizedlist> - -<listitem> -<para>Click the "Start" button on the taskbar; select "Settings" and -"Control Panel". </para> -</listitem> - -<listitem> -<para>Double-click the "Network" icon to open it. </para> -</listitem> - -<listitem> -<para>With the "Identification" tab selected, verify the "Computer Name" -and "Workgroup" fields. In this example we'll use "Shemp" for the name -and "Stooges" for the workgroup. Click the "Change" button and amend -these entries as necessary.</para> -</listitem> - -<listitem> -<para>Select the "Protocols" tab. - -</para> - -<para>The installed Network Protocols will be displayed. There may be a -number of protocols listed but the one of interest to this guide is -the "TCP/IP Protocol". If "TCP/IP Protocol" is not listed, click the -"Add" button to load it.</para> - -<para>(Hint: "Add | TCP/IP Protocol | OK") </para> -</listitem> - -<listitem> -<para>Highlight "TCP/IP -Protocol" and click the "Properties" button. -</para> - -<para>Tabs for specifying various settings for TCP/IP will be displayed.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configuring the IP Address:</emphasis></para> - -<para>Make sure that the Ethernet Interface is shown in the "Adapter" -box; if not, scroll through the list of adapters until the correct -interface is shown. -<itemizedlist> - -<listitem> -<para>Click the "Specify an IP address" radio button to enable the three -text boxes. -</para> - -<para>In our example LAN the Windows NT system is the one we've called -"Shemp"</para> -</listitem> - -<listitem> -<para>In the "IP Address" field enter "192.168.1.4".</para> -</listitem> - -<listitem> -<para>Enter 255.255.255.0 in the "Subnet Mask" field.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Gateway information:</emphasis></para> - -<para>For our example network the FreeBSD box will be acting as our gateway -to the Internet (routing packets between the Ethernet LAN and the PPP dial-up -connection. -<itemizedlist> - -<listitem> -<para>Enter the IP address of the FreeBSD Ethernet interface, -192.168.1.1, in the "New gateway" field and click the "Add" button. -</para> - -<para>If any other gateways are defined in the "Installed gateways" list -you may wish to consider removing them.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configuring DNS:</emphasis></para> - -<para>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use.</para> - -<para>If you wish to run a DNS server on your local FreeBSD system, refer to -Section 6, "Exercise for the Interested Student" for tips on setting -up DNS on your FreeBSD system. -<itemizedlist> - -<listitem> -<para>Click the "DNS" tab</para> -</listitem> - -<listitem> -<para>In the "Host Name" field enter the name of the Windows NT box, in -this case: "Shemp".</para> -</listitem> - -<listitem> -<para>In the "Domain" field enter the name of our local network, in this -case: "my.domain"</para> -</listitem> - -<listitem> -<para>In the "DNS Server Search Order" section, enter the IP address of -the DNS server that your ISP provided, clicking the "Add" button after -every address is entered. Repeat this step as many times as necessary -to add all of the addresses that your ISP provided.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Other Windows NT TCP/IP options:</emphasis></para> - -<para>For our purposes the settings under the "WINS Address" and -"Routing" tabs are not used.</para> - -<para>If you wish to use the Windows Internet Naming Service ("WINS") -your attention is invited to <ulink URL="http://www.localnet.org">http://www.localnet.org</ulink> for -more information about WINS settings, specifically regarding sharing -files transparently across the Internet.</para> - -<para><emphasis remap=bf>Mopping up:</emphasis> -<itemizedlist> - -<listitem> -<para>Click on the "OK" button to close the TCP/IP Properties section. -</para> -</listitem> - -<listitem> -<para>Click on the "Close" button to close the Network Control Panel. -</para> -</listitem> - -<listitem> -<para>Restart your computer if prompted to do so.</para> -</listitem> - -</itemizedlist> -</para> - -<para>That's it!</para> - -</sect1> - -<sect1> -<title>Configuring Windows for Workgroups</title> - -<para>Configuring Windows for Workgroups to act as a network client -requires that the Microsoft TCP/IP-32 driver diskette has been -installed on the workstation. The TCP/IP drivers are not included -with the WfW CD or diskettes; if you need a copy they're available at -<ulink URL="ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip">ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip</ulink>.</para> - -<para>Once the TCP/IP drivers have been loaded, perform the following -steps:</para> - -<para><emphasis remap=bf>Create the Windows for Workgroups "hosts" file:</emphasis></para> - -<para>In order to connect to the other TCP/IP systems on the LAN you'll -need to create an identical copy of the "hosts" file that you -installed on the FreeBSD system in Section 3.4. -<itemizedlist> - -<listitem> -<para>In Program Manager, click the "File" button; select "Run"; and -enter: "notepad \WINDOWS\HOSTS" (without the quotes) and click "OK"</para> -</listitem> - -<listitem> -<para>In the editor, enter the addresses and system names from the hosts -file shown in Section 3.4.</para> -</listitem> - -<listitem> -<para>When finished editing, close the notepad application (making sure -that you save the file!).</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Windows 95 TCP/IP Network Configuation -settings</emphasis> -<itemizedlist> - -<listitem> -<para>In the main window of Program Manager, open the "Network" group by -double-clicking the icon. </para> -</listitem> - -<listitem> -<para>Double click on the "Network Setup" icon. </para> -</listitem> - -<listitem> -<para>In the "Network Drivers Box" double-click the "Microsoft -TCP/IP-32" entry. </para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Windows for Workgroups IP Address:</emphasis> </para> - -<para>Ensure -the correct Ethernet Interface is selected in the "Adapter" list. If -not, scroll down until it is displayed and select it by clicking on -it. -<itemizedlist> - -<listitem> -<para>Ensure that the "Enable Automatic DHCP Configuration" check box is -blank. If it is checked, click it to remove the "X".</para> -</listitem> - -<listitem> -<para>In our example LAN the Windows for Workgroups system is the one -we've called "Moe"; in the "IP Address" field enter "192.168.1.3".</para> -</listitem> - -<listitem> -<para>Enter 255.255.255.0 in the "Subnet Mask" field.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configure the Gateway information:</emphasis></para> - -<para>For our example network the FreeBSD box will be acting as our -gateway to the Internet (routing packets between the Ethernet LAN and -the PPP dial-up connection). -<itemizedlist> - -<listitem> -<para>Enter the IP address of the FreeBSD system, 192.168.1.1, in the -"Default Gateway" field.</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Configuring DNS:</emphasis></para> - -<para>Again, this guide assumes that your Internet Service Provider has -given you a list of Domain Name Servers (or "DNS Servers") that you -should use. If you wish to run a DNS server on your local FreeBSD -system, refer to Section 6, "Exercise for the Interested Student" for -tips on setting up DNS on your FreeBSD system. -<itemizedlist> - -<listitem> -<para>Click the "DNS" button.</para> -</listitem> - -<listitem> -<para>In the "Host Name" field enter the name of the Windows for -Workgroups box, in this case: "Moe".</para> -</listitem> - -<listitem> -<para>In the "Domain" field enter the name of our local network, in this -case: "my.domain"</para> -</listitem> - -<listitem> -<para>In the "Domain Name Service (DNS) Search Order" section, enter the -IP address of the DNS server that your ISP provided, clicking the "Add" -button after each address is entered. Repeat this step as many times as -necessary to add all of the addresses that your ISP provided.</para> -</listitem> - -<listitem> -<para>Click on the "OK" button to close the DNS Configuration window. -</para> -</listitem> - -</itemizedlist> -</para> - -<para><emphasis remap=bf>Mopping up:</emphasis> -<itemizedlist> - -<listitem> -<para>Click on the "OK" button to close the TCP/IP Configuration window. -</para> -</listitem> - -<listitem> -<para>Click on the "OK" button to close the Network Setup window.</para> -</listitem> - -<listitem> -<para>Reboot your computer if prompted. </para> -</listitem> - -</itemizedlist> -</para> - -<para>That's it!</para> - -</sect1> -</chapter> - -<chapter id="testing-the-network"> -<title>Testing the Network</title> - -<para> Once you've completed that appropriate tasks above you should have -a functioning PPP gateway to the Internet.</para> - - -<sect1> -<title>Testing the Dial-Up link:</title> - -<para> The first thing to test is that the connection is being made -between your modem and the ISP.</para> - -</sect1> - -<sect1> -<title>Testing the Ethernet LAN</title> - -<para> *** TBD ***</para> - -</sect1> -</chapter> - -<chapter> -<title>Exercises for the Interested Student</title> - - -<sect1> -<title>Creating a mini-DNS system</title> - -<para>While managing a Domain Name Service (DNS) hierarchy can be a black -art, it is possible to set up a Mini-DNS server on the FreeBSD system -that also acts as your gateway to your ISP.</para> - -<para>Building on the files in <filename>/etc/namedb</filename> when the FreeBSD -system was installed it's possible to create a name server that is -both authoritative for the example network shown here as well as a -front-door to the Internet DNS architecture.</para> - -<para>In this minimal DNS configuration, only three files are necessary: -<informalexample> -<screen>/etc/namedb/named.boot -/etc/namedb/named.root -/etc/namedb/mydomain.db</screen> -</informalexample> -</para> - -<para>The <filename>/etc/namedb/named.root</filename> file is automatically installed -as part of the FreeBSD base installation; the other two files must be -created manually.</para> - - -<sect2> -<title>The <filename>/etc/namedb/named.boot</filename> file</title> - -<para>The <filename>/etc/namedb/named.boot</filename> file controls the startup -settings of the DNS server. -Esentially, it tells the Name Server: -<orderedlist> - -<listitem> -<para>Where to find configuration files,</para> -</listitem> - -<listitem> -<para>What "domain names" it's responsible for, and</para> -</listitem> - -<listitem> -<para>Where to find other DNS servers.</para> -</listitem> - -</orderedlist> -</para> - -<para>Using the '<emphasis remap=tt>ee</emphasis>' editor, create a -<filename>/etc/namedb/named.boot</filename> with the following contents: -<informalexample> -<screen>; boot file for mini-name server - -directory /etc/namedb - -; type domain source host/file backup file - -cache . named.root -primary my.domain. mydomain.db</screen> -</informalexample> -</para> - -<para>Lines that begin with a semi-colon are comments. The significant -lines in this file are: -<itemizedlist> - -<listitem> -<para><command>directory /etc/namedb</command> -</para> - -<para>Tells the Name Server where to find the configuration files -referenced in the remaining sections of the -'<filename>/etc/namedb/named.boot</filename>' file.</para> -</listitem> - -<listitem> -<para><emphasis remap=tt>cache . named.root</emphasis> -</para> - -<para>Tells the Name Server that the list of "Top-Level" DNS servers for -the Internet can be found in a file called '<filename>named.root</filename>'. -(This file is included in the base installation and its -contents are not described in this document.)</para> -</listitem> - -<listitem> -<para><emphasis remap=tt>primary my.domain. mydomain.db</emphasis> -</para> - -<para>Tells the Name Server that it will be "authoritative" for a DNS -domain called "my.domain" and that a list of names and IP addresses -for the systems in "my.domain" (the local network) -can be found in a file named '<filename>mydomain.db</filename>'.</para> -</listitem> - -</itemizedlist> -</para> - -<para>Once the <filename>/etc/namedb/named.boot</filename> file has been created and -saved, proceed to the next section to create the -<filename>/etc/namedb/mydomain.db</filename> file.</para> - -</sect2> - -<sect2> -<title>The <filename>/etc/namedb/mydomain.db</filename> file</title> - -<para>The <filename>/etc/namedb/mydomain.db</filename> file lists the names and IP -addresses of <emphasis>every</emphasis> system in the Local Area Network.</para> - -<para><emphasis>For a detailed description of the statements used in this file, -refer to the <emphasis remap=tt>named</emphasis> manpage.</emphasis></para> - -<para>The <filename>/etc/namedb/mydomain.db</filename> file for our minimal DNS -server has the following contents: -<informalexample> -<screen>@ IN SOA my.domain. root.my.domain. ( - 961230 ; Serial - 3600 ; Refresh - 300 ; Retry - 3600000 ; Expire - 3600 ) ; Minimum - IN NS curly.my.domain. - -curly.my.domain. IN A 192.168.1.1 # The FreeBSD box -larry.my.domain. IN A 192.168.1.2 # The Win'95 box -moe.my.domain. IN A 192.168.1.3 # The WfW box -shemp.my.domain. IN A 192.168.1.4 # The Windows NT box - -$ORIGIN 1.168.192.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR curly.my.domain. -2 IN PTR larry.my.domain. -3 IN PTR moe.my.domain. -4 IN PTR shemp.my.domain. - -$ORIGIN 0.0.127.IN-ADDR.ARPA - IN NS curly.my.domain. -1 IN PTR localhost.my.domain.</screen> -</informalexample> -</para> - -<para>In simple terms, this file declares that the local DNS server is: -<itemizedlist> - -<listitem> -<para>The Start of Authority for ("SOA") for a domain called -'my.domain',</para> -</listitem> - -<listitem> -<para>The Name Server ("NS") for 'my.domain',</para> -</listitem> - -<listitem> -<para>Responsible for the reverse-mapping for all IP addresses that -start with '192.168.1.' and -'127.0.0.' ("$ORIGIN ...")</para> -</listitem> - -</itemizedlist> -</para> - -<para>To add workstation entries to this file you'll need to add two -lines for each system; one in the top section where the name(s) are -mapped into Internet Addresses ("IN A"), and another line that maps -the addresses back into names in the <filename>$ORIGIN -1.168.192.IN-ADDR.ARPA</filename> section.</para> - -</sect2> - -<sect2> -<title>Starting the DNS Server</title> - -<para>By default the DNS server ('<filename>/usr/sbin/named</filename>') is not -started when the system boots. You can modify this behavior by -changing a single line in '<filename>/etc/rc.conf</filename>' as follows:</para> - -<para> Using the '<emphasis remap=tt>ee</emphasis>' editor, load <filename>/etc/rc.conf</filename>. Scroll -down approximately 40 lines until you come to the section that says: -<informalexample> -<screen>--- -named_enable="NO" # Run named, the DNS server (or NO). -named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). ----</screen> -</informalexample> - -Change this section to read: -<informalexample> -<screen>--- -named_enable="YES" # Run named, the DNS server (or NO). -named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). ----</screen> -</informalexample> - -Save the file and reboot.</para> - -<para>Alternatively, start the Name Server daemon by entering the following -command: -<informalexample> -<screen># named -b /etc/namedb/named.boot</screen> -</informalexample> -</para> - -<para>Whenever you modify any of the files in <filename>/etc/namedb</filename> you'll -need to kick-start the Name Server process to make it pick up the -modifications. This is performed with the following system command: -<informalexample> -<screen># kill -HUP `cat /var/run/named.pid`</screen> -</informalexample> -</para> - -</sect2> -</sect1> - -<sect1> -<title>Playing with PPP filters</title> - -<para>The PPP program has the ability to apply selected filtering rules -to the traffic it routes. While this is not nearly as secure as a -formal firewall it does provide some access control as to how the link -is used.</para> - -<para>('<emphasis remap=tt>man ipfw</emphasis>' for information on setting up a more secure -FreeBSD system.)</para> - -<para>The complete documentation for the various filters and rules under -PPP are availabe in the PPP manpage.</para> - -<para>There are four distinct classes of rules which may be applied to -the PPP program: -<itemizedlist> - -<listitem> -<para><emphasis>alive</emphasis> filter - Access Counter (or "Keep Alive") filters -</para> - -<para>These control which events are ignored by the <literal>set timeout=</literal> -statement in the configuration file.</para> -</listitem> - -<listitem> -<para><emphasis>dial</emphasis> filter - Dialing filters -</para> - -<para>These filtering rules control which events are ignored by the -demand-dial mode of PPP.</para> -</listitem> - -<listitem> -<para><emphasis>in</emphasis> filter - Input filters -</para> - -<para>Control whether incoming packets should be discarded or passed into -the system.</para> -</listitem> - -<listitem> -<para><emphasis>out</emphasis> filter - Output filters -</para> - -<para>Control whether outgoing packets should be discarded or passed into -the system.</para> -</listitem> - -</itemizedlist> -</para> - -<para>What follows is a snippet from an operating system which provides a -good foundation for "normal" Internet operations while preventing PPP -from pumping <emphasis>all</emphasis> data over the dial-up connection. Comments -briefly describe the logic of each rule set: -<informalexample> -<screen># -# KeepAlive filters -# Don't keep Alive with ICMP,DNS and RIP packet -# - set filter alive 0 deny icmp - set filter alive 1 deny udp src eq 53 - set filter alive 2 deny udp dst eq 53 - set filter alive 3 deny udp src eq 520 - set filter alive 4 deny udp dst eq 520 - set filter alive 5 permit 0/0 0/0 -# -# Dial Filters: -# Note: ICMP will trigger a dial-out in this configuration! -# - set filter dial 0 permit 0/0 0/0 -# -# Allow ident packet pass through -# - set filter in 0 permit tcp dst eq 113 - set filter out 0 permit tcp src eq 113 -# -# Allow telnet connection to the Internet -# - set filter in 1 permit tcp src eq 23 estab - set filter out 1 permit tcp dst eq 23 -# -# Allow ftp access to the Internet -# - set filter in 2 permit tcp src eq 21 estab - set filter out 2 permit tcp dst eq 21 - set filter in 3 permit tcp src eq 20 dst gt 1023 - set filter out 3 permit tcp dst eq 20 -# -# Allow access to DNS lookups -# - set filter in 4 permit udp src eq 53 - set filter out 4 permit udp dst eq 53 -# -# Allow DNS Zone Transfers -# - set filter in 5 permit tcp src eq 53 - set filter out 5 permit tcp dst eq 53 -# -# Allow access from/to local network -# - set filter in 6 permit 0/0 192.168.1.0/24 - set filter out 6 permit 192.168.1.0/24 0/0 -# -# Allow ping and traceroute response -# - set filter in 7 permit icmp - set filter out 7 permit icmp - set filter in 8 permit udp dst gt 33433 - set filter out 9 permit udp dst gt 33433 -# -# Allow cvsup -# - set filter in 9 permit tcp src eq 5998 - set filter out 9 permit tcp dst eq 5998 - set filter in 10 permit tcp src eq 5999 - set filter out 10 permit tcp dst eq 5999 -# -# Allow NTP for Time Synchronization -# - set filter in 11 permit tcp src eq 123 dst eq 123 - set filter out 11 permit tcp src eq 123 dst eq 123 - set filter in 12 permit udp src eq 123 dst eq 123 - set filter out 12 permit udp src eq 123 dst eq 123 -# -# SMTP'd be a good idea! -# - set filter in 13 permit tcp src eq 25 - set filter out 13 permit tcp dst eq 25 -# -# -# We use a lot of `whois`, let's pass that -# - set filter in 14 permit tcp src eq 43 - set filter out 14 permit tcp dst eq 43 - set filter in 15 permit udp src eq 43 - set filter out 15 permit udp dst eq 43 -# -# If none of above rules matches, then packet is blocked. -#-------</screen> -</informalexample> -</para> - -<para>Up to 20 distinct filtering rules can be applied to each class of -filter. Rules in each class are number sequentially from 0 to 20 -<emphasis>but none of the rules for a particular filter class take affect -until ruleset '0' is defined!</emphasis></para> - -<para>If you choose <emphasis>not</emphasis> to use Filtering Rules in the PPP -configuration then <acronym>ALL</acronym> traffic will be permitted both into and -out of your system while it's connected to your ISP.</para> - -<para>If you decide that you want to implement filtering rules, add the -above lines to your <filename>/etc/ppp/ppp.conf</filename> file in either the -"default:", "demand:", or "interactive:" section (or all of them - the -choice is yours).</para> - -</sect1> -</chapter> -</book> diff --git a/en_US.ISO8859-1/share/images/callouts/1.png b/en_US.ISO8859-1/share/images/callouts/1.png Binary files differdeleted file mode 100644 index 0ad37cdc31..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/1.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/10.png b/en_US.ISO8859-1/share/images/callouts/10.png Binary files differdeleted file mode 100644 index 470a5cf922..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/10.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/2.png b/en_US.ISO8859-1/share/images/callouts/2.png Binary files differdeleted file mode 100644 index 1b4d5d4751..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/2.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/3.png b/en_US.ISO8859-1/share/images/callouts/3.png Binary files differdeleted file mode 100644 index 436e7443d8..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/3.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/4.png b/en_US.ISO8859-1/share/images/callouts/4.png Binary files differdeleted file mode 100644 index 676b80f5ea..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/4.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/5.png b/en_US.ISO8859-1/share/images/callouts/5.png Binary files differdeleted file mode 100644 index 97aacaca20..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/5.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/6.png b/en_US.ISO8859-1/share/images/callouts/6.png Binary files differdeleted file mode 100644 index a6a58f4b1a..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/6.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/7.png b/en_US.ISO8859-1/share/images/callouts/7.png Binary files differdeleted file mode 100644 index 79b81a9f30..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/7.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/8.png b/en_US.ISO8859-1/share/images/callouts/8.png Binary files differdeleted file mode 100644 index 5cec3a26d4..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/8.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/images/callouts/9.png b/en_US.ISO8859-1/share/images/callouts/9.png Binary files differdeleted file mode 100644 index e8f75901b8..0000000000 --- a/en_US.ISO8859-1/share/images/callouts/9.png +++ /dev/null diff --git a/en_US.ISO8859-1/share/sgml/authors.ent b/en_US.ISO8859-1/share/sgml/authors.ent deleted file mode 100644 index 0ab498c10d..0000000000 --- a/en_US.ISO8859-1/share/sgml/authors.ent +++ /dev/null @@ -1,550 +0,0 @@ -<!-- - Names and email address of contributing authors and CVS committers. - Entity names for committers should be the same as their login names on - freefall.FreeBSD.org. - - Use these entities when referencing people. - - Please keep this list in alphabetical order by entity names. - - IMPORTANT: If you delete names from this file you *must* ensure that - all references to them have been removed from the handbook's - translations. If they haven't then you *will* break the - builds for the other languages, and we will poke fun of you - in public. - - $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/authors.ent,v 1.130 2000/11/13 15:31:15 shige Exp $ ---> - -<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.org</email>"> - -<!ENTITY a.ache "Andrey A. Chernov <email>ache@FreeBSD.org</email>"> - -<!ENTITY a.adam "Adam David <email>adam@FreeBSD.org</email>"> - -<!ENTITY a.ade "Ade Lovett <email>ade@FreeBSD.org</email>"> - -<!ENTITY a.adrian "Adrian Chadd <email>adrian@FreeBSD.org</email>"> - -<!ENTITY a.akiyama "Shunsuke Akiyama <email>akiyama@FreeBSD.org</email>"> - -<!ENTITY a.alc "Alan L. Cox <email>alc@FreeBSD.org</email>"> - -<!ENTITY a.alex "Alexander Langer <email>alex@FreeBSD.org</email>"> - -<!ENTITY a.alfred "Alfred Perlstein <email>alfred@FreeBSD.org</email>"> - -<!ENTITY a.amurai "Atsushi Murai <email>amurai@FreeBSD.org</email>"> - -<!ENTITY a.andreas "Andreas Klemm <email>andreas@FreeBSD.org</email>"> - -<!ENTITY a.andy "Andrey Zakhvatov <email>andy@FreeBSD.org</email>"> - -<!ENTITY a.archie "Archie Cobbs <email>archie@FreeBSD.org</email>"> - -<!ENTITY a.asami "Satoshi Asami <email>asami@FreeBSD.org</email>"> - -<!ENTITY a.asmodai "Jeroen Ruigrok/Asmodai <email>asmodai@FreeBSD.org</email>"> - -<!ENTITY a.assar "Assar Westerlund <email>assar@FreeBSD.org</email>"> - -<!ENTITY a.ats "Andreas Schulz <email>ats@FreeBSD.org</email>"> - -<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>"> - -<!ENTITY a.babkin "Sergey Babkin <email>babkin@FreeBSD.org</email>"> - -<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.org</email>"> - -<!ENTITY a.ben "Ben Smithurst <email>ben@FreeBSD.org</email>"> - -<!ENTITY a.benno "Benno Rice <email>benno@FreeBSD.org</email>"> - -<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.org</email>"> - -<!ENTITY a.bmah "Bruce A. Mah <email>bmah@FreeBSD.org</email>"> - -<!ENTITY a.bmilekic "Bosko Milekic <email>bmilekic@FreeBSD.org</email>"> - -<!ENTITY a.bp "Boris Popov <email>bp@FreeBSD.org</email>"> - -<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.org</email>"> - -<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.org</email>"> - -<!ENTITY a.bsd "Brian S. Dean <email>bsd@FreeBSD.org</email>"> - -<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.org</email>"> - -<!ENTITY a.cg "Cameron Grant <email>cg@FreeBSD.org</email>"> - -<!ENTITY a.charnier "Philippe Charnier <email>charnier@FreeBSD.org</email>"> - -<!ENTITY a.chris "Chris Costello <email>chris@FreeBSD.org</email>"> - -<!ENTITY a.chuck "Chuck Robey <email>chuckr@glue.umd.edu</email>"> - -<!ENTITY a.chuckr "Chuck Robey <email>chuckr@FreeBSD.org</email>"> - -<!ENTITY a.cjh "Junho CHOI <email>cjh@FreeBSD.org</email>"> - -<!ENTITY a.cp "Chuck Paterson <email>cp@FreeBSD.org</email>"> - -<!ENTITY a.cokane "Coleman Kane <email>cokane@FreeBSD.org</email>"> - -<!ENTITY a.cpiazza "Chris Piazza <email>cpiazza@FreeBSD.org</email>"> - -<!ENTITY a.cracauer "Martin Cracauer <email>cracauer@FreeBSD.org</email>"> - -<!ENTITY a.csgr "Geoff Rehmet <email>csgr@FreeBSD.org</email>"> - -<!ENTITY a.cwt "Chris Timmons <email>cwt@FreeBSD.org</email>"> - -<!ENTITY a.dan "Dan Moschuk <email>dan@FreeBSD.org</email>"> - -<!ENTITY a.danny "Daniel O'Callaghan <email>danny@FreeBSD.org</email>"> - -<!ENTITY a.dannyboy "Daniel Harris <email>dannyboy@FreeBSD.org</email>"> - -<!ENTITY a.darrenr "Darren Reed <email>darrenr@FreeBSD.org</email>"> - -<!ENTITY a.davidn "David Nugent <email>davidn@blaze.net.au</email>"> - -<!ENTITY a.dbaker "Daniel Baker <email>dbaker@FreeBSD.org</email>"> - -<!ENTITY a.dburr "Donald Burr <email>dburr@FreeBSD.org</email>"> - -<!ENTITY a.dcs "Daniel C. Sobral <email>dcs@FreeBSD.org</email>"> - -<!ENTITY a.dec "David E. Cross <email>dec@FreeBSD.org</email>"> - -<!ENTITY a.deischen "Daniel Eischen <email>deischen@FreeBSD.org</email>"> - -<!ENTITY a.demon "Dmitry Sivachenko <email>demon@FreeBSD.org</email>"> - -<!ENTITY a.des "Dag-Erling C. Smørgrav <email>des@FreeBSD.org</email>"> - -<!ENTITY a.dfr "Doug Rabson <email>dfr@FreeBSD.org</email>"> - -<!ENTITY a.dg "David Greenman <email>dg@FreeBSD.org</email>"> - -<!ENTITY a.dick "Richard Seaman Jr. <email>dick@FreeBSD.org</email>"> - -<!ENTITY a.dillon "Matthew Dillon <email>dillon@FreeBSD.org</email>"> - -<!ENTITY a.dima "Dima Ruban <email>dima@FreeBSD.org</email>"> - -<!ENTITY a.dirk "Dirk Frömberg <email>dirk@FreeBSD.org</email>"> - -<!ENTITY a.dirkvangulik "Dirk-Willem van Gulik <email>Dirk.vanGulik@jrc.it</email>"> - -<!ENTITY a.dougb "Doug Barton <email>DougB@FreeBSD.org</email>"> - -<!ENTITY a.dt "Dmitrij Tejblum <email>dt@FreeBSD.org</email>"> - -<!ENTITY a.dufault "Peter Dufault <email>dufault@FreeBSD.org</email>"> - -<!ENTITY a.dwhite "Doug White <email>dwhite@FreeBSD.org</email>"> - -<!ENTITY a.dwmalone "David Malone <email>dwmalone@FreeBSD.org</email>"> - -<!ENTITY a.dyson "John Dyson <email>dyson@FreeBSD.org</email>"> - -<!ENTITY a.eivind "Eivind Eklund <email>eivind@FreeBSD.org</email>"> - -<!ENTITY a.ejc "Eric J. Chet <email>ejc@FreeBSD.org</email>"> - -<!ENTITY a.erich "Eric L. Hernes <email>erich@FreeBSD.org</email>"> - -<!ENTITY a.faq "FAQ Maintainer <email>faq@FreeBSD.org</email>"> - -<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.org</email>"> - -<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.org</email>"> - -<!ENTITY a.foxfair "Howard F. Hu <email>foxfair@FreeBSD.org</email>"> - -<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.org</email>"> - -<!ENTITY a.gad "Garance A Drosehn <email>gad@FreeBSD.org</email>"> - -<!ENTITY a.gallatin "Andrew Gallatin <email>gallatin@FreeBSD.org</email>"> - -<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.org</email>"> - -<!ENTITY a.gena "Gennady B. Sorokopud <email>gena@NetVision.net.il</email>"> - -<!ENTITY a.ghelmer "Guy Helmer <email>ghelmer@cs.iastate.edu</email>"> - -<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.org</email>"> - -<!ENTITY a.gioria "Sebastien Gioria <email>gioria@FreeBSD.org</email>"> - -<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.org</email>"> - -<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.org</email>"> - -<!ENTITY a.graichen "Thomas Graichen <email>graichen@FreeBSD.org</email>"> - -<!ENTITY a.green "Brian F. Feldman <email>green@FreeBSD.org</email>"> - -<!ENTITY a.grog "Greg Lehey <email>grog@FreeBSD.org</email>"> - -<!ENTITY a.groudier "Gerard Roudier <email>groudier@club-internet.fr</email>"> - -<!ENTITY a.gryphon "Coranth Gryphon <email>gryphon@healer.com</email>"> - -<!ENTITY a.gshapiro "Gregory Neil Shapiro <email>gshapiro@FreeBSD.org</email>"> - -<!ENTITY a.gsutter "Gregory Sutter <email>gsutter@FreeBSD.org</email>"> - -<!ENTITY a.guido "Guido van Rooij <email>guido@FreeBSD.org</email>"> - -<!ENTITY a.hanai "Hiroyuki HANAI <email>hanai@FreeBSD.org</email>"> - -<!ENTITY a.handy "Brian N. Handy <email>handy@sxt4.physics.montana.edu</email>"> - -<!ENTITY a.hrs "Hiroki Sato <email>hrs@FreeBSD.org</email>"> - -<!ENTITY a.roger "Roger Hardiman <email>roger@freebsd.org</email>"> - -<!ENTITY a.helbig "Wolfgang Helbig <email>helbig@FreeBSD.org</email>"> - -<!ENTITY a.hm "Hellmuth Michaelis <email>hm@FreeBSD.org</email>"> - -<!ENTITY a.hoek "Tim Vanderhoek <email>hoek@FreeBSD.org</email>"> - -<!ENTITY a.horikawa "Kazuo Horikawa <email>horikawa@FreeBSD.org</email>"> - -<!ENTITY a.hosokawa "Tatsumi Hosokawa <email>hosokawa@FreeBSD.org</email>"> - -<!ENTITY a.hsu "Jeffrey Hsu <email>hsu@FreeBSD.org</email>"> - -<!ENTITY a.imp "Warner Losh <email>imp@FreeBSD.org</email>"> - -<!ENTITY a.issei "Issei Suzuki <email>issei@FreeBSD.org</email>"> - -<!ENTITY a.itojun "Jun-ichiro Itoh <email>itojun@itojun.org</email>"> - -<!ENTITY a.iwasaki "Mitsuru IWASAKI <email>iwasaki@FreeBSD.org</email>"> - -<!ENTITY a.jake "Jake Burkholder <email>jake@FreeBSD.org</email>"> - -<!ENTITY a.jasone "Jason Evans <email>jasone@FreeBSD.org</email>"> - -<!ENTITY a.jayanth "Jayanth Vijayaraghavan <email>jayanth@FreeBSD.org</email>"> - -<!ENTITY a.jb "John Birrell <email>jb@cimlogic.com.au</email>"> - -<!ENTITY a.jdp "John Polstra <email>jdp@FreeBSD.org</email>"> - -<!ENTITY a.jedgar "Chris D. Faulhaber <email>jedgar@FreeBSD.org</email>"> - -<!ENTITY a.jeh "James Housley <email>jeh@FreeBSD.org</email>"> - -<!ENTITY a.jehamby "Jake Hamby <email>jehamby@lightside.com</email>"> - -<!ENTITY a.jesusr "Jesus Rodriguez <email>jesusr@FreeBSD.org</email>"> - -<!ENTITY a.jfieber "John Fieber <email>jfieber@FreeBSD.org</email>"> - -<!ENTITY a.jfitz "James FitzGibbon <email>jfitz@FreeBSD.org</email>"> - -<!ENTITY a.jgreco "Joe Greco <email>jgreco@FreeBSD.org</email>"> - -<!ENTITY a.jhay "John Hay <email>jhay@FreeBSD.org</email>"> - -<!ENTITY a.jhb "John Baldwin <email>jhb@FreeBSD.org</email>"> - -<!ENTITY a.jhs "Julian Stacey <email>jhs@FreeBSD.org</email>"> - -<!ENTITY a.jim "Jim Mock <email>jim@FreeBSD.org</email>"> - -<!ENTITY a.jkh "Jordan K. Hubbard <email>jkh@FreeBSD.org</email>"> - -<!ENTITY a.jkoshy "Joseph Koshy <email>jkoshy@FreeBSD.org</email>"> - -<!ENTITY a.jlemon "Jonathan Lemon <email>jlemon@FreeBSD.org</email>"> - -<!ENTITY a.jlind "John Lind <email>john@starfire.MN.ORG</email>"> - -<!ENTITY a.jlrobin "James L. Robinson <email>jlrobin@FreeBSD.org</email>"> - -<!ENTITY a.jmacd "Joshua Peck Macdonald <email>jmacd@FreeBSD.org</email>"> - -<!ENTITY a.jmas "Jose M. Alcaide <email>jmas@FreeBSD.org</email>"> - -<!ENTITY a.jmb "Jonathan M. Bresler <email>jmb@FreeBSD.org</email>"> - -<!ENTITY a.jmg "John-Mark Gurney <email>jmg@FreeBSD.org</email>"> - -<!ENTITY a.jmz "Jean-Marc Zucconi <email>jmz@FreeBSD.org</email>"> - -<!ENTITY a.joe "Josef Karthauser <email>joe@FreeBSD.org</email>"> - -<!ENTITY a.joerg "Jörg Wunsch <email>joerg@FreeBSD.org</email>"> - -<!ENTITY a.john "John Cavanaugh <email>john@FreeBSD.org</email>"> - -<!ENTITY a.jon "Jonathan Chen <email>jon@FreeBSD.org</email>"> - -<!ENTITY a.jraynard "James Raynard <email>jraynard@FreeBSD.org</email>"> - -<!ENTITY a.jseger "Justin Seger <email>jseger@FreeBSD.org</email>"> - -<!ENTITY a.julian "Julian Elischer <email>julian@FreeBSD.org</email>"> - -<!ENTITY a.jwd "John W. DeBoskey <email>jwd@FreeBSD.org</email>"> - -<!ENTITY a.jvh "Johannes Helander <email>jvh@FreeBSD.org</email>"> - -<!ENTITY a.karl "Karl Strickland <email>karl@FreeBSD.org</email>"> - -<!ENTITY a.kato "Takenori KATO <email>kato@FreeBSD.org</email>"> - -<!ENTITY a.kbyanc "Kelly Yancey <email>kbyanc@FreeBSD.org</email>"> - -<!ENTITY a.keith "Jing-Tang Keith Jang <email>keith@FreeBSD.org</email>"> - -<!ENTITY a.kelly "Sean Kelly <email>kelly@ad1440.net</email>"> - -<!ENTITY a.ken "Kenneth D. Merry <email>ken@FreeBSD.org</email>"> - -<!ENTITY a.kevlo "Kevin Lo <email>kevlo@FreeBSD.org</email>"> - -<!ENTITY a.kiri "Kazuhiko Kiriyama <email>kiri@FreeBSD.org</email>"> - -<!ENTITY a.kjc "Kenjiro Cho <email>kjc@FreeBSD.org</email>"> - -<!ENTITY a.knu "Akinori MUSHA <email>knu@FreeBSD.org</email>"> - -<!ENTITY a.kris "Kris Kennaway <email>kris@FreeBSD.org</email>"> - -<!ENTITY a.kuriyama "Jun Kuriyama <email>kuriyama@FreeBSD.org</email>"> - -<!ENTITY a.lars "Lars Fredriksen <email>lars@FreeBSD.org</email>"> - -<!ENTITY a.lile "Larry Lile <email>lile@FreeBSD.org</email>"> - -<!ENTITY a.lioux "Mário Sérgio Fujikawa Ferreira<email>lioux@FreeBSD.org</email>"> - -<!ENTITY a.ljo "L Jonas Olsson <email>ljo@FreeBSD.org</email>"> - -<!ENTITY a.luoqi "Luoqi Chen <email>luoqi@FreeBSD.org</email>"> - -<!ENTITY a.marcel "Marcel Moolenaar <email>marcel@FreeBSD.org</email>"> - -<!ENTITY a.markm "Mark Murray <email>markm@FreeBSD.org</email>"> - -<!ENTITY a.marko "Mark Ovens <email>marko@FreeBSD.org</email>"> - -<!ENTITY a.martin "Martin Renters <email>martin@FreeBSD.org</email>"> - -<!ENTITY a.max "Masafumi NAKANE <email>max@FreeBSD.org</email>"> - -<!ENTITY a.mayo "Mark Mayo <email>mark@vmunix.com</email>"> - -<!ENTITY a.mbarkah "Ade Barkah <email>mbarkah@FreeBSD.org</email>"> - -<!ENTITY a.mckay "Stephen McKay <email>mckay@FreeBSD.org</email>"> - -<!ENTITY a.mckusick "Kirk McKusick <email>mckusick@FreeBSD.org</email>"> - -<!ENTITY a.md "Mark Dapoz <email>md@bsc.no</email>"> - -<!ENTITY a.mdodd "Matthew N. Dodd <email>winter@jurai.net</email>"> - -<!ENTITY a.mharo "Michael Haro <email>mharo@FreeBSD.org</email>"> - -<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.org</email>"> - -<!ENTITY a.mks "Mike Spengler <email>mks@FreeBSD.org</email>"> - -<!ENTITY a.motoyuki "Motoyuki Konno <email>motoyuki@FreeBSD.org</email>"> - -<!ENTITY a.mph "Matthew Hunt <email>mph@FreeBSD.org</email>"> - -<!ENTITY a.mpp "Mike Pritchard <email>mpp@FreeBSD.org</email>"> - -<!ENTITY a.msmith "Michael Smith <email>msmith@FreeBSD.org</email>"> - -<!ENTITY a.mtaylor "Mark J. Taylor <email>mtaylor@FreeBSD.org</email>"> - -<!ENTITY a.murray "Murray Stokely <email>murray@FreeBSD.org</email>"> - -<!ENTITY a.nakai "Yukihiro Nakai <email>nakai@FreeBSD.org</email>"> - -<!ENTITY a.nate "Nate Williams <email>nate@FreeBSD.org</email>"> - -<!ENTITY a.nbm "Neil Blakey-Milner <email>nbm@FreeBSD.org</email>"> - -<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.org</email>"> - -<!ENTITY a.newton "Mark Newton <email>newton@FreeBSD.org</email>"> - -<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.org</email>"> - -<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.org</email>"> - -<!ENTITY a.non "Noriaki Mitsunaga <email>non@FreeBSD.org</email>"> - -<!ENTITY a.nsayer "Nick Sayer <email>nsayer@FreeBSD.org</email>"> - -<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.org</email>"> - -<!ENTITY a.nyan "Yoshihiro Takahashi <email>nyan@FreeBSD.org</email>"> - -<!ENTITY a.obrien "David O'Brien <email>obrien@FreeBSD.org</email>"> - -<!ENTITY a.okazaki "OKAZAKI Tetsurou <email>okazaki@FreeBSD.org</email>"> - -<!ENTITY a.olah "Andras Olah <email>olah@FreeBSD.org</email>"> - -<!ENTITY a.onoe "Atsushi Onoe <email>onoe@FreeBSD.org</email>"> - -<!ENTITY a.opsys "Chris Watson <email>opsys@open-systems.net</email>"> - -<!ENTITY a.patrick "Patrick S. Gardella <email>patrick@FreeBSD.org</email>"> - -<!ENTITY a.paul "Paul Richards <email>paul@FreeBSD.org</email>"> - -<!ENTITY a.pb "Pierre Beyssac <email>pb@fasterix.freenix.org</email>"> - -<!ENTITY a.pds "Peter da Silva <email>pds@FreeBSD.org</email>"> - -<!ENTITY a.peter "Peter Wemm <email>peter@FreeBSD.org</email>"> - -<!ENTITY a.phantom "Alexey Zelkin <email>phantom@FreeBSD.org</email>"> - -<!ENTITY a.phk "Poul-Henning Kamp <email>phk@FreeBSD.org</email>"> - -<!ENTITY a.pho "Peter Holm <email>pho@FreeBSD.org</email>"> - -<!ENTITY a.piero "Piero Serini <email>piero@strider.inet.it</email>"> - -<!ENTITY a.pjc "Peter Childs <email>pjchilds@imforei.apana.org.au</email>"> - -<!ENTITY a.proven "Chris Provenzano <email>proven@FreeBSD.org</email>"> - -<!ENTITY a.ps "Paul Saab <email>ps@FreeBSD.org</email>"> - -<!ENTITY a.pst "Paul Traina <email>pst@FreeBSD.org</email>"> - -<!ENTITY a.reg "Jeremy Lea <email>reg@FreeBSD.org</email>"> - -<!ENTITY a.rgrimes "Rodney Grimes <email>rgrimes@FreeBSD.org</email>"> - -<!ENTITY a.rhuff "Robert Huff <email>rhuff@cybercom.net</email>"> - -<!ENTITY a.ricardag "Ricardo AG <email>ricardag@ag.com.br</email>"> - -<!ENTITY a.rich "Rich Murphey <email>rich@FreeBSD.org</email>"> - -<!ENTITY a.rnordier "Robert Nordier <email>rnordier@FreeBSD.org</email>"> - -<!ENTITY a.roberto "Ollivier Robert <email>roberto@FreeBSD.org</email>"> - -<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.org</email>"> - -<!ENTITY a.ru "Ruslan Ermilov <email>ru@FreeBSD.org</email>"> - -<!ENTITY a.rv "Rajesh Vaidheeswarran <email>rv@FreeBSD.org</email>"> - -<!ENTITY a.rwatson "Robert Watson <email>rwatson@FreeBSD.org</email>"> - -<!ENTITY a.sada "SADA Kenji <email>sada@FreeBSD.org</email>"> - -<!ENTITY a.sanpei "Yoshiro Sanpei MIHIRA <email>sanpei@FreeBSD.org</email>"> - -<!ENTITY a.scottl "Scott Long <email>scottl@FreeBSD.org</email>"> - -<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.org</email>"> - -<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.org</email>"> - -<!ENTITY a.sef "Sean Eric Fagan <email>sef@FreeBSD.org</email>"> - -<!ENTITY a.shafeeq "Shafeeq Sinnamohideen <email>shafeeq@FreeBSD.org</email>"> - -<!ENTITY a.sheldonh "Sheldon Hearn <email>sheldonh@FreeBSD.org</email>"> - -<!ENTITY a.shige "Shigeyuki Fukushima <email>shige@FreeBSD.org</email>"> - -<!ENTITY a.shin "Yoshinobu Inoue <email>shin@FreeBSD.org</email>"> - -<!ENTITY a.simokawa "Hidetoshi Shimokawa <email>simokawa@FreeBSD.org</email>"> - -<!ENTITY a.smace "Scott Mace <email>smace@FreeBSD.org</email>"> - -<!ENTITY a.smpatel "Sujal Patel <email>smpatel@FreeBSD.org</email>"> - -<!ENTITY a.sobomax "Maxim Sobolev <email>sobomax@FreeBSD.org</email>"> - -<!ENTITY a.sos "Søren Schmidt <email>sos@FreeBSD.org</email>"> - -<!ENTITY a.stark "Gene Stark <email>stark@FreeBSD.org</email>"> - -<!ENTITY a.stb "Stefan Bethke <email>stb@FreeBSD.org</email>"> - -<!ENTITY a.steve "Steve Price <email>steve@FreeBSD.org</email>"> - -<!ENTITY a.sumikawa "Munechika Sumikawa <email>sumikawa@FreeBSD.org</email>"> - -<!ENTITY a.swallace "Steven Wallace <email>swallace@FreeBSD.org</email>"> - -<!ENTITY a.tanimura "Seigo Tanimura <email>tanimura@FreeBSD.org</email>"> - -<!ENTITY a.taoka "Satoshi Taoka <email>taoka@FreeBSD.org</email>"> - -<!ENTITY a.takawata "Takanori Watanabe <email>takawata@FreeBSD.org</email>"> - -<!ENTITY a.tedm "Ted Mittelstaedt <email>tedm@FreeBSD.org</email>"> - -<!ENTITY a.tegge "Tor Egge <email>tegge@FreeBSD.org</email>"> - -<!ENTITY a.tg "Thomas Gellekum <email>tg@FreeBSD.org</email>"> - -<!ENTITY a.thepish "Peter Hawkins <email>thepish@FreeBSD.org</email>"> - -<!ENTITY a.tom "Tom Hukins <email>tom@FreeBSD.org</email>"> - -<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.org</email>"> - -<!ENTITY a.toshi "Toshihiko Arai <email>toshi@FreeBSD.org</email>"> - -<!ENTITY a.trevor "Trevor Johnson <email>trevor@FreeBSD.org</email>"> - -<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.org</email>"> - -<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.org</email>"> - -<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.org</email>"> - -<!ENTITY a.ulf "Ulf Zimmermann <email>ulf@FreeBSD.org</email>"> - -<!ENTITY a.ume "Hajimu UMEMOTO <email>ume@FreeBSD.org</email>"> - -<!ENTITY a.unfurl "Bill Swingle <email>unfurl@FreeBSD.org</email>"> - -<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.org</email>"> - -<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.org</email>"> - -<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>"> - -<!ENTITY a.wilko "Wilko Bulte <email>wilko@FreeBSD.org</email>"> - -<!ENTITY a.will "Will Andrews <email>will@FreeBSD.org</email>"> - -<!ENTITY a.wlloyd "Bill Lloyd <email>wlloyd@mpd.ca</email>"> - -<!ENTITY a.wollman "Garrett Wollman <email>wollman@FreeBSD.org</email>"> - -<!ENTITY a.wosch "Wolfram Schneider <email>wosch@FreeBSD.org</email>"> - -<!ENTITY a.wpaul "Bill Paul <email>wpaul@FreeBSD.org</email>"> - -<!ENTITY a.wsanchez "Wilfredo Sánchez <email>wsanchez@FreeBSD.org</email>"> - -<!ENTITY a.yokota "Kazutaka YOKOTA <email>yokota@FreeBSD.org</email>"> - diff --git a/en_US.ISO8859-1/share/sgml/bookinfo.ent b/en_US.ISO8859-1/share/sgml/bookinfo.ent deleted file mode 100644 index 5587c3bebd..0000000000 --- a/en_US.ISO8859-1/share/sgml/bookinfo.ent +++ /dev/null @@ -1,12 +0,0 @@ -<!-- - References to other files that can be included within a DocBook - BookInfo element. - - Entity names take the form "bookinfo.<element>", where <element> is - the name of the outermost element in the entity. Examples would - be "bookinfo.legalnotice", and "bookinfo.preface". - - $FreeBSD$ ---> - -<!ENTITY bookinfo.legalnotice SYSTEM "legalnotice.sgml"> diff --git a/en_US.ISO8859-1/share/sgml/catalog b/en_US.ISO8859-1/share/sgml/catalog deleted file mode 100644 index 5ebe8768fc..0000000000 --- a/en_US.ISO8859-1/share/sgml/catalog +++ /dev/null @@ -1,9 +0,0 @@ - -- ...................................................................... -- - -- FreeBSD SGML Public Identifiers ...................................... -- - - -- $FreeBSD: doc/share/sgml/catalog,v 1.9 2000/07/08 16:31:28 phantom Exp $ - -- - -PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" - "freebsd.dsl" - diff --git a/en_US.ISO8859-1/share/sgml/freebsd.dsl b/en_US.ISO8859-1/share/sgml/freebsd.dsl deleted file mode 100644 index 6c2b0451bc..0000000000 --- a/en_US.ISO8859-1/share/sgml/freebsd.dsl +++ /dev/null @@ -1,39 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/share/sgml/freebsd.dsl,v 1.3 2000/06/08 01:58:59 jim Exp $ --> - -<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ -<!ENTITY freebsd.dsl PUBLIC "-//FreeBSD//DOCUMENT DocBook Language Neutral Stylesheet//EN" CDATA DSSSL> -<!ENTITY % output.html "IGNORE"> -<!ENTITY % output.print "IGNORE"> -]> - -<style-sheet> - <style-specification use="docbook"> - <style-specification-body> - - <![ %output.html; [ - (define ($email-footer$) - (make sequence - (literal "For questions about FreeBSD, e-mail <") - (make element gi: "a" - attributes: (list (list "href" "mailto:questions@FreeBSD.org")) - (literal "questions@FreeBSD.org")) - (literal ">.") - (make empty-element gi: "br") - (literal "For questions about this documentation, e-mail <") - (make element gi: "a" - attributes: (list (list "href" "mailto:doc@FreeBSD.org")) - (literal "doc@FreeBSD.org")) - (literal ">."))) - - <!-- Convert " ... " to `` ... '' in the HTML output. --> - (element quote - (make sequence - (literal "``") - (process-children) - (literal "''"))) - ]]> - </style-specification-body> - </style-specification> - - <external-specification id="docbook" document="freebsd.dsl"> -</style-sheet> diff --git a/en_US.ISO8859-1/share/sgml/legalnotice.sgml b/en_US.ISO8859-1/share/sgml/legalnotice.sgml deleted file mode 100644 index ecb8ba6cee..0000000000 --- a/en_US.ISO8859-1/share/sgml/legalnotice.sgml +++ /dev/null @@ -1,44 +0,0 @@ -<!-- - Standard FreeBSD Documentation Project Legal Notice. - - $FreeBSD$ ---> - -<legalnotice> - <para>Redistribution and use in source (SGML DocBook) and 'compiled' - forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions are - met:</para> - - <orderedlist> - <listitem> - <para>Redistributions of source code (SGML DocBook) must retain the - above copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified.</para> - </listitem> - - <listitem> - <para>Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must - reproduce the above copyright notice, this list of conditions and - the following disclaimer in the documentation and/or other - materials provided with the distribution.</para> - </listitem> - </orderedlist> - - <important> - <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION - PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, - BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, - BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS - OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR - TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH - DAMAGE.</para> - </important> -</legalnotice> - |
