aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1')
-rw-r--r--en_US.ISO8859-1/articles/committers-guide/article.xml312
-rw-r--r--en_US.ISO8859-1/articles/contributing-ports/article.xml4
-rw-r--r--en_US.ISO8859-1/articles/contributing/article.xml53
-rw-r--r--en_US.ISO8859-1/articles/contributors/contrib.additional.xml95
-rw-r--r--en_US.ISO8859-1/articles/contributors/contrib.committers.xml52
-rw-r--r--en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml4
-rw-r--r--en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml8
-rw-r--r--en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml4
-rw-r--r--en_US.ISO8859-1/articles/freebsd-update-server/article.xml6
-rw-r--r--en_US.ISO8859-1/articles/geom-class/article.xml2
-rw-r--r--en_US.ISO8859-1/articles/hubs/article.xml11
-rw-r--r--en_US.ISO8859-1/articles/linux-users/article.xml2
-rw-r--r--en_US.ISO8859-1/articles/mailing-list-faq/Makefile4
-rw-r--r--en_US.ISO8859-1/articles/portbuild/article.xml2754
-rw-r--r--en_US.ISO8859-1/articles/problem-reports/article.xml36
-rw-r--r--en_US.ISO8859-1/articles/rc-scripting/article.xml25
-rw-r--r--en_US.ISO8859-1/articles/solid-state/article.xml488
-rw-r--r--en_US.ISO8859-1/books/Makefile1
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/Makefile4
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml299
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml2
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml4
-rw-r--r--en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml10
-rw-r--r--en_US.ISO8859-1/books/bibliography/Makefile4
-rw-r--r--en_US.ISO8859-1/books/corp-net-guide/Makefile25
-rw-r--r--en_US.ISO8859-1/books/corp-net-guide/book.xml3223
-rw-r--r--en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl18
-rw-r--r--en_US.ISO8859-1/books/dev-model/book.xml80
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/Makefile4
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml248
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml155
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml25
-rw-r--r--en_US.ISO8859-1/books/faq/Makefile4
-rw-r--r--en_US.ISO8859-1/books/faq/book.xml4147
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/Makefile4
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml4
-rw-r--r--en_US.ISO8859-1/books/handbook/Makefile8
-rw-r--r--en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml299
-rw-r--r--en_US.ISO8859-1/books/handbook/audit/chapter.xml637
-rw-r--r--en_US.ISO8859-1/books/handbook/basics/chapter.xml3095
-rw-r--r--en_US.ISO8859-1/books/handbook/book.xml3
-rw-r--r--en_US.ISO8859-1/books/handbook/boot/chapter.xml31
-rw-r--r--en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml96
-rw-r--r--en_US.ISO8859-1/books/handbook/colophon.xml21
-rw-r--r--en_US.ISO8859-1/books/handbook/config/chapter.xml113
-rw-r--r--en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml2815
-rw-r--r--en_US.ISO8859-1/books/handbook/desktop/chapter.xml540
-rw-r--r--en_US.ISO8859-1/books/handbook/disks/chapter.xml331
-rw-r--r--en_US.ISO8859-1/books/handbook/dtrace/chapter.xml115
-rw-r--r--en_US.ISO8859-1/books/handbook/eresources/chapter.xml1060
-rw-r--r--en_US.ISO8859-1/books/handbook/filesystems/chapter.xml501
-rw-r--r--en_US.ISO8859-1/books/handbook/firewalls/chapter.xml1903
-rw-r--r--en_US.ISO8859-1/books/handbook/geom/chapter.xml760
-rw-r--r--en_US.ISO8859-1/books/handbook/index.xml1
-rw-r--r--en_US.ISO8859-1/books/handbook/install/chapter.xml4
-rw-r--r--en_US.ISO8859-1/books/handbook/introduction/chapter.xml20
-rw-r--r--en_US.ISO8859-1/books/handbook/jails/Makefile15
-rw-r--r--en_US.ISO8859-1/books/handbook/jails/chapter.xml16
-rw-r--r--en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml928
-rw-r--r--en_US.ISO8859-1/books/handbook/l10n/chapter.xml631
-rw-r--r--en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml906
-rw-r--r--en_US.ISO8859-1/books/handbook/mac/chapter.xml868
-rw-r--r--en_US.ISO8859-1/books/handbook/mail/chapter.xml12
-rw-r--r--en_US.ISO8859-1/books/handbook/mirrors/chapter.xml3397
-rw-r--r--en_US.ISO8859-1/books/handbook/multimedia/chapter.xml1481
-rw-r--r--en_US.ISO8859-1/books/handbook/network-servers/chapter.xml379
-rw-r--r--en_US.ISO8859-1/books/handbook/ports/chapter.xml2221
-rw-r--r--en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml1966
-rw-r--r--en_US.ISO8859-1/books/handbook/preface/preface.xml641
-rw-r--r--en_US.ISO8859-1/books/handbook/printing/chapter.xml4018
-rw-r--r--en_US.ISO8859-1/books/handbook/security/chapter.xml35
-rw-r--r--en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml2123
-rw-r--r--en_US.ISO8859-1/books/handbook/users/chapter.xml649
-rw-r--r--en_US.ISO8859-1/books/handbook/vinum/chapter.xml685
-rw-r--r--en_US.ISO8859-1/books/handbook/virtualization/chapter.xml46
-rw-r--r--en_US.ISO8859-1/books/handbook/x11/chapter.xml1079
-rw-r--r--en_US.ISO8859-1/books/pmake/Makefile6
-rw-r--r--en_US.ISO8859-1/books/porters-handbook/Makefile4
-rw-r--r--en_US.ISO8859-1/books/porters-handbook/book.xml270
-rw-r--r--en_US.ISO8859-1/flyer/Makefile2
-rw-r--r--en_US.ISO8859-1/flyer/flyer.tex13
-rw-r--r--en_US.ISO8859-1/htdocs/4xx.xml25
-rw-r--r--en_US.ISO8859-1/htdocs/Makefile6
-rw-r--r--en_US.ISO8859-1/htdocs/about.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/administration.xml21
-rw-r--r--en_US.ISO8859-1/htdocs/advocacy/myths.xml5
-rw-r--r--en_US.ISO8859-1/htdocs/applications.xml13
-rw-r--r--en_US.ISO8859-1/htdocs/art.xml4
-rw-r--r--en_US.ISO8859-1/htdocs/cgi/cgi-style.pl2
-rwxr-xr-xen_US.ISO8859-1/htdocs/cgi/cvsweb.cgi7
-rwxr-xr-xen_US.ISO8859-1/htdocs/cgi/man.cgi36
-rwxr-xr-xen_US.ISO8859-1/htdocs/cgi/ports.cgi8
-rwxr-xr-xen_US.ISO8859-1/htdocs/cgi/query-pr-summary.cgi14
-rw-r--r--en_US.ISO8859-1/htdocs/community.xsl6
-rw-r--r--en_US.ISO8859-1/htdocs/community/mailinglists.xml3
-rw-r--r--en_US.ISO8859-1/htdocs/copyright/Makefile7
-rw-r--r--en_US.ISO8859-1/htdocs/copyright/copyright.xml3
-rw-r--r--en_US.ISO8859-1/htdocs/copyright/freebsd-doc-license.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/copyright/freebsd-license.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/developers/cvs.xml67
-rw-r--r--en_US.ISO8859-1/htdocs/doc/Makefile6
-rw-r--r--en_US.ISO8859-1/htdocs/docproj/translations.xml10
-rw-r--r--en_US.ISO8859-1/htdocs/docs/books.xml7
-rw-r--r--en_US.ISO8859-1/htdocs/donations/donors.xml7
-rw-r--r--en_US.ISO8859-1/htdocs/donations/index.xml22
-rw-r--r--en_US.ISO8859-1/htdocs/donations/wantlist.xml8
-rw-r--r--en_US.ISO8859-1/htdocs/events/Makefile4
-rw-r--r--en_US.ISO8859-1/htdocs/features.xml312
-rw-r--r--en_US.ISO8859-1/htdocs/gnome/docs/bugging.xml4
-rw-r--r--en_US.ISO8859-1/htdocs/gnome/docs/faq2.xml5
-rw-r--r--en_US.ISO8859-1/htdocs/gnome/gnomelogalyzer.sh4
-rw-r--r--en_US.ISO8859-1/htdocs/google6bb24ed0b804d5e9.html1
-rw-r--r--en_US.ISO8859-1/htdocs/index.xsl5
-rw-r--r--en_US.ISO8859-1/htdocs/internal/Makefile2
-rw-r--r--en_US.ISO8859-1/htdocs/internal/bylaws.xml4
-rw-r--r--en_US.ISO8859-1/htdocs/internal/doceng.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/internal/homepage.pl7
-rw-r--r--en_US.ISO8859-1/htdocs/internal/i18n.xml3
-rw-r--r--en_US.ISO8859-1/htdocs/layout/css/fixed.css2
-rw-r--r--en_US.ISO8859-1/htdocs/layout/css/layout.css69
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/Makefile11
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_get_back.pngbin209 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_get_bl.pngbin353 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_get_br.pngbin335 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_get_tl.pngbin338 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_get_tr.pngbin360 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_new_back.pngbin201 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_new_bl.pngbin305 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_new_br.pngbin291 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_new_tl.pngbin298 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/images/front_new_tr.pngbin314 -> 0 bytes
-rw-r--r--en_US.ISO8859-1/htdocs/layout/js/google.js53
-rw-r--r--en_US.ISO8859-1/htdocs/multimedia/multimedia-input.xml36
-rw-r--r--en_US.ISO8859-1/htdocs/news/2012-compromise.xml340
-rw-r--r--en_US.ISO8859-1/htdocs/news/2012-compromise/Makefile13
-rw-r--r--en_US.ISO8859-1/htdocs/news/2012-compromise/md5.sums.20121118.txt22593
-rw-r--r--en_US.ISO8859-1/htdocs/news/2012-compromise/sha256.sums.20121118.txt22593
-rw-r--r--en_US.ISO8859-1/htdocs/news/Makefile4
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/Makefile1
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/README6
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/report-2001-08.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/report-2002-05-2002-06.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/report-2012-04-2012-06.xml1007
-rw-r--r--en_US.ISO8859-1/htdocs/news/status/status.xml4
-rw-r--r--en_US.ISO8859-1/htdocs/platforms/arm.xml3
-rw-r--r--en_US.ISO8859-1/htdocs/privacy.xml60
-rw-r--r--en_US.ISO8859-1/htdocs/projects/mac/index.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/projects/newbies.xml6
-rw-r--r--en_US.ISO8859-1/htdocs/projects/projects.xml6
-rw-r--r--en_US.ISO8859-1/htdocs/releases/5.3R/todo.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/releases/6.1R/todo.xml4
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/Makefile11
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/announce.xml331
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/errata.html247
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/hardware.html10978
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/installation.html235
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/readme.html403
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/relnotes-detailed.html2010
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/relnotes.xml875
-rw-r--r--en_US.ISO8859-1/htdocs/releases/9.1R/schedule.xml19
-rw-r--r--en_US.ISO8859-1/htdocs/releases/index.xml10
-rw-r--r--en_US.ISO8859-1/htdocs/releng/charter.xml2
-rw-r--r--en_US.ISO8859-1/htdocs/releng/index.xml24
-rw-r--r--en_US.ISO8859-1/htdocs/relnotes.xml12
-rw-r--r--en_US.ISO8859-1/htdocs/search/index-site.xsl2
-rw-r--r--en_US.ISO8859-1/htdocs/search/sitemap.xml35
-rw-r--r--en_US.ISO8859-1/htdocs/security/security.xml13
-rw-r--r--en_US.ISO8859-1/htdocs/snapshots/index.xml25
-rw-r--r--en_US.ISO8859-1/htdocs/where.xml15
-rw-r--r--en_US.ISO8859-1/share/xml/mailing-lists.ent25
-rw-r--r--en_US.ISO8859-1/share/xml/release.l10n.ent12
-rw-r--r--en_US.ISO8859-1/share/xml/teams.ent2
172 files changed, 84005 insertions, 25611 deletions
diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml
index 16dbbe89a2..76ba7fc331 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.xml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -23,6 +23,7 @@
<year>2010</year>
<year>2011</year>
<year>2012</year>
+ <year>2013</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
@@ -209,7 +210,7 @@
<row>
<entry>doc</entry>
<entry>doceng@</entry>
- <entry>doc/, www/, src/ documentation</entry>
+ <entry>doc/, src/ documentation</entry>
</row>
<row>
@@ -367,7 +368,7 @@
<sect2 id="svn-getting-started">
<title>Getting Started</title>
- <para>There are three ways to obtain a working copy of the tree
+ <para>There are a few ways to obtain a working copy of the tree
from Subversion. This section will explain them.</para>
<sect3>
@@ -463,119 +464,6 @@
information on how to set one up.</para>
</sect3>
- <sect3>
- <title>Checkout from a Local Mirror Using
- <acronym>SVK</acronym></title>
-
- <para>The third alternative is to use <acronym>SVK</acronym>
- to maintain a local mirror. It is a version control system
- build on top of Subversion's storage engine. It is
- identical to Subversion in most respects, except that it
- allows for setting up parts of repositories as mirrors of
- other repositories, and keeping local branches for merging
- back into the upstream repositories. There are extensions
- that allow <acronym>SVK</acronym> to mirror
- <acronym>CVS</acronym> and Perforce repositories in addition
- to Subversion ones.</para>
-
- <para>Like everything, <acronym>SVK</acronym> has its
- disadvantages, one being that local revision numbers will
- not match upstream revision numbers. This makes it
- difficult to <command>svk log</command>, <command>svk
- diff</command>, or <command>svk update</command> to an
- arbitrary upstream revision.</para>
-
- <para>To set up a mirror of the &os; repository, do:</para>
-
- <screen>&prompt.user; <userinput>svk mirror svn+ssh://svn.freebsd.org/base //freebsd/base</userinput></screen>
-
- <para>The local <acronym>SVK</acronym> repository will be
- stored in <filename
- class="directory">~/.svk/local/</filename>, but can be
- moved to an alternate location. If it is moved,
- <filename>~/.svk/config</filename> should be amended
- manually to reflect the move.</para>
-
- <para>Any path can be used, not just the one in the example
- above. A common pattern is to place mirrors under
- <literal>//mirror</literal>, e.g.,
- <filename
- class="directory">//mirror/freebsd/base/</filename>, and
- local branches under <literal>//local</literal>.</para>
-
- <para>To pull down the contents of the repository to the
- mirror:</para>
-
- <screen>&prompt.user; <userinput>svk sync //freebsd/base</userinput></screen>
-
- <note>
- <para><command>svk sync</command> will take a very long
- time, possibly several days over a slow network
- connection. &a.peter; has a tarball that can be used to
- jumpstart the mirror, but only if one does not exist
- already.</para>
- </note>
-
- <para>To use the tarball referenced above:</para>
-
- <screen>&prompt.user; <userinput>cd ~</userinput>
-&prompt.user; <userinput>scp freefall:/home/peter/dot_svk_r179646.tbz2 .</userinput>
-&prompt.user; <userinput>tar xf dot_svk_r179646.tbz2</userinput></screen>
-
- <para>Then edit <filename>~/.svk/config</filename> and replace
- <filename
- class="directory">/scratch/tmp/peter/.svk/local/</filename>
- with the equivalent of <filename
- class="directory">/home/<replaceable>jarjar</replaceable>/.svk/local/</filename>.</para>
-
- <para>You can check out files directly from your mirror, once
- it has been created:</para>
-
- <screen>&prompt.user; <userinput>svk checkout //freebsd/base/head /usr/src</userinput></screen>
-
- <para>Unlike <acronym>SVN</acronym>, <acronym>SVK</acronym>
- does not store metadata or reference copies in the working
- copy. All metadata is recorded in
- <filename>~/.svk/config</filename>; reference copies are not
- used at all because <acronym>SVK</acronym> always operates
- on a local repository.</para>
-
- <para>When committing from a working copy like the one above,
- <acronym>SVN</acronym> will commit directly to the upstream
- repository, then synchronise the mirror.</para>
-
- <para>However, the <quote>killer app</quote> for
- <acronym>SVK</acronym> is the ability to work without a
- network connection. To do that, a local branch must be set
- up:</para>
-
- <screen>&prompt.user; <userinput>svk mkdir //local/freebsd</userinput>
-&prompt.user; <userinput>svk copy //freebsd/base/head //local/freebsd/head</userinput></screen>
-
- <para>Once again, any path can be used, it does not have to
- specifically be the one in the example.</para>
-
- <para>Before use, the local branch has to be synchronized,
- like so:</para>
-
- <screen>&prompt.user; <userinput>svk pull //local/freebsd/head</userinput></screen>
-
- <para>Then check out from the newly created local
- branch:</para>
-
- <screen>&prompt.user; <userinput>svk checkout //local/freebsd/head /usr/src</userinput></screen>
-
- <para>The point of this exercise is showing that it is
- possible to commit work-in-progress to a local branch, and
- only push it to the upstream repository when work is
- complete. The easy way to push is with <command>svk
- push</command>, but there is a serious disadvantage to it:
- it will push every single commit made to the local branch
- incrementally instead of lumping them all into a single
- commit. Therefore, using <command>svk smerge</command> is
- preferable.</para>
- </sect3>
-
<sect3 id="subversion-primer-base-layout">
<title><literal>RELENG_*</literal> Branches and General
Layout</title>
@@ -708,16 +596,6 @@
daily use, except for the revision renumbering mentioned
earlier.</para>
- <note>
- <para><acronym>SVN</acronym> and <acronym>SVK</acronym>
- commands that have direct <acronym>CVS</acronym> equivalents
- usually have the same name and abbreviations. For example:
- <emphasis>checkout</emphasis> and <emphasis>co</emphasis>,
- <emphasis>update</emphasis> and <emphasis>up</emphasis>, and
- <emphasis>commit</emphasis> and
- <emphasis>ci</emphasis>.</para>
- </note>
-
<sect3>
<title>Help</title>
@@ -821,11 +699,7 @@
<screen>&prompt.user; <userinput>svn status</userinput></screen>
- <para><acronym>CVS</acronym> has no direct equivalent of this
- command. The nearest would be <command>cvs up -N</command>
- which shows local changes and files that are out-of-date.
- Doing this in <acronym>SVN</acronym> is possible too,
- however:</para>
+ <para>To show local changes and files that are out-of-date do:</para>
<screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
</sect3>
@@ -833,7 +707,7 @@
<sect3>
<title>Editing and Committing</title>
- <para>Like <acronym>CVS</acronym> but unlike Perforce,
+ <para>Unlike Perforce,
<acronym>SVN</acronym> and <acronym>SVK</acronym> do not
need to be told in advance about file editing.</para>
@@ -879,7 +753,7 @@
</para>
</note>
- <para>As with <acronym>CVS</acronym>, files are added to a
+ <para>Files are added to a
<acronym>SVN</acronym> repository with <command>svn
add</command>. To add a file named
<emphasis>foo</emphasis>, edit it, then:</para>
@@ -907,10 +781,9 @@
<screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen>
- <para>In <acronym>CVS</acronym>, the directory is immediately
- created in the repository when you <command>cvs
- add</command> it; this is not the case in Subversion.
- Furthermore, unlike <acronym>CVS</acronym>, Subversion
+ <para>The directory is not immediately
+ created in the repository when you use <command>svn
+ mkdir</command>. Subversion
allows directories to be removed using <command>svn
rm</command>, however there is no <command>svn
rmdir</command>:</para>
@@ -935,9 +808,6 @@
<screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput>
&prompt.user; <userinput>svn remove <replaceable>foo.c</replaceable></userinput></screen>
-
- <para>Neither of these operations have equivalents in
- <acronym>CVS</acronym>.</para>
</sect3>
<sect3>
@@ -962,11 +832,11 @@
<para><command>svn diff</command> displays changes to the
working copy of the repository. Diffs generated by
- <acronym>SVN</acronym> are unified by default, unlike
- <acronym>CVS</acronym>, and include new files by default
+ <acronym>SVN</acronym> are unified
+ and include new files by default
in the diff output.</para>
- <para>As with <acronym>CVS</acronym>, <command>svn
+ <para><command>svn
diff</command> can show the changes between two revisions
of the same file:</para>
@@ -984,8 +854,8 @@
<title>Reverting</title>
<para>Local changes (including additions and deletions) can be
- reverted using <command>svn revert</command>. Unlike
- <command>cvs up -C</command>, it does not update out-of-date
+ reverted using <command>svn revert</command>.
+ It does not update out-of-date
files&mdash;it just replaces them with pristine copies of
the original version.</para>
</sect3>
@@ -1848,6 +1718,13 @@ U stable/9/share/man/man4/netmap.4
<screen>&prompt.user; <userinput>svn merge -r179454:179453 svn+ssh://svn.freebsd.org/base/ROADMAP.txt</userinput></screen>
+ <note>
+ <para>It is important to ensure that the mergeinfo
+ is correct when reverting a file in order to permit
+ <command>svn mergeinfo --eligible</command> to work as
+ expected.</para>
+ </note>
+
<para>Reverting the deletion of a file is slightly different.
Copying the version of the file that predates the deletion
is required. For example, to restore a file that was
@@ -1874,8 +1751,8 @@ U stable/9/share/man/man4/netmap.4
of <command>svn status</command> and <command>svn
diff</command> before committing.</para>
- <para>Mistakes will happen, but, unlike with
- <acronym>CVS</acronym>, they can generally be fixed without
+ <para>Mistakes will happen but,
+ they can generally be fixed without
disruption.</para>
<para>Take a case of adding a file in the wrong location. The
@@ -2011,37 +1888,20 @@ U stable/9/share/man/man4/netmap.4
<para>Don't remove and re-add the same file in a single commit
as this will break the CVS exporter.</para>
- <para>Speeding up checkouts and minimising network traffic is
- possible with the following recipe:</para>
-
- <screen>&prompt.user; <userinput>svn co --depth=empty svn+ssh://svn.freebsd.org/base fbsvn</userinput>
-&prompt.user; <userinput>cd fbsvn</userinput>
-&prompt.user; <userinput>svn up --depth=empty stable</userinput>
-&prompt.user; <userinput>svn up head</userinput>
-&prompt.user; <userinput>cd stable</userinput>
-&prompt.user; <userinput>cp -r ../head/ 7</userinput>
-&prompt.user; <userinput>cd 7</userinput>
-&prompt.user; <userinput>svn switch svn+ssh://svn.freebsd.org/base/stable/7</userinput>
-&prompt.user; <userinput>cd ..</userinput>
-&prompt.user; <userinput>cp -r 7/ 6</userinput>
-&prompt.user; <userinput>cd 6</userinput>
-&prompt.user; <userinput>svn switch svn+ssh://svn.freebsd.org/base/stable/6</userinput></screen>
-
- <para>What this bit of evil does is check out head, stable/7 and
- stable/6. We create the empty checkout directories under
- <acronym>SVN</acronym>'s control. In <acronym>SVN</acronym>,
- subtrees are self identifying, like in <acronym>CVS</acronym>.
- We check out head and clone it as stable/7. Except we don't
- want the head version so we <quote>switch</quote> it to the
- 7.x tree location. <acronym>SVN</acronym> downloads diffs to
- convert the <quote>head</quote> files to
- <quote>stable/7</quote> instead of doing a fresh checkout.
- The same goes for stable/6. This does, however, definitely
- count as abuse of the working copy client code!</para>
+ <para>Speeding up svn is
+ possible by adding the following to <filename>~/.ssh/config</filename>:</para>
+
+ <screen>Host *
+ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
+ControlMaster auto
+ControlPersist yes</screen>
+
+ <para>and then typing</para>
+ <screen><userinput>mkdir ~/.ssh/sockets</userinput></screen>
<para>Checking out a working copy with a stock Subversion client
without &os;-specific patches
- (<makevar>WITH_FREEBSD_TEMPLATE</makevar>) will mean that
+ (<makevar>OPTIONS_SET=FREEBSD_TEMPLATE</makevar>) will mean that
<literal>&dollar;FreeBSD&dollar;</literal> tags will not be
expanded. Once the correct version has been installed, trick
Subversion into expanding them like so:</para>
@@ -2049,8 +1909,7 @@ U stable/9/share/man/man4/netmap.4
<screen>&prompt.user; <userinput>svn propdel -R svn:keywords .</userinput>
&prompt.user; <userinput>svn revert -R .</userinput></screen>
- <para>This is not a good idea if uncommitted patches exist,
- however.</para>
+ <para>This will wipe out uncommitted patches.</para>
</sect2>
</sect1>
@@ -2078,7 +1937,7 @@ U stable/9/share/man/man4/netmap.4
<itemizedlist>
<listitem>
<para>Add your author entity to
- <filename>head/en_US.ISO8859-1/share/xml/authors.ent</filename>;
+ <filename>head/share/xml/authors.ent</filename>;
this should be done first since an omission of this commit will
cause the next commits to break the doc/ build.</para>
@@ -2186,8 +2045,8 @@ U stable/9/share/man/man4/netmap.4
</listitem>
<listitem>
- <para>(For committers only:)
- If you subscribe to &a.svn-src-all.name; or the &a.cvsall;,
+ <para>If you subscribe to &a.svn-src-all.name;,
+ &a.svn-ports-all.name; or &a.svn-doc-all.name;,
you will probably want to unsubscribe to avoid receiving duplicate
copies of commit messages and their followups.</para>
</listitem>
@@ -2591,14 +2450,13 @@ U stable/9/share/man/man4/netmap.4
<term>&a.committers;</term>
<listitem>
- <para>cvs-committers is the entity that the version control system uses to send you all your
- commit messages. You should <emphasis>never</emphasis> send email
- directly to this list. You should only send replies to this list
- when they are short and are directly related to a commit.</para>
-
- <para>There is a similar list, svn-committers, which has a
- similar purpose but is a normal list, i.e., you are free to
- send any suitable message to this list.</para>
+ <para>&a.svn-src-all.name;, &a.svn-ports-all.name; and
+ &a.svn-doc-all.name; are the mailing lists that the
+ version control system uses to send commit messages to.
+ You should <emphasis>never</emphasis> send email directly
+ to these lists. You should only send replies to this list
+ when they are short and are directly related to a
+ commit.</para>
</listitem>
</varlistentry>
@@ -3488,9 +3346,9 @@ U stable/9/share/man/man4/netmap.4
from the port <filename>Makefile</filename>.
It will also add an entry to the port's
category <filename>Makefile</filename>. It was
- written by &a.mharo; and &a.will;, and is currently maintained
- by &a.garga;, so please send questions/patches about
- <command>addport</command> to him.</para>
+ written by &a.mharo;, &a.will;, and &a.garga;. When sending
+ questions about this script to the &a.ports;, please also CC
+ &a.crees;, the current maintainer.</para>
</answer>
</qandaentry>
@@ -3597,9 +3455,9 @@ U stable/9/share/man/man4/netmap.4
<para>Alternatively, you can use the <command>rmport</command>
script, from <filename class="directory">ports/Tools/scripts</filename>.
- This script has been written by &a.vd;, who is also its current
- maintainer, so please send questions, patches or suggestions
- about <command>rmport</command> to him.</para>
+ This script was written by &a.vd;. When sending
+ questions about this script to the &a.ports;, please also CC
+ &a.crees;, the current maintainer.</para>
</answer>
</qandaentry>
</qandadiv>
@@ -3657,6 +3515,12 @@ U stable/9/share/man/man4/netmap.4
one step.</para>
</step>
</procedure>
+
+ <tip>
+ <para><command>addport</command> now detects when the port to
+ add has previously existed, and should handle all except
+ the <filename>ports/LEGAL</filename> step automatically.</para>
+ </tip>
</answer>
</qandaentry>
</qandadiv>
@@ -3954,7 +3818,7 @@ U stable/9/share/man/man4/netmap.4
<procedure>
<step>
- <para>Perform any needed repocopies. (This only applies
+ <para>Perform any needed moves. (This only applies
to physical categories.)</para>
</step>
@@ -3978,12 +3842,9 @@ U stable/9/share/man/man4/netmap.4
</question>
<answer>
- <para>The procedure is a strict superset of the one to
- repocopy individual ports (see above).</para>
-
<procedure>
<step>
- <para>Upgrade each copied port's
+ <para>Upgrade each moved port's
<filename>Makefile</filename>. Do not connect the
new category to the build yet.</para>
@@ -4030,10 +3891,11 @@ U stable/9/share/man/man4/netmap.4
sh -e <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh
</command>. This will check <emphasis>every</emphasis>
port in the ports tree, even those not connected to the
- build, so you can run it directly after the repocopy.
+ build, so you can run it directly after the move
+ operation.
Hint: do not forget to look at the
<makevar>PKGORIGIN</makevar>s of any slave ports of the
- ports you just repocopied!</para>
+ ports you just moved!</para>
</step>
<step>
@@ -4067,57 +3929,11 @@ U stable/9/share/man/man4/netmap.4
</step>
<step>
- <para>Update the instructions for &man.cvsup.1;:</para>
-
- <itemizedlist>
- <listitem>
- <para>
- add the category to
- <filename>distrib/cvsup/sup/README</filename>
- </para>
- </listitem>
-
- <listitem>
- <para>
- adding the following files into
- <filename>distrib/cvsup/sup/ports-<replaceable>categoryname</replaceable></filename>:
- <filename>list.cvs</filename> and
- <filename>releases</filename>.</para>
- </listitem>
-
- <listitem>
- <para>
- add the category to
- <filename>src/share/examples/cvsup/ports-supfile</filename>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- (Note: these are
- in the src, not the ports, repository). If you
- are not a src committer, you will need to submit
- a PR for this.</para>
- </step>
-
- <step>
- <para>
- Update the list of categories used by &man.sysinstall.8;
- in <filename>src/usr.sbin/sysinstall</filename>.</para>
- </step>
-
- <step>
<para>Update the documentation by modifying the
following:</para>
<itemizedlist>
<listitem>
- <para>the section of the Handbook that lists the
- <ulink url="&url.books.handbook;/cvsup.html#CVSUP-COLLEC">
- cvsup collections</ulink>.</para>
- </listitem>
-
- <listitem>
<para>the
<ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
list of categories</ulink> in the Porter's Handbook</para>
@@ -4167,10 +3983,6 @@ U stable/9/share/man/man4/netmap.4
<itemizedlist>
<listitem>
- <para><filename>src/usr.sbin/sysinstall</filename></para>
- </listitem>
-
- <listitem>
<para>the
<ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
list of categories</ulink> in the Porter's Handbook</para>
diff --git a/en_US.ISO8859-1/articles/contributing-ports/article.xml b/en_US.ISO8859-1/articles/contributing-ports/article.xml
index 7f299ebd98..f9778f0e7d 100644
--- a/en_US.ISO8859-1/articles/contributing-ports/article.xml
+++ b/en_US.ISO8859-1/articles/contributing-ports/article.xml
@@ -462,7 +462,7 @@
<para>Regularly check the automated ports building
cluster, <ulink
url="http://pointyhat.FreeBSD.org">pointyhat</ulink>,
- and the <ulink url="http://www.portscout.org">distfiles
+ and the <ulink url="http://portscout.FreeBSD.org">distfiles
scanner</ulink> to see if any of the ports you
maintain are failing to build or fetch (see <link
linkend="resources">resources</link> for more
@@ -794,7 +794,7 @@
build status of your ports. As a contributor you can use it to
find broken and unmaintained ports that need to be fixed.</para>
- <para>The <ulink url="http://www.portscout.org">FreeBSD Ports
+ <para>The <ulink url="http://portscout.FreeBSD.org">FreeBSD Ports
distfile scanner</ulink> can show you ports for which the
distfiles are not fetchable. You can check on your own ports or
use it to find ports that need their
diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml
index be8171f5a2..ac6d5f2450 100644
--- a/en_US.ISO8859-1/articles/contributing/article.xml
+++ b/en_US.ISO8859-1/articles/contributing/article.xml
@@ -85,7 +85,7 @@
<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
+ (Docbook is not difficult to learn, but there is no objection
to ASCII submissions).</para>
</listitem>
@@ -231,7 +231,8 @@
<title>Pick one of the items from the <quote>Ideas</quote>
page</title>
- <para>The <ulink url="&url.base;/projects/ideas/">&os; list of
+ <para>The <ulink url="http://wiki.freebsd.org/IdeasPage">&os;
+ list of
projects and ideas for volunteers</ulink> is also available
for people willing to contribute to the &os; project. The
list is being regularly updated and contains items for both
@@ -339,39 +340,22 @@
<para>The preferred &man.diff.1; format for submitting patches
is the unified output format generated by <command>diff
- -u</command>. However, for patches that substantially
- change a region of code, a context output format diff
- generated by <command>diff -c</command> may be more readable
- and thus preferable.</para>
+ -u</command>.</para>
<indexterm>
<primary><command>diff</command></primary>
</indexterm>
- <para>For example:</para>
-
- <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>
-
- <para>or</para>
-
- <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>
-
- <para>would generate such a set of context diffs for the given
- source file or directory hierarchy.</para>
-
- <para>Likewise,</para>
-
<screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen>
<para>or</para>
- <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen>
+ <screen>&prompt.user; <userinput>diff -u -r -N olddir newdir</userinput></screen>
- <para>would do the same, except in the unified diff
- format.</para>
+ <para>would generate a set of unified diffs for the given source
+ file or directory hierarchy.</para>
- <para>See the manual page for &man.diff.1; for more
- details.</para>
+ <para>See &man.diff.1; for more information.</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
@@ -397,9 +381,8 @@
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;
+ such as if you are unsure of copyright issues governing its further
+ distribution then you should send it to &a.core;
directly rather than submitting it with &man.send-pr.1;. The
&a.core; reaches a much smaller group of people who
do much of the day-to-day work on FreeBSD. Note that this
@@ -503,7 +486,7 @@ 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.
- &#36;Id&#36;</programlisting>
+ &dollar;&os;&dollar;</programlisting>
<para>For your convenience, a copy of this text can be found in
<filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para>
@@ -532,9 +515,9 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<para>Donations may be sent in check form to:
<address>
The FreeBSD Foundation
- <street>7321 Brockway Dr.</street>
+ <street>P.O. Box 20247</street>,
<city>Boulder</city>,
- <state>CO</state> <postcode>80303</postcode>
+ <state>CO</state> <postcode>80308</postcode>
<country>USA</country>
</address></para>
@@ -562,16 +545,6 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<ulink url="&url.base;/donations/">Donations Liaison
Office</ulink>.</para>
</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 see the
- <ulink url="&url.articles.hubs;/index.html">Mirroring
- FreeBSD</ulink> article for more information.</para>
- </sect3>
</sect2>
</sect1>
diff --git a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml
index 02ba44b40c..fa3b55279e 100644
--- a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml
+++ b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml
@@ -1144,11 +1144,6 @@
</listitem>
<listitem>
- <para>Barbara</para>
- <!-- (rene@) No email address per request. -->
- </listitem>
-
- <listitem>
<para>Barry Bierbauch
<email>pivrnec@vszbr.cz</email></para>
</listitem>
@@ -1688,7 +1683,7 @@
<listitem>
<para>Chris Petrik
- <email>chris@officialunix.com</email></para>
+ <email>c.petrik.sosa@gmail.com</email></para>
</listitem>
<listitem>
@@ -1722,6 +1717,11 @@
</listitem>
<listitem>
+ <para>Christian Heckendorf
+ <email>heckend@bu.edu</email></para>
+ </listitem>
+
+ <listitem>
<para>Christian Lackas
<email>delta@lackas.net</email></para>
</listitem>
@@ -2121,6 +2121,11 @@
</listitem>
<listitem>
+ <para>Danilo Eg&ecirc;a Gondolfo
+ <email>danilogondolfo@gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Danny Braniss
<email>danny@cs.huji.ac.il</email></para>
</listitem>
@@ -2364,11 +2369,6 @@
</listitem>
<listitem>
- <para>David Naylor
- <email>naylor.b.david@gmail.com</email></para>
- </listitem>
-
- <listitem>
<para>David Otto
<email>ottodavid@gmx.net</email></para>
</listitem>
@@ -2414,18 +2414,23 @@
</listitem>
<listitem>
+ <para>David Vachulka
+ <email>arch_dvx@users.sourceforge.net</email></para>
+ </listitem>
+ <listitem>
+
<para>David Wolfskill
<email>david@catwhisker.org</email></para>
</listitem>
<listitem>
- <para>Dax Labrador
- <email>semprix@bsdmail.org</email></para>
+ <para>David Yeske
+ <email>dyeske@yahoo.com</email></para>
</listitem>
<listitem>
- <para>David Yeske
- <email>dyeske@yahoo.com</email></para>
+ <para>Dax Labrador
+ <email>semprix@bsdmail.org</email></para>
</listitem>
<listitem>
@@ -3091,6 +3096,11 @@
</listitem>
<listitem>
+ <para>Fabian M. Borschel
+ <email>fmb@onibox.net</email></para>
+ </listitem>
+
+ <listitem>
<para>Fabien Devaux
<email>fab@gcu.info</email></para>
</listitem>
@@ -3590,11 +3600,6 @@
</listitem>
<listitem>
- <para>Grzegorz Blach
- <email>magik@roorback.net</email></para>
- </listitem>
-
- <listitem>
<para>Guillaume Paquet
<email>amyfoub@videotron.ca</email></para>
</listitem>
@@ -4428,6 +4433,11 @@
</listitem>
<listitem>
+ <para>Jean Benoit
+ <email>jean@unistra.fr</email></para>
+ </listitem>
+
+ <listitem>
<para>Jean-Sebastien Roy
<email>js@jeannot.org</email></para>
</listitem>
@@ -5123,6 +5133,11 @@
</listitem>
<listitem>
+ <para>Joseph Mingrone
+ <email>jrm@ftfl.ca</email></para>
+ </listitem>
+
+ <listitem>
<para>Joseph Scott
<email>joseph@randomnetworks.com</email></para>
</listitem>
@@ -5302,11 +5317,6 @@
</listitem>
<listitem>
- <para>Kubilay Kocak
- <email>koobs.freebsd@gmail.com</email></para>
- </listitem>
-
- <listitem>
<para>KUNISHIMA Takeo
<email>kunishi@c.oka-pu.ac.jp</email></para>
</listitem>
@@ -6013,6 +6023,11 @@
</listitem>
<listitem>
+ <para>Manuel Creach
+ <email>manuel.creach@me.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Manuel Rabade Garcia
<email>mig@mig-29.net</email></para>
</listitem>
@@ -6461,6 +6476,11 @@
</listitem>
<listitem>
+ <para>Matt Stofko
+ <email>matt@mjslabs.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Matt Thomas
<email>matt@3am-software.com</email></para>
</listitem>
@@ -6760,6 +6780,11 @@
</listitem>
<listitem>
+ <para>Michael Gmelin
+ <email>freebsd@grem.de</email></para>
+ </listitem>
+
+ <listitem>
<para>Michael Hancock
<email>michaelh@cet.co.jp</email></para>
</listitem>
@@ -8315,6 +8340,11 @@
</listitem>
<listitem>
+ <para>Pierre David
+ <email>pdagog@gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Pierre Y. Dampure
<email>pierre.dampure@k2c.co.uk</email></para>
</listitem>
@@ -9337,11 +9367,6 @@
</listitem>
<listitem>
- <para>Simon J Gerraty
- <email>sjg@juniper.net</email></para>
- </listitem>
-
- <listitem>
<para>Simon Lang
<email>simon@lang-clan.de</email></para>
</listitem>
@@ -10518,6 +10543,11 @@
</listitem>
<listitem>
+ <para>Victor Popov
+ <email>v.a.popov@gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Victor Semionov
<email>semionov@mail.bg</email></para>
</listitem>
@@ -10798,6 +10828,11 @@
</listitem>
<listitem>
+ <para>Yamagi Burmeister
+ <email>yamagi@yamagi.org</email></para>
+ </listitem>
+
+ <listitem>
<para>Yanhui Shen
<email>shen.elf@gmail.com</email></para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml
index ba64dac81c..07b1018b5c 100644
--- a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml
+++ b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml
@@ -68,6 +68,10 @@
</listitem>
<listitem>
+ <para>&a.syuu;</para>
+ </listitem>
+
+ <listitem>
<para>&a.gavin;</para>
</listitem>
@@ -92,10 +96,6 @@
</listitem>
<listitem>
- <para>&a.dougb;</para>
- </listitem>
-
- <listitem>
<para>&a.art;</para>
</listitem>
@@ -120,6 +120,10 @@
</listitem>
<listitem>
+ <para>&a.gblach;</para>
+ </listitem>
+
+ <listitem>
<para>&a.mbr;</para>
</listitem>
@@ -172,10 +176,6 @@
</listitem>
<listitem>
- <para>&a.wilko;</para>
- </listitem>
-
- <listitem>
<para>&a.oleg;</para>
</listitem>
@@ -292,6 +292,10 @@
</listitem>
<listitem>
+ <para>&a.carl;</para>
+ </listitem>
+
+ <listitem>
<para>&a.vd;</para>
</listitem>
@@ -452,6 +456,10 @@
</listitem>
<listitem>
+ <para>&a.sjg;</para>
+ </listitem>
+
+ <listitem>
<para>&a.gibbs;</para>
</listitem>
@@ -496,6 +504,10 @@
</listitem>
<listitem>
+ <para>&a.bar;</para>
+ </listitem>
+
+ <listitem>
<para>&a.jmg;</para>
</listitem>
@@ -616,6 +628,10 @@
</listitem>
<listitem>
+ <para>&a.markj;</para>
+ </listitem>
+
+ <listitem>
<para>&a.tj;</para>
</listitem>
@@ -684,6 +700,10 @@
</listitem>
<listitem>
+ <para>&a.koobs;</para>
+ </listitem>
+
+ <listitem>
<para>&a.jkois;</para>
</listitem>
@@ -768,6 +788,10 @@
</listitem>
<listitem>
+ <para>&a.dru;</para>
+ </listitem>
+
+ <listitem>
<para>&a.jlh;</para>
</listitem>
@@ -792,6 +816,10 @@
</listitem>
<listitem>
+ <para>&a.ian;</para>
+ </listitem>
+
+ <listitem>
<para>&a.truckman;</para>
</listitem>
@@ -1008,6 +1036,10 @@
</listitem>
<listitem>
+ <para>&a.dbn;</para>
+ </listitem>
+
+ <listitem>
<para>&a.bland;</para>
</listitem>
@@ -1520,6 +1552,10 @@
</listitem>
<listitem>
+ <para>&a.bryanv;</para>
+ </listitem>
+
+ <listitem>
<para>&a.avilla;</para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml
index 0f42288312..45028ce029 100644
--- a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml
+++ b/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml
@@ -3,6 +3,10 @@
<itemizedlist>
<listitem>
+ <para>&a.attilio; (2012)</para>
+ </listitem>
+
+ <listitem>
<para>&a.wilko; (2006 - 2012)</para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml
index 7ab3b549b0..e11b6ff7f4 100644
--- a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml
+++ b/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml
@@ -3,6 +3,14 @@
<!-- $FreeBSD$ -->
<itemizedlist>
<listitem>
+ <para>Doug Barton (2000 - 2012)</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.wilko; (2000 - 2012)</para>
+ </listitem>
+
+ <listitem>
<para>&a.murray; (2000 - 2012)</para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml
index 418f3e058e..f9cb424f6c 100644
--- a/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml
+++ b/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml
@@ -3,6 +3,10 @@
<itemizedlist>
<listitem>
+ <para>&a.pav; (2006 - 2012)</para>
+ </listitem>
+
+ <listitem>
<para>&a.flz; (2008 - 2012)</para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/freebsd-update-server/article.xml b/en_US.ISO8859-1/articles/freebsd-update-server/article.xml
index 0d6fdac872..7f1aff1ba7 100644
--- a/en_US.ISO8859-1/articles/freebsd-update-server/article.xml
+++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.xml
@@ -20,7 +20,7 @@
<year>2009</year>
<year>2010</year>
<year>2011</year>
- <holder role="mailto:jhelfman@experts-exchange.com">Jason Helfman</holder>
+ <holder role="mailto:jgh@FreeBSD.org">Jason Helfman</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
@@ -49,9 +49,7 @@
<sect1 id="acknowledgments">
<title>Acknowledgments</title>
- <para>This article was originally published at <ulink
- url="http://www.experts-exchange.com/OS/Unix/BSD/FreeBSD/A_1941-Build-Your-Own-FreeBSD-Update-Server.html">Experts Exchange</ulink>,
- and subsequently printed at <ulink
+ <para>This article was subsequently printed at <ulink
url="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD
Magazine</ulink>.</para>
</sect1>
diff --git a/en_US.ISO8859-1/articles/geom-class/article.xml b/en_US.ISO8859-1/articles/geom-class/article.xml
index 97f7d87c21..bb33aaaf8d 100644
--- a/en_US.ISO8859-1/articles/geom-class/article.xml
+++ b/en_US.ISO8859-1/articles/geom-class/article.xml
@@ -89,7 +89,7 @@
<listitem><para>The &man.style.9; man page &mdash; for documentation on
the coding-style conventions which must be followed for any code
- which is to be committed to the FreeBSD CVS tree.</para></listitem>
+ which is to be committed to the FreeBSD Subversion tree.</para></listitem>
</itemizedlist>
diff --git a/en_US.ISO8859-1/articles/hubs/article.xml b/en_US.ISO8859-1/articles/hubs/article.xml
index c3bcf45556..c523a24e29 100644
--- a/en_US.ISO8859-1/articles/hubs/article.xml
+++ b/en_US.ISO8859-1/articles/hubs/article.xml
@@ -122,13 +122,10 @@
also affected by the types of services you want to offer.
Plain FTP or HTTP services may not require a huge
amount of resources. Watch out if you provide
- CVSup, rsync or even AnonCVS. This can have a huge
- impact on CPU and memory requirements. Especially
- rsync is considered a memory hog, and CVSup does
- indeed consume some CPU. For AnonCVS it might
- be a nice idea to set up a memory resident file system (MFS) of at least
- 300 MB, so you need to take this into account
- for your memory requirements. The following
+ rsync. This can have a huge
+ impact on CPU and memory requirements as it is
+ considered a memory hog.
+ The following
are just examples to give you a very rough hint.
</para>
<para>
diff --git a/en_US.ISO8859-1/articles/linux-users/article.xml b/en_US.ISO8859-1/articles/linux-users/article.xml
index ad9e71e091..d5a00d5dd6 100644
--- a/en_US.ISO8859-1/articles/linux-users/article.xml
+++ b/en_US.ISO8859-1/articles/linux-users/article.xml
@@ -404,7 +404,7 @@ ifconfig_em0="DHCP"</programlisting>
<para>Updating from source is the most involved update method, but offers
the greatest amount of flexibility. The process involves synchronizing a
local copy of the FreeBSD source code with the &os;
- <application>CVS</application> (Concurrent Versioning System) servers.
+ <application>Subversion</application> servers.
Once the local source code is up to date you can build new versions of
the kernel and userland. For more information on source updates see
<ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/updating-upgrading.html">the chapter on updating</ulink>
diff --git a/en_US.ISO8859-1/articles/mailing-list-faq/Makefile b/en_US.ISO8859-1/articles/mailing-list-faq/Makefile
index 6412bc5980..53a873470a 100644
--- a/en_US.ISO8859-1/articles/mailing-list-faq/Makefile
+++ b/en_US.ISO8859-1/articles/mailing-list-faq/Makefile
@@ -13,11 +13,11 @@ INSTALL_ONLY_COMPRESSED?=
WITH_ARTICLE_TOC?=YES
#
-# SRCS lists the individual SGML files that make up the document. Changes
+# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
-# SGML content
+# XML content
SRCS= article.xml
URL_RELPREFIX?= ../../../..
diff --git a/en_US.ISO8859-1/articles/portbuild/article.xml b/en_US.ISO8859-1/articles/portbuild/article.xml
index 5c26bca917..03443e1e95 100644
--- a/en_US.ISO8859-1/articles/portbuild/article.xml
+++ b/en_US.ISO8859-1/articles/portbuild/article.xml
@@ -21,6 +21,7 @@
<year>2010</year>
<year>2011</year>
<year>2012</year>
+ <year>2013</year>
<holder role="mailto:portmgr@FreeBSD.org">The &os; Ports
Management Team</holder>
</copyright>
@@ -47,95 +48,113 @@
<ulink url="http://pointyhat.FreeBSD.org"></ulink>.</para>
<para>This article documents the internal workings of the
- cluster.</para>
+ cluster.</para>
<note>
<para>Many of the details in this article will be of interest only to
- those on the <ulink url="&url.base;/portmgr">Ports Management</ulink>
- team.</para>
+ those on the <ulink url="&url.base;/portmgr/">Ports Management</ulink>
+ team.</para>
</note>
<sect2 id="codebase">
<title>The codebase</title>
- <para>Most of the package building magic occurs under the
- <filename>/var/portbuild</filename> directory. Unless
- otherwise specified, all paths will be relative to
- this location. <replaceable>${arch}</replaceable> will
- be used to specify one of the package architectures
- (amd64, &i386;, ia64, powerpc, and &sparc64;), and
- <replaceable>${branch}</replaceable> will be used
- to specify the build branch (7, 7-exp, 8, 8-exp, 9, 9-exp, 10, 10-exp).
- </para>
+ <para>Most of the package building magic occurs under the
+ <filename>/var/portbuild</filename> directory. Unless
+ otherwise specified, all paths will be relative to
+ this location. <replaceable>${arch}</replaceable> will
+ be used to specify one of the package architectures
+ (e.g., amd64, arm, &i386;, ia64, powerpc, &sparc64;), and
+ <replaceable>${branch}</replaceable> will be used
+ to specify the build branch (e.g., 7, 7-exp, 8, 8-exp, 9, 9-exp, 10, 10-exp).
+ The set of branches that <username>portmgr</username> currently
+ supports is the same as those that the &os;
+ <ulink url="http://www.freebsd.org/security/index.html#supported-branches">security team</ulink>
+ supports.
+ </para>
- <note>
- <para>Packages are no longer built for Releases 4, 5, or 6, nor
- for the alpha architecture.</para>
- </note>
+ <note>
+ <para>Packages are no longer built for branches 4, 5, or 6, nor
+ for the alpha architecture.</para>
+ </note>
- <para>The scripts that control all of this live in
- <filename class="directory">/var/portbuild/scripts/</filename>.
- These are the checked-out copies from the Subversion repository
- <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/">
- <filename class="directory">base/projects/portbuild/scripts/</filename>
- </ulink>.</para>
+ <para>The scripts that control all of this live in
+ <filename role="directory">/var/portbuild/scripts/</filename>.
+ These are the checked-out copies from the Subversion repository at
+ <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/">
+ <filename role="directory">base/projects/portbuild/scripts/</filename>
+ </ulink>.</para>
- <para>Typically, incremental builds are done that use previous
- packages as dependencies; this takes less time, and puts less
- load on the mirrors. Full builds are usually only done:</para>
+ <para>Typically, incremental builds are done that use previous
+ packages as dependencies; this takes less time, and puts less
+ load on the mirrors. Full builds are usually only done:</para>
- <itemizedlist>
- <listitem><para>right after release time, for the
- <literal>-STABLE</literal> branches</para></listitem>
+ <itemizedlist>
+ <listitem>
+ <para>right after release time, for the
+ <literal>-STABLE</literal> branches</para>
+ </listitem>
- <listitem><para>periodically to test changes to
- <literal>-CURRENT</literal>
- </para></listitem>
+ <listitem>
+ <para>periodically to test changes to
+ <literal>-CURRENT</literal></para>
+ </listitem>
- <listitem><para>for experimental builds</para></listitem>
- </itemizedlist>
+ <listitem>
+ <para>for experimental (<literal>"exp-"</literal>) builds</para>
+ </listitem>
+ </itemizedlist>
+ <para>Packages from experimental builds are not uploaded.</para>
</sect2>
<sect2 id="codebase-notes">
<title>Notes on the codebase</title>
<para>Until mid-2010, the scripts were completely specific to
- <hostid>pointyhat</hostid> as the head (dispatch) node. During
+ <hostid>pointyhat.FreeBSD.org</hostid> as the head (dispatch) node. During
the summer of 2010, a significant rewrite was done in order to allow
for other hosts to be head nodes. Among the changes were:</para>
<itemizedlist>
- <listitem><para>removal of the hard-coding of the string
- <literal>pointyhat</literal></para></listitem>
-
- <listitem><para>factoring out all configuration constants (which
- were previously scattered throughout the code) into configuration
- files (see <link linkend="new-head-node">below</link>)
- </para></listitem>
+ <listitem>
+ <para>removal of the hard-coding of the string
+ <literal>pointyhat</literal></para>
+ </listitem>
- <listitem><para>appending the hostname to the directories
- specified by <literal>buildid</literal> (this will allow
- directories to be unambigious when copied between machines.)
- </para></listitem>
+ <listitem>
+ <para>factoring out all configuration constants (which
+ were previously scattered throughout the code) into configuration
+ files (see <link linkend="new-head-node">below</link>)</para>
+ </listitem>
- <listitem><para>making the scripts more robust in terms of setting
- up directories and symlinks</para></listitem>
+ <listitem>
+ <para>appending the hostname to the directories
+ specified by <literal>buildid</literal> (this will allow
+ directories to be unambigious when copied between machines.)</para>
+ </listitem>
- <listitem><para>where necessary, changing certain script invocations
- to make all the above easier</para></listitem>
+ <listitem>
+ <para>making the scripts more robust in terms of setting
+ up directories and symlinks</para>
+ </listitem>
+ <listitem>
+ <para>where necessary, changing certain script invocations
+ to make all the above easier</para>
+ </listitem>
</itemizedlist>
<para>This document was originally written before these changes
were made. Where things such as script invocations have changed,
- they are denoted as <literal>new codebase:</literal> as opposed
+ they were denoted as <literal>new codebase:</literal> as opposed
to <literal>old codebase:</literal>.</para>
<note>
- <para>As of December 2010, <hostid>pointyhat</hostid> is still
- running on the old codebase, until the new codebase is considered
- rock-solid.</para>
+ <para>Up until November 2012, <hostid>pointyhat</hostid> had still
+ been running the old codebase. That installation has now been
+ permanently offlined. Therefore, all the instructions having
+ to do with the old codebase have been removed.</para>
</note>
<note>
@@ -164,10 +183,10 @@
interesting data (ports and src trees, bindist tarballs,
scripts, etc.) to disconnected nodes during the node-setup
phase. Then, the disconnected portbuild directory is
- nullfs-mounted for chroot builds.</para>
+ nullfs-mounted for jail builds.</para>
<para>The
- <username>ports-<replaceable>${arch}</replaceable></username>
+ <username>portbuild</username>
user can &man.ssh.1; to the client nodes to monitor them.
Use <command>sudo</command> and check the
<hostid>portbuild.<replaceable>hostname</replaceable>.conf</hostid>
@@ -176,41 +195,32 @@
<para>The <command>scripts/allgohans</command> script can
be used to run a command on all of the
<replaceable>${arch}</replaceable> clients.</para>
-
- <para>The <command>scripts/checkmachines</command> script
- is used to monitor the load on all the nodes of the
- build cluster, and schedule which nodes build which ports.
- This script is not very robust, and has a tendency to die.
- It is best to start up this script on the build master
- (e.g. <hostid>pointyhat</hostid>)
- after boot time using a &man.while.1; loop.
- </para>
</sect1>
<sect1 id="setup">
- <title>Chroot Build Environment Setup</title>
+ <title>Jail Build Environment Setup</title>
<para>Package builds are performed in a
- <literal>chroot</literal> populated by the
+ <literal>jail</literal> populated by the
<filename>portbuild</filename> script using the
<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename>
file.</para>
- <para>The following command builds a world from the
+ <para>The <command>makeworld</command> command builds a world from the
<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src/</filename>
tree and installs it into
- <replaceable>${worlddir}</replaceable>. The tree will
- be updated first unless <literal>-nocvs</literal> is
- specified.</para>
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename>.
+ The tree will
+ be updated first unless <literal>-novcs</literal> is
+ specified. It should be run as <username>root</username>:</para>
- <screen>/var/portbuild&prompt.root; <userinput>scripts/makeworld <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-nocvs]</userinput></screen>
+ <screen>&prompt.root; <userinput>/var/portbuild/scripts/makeworld <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-novcs]</userinput></screen>
<para>The <filename>bindist.tar</filename> tarball is created from the
previously installed world by the <command>mkbindist</command>
- script. It should be run as <username>root</username> with the following
- command:</para>
+ script. It should be also be run as <username>root</username>:</para>
- <screen>/var/portbuild&prompt.root; <userinput>scripts/mkbindist <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable></userinput></screen>
+ <screen>&prompt.root; <userinput>/var/portbuild/scripts/mkbindist <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable></userinput></screen>
<para>The per-machine tarballs are located in
<filename><replaceable>${arch}</replaceable>/clients</filename>.</para>
@@ -218,24 +228,16 @@
<para>The <filename>bindist.tar</filename> file is extracted
onto each client at client boot time, and at the start of
each pass of the <command>dopackages</command>
- script.
- </para>
+ script.</para>
- <sect2>
- <title>New Codebase</title>
-
- <para>For both commands above, if
- <replaceable>${buildid}</replaceable> is
- <literal>latest</literal>, it may be omitted.
- </para>
- </sect2>
+ <para>For both commands above, if
+ <replaceable>${buildid}</replaceable> is
+ <literal>latest</literal>, it may be omitted.</para>
</sect1>
<sect1 id="customizing">
<title>Customizing Your Build</title>
- <para>(The following only applies to the new codebase.)</para>
-
<para>You can customize your build by providing local versions of
<filename>make.conf</filename> and/or
<filename>src.conf</filename>,
@@ -277,7 +279,7 @@
<para>(For this case, the contents are identical for both server
and client.)</para>
- <screen>RUBY_DEFAULT_VER= 1.9</screen>
+ <programlisting>RUBY_DEFAULT_VER= 1.9</programlisting>
</example>
<example>
@@ -288,8 +290,7 @@
<para>(For this case, the contents are also identical for both
server and client.)</para>
- <screen>
-.if !defined(CC) || ${CC} == "cc"
+ <programlisting>.if !defined(CC) || ${CC} == "cc"
CC=clang
.endif
.if !defined(CXX) || ${CXX} == "c++"
@@ -298,44 +299,44 @@ CXX=clang++
.if !defined(CPP) || ${CPP} == "cpp"
CPP=clang-cpp
.endif
-# Don't die on warnings
+# Do not die on warnings
NO_WERROR=
-WERROR=
-</screen>
+WERROR=</programlisting>
</example>
<example>
<title>Sample <filename>make.conf.server</filename> for
<application>pkgng</application></title>
- <screen>WITH_PKGNG=yes
-PKG_BIN=/usr/local/sbin/pkg</screen>
+ <programlisting>WITH_PKGNG=yes
+PKG_BIN=/usr/local/sbin/pkg</programlisting>
</example>
<example>
<title>Sample <filename>make.conf.client</filename> for
<application>pkgng</application></title>
- <screen>WITH_PKGNG=yes</screen>
+ <programlisting>WITH_PKGNG=yes</programlisting>
</example>
<example>
<title>Sample <filename>src.conf.server</filename>
to test new <application>sort</application> codebase</title>
- <screen>WITH_BSD_SORT=yes</screen>
+ <programlisting>WITH_BSD_SORT=yes</programlisting>
</example>
</sect1>
<sect1 id="starting">
<title>Starting the Build</title>
- <para>Several separate builds for each architecture - branch combination
+ <para>Separate builds for various combinations of architecture and branch
are supported. All data private to a build (ports tree, src tree,
- packages, distfiles, log files, bindist, Makefile, etc) are located under
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable></filename>.
- The last created build can be alternatively referenced under buildid
- <literal>latest</literal>, the one before is called
+ packages, distfiles, log files, bindist, Makefile, etc) are located under the
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/</filename>
+ directory.
+ The most recently created build can be alternatively referenced using buildid
+ <literal>latest</literal>, and the one before using
<literal>previous</literal>.</para>
<para>New builds are cloned from the <literal>latest</literal>, which is
@@ -344,365 +345,260 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
<sect2 id="build-dopackages">
<title><command>dopackages</command> scripts</title>
- <para>The <filename>scripts/dopackages</filename> scripts
- are used to perform the builds.</para>
+ <para>The <filename>scripts/dopackages.wrapper</filename> script
+ is used to perform the builds.</para>
- <sect3>
- <title>Old codebase</title>
- <para>For the old codebase: the
- most useful are:</para>
+ <screen>&prompt.root; <userinput>dopackages.wrapper <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> <option>[-options]</option></userinput></screen>
- <itemizedlist>
- <listitem>
- <para><command>dopackages.7</command> - Perform
- a 7.X build
- </para>
- </listitem>
+ <para>Most often, you will be using <literal>latest</literal> for
+ the value of <replaceable>buildid</replaceable>.</para>
- <listitem>
- <para><command>dopackages.7-exp</command> - Perform
- a 7.X build with experimental patches
- (7-exp branch)
- </para>
- </listitem>
+ <para><literal>[-options]</literal> may be zero or more of the
+ following:</para>
- <listitem>
- <para><command>dopackages.8</command> - Perform
- a 8.X build
- </para>
- </listitem>
-
- <listitem>
- <para><command>dopackages.8-exp</command> - Perform
- a 8.X build with experimental patches
- (8-exp branch)
- </para>
- </listitem>
-
- <listitem>
- <para><command>dopackages.9</command> - Perform
- a 9.X build
- </para>
- </listitem>
-
- <listitem>
- <para><command>dopackages.9-exp</command> - Perform
- a 9.X build with experimental patches
- (9-exp branch)
- </para>
- </listitem>
-
- <listitem>
- <para><command>dopackages.10</command> - Perform
- a 10.X build
- </para>
- </listitem>
-
- <listitem>
- <para><command>dopackages.10-exp</command> - Perform
- a 10.X build with experimental patches
- (10-exp branch)
- </para>
- </listitem>
- </itemizedlist>
-
- <para>These are wrappers around <command>dopackages</command>,
- and are all symlinked to <command>dopackages.wrapper</command>.
- New branch wrapper scripts can be created by symlinking
- <command>dopackages.${branch}</command> to
- <command>dopackages.wrapper</command>. These scripts
- take a number of arguments. For example:</para>
-
- <screen><command>dopackages.7 <replaceable>${arch}</replaceable> <replaceable>${buildid}</replaceable> <literal>[-options]</literal></command></screen>
-
- </sect3>
-
- <sect3>
- <title>New codebase</title>
- <para>The symlinks go away, and you just use
- <command>dopackages.wrapper</command> directly. For example:</para>
-
- <screen><command>dopackages.wrapper <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> <literal>[-options]</literal></command></screen>
-
- </sect3>
-
- <sect3>
- <title>Either codebase</title>
+ <itemizedlist>
+ <listitem>
+ <para><option>-keep</option> - Do not delete this build in the
+ future, when it would be normally deleted as part of the
+ <literal>latest</literal> - <literal>previous</literal> cycle.
+ Do not forget to clean it up manually when you no longer need it.</para>
+ </listitem>
- <para>Most often, you will be using <literal>latest</literal> for
- the value of <replaceable>buildid</replaceable>.</para>
+ <listitem>
+ <para><option>-nofinish</option> - Do not perform
+ post-processing once the build is complete. Useful
+ if you expect that the build will need to be restarted
+ once it finishes. If you use this option, do not forget to cleanup
+ the clients when you do not need the build any more.</para>
+ </listitem>
- <para><literal>[-options]</literal> may be zero or more of the
- following:</para>
+ <listitem>
+ <para><option>-finish</option> - Perform
+ post-processing only.</para>
+ </listitem>
- <itemizedlist>
- <listitem>
- <para><literal>-keep</literal> - Do not delete this build in the
- future, when it would be normally deleted as part of the
- <literal>latest</literal> - <literal>previous</literal> cycle.
- Don't forget to clean it up manually when you no longer need it.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-nocleanup</option> - By default, when the
+ <option>-finish</option> stage of the build is complete, the build
+ data will be deleted from the clients. This option will prevent
+ that.</para>
+ </listitem>
- <listitem>
- <para><literal>-nofinish</literal> - Do not perform
- post-processing once the build is complete. Useful
- if you expect that the build will need to be restarted
- once it finishes. If you use this option, don't forget to cleanup
- the clients when you don't need the build anymore.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-restart</option> - Restart an interrupted
+ (or non-<literal>finish</literal>ed) build from the
+ beginning. Ports that failed on the previous build will
+ be rebuilt.</para>
+ </listitem>
- <listitem>
- <para><literal>-finish</literal> - Perform
- post-processing only.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-continue</option> - Restart an interrupted
+ (or non-<literal>finish</literal>ed) build. Will not
+ rebuild ports that failed on the previous build.</para>
+ </listitem>
- <listitem>
- <para><literal>-nocleanup</literal> - By default, when the
- <literal>-finish</literal> stage of the build is complete, the build
- data will be deleted from the clients. This option will prevent
- that.</para>
- </listitem>
+ <listitem>
+ <para><option>-incremental</option> - Compare the
+ interesting fields of the new
+ <filename>INDEX</filename> with the previous one,
+ remove packages and log files for the old ports that
+ have changed, and rebuild the rest. This
+ cuts down on build times substantially since
+ unchanged ports do not get rebuilt every time.</para>
+ </listitem>
- <listitem>
- <para><literal>-restart</literal> - Restart an interrupted
- (or non-<literal>finish</literal>ed) build from the
- beginning. Ports that failed on the previous build will
- be rebuilt.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-cdrom</option> - This package build is
+ intended to end up on a CD-ROM, so
+ <makevar>NO_CDROM</makevar> packages and distfiles
+ should be deleted in post-processing.</para>
+ </listitem>
- <listitem>
- <para><literal>-continue</literal> - Restart an interrupted
- (or non-<literal>finish</literal>ed) build. Will not
- rebuild ports that failed on the previous build.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-nobuild</option> - Perform all
+ the preprocessing steps, but do not actually do
+ the package build.</para>
+ </listitem>
- <listitem>
- <para><literal>-incremental</literal> - Compare the
- interesting fields of the new
- <literal>INDEX</literal> with the previous one,
- remove packages and log files for the old ports that
- have changed, and rebuild the rest. This
- cuts down on build times substantially since
- unchanged ports do not get rebuilt every time.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-noindex</option> - Do not rebuild
+ <filename>INDEX</filename> during preprocessing.</para>
+ </listitem>
- <listitem>
- <para><literal>-cdrom</literal> - This package build is
- intended to end up on a CD-ROM, so
- <literal>NO_CDROM</literal> packages and distfiles
- should be deleted in post-processing.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-noduds</option> - Do not rebuild the
+ <filename>duds</filename> file (ports that are never
+ built, e.g., those marked <literal>IGNORE</literal>,
+ <makevar>NO_PACKAGE</makevar>, etc.) during
+ preprocessing.</para>
+ </listitem>
- <listitem>
- <para><literal>-nobuild</literal> - Perform all
- the preprocessing steps, but do not actually do
- the package build.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-nochecksubdirs</option> - Do not check the
+ <makevar>SUBDIRS</makevar> for ports that are not connected
+ to the build.</para>
+ </listitem>
- <listitem>
- <para><literal>-noindex</literal> - Do not rebuild
- <filename>INDEX</filename> during preprocessing.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-trybroken</option> - Try to build
+ <makevar>BROKEN</makevar> ports (off by default
+ because the amd64/&i386; clusters are fast enough now
+ that when doing incremental builds, more time
+ was spent rebuilding things that were going to
+ fail anyway. Conversely, the other clusters
+ are slow enough that it would be a waste of time
+ to try and build <makevar>BROKEN</makevar> ports).</para>
- <listitem>
- <para><literal>-noduds</literal> - Do not rebuild the
- <filename>duds</filename> file (ports that are never
- built, e.g. those marked <literal>IGNORE</literal>,
- <literal>NO_PACKAGE</literal>, etc.) during
- preprocessing.
- </para>
- </listitem>
+ <note>
+ <para>With <option>-trybroken</option>, you probably
+ also want to use <option>-fetch-original</option>
+ and
+ <option>-unlimited-errors</option>.</para>
+ </note>
+ </listitem>
- <listitem>
- <para><literal>-nochecksubdirs</literal> - Do not check the
- <makevar>SUBDIRS</makevar> for ports that are not connected
- to the build. (New codebase only).
- </para>
- </listitem>
+ <listitem>
+ <para><option>-nosrc</option> - Do not update the
+ <filename>src</filename> tree from the ZFS snapshot, keep the tree from
+ previous build instead.</para>
+ </listitem>
- <listitem>
- <para><literal>-trybroken</literal> - Try to build
- <literal>BROKEN</literal> ports (off by default
- because the amd64/&i386; clusters are fast enough now
- that when doing incremental builds, more time
- was spent rebuilding things that were going to
- fail anyway. Conversely, the other clusters
- are slow enough that it would be a waste of time
- to try and build <literal>BROKEN</literal> ports).
- </para>
- <note>
- <para>With <literal>-trybroken</literal>, you probably
- also want to use <literal>-fetch-original</literal>
- (and, on the new codebase,
- <literal>-unlimited-errors</literal>).</para>
- </note>
- </listitem>
+ <listitem>
+ <para><option>-srcvcs</option> - Do not update the
+ <filename>src</filename> tree from the ZFS snapshot, update it with
+ a fresh checkout instead.</para>
+ </listitem>
- <listitem>
- <para><literal>-nosrc</literal> - Do not update the
- <literal>src</literal> tree from the ZFS snapshot, keep the tree from
- previous build instead.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-noports</option> - Do not update the
+ <filename>ports</filename> tree from the ZFS snapshot, keep the tree from
+ previous build instead.</para>
+ </listitem>
- <listitem>
- <para><literal>-srccvs</literal> - Do not update the
- <literal>src</literal> tree from the ZFS snapshot, update it with
- <literal>cvs update</literal> instead.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-portsvcs</option> - Do not update the
+ <filename>ports</filename> tree from the ZFS snapshot, update it with
+ a fresh checkout instead.</para>
+ </listitem>
- <listitem>
- <para><literal>-noports</literal> - Do not update the
- <literal>ports</literal> tree from the ZFS snapshot, keep the tree from
- previous build instead.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-norestr</option> - Do not attempt to build
+ <makevar>RESTRICTED</makevar> ports.</para>
+ </listitem>
- <listitem>
- <para><literal>-portscvs</literal> - Do not update the
- <literal>ports</literal> tree from the ZFS snapshot, update it with
- <literal>cvs update</literal> instead.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-noplistcheck</option> - Do not make it fatal for
+ ports to leave behind files after deinstallation.</para>
+ </listitem>
- <listitem>
- <para><literal>-norestr</literal> - Do not attempt to build
- <literal>RESTRICTED</literal> ports.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-nodistfiles</option> - Do not collect distfiles
+ that pass <command>make checksum</command> for later
+ uploading to <hostid>ftp-master</hostid>.</para>
+ </listitem>
- <listitem>
- <para><literal>-noplistcheck</literal> - Do not make it fatal for
- ports to leave behind files after deinstallation.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-fetch-original</option> - Fetch the
+ distfile from the original <makevar>MASTER_SITES</makevar>
+ rather than any cache such as on <hostid>ftp-master</hostid>.</para>
+ </listitem>
- <listitem>
- <para><literal>-nodistfiles</literal> - Do not collect distfiles
- that pass <command>make checksum</command> for later
- uploading to <hostid>ftp-master</hostid>.
- </para>
- </listitem>
+ <listitem>
+ <para><option>-unlimited-errors</option>
+ - defeat the "qmanager threshhold" check for runaway
+ builds. You want this primarily when doing a
+ <option>-restart</option> of a build that you expect to mostly
+ fail, or perhaps a <option>-trybroken</option> run. By default,
+ the threshhold check is done.</para>
+ </listitem>
+ </itemizedlist>
- <listitem>
- <para><literal>-fetch-original</literal> - Fetch the
- distfile from the original <literal>MASTER_SITES</literal>
- rather than <hostid>ftp-master</hostid>.
- </para>
- </listitem>
+ <para>Unless you specify <option>-restart</option>,
+ <option>-continue</option>, or <option>-finish</option>,
+ the symlinks for the existing builds will be rotated. i.e,
+ the existing symlink for <filename>previous</filename> will
+ be deleted; the most recent build will have its symlink changed
+ to <filename>previous/</filename>; and a new build will be
+ created and symlinked into <filename>latest/</filename>.</para>
- <listitem>
- <para><literal>-unlimited-errors</literal> (new codebase
- only) - defeat the "qmanager threshhold" check for runaway
- builds. You want this primarily when doing a
- <literal>-restart</literal> of a build that you expect to mostly
- fail, or perhaps a <literal>-trybroken</literal> run. By default,
- the threshhold check is done.</para>
- </listitem>
- </itemizedlist>
+ <para>If the last build finished cleanly you do not need to delete
+ anything. If it was interrupted, or you selected
+ <option>-nocleanup</option>, you need to clean up clients by running</para>
- <para>Unless you specify <literal>-restart</literal>,
- <literal>-continue</literal>, or <literal>-finish</literal>,
- the symlinks for the existing builds will be rotated. i.e,
- the existing symlink for <filename>previous</filename> will
- be deleted; the most recent build will have its symlink changed
- to <filename>previous/</filename>; and a new build will be
- created and symlinked into <filename>latest/</filename>.
- </para>
+ <screen>&prompt.user; <userinput>build cleanup <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> -full</userinput></screen>
- <para>If the last build finished cleanly you do not need to delete
- anything. If it was interrupted, or you selected
- <literal>-nocleanup</literal>, you need to clean up clients by running
- </para>
+ <para>When a new build is created, the directories <filename>errors/</filename>,
+ <filename>logs/</filename>, <filename>packages/</filename>, and so
+ forth, are cleaned by the scripts. If you are short of space,
+ you can also clean out <filename>ports/distfiles/</filename>.
+ Leave the <filename>latest/</filename> directory alone; it is
+ a symlink for the webserver.</para>
- <para><command>build cleanup <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> -full</command></para>
+ <note>
+ <para><literal>dosetupnodes</literal> is supposed to be run from
+ the <literal>dopackages</literal> script in the
+ <option>-restart</option> case, but it can be a good idea to
+ run it by hand and then verify that the clients all have the
+ expected job load. Sometimes,
+ <filename>dosetupnode</filename> cannot clean up a build and you
+ need to do it by hand. (This is a bug.)</para>
+ </note>
- <para><filename>errors/</filename>,
- <filename>logs/</filename>, <filename>packages/</filename>, and so
- forth, are cleaned by the scripts. If you are short of space,
- you can also clean out <filename>ports/distfiles/</filename>.
- Leave the <filename>latest/</filename> directory alone; it is
- a symlink for the webserver.</para>
+ <para>Make sure the <replaceable>${arch}</replaceable> build
+ is run as the <username>portbuild</username> user
+ or it will complain loudly.</para>
- <note>
- <para><literal>dosetupnodes</literal> is supposed to be run from
- the <literal>dopackages</literal> script in the
- <literal>-restart</literal> case, but it can be a good idea to
- run it by hand and then verify that the clients all have the
- expected job load. Sometimes,
- <literal>dosetupnode</literal> cannot clean up a build and you
- need to do it by hand. (This is a bug.)</para>
- </note>
+ <note>
+ <para>The actual package build itself occurs in two
+ identical phases. The reason for this is that sometimes
+ transient problems (e.g., NFS failures, FTP sites being
+ unreachable, etc.) may halt a build. Doing things
+ in two phases is a workaround for these types of
+ problems.</para>
+ </note>
- <para>Make sure the <replaceable>${arch}</replaceable> build
- is run as the ports-<replaceable>${arch}</replaceable> user
- or it will complain loudly.</para>
-
- <note><para>The actual package build itself occurs in two
- identical phases. The reason for this is that sometimes
- transient problems (e.g. NFS failures, FTP sites being
- unreachable, etc.) may halt a build. Doing things
- in two phases is a workaround for these types of
- problems.</para></note>
-
- <para>Be careful that <filename>ports/Makefile</filename>
- does not specify any empty subdirectories. This is especially
- important if you are doing an -exp build. If the build
- process encounters an empty subdirectory, both package build
- phases will stop short, and an error similar to the following
- will be written to
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/make.[0|1]</filename>:
- </para>
+ <para>Be careful that <filename>ports/Makefile</filename>
+ does not specify any empty subdirectories. This is especially
+ important if you are doing an -exp build. If the build
+ process encounters an empty subdirectory, both package build
+ phases will stop short, and an error similar to the following
+ will be written to
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename>:</para>
- <screen><literal>don't know how to make dns-all(continuing)</literal></screen>
+ <screen>don't know how to make dns-all(continuing)</screen>
- <para>To correct this problem, simply comment out or remove
- the <literal>SUBDIR</literal> entries that point to empty
- subdirectories. After doing this, you can restart the build
- by running the proper <command>dopackages</command> command
- with the <literal>-restart</literal> option.
- </para>
+ <para>To correct this problem, simply comment out or remove
+ the <makevar>SUBDIR</makevar> entries that point to empty
+ subdirectories. After doing this, you can restart the build
+ by running the proper <command>dopackages</command> command
+ with the <option>-restart</option> option.</para>
- <note>
- <para>This problem also appears if you create a new category
- <filename>Makefile</filename> with no <makevar>SUBDIR</makevar>s
- in it. This is probably a bug.</para>
- </note>
+ <note>
+ <para>This problem also appears if you create a new category
+ <filename>Makefile</filename> with no <makevar>SUBDIR</makevar>s
+ in it. This is probably a bug.</para>
+ </note>
- <example>
- <title>Update the i386-7 tree and do a complete build</title>
+ <example>
+ <title>Update the i386-7 tree and do a complete build</title>
- <para><command>dopackages.7 i386 -nosrc -norestr -nofinish</command></para>
- <para><command>dopackages.wrapper i386 7 -nosrc -norestr -nofinish</command></para>
- </example>
+ <screen>&prompt.user; <userinput>dopackages.wrapper i386 7 -nosrc -norestr -nofinish</userinput></screen>
+ </example>
- <example>
- <title>Restart an interrupted amd64-8 build without updating</title>
+ <example>
+ <title>Restart an interrupted amd64-8 build without updating</title>
- <para><command>dopackages.8 amd64 -nosrc -noports -norestr -continue -noindex -noduds -nofinish</command></para>
- <para><command>dopackages.wrapper amd64 8 -nosrc -noports -norestr -continue -noindex -noduds -nofinish</command></para>
- </example>
+ <screen>&prompt.user; <userinput>dopackages.wrapper amd64 8 -nosrc -noports -norestr -continue -noindex -noduds -nofinish</userinput></screen>
+ </example>
- <example>
- <title>Post-process a completed sparc64-7 tree</title>
+ <example>
+ <title>Post-process a completed sparc64-7 tree</title>
- <para><command>dopackages.7 sparc64 -finish</command></para>
- <para><command>dopackages.wrapper sparc64 7 -finish</command></para>
- </example>
+ <screen>&prompt.user; <userinput>dopackages.wrapper sparc64 7 -finish</userinput></screen>
+ </example>
- <para>Hint: it us usually best to run the <command>dopackages</command>
- command inside of <command>screen(1)</command>.</para>
- </sect3>
+ <para>Hint: it is usually best to run the <command>dopackages</command>
+ command inside of <command>screen(1)</command>.</para>
</sect2>
<sect2 id="build-command">
@@ -719,10 +615,7 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
<replaceable>branch</replaceable>
[<replaceable>newid</replaceable>]</literal> - Creates
<replaceable>newid</replaceable> (or a datestamp if not specified).
- Only needed when bringing up a new branch or a new architecture.
- (TODO: document whether newid must be specified as
- <literal>latest</literal> in the new codebase.)
- </para>
+ Only needed when bringing up a new branch or a new architecture.</para>
</listitem>
<listitem>
@@ -730,30 +623,26 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
<replaceable>branch</replaceable> <replaceable>oldid</replaceable>
[<replaceable>newid</replaceable>]</literal> - Clones
<replaceable>oldid</replaceable> to
- <replaceable>newid</replaceable> (or a datestamp if not specified).
- </para>
+ <replaceable>newid</replaceable> (or a datestamp if not specified).</para>
</listitem>
<listitem>
<para><literal>build srcupdate <replaceable>arch</replaceable>
<replaceable>branch</replaceable>
<replaceable>buildid</replaceable></literal> - Replaces the src
- tree with a new ZFS snapshot. Don't forget to use
+ tree with a new ZFS snapshot. Do not forget to use
<literal>-nosrc</literal> flag to <command>dopackages</command>
- later!
- </para>
+ later!</para>
</listitem>
<listitem>
<para><literal>build portsupdate <replaceable>arch</replaceable>
<replaceable>branch</replaceable>
<replaceable>buildid</replaceable></literal> - Replaces the ports
- tree with a new ZFS snapshot. Don't forget to use
+ tree with a new ZFS snapshot. Do not forget to use
<literal>-noports</literal> flag to <command>dopackages</command>
- later!
- </para>
+ later!</para>
</listitem>
-
</itemizedlist>
</sect2>
@@ -764,7 +653,7 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
package set. This can be accomplished with the following
invocation:</para>
- <para><command><replaceable>path</replaceable>/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2.tbz</replaceable></command></para>
+ <screen>&prompt.root; <command><replaceable>path</replaceable>/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2.tbz</replaceable></command></screen>
</sect2>
</sect1>
@@ -777,88 +666,72 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
<orderedlist>
<listitem>
- <para>An update of the current <literal>ports</literal>
- tree from the ZFS snapshot [*]
- </para>
+ <para>An update of the current <filename>ports</filename>
+ tree from the ZFS snapshot<footnote id="footnote-status1">
+ <para>Status of these steps can be found in
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</filename>
+ as well as on stderr of the tty running the
+ <command>dopackages</command> command.</para></footnote></para>
</listitem>
<listitem>
<para>An update of the running branch's
- <literal>src</literal> tree from the ZFS snapshot [*]
- </para>
+ <filename>src</filename> tree from the ZFS snapshot<footnoteref linkend='footnote-status1'></footnoteref></para>
</listitem>
<listitem>
<para>Checks which ports do not have a
- <literal>SUBDIR</literal> entry in their respective
- category's <filename>Makefile</filename> [*]
- </para>
+ <makevar>SUBDIR</makevar> entry in their respective
+ category's <filename>Makefile</filename><footnoteref linkend='footnote-status1'></footnoteref></para>
</listitem>
<listitem>
<para>Creates the <filename>duds</filename> file, which
- is a list of ports not to build [*] [+]
- </para>
+ is a list of ports not to build<footnoteref linkend='footnote-status1'></footnoteref><footnote id="footnote-buildstop">
+ <para>If any of these steps fail, the build will stop
+ cold in its tracks.</para></footnote></para>
</listitem>
<listitem>
<para>Generates a fresh <filename>INDEX</filename>
- file [*] [+]
- </para>
+ file<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
</listitem>
<listitem>
<para>Sets up the nodes that will be used in the
- build [*] [+]
- </para>
+ build<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
</listitem>
<listitem>
- <para>Builds a list of restricted ports [*] [+]</para>
+ <para>Builds a list of restricted ports<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
</listitem>
<listitem>
- <para>Builds packages (phase 1) [++]</para>
+ <para>Builds packages (phase 1)<footnote id="footnote-status2"><para>Status of these steps can be found in
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename>.
+ Individual ports will write
+ their build logs to
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/logs/</filename>
+ and their error logs to
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/errors/</filename>.
+ </para></footnote></para>
</listitem>
<listitem>
- <para>Performs another node setup [+]</para>
+ <para>Performs another node setup<footnoteref linkend='footnote-status1'></footnoteref></para>
</listitem>
<listitem>
- <para>Builds packages (phase 2) [++]</para>
+ <para>Builds packages (phase 2)<footnoteref linkend='footnote-status2'></footnoteref></para>
</listitem>
</orderedlist>
-
- <para>[*] Status of these steps can be found in
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</filename>
- as well as on stderr of the tty running the
- <command>dopackages</command> command.</para>
-
- <para>[+] If any of these steps fail, the build will stop
- cold in its tracks.</para>
-
- <para>[++] Status of these steps can be found in
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/make</filename> (old codebase) or
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename> (new codebase).
- Individual ports will write
- their build logs to
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/logs</filename>
- and their error logs to
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/errors</filename>.
- </para>
-
- <para>Formerly the docs tree was also checked out, however, it has
- been found to be unnecessary.
- </para>
</sect1>
<sect1 id="build-maintenance">
<title>Build Maintenance</title>
<para>There are several cases where you will need to manually clean
- up a build:
- </para>
+ up a build:</para>
<orderedlist>
<listitem>
@@ -866,7 +739,7 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
</listitem>
<listitem>
- <para><hostid>pointyhat</hostid> has been rebooted while
+ <para>The head node has been rebooted while
a build was running.</para>
</listitem>
@@ -874,99 +747,98 @@ PKG_BIN=/usr/local/sbin/pkg</screen>
<para><filename>qmanager</filename> has crashed and
has been restarted.</para>
</listitem>
- </orderedlist>
-
- <sect2 id="interrupting">
- <title>Interrupting a Build</title>
-
- <para>Manually interrupting a build is a bit messy. First you need to
- identify the tty in which it's running (either record the output
- of &man.tty.1; when you start the build, or use <command>ps x</command>
- to identify it. You need to make sure that nothing else important
- is running in this tty, e.g. <command>ps -t p1</command> or whatever.
- If there is not, you can just kill off the whole term easily with
- <command>pkill -t pts/1</command>; otherwise issue a
- <command>kill -HUP</command> in there by, for example,
-<command>ps -t pts/1 -o pid= | xargs kill -HUP</command>. Replace
- <replaceable>p1</replaceable> by whatever the tty is, of course.</para>
+ </orderedlist>
- <para>The
- package builds dispatched by <command>make</command> to
- the client machines will clean themselves up after a
- few minutes (check with <command>ps x</command> until they
- all go away).</para>
+ <sect2 id="interrupting">
+ <title>Interrupting a Build</title>
+
+ <para>Manually interrupting a build is a bit messy. First you need to
+ identify the tty in which it's running (either record the output
+ of &man.tty.1; when you start the build, or use <command>ps x</command>
+ to identify it. You need to make sure that nothing else important
+ is running in this tty, e.g., <userinput>ps -t p1</userinput> or whatever.
+ If there is not, you can just kill off the whole term easily with
+ <userinput>pkill -t pts/1</userinput>; otherwise issue a
+ <userinput>kill -HUP</userinput> in there by, for example,
+ <userinput>ps -t pts/1 -o pid= | xargs kill -HUP</userinput>. Replace
+ <replaceable>p1</replaceable> by whatever the tty is, of course.</para>
+
+ <para>The
+ package builds dispatched by <command>make</command> to
+ the client machines will clean themselves up after a
+ few minutes (check with <command>ps x</command> until they
+ all go away).</para>
+
+ <para>If you do not kill &man.make.1;, then it will spawn more jobs.
+ If you do not kill <command>dopackages</command>, then it will restart
+ the entire build. If you do not kill the <command>pdispatch</command>
+ processes, they'll keep going (or respawn) until they've built their
+ package.</para>
+ </sect2>
- <para>If you do not kill &man.make.1;, then it will spawn more jobs.
- If you do not kill <command>dopackages</command>, then it will restart
- the entire build. If you do not kill the <command>pdispatch</command>
- processes, they'll keep going (or respawn) until they've built their
- package.</para>
+ <sect2 id="cleanup">
+ <title>Cleaning up a Build</title>
- </sect2>
+ <para>To free up resources, you will need to clean up client machines by
+ running <command>build cleanup</command> command. For example:</para>
- <sect2 id="cleanup">
- <title>Cleaning up a Build</title>
+ <screen>&prompt.user; <userinput>/var/portbuild/scripts/build cleanup i386 8-exp 20080714120411 -full</userinput></screen>
- <para>To free up resources, you will need to clean up client machines by
- running <command>build cleanup</command> command. For example:
- <screen>&prompt.user; <userinput>/var/portbuild/scripts/build cleanup i386 8-exp 20080714120411 -full</userinput></screen></para>
+ <para>If you forget to do this, then the old build
+ <literal>jail</literal>s will not be cleaned up for 24 hours, and no
+ new jobs will be dispatched in their place since
+ <hostid>pointyhat</hostid> thinks the job slot is still occupied.</para>
- <para>If you forget to do this, then the old build
- <literal>chroot</literal>s will not be cleaned up for 24 hours, and no
- new jobs will be dispatched in their place since
- <hostid>pointyhat</hostid> thinks the job slot is still occupied.</para>
+ <para>To check, <userinput>cat ~/loads/*</userinput> to display the
+ status of client machines; the first column is the number of jobs
+ it thinks is running, and this should be roughly concordant
+ with the load average. <literal>loads</literal> is refreshed
+ every 2 minutes. If you do <userinput>ps x | grep pdispatch</userinput>
+ and it is less than the number of jobs that <literal>loads</literal>
+ thinks are in use, you are in trouble.</para>
- <para>To check, <command>cat ~/loads/*</command> to display the
- status of client machines; the first column is the number of jobs
- it thinks is running, and this should be roughly concordant
- with the load average. <literal>loads</literal> is refreshed
- every 2 minutes. If you do <command>ps x | grep pdispatch</command>
- and it's less than the number of jobs that <literal>loads</literal>
- thinks are in use, you're in trouble.</para>
+ <para>You may have problem with the <command>umount</command>
+ commands hanging. If so, you are going to have to use the
+ <command>allgohans</command> script to run an &man.ssh.1;
+ command across all clients for that buildenv. For example:</para>
- <para>You may have problem with the <command>umount</command>
- commands hanging. If so, you are going to have to use the
- <command>allgohans</command> script to run an &man.ssh.1;
- command across all clients for that buildenv. For example:
-<screen>ssh -l root gohan24 df</screen>
+ <screen>&prompt.user; ssh gohan24 df</screen>
- will get you a df, and
+ <para>will get you a df, and</para>
-<screen>allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports"
-allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/src"</screen>
+ <screen>&prompt.user; allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports"
+&prompt.user; allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/src"</screen>
- are supposed to get rid of the hanging mounts. You will have to
- keep doing them since there can be multiple mounts.</para>
+ <para>are supposed to get rid of the hanging mounts. You will have to
+ keep doing them since there can be multiple mounts.</para>
- <note>
- <para>Ignore the following:
+ <note>
+ <para>Ignore the following:</para>
-<screen>umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: statfs: No such file or directory
+ <screen>umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: statfs: No such file or directory
umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: unknown file system
umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
/x/tmp/8-exp/chroot/53837/compat/linux/proc: not a file system root directory</screen>
- The former 2 mean that that client did not have those mounted;
- the latter 2 are a bug.</para>
-
- <para>You may also see messages about <literal>procfs</literal>.</para>
- </note>
+ <para>The former two mean that the client did not have those mounted;
+ the latter two are a bug.</para>
- <para>After you have done all the above, remove the
- <filename><replaceable>${arch}</replaceable>/lock</filename>
- file before trying to restart the build. If you do not,
- <filename>dopackages</filename> will simply exit.
- </para>
+ <para>You may also see messages about <literal>procfs</literal>.</para>
+ </note>
- <para>If you have to do a ports tree update before
- restarting, you may have to rebuild either <filename>duds</filename>,
- <filename>INDEX</filename>, or both.</para>
+ <para>After you have done all the above, remove the
+ <filename><replaceable>${arch}</replaceable>/lock</filename>
+ file before trying to restart the build. If you do not,
+ <filename>dopackages</filename> will simply exit.</para>
+ <para>If you have to do a ports tree update before
+ restarting, you may have to rebuild either <filename>duds</filename>,
+ <filename>INDEX</filename>, or both.</para>
</sect2>
<sect2 id="build-command-2">
<title>Maintaining builds with the <command>build</command>
- command</title>
+ command</title>
<para>Here are the rest of the options for the <command>build</command>
command:</para>
@@ -975,26 +847,16 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<listitem>
<para><literal>build destroy <replaceable>arch</replaceable>
<replaceable>branch</replaceable></literal> - Destroy the
- build id.
- </para>
+ build id.</para>
</listitem>
<listitem>
<para><literal>build list <replaceable>arch</replaceable>
<replaceable>branch</replaceable></literal> - Shows the current set
- of build ids.
- </para>
- </listitem>
-
- <listitem>
- <para><literal>build upload <replaceable>arch</replaceable>
- <replaceable>branch</replaceable></literal> - not yet
- implemented.</para>
+ of build ids.</para>
</listitem>
</itemizedlist>
-
</sect2>
-
</sect1>
<sect1 id="monitoring">
@@ -1003,14 +865,14 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<para>You can use <command>qclient</command> command to monitor the status
of build nodes, and to list the currently scheduled jobs:</para>
- <para><command>python <replaceable>path</replaceable>/qmanager/qclient jobs</command></para>
- <para><command>python <replaceable>path</replaceable>/qmanager/qclient status</command></para>
+ <screen>&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient jobs</userinput>
+&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient status</userinput></screen>
<para>The
- <command>scripts/stats <replaceable>${branch}</replaceable></command>
+ <userinput>scripts/stats <replaceable>${branch}</replaceable></userinput>
command shows the number of packages already built.</para>
- <para>Running <command>cat /var/portbuild/*/loads/*</command>
+ <para>Running <userinput>cat /var/portbuild/*/loads/*</userinput>
shows the client loads and number of concurrent builds in
progress. The files that have been recently updated are the clients
that are online; the others are the offline clients.</para>
@@ -1025,18 +887,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
idle node.</para>
</note>
- <para>Running <command>tail -f <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</command>
+ <para>Running <userinput>tail -f <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</userinput>
shows the overall build progress.</para>
<para>If a port build is failing, and it is not immediately obvious
from the log as to why, you can preserve the
- <literal>WRKDIR</literal> for further analysis. To do this,
+ <makevar>WRKDIR</makevar> for further analysis. To do this,
touch a file called <filename>.keep</filename> in the port's
directory. The next time the cluster tries to build this port,
- it will tar, compress, and copy the <literal>WRKDIR</literal>
+ it will tar, compress, and copy the <makevar>WRKDIR</makevar>
to
- <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/wrkdirs</filename>.
- </para>
+ <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/wrkdirs/</filename>.</para>
<para>If you find that the system is looping trying to build the
same package over and over again, you may be able to fix the
@@ -1049,19 +910,18 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<para>Keep an eye on &man.df.1; output. If the
<filename>/var/portbuild</filename> file system becomes full
- then <trademark>Bad Things</trademark> happen.
- </para>
+ then <trademark>Bad Things</trademark> happen.</para>
- <para>The status of all current builds is generated twice an hour
- and posted to
+ <para>The status of all current builds is generated periodically
+ into the <filename>packagestats.html</filename> file, e.g.,
<ulink url="http://pointyhat.FreeBSD.org/errorlogs/packagestats.html"></ulink>.
For each <literal>buildenv</literal>, the following is displayed:</para>
<itemizedlist>
<listitem>
- <para><literal>cvs date</literal> is the contents of
- <filename>cvsdone</filename>. This is why we recommend that you
- update <filename>cvsdone</filename> for <literal>-exp</literal>
+ <para><literal>updated</literal> is the contents of
+ <filename>.updated</filename>. This is why we recommend that you
+ update <filename>.updated</filename> for <literal>-exp</literal>
runs (see below).</para>
</listitem>
@@ -1070,7 +930,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
</listitem>
<listitem>
- <para>number of lines in <literal>INDEX</literal></para>
+ <para>number of lines in <filename>INDEX</filename></para>
</listitem>
<listitem>
@@ -1092,7 +952,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<listitem>
<para><literal>missing</literal> shows the difference between
<filename>INDEX</filename> and the other columns. If you have
- restarted a run after a <command>cvs update</command>, there
+ restarted a run after a ports tree update, there
will likely be duplicates in the packages and error columns,
and this column will be meaningless. (The script is naive).</para>
</listitem>
@@ -1116,7 +976,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
You can easily bounce the new ones to maintainers.</para>
<para>After a port appears broken on every build combination
- multiple times, it is time to mark it <literal>BROKEN</literal>.
+ multiple times, it is time to mark it <makevar>BROKEN</makevar>.
Two weeks' notification for the maintainers seems fair.</para>
<note>
@@ -1133,20 +993,20 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<para>When building packages for a release, it may be
necessary to manually update the <literal>ports</literal>
- and <literal>src</literal> trees to the release tag and use
- <literal>-nocvs</literal> and
- <literal>-noportscvs</literal>.</para>
+ and <filename>src</filename> trees to the release tag and use
+ <option>-novcs</option> and
+ <option>-noportsvcs</option>.</para>
<para>To build package sets intended for use on a CD-ROM,
- use the <literal>-cdrom</literal> option to
+ use the <option>-cdrom</option> option to
<command>dopackages</command>.</para>
<para>If the disk space is not available on the cluster, use
- <literal>-nodistfiles</literal> to avoid collecting distfiles.</para>
+ <option>-nodistfiles</option> to avoid collecting distfiles.</para>
<para>After the initial build completes, restart the build
with
- <literal>-restart -fetch-original</literal>
+ <option>-restart -fetch-original</option>
to collect updated distfiles as well. Then, once the
build is post-processed, take an inventory of the list
of files fetched:</para>
@@ -1177,8 +1037,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
and inform them of the release package location.</para>
<para>Remember to coordinate with the &a.re; about the timing
- and status of the release builds.
- </para>
+ and status of the release builds.</para>
</sect1>
<sect1 id="uploading">
@@ -1187,11 +1046,11 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<para>Once a build has completed, packages and/or distfiles
can be transferred to <hostid>ftp-master</hostid> for
propagation to the FTP mirror network. If the build was
- run with <literal>-nofinish</literal>, then make sure to
+ run with <option>-nofinish</option>, then make sure to
follow up with
<command>dopackages -finish</command> to post-process the
- packages (removes <literal>RESTRICTED</literal> and
- <literal>NO_CDROM</literal> packages where appropriate,
+ packages (removes <makevar>RESTRICTED</makevar> and
+ <makevar>NO_CDROM</makevar> packages where appropriate,
prunes packages not listed in <filename>INDEX</filename>,
removes from <filename>INDEX</filename>
references to packages not built, and generates a
@@ -1199,7 +1058,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
summary); and distfiles (moves them from the temporary
<filename>distfiles/.pbtmp</filename> directory into
<filename>distfiles/</filename> and removes
- <literal>RESTRICTED</literal> and <literal>NO_CDROM</literal>
+ <makevar>RESTRICTED</makevar> and <makevar>NO_CDROM</makevar>
distfiles).</para>
<para>It is usually a good idea to run the
@@ -1212,41 +1071,42 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
the final package set for a release.</para>
<para>The package subdirectories are named by whether they are for
- <literal>release</literal>, <literal>stable</literal>, or
- <literal>current</literal>. Examples:</para>
+ <filename>release</filename>, <filename>stable</filename>, or
+ <filename>current</filename>. Examples:</para>
<itemizedlist>
<listitem>
- <para><literal>packages-7.2-release</literal></para>
+ <para><filename>packages-7.2-release</filename></para>
</listitem>
<listitem>
- <para><literal>packages-7-stable</literal></para>
+ <para><filename>packages-7-stable</filename></para>
</listitem>
<listitem>
- <para><literal>packages-8-stable</literal></para>
+ <para><filename>packages-8-stable</filename></para>
</listitem>
<listitem>
- <para><literal>packages-9-stable</literal></para>
+ <para><filename>packages-9-stable</filename></para>
</listitem>
<listitem>
- <para><literal>packages-10-current</literal></para>
+ <para><filename>packages-10-current</filename></para>
</listitem>
</itemizedlist>
- <note><para>Some of the directories on
- <hostid>ftp-master</hostid> are, in fact, symlinks. Examples:</para>
+ <note>
+ <para>Some of the directories on
+ <hostid>ftp-master</hostid> are, in fact, symlinks. Examples:</para>
<itemizedlist>
<listitem>
- <para><literal>packages-stable</literal></para>
+ <para><filename>packages-stable</filename></para>
</listitem>
<listitem>
- <para><literal>packages-current</literal></para>
+ <para><filename>packages-current</filename></para>
</listitem>
</itemizedlist>
@@ -1256,7 +1116,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
one of the symlinks that points to it.</para>
</note>
- <para>If you are doing a completely new package set (e.g. for
+ <para>If you are doing a completely new package set (e.g., for
a new release), copy packages to the staging area on
<hostid>ftp-master</hostid> with something like the following:</para>
@@ -1267,19 +1127,18 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
the package set was transferred successfully, remove the
package set that the new package set is to replace (in
<filename>~/w/ports/<replaceable>${arch}</replaceable></filename>),
- and move the new set into place. (<literal>w/</literal> is
+ and move the new set into place. (<filename>w/</filename> is
merely a shortcut.)</para>
<para>For incremental builds, packages should be uploaded
using <command>rsync</command> so we do not put too much
strain on the mirrors.</para>
- <para><emphasis>ALWAYS</emphasis> use <literal>-n</literal>
+ <para><emphasis>ALWAYS</emphasis> use <option>-n</option>
first with <command>rsync</command> and check the output
to make sure it is sane. If it looks good, re-run the
- <command>rsync</command> without the <literal>-n</literal>
- option.
- </para>
+ <command>rsync</command> without the <option>-n</option>
+ option.</para>
<para>Example <command>rsync</command> command for incremental
package upload:</para>
@@ -1308,12 +1167,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<para>In general, an experimental patches build is run the same
way as any other build, except that you should first update the
ports tree to the latest version and then apply your patches.
- To do the former, you can use the following:
+ To do the former, you can use the following:</para>
+
+ <note>
+ <para>The following example is obsolete</para>
+ </note>
+
+ <screen>&prompt.user; <userinput>cvs -R update -dP > update.out</userinput>
+&prompt.user; <userinput>date > .updated</userinput></screen>
- <screen>&prompt.user; <userinput>cvs -R update -dP > update.out</userinput>
-&prompt.user; <userinput>date > cvsdone</userinput></screen>
- This will most closely simulate what the <literal>dopackages</literal>
- script does. (While <filename>cvsdone</filename> is merely
+ <para>This will most closely simulate what the <literal>dopackages</literal>
+ script does. (While <filename>.updated</filename> is merely
informative, it can be a help.)</para>
<para>You will need to edit <filename>update.out</filename> to look
@@ -1327,7 +1191,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
tested.</para>
<para>Since the machine is shared, someone else may delete your
- changes by mistake, so keep a copy of them in e.g. your home
+ changes by mistake, so keep a copy of them in e.g., your home
directory on <hostid>freefall</hostid>. Do not use
<filename>tmp/</filename>; since <hostid>pointyhat</hostid>
itself runs some version of <literal>-CURRENT</literal>, you
@@ -1359,10 +1223,12 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
&prompt.user; <userinput>cd /var/portbuild/i386/8/errors</userinput>
&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/8-errs</userinput></screen>
- <note><para>If it has been a long time since one of the builds
+ <note>
+ <para>If it has been a long time since one of the builds
finished, the logs may have been automatically compressed with
- bzip2. In that case, you must use <literal>sort | sed
- 's,\.bz2,,g'</literal> instead.</para></note>
+ bzip2. In that case, you must use <userinput>sort | sed
+ 's,\.bz2,,g'</userinput> instead.</para>
+ </note>
<screen>&prompt.user; <userinput>comm -3 /tmp/8-errs /tmp/8-exp-errs | less</userinput></screen>
@@ -1376,20 +1242,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<listitem>
<para>Port was fixed since the control build was run, or was
upgraded to a newer version that is also broken (thus the
- newer version should appear in the second column)
- </para>
+ newer version should appear in the second column)</para>
</listitem>
<listitem>
<para>Port is fixed by the patches in the experimental patches
- build
- </para>
+ build</para>
</listitem>
<listitem>
<para>Port did not build under the experimental patches build
- due to a dependency failure
- </para>
+ due to a dependency failure</para>
</listitem>
</itemizedlist>
@@ -1397,42 +1260,49 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
include:</para>
<itemizedlist>
- <listitem>
- <para>Port was broken by the experimental patches [1]</para>
+ <listitem id="broken-by-exp-patches" xreflabel="broken by experimental patches">
+ <para>Port was broken by the experimental patches</para>
</listitem>
- <listitem>
+ <listitem id="broken-by-upgrading" xreflabel="broken by upgrading">
<para>Port was upgraded since the control build and has become
- broken [2]
- </para>
+ broken</para>
</listitem>
<listitem>
- <para>Port was broken due to a transient error (e.g. FTP site
- down, package client error, etc.)
- </para>
+ <para>Port was broken due to a transient error (e.g., FTP site
+ down, package client error, etc.)</para>
</listitem>
</itemizedlist>
<para>Both columns should be investigated and the reason for the
- errors understood before committing the experimental patches set.
- To differentiate between [1] and [2] above, you can do a rebuild
- of the affected packages under the control branch:</para>
+ errors understood before committing the experimental patches
+ set. To differentiate between <xref
+ linkend="broken-by-exp-patches"></xref> and <xref
+ linkend="broken-by-upgrading"></xref> above, you can do a
+ rebuild of the affected packages under the control
+ branch:</para>
<screen>&prompt.user; <userinput>cd /var/portbuild/i386/8/ports</userinput></screen>
- <note><para>Be sure to <literal>cvs update</literal> this tree to the same date as
- the experimental patches tree.</para></note>
+ <note>
+ <para>The following example is obsolete</para>
+ </note>
+
+ <note>
+ <para>Be sure to <userinput>cvs update</userinput> this tree to the same date as
+ the experimental patches tree.</para>
+ </note>
<!-- XXX MCL fix -->
<para>The following command will set up the control branch for
the partial build (old codebase):</para>
- <screen>&prompt.user; <userinput>/var/portbuild/scripts/dopackages.8 -noportscvs -nobuild -nocvs -nofinish</userinput></screen>
+ <screen>&prompt.user; <userinput>/var/portbuild/scripts/dopackages.8 -noportsvcs -nobuild -novcs -nofinish</userinput></screen>
<!-- XXX MCL obsolete -->
<para>The builds must be performed from the
- <literal>packages/All</literal> directory. This directory should
+ <filename>packages/All</filename> directory. This directory should
initially be empty except for the Makefile symlink. If this
symlink does not exist, it must be created:</para>
@@ -1440,15 +1310,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
&prompt.user; <userinput>ln -sf ../../Makefile .</userinput>
&prompt.user; <userinput>make -k -j&lt;#&gt; &lt;list of packages to build&gt;</userinput></screen>
- <note><para>&lt;#&gt; is the concurrency of the build to
- attempt. It is usually the sum of the weights listed in
- <filename>/var/portbuild/i386/mlist</filename> unless you have a
- reason to run a heavier or lighter build.</para>
-
- <para>The list of packages to build should be a list of package
- names (including versions) as they appear in
- <filename>INDEX</filename>. The <literal>PKGSUFFIX</literal>
- (i.e. .tgz or .tbz) is optional.</para></note>
+ <note>
+ <para>&lt;#&gt; is the concurrency of the build to
+ attempt. It is usually the sum of the weights listed in
+ <filename>/var/portbuild/i386/mlist</filename> unless you have a
+ reason to run a heavier or lighter build.</para>
+
+ <para>The list of packages to build should be a list of package
+ names (including versions) as they appear in
+ <filename>INDEX</filename>. The <makevar>PKGSUFFIX</makevar>
+ (i.e., <filename>.tgz</filename> or <filename>.tbz</filename>) is optional.</para>
+ </note>
<para>This will build only those packages listed as well as all
of their dependencies.</para>
@@ -1472,8 +1344,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<title>How to configure a new package building node</title>
<para>Before following these steps, please coordinate with
- <literal>portmgr</literal>.
- </para>
+ <literal>portmgr</literal>.</para>
<note>
<para>Due to some generous donations, <literal>portmgr</literal> is
@@ -1523,7 +1394,6 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
has been shown to saturate a cable modem line.</para>
</listitem>
</itemizedlist>
-
</sect2>
<sect2 id="node-preparation">
@@ -1561,16 +1431,19 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<step>
<para>Pick a directory to hold ports configuration and
- <command>chroot</command> subdirectories. It may be
+ <filename>chroot</filename> subdirectories. It may be
best to put it this on its own partition. (Example:
<filename>/usr2/</filename>.)</para>
+ <note>
+ <para>The filename <filename>chroot</filename> is a
+ historical remnant.</para>
+ </note>
</step>
</procedure>
-
</sect2>
<sect2 id="node-src">
- <title>Configuring <literal>src</literal></title>
+ <title>Configuring <filename>src</filename></title>
<procedure>
<step>
@@ -1584,7 +1457,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
</step>
<step>
- <para>If you are using <literal>pxeboot</literal>: create a
+ <para>If you are using <filename>pxeboot</filename>: create a
directory to contain the install bits. You will probably
want to use a subdirectory of <filename>/pxeroot</filename>,
e.g.,
@@ -1594,8 +1467,8 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<step>
<para>If you are cross-building, export
- <literal>TARGET_ARCH</literal>=<replaceable>${arch}</replaceable>.
- </para>
+ <makevar>TARGET_ARCH</makevar>=<replaceable>${arch}</replaceable>.</para>
+
<note>
<para>The procedure for cross-building ports is not yet
defined.</para>
@@ -1604,17 +1477,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
<step>
<para>Generate a kernel config file. Include
- <literal>GENERIC</literal> (or, if you are using more than
- 3.5G on &i386;, <literal>PAE</literal>).
- </para>
- <para>
- Required options:<screen>
-options NULLFS
-options TMPFS</screen>
- </para>
- <para>
- Suggested options:<screen>
-options GEOM_CONCAT
+ <filename>GENERIC</filename> (or, if you are using more than
+ 3.5G on &i386;, <filename>PAE</filename>).</para>
+
+ <para>Required options:</para>
+
+ <programlisting>options NULLFS
+options TMPFS</programlisting>
+
+ <para>Suggested options:</para>
+
+ <programlisting>options GEOM_CONCAT
options GEOM_STRIPE
options SHMMAXPGS=65536
options SEMMNI=40
@@ -1622,41 +1495,41 @@ options SEMMNS=240
options SEMUME=40
options SEMMNU=120
-options ALT_BREAK_TO_DEBUGGER</screen>
- </para>
+options ALT_BREAK_TO_DEBUGGER</programlisting>
- <para>For <literal>PAE</literal>, it is not currently possible
+ <para>For <filename>PAE</filename>, it is not currently possible
to load modules. Therefore, if you are running an architecture
- that supports Linux emulation, you will need to add:<screen>
-options COMPAT_LINUX
-options LINPROCFS</screen>
- </para>
-
- <para>Also for <literal>PAE</literal>, as of 20110912 you need
- the following. This needs to be investigated:<screen>
-nooption NFSD # New Network Filesystem Server
+ that supports Linux emulation, you will need to add:</para>
+
+ <programlisting>options COMPAT_LINUX
+options LINPROCFS</programlisting>
+
+ <para>Also for <filename>PAE</filename>, as of 20110912 you need
+ the following. This needs to be investigated:</para>
+
+ <programlisting>nooption NFSD # New Network Filesystem Server
options NFSCLIENT # Network Filesystem Client
-options NFSSERVER # Network Filesystem Server</screen>
- </para>
+options NFSSERVER # Network Filesystem Server</programlisting>
</step>
<step>
- <para>As root, do the usual build steps, e.g.:<screen>
-<userinput>make -j4 buildworld</userinput>
-<userinput>make buildkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
-<userinput>make installkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
-<userinput>make installworld</userinput></screen>
- The install steps use <makevar>DESTDIR</makevar>.
- </para>
+ <para>As root, do the usual build steps, e.g.:</para>
+
+ <screen>&prompt.root; <userinput>make -j4 buildworld</userinput>
+&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
+&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
+&prompt.root; <userinput>make installworld</userinput></screen>
+
+ <para>The install steps use <makevar>DESTDIR</makevar>.</para>
</step>
<step>
<para>Customize files in <filename>etc/</filename>.
Whether you do this on the client itself, or another
machine, will depend on whether you are using
- <literal>pxeboot</literal>.</para>
+ <filename>pxeboot</filename>.</para>
- <para>If you are using <literal>pxeboot</literal>: create
+ <para>If you are using <filename>pxeboot</filename>: create
a subdirectory of
<filename><replaceable>${DESTDIR}</replaceable></filename>
called <filename>conf/</filename>. Create one subdirectory
@@ -1677,20 +1550,20 @@ options NFSSERVER # Network Filesystem Server</screen>
<itemizedlist>
<listitem>
<para>Create a
- <literal>ports-<replaceable>${arch}</replaceable></literal>
- user and group. Add it to the <literal>wheel</literal>
- group. It can have the <literal>'*'</literal> password.</para>
+ <literal>portbuild</literal>
+ user and group. It can have the <literal>'*'</literal> password.</para>
<para>Create
- <filename>/home/ports-<replaceable>${arch}/.ssh/</replaceable></filename>
+ <filename>/home/portbuild/.ssh/</filename>
and populate <filename>authorized_keys</filename>. </para>
</listitem>
<listitem>
- <para>Also add the following users:<screen>
-squid:*:100:100::0:0:User &amp;:/usr/local/squid:/bin/sh
-ganglia:*:102:102::0:0:User &amp;:/usr/local/ganglia:/bin/sh</screen>
- </para>
+ <para>Also add the following users:</para>
+
+ <programlisting>squid:*:100:100::0:0:User &amp;:/usr/local/squid:/bin/sh
+ganglia:*:102:102::0:0:User &amp;:/usr/local/ganglia:/bin/sh</programlisting>
+
<para>Add them to <filename>etc/group</filename> as well.</para>
</listitem>
@@ -1700,45 +1573,45 @@ ganglia:*:102:102::0:0:User &amp;:/usr/local/ganglia:/bin/sh</screen>
</listitem>
<listitem>
- <para>In <filename>etc/crontab</filename>: add
- <screen>* * * * * root /var/portbuild/scripts/client-metrics</screen>
- </para>
+ <para>In <filename>etc/crontab</filename>: add</para>
+
+ <programlisting>* * * * * root /var/portbuild/scripts/client-metrics</programlisting>
</listitem>
<listitem>
<para>Create the appropriate
<filename>etc/fstab</filename>. (If you have multiple,
- different, machines, you will need to put those in
- the override directories.)</para>
+ different, machines, you will need to put those in
+ the override directories.)</para>
</listitem>
<listitem>
- <para>In <filename>etc/inetd.conf</filename>: add
- <screen>infoseek stream tcp nowait nobody /var/portbuild/scripts/reportload</screen>
- </para>
+ <para>In <filename>etc/inetd.conf</filename>: add</para>
+
+ <programlisting>infoseek stream tcp nowait nobody /var/portbuild/scripts/reportload</programlisting>
</listitem>
<listitem>
- <para>We run the cluster on UTC:
- <screen>cp /usr/share/zoneinfo/Etc/UTC etc/localtime</screen>
- </para>
+ <para>You should run the cluster on UTC. If you have not set the clock
+ to UTC:</para>
+
+ <programlisting>&prompt.root; cp -p /usr/share/zoneinfo/Etc/UTC etc/localtime</programlisting>
</listitem>
<listitem>
<para>Create the appropriate
<filename>etc/rc.conf</filename>. (If you are using
- <literal>pxeboot</literal>, and have multiple,
- different, machines, you will need to put those in
- the override directories.)</para>
+ <literal>pxeboot</literal>, and have multiple,
+ different, machines, you will need to put those in
+ the override directories.)</para>
- <para>Recommended entries for physical nodes:<screen>
-hostname="<replaceable>${hostname}</replaceable>"
+ <para>Recommended entries for physical nodes:</para>
+
+ <programlisting>hostname="<replaceable>${hostname}</replaceable>"
inetd_enable="YES"
linux_enable="YES"
nfs_client_enable="YES"
ntpd_enable="YES"
-ntpdate_enable="YES"
-ntpdate_flags="north-america.pool.ntp.org"
sendmail_enable="NONE"
sshd_enable="YES"
sshd_program="/usr/local/sbin/sshd"
@@ -1746,18 +1619,16 @@ sshd_program="/usr/local/sbin/sshd"
gmond_enable="YES"
squid_enable="YES"
squid_chdir="<filename>/<replaceable>usr2</replaceable>/squid/logs</filename>"
-squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"
-</screen>
- </para>
+squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"</programlisting>
- <para>Required entries for VMWare-based nodes:<screen>
-vmware_guest_vmmemctl_enable="YES"
-vmware_guest_guestd_enable="YES"
-</screen>
- </para>
+ <para>Required entries for VMWare-based nodes:</para>
+
+ <programlisting>vmware_guest_vmmemctl_enable="YES"
+vmware_guest_guestd_enable="YES"</programlisting>
+
+ <para>Recommended entries for VMWare-based nodes:</para>
- <para>Recommended entries for VMWare-based nodes:<screen>
-hostname=""
+ <programlisting>hostname=""
ifconfig_em0="DHCP"
fsck_y_enable="YES"
@@ -1771,9 +1642,7 @@ sshd_program="/usr/local/sbin/sshd"
gmond_enable="YES"
squid_enable="YES"
squid_chdir="<filename>/<replaceable>usr2</replaceable>/squid/logs</filename>"
-squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"
-</screen>
- </para>
+squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"</programlisting>
<para>&man.ntpd.8; should <emphasis>not</emphasis>
be enabled for VMWare instances.</para>
@@ -1785,7 +1654,6 @@ squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</
persistent (which should save instantiation time.)
Work is still ongoing.
</para>
-
</listitem>
<listitem>
@@ -1794,8 +1662,9 @@ squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</
</listitem>
<listitem>
- <para>Modify <filename>etc/sysctl.conf</filename>:<screen>
-9a10,30
+ <para>Modify <filename>etc/sysctl.conf</filename>:</para>
+
+ <screen>9a10,30
> kern.corefile=<filename>/<replaceable>usr2</replaceable>/%N.core</filename>
> kern.sugid_coredump=1
> #debug.witness_ddb=0
@@ -1805,7 +1674,7 @@ squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</
> kern.maxfiles=40000
> kern.maxfilesperproc=30000
>
-> # Since the NFS root is static we don't need to check frequently for file changes
+> # Since the NFS root is static we do not need to check frequently for file changes
> # This saves >75% of NFS traffic
> vfs.nfs.access_cache_timeout=300
> debug.debugger_on_panic=1
@@ -1817,7 +1686,6 @@ squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</
> security.jail.enforce_statfs=1
>
> vfs.lookup_shared=1</screen>
- </para>
</listitem>
<listitem>
@@ -1826,36 +1694,32 @@ squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</
<literal>@pointyhat.freebsd.org</literal>.</para>
</listitem>
</itemizedlist>
-
</step>
-
</procedure>
-
</sect2>
<sect2 id="node-ports">
- <title>Configuring <literal>ports</literal></title>
+ <title>Configuring <filename>ports</filename></title>
<procedure>
<step>
- <para>Install the following ports:<screen>
-net/rsync
+ <para>Install the following ports:</para>
+
+ <programlisting>net/rsync
security/openssh-portable (with HPN on)
security/sudo
sysutils/ganglia-monitor-core (with GMETAD off)
-www/squid (with SQUID_AUFS on)</screen>
- </para>
+www/squid (with SQUID_AUFS on)</programlisting>
<para>There is a WIP to create a meta-port, but it is not yet
- complete.
- </para>
+ complete.</para>
</step>
<step>
<para>Customize files in <filename>usr/local/etc/</filename>.
Whether you do this on the client itself, or another
machine, will depend on whether you are using
- <literal>pxeboot</literal>.</para>
+ <filename>pxeboot</filename>.</para>
<note>
<para>The trick of using <filename>conf</filename>
@@ -1870,8 +1734,9 @@ www/squid (with SQUID_AUFS on)</screen>
<itemizedlist>
<listitem>
<para>Modify
- <filename>usr/local/etc/gmond.conf</filename>:<screen>
-21,22c21,22
+ <filename>usr/local/etc/gmond.conf</filename>:</para>
+
+ <screen>21,22c21,22
&lt; name = "unspecified"
&lt; owner = "unspecified"
---
@@ -1881,7 +1746,6 @@ www/squid (with SQUID_AUFS on)</screen>
&lt; url = "unspecified"
---
&gt; url = "http://pointyhat.freebsd.org"</screen>
- </para>
<!-- XXX MCL adapted literally from krismail; I do not understand it -->
<para>If there are machines from more than one cluster in the
@@ -1892,10 +1756,11 @@ www/squid (with SQUID_AUFS on)</screen>
<listitem>
<!-- XXX MCL get latest patches from narutos -->
<para>Create
- <filename>usr/local/etc/rc.d/portbuild.sh</filename>,
- using the appropriate value for
- <literal>scratchdir</literal>:<screen>
-#!/bin/sh
+ <filename>usr/local/etc/rc.d/portbuild.sh</filename>,
+ using the appropriate value for
+ <literal>scratchdir</literal>:</para>
+
+ <programlisting>#!/bin/sh
#
# Configure a package build system post-boot
@@ -1904,7 +1769,7 @@ scratchdir=<filename>/<replaceable>usr2</replaceable></filename>
ln -sf ${scratchdir}/portbuild /var/
# Identify builds ready for use
-cd /var/portbuild/<replaceable>${arch}</replaceable>
+cd /var/portbuild/<replaceable>arch</replaceable>
for i in */builds/*; do
if [ -f ${i}/.ready ]; then
mkdir /tmp/.setup-${i##*/}
@@ -1912,14 +1777,14 @@ for i in */builds/*; do
done
# Flag that we are ready to accept jobs
-touch /tmp/.boot_finished</screen>
- </para>
+touch /tmp/.boot_finished</programlisting>
</listitem>
<listitem>
<para>Modify
- <filename>usr/local/etc/squid/squid.conf</filename>:<screen>
-288,290c288,290
+ <filename>usr/local/etc/squid/squid.conf</filename>:</para>
+
+ <screen>288,290c288,290
&lt; #auth_param basic children 5
&lt; #auth_param basic realm Squid proxy-caching web server
&lt; #auth_param basic credentialsttl 2 hours
@@ -1935,7 +1800,6 @@ touch /tmp/.boot_finished</screen>
&gt; maximum_object_size 400 MB
2828a2838
&gt; negative_ttl 0 minutes</screen>
- </para>
<para>Also, change <filename>usr/local</filename>
to <filename><replaceable>usr2</replaceable></filename> in
@@ -1945,37 +1809,35 @@ touch /tmp/.boot_finished</screen>
<literal>cache_store_log</literal>,
<literal>pid_filename</literal>,
<literal>netdb_filename</literal>,
- <literal>coredump_dir</literal>.
- </para>
+ <literal>coredump_dir</literal>.</para>
<para>Finally, change the <literal>cache_dir</literal>
storage scheme from <literal>ufs</literal> to
- <literal>aufs</literal> (offers better performance).
- </para>
+ <literal>aufs</literal> (offers better performance).</para>
</listitem>
<listitem>
<para>Configure <command>ssh</command>: copy
- <filename>/etc/ssh</filename> to
- <filename>/usr/local/etc/ssh</filename> and add
+ <filename>etc/ssh</filename> to
+ <filename>usr/local/etc/ssh</filename> and add
<literal>NoneEnabled yes</literal> to
<filename>sshd_config</filename>.</para>
</listitem>
<listitem>
- <para>Modify
- <filename>usr/local/etc/sudoers</filename>:<screen>
-38a39,42
->
-> # local changes for package building
-> %wheel ALL=(ALL) ALL
-> ports-<replaceable>${arch}</replaceable> ALL=(ALL) NOPASSWD: ALL</screen>
- </para>
+ <note>
+ <para>This step is under review.</para>
+ </note>
+
+ <para>Create
+ <filename>usr/local/etc/sudoers/sudoers.d/portbuild</filename>:</para>
+
+ <programlisting># local changes for package building
+portbuild ALL=(ALL) NOPASSWD: ALL</programlisting>
</listitem>
</itemizedlist>
</step>
</procedure>
-
</sect2>
<sect2 id="node-configuration">
@@ -1985,21 +1847,20 @@ touch /tmp/.boot_finished</screen>
<step>
<para>Change into the port/package directory you picked
above, e.g.,
- <command>cd <filename>/<replaceable>usr2</replaceable></filename></command>.
- </para>
+ <command>cd <filename>/<replaceable>usr2</replaceable></filename></command>.</para>
</step>
<step>
- <para>As root:<screen>
-<userinput>mkdir portbuild</userinput>
-<userinput>chown ports-<replaceable>${arch}</replaceable>:ports-<replaceable>${arch}</replaceable> portbuild</userinput>
-<userinput>mkdir pkgbuild</userinput>
-<userinput>chown ports-<replaceable>${arch}</replaceable>:ports-<replaceable>${arch}</replaceable> pkgbuild</userinput>
-<userinput>mkdir squid</userinput>
-<userinput>mkdir squid/cache</userinput>
-<userinput>mkdir squid/logs</userinput>
-<userinput>chown -R squid:squid squid</userinput></screen>
- </para>
+ <para>As root:</para>
+
+ <screen>&prompt.root; <userinput>mkdir portbuild</userinput>
+&prompt.root; <userinput>chown portbuild:portbuild portbuild</userinput>
+&prompt.root; <userinput>mkdir pkgbuild</userinput>
+&prompt.root; <userinput>chown portbuild:portbuild pkgbuild</userinput>
+&prompt.root; <userinput>mkdir squid</userinput>
+&prompt.root; <userinput>mkdir squid/cache</userinput>
+&prompt.root; <userinput>mkdir squid/logs</userinput>
+&prompt.root; <userinput>chown -R squid:squid squid</userinput></screen>
</step>
<!-- XXX MCL adapted literally from krismail; I do not understand it -->
@@ -2008,9 +1869,8 @@ touch /tmp/.boot_finished</screen>
between boots then they must either preserve their
<filename>/tmp</filename>, or revalidate their available
builds at boot time (see the script on the <literal>amd64</literal>
- machines). They must also clean up stale chroots from previous
- builds before creating <filename>/tmp/.boot_finished</filename>.
- </para>
+ machines). They must also clean up stale jails from previous
+ builds before creating <filename>/tmp/.boot_finished</filename>.</para>
</step>
<step>
@@ -2019,32 +1879,32 @@ touch /tmp/.boot_finished</screen>
<step>
<para>As root, initialize the <command>squid</command>
- directories:
- <screen><userinput>squid -z</userinput></screen></para>
+ directories:</para>
+
+ <screen><userinput>squid -z</userinput></screen>
</step>
</procedure>
-
</sect2>
<sect2 id="pointyhat-configuration">
- <title>Configuration on <literal>pointyhat</literal></title>
+ <title>Configuration on the server</title>
<para>These steps need to be taken by a <literal>portmgr</literal>
- acting as <literal>ports-<replaceable>${arch}</replaceable></literal>
- on <hostid>pointyhat</hostid>.
- </para>
+ acting as <literal>portbuild</literal>
+ on the server.</para>
<procedure>
<step>
<para>If any of the default TCP ports is not available (see
above), you will need to create an <command>ssh</command>
- tunnel for it and include it in the
+ tunnel for them and include its invocation command in
+ <literal>portbuild</literal>'s
<filename>crontab</filename>.</para>
</step>
<step>
- <para>Add an entry to
- <filename>/home/ports-<replaceable>${arch}</replaceable>/.ssh/config</filename>
+ <para>Unless you can use the defaults, add an entry to
+ <filename>/home/portbuild/.ssh/config</filename>
to specify the public IP address, TCP port for
<command>ssh</command>, username, and any other necessary
information.</para>
@@ -2052,34 +1912,36 @@ touch /tmp/.boot_finished</screen>
<step>
<para>Create
-<filename>/var/portbuild/<replaceable>${arch}</replaceable>/clients/bindist-<replaceable>${hostname}</replaceable>.tar</filename>.
- </para>
+ <filename>/var/portbuild/<replaceable>${arch}</replaceable>/clients/bindist-<replaceable>${hostname}</replaceable>.tar</filename>.</para>
<itemizedlist>
<listitem>
<para>Copy one of the existing ones as a template and unpack it
in a temporary directory.</para>
</listitem>
+
<listitem>
<para>Customize <filename>etc/resolv.conf</filename>
- for the local site.</para>
+ for the local site.</para>
</listitem>
+
<listitem>
<para>Customize <filename>etc/make.conf</filename> for
- FTP fetches for the local site. Note: the nulling-out
- of <makevar>MASTER_SITE_BACKUP</makevar> must be common
- to all nodes, but the first entry in
- <makevar>MASTER_SITE_OVERRIDE</makevar> should be the
- nearest local FTP mirror. Example:<screen><command>
-.if defined(FETCH_ORIGINAL)
+ FTP fetches for the local site. Note: the nulling-out
+ of <makevar>MASTER_SITE_BACKUP</makevar> must be common
+ to all nodes, but the first entry in
+ <makevar>MASTER_SITE_OVERRIDE</makevar> should be the
+ nearest local FTP mirror. Example:</para>
+
+ <programlisting>.if defined(FETCH_ORIGINAL)
MASTER_SITE_BACKUP=
.else
MASTER_SITE_OVERRIDE= \
ftp://<replaceable>friendly-local-ftp-mirror</replaceable>/pub/FreeBSD/ports/distfiles/${DIST_SUBDIR}/ \
ftp://${BACKUP_FTP_SITE}/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
-.endif</command></screen>
- </para>
+.endif</programlisting>
</listitem>
+
<listitem>
<para><command>tar</command> it up and move it to the right
location.</para>
@@ -2088,7 +1950,7 @@ MASTER_SITE_OVERRIDE= \
<para>Hint: you will need one of these for each machine;
however, if you have multiple machines at one site, you
- should create a site-specific one (e.g. in
+ should create a site-specific one (e.g., in
<filename>/var/portbuild/conf/clients/</filename>)
and symlink to it.</para>
</step>
@@ -2100,33 +1962,31 @@ MASTER_SITE_OVERRIDE= \
file contains overrides to
<filename>/var/portbuild/<replaceable>${arch}</replaceable>/portbuild.conf</filename>.</para>
- <para>Suggested values:<screen>
-disconnected=1
+ <para>Suggested values:</para>
+
+ <programlisting>disconnected=1
http_proxy="http://localhost:3128/"
squid_dir=<filename>/<replaceable>usr2</replaceable>/squid</filename>
scratchdir=<filename>/<replaceable>usr2</replaceable>/pkgbuild</filename>
-client_user=ports-<replaceable>${arch}</replaceable>
+client_user=portbuild
sudo_cmd="sudo -H"
rsync_gzip=-z
infoseek_host=localhost
-infoseek_port=<replaceable>${tunelled-tcp-port}</replaceable></screen>
- </para>
+infoseek_port=<replaceable>${tunelled-tcp-port}</replaceable></programlisting>
- <para>Possible other values:<screen>
-use_md_swap=1
+ <para>Possible other values:</para>
+
+ <programlisting>use_md_swap=1
md_size=9g
use_zfs=1
scp_cmd="/usr/local/bin/scp"
-ssh_cmd="/usr/local/bin/ssh"
-</screen>
- </para>
+ssh_cmd="/usr/local/bin/ssh"</programlisting>
</step>
</procedure>
<para>These steps need to be taken by a <literal>portmgr</literal>
- acting as <literal>root</literal> on <hostid>pointyhat</hostid>.
- </para>
+ acting as <literal>root</literal> on <hostid>pointyhat</hostid>.</para>
<procedure>
<step>
@@ -2138,43 +1998,41 @@ ssh_cmd="/usr/local/bin/ssh"
<step>
<para>Add an appropriate <literal>data_source</literal> entry to
<filename>/usr/local/etc/gmetad.conf</filename>:</para>
- <para>
- <literal>data_source "<replaceable>arch</replaceable>/<replaceable>location</replaceable> Package Build Cluster" 30 <replaceable>hostname</replaceable></literal>
- </para>
- <para>You will need to restart <filename>gmetad</filename>.
- </para>
+ <programlisting>data_source "<replaceable>arch</replaceable>/<replaceable>location</replaceable> Package Build Cluster" 30 <replaceable>hostname</replaceable></programlisting>
+
+ <para>You will need to restart <filename>gmetad</filename>.</para>
</step>
</procedure>
-
</sect2>
<sect2 id="node-enabling">
<title>Enabling the node</title>
<para>These steps need to be taken by a <literal>portmgr</literal>
- acting as <literal>ports-<replaceable>arch</replaceable></literal>
- on <hostid>pointyhat</hostid>.
- </para>
+ acting as <literal>portbuild</literal>:</para>
<procedure>
<step>
- <para>Ensure that <literal>ssh</literal> is working by executing
- <command>ssh <replaceable>hostname</replaceable></command>.
- </para>
+ <para>Ensure that <literal>ssh</literal> to the client
+ is working by executing
+ <userinput>ssh <replaceable>hostname</replaceable> uname -a</userinput>.
+ The actual command is not important; what is important is to
+ confirm the setup, and also add an entry into
+ <filename>known_hosts</filename>, once you have confirmed the
+ node's identity.</para>
</step>
<step>
- <para>Populate <filename>/var/portbuild/scripts/</filename>
- by something like
- <command>/var/portbuild/scripts/dosetupnode <replaceable>arch</replaceable> <replaceable>major</replaceable> latest <replaceable>hostname</replaceable></command>.
- Verify that you now have files in that directory.
- </para>
+ <para>Populate the client's copy of
+ <filename>/var/portbuild/scripts/</filename> by something like
+ <userinput>/var/portbuild/scripts/dosetupnode <replaceable>arch</replaceable> <replaceable>major</replaceable> latest <replaceable>hostname</replaceable></userinput>.
+ Verify that you now have files in that directory.</para>
</step>
<step>
<para>Test the other TCP ports by executing
- <command>telnet <replaceable>hostname</replaceable> <replaceable>portnumber</replaceable></command>.
+ <userinput>telnet <replaceable>hostname</replaceable> <replaceable>portnumber</replaceable></userinput>.
<literal>414</literal> (or its tunnel) should give you a few lines of status
information including <literal>arch</literal> and
<literal>osversion</literal>; <literal>8649</literal> should
@@ -2184,15 +2042,13 @@ ssh_cmd="/usr/local/bin/ssh"
</procedure>
<para>This step needs to be taken by a <literal>portmgr</literal>
- acting as <literal>root</literal> on <hostid>pointyhat</hostid>.
- </para>
+ acting as <literal>root</literal>:</para>
<procedure>
<step>
- <para>Tell <filename>qmanager</filename> about the node. Example:
- </para>
+ <para>Tell <filename>qmanager</filename> about the node. Example:</para>
- <para><command>python <replaceable>path</replaceable>/qmanager/qclient add
+ <para><userinput>python <replaceable>path</replaceable>/qmanager/qclient add
name=<replaceable>uniquename</replaceable>
arch=<replaceable>arch</replaceable>
osversion=<replaceable>osversion</replaceable>
@@ -2203,7 +2059,19 @@ ssh_cmd="/usr/local/bin/ssh"
primarypool=package
pools="package all" maxjobs=1
acl="ports-<replaceable>arch</replaceable>,deny_all"
- </command></para>
+ </userinput></para>
+ </step>
+ </procedure>
+
+ <para>Finally, again as <literal>portmgr</literal>
+ acting as <literal>portbuild</literal>:</para>
+
+ <procedure>
+ <step>
+ <para>Once you are sure that the client is working, tell
+ <application>pollmachine</application> about it by adding
+ it to
+ <filename>/var/portbuild/<replaceable>${arch}</replaceable>/mlist</filename>.</para>
</step>
</procedure>
</sect2>
@@ -2212,118 +2080,73 @@ ssh_cmd="/usr/local/bin/ssh"
<sect1 id="new-branch">
<title>How to configure a new &os; branch</title>
- <para>When a new branch is created, some work needs to
- be done to specify that the previous branch is no longer
- equivalent to <literal>HEAD</literal>. The following
- instructions apply to the <emphasis>previous</emphasis>
- branch number:</para>
-
- <itemizedlist>
- <listitem>
- <para>(new codebase) Edit <filename>/var/portbuild/conf/server.conf</filename>
- with the following changes:</para>
-
- <itemizedlist>
- <listitem>
- <para>Add <replaceable>new-branch</replaceable> to
- <makevar>SRC_BRANCHES</makevar>.</para>
- </listitem>
-
- <listitem>
- <para>For what was previously head, change
- <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_TAG</makevar> to
- <literal>RELENG_<replaceable>branch</replaceable>_0</literal>.</para>
- </listitem>
-
- <listitem>
- <para>Add
- <makevar>SRC_BRANCH_<replaceable>new-branch</replaceable>_TAG</makevar>
- <literal>=.</literal> (literal period).</para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <sect2 id="new-branch-pre-qmanager">
+ <title>Steps necessary before <application>qmanager</application> is started</title>
- <listitem>
- <para>(new codebase) Run <command>
-/var/portbuild/updatesnap</command> manually.</para>
- </listitem>
+ <para>When a new branch is created, some work needs to
+ be done to specify that the previous branch is no longer
+ equivalent to <literal>HEAD</literal>.</para>
- <listitem>
- <para>(Only for old codebase)
- Create a new <application>zfs</application> filesystem
- for sources:
- <screen>zfs create a/snap/src-<replaceable>branch</replaceable></screen>
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Edit <filename>/var/portbuild/conf/server.conf</filename>
+ with the following changes:</para>
- <listitem>
- <para>(Only necessary for old codebase):
- Checkout a <literal>src</literal> tree in the new filesystem:
- <screen>cvs -Rq -d /r/ncvs co -d src-<replaceable>branch</replaceable>-r RELENG_<replaceable>branch</replaceable></screen>
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Add <replaceable>new-branch</replaceable> to
+ <makevar>SRC_BRANCHES</makevar>.</para>
+ </listitem>
- <listitem>
- <para>(Only necessary for old codebase):
- Edit the master copy of
- <filename>Tools/portbuild/portbuild.conf</filename>.</para>
- </listitem>
+ <listitem>
+ <para>For what was previously head, change
+ <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to
+ <literal>releng/<replaceable>branch</replaceable>.0</literal>
+ (literal zero).</para>
+ </listitem>
- <listitem>
- <para>(Only necessary for old codebase):
- For each arch, edit its copy of the above in
- <filename>/var/portbuild/<replaceable>arch</replaceable>/portbuild.conf</filename>.</para>
- </listitem>
+ <listitem>
+ <para>Add
+ <makevar>SRC_BRANCH_<replaceable>new-branch</replaceable>_SUBDIR</makevar>
+ <literal>=head</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para>(Only necessary for old codebase):
- Edit <filename>/var/portbuild/scripts/buildenv</filename>.</para>
- </listitem>
+ <listitem>
+ <para>Run <command>/var/portbuild/updatesnap</command> manually.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
- <listitem>
- <para>(Only necessary for old codebase):
- Add a link from
- <filename>/var/portbuild/scripts/dopackages</filename> to
- <filename>/var/portbuild/scripts/dopackages.<replaceable>branch</replaceable></filename>.</para>
- </listitem>
+ <sect2 id="new-branch-post-qmanager">
+ <title>Steps necessary after <application>qmanager</application> is started</title>
- <listitem>
- <para>(Only necessary for old codebase):
- Modify <makevar>HEAD_BRANCH</makevar> and
- <makevar>NON_HEAD_BRANCHES</makevar> in
- <filename>/var/portbuild/scripts/updatesnap</filename>.</para>
- </listitem>
+ <note>
+ <para>Again, as
+ <literal>portbuild</literal>:</para>
+ </note>
- <listitem>
- <!-- XXX MCL writeup for new codebase -->
- <para>(Only necessary for old codebase):
- Add the <literal>snap</literal> directory to
- <filename>/var/portbuild/scripts/zexpire</filename>.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>For each branch that will be supported, do the following:</para>
- <listitem>
- <para>(Only necessary for old codebase):
- In the <filename>/var/portbuild/errorlogs/</filename>
- directory, create links for the webserver:<screen>
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/errors <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-full
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/logs <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-full-logs
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/errors <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-latest
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/logs <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-latest-logs
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/packages <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-packages-full
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/packages <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-packages-latest</screen>
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Kick-start the build for the branch with:</para>
- <listitem>
- <para>Kick-start the build for the branch with
- <screen>build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen></para>
- </listitem>
+ <screen>build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen>
+ </listitem>
- <listitem>
- <para><link linkend="setup">Create <filename>bindist.tar</filename>
- </link>.</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><link linkend="setup">Create
+ <filename>bindist.tar</filename></link>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect2>
</sect1>
<sect1 id="old-branch">
@@ -2334,61 +2157,57 @@ ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/build
<itemizedlist>
<listitem>
- <para>(new codebase) Edit <filename>/var/portbuild/conf/server.conf</filename>
+ <para>Edit <filename>/var/portbuild/conf/server.conf</filename>
with the following changes:</para>
- <itemizedlist>
- <listitem>
- <para>Delete <replaceable>old-branch</replaceable> from
- <makevar>SRC_BRANCHES</makevar>.</para>
- </listitem>
- <listitem>
- <para>Delete
- <makevar>SRC_BRANCH_<replaceable>old-branch</replaceable>_TAG</makevar>
- <literal>=<replaceable>whatever</replaceable></literal></para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>Delete <replaceable>old-branch</replaceable> from
+ <makevar>SRC_BRANCHES</makevar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Delete
+ <makevar>SRC_BRANCH_<replaceable>old-branch</replaceable>_SUBDIR</makevar><literal>=</literal>
+ <replaceable>whatever</replaceable></para>
+ </listitem>
+ </itemizedlist>
</listitem>
<listitem>
- <para>(both):
-<command>umount a/snap/src-<replaceable>old-branch</replaceable>/src;
+ <screen>umount a/snap/src-<replaceable>old-branch</replaceable>/src;
umount a/snap/src-<replaceable>old-branch</replaceable>;
-zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></command></para>
+zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
- <para>(both) You will probably find that the following files and
+ <para>You will probably find that the following files and
symlinks in <filename>/var/portbuild/errorlogs/</filename>
can be removed:</para>
- <itemizedlist>
- <listitem>
- <para>Files named
- <filename>*-<replaceable>old_branch</replaceable>-failure.html</filename>
- </para>
- </listitem>
- <listitem>
- <para>Files named
- <filename>buildlogs_*-<replaceable>old_branch</replaceable>-*-logs.txt</filename>
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Files named
+ <filename>*-<replaceable>old_branch</replaceable>-failure.html</filename></para>
+ </listitem>
- <listitem>
- <para>Symlinks named
- <filename>*-<replaceable>old_branch</replaceable>-previous*</filename>
- </para>
- </listitem>
+ <listitem>
+ <para>Files named
+ <filename>buildlogs_*-<replaceable>old_branch</replaceable>-*-logs.txt</filename></para>
+ </listitem>
- <listitem>
- <para>Symlinks named
- <filename>*-<replaceable>old_branch</replaceable>-latest*</filename>
- </para>
- </listitem>
+ <listitem>
+ <para>Symlinks named
+ <filename>*-<replaceable>old_branch</replaceable>-previous*</filename></para>
+ </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Symlinks named
+ <filename>*-<replaceable>old_branch</replaceable>-latest*</filename></para>
+ </listitem>
+ </itemizedlist>
</listitem>
</itemizedlist>
</sect1>
@@ -2404,34 +2223,32 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></command></para>
<para>As releases go End-Of-Life (see
<ulink url="http://www.freebsd.org/security/index.html#supported-branches">chart</ulink>),
- a full (not incremental!) package build should be done and uploaded.
- </para>
+ a full (not incremental!) package build should be done and uploaded.</para>
- <para>The procedure for the new codebase is as follows:</para>
+ <para>The procedure is as follows:</para>
<itemizedlist>
<listitem>
<para>Edit <filename>/var/portbuild/conf/server.conf</filename>
with the following changes:</para>
- <itemizedlist>
- <listitem>
- <para>Change
- <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_TAG</makevar> to
- <literal>RELENG_<replaceable>branch</replaceable>_<replaceable>N</replaceable></literal>
- where <literal>N</literal> is the newest 'oldest' release
- for that branch.</para>
- </listitem>
- </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>Change the value of
+ <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to
+ <literal>releng/</literal><replaceable>branch</replaceable>.<replaceable>N</replaceable>
+ where <literal>N</literal> is the newest 'oldest' release
+ for that branch.</para>
+ </listitem>
+ </itemizedlist>
</listitem>
<listitem>
- <para>Run <command>
-/var/portbuild/updatesnap</command> manually.</para>
+ <para>Run <command>/var/portbuild/updatesnap</command> manually.</para>
</listitem>
<listitem>
- <para>Run <command>
-dopackages</command> with <literal>-nobuild</literal>.</para>
+ <para>Run <command>dopackages</command> with <literal>-nobuild</literal>.</para>
</listitem>
<listitem>
@@ -2439,370 +2256,375 @@ dopackages</command> with <literal>-nobuild</literal>.</para>
</listitem>
<listitem>
- <para>Now you can run <command>
-dopackages</command> without <literal>-nobuild</literal>.</para>
+ <para>Now you can run <command>dopackages</command> without <literal>-nobuild</literal>.</para>
</listitem>
-
</itemizedlist>
-
- <para>The procedure for the old codebase is left as an
- exercise for the reader.</para>
-
</sect1>
<sect1 id="new-arch">
<title>How to configure a new architecture</title>
- <note>
- <para>The initial steps need to be done using
- <application>sudo</application>.</para>
- </note>
+ <sect2 id="new-arch-pre-qmanager">
+ <title>Steps necessary before <application>qmanager</application> is started</title>
- <itemizedlist>
- <listitem>
- <para>Create a new
- <literal>ports-<replaceable>arch</replaceable></literal>
- user and group.</para>
- </listitem>
+ <note>
+ <para>The initial steps need to be done as
+ <literal>root</literal>.</para>
+ </note>
- <listitem>
- <screen>mkdir /var/portbuild/<replaceable>arch</replaceable></screen>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>If it has not already been done, create the
+ <literal>portbuild</literal>
+ user and group.</para>
+ </listitem>
- <listitem>
- <para>Create a new <application>zfs</application> filesystem:
- <screen>zfs create -o mountpoint=/a/portbuild/<replaceable>arch</replaceable> a/portbuild/<replaceable>arch</replaceable></screen>
- </para>
- </listitem>
+ <listitem>
+ <screen>mkdir /var/portbuild/<replaceable>arch</replaceable></screen>
+ </listitem>
- <listitem>
- <screen>
-chown ports-<replaceable>arch</replaceable>:portmgr /var/portbuild/<replaceable>arch</replaceable>;
-chmod 755 /var/portbuild/<replaceable>arch</replaceable>;
-cd /var/portbuild/<replaceable>arch</replaceable></screen>
- </listitem>
+ <listitem>
+ <para>Create a new <application>zfs</application> filesystem:</para>
- <listitem>
- <para>Create and populate the <filename>.ssh</filename> directory.</para>
+ <screen>&prompt.root; zfs create -o mountpoint=/a/portbuild/<replaceable>arch</replaceable> a/portbuild/<replaceable>arch</replaceable></screen>
</listitem>
- <listitem>
- <para>Create a directory for buildlogs and errorlogs:
- <screen>mkdir /dumpster/pointyhat/<replaceable>arch</replaceable>/archive</screen>
- </para>
-
- <note>
- <para>It is possible that <filename>/dumpster/pointyhat</filename>
- will not have enough space. In that case, create the archive
- directory as
- <filename>/dumpster/pointyhat/<replaceable>arch</replaceable>/archive</filename>
- and symlink to that. (This needs to be sorted out.)
- </para>
- </note>
- </listitem>
+ <listitem>
+ <screen>&prompt.root; chown portbuild:portbuild /var/portbuild/<replaceable>arch</replaceable>;
+&prompt.root; chmod 775 /var/portbuild/<replaceable>arch</replaceable>;
+&prompt.root; cd /var/portbuild/<replaceable>arch</replaceable></screen>
+ </listitem>
- <listitem>
- <para>Create a link to the above for the webserver:
- <screen>ln -s /dumpster/pointyhat/<replaceable>arch</replaceable>/archive archive</screen>
- </para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Create the <filename>.ssh</filename> directory.</para>
+ </listitem>
+ </itemizedlist>
- <note>
- <para>The next steps are most easily done as user
- <literal>ports-<replaceable>arch</replaceable></literal>.</para>
- </note>
+ <note>
+ <para>The next steps are most easily done as user
+ <literal>portbuild</literal>.</para>
+ </note>
- <itemizedlist>
- <listitem>
- <para>In the
- <filename>/var/portbuild/<replaceable>arch</replaceable></filename>
- directory:<screen>mkdir clients</screen></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Create an archive directory for buildlogs and errorlogs
+ under <filename>archive/</filename>.</para>
+ </listitem>
- <listitem>
- <para>Populate <filename>clients</filename> as usual.</para>
- </listitem>
+ <listitem>
+ <para>For each branch that will be supported, do the following:</para>
- <listitem>
- <para><screen>mkdir loads</screen></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Kick-start the build for the branch with</para>
- <listitem>
- <para><screen>mkdir lockfiles</screen></para>
- </listitem>
+ <screen>&prompt.root; build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para>Create a local <filename>make.conf</filename>. In the
- most trivial case, you can
- <screen>ln ../make.conf ./make.conf</screen></para>
- </listitem>
+ <listitem>
+ <para>If you are going to store your historical buildlogs and
+ errorlogs on your head node's hard drive, you may skip this step.
+ Otherwise:</para>
- <listitem>
- <para>Create an empty <filename>mlist</filename> file.</para>
- </listitem>
+ <para>Create an external directory and link to it:</para>
- <listitem>
- <para>(Only necessary for old codebase) Create
- <filename>pnohang.<replaceable>arch</replaceable></filename>.
- (The easiest way may be to do the following on a client, and
- then copy it back):
- <screen>cc pnohang.c -o pnohang-<replaceable>arch</replaceable></screen>
- </para>
- </listitem>
+ <example>
+ <title>Creating and linking an external archive directory</title>
- <listitem>
- <para>Create a fresh <filename>portbuild.conf</filename> file
- from one of the ones for another architecture.</para>
- </listitem>
+ <screen>&prompt.root; mkdir /dumpster/pointyhat/<replaceable>arch</replaceable>/archive
+&prompt.root; ln -s /dumpster/pointyhat/<replaceable>arch</replaceable>/archive archive</screen>
+ </example>
- <listitem>
- <para>Create customized
- <filename>portbuild.<replaceable>machinename</replaceable>.conf</filename>
- files as appropriate.</para>
- </listitem>
+ <note>
+ <para>(Historical note that only applied to the original
+ <hostid>pointyhat.FreeBSD.org</hostid> installation)</para>
+
+ <para>It is possible that <filename>/dumpster/pointyhat</filename>
+ will not have enough space. In that case, create the archive
+ directory as
+ <filename>/dumpster/pointyhat/<replaceable>arch</replaceable>/archive</filename>
+ and symlink to that.</para>
+ </note>
+ </listitem>
- <listitem>
- <para><screen>cd .ssh &amp;&amp; ssh-keygen</screen></para>
- </listitem>
+ <listitem>
+ <para>Populate <filename>clients</filename> as usual.</para>
+ </listitem>
- <listitem>
- <para>Edit the <filename>.ssh/config</filename> file for
- convenience in using <application>ssh</application>.</para>
- </listitem>
+ <listitem>
+ <para>Create a fresh <filename>portbuild.conf</filename> file
+ from one of the ones for another architecture.</para>
+ </listitem>
- <listitem>
- <para>Make the private configuration directory:
- <screen>mkdir /var/portbuild/conf/<replaceable>arch</replaceable></screen>
- </para>
- </listitem>
+ <listitem>
+ <para>Create customized
+ <filename>portbuild.<replaceable>machinename</replaceable>.conf</filename>
+ files as appropriate.</para>
+ </listitem>
- <listitem>
- <para>In that directory: create any <filename>dotunnel.*</filename>
- scripts needed.</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <screen>&prompt.root; cd .ssh &amp;&amp; ssh-keygen</screen>
+ </listitem>
- <note>
- <para>Once again using <application>sudo</application>:</para>
- </note>
+ <listitem>
+ <para>If desired,
+ edit the <filename>.ssh/config</filename> file for
+ convenience in using <application>ssh</application>.</para>
+ </listitem>
- <itemizedlist>
- <listitem>
- <para>Tell <application>qmanager</application> about the arch:
- <screen>python <replaceable>path</replaceable>/qmanager/qclient add_acl name=ports-<replaceable>arch</replaceable> uidlist=ports-<replaceable>arch</replaceable> gidlist=portmgr sense=1</screen></para>
- </listitem>
+ <listitem>
+ <para>If you need to create any tunnels:</para>
- <listitem>
- <para>(Only necessary for new codebase):
- Add <replaceable>arch</replaceable> to <makevar>SUPPORTED_ARCHS</makevar> in
- <filename>/var/portbuild/<replaceable>arch</replaceable>/server.conf</filename>.</para>
- </listitem>
+ <procedure>
+ <step>
+ <para>Make a private configuration directory:</para>
- <listitem>
- <para>(Only necessary for old codebase):
- Edit <filename>/var/portbuild/scripts/buildenv</filename>.</para>
- </listitem>
+ <screen>&prompt.root; mkdir /var/portbuild/conf/<replaceable>arch</replaceable></screen>
+ </step>
- <listitem>
- <para>Add the <replaceable>arch</replaceable> directory to
- <filename>/var/portbuild/scripts/zbackup</filename> and
- <filename>/var/portbuild/scripts/zexpire</filename>.</para>
- </listitem>
+ <step>
+ <para>In that directory: create any <filename>dotunnel.*</filename>
+ scripts needed.</para>
+ </step>
+ </procedure>
+ </listitem>
+ </itemizedlist>
- <listitem>
- <para>(Only necessary for old codebase):
- As with the procedure for creating a new branch:
- in the <filename>/var/portbuild/errorlogs/</filename>
- directory, create links for the webserver:<screen>
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/errors <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-full
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/logs <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-full-logs
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/errors <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-latest
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/logs <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-latest-logs
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/bak/packages <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-packages-full
-ln -s ../<replaceable>arch</replaceable>/<replaceable>branch</replaceable>/builds/latest/packages <replaceable>arch</replaceable>-<replaceable>branch</replaceable>-packages-latest</screen>
- </para>
- </listitem>
+ <note>
+ <para>Once again as <literal>root</literal>:</para>
+ </note>
- <listitem>
- <para>
- In the <filename>/var/portbuild/errorlogs/</filename>
- directory, create two more links for the webserver:<screen>
-ln -s ../<replaceable>arch</replaceable>/archive/buildlogs <replaceable>arch</replaceable>-buildlogs
-ln -s ../<replaceable>arch</replaceable>/archive/errorlogs <replaceable>arch</replaceable>-errorlogs</screen></para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>Add <replaceable>arch</replaceable> to <makevar>SUPPORTED_ARCHS</makevar> in
+ <filename>/var/portbuild/conf/server.conf</filename>.</para>
+ </listitem>
- <note>
- <para>Again, as
- <literal>ports-<replaceable>arch</replaceable></literal>:</para>
- </note>
+ <listitem>
+ <para>Add the <replaceable>arch</replaceable> directory to
+ <filename>/var/portbuild/scripts/zbackup</filename> and
+ <filename>/var/portbuild/scripts/zexpire</filename>.</para>
+ </listitem>
+ </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>For each branch that will be supported, do the following:
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>Add an appropriate <replaceable>arch</replaceable> entry for
+ <filename>/var/portbuild/scripts/dologs</filename> to the portbuild
+ <filename>crontab</filename>. (This is a hack and should go away.)</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
- <itemizedlist>
- <listitem>
- <para>Kick-start the build for the branch with
- <screen>build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen></para>
- </listitem>
+ <sect2 id="new-arch-post-qmanager">
+ <title>Steps necessary after <application>qmanager</application> is started</title>
- <listitem>
- <para><link linkend="setup">Create
- <filename>bindist.tar</filename></link>.</para>
- </listitem>
- </itemizedlist>
+ <note>
+ <para>Again as <literal>root</literal>:</para>
+ </note>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>Tell <application>qmanager</application> about the arch:</para>
- <note>
- <para>One last time using <application>sudo</application>:</para>
- </note>
+ <screen>python <replaceable>path</replaceable>/qmanager/qclient add_acl name=ports-<replaceable>arch</replaceable> uidlist=ports-<replaceable>arch</replaceable> gidlist=portbuild sense=1</screen>
+ </listitem>
- <itemizedlist>
- <listitem>
- <para>(Only necessary for old codebase):
- Only after the first time a
- <application>dopackages</application> has been run for the
- arch: add the arch to
- <filename>/var/portbuild/scripts/dopackagestats</filename>.</para>
- </listitem>
+ <listitem>
+ <para>For each branch that will be supported, do the following:</para>
- <listitem>
- <para>Add an appropriate <replaceable>arch</replaceable> entry for
- <filename>/var/portbuild/scripts/dologs</filename> to the root
- <filename>crontab</filename>. (This is a hack and should go away.)
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="setup">Create
+ <filename>bindist.tar</filename></link>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect2>
</sect1>
<sect1 id="new-head-node">
<title>How to configure a new head node (pointyhat instance)</title>
- <para>This section is in progress.</para>
+ <para>Please talk to Mark Linimon before making any changes
+ to this section.</para>
- <para>Please talk to Mark Linimon before making any changes.</para>
+ <sect2 id="pointyhat-privsep">
+ <title>Notes on privilege separation</title>
+
+ <para>As of January 2013, a rewrite is in progress to further separate
+ privileges. The following concepts are introduced:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Server-side user <username>portbuild</username> assumes all
+ responsiblity for operations involving builds and communicating
+ with the clients. This user no longer has access to
+ <application>sudo</application>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Server-side user <username>srcbuild</username> is created
+ and given responsiblity for operations involving both VCS
+ operations and anything involving src builds for the clients.
+ This user does not have access to
+ <application>sudo</application>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The server-side
+ <literal>ports-</literal><replaceable>arch</replaceable>
+ users go away.</para>
+ </listitem>
+
+ <listitem>
+ <para>None of the above server-side users have
+ <application>ssh</application> keys. Individual
+ <literal>portmgr</literal> will accomplish all those
+ tasks using <application>ksu</application>. (This is
+ still work-in-progress.)</para>
+ </listitem>
+
+ <listitem>
+ <para>The only client-side user is also named
+ <username>portbuild</username> and still has access to
+ <application>sudo</application> for the purpose of managing
+ jails.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This document has not yet been updated with the latest changes.
+ </para>
+ </sect2>
<sect2 id="pointyhat-basics">
<title>Basic installation</title>
<procedure>
-
<step>
<para>Install FreeBSD.</para>
</step>
<step>
- <para>For each supported arch, add a
- <literal>ports-<replaceable>${arch}</replaceable></literal>
- user and group. Add them to the <literal>wheel</literal>
- group. They should have the <literal>'*'</literal> password.
- Also, similarly, create the <literal>ports</literal> and
- <literal>portmgr</literal> users.</para>
+ <para>Create a user to own the <application>portbuild</application>
+ repository, such as <literal>portbuild</literal>. It should have the
+ <literal>'*'</literal> password.</para>
</step>
<step>
- <para>For each supported arch, create
- <filename>/home/ports-<replaceable>${arch}/.ssh/</replaceable></filename>
- and populate <filename>authorized_keys</filename>. </para>
- </step>
+ <para>Export that value for a later initialization step:</para>
-<!-- NOTYET
- <step>
- <para>Also add the following users:<screen>
-squid:*:100:100::0:0:User &:/usr/local/squid:/bin/sh
-ganglia:*:102:102::0:0:User &:/usr/local/ganglia:/bin/sh</screen>
- </para>
- <para>Add them to <filename>/etc/group</filename> as well.</para>
+ <screen>&prompt.root; export PORTBUILD_USER=<replaceable>portbuild</replaceable></screen>
</step>
--->
<step>
- <para>Create the appropriate files in
- <filename>/etc/.ssh/</filename>.</para>
+ <para>Similarly, create a user to own the <application>svn</application>
+ repository, such as <literal>srcbuild</literal>. It should have the
+ <literal>'*'</literal> password.</para>
</step>
<step>
- <para>Add the following to <filename>/boot/loader.conf</filename>:<screen>
-console="vidconsole,comconsole"</screen>
- </para>
+ <para>Export that value for a later initialization step:</para>
+
+ <screen>&prompt.root; export SRCBUILD_USER=<replaceable>srcbuild</replaceable></screen>
</step>
<step>
- <para>Add the following to <filename>/etc/sysctl.conf</filename>:<screen>
-kern.maxfiles=40000</screen>
- </para>
+ <para>Add the following to <filename>/boot/loader.conf</filename>:</para>
+
+ <programlisting>console="vidconsole,comconsole"</programlisting>
</step>
<step>
- <para>Make sure the following change is made to
- <filename>/etc/ttys</filename>:<screen>
-ttyu0 "/usr/libexec/getty std.9600" vt100 on secure</screen>
- </para>
+ <para>You should run the cluster on UTC. If you have not set the clock
+ to UTC:</para>
+
+ <programlisting>&prompt.root; cp -p /usr/share/zoneinfo/Etc/UTC /etc/localtime</programlisting>
</step>
<step>
- <para>TBA</para>
- </step>
- </procedure>
+ <para>Create the appropriate
+ <filename>/etc/rc.conf</filename>.</para>
- </sect2>
+ <para>Required entries:</para>
- <sect2 id="pointyhat-disk">
- <title>Configuring the disk</title>
+ <programlisting>hostname="<replaceable>${hostname}</replaceable>"
+sshd_enable="YES"
+zfs_enable="YES"</programlisting>
- <procedure>
+ <para>Recommended entries:</para>
- <step>
- <para>Create a <application>zfs</application> volume named
- <filename>a</filename> and mount it on
- <filename>/a</filename>:<screen>
-# zpool create a mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8</screen>
- </para>
+ <programlisting>background_fsck="NO"
+clear_tmp_enable="YES"
+dumpdev="AUTO"
+fsck_y_enable="YES"
+
+apache22_enable="YES"
+apache_flags=""
+apache_pidfile="/var/run/httpd.pid"
+gmetad_enable="YES"
+gmond_enable="YES"
+inetd_enable="YES"
+inetd_flags="-l -w"
+mountd_enable="YES"
+nfs_server_enable="YES"
+nfs_server_flags="-u -t -n 12"
+nfs_remote_port_only="YES"
+ntpd_enable="YES"
+rpcbind_enable="YES"
+rpc_lockd_enable="NO"
+rpc_statd_enable="YES"
+sendmail_enable="NONE"
+smartd_enable="YES"</programlisting>
</step>
<step>
- <para>Set up the base portbuild directory:<screen>
-# mkdir -p /a/portbuild
-# cd /a/portbuild
-# chown portmgr:portmgr .
-# chmod 775 .</screen>
- </para>
+ <para>Create <filename>/etc/resolv.conf</filename>, if
+ necessary.</para>
</step>
<step>
- <para>TBA</para>
+ <para>Create the appropriate files in
+ <filename>/etc/ssh/</filename>.</para>
</step>
- </procedure>
-
- </sect2>
-
- <sect2 id="pointyhat-src">
- <title>Configuring <literal>src</literal></title>
+ <step>
+ <para>Add the following to <filename>/etc/sysctl.conf</filename>:</para>
- <procedure>
+ <programlisting>kern.maxfiles=40000
+kern.maxfilesperproc=38000
+sysctl vfs.usermount=1
+sysctl vfs.zfs.super_owner=1</programlisting>
+ </step>
<step>
- <para>TBA</para>
- </step>
+ <para>Make sure the following change is made to
+ <filename>/etc/ttys</filename>:</para>
+ <programlisting>ttyu0 "/usr/libexec/getty std.9600" vt100 on secure</programlisting>
+ </step>
</procedure>
+ </sect2>
+ <sect2 id="pointyhat-src">
+ <title>Configuring <filename>src</filename></title>
+
+ <para>You should be able to install from the most recent release
+ using only the default kernel configuration.</para>
</sect2>
<sect2 id="pointyhat-ports">
- <title>Configuring <literal>ports</literal></title>
+ <title>Configuring <filename>ports</filename></title>
<procedure>
<step>
- <para>The following ports (or their latest successors) are required:<screen>
-databases/py-pysqlite23
-databases/py-sqlalchemy
+ <para>The following ports (or their latest successors) are required:</para>
+
+ <programlisting>databases/py-sqlite3
+databases/py-sqlalchemy (only SQLITE is needed)
devel/git (WITH_SVN)
devel/py-configobj
devel/py-setuptools
@@ -2810,85 +2632,420 @@ devel/subversion
net/nc
net/rsync
sysutils/ganglia-monitor-core (with GMETAD off)
-sysutils/ganglia-webfrontend (WITHOUT_X11)
-www/apache22 (with EXT_FILTER and THREADS)</screen>
- </para>
-
- <para>Expect those to bring in:<screen>
-databases/sqlite3
-lang/perl-5.12
-lang/python27</screen>
- </para>
-
- <para>The following ports (or their latest successors) are strongly suggested:<screen>
-benchmarks/bonnie++
-devel/ccache
+sysutils/ganglia-webfrontend (compile with -DWITHOUT_X11)
+www/apache22 (with EXT_FILTER)</programlisting>
+
+ <para>Expect those to bring in, among others:</para>
+
+ <programlisting>databases/sqlite3
+lang/perl-5.14 (or successor)
+lang/python27 (or sucessor)</programlisting>
+
+ <para>The following ports (or their latest successors) are strongly suggested:</para>
+
+ <programlisting>devel/ccache
mail/postfix
net/isc-dhcp41-server
-ports-mgmt/pkg_cutleaves
-ports-mgmt/pkg_tree
+ports-mgmt/pkg
ports-mgmt/portaudit
ports-mgmt/portmaster
-security/sudo
shells/bash
shells/zsh
-sysutils/screen
-sysutils/smartmontools</screen>
- </para>
+sysutils/screen</programlisting>
+
+ <note>
+ <para>The use of <application>sudo</application> on the master,
+ which was formerly required, is
+ <emphasis>no longer recommended</emphasis>.
+ </para>
+ </note>
+
+ <para>The following ports (or their latest successors) are handy:</para>
+
+ <programlisting>benchmarks/bonnie++
+ports-mgmt/pkg_tree
+sysutils/dmidecode
+sysutils/smartmontools
+sysutils/zfs-stats</programlisting>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2 id="pointyhat-zfs-volume">
+ <title>Configuring the zfs volume and setting up the repository</title>
+
+ <para>The following steps need to be done as euid root.</para>
+
+ <procedure>
+ <step>
+ <para>Pick a <application>zfs</application> volume name and export
+ it. We have used <replaceable>a</replaceable> so far to date.</para>
+
+ <programlisting>&prompt.root; export ZFS_VOLUME=<replaceable>a</replaceable></programlisting>
+ </step>
+
+ <step>
+ <para>Pick a mountpoint and export it. We have used
+ <filename>/<replaceable>a</replaceable></filename> so far to date.</para>
+
+ <screen>&prompt.root; export ZFS_MOUNTPOINT=/<replaceable>a</replaceable></screen>
+ </step>
+
+ <step>
+ <para>Create the <application>zfs</application> volume
+ and mount it.</para>
+
+ <example>
+ <title>Creating a <application>zfs</application> volume for portbuild</title>
+
+ <screen>&prompt.root; zpool create ${ZFS_VOLUME} mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8</screen>
+ </example>
+
+ <note>
+ <para>We will define a <application>zfs</application>
+ <literal>permission set</literal> below, so that the
+ <replaceable>portbuild</replaceable> user may administer this
+ volume without having to have root privileges.</para>
+ </note>
+ </step>
+
+ <step>
+ <para>Select an <application>svn</application> repository
+ and export it. See the
+ <ulink url="&url.books.handbook;/mirrors-svn.html">&os; Handbook</ulink>
+ for the currently supported list.</para>
+
+ <screen>&prompt.root; export VCS_REPOSITORY=<replaceable>svn://svn0.us-east.FreeBSD.org</replaceable></screen>
+ </step>
+
+ <step>
+ <para>Obtain a copy of the kickstart script into a
+ temporary directory. (You will not need to keep this
+ directory later.)</para>
+
+ <screen>&prompt.root; mkdir -p /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable>
+&prompt.root; svn checkout ${VCS_REPOSITORY}/base/projects/portbuild/admin/tools /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable></screen>
+ </step>
+
+ <step>
+ <para>Run the kickstart script:</para>
+
+ <screen>&prompt.root; sh /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable>/mkportbuild</screen>
+
+ <para>This will accomplish all the following 5 steps:</para>
+
+ <procedure>
+
+<!-- begin of whitespace-broken area -->
+ <step>
+ <para>Create the <filename>portbuild</filename> directory:</para>
+
+ <screen>&prompt.root; mkdir -p ${ZFS_MOUNTPOINT}/portbuild</screen>
+ </step>
+
+ <step>
+ <para>Create and mount a new <application>zfs</application>
+ filesystem on it:</para>
+
+ <screen>zfs create -o mountpoint=${ZFS_MOUNTPOINT}/portbuild ${ZFS_VOLUME}/portbuild</screen>
+ </step>
+
+ <step>
+ <para>Set up the directory:</para>
+
+ <screen>&prompt.root; chown ${PORTBUILD_USER}:${PORTBUILD_USER} ${ZFS_MOUNTPOINT}/portbuild
+&prompt.root; chmod 775 ${ZFS_MOUNTPOINT}/portbuild
+&prompt.root; ln -sf ${ZFS_MOUNTPOINT}/portbuild /var/portbuild</screen>
+
+ <note>
+ <para>The <command>ln</command> is necessary due to a number
+ of hardcoded paths. This is a bug.</para>
+ </note>
+ </step>
+
+ <step>
+ <para>Set up the initial repository:</para>
+
+ <screen>&prompt.user; svn checkout ${VCS_REPOSITORY}/base/projects/portbuild ${ZFS_MOUNTPOINT}/portbuild</screen>
+ </step>
+<!-- end of whitespace-broken area -->
+
+ <step>
+ <para>Set up the <application>zfs</application>
+ <literal>permission sets</literal>.</para>
+ </step>
+ </procedure>
+
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2 id="portbuild-repo-configuration">
+ <title>Configuring the <application>portbuild</application> files</title>
+
+ <procedure>
+ <step>
+ <para>Configure how build slaves will talk to your server
+ by making the following changes to
+ <filename>/<replaceable>a</replaceable>/portbuild/conf/client.conf</filename>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Set <makevar>CLIENT_NFS_MASTER</makevar> to wherever
+ your build slaves will PXE boot from. (Possibly, the
+ hostname of your server.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>CLIENT_BACKUP_FTP_SITE</makevar>
+ to a backup site for FTP fetches; again, possibly
+ the hostname of your server.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>CLIENT_UPLOAD_HOST</makevar> to
+ where completed packages will be uploaded.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Most of the other default values should be fine.</para>
</step>
<step>
- <para>Configure mail by doing the following: TBA.
- </para>
+ <para>Most of the default values in
+ <filename>/<replaceable>a</replaceable>/portbuild/conf/common.conf</filename>
+ should be fine. This file holds definitions used by
+ both the server and all its clients.</para>
+ </step>
+
+ <step>
+ <para>Configure the server by making the following changes to
+ <filename>/<replaceable>a</replaceable>/portbuild/conf/server.conf</filename>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Set <makevar>SUPPORTED_ARCHS</makevar> to the
+ list of architectures you wish to build packages for.</para>
+ </listitem>
+
+ <listitem>
+ <para>For each source branch you will be building for, set
+ <makevar>SRC_BRANCHES</makevar> and
+ <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar>
+ as detailed in <xref linkend="new-branch-pre-qmanager"/>.
+ You should not need to change
+ <makevar>SRC_BRANCHES_PATTERN</makevar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>ZFS_VOLUME</makevar> and
+ <makevar>ZFS_MOUNTPOINT</makevar> to whatever you
+ chose above.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>UPLOAD_DIRECTORY</makevar>,
+ <makevar>UPLOAD_TARGET</makevar>, and
+ <makevar>UPLOAD_USER</makevar> as appropriate
+ for your site.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>VCS_REPOSITORY</makevar> to whatever
+ you chose above.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set <makevar>MASTER_URL</makevar> to the http
+ URL of your server. This will be stamped into the
+ package build logs and the indices thereof.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Most of the other default values should be fine.</para>
</step>
</procedure>
+ </sect2>
+ <sect2 id="pointyhat-pre-qmanager">
+ <title>pre-<application>qmanager</application></title>
+
+ <procedure>
+ <step>
+ <para>For each architecture, follow the steps in
+ <xref linkend="new-arch-pre-qmanager"/>.</para>
+ </step>
+ </procedure>
</sect2>
- <sect2 id="pointyhat-other">
- <title>Other</title>
+ <sect2 id="pointyhat-qmanager">
+ <title><application>qmanager</application></title>
<procedure>
+ <step>
+ <para>Copy the following files from
+ <filename>/a/portbuild/admin/etc/rc.d/</filename> to
+ <filename>/usr/local/etc/rc.d/</filename>:</para>
+
+ <programlisting>pollmachine
+qmanager</programlisting>
+
+ <para>As root, start each one of them. You may find it handy
+ to start each under <application>screen</application> for
+ debugging purposes.</para>
+ </step>
<step>
- <para>TBA</para>
+ <para>Initialize the <application>qmanager</application>
+ database's acl list:</para>
+
+ <note>
+ <para>This should now be automatically done for you by
+ the first <command>build</command> command.</para>
+ </note>
+
+ <screen>&prompt.root; python /<replaceable>a</replaceable>/portbuild/qmanager/qclient add_acl name=deny_all uidlist= gidlist= sense=0</screen>
</step>
+ </procedure>
+ </sect2>
+ <sect2 id="pointyhat-src-ports-repos">
+ <title>Creating src and ports repositories</title>
+
+ <procedure>
+ <step>
+ <para>As the <replaceable>srcbuild</replaceable> user,
+ run the following commands manually to create the
+ <literal>src</literal> and <literal>ports</literal>
+ repositories, respectively:</para>
+
+ <screen>&prompt.user; /<replaceable>a</replaceable>/portbuild/admin/scripts/updatesnap.ports
+&prompt.user; /<replaceable>a</replaceable>/portbuild/admin/scripts/updatesnap</screen>
+
+ <para>These will be periodically run from the
+ <replaceable>srcbuild</replaceable>
+ <filename>crontab</filename>, which you will
+ install below.</para>
+ </step>
</procedure>
+ </sect2>
+ <sect2 id="pointyhat-other-services">
+ <title>Other services</title>
+
+ <procedure>
+ <step>
+ <para>Configure
+ <filename>/usr/local/etc/apache22/httpd.conf</filename>
+ as appropriate for your site.</para>
+ </step>
+
+ <step>
+ <para>Copy <filename>/a/portbuild/admin/conf/apache.conf</filename>
+ to the appropriate <filename>Includes/</filename> subdirectory, e.g.,
+ <filename>/usr/local/etc/apache22/Includes/portbuild.conf</filename>.
+ Configure it as appropriate for your site.</para>
+ </step>
+
+ <step>
+ <para>Install <filename>/a/portbuild/admin/crontabs/portbuild</filename> as
+ the <username>portbuild</username> crontab via
+ <command>crontab -u portbuild -e</command>. If you do
+ not support all the archs listed there, make sure to comment out
+ the appropriate <application>dologs</application> entries.</para>
+ </step>
+
+ <step>
+ <para>Install <filename>/a/srcbuild/admin/crontabs/portbuild</filename> as
+ the <username>srcbuild</username> crontab via
+ <command>crontab -u srcbuild -e</command>.</para>
+ </step>
+
+ <step>
+ <para>If your build slaves will be pxebooted, make sure to
+ enable the <application>tftp</application> entries in
+ <filename>/etc/inetd.conf</filename>.</para>
+ </step>
+
+ <step>
+ <para>Configure mail by doing the following:</para>
+
+ <para><command>newaliases</command>.</para>
+ </step>
+ </procedure>
</sect2>
+ <sect2 id="pointyhat-finishing-up">
+ <title>Finishing up</title>
+
+ <procedure>
+ <step>
+ <para>For each architecture, follow the steps in
+ <xref linkend="new-arch-post-qmanager"/>.</para>
+ </step>
+
+ <step>
+ <para>You will probably find it handy to append
+ the following to the <makevar>PATH</makevar> definition for
+ the <replaceable>portbuild</replaceable> user:</para>
+
+ <programlisting>/<replaceable>a</replaceable>/portbuild/scripts:/<replaceable>a</replaceable>/portbuild/tools</programlisting>
+ </step>
+
+ <step>
+ <para>You will also probably find it handy to append
+ the following to the <makevar>PATH</makevar> definition for
+ the <replaceable>srcbuild</replaceable> user:</para>
+
+ <programlisting>/<replaceable>a</replaceable>/portbuild/admin/scripts:/<replaceable>a</replaceable>/portbuild/admin/tools</programlisting>
+ </step>
+ </procedure>
+
+ <para>You should now be ready to build packages.</para>
+ </sect2>
</sect1>
<sect1 id="disk-failure">
<title>Procedures for dealing with disk failures</title>
- <para>When a machine has a disk failure (e.g. panics due to read errors,
+ <note>
+ <para>The following section is particular to <hostid>freebsd.org</hostid>
+ and is somewhat obsolete.</para>
+ </note>
+
+ <para>When a machine has a disk failure (e.g., panics due to read errors,
etc), then we should do the following steps:</para>
<itemizedlist>
- <listitem><para>Note the time and failure mode (e.g. paste in the
- relevant console output) in
- <filename>/var/portbuild/<replaceable>${arch}</replaceable>/reboots</filename></para></listitem>
+ <listitem>
+ <para>Note the time and failure mode (e.g., paste in the
+ relevant console output) in
+ <filename>/var/portbuild/<replaceable>${arch}</replaceable>/reboots</filename></para>
+ </listitem>
- <listitem><para>For i386 gohan clients, scrub the disk by touching
- <filename>/SCRUB</filename> in the nfsroot (e.g.
- <filename>/a/nfs/8.dir1/SCRUB</filename>) and rebooting. This will
- <command>dd if=/dev/zero of=/dev/ad0</command> and force the drive to
- remap any bad sectors it finds, if it has enough spares left. This is
- a temporary measure to extend the lifetime of a drive that is on the
- way out.</para>
+ <listitem>
+ <para>For i386 gohan clients, scrub the disk by touching
+ <filename>/SCRUB</filename> in the nfsroot (e.g.,
+ <filename>/a/nfs/8.dir1/SCRUB</filename>) and rebooting. This will
+ <command>dd if=/dev/zero of=/dev/ad0</command> and force the drive to
+ remap any bad sectors it finds, if it has enough spares left. This is
+ a temporary measure to extend the lifetime of a drive that is on the
+ way out.</para>
- <note><para>For the i386 blade systems another signal of a failing
- disk seems to be that the blade will completely hang and be
- unresponsive to either console break, or even NMI.</para></note>
+ <note>
+ <para>For the i386 blade systems another signal of a failing
+ disk seems to be that the blade will completely hang and be
+ unresponsive to either console break, or even NMI.</para>
+ </note>
- <para>For other build systems that don't newfs their disk at boot (e.g.
- amd64 systems) this step has to be skipped.</para></listitem>
+ <para>For other build systems that do not newfs their disk at boot (e.g.,
+ amd64 systems) this step has to be skipped.</para>
+ </listitem>
- <listitem><para>If the problem recurs, then the disk is probably toast.
- Take the machine out of <filename>mlist</filename> and (for ata disks)
- run <command>smartctl</command> on the drive:</para>
+ <listitem>
+ <para>If the problem recurs, then the disk is probably toast.
+ Take the machine out of <filename>mlist</filename> and (for ata disks)
+ run <command>smartctl</command> on the drive:</para>
<screen>smartctl -t long /dev/ad0</screen>
@@ -2919,7 +3076,8 @@ LifeTime(hours) LBA_of_first_error
<para>It will also display other data including a log of previous drive
errors. It is possible for the drive to show previous DMA errors
without failing the self-test though (because of sector
- remapping).</para></listitem>
+ remapping).</para>
+ </listitem>
</itemizedlist>
<para>When a disk has failed, please inform the cluster administrators
diff --git a/en_US.ISO8859-1/articles/problem-reports/article.xml b/en_US.ISO8859-1/articles/problem-reports/article.xml
index 5386264d2a..61ad4fa589 100644
--- a/en_US.ISO8859-1/articles/problem-reports/article.xml
+++ b/en_US.ISO8859-1/articles/problem-reports/article.xml
@@ -8,7 +8,6 @@
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
- &tm-attrib.cvsup;
&tm-attrib.ibm;
&tm-attrib.intel;
&tm-attrib.sparc;
@@ -86,7 +85,7 @@
course of action, and will only serve to frustrate you and the
developers. Conversely, there are cases where it might be
appropriate to submit a problem report about something else than
- a bug&mdash;an enhancement or a feature request, for
+ a bug&mdash;an enhancement or a new feature, for
instance.</para>
<para>So how do you determine what is a bug and what is not? As a
@@ -103,12 +102,6 @@
<itemizedlist>
<listitem>
- <para>Requests for feature enhancements. It is generally a
- good idea to air these on the mailing lists before
- submitting a problem report.</para>
- </listitem>
-
- <listitem>
<para>Notification of updates to externally maintained
software (mainly ports, but also externally maintained base
system components such as BIND or various GNU
@@ -277,7 +270,7 @@
carefully study the contents of the
<filename>/usr/src/UPDATING</filename> file on your system
or its latest version at
- <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>.
+ <ulink url="http://svnweb.freebsd.org/base/head/UPDATING?view=log"></ulink>.
(This is vital information
if you are upgrading from one version to
another&mdash;especially if you are upgrading to the
@@ -288,10 +281,10 @@
<filename>/usr/ports/UPDATING</filename> (for individual ports)
or <filename>/usr/ports/CHANGES</filename> (for changes
that affect the entire Ports Collection).
- <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING"></ulink>
+ <ulink url="http://svnweb.freebsd.org/ports/head/UPDATING?view=log"></ulink>
and
- <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES"></ulink>
- are also available via CVSweb.</para>
+ <ulink url="http://svnweb.freebsd.org/ports/head/CHANGES?view=log"></ulink>
+ are also available via svnweb.</para>
</listitem>
</itemizedlist>
</section>
@@ -371,8 +364,8 @@
is a place to put that, see below) and on which architecture.
You should include whether you are running from a release
(e.g. from a CDROM or download), or from
- a system maintained by &man.cvsup.1; (and, if so, how
- recently you updated). If you are tracking the
+ a system maintained by Subversion (and, if so,
+ what revision number you are at). If you are tracking the
&os.current; branch, that is the very first thing someone
will ask, because fixes (especially for high-profile
problems) tend to get committed very quickly, and
@@ -584,11 +577,11 @@
<option>-c</option> or <option>-u</option> option to
&man.diff.1; to create a context or unified diff (unified is
preferred), and make
- sure to specify the exact CVS revision numbers of the files
+ sure to specify the exact SVN revision numbers of the files
you modified so the developers who read your report will be
able to apply them easily. For problems with the kernel or the
base utilities, a patch against &os.current; (the HEAD
- CVS branch) is preferred since all new code should be applied
+ Subversion branch) is preferred since all new code should be applied
and tested there first. After appropriate or substantial testing
has been done, the code will be merged/migrated to the &os.stable;
branch.</para>
@@ -661,8 +654,8 @@
<para><emphasis>Confidential:</emphasis> This is prefilled
to <literal>no</literal>. Changing it makes no sense as
there is no such thing as a confidential &os; problem
- report&mdash;the PR database is distributed worldwide by
- <application>CVSup</application>.</para>
+ report&mdash;the PR database is distributed
+ worldwide.</para>
</listitem>
<listitem>
@@ -920,7 +913,7 @@
</itemizedlist>
<para>Here is the current list of categories (taken from
- <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories"></ulink>):</para>
+ <ulink url="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories"></ulink>):</para>
<itemizedlist>
<listitem>
@@ -929,11 +922,6 @@
</listitem>
<listitem>
- <para><literal>alpha:</literal> problems specific to the
- Alpha platform.</para>
- </listitem>
-
- <listitem>
<para><literal>amd64:</literal> problems specific to the
AMD64 platform.</para>
</listitem>
diff --git a/en_US.ISO8859-1/articles/rc-scripting/article.xml b/en_US.ISO8859-1/articles/rc-scripting/article.xml
index 9a93599a53..c12a4a58d6 100644
--- a/en_US.ISO8859-1/articles/rc-scripting/article.xml
+++ b/en_US.ISO8859-1/articles/rc-scripting/article.xml
@@ -397,8 +397,8 @@ start_cmd="${name}_start"
stop_cmd=":"
load_rc_config $name<co id="rcng-confdummy-loadconfig"/>
-eval "${rcvar}=\${${rcvar}:-'NO'}"<co id="rcng-confdummy-enable"/>
-dummy_msg=${dummy_msg:-"Nothing started."}<co id="rcng-confdummy-opt"/>
+: ${dummy_enable:=no} <co id="rcng-confdummy-enable"/>
+: ${dummy_msg="Nothing started."}<co id="rcng-confdummy-opt"/>
dummy_start()
{
@@ -445,7 +445,7 @@ run_rc_command "$1"</programlisting>
system, you should add a default setting for the knob to
<filename>/etc/defaults/rc.conf</filename> and document
it in &man.rc.conf.5;. Otherwise it is your script that
- should provide a default setting for the knob. A portable
+ should provide a default setting for the knob. The canonical
approach to the latter case is shown in the example.</para>
<note>
@@ -476,7 +476,7 @@ run_rc_command "$1"</programlisting>
<important>
<para>The names of all &man.rc.conf.5; variables used
exclusively by our script <emphasis>must</emphasis>
- have the same prefix: <envar>${name}</envar>. For
+ have the same prefix: <envar>${name}_</envar>. For
example: <envar>dummy_mode</envar>,
<envar>dummy_state_file</envar>, and so on.</para>
</important>
@@ -484,19 +484,10 @@ run_rc_command "$1"</programlisting>
<note>
<para>While it is possible to use a shorter name internally,
e.g., just <envar>msg</envar>, adding the unique prefix
- <envar>${name}</envar> to all global names introduced by
+ <envar>${name}_</envar> to all global names introduced by
our script will save us from possible
collisions with the &man.rc.subr.8; namespace.</para>
- <para>As long as an &man.rc.conf.5; variable and its
- internal equivalent are the same, we can use a more
- compact expression to set the default value:</para>
-
- <programlisting>: ${dummy_msg:="Nothing started."}</programlisting>
-
- <para>The current style is to use the more verbose form
- though.</para>
-
<para>As a rule, <filename>rc.d</filename> scripts of the
base system need not provide defaults for their
&man.rc.conf.5; variables because the defaults should
@@ -509,7 +500,11 @@ run_rc_command "$1"</programlisting>
<callout arearefs="rcng-confdummy-msg">
<para>Here we use <envar>dummy_msg</envar> to actually
- control our script, i.e., to emit a variable message.</para>
+ control our script, i.e., to emit a variable message.
+ Use of a shell function is overkill here, since it only
+ runs a single command; an equally valid alternative is:</para>
+
+ <programlisting>start_cmd="echo \"$dummy_msg\""</programlisting>
</callout>
</calloutlist>
</sect1>
diff --git a/en_US.ISO8859-1/articles/solid-state/article.xml b/en_US.ISO8859-1/articles/solid-state/article.xml
index a4fc36fdfc..1290cb19cc 100644
--- a/en_US.ISO8859-1/articles/solid-state/article.xml
+++ b/en_US.ISO8859-1/articles/solid-state/article.xml
@@ -67,79 +67,84 @@
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
- <para>This article covers the use of solid state disk devices in &os;
- to create embedded systems.</para>
-
- <para>Embedded systems have the advantage of increased stability due to
- the lack of integral moving parts (hard drives). Account must be
- taken, however, for the generally low disk space available in the
- system and the durability of the storage medium.</para>
-
- <para>Specific topics to be covered include the types and attributes of
- solid state media suitable for disk use in &os;, kernel options
- that are of interest in such an environment, the
- <filename>rc.initdiskless</filename> mechanisms that automate the
- initialization of such systems and the need for read-only filesystems,
- and building filesystems from scratch. The article will conclude
- with some general strategies for small and read-only &os;
- environments.</para>
+ <para>This article covers the use of solid state disk devices in
+ &os; to create embedded systems.</para>
+
+ <para>Embedded systems have the advantage of increased stability
+ due to the lack of integral moving parts (hard drives).
+ Account must be taken, however, for the generally low disk
+ space available in the system and the durability of the
+ storage medium.</para>
+
+ <para>Specific topics to be covered include the types and
+ attributes of solid state media suitable for disk use in &os;,
+ kernel options that are of interest in such an environment,
+ the <filename>rc.initdiskless</filename> mechanisms that
+ automate the initialization of such systems and the need for
+ read-only filesystems, and building filesystems from scratch.
+ The article will conclude with some general strategies for
+ small and read-only &os; environments.</para>
</abstract>
</articleinfo>
<sect1 id="intro">
<title>Solid State Disk Devices</title>
- <para>The scope of this article will be limited to solid state disk
- devices made from flash memory. Flash memory is a solid state memory
- (no moving parts) that is non-volatile (the memory maintains data even
- after all power sources have been disconnected). Flash memory can
- withstand tremendous physical shock and is reasonably fast (the flash
- memory solutions covered in this article are slightly slower than a EIDE
- hard disk for write operations, and much faster for read operations).
- One very important aspect of flash memory, the ramifications of which
- will be discussed later in this article, is that each sector has a
- limited rewrite capacity. You can only write, erase, and write again to
- a sector of flash memory a certain number of times before the sector
- becomes permanently unusable. Although many flash memory products
- automatically map bad blocks, and although some even distribute write
- operations evenly throughout the unit, the fact remains that there
- exists a limit to the amount of writing that can be done to the device.
- Competitive units have between 1,000,000 and 10,000,000 writes per
- sector in their specification. This figure varies due to the
- temperature of the environment.</para>
-
- <para>Specifically, we will be discussing ATA compatible compact-flash
- units, which are quite popular as storage media for digital
- cameras. Of particular interest is the fact that they pin out directly
- to the IDE bus and are compatible with the ATA command set. Therefore,
- with a very simple and low-cost adaptor, these devices can be attached
- directly to an IDE bus in a computer. Once implemented in this manner,
- operating systems such as &os; see the device as a normal hard disk
- (albeit small).</para>
-
- <para>Other solid state disk solutions do exist, but their expense,
- obscurity, and relative unease of use places them beyond the scope of
- this article.</para>
+ <para>The scope of this article will be limited to solid state
+ disk devices made from flash memory. Flash memory is a solid
+ state memory (no moving parts) that is non-volatile (the memory
+ maintains data even after all power sources have been
+ disconnected). Flash memory can withstand tremendous physical
+ shock and is reasonably fast (the flash memory solutions covered
+ in this article are slightly slower than a EIDE hard disk for
+ write operations, and much faster for read operations). One
+ very important aspect of flash memory, the ramifications of
+ which will be discussed later in this article, is that each
+ sector has a limited rewrite capacity. You can only write,
+ erase, and write again to a sector of flash memory a certain
+ number of times before the sector becomes permanently unusable.
+ Although many flash memory products automatically map bad
+ blocks, and although some even distribute write operations
+ evenly throughout the unit, the fact remains that there exists a
+ limit to the amount of writing that can be done to the device.
+ Competitive units have between 1,000,000 and 10,000,000 writes
+ per sector in their specification. This figure varies due to
+ the temperature of the environment.</para>
+
+ <para>Specifically, we will be discussing ATA compatible
+ compact-flash units, which are quite popular as storage media
+ for digital cameras. Of particular interest is the fact that
+ they pin out directly to the IDE bus and are compatible with the
+ ATA command set. Therefore, with a very simple and low-cost
+ adaptor, these devices can be attached directly to an IDE bus in
+ a computer. Once implemented in this manner, operating systems
+ such as &os; see the device as a normal hard disk (albeit
+ small).</para>
+
+ <para>Other solid state disk solutions do exist, but their
+ expense, obscurity, and relative unease of use places them
+ beyond the scope of this article.</para>
</sect1>
<sect1 id="kernel">
<title>Kernel Options</title>
- <para>A few kernel options are of specific interest to those creating
- an embedded &os; system.</para>
+ <para>A few kernel options are of specific interest to those
+ creating an embedded &os; system.</para>
<para>All embedded &os; systems that use flash memory as system
- disk will be interested in memory disks and memory filesystems. Because
- of the limited number of writes that can be done to flash memory, the
- disk and the filesystems on the disk will most likely be mounted
- read-only. In this environment, filesystems such as
- <filename>/tmp</filename> and <filename>/var</filename> are mounted as
- memory filesystems to allow the system to create logs and update
- counters and temporary files. Memory filesystems are a critical
- component to a successful solid state &os; implementation.</para>
-
- <para>You should make sure the following lines exist in your kernel
- configuration file:</para>
+ disk will be interested in memory disks and memory filesystems.
+ Because of the limited number of writes that can be done to
+ flash memory, the disk and the filesystems on the disk will most
+ likely be mounted read-only. In this environment, filesystems
+ such as <filename>/tmp</filename> and <filename>/var</filename>
+ are mounted as memory filesystems to allow the system to create
+ logs and update counters and temporary files. Memory
+ filesystems are a critical component to a successful solid state
+ &os; implementation.</para>
+
+ <para>You should make sure the following lines exist in your
+ kernel configuration file:</para>
<programlisting>options MFS # Memory Filesystem
options MD_ROOT # md device usable as a potential root device
@@ -147,58 +152,63 @@ pseudo-device md # memory disk</programlisting>
</sect1>
<sect1 id="ro-fs">
- <title>The <literal>rc</literal> Subsystem and Read-Only Filesystems</title>
+ <title>The <literal>rc</literal> Subsystem and Read-Only
+ Filesystems</title>
<para>The post-boot initialization of an embedded &os; system is
controlled by <filename>/etc/rc.initdiskless</filename>.</para>
- <para><filename>/etc/rc.d/var</filename> mounts <filename>/var</filename>
- as a memory filesystem, makes a configurable list of directories in
- <filename>/var</filename> with the &man.mkdir.1; command, and
- changes modes on some of those directories. In the execution of
+ <para><filename>/etc/rc.d/var</filename> mounts
+ <filename>/var</filename> as a memory filesystem, makes a
+ configurable list of directories in <filename>/var</filename>
+ with the &man.mkdir.1; command, and changes modes on some of
+ those directories. In the execution of
<filename>/etc/rc.d/var</filename>, one other
<filename>rc.conf</filename> variable comes into play &ndash;
- <literal>varsize</literal>. The <filename>/etc/rc.d/var</filename>
- file creates a <filename>/var</filename> partition based on the value of
+ <literal>varsize</literal>. The
+ <filename>/etc/rc.d/var</filename> file creates a
+ <filename>/var</filename> partition based on the value of
this variable in <filename>rc.conf</filename>:</para>
<programlisting>varsize=8192</programlisting>
<para>Remember that this value is in sectors by default.</para>
- <para>The fact that <filename>/var</filename>
- is a read-write filesystem is an important
- distinction, as the <filename>/</filename> partition (and any other
- partitions you may have on your flash media) should be mounted
- read-only. Remember that in <xref linkend="intro"/> we detailed the
- limitations of flash memory - specifically the limited write capability.
- The importance of not mounting filesystems on flash media read-write,
- and the importance of not using a swap file, cannot be overstated. A
- swap file on a busy system can burn through a piece of flash media in
- less than one year. Heavy logging or temporary file creation and
- destruction can do the same. Therefore, in addition to removing the
+ <para>The fact that <filename>/var</filename> is a read-write
+ filesystem is an important distinction, as the
+ <filename>/</filename> partition (and any other partitions you
+ may have on your flash media) should be mounted read-only.
+ Remember that in <xref linkend="intro"/> we detailed the
+ limitations of flash memory - specifically the limited write
+ capability. The importance of not mounting filesystems on flash
+ media read-write, and the importance of not using a swap file,
+ cannot be overstated. A swap file on a busy system can burn
+ through a piece of flash media in less than one year. Heavy
+ logging or temporary file creation and destruction can do the
+ same. Therefore, in addition to removing the
<literal>swap</literal> entry from your
- <filename>/etc/fstab</filename> file, you should also change the Options
- field for each filesystem to <literal>ro</literal> as follows:</para>
+ <filename>/etc/fstab</filename> file, you should also change the
+ Options field for each filesystem to <literal>ro</literal> as
+ follows:</para>
<programlisting># Device Mountpoint FStype Options Dump Pass#
/dev/ad0s1a / ufs ro 1 1</programlisting>
- <para>A few applications in the average system will immediately begin to
- fail as a result of this change. For instance, cron
+ <para>A few applications in the average system will immediately
+ begin to fail as a result of this change. For instance, cron
will not run properly as a result of missing cron tabs in the
<filename>/var</filename> created by
<filename>/etc/rc.d/var</filename>, and syslog and dhcp will
- encounter problems as well as a result of the read-only filesystem and
- missing items in the <filename>/var</filename> that
- <filename>/etc/rc.d/var</filename> has created. These are only
- temporary problems though, and are addressed, along with solutions to
- the execution of other common software packages in
+ encounter problems as well as a result of the read-only
+ filesystem and missing items in the <filename>/var</filename>
+ that <filename>/etc/rc.d/var</filename> has created. These are
+ only temporary problems though, and are addressed, along with
+ solutions to the execution of other common software packages in
<xref linkend="strategies"/>.</para>
- <para>An important thing to remember is that a filesystem that was mounted
- read-only with <filename>/etc/fstab</filename> can be made read-write at
- any time by issuing the command:</para>
+ <para>An important thing to remember is that a filesystem that was
+ mounted read-only with <filename>/etc/fstab</filename> can be
+ made read-write at any time by issuing the command:</para>
<screen>&prompt.root; <userinput>/sbin/mount -uw <replaceable>partition</replaceable></userinput></screen>
@@ -210,73 +220,79 @@ pseudo-device md # memory disk</programlisting>
<sect1>
<title>Building a File System From Scratch</title>
- <para>Because ATA compatible compact-flash cards are seen by &os; as
- normal IDE hard drives, you could
- theoretically install &os; from the network using the kern and
- mfsroot floppies or from a CD.</para>
+ <para>Because ATA compatible compact-flash cards are seen by &os;
+ as normal IDE hard drives, you could theoretically install &os;
+ from the network using the kern and mfsroot floppies or from a
+ CD.</para>
<para>However, even a small installation of &os; using normal
- installation procedures can produce a system in size of greater than 200
- megabytes. Because most people will be using smaller flash memory
- devices (128 megabytes is considered fairly large - 32 or even 16
- megabytes is common) an installation using normal mechanisms is not
- possible&mdash;there is simply not enough disk space for even the
- smallest of conventional installations.</para>
-
- <para>The easiest way to overcome this space limitation is to install
- &os; using conventional means to a normal hard disk. After the
- installation is complete, pare down the operating system to a size that
- will fit onto your flash media, then tar the entire filesystem. The
- following steps will guide you through the process of preparing a piece
- of flash memory for your tarred filesystem. Remember, because a normal
- installation is not being performed, operations such as partitioning,
- labeling, file-system creation, etc. need to be performed by hand. In
- addition to the kern and mfsroot floppy disks, you will also need to use
- the fixit floppy.</para>
+ installation procedures can produce a system in size of greater
+ than 200 megabytes. Because most people will be using smaller
+ flash memory devices (128 megabytes is considered fairly large -
+ 32 or even 16 megabytes is common) an installation using normal
+ mechanisms is not possible&mdash;there is simply not enough disk
+ space for even the smallest of conventional
+ installations.</para>
+
+ <para>The easiest way to overcome this space limitation is to
+ install &os; using conventional means to a normal hard disk.
+ After the installation is complete, pare down the operating
+ system to a size that will fit onto your flash media, then tar
+ the entire filesystem. The following steps will guide you
+ through the process of preparing a piece of flash memory for
+ your tarred filesystem. Remember, because a normal installation
+ is not being performed, operations such as partitioning,
+ labeling, file-system creation, etc. need to be performed by
+ hand. In addition to the kern and mfsroot floppy disks, you
+ will also need to use the fixit floppy.</para>
<procedure>
<step>
<title>Partitioning your flash media device</title>
<para>After booting with the kern and mfsroot floppies, choose
- <literal>custom</literal> from the installation menu. In the custom
- installation menu, choose <literal>partition</literal>. In the
- partition menu, you should delete all existing partitions using the
- <keycap>d</keycap> key. After deleting all existing partitions,
- create a partition using the <keycap>c</keycap> key and accept the
- default value for the size of the partition. When asked for the
- type of the partition, make sure the value is set to
- <literal>165</literal>. Now write this partition table to the disk
- by pressing the <keycap>w</keycap> key (this is a hidden option on
- this screen). If you are using an ATA compatible compact
- flash card, you should choose the &os; Boot Manager. Now press
- the <keycap>q</keycap> key to quit the partition menu. You will be
- shown the boot manager menu once more - repeat the choice you made
- earlier.</para>
+ <literal>custom</literal> from the installation menu. In
+ the custom installation menu, choose
+ <literal>partition</literal>. In the partition menu, you
+ should delete all existing partitions using the
+ <keycap>d</keycap> key. After deleting all existing
+ partitions, create a partition using the <keycap>c</keycap>
+ key and accept the default value for the size of the
+ partition. When asked for the type of the partition, make
+ sure the value is set to <literal>165</literal>. Now write
+ this partition table to the disk by pressing the
+ <keycap>w</keycap> key (this is a hidden option on this
+ screen). If you are using an ATA compatible compact flash
+ card, you should choose the &os; Boot Manager. Now press
+ the <keycap>q</keycap> key to quit the partition menu. You
+ will be shown the boot manager menu once more - repeat the
+ choice you made earlier.</para>
</step>
<step>
- <title>Creating filesystems on your flash memory device</title>
+ <title>Creating filesystems on your flash memory
+ device</title>
<para>Exit the custom installation menu, and from the main
- installation menu choose the <literal>fixit</literal> option. After
- entering the fixit environment, enter the following command:</para>
+ installation menu choose the <literal>fixit</literal>
+ option. After entering the fixit environment, enter the
+ following command:</para>
<screen>&prompt.root; <userinput>disklabel -e /dev/ad0c</userinput></screen>
- <para>At this point you will have entered the vi editor under the
- auspices of the disklabel command. Next, you need to add
- an <literal>a:</literal> line at the end of the file. This
- <literal>a:</literal> line should look like:</para>
+ <para>At this point you will have entered the vi editor under
+ the auspices of the disklabel command. Next, you need to
+ add an <literal>a:</literal> line at the end of the file.
+ This <literal>a:</literal> line should look like:</para>
<programlisting>a: <replaceable>123456</replaceable> 0 4.2BSD 0 0</programlisting>
- <para>Where <replaceable>123456</replaceable> is a number that is
- exactly the same as the number in the existing <literal>c:</literal>
- entry for size. Basically you are duplicating the existing
- <literal>c:</literal> line as an <literal>a:</literal> line, making
- sure that fstype is <literal>4.2BSD</literal>. Save the file and
- exit.</para>
+ <para>Where <replaceable>123456</replaceable> is a number that
+ is exactly the same as the number in the existing
+ <literal>c:</literal> entry for size. Basically you are
+ duplicating the existing <literal>c:</literal> line as an
+ <literal>a:</literal> line, making sure that fstype is
+ <literal>4.2BSD</literal>. Save the file and exit.</para>
<screen>&prompt.root; <userinput>disklabel -B -r /dev/ad0c</userinput>
&prompt.root; <userinput>newfs /dev/ad0a</userinput></screen>
@@ -289,22 +305,24 @@ pseudo-device md # memory disk</programlisting>
<screen>&prompt.root; <userinput>mount /dev/ad0a /flash</userinput></screen>
- <para>Bring this machine up on the network so we may transfer our tar
- file and explode it onto our flash media filesystem. One example of
- how to do this is:</para>
+ <para>Bring this machine up on the network so we may transfer
+ our tar file and explode it onto our flash media filesystem.
+ One example of how to do this is:</para>
<screen>&prompt.root; <userinput>ifconfig xl0 192.168.0.10 netmask 255.255.255.0</userinput>
&prompt.root; <userinput>route add default 192.168.0.1</userinput></screen>
- <para>Now that the machine is on the network, transfer your tar file.
- You may be faced with a bit of a dilemma at this point - if your
- flash memory part is 128 megabytes, for instance, and your tar file
- is larger than 64 megabytes, you cannot have your tar file on the
- flash media at the same time as you explode it - you will run out of
- space. One solution to this problem, if you are using FTP, is to
- untar the file while it is transferred over FTP. If you perform
- your transfer in this manner, you will never have the tar file and
- the tar contents on your disk at the same time:</para>
+ <para>Now that the machine is on the network, transfer your
+ tar file. You may be faced with a bit of a dilemma at this
+ point - if your flash memory part is 128 megabytes, for
+ instance, and your tar file is larger than 64 megabytes, you
+ cannot have your tar file on the flash media at the same
+ time as you explode it - you will run out of
+ space. One solution to this problem, if you are using FTP,
+ is to untar the file while it is transferred over FTP. If
+ you perform your transfer in this manner, you will never
+ have the tar file and the tar contents on your disk at the
+ same time:</para>
<screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| tar xvf -"</userinput></screen>
@@ -313,70 +331,74 @@ pseudo-device md # memory disk</programlisting>
<screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| zcat | tar xvf -"</userinput></screen>
- <para>After the contents of your tarred filesystem are on your flash
- memory filesystem, you can unmount the flash memory and
- reboot:</para>
+ <para>After the contents of your tarred filesystem are on your
+ flash memory filesystem, you can unmount the flash memory
+ and reboot:</para>
<screen>&prompt.root; <userinput>cd /</userinput>
&prompt.root; <userinput>umount /flash</userinput>
&prompt.root; <userinput>exit</userinput></screen>
- <para>Assuming that you configured your filesystem correctly when it
- was built on the normal hard disk (with your filesystems mounted
- read-only, and with the necessary options compiled into the kernel)
- you should now be successfully booting your &os; embedded
- system.</para>
+ <para>Assuming that you configured your filesystem correctly
+ when it was built on the normal hard disk (with your
+ filesystems mounted read-only, and with the necessary
+ options compiled into the kernel) you should now be
+ successfully booting your &os; embedded system.</para>
</step>
</procedure>
</sect1>
<sect1 id="strategies">
- <title>System Strategies for Small and Read Only Environments</title>
+ <title>System Strategies for Small and Read Only
+ Environments</title>
<para>In <xref linkend="ro-fs"/>, it was pointed out that the
<filename>/var</filename> filesystem constructed by
- <filename>/etc/rc.d/var</filename> and the presence of a read-only
- root filesystem causes problems with many common software packages used
- with &os;. In this article, suggestions for successfully running
- cron, syslog, ports installations, and the Apache web server will be
- provided.</para>
+ <filename>/etc/rc.d/var</filename> and the presence of a
+ read-only root filesystem causes problems with many common
+ software packages used with &os;. In this article, suggestions
+ for successfully running cron, syslog, ports installations, and
+ the Apache web server will be provided.</para>
<sect2>
<title>cron</title>
- <para>Upon boot, <filename class="directory">/var</filename> gets
- populated by <filename>/etc/rc.d/var</filename> using the list from
- <filename>/etc/mtree/BSD.var.dist</filename>, so the <filename
- class="directory">cron</filename>, <filename
- class="directory">cron/tabs</filename>, <filename
- class="directory">at</filename>, and a few other standard
+ <para>Upon boot, <filename class="directory">/var</filename>
+ gets populated by <filename>/etc/rc.d/var</filename> using the
+ list from <filename>/etc/mtree/BSD.var.dist</filename>, so the
+ <filename class="directory">cron</filename>, <filename
+ class="directory">cron/tabs</filename>, <filename
+ class="directory">at</filename>, and a few other standard
directories get created.</para>
- <para>However, this does not solve the problem of maintaining cron
- tabs across reboots. When the system reboots, the
- <filename>/var</filename> filesystem that is in memory will disappear
- and any cron tabs you may have had in it will also disappear.
- Therefore, one solution would be to create cron tabs for the users
- that need them, mount your <filename>/</filename> filesystem as
- read-write and copy those cron tabs to somewhere safe, like
+ <para>However, this does not solve the problem of maintaining
+ cron tabs across reboots. When the system reboots, the
+ <filename>/var</filename> filesystem that is in memory will
+ disappear and any cron tabs you may have had in it will also
+ disappear. Therefore, one solution would be to create cron
+ tabs for the users that need them, mount your
+ <filename>/</filename> filesystem as read-write and copy those
+ cron tabs to somewhere safe, like
<filename>/etc/tabs</filename>, then add a line to the end of
- <filename>/etc/rc.initdiskless</filename> that copies those crontabs into
- <filename>/var/cron/tabs</filename> after that directory has been
- created during system initialization. You may also need to add a line
- that changes modes and permissions on the directories you create and
- the files you copy with <filename>/etc/rc.initdiskless</filename>.</para>
+ <filename>/etc/rc.initdiskless</filename> that copies those
+ crontabs into <filename>/var/cron/tabs</filename> after that
+ directory has been created during system initialization. You
+ may also need to add a line that changes modes and permissions
+ on the directories you create and the files you copy with
+ <filename>/etc/rc.initdiskless</filename>.</para>
</sect2>
<sect2>
<title>syslog</title>
- <para><filename>syslog.conf</filename> specifies the locations of
- certain log files that exist in <filename>/var/log</filename>. These
- files are not created by <filename>/etc/rc.d/var</filename> upon
- system initialization. Therefore, somewhere in
- <filename>/etc/rc.d/var</filename>, after the section that creates
- the directories in <filename>/var</filename>, you will need to add
- something like this:</para>
+ <para><filename>syslog.conf</filename> specifies the locations
+ of certain log files that exist in
+ <filename>/var/log</filename>. These files are not created by
+ <filename>/etc/rc.d/var</filename> upon system initialization.
+ Therefore, somewhere in <filename>/etc/rc.d/var</filename>,
+ after the section that creates the directories in
+ <filename>/var</filename>, you will need to add something like
+ this:</para>
<screen>&prompt.root; <userinput>touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages</userinput>
&prompt.root; <userinput>chmod 0644 /var/log/*</userinput></screen>
@@ -385,27 +407,30 @@ pseudo-device md # memory disk</programlisting>
<sect2>
<title>Ports Installation</title>
- <para>Before discussing the changes necessary to successfully use the
- ports tree, a reminder is necessary regarding the read-only nature of
- your filesystems on the flash media. Since they are read-only, you
- will need to temporarily mount them read-write using the mount syntax
- shown in <xref linkend="ro-fs"/>. You should always remount those
+ <para>Before discussing the changes necessary to successfully
+ use the ports tree, a reminder is necessary regarding the
+ read-only nature of your filesystems on the flash media.
+ Since they are read-only, you will need to temporarily mount
+ them read-write using the mount syntax shown in <xref
+ linkend="ro-fs"/>. You should always remount those
filesystems read-only when you are done with any maintenance -
- unnecessary writes to the flash media could considerably shorten its
- lifespan.</para>
-
- <para>To make it possible to enter a ports directory and successfully
- run <command>make</command> <maketarget>install</maketarget>,
- we must create a packages directory on
- a non-memory filesystem that will keep track of our packages across
- reboots. Because it is necessary to mount your filesystems as
- read-write for the installation of a package anyway, it is sensible to
- assume that an area on the flash media can also be used for package
+ unnecessary writes to the flash media could considerably
+ shorten its lifespan.</para>
+
+ <para>To make it possible to enter a ports directory and
+ successfully run
+ <command>make</command> <maketarget>install</maketarget>, we
+ must create a packages directory on a non-memory filesystem
+ that will keep track of our packages across reboots. Because
+ it is necessary to mount your filesystems as read-write for
+ the installation of a package anyway, it is sensible to assume
+ that an area on the flash media can also be used for package
information to be written to.</para>
- <para>First, create a package database directory. This is normally in
- <filename>/var/db/pkg</filename>, but we cannot place it there as it
- will disappear every time the system is booted.</para>
+ <para>First, create a package database directory. This is
+ normally in <filename>/var/db/pkg</filename>, but we cannot
+ place it there as it will disappear every time the system is
+ booted.</para>
<screen>&prompt.root; <userinput>mkdir /etc/pkg</userinput></screen>
@@ -415,12 +440,13 @@ pseudo-device md # memory disk</programlisting>
<screen>&prompt.root; <userinput>ln -s /etc/pkg /var/db/pkg</userinput></screen>
- <para>Now, any time that you mount your filesystems as read-write and
- install a package, the <command>make</command> <maketarget>install</maketarget> will work,
- and package information
- will be written successfully to <filename>/etc/pkg</filename> (because
- the filesystem will, at that time, be mounted read-write) which will
- always be available to the operating system as
+ <para>Now, any time that you mount your filesystems as
+ read-write and install a package, the
+ <command>make</command> <maketarget>install</maketarget> will
+ work, and package information will be written successfully to
+ <filename>/etc/pkg</filename> (because the filesystem will, at
+ that time, be mounted read-write) which will always be
+ available to the operating system as
<filename>/var/db/pkg</filename>.</para>
</sect2>
@@ -428,40 +454,42 @@ pseudo-device md # memory disk</programlisting>
<title>Apache Web Server</title>
<note>
- <para>The steps in this section are only necessary if Apache is
- set up to write its pid or log information outside of
+ <para>The steps in this section are only necessary if Apache
+ is set up to write its pid or log information outside of
<filename class="directory">/var</filename>. By default,
Apache keeps its pid file in <filename
- class="directory">/var/run/httpd.pid</filename> and its log
- files in <filename class="directory">/var/log</filename>.</para>
+ class="directory">/var/run/httpd.pid</filename> and its
+ log files in <filename
+ class="directory">/var/log</filename>.</para>
</note>
<para>It is now assumed that Apache keeps its log files in a
directory <filename
- class="directory"><replaceable>apache_log_dir</replaceable></filename>
+ class="directory"><replaceable>apache_log_dir</replaceable></filename>
outside of <filename class="directory">/var</filename>.
- When this directory lives on a read-only filesystem, Apache will
- not be able to save any log files, and may have problems working.
- If so, it is necessary to add a new directory to the
+ When this directory lives on a read-only filesystem, Apache
+ will not be able to save any log files, and may have problems
+ working. If so, it is necessary to add a new directory to the
list of directories in <filename>/etc/rc.d/var</filename> to
create in <filename>/var</filename>, and to link
- <filename class="directory"><replaceable>apache_log_dir</replaceable></filename> to
- <filename>/var/log/apache</filename>. It is also necessary to set
- permissions and ownership on this new directory.</para>
+ <filename
+ class="directory"><replaceable>apache_log_dir</replaceable></filename>
+ to <filename>/var/log/apache</filename>. It is also necessary
+ to set permissions and ownership on this new directory.</para>
- <para>First, add the directory <literal>log/apache</literal> to the list
- of directories to be created in
+ <para>First, add the directory <literal>log/apache</literal> to
+ the list of directories to be created in
<filename>/etc/rc.d/var</filename>.</para>
<para>Second, add these commands to
- <filename>/etc/rc.d/var</filename> after the directory creation
- section:</para>
+ <filename>/etc/rc.d/var</filename> after the directory
+ creation section:</para>
<screen>&prompt.root; <userinput>chmod 0774 /var/log/apache</userinput>
&prompt.root; <userinput>chown nobody:nobody /var/log/apache</userinput></screen>
- <para>Finally, remove the existing
- <filename class="directory"><replaceable>apache_log_dir</replaceable></filename>
+ <para>Finally, remove the existing <filename
+ class="directory"><replaceable>apache_log_dir</replaceable></filename>
directory, and replace it with a link:</para>
<screen>&prompt.root; <userinput>rm -rf <filename class="directory"><replaceable>apache_log_dir</replaceable></filename></userinput>
diff --git a/en_US.ISO8859-1/books/Makefile b/en_US.ISO8859-1/books/Makefile
index ecf27143de..4cf91fdde1 100644
--- a/en_US.ISO8859-1/books/Makefile
+++ b/en_US.ISO8859-1/books/Makefile
@@ -1,7 +1,6 @@
# $FreeBSD$
SUBDIR = arch-handbook
-SUBDIR+= corp-net-guide
SUBDIR+= design-44bsd
SUBDIR+= dev-model
SUBDIR+= developers-handbook
diff --git a/en_US.ISO8859-1/books/arch-handbook/Makefile b/en_US.ISO8859-1/books/arch-handbook/Makefile
index 7c1f296a6c..9ad49d0e62 100644
--- a/en_US.ISO8859-1/books/arch-handbook/Makefile
+++ b/en_US.ISO8859-1/books/arch-handbook/Makefile
@@ -16,11 +16,11 @@ INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
-# SRCS lists the individual SGML files that make up the document. Changes
+# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
-# SGML content
+# XML content
SRCS= book.xml
SRCS+= boot/chapter.xml
SRCS+= driverbasics/chapter.xml
diff --git a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml
index f70027a2e9..c4b87c9ba7 100644
--- a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml
+++ b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml
@@ -48,13 +48,7 @@
<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 filesystem hierarchy.
- In releases of FreeBSD older than 5.0-RELEASE, where
- &man.devfs.5; support is not 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>
+ <filename>/dev</filename> in the filesystem hierarchy.</para>
<para>Device drivers can roughly be broken down into two
categories; character and network device drivers.</para>
@@ -208,25 +202,23 @@ KMOD=skeleton
<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. Two versions are shown, one for &os;&nbsp;4.X and
- one for &os;&nbsp;5.X.</para>
+ read from it.</para>
<example>
<title>Example of a Sample Echo Pseudo-Device Driver for
- &os;&nbsp;4.X</title>
+ &os;&nbsp;10.X</title>
<programlisting>/*
- * Simple `echo' pseudo-device KLD
+ * Simple Echo pseudo-device KLD
*
* Murray Stokely
+ * Søren (Xride) Straarup
+ * Eitan Adler
*/
-#define MIN(a,b) (((a) &lt; (b)) ? (a) : (b))
-
#include &lt;sys/types.h&gt;
#include &lt;sys/module.h&gt;
#include &lt;sys/systm.h&gt; /* uprintf */
-#include &lt;sys/errno.h&gt;
#include &lt;sys/param.h&gt; /* defines used in kernel.h */
#include &lt;sys/kernel.h&gt; /* types used in module initialization */
#include &lt;sys/conf.h&gt; /* cdevsw struct */
@@ -236,170 +228,6 @@ KMOD=skeleton
#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 count;
-static t_echo *echomsg;
-
-MALLOC_DECLARE(M_ECHOBUF);
-MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
-
-/*
- * This function 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>&amp;</literal>echo_cdevsw,
- 0,
- UID_ROOT,
- GID_WHEEL,
- 0600,
- "echo");
- /* kmalloc memory for use by this driver */
- 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 = EOPNOTSUPP;
- 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-&gt;uio_resid, (echomsg-&gt;len - uio-&gt;uio_offset &gt; 0) ?
- echomsg-&gt;len - uio-&gt;uio_offset : 0);
- if ((err = uiomove(echomsg-&gt;msg + uio-&gt;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-&gt;uio_iov-&gt;iov_base, echomsg-&gt;msg,
- MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE - 1));
-
- /* Now we need to null terminate, then record the length */
- *(echomsg-&gt;msg + MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE - 1)) = 0;
- echomsg-&gt;len = MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE);
-
- if (err != 0) {
- uprintf("Write failed: bad address!\n");
- }
- count++;
- return(err);
-}
-
-DEV_MODULE(echo,echo_loader,NULL);</programlisting>
- </example>
-
- <example>
- <title>Example of a Sample Echo Pseudo-Device Driver for
- &os;&nbsp;5.X</title>
-
- <programlisting>/*
- * Simple `echo' pseudo-device KLD
- *
- * Murray Stokely
- *
- * Converted to 5.X by S&oslash;ren (Xride) Straarup
- */
-
-#include &lt;sys/types.h&gt;
-#include &lt;sys/module.h&gt;
-#include &lt;sys/systm.h&gt; /* uprintf */
-#include &lt;sys/errno.h&gt;
-#include &lt;sys/param.h&gt; /* defines used in kernel.h */
-#include &lt;sys/kernel.h&gt; /* types used in module initialization */
-#include &lt;sys/conf.h&gt; /* cdevsw struct */
-#include &lt;sys/uio.h&gt; /* uio struct */
-#include &lt;sys/malloc.h&gt;
-
-#define BUFFERSIZE 256
-
-
-/* Function prototypes */
static d_open_t echo_open;
static d_close_t echo_close;
static d_read_t echo_read;
@@ -415,15 +243,14 @@ static struct cdevsw echo_cdevsw = {
.d_name = "echo",
};
-typedef struct s_echo {
+struct s_echo {
char msg[BUFFERSIZE];
int len;
-} t_echo;
+};
/* vars */
static struct cdev *echo_dev;
-static int count;
-static t_echo *echomsg;
+static struct s_echo *echomsg;
MALLOC_DECLARE(M_ECHOBUF);
MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
@@ -434,20 +261,25 @@ MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
*/
static int
-echo_loader(struct module *m, int what, void *arg)
+echo_loader(struct module *m __unused, int what, void *arg __unused)
{
- int err = 0;
+ int error = 0;
switch (what) {
case MOD_LOAD: /* kldload */
- echo_dev = make_dev(<literal>&amp;</literal>echo_cdevsw,
+ error = make_dev_p(MAKEDEV_CHECKNAME | MAKEDEV_WAITOK,
+ &amp;echo_dev,
+ &amp;echo_cdevsw,
0,
UID_ROOT,
GID_WHEEL,
0600,
"echo");
+ if (error != 0)
+ break;
+
/* kmalloc memory for use by this driver */
- echomsg = malloc(sizeof(t_echo), M_ECHOBUF, M_WAITOK);
+ echomsg = malloc(sizeof(*echomsg), M_ECHOBUF, M_WAITOK);
printf("Echo device loaded.\n");
break;
case MOD_UNLOAD:
@@ -456,26 +288,27 @@ echo_loader(struct module *m, int what, void *arg)
printf("Echo device unloaded.\n");
break;
default:
- err = EOPNOTSUPP;
+ error = EOPNOTSUPP;
break;
}
- return(err);
+ return (error);
}
static int
-echo_open(struct cdev *dev, int oflags, int devtype, struct thread *p)
+echo_open(struct cdev *dev __unused, int oflags __unused, int devtype __unused, struct thread *p __unused)
{
- int err = 0;
+ int error = 0;
uprintf("Opened device \"echo\" successfully.\n");
- return(err);
+ return (error);
}
static int
-echo_close(struct cdev *dev, int fflag, int devtype, struct thread *p)
+echo_close(struct cdev *dev __unused, int fflag __unused, int devtype __unused, struct thread *p __unused)
{
- uprintf("Closing device \"echo.\"\n");
- return(0);
+
+ uprintf("Closing device \"echo\".\n");
+ return (0);
}
/*
@@ -485,21 +318,21 @@ echo_close(struct cdev *dev, int fflag, int devtype, struct thread *p)
*/
static int
-echo_read(struct cdev *dev, struct uio *uio, int ioflag)
+echo_read(struct cdev *dev __unused, struct uio *uio, int ioflag __unused)
{
- int err = 0;
- int amt;
+ int error, amt;
/*
* How big is this read operation? Either as big as the user wants,
* or as big as the remaining data
*/
- amt = MIN(uio-&gt;uio_resid, (echomsg-&gt;len - uio-&gt;uio_offset &gt; 0) ?
- echomsg-&gt;len - uio-&gt;uio_offset : 0);
- if ((err = uiomove(echomsg-&gt;msg + uio-&gt;uio_offset, amt, uio)) != 0) {
+
+ amt = MIN(uio-&gt;uio_resid, echomsg-&gt;len - uio-&gt;uio_offset);
+ uio-&gt;uio_offset += amt;
+ if ((error = uiomove(echomsg-&gt;msg, amt, uio)) != 0)
uprintf("uiomove failed!\n");
- }
- return(err);
+
+ return (error);
}
/*
@@ -508,55 +341,57 @@ echo_read(struct cdev *dev, struct uio *uio, int ioflag)
*/
static int
-echo_write(struct cdev *dev, struct uio *uio, int ioflag)
+echo_write(struct cdev *dev __unused, struct uio *uio, int ioflag __unused)
{
- int err = 0;
+ int error, amt;
+
+ /* Copy the string in from user memory to kernel memory */
+
+ /*
+ * We either write from the beginning or are appending -- do
+ * not allow random access.
+ */
+ if (uio-&gt;uio_offset != 0 &amp;&amp; (uio-&gt;uio_offset != echomsg-&gt;len))
+ return (EINVAL);
+
+ /*
+ * This is new message, reset length
+ */
+ if (uio-&gt;uio_offset == 0)
+ echomsg-&gt;len = 0;
+
+ /* NULL character should be overridden */
+ if (echomsg-&gt;len != 0)
+ echomsg-&gt;len--;
/* Copy the string in from user memory to kernel memory */
- err = copyin(uio-&gt;uio_iov-&gt;iov_base, echomsg-&gt;msg,
- MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE - 1));
+ amt = MIN(uio-&gt;uio_resid, (BUFFERSIZE - echomsg-&gt;len));
+
+ error = uiomove(echomsg-&gt;msg + uio-&gt;uio_offset, amt, uio);
/* Now we need to null terminate, then record the length */
- *(echomsg-&gt;msg + MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE - 1)) = 0;
- echomsg-&gt;len = MIN(uio-&gt;uio_iov-&gt;iov_len, BUFFERSIZE);
+ echomsg-&gt;len += amt + 1;
+ uio-&gt;uio_offset += amt + 1;
+ echomsg-&gt;msg[echomsg-&gt;len - 1] = 0;
- if (err != 0) {
+ if (error != 0)
uprintf("Write failed: bad address!\n");
- }
- count++;
- return(err);
+ return (error);
}
DEV_MODULE(echo,echo_loader,NULL);</programlisting>
</example>
- <para>To install this driver on &os;&nbsp;4.X you will first need to
- make a node on your filesystem with a command such as:</para>
-
- <screen>&prompt.root; <userinput>mknod /dev/echo c 33 0</userinput></screen>
-
<para>With this driver loaded you should now be able to type
something like:</para>
<screen>&prompt.root; <userinput>echo -n "Test Data" &gt; /dev/echo</userinput>
&prompt.root; <userinput>cat /dev/echo</userinput>
-Test Data</screen>
+Opened device "echo" successfully.
+Test Data
+Closing device "echo".</screen>
<para>Real hardware devices are described in the next chapter.</para>
-
- <para>Additional Resources
- <itemizedlist>
- <listitem><simpara><ulink
- url="http://ezine.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://ezine.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 id="driverbasics-block">
diff --git a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml
index 20a2996f02..578d7da34b 100644
--- a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml
+++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml
@@ -146,7 +146,7 @@
DEVMETHOD(device_suspend, xxx_isa_suspend),
DEVMETHOD(device_resume, xxx_isa_resume),
- { 0, 0 }
+ DEVMETHOD_END
};
static driver_t xxx_isa_driver = {
diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml
index b6f5aff26d..15a70da312 100644
--- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml
+++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml
@@ -37,7 +37,7 @@
#include &lt;sys/conf.h&gt; /* cdevsw struct */
#include &lt;sys/uio.h&gt; /* uio struct */
#include &lt;sys/malloc.h&gt;
-#include &lt;sys/bus.h&gt; /* structs, prototypes for pci bus stuff */
+#include &lt;sys/bus.h&gt; /* structs, prototypes for pci bus stuff and DEVMETHOD macros! */
#include &lt;machine/bus.h&gt;
#include &lt;sys/rman.h&gt;
@@ -221,7 +221,7 @@ static device_method_t mypci_methods[] = {
DEVMETHOD(device_suspend, mypci_suspend),
DEVMETHOD(device_resume, mypci_resume),
- { 0, 0 }
+ DEVMETHOD_END
};
static devclass_t mypci_devclass;
diff --git a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml
index 4ce5564a02..9686fae370 100644
--- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml
+++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml
@@ -82,16 +82,16 @@
<sect1 id="oss-files">
<title>Files</title>
- <para>All the relevant code currently (FreeBSD 4.4) lives in
+ <para>All the relevant code lives in
<filename>/usr/src/sys/dev/sound/</filename>, except for the
public ioctl interface definitions, found in
<filename>/usr/src/sys/sys/soundcard.h</filename></para>
<para>Under <filename>/usr/src/sys/dev/sound/</filename>, the
<filename>pcm/</filename> directory holds the central code,
- while the <filename>isa/</filename> and
- <filename>pci/</filename> directories have the drivers for ISA
- and PCI boards.</para>
+ while the <filename>pci/</filename>, <filename>isa/</filename>
+ and <filename>usb/</filename> directories have the drivers
+ for PCI and ISA boards, and for USB audio devices.</para>
</sect1>
@@ -527,7 +527,7 @@
<function>channel_resetdone()</function>, and
<function>channel_notify()</function> are for special purposes
and should not be implemented in a driver without discussing
- it with the authorities (&a.cg;).</para>
+ it on the &a.multimedia;.</para>
<para><function>channel_setdir()</function> is deprecated.</para>
</sect3>
diff --git a/en_US.ISO8859-1/books/bibliography/Makefile b/en_US.ISO8859-1/books/bibliography/Makefile
index c638bf7fff..3a4bb68350 100644
--- a/en_US.ISO8859-1/books/bibliography/Makefile
+++ b/en_US.ISO8859-1/books/bibliography/Makefile
@@ -13,11 +13,11 @@ INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
-# SRCS lists the individual SGML files that make up the document. Changes
+# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
-# SGML content
+# XML content
SRCS= book.xml
DOC_PREFIX?= ${.CURDIR}/../../..
diff --git a/en_US.ISO8859-1/books/corp-net-guide/Makefile b/en_US.ISO8859-1/books/corp-net-guide/Makefile
deleted file mode 100644
index e4834d3e81..0000000000
--- a/en_US.ISO8859-1/books/corp-net-guide/Makefile
+++ /dev/null
@@ -1,25 +0,0 @@
-# $FreeBSD$
-
-DOC?= book
-
-FORMATS?= html
-
-INSTALL_COMPRESSED?=gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= book.xml
-
-IMAGES_EN= 08-01.eps
-IMAGES_EN+= 08-02.eps
-IMAGES_EN+= 08-03.eps
-IMAGES_EN+= 08-04.eps
-IMAGES_EN+= 08-05.eps
-IMAGES_EN+= 08-06.eps
-
-# 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/corp-net-guide/book.xml b/en_US.ISO8859-1/books/corp-net-guide/book.xml
deleted file mode 100644
index abe65ada67..0000000000
--- a/en_US.ISO8859-1/books/corp-net-guide/book.xml
+++ /dev/null
@@ -1,3223 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
- "../../../share/xml/freebsd45.dtd">
-
-<!-- $FreeBSD$ -->
-<!-- FreeBSD Documentation Project -->
-
-<book lang='en'>
- <bookinfo>
- <title>The FreeBSD Corporate Networker's Guide</title>
-
- <author>
- <firstname>Ted</firstname>
- <surname>Mittelstaedt</surname>
- </author>
-
- <copyright>
- <year>2001</year>
- <holder>Addison-Wesley Longman, Inc (Original English language edition)</holder>
- </copyright>
-
- <copyright>
- <year>2001</year>
- <holder>Pearson Educational Japan (Japanese language translation)</holder>
- </copyright>
-
- <isbn>ENGLISH LANGUAGE EDITION ISBN: 0-201-70481-1</isbn>
- <isbn>JAPANESE LANGUAGE EDITION ISBN: 4-89471-464-7</isbn>
-
- <legalnotice id="legalnotice">
- <para>The eighth chapter of the book, <citetitle>The FreeBSD Corporate
- Networker's Guide</citetitle> is excerpted here with the permission
- of the publisher. No part of it may be further reproduced or
- distributed without the publisher's express written
- <email>Chanda.Leary-Coutu@awl.com</email>.
- The other chapters of
- <ulink url="http://cseng.aw.com/book/0,,0201704811,00.html">the
- book</ulink> covers topics such as system administration,
- fileserving, and e-mail delivery. More information about this book is
- available from the publisher, with whom you can also sign up to
- receive news of <ulink url="mailto:Chanda.Leary-Coutu@awl.com">related
- titles</ulink>. The author's web site for the book includes sample
- code, working examples,
- <ulink url="http://www.freebsd-corp-net-guide.com/errata.html">errata</ulink>
- and a Q&amp;A forum, and is available at
- <ulink url="http://www.freebsd-corp-net-guide.com/"></ulink>.</para>
- </legalnotice>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
- </bookinfo>
-
- <chapter id="printserving" label="8">
- <title>Printserving</title>
-
- <para>Printserving is a complicated topic. There are many different
- software interfaces to printers, as well as a wide variety of printer
- hardware interfaces. This chapter covers the basics of setting up a
- print queue, using Samba to print, and administering print queues and
- connections.</para>
-
- <sect1 id="printserving-history">
- <title>PC printing history</title>
-
- <para>In the early days of the personal computer, printing was simple.
- The PC owner bought a cheap printer, usually a dot matrix that barely
- supported ASCII, and plugged it into the computer with a parallel
- cable. Applications would either work with the printer or not, and
- most did because all they could do was output DOS or ASCII text. The
- few software applications that supported graphics generally could only
- output on specific makes and models of printers. Shared
- <emphasis>network</emphasis> printing, if it existed, was usually done
- by some type of serial port switchbox.</para>
-
- <para>This was the general state of affairs with the PC until the
- Windows operating system was released. All at once, application
- programmers were finally free of the restrictions of worrying about
- how some printer manufacturer would change printer control codes.
- Graphics printing, in the form of fonts and images, was added to most
- applications, and demand for it rapidly increased across the
- corporation. Large, high-capacity laser printers designed for office
- printing appeared on the scene. Printing went from 150 to 300 to
- 600 dpi for the common desktop laser printer.</para>
-
- <para>Today organizational network printing is complex, and printers
- themselves are more complicated. Most organizations find that sharing
- a few high-quality laser printers is much more cost effective than
- buying many cheaper dot matrix units. Good network print serving is a
- necessity, and it can be very well provided by the FreeBSD UNIX
- system.</para>
- </sect1>
-
- <sect1 id="printserving-protocols">
- <title>Printer communication protocols and hardware</title>
-
- <para>Printers that don't use proprietary vendor codes communicate with
- computers using one or more of three major printing protocols. The
- communication is done over a hardware cable that can be a parallel
- connection (printer port) or a serial connection (COM port).</para>
-
- <sect2>
- <title>ASCII Printing Protocol</title>
-
- <para>The ASCII protocol is the simplest protocol used, as well as the
- oldest. ASCII is also used to represent text files internally in
- the DOS, UNIX, and Windows operating systems. Therefore, data taken
- from a text file or a directory listing generally requires little
- preparation before being sent to the printer, other than a
- newline-to-carriage return/linefeed conversion for UNIX. Printers
- usually follow the DOS text file convention of the print head
- requiring an explicit carriage return character followed by a
- linefeed character at the end of a line of text. Since UNIX uses
- only the linefeed character to terminate text, an additional
- carriage return character must be added to the end of each line in
- raw text print output; otherwise, text prints in a
- <emphasis>stairstep</emphasis> output. (Some printers have hardware
- or software switches to do the conversion.)</para>
- </sect2>
-
- <sect2>
- <title>PostScript Printing Protocol</title>
-
- <para>Adobe introduced the PostScript language in 1985; it is used to
- enable the printout of high quality graphics and styled font text.
- PostScript is now the de-facto print standard in the UNIX community,
- and the only print standard in the Macintosh community. Numerous
- UNIX utilities exist to <emphasis>beautify</emphasis> and enhance
- text printing with PostScript. PostScript can be used to download
- font files into a printer as well as the data to be printed.
- PostScript commands can be sent to instruct the printer CPU to
- image, rotate, and scale complex graphics and images, thus freeing
- the host CPU. Scaling is particularly important with fonts since
- the document with the font has been produced on a computer screen
- with far lower resolution than the printer. For example, a 1024x768
- computer screen on a 17-inch monitor allows for a resolution of
- approximately 82dpi, a modern desktop printer prints at a resolution
- of 600dpi. Therefore, a font must be scaled at least seven times
- larger for WYSIWYG output!</para>
-
- <para>PostScript printers generally come with a number of resident
- fonts. For example, the NEC Silentwriter 95 contains Courier,
- Helvetica, ITC Avant Garde Gothic Book, ITC Bookman Light, New
- Century Schoolbook Roman, Palatino Roman, Times Roman, and several
- symbol fonts. These are stored in Read Only Memory (ROM) in the
- printer. When a page is printed from a Windows client that contains
- a font not in the printer, a font substitution table is used. If no
- substitute can be made, Courier is usually used. The user should be
- conscious of this when creating documents - documents with fonts not
- listed in the substitution table may cause other users problems when
- printing. Avoid use of strange fonts for documents that will be
- widely distributed.</para>
-
- <para>The user program can choose to download different fonts as
- outline fonts to the PostScript printer if desired. Fonts that are
- commonly used by the user are often downloaded to PostScript
- printers that are connected directly to the user's computer, the
- fonts are then available to successive print jobs until the printer
- is turned off. When PostScript printers are networked, the clients
- must download any fonts desired <emphasis>with each print
- job</emphasis>. Since jobs come from different clients, the
- clients cannot assume that downloaded fonts will still be in the
- printer.</para>
-
- <para>PostScript print jobs also contain a header that is sent
- describing the page layout, among other things. On a shared network
- printer, this header must also be downloaded with each print job.
- Although some PostScript drivers allow downloading of the header
- only once, this usually requires a bi-directional serial connection
- to the printer, instead of a unidirectional parallel
- connection.</para>
-
- <para>PostScript print jobs can be sent either as binary data or as
- ASCII. The main advantage of binary data transmission is that it is
- faster. However, not all PostScript printers support it. Also,
- fonts can generally not be downloaded in binary. When FreeBSD is
- used as a printserver, ASCII PostScript printing should be selected
- on the clients, this is generally the default with most PostScript
- drivers.</para>
-
- <para>The Adobe company licenses PostScript interpreters as well as
- resident fonts to printer manufacturers, and extracts a hefty
- license fee from any printer manufacturer who wants to use them in
- its printer. This presents both a benefit and a problem to the end
- user. Although a single company holding control over a standard can
- guarantee compliance, it does significantly raise the cost of the
- printer. As a result, PostScript has not met with much success in
- the lower-end laser and inkjet Windows printing market, despite the
- fact that Adobe distributes PostScript software operating system
- drivers for free.</para>
-
- <para>One issue that is a concern when networking PostScript printers
- is the selection of banner page, (also known as header page, or
- <emphasis>burst page)</emphasis> printing. UNIX shared printing
- began with ASCII line printers, and since UNIX is a multiuser
- system, often many different user print jobs piled up in the printer
- output hopper. To separate these jobs the UNIX printing system
- programs support banner page printing if the client program that
- submits jobs asks for them. These pages print at the beginning or
- end of every print job and contain the username, submittal date, and
- so on.. By default, most clients, whether remote (e.g., a Windows
- LPR client) or local (e.g., the <command>/usr/bin/lpr</command>
- program) trigger a banner page to be printed. One problem is that
- some PostScript printers abort the entire job if they get
- unformatted ASCII text instead of PostScript. (In general,
- PostScript printers compatible with Hewlett-Packard Printer Control
- Language [HPPCL] handle banners without problems) Banner printing
- should be disabled for any printers with this problem, unless
- PostScript banner page printing is set up on the server.</para>
- </sect2>
-
- <sect2>
- <title>HPPCL Printing Protocol</title>
-
- <para>The Hewlett Packard company currently holds the largest market
- share of desktop inkjet and office laser printers. Back when
- Windows was released, HP decided to expand into the desktop laser
- jet market with the first LaserJet series of printers. At the time
- there was much pressure on Microsoft to use Adobe Type Manager for
- scalable fonts within Windows, and to print PostScript to
- higher-end printers. Microsoft decided against doing this and used
- a technically inferior font standard, Truetype. They thought that
- it would be unlikely that the user would download fonts to the
- printer, since desktop Publishing was not being done on PC's at the
- time. Instead users would rasterize the entire page to the printer
- using whatever proprietary graphics printer codes the selected
- printer needed. HP devised HPPCL for their LaserJets, and make
- PostScript an add-on. The current revision of HPPCL now allows for
- many of the same scaling and font download commands that PostScript
- does. HP laser jet printers that support PostScript can be
- distinguished by the letter "M" in their model number. (M is for
- Macintosh, since Macintosh requires PostScript to print) For
- example, the HP 6MP has PostScript, the 6P doesn't.</para>
-
- <para>HPPCL has almost no support in the UNIX applications market, and
- it is very unlikely that any will appear soon. One big reason is
- the development of the free <application>Ghostscript</application>
- PostScript interpreter. <application>Ghostscript</application> can
- take a PostScript input stream and print it on a PCL printer under
- UNIX. Another reason is the UNIX community's dislike of reinventing
- the wheel. HPPCL has no advantage over PostScript, and in many ways
- there are fewer problems with PostScript. Considering that
- PostScript can be added to a printer, either by hardware or use of
- <application>Ghostscript</application>, what is the point of
- exchanging an existing working solution for a slightly technically
- inferior one? Over the life of the printer, taking into account the
- costs of toner, paper, and maintenance, the initial higher cost of
- PostScript support is infinitesimal.</para>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-network">
- <title>Network Printing Basics</title>
-
- <para>The most common network printing implementation is a printserver
- accepting print jobs from clients tied to the server via a network
- cable.</para>
-
- <sect2>
- <title>Printservers</title>
-
- <para>The term "printserver" is one of those networking terms, like
- <emphasis>packet,</emphasis> that has been carelessly tossed around
- until its meaning has become somewhat confusing and blurred. To be
- specific, a printserver is simply a program that arbitrates print
- data from multiple clients for a single printer. Printservers can
- be implemented in one of the four methods described in the following
- sections.</para>
-
- <sect3>
- <title>Printserver on the fileserver</title>
-
- <para>The printer can be physically cabled to the PC running the
- Network OS. Print jobs are submitted by clients to the
- printserver software on the fileserver, which sends them down the
- parallel or serial cable to the printer. The printer must be
- physically close to the fileserver. This kind of printserving is
- popular in smaller workgroup networks, in smaller offices.</para>
-
- <figure>
- <title>Printserver on the fileserver</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-01" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> ,---------.
- | ======= | Server
- | ======= | +---------------------+ ,-----.
-+-----------+ | +---------------+ | | |
-| Printer [ ]------------[ ] | Printserver | | |_____|
-+-----------+ Parallel | | Software | [ ]------_________
- Cable | +---------------+ | / ::::::: \
- +---------------------+ `---------'
- Network PC</literallayout>
- </textobject>
-
- <textobject>
- <phrase>Printer, connected to a network server running
- printserver software, with one or more network PCs printing
- through it.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </sect3>
-
- <sect3>
- <title>Printserver on a separate PC</title>
-
- <para>It is possible to run a print server program on a cheap PC
- that is located next to the printer and plugged into it via
- parallel cable. This program simply acts as a pass-through
- program, taking network packets from the network interface and
- passing them to the printer. This kind of server doesn't allow
- any manipulation of print jobs, jobs usually come from a central
- fileserver, where jobs are controlled.</para>
-
- <figure>
- <title>Printserver on a separate PC</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-02" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> Fileserver
- ,----------------.
- ,---------. .---| | === |
- | ======= | ,-----. | `----------======'
- | ======= | | | |
- +-----------+ |_____| |
- | Printer [ ]------------_________---------| Ethernet
- +-----------+ Parallel / ::::::: \ |
- Cable `---------' |
- Printserver | ,-----.
- | | |
- | |_____|
- `---------_________
- / ::::::: \
- `---------'
- Network PC</literallayout>
- </textobject>
-
- <textobject>
- <phrase>Printer connected to a printserver (typically running
- FreeBSD), with network files hosted on a separate machine,
- and a network PC, able to access both resources.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </sect3>
-
- <sect3>
- <title>Printserver on a separate hardware box</title>
-
- <para>A printserver on a separate hardware box is exemplified by
- network devices such as the Intel Netport, the HP JetDirect Ex,
- the Osicom/DPI NETPrint, and the Lexmark MarkNet. Basically, these
- are plastic boxes with an Ethernet connection on one side and a
- parallel port on the other. Like a printserver on a PC, these
- devices don't allow remote job manipulation, and merely pass
- packets from the network down the parallel port to the
- printer.</para>
-
- <figure>
- <title>Printserver on a separate hardware box</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-03" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> Fileserver
- ,----------------.
- ,---------. .---| | === |
- | ======= | | `----------======'
- | ======= | Printserver |
- +-----------+ ,--------. |
- | Printer [ ]-----------[ ] ooo [ ]-------| Ethernet
- +-----------+ Parallel `--------' |
- Cable |
- | ,-----.
- | | |
- | |_____|
- `---------_________
- / ::::::: \
- `---------'
- Network PC</literallayout>
- </textobject>
-
- <textobject>
- <phrase>Printer connected to a dedicated print server
- <quote>appliance</quote>.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </sect3>
-
- <sect3>
- <title>Printserver in the Printer</title>
-
- <para>The HP JetDirect Internal is the best known printserver of
- this type. It is inserted into a slot in the printer case, and it
- works identically to the external JetDirect units.</para>
-
- <figure>
- <title>Printserver in the printer</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-04" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> Fileserver
- ,----------------.
- ,---------. .---| | === |
- | ======= | | `----------======'
- | ======= | |
- +-----------+ |
- | Printer [ ]------------------------------| Ethernet
- +-----------+ |
- |
- | ,-----.
- | | |
- | |_____|
- `---------_________
- / ::::::: \
- `---------'
- Network PC</literallayout>
- </textobject>
-
- <textobject>
- <phrase>Printer with an embedded print server, connecting
- directly to the local network.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Printspools</title>
-
- <para>Printspooling is an integral part of network printing. Since
- the PC can spit out data much faster than the printer can accept it,
- the data must be buffered in a spool at some location. In addition,
- because many clients share printers, when clients send print jobs at
- the same time, jobs must be placed on a queue so that one can be
- printed after the other.</para>
-
- <sect3>
- <title>Logical location of the print spool</title>
-
- <para>Printspooling can be implemented at one of three
- locations</para>
-
- <orderedlist>
- <listitem>
- <para>The client. Clients can be required to spool their own
- print jobs on their own disks. For example, when a Windows
- client application generates a print job the job must be
- placed on the local client's hard drive. Once the remote
- print server is free to accept the job it signals the client
- to start sending the job a bit at a time. Client spooling is
- popular in peer-to-peer networks with no defined central
- fileserver. However, it is impossible for a central
- administrator to perform advanced print job management tasks
- such as moving a particular print job ahead of another, or
- deleting jobs.</para>
- </listitem>
-
- <listitem>
- <para>The printserver. If each printer on the network is
- allocated their own combination print spooler-printserver,
- jobs can stack at the printer. Many of the larger printers
- with internal printservers have internal hard disks for this
- purpose. Although this enables basic job management, it still
- restricts the ability to move jobs from one printer to
- another.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>A central print spooler on a
- fileserver</emphasis>. Print jobs are received from all
- clients on the network in the spool and then dispatched to the
- appropriate printer. This scheme is the best for locations
- with several busy printers and many clients. Administration
- is extremely simple because all print jobs are spooled on a
- central server, which is particularly important in bigger
- organizations. Many large organizations have standardized on
- PostScript printing for all printing; in the event that a
- particular printer fails and is offline, incoming PostScript
- print jobs can be rerouted automatically to another printer.
- Since all printers and clients are using PostScript, clients
- don't need to be reconfigured when this happens. Print jobs
- appear the same whether printed on a 4 page-per-minute NEC
- Silentwriter 95, or a 24 page-per-minute HP LaserJet 5SiMX if
- both printers are defined in the client as PostScript
- printers.</para>
- </listitem>
- </orderedlist>
-
- <figure>
- <title>Print spool locations</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-05" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> Client
- ,---------. PC
- | ======= | ,-----.
- | ======= | | |
- +-----------+ |_____|
- | Printer [ ]---------------------------------------------------_________
- +-----------+ / ::::::: \
- `---------'
- Spool
-
- Printserver
- ,---------. PC
- | ======= | ,-----.
- | ======= | | |
- +-----------+ ,----------------. |_____|
- | Printer [ ]--------------| | === |-------------------_________
- +-----------+ `----------======' / ::::::: \
- Spool `---------'
-
-
- Fileserver
- ,---------. PC
- | ======= | ,-----.
- | ======= | Printserver Fileserver | |
- +-----------+ ,----------------. ,----------------. |_____|
- | Printer [ ]----| | === |-----| | === |------_________
- +-----------+ `----------======' `----------======' / ::::::: \
- Spool `---------'</literallayout>
- </textobject>
-
- <textobject>
- <phrase>Possible locations for the print spool</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>FreeBSD is an excellent platform to implement centralized
- printserving and print spooling. The rest of this chapter
- concentrates on the centralized print spooler model. Note that
- PostScript printing is not a requirement for this model--the HPPCL
- protocol can be the standard print protocol as well. For
- transparent printing between printers with HPPCL, however, the
- printer models must be similar.</para>
- </sect3>
-
- <sect3>
- <title>Physical location of the print spool</title>
-
- <para>In some companies, the central fileserver is often placed in a
- closet, locked away. Printers, on the other hand, are best
- located in high traffic areas for ease of use. Network printing
- works best when the printers are evenly distributed throughout the
- organization. Attempting to place all the major printers in one
- location, as technically advantageous as it may seem, merely
- provokes users to requisition smaller printers that are more
- convenient for that quick print job. The administrator may end up
- with a datacenter full of nice, expensive printers that are never
- used, while the smaller personal laser printers scattered
- throughout the plant bear most of the printing load.</para>
-
- <para>The big problem with this is that scattering printers through
- the organization makes it difficult to utilize the 3 possible
- parallel ports on the fileserver due to parallel port distance
- limitations. Although high-speed serial ports may extend the
- distance, not many printers have good serial ports on them. This
- is where the hardware network print server devices can come into
- play. I prefer using these devices because they are much cheaper
- and more reliable than a standalone PC running printserver
- software. For example, Castelle
- <ulink url="http://www.castelle.com/"></ulink>
- sells the LANpress 1P/10BT printserver for about $170.00. Using
- these devices a FreeBSD UNIX server can have dozens of print spools
- accepting print jobs and then route them back out over the network
- to these remote printserver boxes. If these hardware servers are
- used, they must support the Line Printer Daemon (LPD) print
- protocol.</para>
-
- <para>With a scheme like this it is important to have enough disk
- space on the spool to handle the print jobs. A single large
- PowerPoint presentation PostScript print job containing many
- graphics may be over 100MB. When many such jobs stack up in the
- print spool waiting to print, the print spooler should have
- several gigabytes of free disk space available.</para>
- </sect3>
-
- <sect3>
- <title>Network Printing to Remote Spools</title>
-
- <para>Although several proprietary network printing protocols such
- as Banyan Vines and NetWare, are tied to proprietary network protocols,
- FreeBSD UNIX can use two TCP/IP network printing protocols to
- print to remote print spools. The two print protocols available
- on TCP/IP with FreeBSD are the open LPD protocol and the
- NetBIOS-over-TCP/IP Server Messaging Block (SMB) print protocol
- first defined by Intel and Microsoft and later used by IBM and
- Microsoft.</para>
-
- <para>The LPD protocol is defined in RFC1179. This network protocol
- is the standard print protocol used on all UNIX systems. LPD
- client implementations exist for all Windows operating systems and
- DOS. Microsoft has written LPD for the Windows NT versions, the
- other Windows operating system implementations are provided by
- third parties.</para>
-
- <para>The Microsoft Networking network protocol that runs on top of
- SMB can use NetBIOS over TCP/IP as defined in RFC1001 and RFC1002.
- This protocol has a specification for printing that is the same
- print protocol used to send print jobs to NT Server by Microsoft
- clients. To implement this protocol on FreeBSD requires the
- installation of the Samba client suite of programs discussed in
- Chapter 7.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-lpr-windows">
- <title>Setting up LPR on Windows clients</title>
-
- <para>The program clients use to print via LPD is the Line Printer
- Remote, or LPR program. The following instructions cover enabling
- this program on Windows clients.</para>
-
- <sect2>
- <title>Windows 3.1/Windows for Workgroups 3.11</title>
-
- <para>Several commercial TCP/IP stacks are available for Win31, that
- provide LPR client programs, in addition to the basic TCP/IP
- protocol to Win31. WfW has TCP/IP networking available for free
- from Microsoft, but it doesn't include an LPR client. Unfortunately,
- I have not come across a freeware implementation of a 16-bit Windows
- LPR client, so with the following instructions I use the Shareware
- program WLPRSPL available from
- <ulink url="http://www.winsite.com/info/pc/win3/winsock/wlprs41.zip"></ulink>.
- This program must be active during client printing, and is usually
- placed in the Startup group.</para>
-
- <para>Organizations that want to use UNIX as a printserver to a group
- of Win31 clients without using a commercial or shareware LPR program
- have another option. The Microsoft Networking client for DOS used
- underneath Win31 contains SMB-based printing which is covered later
- in the chapter. DOS networking client setup and use are covered in
- Chapter 2 and Chapter 7.</para>
-
- <para>If LPR-based client printing is desired and the organization
- doesn't want to upgrade to Win95, (which has several LPR clients
- available) the following instructions can be used. WLPRSPL needs a
- Winsock under Windows 3.1, so for the example I explain the setup of
- the Novell 16-bit TCP/IP client. The stack can be FTPed from
- Novell, and is easy to integrate into sites that already use the
- 16-bit NetWare networking client, usually NW 3.11 and 3.12. In most
- cases, however, sites that use NetWare + Win31 are probably best off
- printing through the NetWare server, then loading an LPR spooler as
- an Netware Loadable Module (NLM) to send the job over to
- FreeBSD.</para>
-
- <para>As an alternate, the Microsoft Networking DOS 16-bit TCP/IP
- client under Win31 contains a Winsock, as does Microsoft TCP/IP for
- WfW. The target machine used here is a Compaq Deskpro 386/33 with
- 12MB of ram with an operating version of Windows 3.1, and a 3com
- 3C579 EISA network card. The instructions assume an LPR printserver
- on the network, named <hostid>mainprinter.my.domain.com</hostid>
- with a print queue named RAW.</para>
-
- <para>Use the installation instructions in Exhibit 8.1 for a quick and
- dirty TCP/IP Winsock for Win31 systems. Administrators who already
- have the Novell IPX client installed should skip those steps.</para>
- </sect2>
-
- <sect2>
- <title>Installation of the Novell TCP/IP Winsock client</title>
-
- <procedure>
- <step>
- <para>Make sure that the machine has enough environment space
- (2048 bytes or more) by adding the following line to the
- <filename>config.sys</filename> file and rebooting:</para>
-
- <programlisting>SHELL=C:\COMMAND.COM /E:2048 /P</programlisting>
- </step>
-
- <step>
- <para>Obtain the <filename>TCP16.EXE</filename> file from
- <ulink url="ftp://ftp3.novell.com/pub/updates/eol/nweol/tcp16.exe"></ulink>.</para>
- </step>
-
- <step>
- <para>Obtain the Network Adapter support diskette for the network
- card in your machine. This should be supplied with the card, or
- available via FTP from the network adapter manufacturer's FTP
- site.</para>
- </step>
-
- <step>
- <para>Now you need the file <filename>LSL.COM</filename>. This is
- available on some Network Adapter Driver diskettes, it used to
- be available from the <filename>VLM121_2.EXE</filename> file
- from Novell but unfortunately this file is no longer publicly
- accessible from Novell.</para>
- </step>
-
- <step>
- <para>If you have <filename>vlm121_2.exe</filename> in a temporary
- directory, run it. This will extract a number of files.</para>
- </step>
-
- <step>
- <para>One of the files extracted is <filename>LSL.CO_</filename>
- extract this file with the command <command>nwunpack
- lsl.co_</command>.</para>
- </step>
-
- <step>
- <para>Create the directory <filename>c:\nwclient</filename>. Then,
- copy <filename>lsl.com</filename> from the temporary directory
- into the directory.</para>
- </step>
-
- <step>
- <para>Obtain and install the printer driver for the model of
- printer that you will be spooling to and point it to
- <devicename>LPT1:</devicename>. Win31 and WfW 3.11 have an
- incomplete printer driver list, so if you need a driver
- Microsoft has many Win16 printer drivers on their FTP site. A
- list is available at
- <ulink url="ftp://ftp.microsoft.com/Softlib/index.txt"></ulink>.
- In addition, if you are installing a PostScript printer driver
- for a printer supplied in Win31, it may be necessary to patch
- the driver. The Microsoft PostScript driver supplied in Win31
- is version 3.5. (The patch named
- <filename>PSCRIP.EXE</filename> which brought the PostScript
- driver to version 3.58 is no longer publicly available.) WfW
- already uses the more recent PostScript driver, as does Win31
- version A. Installing the Adobe PostScript driver for Win31 is
- also an option. (see
- <ulink url="http://www.adobe.com/support/downloads/pdrvwin.htm"></ulink>
- for the version 3.1.2 Win31 PostScript driver).</para>
- </step>
-
- <step>
- <para>Look on the network adapter driver disk for the subdirectory
- <filename>nwclient/</filename> and then look for the ODI driver
- for the adapter card. For example, on the 3com 3C509/3C579
- adapter driver disk, the driver and location are
- <filename>\NWCLIENT\3C5X9.COM</filename>. Copy this driver to
- the <filename>c:\nwclient</filename> directory.</para>
- </step>
-
- <step>
- <para>Create a file called <filename>NET.CFG</filename> in the
- <filename>c:\nwclient</filename> directory. Often, the network
- card adapter driver diskette has a template for this file in the
- same location as the ODI driver. This can be modified, as can
- the following example:</para>
-
- <programlisting>LINK SUPPORT
-
-BUFFERS 4 1600
-
-MEMPOOL 8192
-
-LINK DRIVER
-3C5X9
-
-; PORT 300 (these are optional, if needed by card uncomment)
-
-; INT 10 (optional, uncomment and modify if needed)</programlisting>
- </step>
-
- <step>
- <para>Attempt to load the network card driver. First load
- <filename>lsl</filename>, then the ODI driver. With the 3com
- card the commands are:</para>
-
- <screen><userinput>lsl</userinput>
-<userinput>3c5x9</userinput></screen>
-
- <para>If the driver properly loads it will list the hardware port
- and interrupt settings for the network adapter. If it has
- loaded properly, unload the drivers in reverse order with the
- <option>/u</option> command:</para>
-
- <screen><userinput>3c5x9 /u</userinput>
-<userinput>lsl /u</userinput></screen>
- </step>
-
- <step>
- <para>Go to the temporary directory that contains the
- <filename>tcp16.exe</filename> file and extract it by running
- the program.</para>
- </step>
-
- <step>
- <para>Run the install batch file by typing
- <command>installr</command>. It should list <literal>New
- Installation detected</literal>. It will then copy a number
- of files into <filename>nwclient</filename>, add some
- commented-out sections to <filename>net.cfg</filename>, and call
- <command>edit</command> on <filename>net.cfg</filename>.</para>
- </step>
-
- <step>
- <para>Read the editing instructions and make the appropriate
- entries. The sample <filename>net.cfg</filename> file from
- above would look like this.</para>
-
- <programlisting>LINK SUPPORT
-
-BUFFERS 4 1600
-
-MEMPOOL 8192
-
-LINK DRIVER 3C5X9
-
-FRAME ETHERNET_II
-
-Protocol TCPIP
-
-PATH TCP_CFG c:\nwclient
-
-ip_address 192.168.1.54 LAN_NET
-
-ip_netmask 255.255.255.0 LAN_NET
-
-ip_router 192.168.1.1 LAN_NET
-
-Bind 3C5X9 #1 Ethernet_II LAN_NET</programlisting>
-
- <para>Save and exit, the Installer should list <literal>TCP16
- installation completed</literal>.</para>
- </step>
-
- <step>
- <para>Reload the client with the commands:</para>
-
- <screen><userinput>lsl</userinput>
-<userinput>3c5x9</userinput>
-<userinput>tcpip</userinput></screen>
-
- <para>The TCP/IP driver should list the IP numbers and other
- information.</para>
- </step>
-
- <step>
- <para>Optionally, create either a <filename>HOSTS</filename> file,
- or a <filename>RESOLV.CFG</filename> file (pointing to a
- nameserver) in <filename>c:\nwclient</filename>. Check to see
- this is operating properly by pinging a hostname.</para>
-
- <para>Add the <filename>c:\nwclient</filename> directory to the
- <envar>PATH</envar>, as well as the 3 startup commands in step
- 15 in <filename>autoexec.bat</filename></para>
- </step>
- </procedure>
- </sect2>
-
- <sect2>
- <title>Installation of the LPR client on 16-bit Windows with a Winsock
- installed</title>
-
- <para>The following assumes a running Win31 installation with a
- Winsock or a running WfW installation with the 32-bit Microsoft
- TCP/IP protocol installed.</para>
-
- <procedure>
- <step>
- <para>Install the printer driver desired. See step 8 of the
- previous set of instructions.</para>
- </step>
-
- <step>
- <para>Obtain and extract into a temporary directory the
- <filename>wlprs41.zip</filename> file from the location
- mentioned above.</para>
- </step>
-
- <step>
- <para>Run <command>setup.exe</command> from the temporary
- directory containing the <filename>wlprs</filename> files.
- </para>
- </step>
-
- <step>
- <para>In setup, accept default directory, and check Yes to add to
- its own group. Click <guibutton>Continue</guibutton> when asked
- for group name, and check whatever choice you want when asked to
- copy the <filename>doc</filename> files.</para>
- </step>
-
- <step>
- <para>Click <guibutton>No</guibutton> when asked to add the
- program to <literal>Startup</literal>.</para>
- </step>
-
- <step>
- <para>On the UNIX FreeBSD print spooler, make sure that there is
- an entry in <filename>/etc/hosts.lpd</filename> or
- <filename>/etc/hosts.equiv</filename> for the client
- workstation, thereby allowing it to submit jobs.</para>
- </step>
-
- <step>
- <para>Double-click the Windows LPR Spooler icon in the Windows LPR
- Spooler group that is opened. When it asks for a valid spool
- directory, just select the <filename>c:\wlprspl</filename>
- directory that the program installed its files into.</para>
- </step>
-
- <step>
- <para>When asked for a valid Queue Definition File, just click
- <guibutton>OK</guibutton> to use the default filename. The
- program automatically creates a queue definition file.</para>
- </step>
-
- <step>
- <para>The program opens up with its menu. Click
- <guibutton>Setup</guibutton> in the top menu, then select
- <guimenuitem>Define New Queue</guimenuitem>.</para>
- </step>
-
- <step>
- <para>For a local spool filename, just use the name of the remote
- queue (RAW) to which the client prints.</para>
- </step>
-
- <step>
- <para>For the remote printer name, use the same name as the remote
- queue (RAW) to which the client prints.</para>
- </step>
-
- <step>
- <para>For the remote hostname, use the machine name
- of the FreeBSD print spooler.
- <hostid role="fqdn"><replaceable>mainprinter.ayedomain.com</replaceable></hostid>.</para>
- </step>
-
- <step>
- <para>For the Description, enter a description such as
- <literal>3rd floor Marketing printer</literal>.</para>
- </step>
-
- <step>
- <para>For the protocol, leave the default of BSD LPR/LPD
- selected.</para>
- </step>
-
- <step>
- <para>Click on the <guimenuitem>Queue Properties</guimenuitem>,
- and make sure that the <guilabel>Print unfiltered</guilabel> is
- selected. If you're printing PostScript, then also click the
- <guibutton>Advanced options</guibutton> button. Make sure that
- <guilabel>Remove trailing Ctrl-D</guilabel> is
- <emphasis>unchecked</emphasis>, and that <guilabel>Remove
- Leading Ctrl-D</guilabel> is <emphasis>checked</emphasis>.
- Also with PostScript, if the printer cannot print ASCII, uncheck
- the <guilabel>Send header page</guilabel> box. (PostScript
- header/banner pages are discussed later in this chapter)</para>
- </step>
-
- <step>
- <para>Click <guibutton>OK</guibutton>. At the main menu of the
- program, click <guimenu>File</guimenu>, then <guimenu>Control
- Panel/Printers</guimenu> to bring up the Printers control
- panel of Windows.</para>
- </step>
-
- <step>
- <para>Make sure that the <guilabel>Use Print Manager</guilabel>
- button is checked, then highlight the printer driver and click
- the <guibutton>Connect</guibutton> button.</para>
- </step>
-
- <step>
- <para>Scroll down to the <guilabel>C:\WLPRSPL\RAW</guilabel> entry
- for the spool that was built and highlight this. Click
- <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Minimize the Windows LPR Spooler. Copy the Windows LPR
- Spooler icon to the Startup group. Click
- <guimenu>File/Properties</guimenu> with the Windows LPR Spooler
- icon highlighted in the Startup group. Check the <guilabel>Run
- Minimized</guilabel> button.</para>
- </step>
-
- <step>
- <para>Exit Windows, and when the <guibutton>Save queue
- changes?</guibutton> button comes up, click
- <guibutton>Yes</guibutton>.</para>
- </step>
-
- <step>
- <para>Restart windows and make sure that the spooler starts
- up.</para>
- </step>
-
- <step>
- <para>Open the Control Panel and look for a new yellow icon named
- <guiicon>Set Username</guiicon> If you are running the Novell or
- other Winsock under Win31, click on this icon and put the
- username of the person using this computer into the space
- provided. If you are running WfW, this isn't necessary because
- Windows will supply the username.</para>
- </step>
-
- <step>
- <para>If the spooler is not started properly in some
- installations, there may be a bug. If placing the icon in the
- Startup group doesn't actually start the spooler, the program
- name can be placed in the <literal>run=</literal> line of
- <filename>win.ini</filename>.</para>
- </step>
-
- <step>
- <para>Try printing a print job from an application such as
- Notepad. If everything goes properly, clicking on the
- <guimenuitem>Queues/Show remote printer status</guimenuitem>" in
- the Windows LPR menu should show the print job spooled and
- printing on the remote printserver.</para>
- </step>
- </procedure>
- </sect2>
-
- <sect2>
- <title>Installation of LPR client on Windows 95/98</title>
-
- <para>The <command>wlprspl</command> program also can be used under
- Windows 95, but as a 16-bit program, it is far from an optimal
- implementation on a 32-bit operating system. In addition, Win95 and
- its derivatives fundamentally changed from Windows 3.1 in the
- printing subsystem. For these reasons I use a different LPR client
- program for Win95/98 LPR printing instructions. It is a full 32-bit
- print program, and it installs as a <emphasis>Windows 32-bit
- printer</emphasis> <emphasis>port monitor</emphasis>. The program
- is called ACITS LPR Remote Printing for Windows 95 and it is located
- at <ulink url="http://shadowland.cc.utexas.edu/acitslpr.htm"></ulink>.</para>
-
- <para>ACITS stands for Academic Computing and Instructional
- Technologies Services. The ACITS LPR client includes software
- developed by the University of Texas at Austin and its contributors,
- it was written by Glenn K. Smith, a systems analyst with the
- Networking Services group at the university. The filename of the
- archive in the original program was ACITSLPR95.EXE and as of version
- 1.4 it was free for individuals or organizations to use for their
- internal printing needs. Since that time, it has gotten so popular
- that the university has taken over the program, incremented the
- version number (to get out from under the free license) and is now
- charging a $35 per copy fee for commercial use for the newer
- versions. The older free version can still be found on overseas FTP
- servers, such as
- <ulink url="http://www.go.dlr.de/fresh/pc/src/winsock/acitslpr95.exe"></ulink>.</para>
-
- <para>It is likely that the cost of a shareware/commercial LPR program
- for Win95 plus the cost of Win95 itself will meet or exceed that of
- Win2K. As such, users wishing to print via LPR to FreeBSD UNIX
- systems will probably find it cheaper to simply upgrade to Windows
- NT Workstation or Win2K.</para>
-
- <para>ACITS LPR and Win95 have a few printing idiosyncrasies. Most
- Win95 programs, such as Microsoft Word, expect print output to be
- spooled on the local hard drive and then metered out to a printer
- that is plugged into the parallel port. Network printing, on the
- other hand, assumes that print output will go directly from the
- application to the remote print server. Under Win95, local ports
- have a setting under Properties, Details, Spool Settings labeled
- "Print directly to the printer". If this is checked, the
- application running on the desktop (such as Microsoft Word) will not
- create a little Printer icon with pages coming out of it or use
- other means of showing the progress of the job as it is built. This
- can be very disconcerting to the user of a network printer, so this
- option should be checked only with printers plugged directly into
- the parallel port. Worse, if this is checked with ACITS, it can
- cause the job to abort if the remote print spooler momentarily goes
- offline.</para>
-
- <para>Another local setting also should be changed. Generally, with
- local ports, Win95 builds the first page in the spooler and then
- starts printing it while the rest of the pages spool. If ACITS
- starts printing the first page while the rest of the pages are
- building, timeouts at the network layer can sometimes cause very
- large jobs to abort. The entire job should be set to completely
- spool before the LPR client passes it to the UNIX spooler. The
- problem is partly the result of program design: because ACITS is
- implemented as a local printer port instead of being embedded into
- Win95 networking (and available in Network Neighborhood) the program
- acts like a local printer port in some ways.</para>
-
- <para>The LPR program can be set to deselect banner/burst page
- printing if a PostScript printer that cannot support ASCII is used.
- The burst pages referred to here are NOT generated by the Windows
- machine. Use the instructions in Exhibit 8.3 to install ACITS.</para>
-
- <procedure>
- <title>LPR client on Win95/98 installation instructions</title>
-
- <step>
- <para>Obtain the <filename>ACITSLPR95.EXE</filename> file and
- place it in a temporary directory such as
- <filename>c:\temp1</filename>.</para>
- </step>
-
- <step>
- <para>Close all running programs on the desktop. The computer
- <emphasis>must</emphasis> be rebooted at completion of
- installation or the program will not work.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Start</guibutton>,
- <guimenuitem>Run</guimenuitem> and type in
- <userinput>c:\temp1\acitslpr95</userinput> then click
- <guibutton>Yes</guibutton> at the InstallShield prompt.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Next</guibutton>, then
- <guibutton>Yes</guibutton>. The program will run through some
- installation and then presents a Help screen that explains how
- to configure an LPR port.</para>
- </step>
-
- <step>
- <para>After the help screen closes, the program asks to reboot the
- system. Ensure that <guilabel>Yes</guilabel> is checked and
- click <guibutton>Finish</guibutton> to reboot.</para>
- </step>
-
- <step>
- <para>After the machine comes back up, install a Printer icon in
- the <guibutton>Start</guibutton>, <guimenu>Settings</guimenu>,
- <guimenuitem>Printers</guimenuitem> folder if one hasn't been
- created for the correct model of destination printer.</para>
- </step>
-
- <step>
- <para>With the Printers folder open, right-click over the printer
- icon that needs to use the LPR program and click on the
- <guilabel>Properties</guilabel> tab.</para>
- </step>
-
- <step>
- <para>Under the <guilabel>Details</guilabel> tab, click the
- <guilabel>Add Port</guilabel> tab, then click
- <guibutton>Other</guibutton>.</para>
- </step>
-
- <step>
- <para>Highlight the <guilabel>ACITS LPR Remote Printing</guilabel>
- line and click <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>The Add ACITS LPR screen opens. Type in the hostname of the
- UNIX system that the client spools through&mdash;
- <hostid role="fqdn"><replaceable>mainprinter.ayedomain.com</replaceable></hostid>.</para>
- </step>
-
- <step>
- <para>Type in the Printer/Queue name and click
- <guibutton>OK</guibutton>. (Some versions have a "Verify Printer
- Information" button.) The LPR program then contacts the UNIX
- host and makes sure that the selected printer is
- available.</para>
-
- <note>
- <para>If this fails the client machine name is probably not in
- the <filename>/etc/hosts.equiv</filename> or
- <filename>etc/hosts.lpd</filename> on the FreeBSD printserver.
- Most sites may simply decide to put a wildcard in
- <filename>hosts.equiv</filename> to allow printing, especially
- if DHCP is used, but many security-conscious sites may stick
- with individual entries in
- <filename>hosts.lpd</filename>.</para>
- </note>
- </step>
-
- <step>
- <para>If the printer is PostScript and cannot print ASCII, make
- sure that the "No banner page control flag" is checked to turn
- off banner pages. Accessible under Port settings, this flag is
- overridden if the <filename>/etc/printcap</filename> file
- specifies no banner pages.</para>
- </step>
-
- <step>
- <para>Review how the "send plain text control flag" is set. With
- this flag unchecked, the LPR code sent is L, (i.e., print
- unfiltered) meaning that the <literal>if</literal> filter gets
- called with the <option>-c</option> option. This is equivalent
- to the local invocation of <filename>/usr/bin/lpr -l</filename>.
- With the flag checked, the code is F, (formatted) meaning that
- the <literal>if</literal> filter gets called without the
- <option>-c</option> option. This is equivalent to the default
- invocation <filename>/usr/bin/lpr</filename>. (This is also an
- issue under Windows NT, which retypes the print job to text if
- this flag is checked. Some filters understand the
- <option>-c</option> flag, which is used to preserve control
- characters, so it should generally remain unchecked.</para>
- </step>
-
- <step>
- <para>Leave the "Send data file before control file" box
- unchecked. This option is used only in rare mainframe spooling
- circumstances.</para>
- </step>
-
- <step>
- <para>Click <guibutton>OK</guibutton>, then click the
- <guibutton>Spool Settings</guibutton> button at the properties
- page.</para>
- </step>
-
- <step>
- <para>Make sure that the "Spool print jobs so program finishes
- printing faster" box is checked.</para>
- </step>
-
- <step>
- <para>Make sure that "Start printing after last page is spooled"
- box is checked.</para>
- </step>
-
- <step>
- <para>Make sure that "Disable bi-directional support for this
- printer" is checked, or greyed out.</para>
- </step>
-
- <step>
- <para>Make sure that the "Spool data format" is set to RAW. Some
- printer drivers present a choice of EMF or RAW, such as the
- Generic Text driver, in this case select RAW.</para>
- </step>
-
- <step>
- <para>Click <guibutton>OK</guibutton>, then
- <guibutton>OK</guibutton> again to close the Printer Properties.
- The printer icon now spools through FreeBSD.</para>
- </step>
- </procedure>
- </sect2>
-
- <sect2>
- <title>Installation of LPR client on Windows NT</title>
-
- <para>Unlike WfW and Win95 TCP/IP, Windows NT&mdash;both server and
- workstation&mdash;includes an LPR client as well as an LPD program
- that allows incoming print jobs to be printed from LPR clients, such
- as UNIX systems.</para>
-
- <para>To install the LPR client and daemon program under Windows NT
- 3.51, use the following instructions. The TCP/IP protocol should be
- installed beforehand and you must be logged in to the NT system as
- Administrator. This can be done at any time after the NT system is
- installed, or during OS installation:</para>
-
- <procedure>
- <step>
- <para>Double-click on Main, Control Panel, then
- Network Settings.</para>
- </step>
-
- <step>
- <para>In the Installed Network Software window, "Microsoft TCP/IP
- Printing" should be listed as well as "TCP/IP Protocol". If it
- is, stop here; otherwise continue.</para>
- </step>
-
- <step>
- <para>Click the <guibutton>Add Software</guibutton> button to get
- the Add Network Software dialog box</para>
- </step>
-
- <step>
- <para>Click the down arrow and select TCP/IP Protocol and related
- components. Click <guibutton>Continue</guibutton>.</para>
- </step>
-
- <step>
- <para>Check the "TCP/IP Network Printing Support" box and click
- <guibutton>Continue</guibutton>. LPR printing is now installed.
- Follow the instructions to reboot to save changes.</para>
- </step>
- </procedure>
-
- <para>To install the LPR client and daemon program under Windows NT 4,
- use the following instructions. The TCP/IP protocol should be
- installed beforehand and you must be logged in to the NT system as
- Administrator. This can be done at any time after the NT system is
- installed, or during OS installation:</para>
-
- <procedure>
- <step>
- <para>Click on <guibutton>Start</guibutton>,
- <guimenuitem>Settings</guimenuitem>, <guimenuitem>Control
- Panel</guimenuitem>, and double-click on
- <guiicon>Network</guiicon> to open it up.</para>
- </step>
-
- <step>
- <para>Click on the <guilabel>Services</guilabel> tab.
- <literal>Microsoft TCP/IP Printing</literal> should be listed.
- If not, continue steps 3 - 4.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Add</guibutton>, then select
- <guilabel>Microsoft TCP/IP Printing</guilabel> and click
- <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Close</guibutton>. Follow instructions to
- reboot to save changes.</para>
-
- <note>
- <para>Any NT Service Packs that were previously installed must
- be reapplied after these operations.</para>
- </note>
- </step>
- </procedure>
-
- <para>Once LPR printing has been installed, the Printer icon or icons
- must be created on the NT system so that applications can print.
- Since this printer driver does all job formatting before passing the
- printing to the FreeBSD printserver, the print queues specified
- should be raw queues on the FreeBSD system, which don't do any job
- formatting.</para>
-
- <para>To install the printer icon in Print Manager and set it to send
- print jobs to the FreeBSD UNIX system, use the following
- instructions under NT 3.51. You must be logged in to the NT system
- as Administrator. This can be done at any time after the NT system
- is installed, or during OS installation.</para>
-
- <procedure>
- <step>
- <para>Click on Main, and open it. Then click on Print Manager to
- open it.</para>
- </step>
-
- <step>
- <para>Click on <guiicon>Printer</guiicon>, <guibutton>Create
- Printer</guibutton>. Select the appropriate printer
- driver.</para>
- </step>
-
- <step>
- <para>Click the down arrow under Print To and select
- Other.</para>
- </step>
-
- <step>
- <para>In the Available Print Monitors window select
- LPR port and click <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Enter the hostname of the FreeBSD printserver, and the name
- of the printer queue and click <guibutton>OK</guibutton></para>
- </step>
-
- <step>
- <para>Click <guibutton>OK</guibutton> to close the Create Printer
- window. The Printer icon is created.</para>
- </step>
- </procedure>
-
- <para>To install the printer icon in Print Manager and set it to send
- print jobs to the FreeBSD UNIX system, use the following
- instructions under NT 4. You must be logged in to the NT system as
- Administrator. This can be done at any time after the NT system is
- installed, or during OS installation:</para>
-
- <procedure>
- <step>
- <para>Click <guibutton>Start</guibutton>,
- <guimenuitem>Settings</guimenuitem>,
- <guimenuitem>Printers</guimenuitem> to open the printer
- folder.</para>
- </step>
-
- <step>
- <para>Double-click <guiicon>Add Printer</guiicon> to start the
- wizard.</para>
- </step>
-
- <step>
- <para>Select the My Computer radio button, not the Network
- Print Server button and click <guibutton>Next</guibutton>. (The
- printer <emphasis>is</emphasis> a networked printer, it is
- managed on the local NT system. Microsoft used confusing
- terminology here.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Add Port</guibutton> and select LPR Port,
- then click <guibutton>New Port</guibutton>.</para>
- </step>
-
- <step>
- <para>Enter the hostname and print queue for the FreeBSD
- printserver and click <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Click <guibutton>Next</guibutton> and select the correct
- printer driver. Continue until the printer is set up.</para>
- </step>
- </procedure>
-
- <para>The LPR client in Windows NT allows DOS print jobs originating
- in DOS boxes to be routed to the central UNIX print spooler. This
- is an advantage over the Win95 and WfW LPR programs.</para>
-
- <sect3>
- <title>Windows NT Registry Changes</title>
-
- <para>Using the LPR daemon program under Windows NT presents one
- problem. If the NT server is used as an LPR/LPD "relay", for
- example, to pass jobs from clients to LPR print queues on a UNIX
- system, to pass jobs from LPR programs on UNIX terminating at NT
- print queues, or to pass jobs from Appletalk clients to LPR
- printers, NT retypes the job if the type code is set to P (text).
- This can wreak havoc on PostScript files printed through HP
- LaserJet printers with internal MIO cards in them, if the job
- originates from the <filename>/usr/bin/lpr</filename> program
- under UNIX, which assigns a P type code. The printserver card
- treats PostScript jobs as text, and instead of the print job, the
- raw PostScript codes print. This problem often manifests in the
- following way: <filename>/usr/bin/lpr</filename> is used to print
- a PostScript file from UNIX directly to the remote printer
- printserver, which works fine, but spooling it through NT causes
- problems.</para>
-
- <para>A registry change that can override the NT Server formatting
- behavior is detailed in Microsoft Knowledge Base article ID
- Q150930. With Windows NT 3.51, and 4.0 up to service pack 1 the
- change is global. Starting with NT 4.0 Service pack 2 the change
- can be applied to specific print queues, (see Knowledge Base
- article ID Q168457). This registry change also works for
- Windows 2000.</para>
-
- <para>Under Windows NT 4.0, the change is:</para>
-
- <procedure>
- <step>
- <para>Run Registry Editor
- (<filename>REGEDT32.EXE</filename>)</para>
- </step>
-
- <step>
- <para>From the <literal>HKEY_LOCAL_MACHINE</literal> subtree, go
- to the following key:</para>
-
- <para><literal>\SYSTEM\CurrentControlSet\Services\LPDSVC\Parameters</literal></para>
- </step>
-
- <step>
- <para>On the <guimenu>Edit</guimenu> menu, click
- <guimenuitem>Add Value</guimenuitem>.</para>
- </step>
-
- <step>
- <para>Add the following:</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>Value Name:</entry>
- <entry>SimulatePassThrough</entry>
- </row>
-
- <row>
- <entry>Data Type:</entry>
- <entry>REG_DWORD</entry>
- </row>
-
- <row>
- <entry>Data</entry>
- <entry>1</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <note>
- <para>The default value is 0, which informs LPD to assign
- datatypes according to the control commands.</para>
- </note>
- </step>
- </procedure>
-
- <para>Under Windows NT 3.51, the change is:</para>
-
- <procedure>
- <step>
- <para>Run Registry Editor
- (<filename>REGEDT32.EXE</filename>)</para>
- </step>
-
- <step>
- <para>From the <literal>HKEY_LOCAL_MACHINE</literal> subtree, go
- to the following key:</para>
-
- <para><literal>\SYSTEM\CurrentControlSet\Services\LPDSVC\Parameters</literal></para>
- </step>
-
- <step>
- <para>On the <guimenu>Edit</guimenu> menu, click
- <guimenuitem>Add Value</guimenuitem>.</para>
- </step>
-
- <step>
- <para>Add the following:</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>Value Name:</entry>
- <entry>SimulatePassThrough</entry>
- </row>
-
- <row>
- <entry>Data Type:</entry>
- <entry>REG_DWORD</entry>
- </row>
-
- <row>
- <entry>Data</entry>
- <entry>1</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <note>
- <para>The default value is 0, which informs LPD to assign
- datatypes according to the control commands.</para>
- </note>
- </step>
-
- <step>
- <para>Create an LPD key at the same level as the LPDSVC
- key.</para>
- </step>
-
- <step>
- <para>Click the LPDSVC Key, click <guimenuitem>Save
- Key</guimenuitem> from the <guimenu>Registry</guimenu> menu,
- and then save the file as
- <filename>LPDSVC.KEY</filename></para>
- </step>
-
- <step>
- <para>Click the LPD key created in step 5.</para>
- </step>
-
- <step>
- <para>Click <guimenuitem>Restore</guimenuitem> on the
- <guimenu>Registry</guimenu> menu, click the file created in
- step 6, and then click <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>A warning message appears. Click
- <guibutton>OK</guibutton> and then quit the Registry
- Editor.</para>
- </step>
-
- <step>
- <para>At a command prompt window, type:</para>
-
- <screen><userinput>net stop lpdsvc</userinput>
-<userinput>net start lpdsvc</userinput></screen>
- </step>
- </procedure>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-ps-dos">
- <title>Printing PostScript and DOS command files</title>
-
- <para>One problem with printing under Win31 and Win95 with the LPR
- methods discussed is the lack of a <quote>raw</quote>
- <devicename>LPT1:</devicename> device. This is annoying to the
- administrator who wants to print an occasional text file, such as a
- file full of printer control codes, without their being intercepted by
- the Windows printer driver. Of course this is also an issue with DOS
- programs, but a commercial site that runs significant DOS software and
- wants to print directly to UNIX with LPR really only has one
- option&mdash;to use a commercial TCP/IP stack containing a DOS LPR
- program.</para>
-
- <para>Normally, under Windows printing, virtually all graphical programs
- print through the Windows printer driver. This is true even of basic
- programs such as Notepad. For example, an administrator may have a
- DOS batch file named <filename>filename.txt</filename> containing the
- following line:</para>
-
- <programlisting>echo \033&amp;k2G &gt; lpt1:</programlisting>
-
- <para>This batch file switches a HP LaserJet from CR-LF, MS-DOS
- textfile printing into Newline termination UNIX textfile printing.
- Otherwise, raw text printed from UNIX on the HP prints with a
- stairstep effect.</para>
-
- <para>If the administrator opens this file with Notepad and prints it
- using a regular printer driver, such as an Epson LQ, the Windows
- printer driver encapsulates this print output into a series of
- printer-specific control codes that do things such as initialize the
- printer, install fonts, and so on. The printer won't interpret this
- output as control code input. Usually, if the printer is locally
- attached, the user can force a "raw text print" of the file by opening
- a DOS window and running:</para>
-
- <screen><userinput>copy filename.txt lpt1: /b</userinput></screen>
-
- <para>Since the LPR client program doesn't provide a DOS driver, it
- cannot reroute input from the <devicename>LPT1:</devicename> device
- ports. The solution is to use the Generic / Text Only printer driver
- in conjunction with Wordpad (under Win95); under Win31 use a different
- text editor. The Notepad editor supplied with Windows is unsuitable
- for this - it "helpfully" inserts a 1 inch margin of spaces around all
- printed output, as well as the filename title. Wordpad supplied with
- Win95, can be set to use margins of zero, and inserts no additions
- into the printed output. Also, make sure that banner pages are turned
- off, and the print type is set to raw.</para>
- </sect1>
-
- <sect1 id="printserving-psprinter">
- <title>Checking PostScript Printer capabilities</title>
-
- <para>Following is a PostScript command file that can be used to get a
- PostScript printer to output a number of useful pieces of information
- that are needed to set up a printer icon under Windows properly. It
- was printed from Wordpad, in Win95, through the Generic / Text Only
- printer driver with the following instructions:</para>
-
- <procedure>
- <step>
- <para><guibutton>Start</guibutton>, <guimenuitem>Run</guimenuitem>,
- type in <userinput>Wordpad</userinput> and press
- <keycap>Enter</keycap>.</para>
- </step>
-
- <step>
- <para><guimenu>File</guimenu>, <guimenuitem>Open</guimenuitem>
- <filename>testps.txt</filename></para>
- </step>
-
- <step>
- <para><guimenu>File</guimenu>, <guimenuitem>Page
- Setup</guimenuitem>, <guimenuitem>Printer</guimenuitem>, select
- <guimenuitem>Generic / Text Only</guimenuitem>, click
- <guibutton>Properties</guibutton></para>
- </step>
-
- <step>
- <para>Click <guimenuitem>Device Options</guimenuitem>, select
- <guilabel>TTY custom</guilabel>, click
- <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Click <guibutton>OK</guibutton>, then set all four margins to
- <literal>0</literal>; click <guibutton>OK</guibutton>.</para>
- </step>
-
- <step>
- <para>Click <guimenu>File</guimenu>,
- <guimenuitem>Print</guimenuitem>,
- <guibutton>OK</guibutton>.</para>
- </step>
- </procedure>
-
- <para>This could also have been printed with
- <filename>/usr/bin/lpr</filename> on a UNIX command prompt. The file
- prints <emphasis>Test Page</emphasis> and some printer statistics
- below that, as follows.</para>
-
- <programlisting>% filename: testps.txt
-% purpose: to verify proper host connection and function of PostScript
-% printers.
-/buf 10 string def
-/CM {
-save statusdict/product get (PostScript) anchorsearch
-exch pop {length 0 eq
-{1}{2}ifelse
-}
-{2}ifelse exch restore
-}bind def
-/isCM {
-CM 1 ge
-}bind def
-/Times-BoldItalic findfont 75 scalefont setfont
-150 500 moveto
-(Test Page) false charpath
-isCM{gsave 0.0 1.0 1.0 0.0 setcmykcolor fill grestore}if
-2 setlinewidth stroke
-/Times-Roman findfont 10 scalefont setfont
-150 400 moveto
-(Your PostScript printer is properly connected and operational.)show
-150 380 moveto
-(The border around the page indicates your printer's printable region.)show
-{ vmreclaim } stopped pop
-vmstatus exch sub exch pop
-150 360 moveto
-(Max Available Printer Virtual Memory (KB):)show
-150 340 moveto
-dup 1024 div truncate buf cvs show
-150 320 moveto
-(Calculated memory size used for PostScript printer icon properties:) show
-150 300 moveto
-0.85 mul 1024 div truncate buf cvs show
-150 280 moveto
-(Printer Model: )show
-statusdict begin product show end
-150 260 moveto
-(PostScript Level: )show
-/languagelevel where
-{ languagelevel 3 string cvs show pop }
-{(1) show } ifelse
-150 240 moveto
-(PostScript Version: )show
-statusdict begin
-version show (.)show
-revision 40 string cvs show end
-clippath stroke
-showpage</programlisting>
- </sect1>
-
- <sect1 id="printserving-lpr-freebsd">
- <title>Setting up LPR/LPD on FreeBSD</title>
-
- <para>When a FreeBSD system is booted, it starts the LPD spooler control
- daemon program if the <filename>/etc/rc.conf</filename> file has
- <literal>lpd_enable="YES"</literal> set. If this is not set, attempts
- to print through and from the FreeBSD system will fail with an
- <errorname>lpr: connect: No such file or directory</errorname> error
- message.</para>
-
- <para>The LPD program manages all incoming print jobs, whether they come
- in from the network, or from local users on the UNIX system. It
- transfers print jobs to all locally attached parallel or serial
- printers, as well as defined remote printers. Several programs also
- are used to manipulate jobs in the print spools that LPD manages, as
- well as the user programs to submit them from the UNIX command prompt.
- All of these programs use the <filename>/etc/printcap</filename> file,
- which is the master control file for the printing system.</para>
-
- <para>Back when printing was mostly text, it was common to place
- printers on a serial connection that stretched for long distances.
- Often, 9600bps was used because it could work reliably up to a block
- away, which allowed printers to be located almost anywhere on an
- office high-rise floor. Modern office print jobs, on the other hand,
- are generally graphics-laden and tend to be rather large. These jobs
- would take hours to transfer over a slower 9600bps serial printer
- connection. Today, most printers that are not connected to a remote
- hardware print server box are directly connected to the server using
- parallel cables. All of the examples shown here are direct
- connections that are parallel connections.</para>
-
- <para>The <filename>printcap</filename> configuration file, like most
- UNIX configuration files, indicates comment lines starting with a hash
- character. Lines without a hash character are meant to be part of a
- printer queue description line. Each printer queue description line
- starts with a symbolic name, and ends with a newline. Since the
- description lines are often quite long, they are often written to span
- multiple lines by escaping intermediate newlines with the backslash
- (<literal>\</literal>) character. The
- <filename>/etc/printcap</filename> file, as supplied, defines a single
- printer queue, <literal>lp</literal>. The <literal>lp</literal> queue
- is the default queue. Most UNIX-supplied printing utilities send
- print output to this queue if no printer is specified by the user. It
- should be set to point to the most popular print queue with
- <emphasis>local</emphasis> UNIX print users, (i.e., users that have
- shell accounts).</para>
-
- <para>The layout of <filename>/etc/printcap</filename> is covered in the
- manual page, which is reached by running the <userinput>man
- printcap</userinput> command. The stock
- <filename>/etc/printcap</filename> file at the line defining the spool
- <literal>lp</literal> shows:</para>
-
- <programlisting>#
-lp|local line printer:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
-#</programlisting>
-
- <para>In this example the first line defines the names by which the
- printer is known, and ends with an escaped newline. The next line
- defines the physical device, the PC parallel port, by
- <filename>/dev/lpt0</filename>, and the directory in which the spool
- files are stored at <filename>/var/spool/output/lpd</filename>, and
- the error log file. Note that this particular error log file will not
- show all LPD errors, such as bad job submittals, it usually shows only
- the errors that originate within the printing system itself.</para>
-
- <para>In general, the administrator creates two print queues for every
- printer that is connected to the FreeBSD machine. The first queue
- entry contains whatever additional capabilities UNIX shell users on
- the server require. The second is a raw queue that performs no print
- processing on the incoming print job. This queue is used by remote
- clients, such as Windows clients, that format their own jobs.</para>
-
- <para>If the administrator is setting up the printer to allow incoming
- LPR jobs from network clients, such as other Windows or UNIX systems,
- those systems <emphasis>must</emphasis> be listed in
- <filename>/etc/hosts.lpd</filename>.</para>
-
- <sect2>
- <title>Creating the spools</title>
-
- <para>Building new print spools is merely a matter of making an entry
- in the <filename>/etc/printcap</filename> file, creating the spool
- directories, and setting the correct permissions on them. For
- example, the following additional line defines a PostScript printer
- named NEC (in addition to the <literal>lp</literal>
- definition):</para>
-
- <programlisting>#
-lp|local line printer:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
-
-NEC|NEC Silentwriter 95 PostScript printer:\
- :lp=/dev/lpt0:sd=/var/spool/output/NEC:lf=/var/log/lpd-errs:
-#</programlisting>
-
- <para>Because UNIX is case sensitive, NEC is different from
- <literal>nec</literal> in both the name of the printer and the name
- of the Spool directory. With the print spooler LPD, the Spool
- directories <emphasis>must</emphasis> be different from each other,
- or the spooler gets confused and doesn't print.</para>
-
- <para>After the <filename>/etc/printcap</filename> is modified, the
- root user must create the <filename>/var/spool/output/NEC</filename>
- directory and assign ownership of it to the <username>bin</username>
- user, assign group ownership to <username>daemon</username>, and set
- permissions with the following commands:</para>
-
- <screen>&prompt.user; <userinput>su root</userinput>
-&prompt.root; <userinput>cd /var/spool/output</userinput>
-&prompt.root; <userinput>mkdir NEC</userinput>
-&prompt.root; <userinput>chown bin NEC</userinput>
-&prompt.root; <userinput>chgrp daemon NEC</userinput>
-&prompt.root; <userinput>chmod 755 NEC</userinput></screen>
- </sect2>
-
- <sect2>
- <title>Additional spool capabilities</title>
-
- <para>Because modern print jobs (especially PostScript) can sometimes
- reach hundreds of megabytes, the <literal>sd</literal> capability
- entry in the <filename>/etc/printcap</filename> file should always
- point to a Spool directory on a filesystem that has enough space.
- The <filename>/var</filename> directory on a default FreeBSD
- installation is generally set to a fairly small amount, which can
- easily overflow the spool. There are four ways to handle this
- problem:</para>
-
- <orderedlist>
- <listitem>
- <para>During FreeBSD installation, if the administrator knows a
- lot of print jobs are going to go through the spooler,
- <filename>/var</filename> should be set to a large
- amount of free space.</para>
- </listitem>
-
- <listitem>
- <para>Modify the <literal>sd</literal> capability in the
- <filename>/etc/printcap</filename> file to point to a spool
- directory in a different, larger filesystem, such as
- <filename>/usr/spool</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Use soft links to point the
- <filename>/var/spool/output</filename> directory to directories
- on a larger filesystem.</para>
- </listitem>
-
- <listitem>
- <para>Don't define a <filename>/var</filename> directory at all
- during FreeBSD installation; this would make the installer link
- <filename>/var</filename> to
- <filename>/usr/var</filename>.</para>
- </listitem>
- </orderedlist>
-
- <para>In addition to spools, the following other capabilities are
- usually placed in a production
- <filename>/etc/printcap</filename> file.</para>
-
- <para>The entry <literal>fo</literal> prints a form feed when the
- printer is opened. It is handy for HPPCL (HP LaserJets) or other
- non-PostScript printers that are located behind electronic print
- sharing devices. It can also be used for printers that accept input
- from multiple connections, such as a parallel port, serial port, and
- localtalk port. An example is an HP LaserJet with an MIO card in it
- plugged into both Ethernet and LocalTalk networks. It will clear
- any garbage out of the printer before the job is processed.</para>
-
- <para>The entry <literal>mx</literal> defines the maximum size of a
- print job, which is a must for modern print jobs that frequently
- grow far past the default print size of a megabyte. The original
- intent of this capability was to prevent errant programs from
- stuffing the spool with jobs so large that they would use up all
- paper in a printer. Graphics-heavy print jobs have made it
- impossible to depend on this kind of space limitation, so
- <literal>mx</literal> is usually set to zero, which turns it
- off.</para>
-
- <para>The entry <literal>sh</literal> suppresses printing of banner
- pages in case the printer cannot handle ASCII and the client
- mistakenly requests them.</para>
-
- <para>The entry <literal>ct</literal> denotes a TCP Connection
- timeout. This is useful if the remote print server doesn't close
- the connection properly.</para>
-
- <note>
- <para>FreeBSD 2.2.5 contains a bug in the LPD system - as a
- workaround the <literal>ct</literal> capability needs to be set
- very large, such as 3600, or the appropriate patch installed and
- LPD recompiled. More recent versions of FreeBSD do not have this
- bug.</para>
- </note>
- </sect2>
-
- <sect2>
- <title>Printing to hardware print server boxes or remote print
- servers.</title>
-
- <para>Hardware print server boxes, such as the HP JetDirect internal
- and external cards, need some additional capabilities defined in the
- <filename>/etc/printcap</filename> entry; <literal>rp</literal>, for
- remote print spool, and <literal>rm</literal> for remote machine
- name.</para>
-
- <para>The <literal>rm</literal> capability is simply the DNS or
- <filename>/etc/hosts</filename> name of the IP number associated
- with the remote printserver device. Obviously, print server
- devices, such as the HP JetDirect, must not use a dynamic TCP/IP
- network numbering assignment. If they get their numbering via DHCP,
- the IP number should be assigned from the static pool; it should
- always be the same IP number.</para>
-
- <para>Determining the name used for <literal>rp</literal>, on the
- other hand, can be rather difficult. Here are some common
- names:</para>
-
- <para>Windows NT Server: Printer name of the printer icon created in
- Print Manager</para>
-
- <para>FreeBSD: Print queue name defined in
- <filename>/etc/printcap</filename></para>
-
- <para>HP JetDirect: Either the name <literal>TEXT</literal> or the
- name <literal>RAW</literal>. <literal>TEXT</literal> automatically
- converts incoming UNIX newline text to DOS-like CR/LF text that the
- printer can print. <literal>RAW</literal> should be used for
- PostScript, and HPPCL printing.</para>
-
- <para>HP JetDirect EX +3: External, 3 port version of the JetDirect.
- Use <literal>RAW1</literal>, <literal>RAW2</literal>,
- <literal>RAW3</literal>, <literal>TEXT1</literal>,
- <literal>TEXT2</literal>, or <literal>TEXT3</literal> depending on
- the port desired.</para>
-
- <para>Intel NetPort: Either use <literal>TEXT</literal> for UNIX text
- conversion printing or use <literal>PASSTHRU</literal> for normal
- printing.</para>
-
- <para>DPI: Use <literal>PORT1</literal> or <literal>PORT2</literal>
- depending on which port the printer is plugged into.</para>
-
- <para>For other manufacturer's print servers refer to the manuals
- supplied with those devices.</para>
-
- <para>The following is an example printcap that redefines the default
- <literal>lp</literal> print queue to send print jobs to the first
- parallel port on a remote HP LaserJet plugged into a JetDirect EX +3
- named <hostid role="fqdn">floor2hp4.biggy.com</hostid>.</para>
-
- <programlisting>#
-lp|local line printer:\
- :rm=floor2hp4.biggy.com:rp=RAW1:\
- :sd=/var/spool/output/lpd:\
- :lf=/var/log/lpd-errs:
-#</programlisting>
-
- <note>
- <para>The <literal>rp</literal> capability <emphasis>must</emphasis>
- be defined or the job goes to the default print queue on the
- remote host. If the remote device does not have a single print
- queue, such as another UNIX system, this causes problems. For
- example, if the remote device was a JetDirect EX + 3 and
- <literal>rp</literal> was omitted, all queues defined would print
- out of the first parallel port.</para>
- </note>
- </sect2>
-
- <sect2>
- <title>Filters</title>
-
- <para>The last two important printcap capabilities concern print
- filters, <literal>if</literal> (input filter) and
- <literal>of</literal> (output filter). If defined, incoming print
- jobs are run through the filters that these entries point to for
- further processing.</para>
-
- <para>Filters are the reason that the UNIX print spooling system is so
- much more powerful than any other commercial server operating
- system. Under FreeBSD, incoming print jobs are acted on by any
- filters specified in the <filename>/etc/printcap</filename>
- <emphasis>no matter where they originate</emphasis>. Incoming print
- jobs from remote Windows, Mac, NT, OS/2 or other clients can be
- intercepted and manipulated by any program specified as a filter.
- Want a PostScript Printer? There's a filter that adds PostScript
- capability to a non-PostScript printer. Want to make a cheap Epson
- MX 80 dot-matrix emulate an expensive Okidata Microline dot-matrix
- for some archaic mainframe application? Write a filter that will
- rewrite the print codes to do it. Want custom-built banner pages?
- Use a filter. Many UNIX <filename>/etc/printcap</filename> filters
- on many Internet sites can do a variety of interesting and unique
- things. Someone may have already written a filter that does what you
- want!</para>
-
- <sect3>
- <title>Types of Filters</title>
-
- <para>Three types of filters can be defined in the
- <filename>/etc/printcap</filename> file. In this book all filter
- examples are for Input filters.</para>
-
- <sect4>
- <title>Input Filters</title>
-
- <para>Input filters are specified by the <literal>if</literal>
- capability. Every job that comes into the spool is acted on by
- any filter specified in the <literal>if</literal> entry for that
- spool. Virtually all filters that an administrator would use are
- specified here. These filters can be either shell scripts, or
- compiled programs.</para>
- </sect4>
-
- <sect4>
- <title>Fixed Filters</title>
-
- <para>Fixed filters are specified by separate capabilities, such
- as <literal>cf</literal>, <literal>df</literal>, and
- <literal>gf</literal>. Mostly, these exist for historical
- reasons. Originally, the idea of LPD was that incoming jobs
- would be submitted with the type fields set to trigger whatever
- filter was desired. However, type codes are confusing and
- annoying to the user, who has to remember which option is needed
- to trigger which type. It is much easier to set up multiple
- queues with different names, and this is what most sites do
- these days. For example, originally a DVI fixed filter might be
- specified in a spool for <literal>lp</literal>, triggered by the
- <option>-d</option> option passed to <command>lpr</command>.
- Jobs without this option aren't acted on by the DVI filter.
- However, the same thing can be done by creating a queue named
- <literal>lp</literal> that doesn't have a DVI filter, and a
- queue named <literal>lpdvi</literal> which has the DVI filter
- specified in the <literal>if</literal> capability. Users just
- need to remember which queue to print to, instead of what option
- needed for this or that program.</para>
- </sect4>
-
- <sect4>
- <title>Output Filters</title>
-
- <para>These are specified by the <literal>of</literal> capability.
- Output filters are much more complicated than input filters and
- are hardly ever used in normal circumstances. They also
- generally require a compiled program somewhere, either directly
- specified or wrapped in a shell script, since they have to do
- their own signal-handling.</para>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Printing Raw UNIX Text with a Filter</title>
-
- <para>One of the first things that a new UNIX user will discover when
- plugging a standard LaserJet or impact printer into a UNIX system
- is the <emphasis>stairstep</emphasis> problem. The symptom is
- that the user dumps text to the printer, either through LPR or
- redirection (by catting it to the parallel device) and instead of
- receiving the expected Courier 10-point printout, gets a page with
- a single line of text, or two lines of text "stairstepped", text
- and nothing else.</para>
-
- <para>The problem is rooted in how printers and UNIX handle
- textfiles internally. Printers by and large follow the "MS-DOS
- Textfile" convention of requiring a carriage return, then a
- linefeed, at the end of every text line. This is a holdover from
- the early days when printers were mechanical devices, and the
- print head needed to return and the platen to advance to start a
- new line. UNIX uses only the linefeed character to terminate a
- text line. So, simply dumping raw text out the parallel port
- works on MS-DOS, but not on UNIX.</para>
-
- <para>If the printer is a PostScript printer, and doesn't support
- standard ASCII, then dumping UNIX text to it doesn't work. But
- then, neither would dumping MS-DOS text to it. (Raw text printing
- on PostScript printers is discussed later in this chapter.) Note
- also that if the printer is connected over the network to an HP
- JetDirect hardware print server, internal or external, the TEXT
- queue on the hardware print automatically adds the extra Carriage
- Return character to the end of a text line.</para>
-
- <para>If the printer is the garden-variety HP LaserJet, DeskJet, or
- an impact printer, and under DOS the administrator is used to
- printing raw text from the command line for directory listings,
- there are two ways to fix stairstep. The first is to send a
- command to the printer to make it print in "unix textfile" mode,
- which makes the printer supply its own carriage return. This
- solution is ugly in a printer environment with UNIX and Windows
- machines attempting to share use of the same printer. Switching
- the printer to work with UNIX disrupts DOS/Windows raw text
- printouts.</para>
-
- <para>The better solution is to use a simple filter that converts
- incoming text from UNIX style to DOS style. The following filter
- posted on questions@FreeBSD.org and the sample
- <filename>/etc/printcap</filename> entry can be used to do
- this:</para>
-
- <programlisting>#!/bin/sh
-# /usr/local/libexec/crlfilter
-#
-# simple parlor trick to add CR to LF for printer
-# Every line of standard input is printed with CRLF
-# attached.
-#
-
-awk '{printf "%s\r\n", $0}' -</programlisting>
-
- <para>An alternative filter posted using sed could be written
- as:</para>
-
- <programlisting>#!/bin/sh
-# /usr/local/libexec/crlfilter
-#
-# Add CR to LF for printer
-# Every line of standard input is printed with CRLF
-# attached.
-#
-# Note, the ^M is a *real* ^M (^V^M if your typing in vi)
-#
-
-sed 's/$/^M/' -</programlisting>
-
- <para>Here is an example of a filter that triggers the printers
- automatic LF-to-CR/LF converter (this option is only useful on HP
- LaserJets that support this command):</para>
-
- <programlisting>#!/bin/sh
-# Simply copies stdin to stdout. Ignores all filter
-# arguments.
-# Tells printer to treat LF as CR+LF. Writes a form feed
-# character after printing job.
-
-printf "\033&amp;k2G" &amp;&amp; cat &amp;&amp; printf "\f" &amp;&amp; exit 0
-
-exit 2</programlisting>
-
- <para>The printcap file used to trigger the filter is:</para>
-
- <programlisting>#/etc/printcap
-# The trailer (tr) is used when the queue empties. I found that the
-# form feed (\f) was basically required for the HP to print properly.
-# Banners also need to be shut off.
-#
-
-lp|local line printer:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
- :if=/usr/local/libexec/crlfilter:sh:tr=\f:mx#0:
-#</programlisting>
- </sect3>
-
- <sect3>
- <title>The <literal>pr</literal> filter</title>
-
- <para>Although most filters are built by scripts or programs and are
- added to the UNIX machine by the administrator, there is one
- filter that is supplied with the FreeBSD operating system is very
- useful for raw text files: the <literal>pr</literal> filter. It is
- most commonly used when printing from the UNIX command shell. The
- <literal>pr</literal> filter paginates and applies headers and
- footers to ASCII text files. It is automatically invoked with the
- <option>-p</option> option used with the <command>lpr</command>
- program at the UNIX command prompt.</para>
-
- <para>The <literal>pr</literal> filter is special - it runs <emphasis>in
- addition</emphasis> to any input filters specified for the print
- queue in <filename>/etc/printcap</filename>,
- <emphasis>if</emphasis> the user sets the option for a print job.
- This allows headers and pagination to be applied in addition to
- any special conversion, such as CR to CR/LF that a specified input
- filter may apply.</para>
- </sect3>
-
- <sect3>
- <title>Printing PostScript Banner Pages with a Filter.</title>
-
- <para>Unfortunately, the canned banner page supplied in the LPD
- program prints only on a text-compatible printer. If the attached
- printer understands only PostScript and the administrator wants to
- print banner pages, it is possible to install a filter into the
- <filename>/etc/printcap</filename> file to do this.</para>
-
- <para>The following filter is taken from the FreeBSD Handbook. I've
- slightly changed its invocation for a couple of reasons. First,
- some PostScript printers have difficulty when two print files are
- sent within the same print job or they lack the trailing
- Control-D. Second is that the handbook invocation uses the LPRPS
- program, which requires a serial connection to the printer.</para>
-
- <para>The following filter shows another trick: calling LPR from
- within a filter program to spin off another print job.
- Unfortunately, the problem with using this trick is that the
- banner page always gets printed after the job. This is because
- the incoming job spools first, and then FreeBSD runs the filter
- against it, so the banner page generated by the filter always
- spools behind the existing job.</para>
-
- <para>There are two scripts, both should be put in the
- <filename>/usr/local/libexec</filename> directory, and the modes
- set to executable. The <filename>printcap</filename> also must be
- modified to create the nonbanner and banner versions of the print
- queue. Following the scripts is the
- <filename>/etc/printcap</filename> file showing how they are
- called. Notice that the <literal>sh</literal> parameter is turned
- on since the actual printed banner is being generated on the fly
- by the filter:</para>
-
- <programlisting>#!/bin/sh
-# Filename /usr/local/libexec/psbanner
-# parameter spacing comes from if= filter call template of:
-# if -c -w -l -i -n login -h host
-# parsing trickiness is to allow for the presence or absence of -c
-# sleep is in there for ickiness of some PostScript printers
-
-for dummy
-do
- case "$1" in
- -n) alogname="$2" ;;
- -h) ahostname="$2" ;;
- esac
- shift
-done
-
-/usr/local/libexec/make-ps-header $alogname $ahostname "PostScript" | \
- lpr -P lpnobanner
-
-sleep 10
-
-cat &amp;&amp; exit 0</programlisting>
-
- <para>Here is the <filename>make-ps-header</filename> listing.</para>
-
- <programlisting>#!/bin/sh
-# Filename /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
-
-#
-# 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 &lt;&lt;EOF
-%!PS
-%
-% Make sure we do not interfere with user's job that will follow
-%
-
-%
-% 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
-%
-
-showpage</programlisting>
-
- <para>Here is the <filename>/etc/printcap</filename> file.</para>
-
- <programlisting>#
-lp|local line printer, PostScript, banner:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:\
- :if=/usr/local/libexec/psbanner:sh:mx#0:
-
-lpnobanner|local line printer, PostScript, no banner:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd-noban:\
- :lf=/var/log/lpd-errs:sh:mx#0:
-#</programlisting>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-accounting">
- <title>Printer Accounting</title>
-
- <para>The FreeBSD print spooler can manage accounting statistics for
- printer usage. The spooler counts each page printed and generates
- totals for each user. In this manner departments or individuals can
- be charged money for their use of the printer.</para>
-
- <para>In the academic world, such as student computer labs, accounting
- is very political. Many schemes have been developed to attempt to
- gather statistics to charge people (generally students) for printing.
- Administrators in this environment who deal with printers can have
- almost as many accounting problems as printer problems. In the
- corporate environment, on the other hand, accounting is not as
- important. I strongly recommend against any corporation attempting to
- implement printer accounting on shared printers for a number of
- reasons:</para>
-
- <orderedlist>
- <listitem>
- <para>The entire UNIX accounting system is based on ASCII printouts.
- It is easy to count the number of ASCII pages, form feeds, or text
- lines in a print job. In corporations, however, PostScript and
- HPPCL are generally the order of the day. It is almost impossible
- to figure out by examining the datastream how many pages it will
- occupy, and even if this could be done accurately, it wastes
- significant computational resources.</para>
-
- <note>
- <para>It is possible to get some PostScript printers to count
- pages, but doing so requires a bidirectional connection to the
- printer and additional programming on the UNIX system. This
- task is beyond the scope of this book.</para>
- </note>
- </listitem>
-
- <listitem>
- <para>Banner pages aren't included in UNIX printer accounting
- counts. Therefore, someone submitting 20 two-page jobs uses much
- more paper than does someone submitting one 40 page job, yet both
- are charged the same amount.</para>
- </listitem>
-
- <listitem>
- <para>The username of the submitter can be easily forged, if the job
- is remotely submitted over the network from a client (practically
- all jobs in a Windows client printing environment are remotely
- submitted). Although some LPR clients can be set to authenticate,
- and the <literal>rs</literal> capability can be set to enforce
- authentication, not all can, especially Windows LPR
- clients.</para>
- </listitem>
-
- <listitem>
- <para>It is more difficult for a submitter to hide the IP number or
- machine name of the remote client, but in a Windows environment
- there is no guarantee that someone was sitting at a particular
- desktop machine when the job was submitted.</para>
- </listitem>
-
- <listitem>
- <para>A business generates no revenue by monitoring printer usage.
- In the academic community, however, when a student lab charges for
- printouts the lab is actually extracting money from an entity (the
- student) that is separate from the lab. Within a corporation, the
- concept of department A getting revenue from user B is pointless
- and doesn't generate a net gain for the corporation as a
- whole.</para>
-
- <para>For my printer administration, I have found that I can save
- more money on printing costs by purchasing supplies wisely than by
- attempting to discourage printing through "chargebacks". What is
- the sense of being miserly with printing while spending double on
- toner cartridges because no one is willing to comparison shop, or
- signing a "lease" agreement that isn't beneficial for the printer?
- When you get down to it, corporate users don't care much for print
- sharing anyway, and they generally only agree to it because the
- administrator can buy a far bigger, faster, and fancier printer
- than they can requisition.</para>
- </listitem>
-
- <listitem>
- <para>Worse yet, if usage on a shared printer is charged, it
- encourages employees to look for other places to print.
- Inevitably, people run out buy cheap inkjet printers for their own
- use, and the business ends up spending more on paper and supplies
- for many poor-quality small printers, than it would for a few
- decent big ones. Moreover, the inferior output of these printers
- makes the organization as a whole look bad.</para>
- </listitem>
-
- <listitem>
- <para>The corporate spirit should be one of teamwork, not bickering.
- The surest way to kill a network in a corporation is to set up a
- situation that puts the administrator into the policeman position
- or pits one department against another.</para>
- </listitem>
- </orderedlist>
-
- <para>The only justification I've ever seen for running accounting on
- corporate printers is using the accounting system to automate
- reminders to the administrator to replace paper, or toner. Aside from
- this use, a corporation that implements accounting as a way of
- encouraging employees not to waste paper ends up defeating the purpose
- of turning on accounting.</para>
- </sect1>
-
- <sect1 id="printserving-samba">
- <title>Microsoft Networking Client printing with Samba</title>
-
- <para>Although LPR is a time-tested and truly cross-platform printing
- solution, sites with a majority of Windows clients running Microsoft
- Networking have an alternate printing mechanism&mdash;Samba. Samba
- can provide print services to clients running SMB-compatible network
- clients. With a running Samba installation, the administrator may
- "share out" printers as well as filesystem directories from the
- FreeBSD system.</para>
-
- <para>Printers accessed with Samba must be defined both in the
- <filename>/etc/printcap</filename> file and the
- <filename>/usr/local/etc/smb.conf</filename> file. If the individual
- printers are defined in the <filename>smb.conf</filename> file with
- the <literal>printer driver=</literal> statement set to the exact
- model name of the printer, the "Auto printer driver install" feature
- of Windows NT and Win95/98 is activated. This automatically loads the
- correct printer driver if the user clicks on the print queue in
- Network Neighborhood under Windows 95 or NT 4.0. The restriction, of
- course, is that the printer model must be in the Windows client driver
- database.</para>
-
- <para>The <filename>smb.conf</filename> file also defines the
- <literal>print</literal> command used to pass jobs to the UNIX print
- spool. It is a good idea to redefine this via the <literal>print
- command</literal> option to <literal>lpr -s -P %p %s; rm
- %s</literal>. This turns on soft linking, so that large print jobs
- don't get truncated.</para>
-
- <para>In operation, the SMB-networking client builds the print job on
- itself and then transfers the entire job over the network to the Samba
- server. On the server, Samba has its own temporary print spool
- directory to which the job is copied. Once the job has been
- completely received, it is then passed to the UNIX print
- spooler.</para>
-
- <figure>
- <title>Microsoft Networking Client printing with Samba</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="08-06" format="EPS"/>
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced"> ,---------.
- | ======= | FreeBSD Server
- | ======= | +---------------------+ ,-----.
-+-----------+ | +---------------+ | | |
-| Printer [ ]------------[ ] | Samba | | |_____|
-+-----------+ Parallel | | Software | [ ]------_________
- Cable | +---------------+ | / ::::::: \
- | | `---------'
- | +---------------+ | Network PC
- | | Print | |
- | | Software | |
- | +---------------+ |
- +---------------------+</literallayout>
- </textobject>
-
- <textobject>
- <phrase>The Samba software and the print software run on the same
- host. Samba receives the print job, then hands it to the print
- spooler.</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <sect2>
- <title>Client access issues</title>
-
- <para>Because a Windows client formats print jobs before sending them
- to the server, the administrator may want to hide some of the
- specialty print queues on the server. For example, the queue that
- converts LF to CRLF for UNIX text printouts would probably not be
- shared out. To make such queues invisible, the
- <literal>browseable=no</literal> option can be turned on in the
- <filename>smb.conf</filename> file. Also, the <literal>load
- printers</literal> option must be set to no to allow individual
- printer definitions.</para>
-
- <note>
- <para>In general, the only print queues that should be visible
- through Samba are the "raw" print queues that are set up by the
- administrator to allow incoming preformatted print jobs.</para>
- </note>
-
- <para>Windows clients that print to Samba print queues on the UNIX
- system can view and cancel print jobs in the print queue. They
- cannot pause them, however, which is a difference between Novell and
- Windows NT Server print queues. They also cannot prioritize print
- jobs from the print queue window, although the administrator can
- reprioritize print jobs that are in the queue from a command shell
- on the FreeBSD server.</para>
- </sect2>
-
- <sect2>
- <title>Printer entries in configuration files</title>
-
- <para>Following are listings of sample
- <filename>/etc/printcap</filename> and
- <filename>smb.conf</filename> files used on the system to provide
- print services. An explanation of the interaction of these files
- follows.</para>
-
- <example>
- <title><filename>/etc/printcap</filename></title>
-
- <programlisting>#
-#
-# The printer in lpt0 is a PostScript printer. The nec-crlf entry
-# is for testing the printer when it is switched into HP LaserJet III
-# mode.
-#
-
-lp|local line printer:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:\
- :lf=/var/log/lpd-errs:sh:mx#0:
-
-#
-
-nec-crlf|NEC Silentwriter 95 in ASCII mode with UNIX text filter:\
- :lp=/dev/lpt0:sd=/usr/lpdspool/nec-crlf:\
- :lf=/var/log/lpd-errs:sh:mx#0:\
- :if=/usr/local/libexec/crlfilter:tr=\f:
-
-#
-
-nec-raw|NEC Silentwriter 95 used for PostScript passthrough printing:\
- :lp=/dev/lpt0:sd=/usr/lpdspool/nec-raw:\
- :lf=/var/log/lpd-errs:sh:mx#0:
-
-#
-
-nec-ps-banner|NEC Silentwriter 95 with PostScript banner page created:\
- :lp=/dev/lpt0:sd=/usr/lpdspool/nec-ps-banner:\
- :lf=/var/log/lpd-errs:sh:mx#0:if=/usr/local/libexec/psbanner:
-
-#
-#</programlisting>
- </example>
-
- <example>
- <title><filename>/usr/local/etc/smb.conf</filename></title>
-
- <programlisting>[global]
-comment = FreeBSD - Samba %v
-log file = /var/log/samba.log
-dont descend = /dev,/proc,/root,/stand
-print command = lpr -s -P %p %s; rm %s
-interfaces = <replaceable>X.X.X.X</replaceable> (the system IP number goes here)
-printing = bsd
-map archive = no
-status = yes
-public = yes
-read only = no
-preserve case = yes
-strip dot = yes
-security = share
-guest ok = no
-password level = 1
-dead time = 15
-domain master = yes
-workgroup = WORKGROUP
-
-[homes]
-browseable = no
-comment = User Home Directory
-create mode = 0775
-public = no
-
-[printers]
-path = /var/spool
-comment = Printers
-create mode = 0700
-browseable = no
-read only = yes
-public = no
-
-[lp]
-printable = yes
-browseable = no
-
-[nec-raw]
-comment = Main PostScript printer driver for Windows clients
-printer driver = NEC SilentWriter 95
-printable = yes
-browseable = yes
-
-[wwwroot]
-path = /usr/local/www
-read only = no
-create mode = 0775
-comment = Internal Web Server</programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title>Browsing output</title>
-
- <para>Following is the output of a <userinput>net view</userinput>
- command executed at a DOS prompt under Windows 95:</para>
-
- <screen>Shared resources at \\SERVER
-
-Sharename Type Comment
---------------------------------------------------------------------
-nec-crlf Print NEC Silentwriter 95 in ASCII mode
-nec-raw Print Main PostScript printer driver
-tedm Disk User Home Directory
-wwwroot Disk Internal Web Server
-
-The command was completed successfully.</screen>
-
- <para>In the <filename>/etc/printcap</filename> file four print queues
- are defined, all tied to the printer plugged into the parallel port
- on the FreeBSD server. The first is <literal>lp</literal>, the
- generic local line printer. Since this print queue generally has a
- filter placed on it to format jobs from the UNIX print queue
- properly, it should not be visible on the SMB network (i.e., visible
- in Network Neighborhood). The second queue,
- <literal>nec-crlf</literal>, has a filter that converts UNIX text to
- text that prints without stairstepping, so it also should be hidden
- from the SMB network. The third, <literal>nec-raw</literal>, should
- be visible on the network because this is the spool that the Windows
- clients use. The last queue, <literal>nec-ps-banner</literal>, is
- another specialty queue for UNIX local printing and thus should not
- be visible.</para>
-
- <para>When the <filename>smb.conf</filename> file is parsed, the
- default entry <literal>[printers]</literal> is first read and used
- as a set of defaults for printers that are going to be shared out.
- Next, the <filename>/etc/printcap</filename> file is read to get a
- list of all printers on the server. Last, each printer is checked
- for a service name in the <filename>smb.conf</filename> file that
- contains settings that override the set of defaults.</para>
-
- <para>In the listing of what resources are visible on the network,
- both <literal>nec-crlf</literal> and <literal>nec-raw</literal>
- print queues are visible, and <literal>lp</literal> and
- <literal>nec-ps-banner</literal> is not. <literal>lp</literal> is
- not visible because there is a specific entry,
- <literal>[lp]</literal> in the <filename>smb.conf</filename> file
- that blocks it. <literal>nec-ps-banner</literal> doesn't have such
- an entry, but because the print queue name is not a legal length for
- a SMB name, it isn't shared out either.</para>
-
- <para>The <literal>nec-crlf</literal> printer is visible so as to
- illustrate another point - comments. If a print queue has no entry
- in the <filename>smb.conf</filename> file and is built by scanning
- the <filename>/etc/printcap</filename> file and using the
- <literal>[printers]</literal> defaults, the comment is taken from
- the <filename>/etc/printcap</filename> file next to the queue
- definition name. Otherwise, if an entry is made for the printer in
- the <filename>smb.conf</filename> file the comment is taken from the
- entry in <filename>smb.conf</filename>.</para>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-nt-and-freebsd">
- <title>Printing between NT Server/NetWare and FreeBSD.</title>
-
- <para>Up to this point in the chapter, our main concern has been FreeBSD
- and Windows NT printing interoperability with NT as a print client
- passing jobs to the FreeBSD system. What happens if the situation is
- reversed and the FreeBSD system is itself a printing client of another
- LPD server? This situation can arise in a mixed UNIX/NetWare or
- UNIX/NT environment. The administrator may elect to forgo the use of
- Samba, and use an NT server to provide print services. Alternatively,
- the administrator may have existing DOS Novell IPX clients that they
- don't want to change, printing to an existing IPX Novell NetWare
- server. Many of the earlier hardware print servers, such as the Intel
- NetPort 1 and NetPort 2 were IPX only. A site with a large number of
- these hardware servers may wish to move the clients to TCP/IP, but
- leave the existing IPX-based printing network intact.</para>
-
- <para>With NetWare it is possible to load an LPD NetWare loadable module
- (NLM) on the NetWare server that takes incoming LPR print jobs and
- prints them on IPX print queues. Later versions of NetWare may
- include this NLM, it was an extra cost add-on with NetWare 3.X</para>
-
- <para>With Windows NT Server, loading the TCP/IP LPR printing support
- also loads the LPD print server on NT. By using LPR client programs
- on UNIX, it is possible to submit, view status, and remove jobs
- remotely from an NT server that has LPR installed as a port for its
- printers.</para>
-
- <para>Following is a sample <filename>/etc/printcap</filename> file entry
- that defines a print queue named <literal>tank</literal> on the FreeBSD
- system pointed to an NT LPD server queue named
- <literal>sherman</literal> on a NT Server named
- <hostid role="fqdn">big.army.mil</hostid> in the DNS. This uses the
- <literal>rm</literal> printcap capability. Unlike the earlier
- examples, the output print jobs are sent out not by the PC parallel
- port but over the network to the NT server.</para>
-
- <programlisting>#
-tank|sample remote printer:\
- :rm=big.army.mil:rp=sherman:sd=/var/spool/output/lphost:\
- :lf=/var/log/lpd-errs:
-#</programlisting>
-
- <note>
- <para>When using an NT server as an LPD server it may be necessary to
- make the NT registry changes mentioned under Windows NT Registry
- Changes, earlier in the chapter.</para>
- </note>
- </sect1>
-
- <sect1 id="printserving-unix">
- <title>Printing from UNIX</title>
-
- <para>Two commands used at the FreeBSD command prompt are intended as
- general-purpose print commands: <command>lp</command> and
- <command>lpr</command>.</para>
-
- <sect2>
- <title><command>lp</command></title>
-
- <para>The <command>lp</command> command is simply a front end command
- that calls the <command>lpr</command> command with appropriate
- options. Its main use is to allow the running of precompiled
- binary programs and scripts that assume that the
- <command>lp</command> command is the <emphasis>official</emphasis>
- printing command.</para>
- </sect2>
-
- <sect2>
- <title><command>lpr</command></title>
-
- <para>The <command>lpr</command> command is the main command that is
- used to print files from the command prompts under the FreeBSD
- operating system. It is frequently spawned off as a child program,
- or used in pipes. For example, when the Netscape web browser's
- Print button is clicked, Netscape may create the PostScript output,
- but the output goes through the <command>lpr</command>
- command.</para>
-
- <para>The <command>lpr</command> command, like many UNIX command-line
- printing programs, assumes that the default print queue name is
- <literal>lp</literal>. When the FreeBSD machine is set up, the
- administrator usually sets the <literal>lp</literal> queue to print
- through a filter that allows raw UNIX text sent to it to print
- properly. For example, if an HP LaserJet printer that doesn't have
- PostScript is connected to the server, the
- <literal>lp</literal> queue specifies in the
- <filename>/etc/printcap</filename> file the CRLF filter listed
- earlier. On the other hand, if an Apple Laserwriter that doesn't
- support ASCII is connected to the server, the
- <literal>a2ps</literal>filter would be specified in the
- <filename>/etc/printcap</filename> for the <literal>lp</literal>
- queue.</para>
-
- <para>When printing raw text files usually the <option>-p</option>
- option is specified to <command>lpr</command>. When printing
- preformatted files, such as PostScript files, the
- <option>-P</option> option is used, which selects whatever queue is
- used to handle these job types.</para>
- </sect2>
-
- <sect2>
- <title>Managing the UNIX Print Queue</title>
-
- <para>Once the print jobs coming in from clients are received on the
- FreeBSD system and placed in the print spool, they are metered out
- at a slower rate to the various printers. If traffic activity is
- light, and few print jobs get sent through, the administrator can
- probably ignore the print queue as long as it continues to work.
- However, a busy network printer running at an optimal rate of speed
- usually has a backlog of unprinted jobs in the queue waiting for
- print time. To keep all users happy and to provide for the
- occasional rush print job, the UNIX LPD/LPR printing system has
- several administration commands which are described here.</para>
-
- <sect3>
- <title>Viewing the queue</title>
-
- <para>On busy printers, and to troubleshoot stopped printers, users
- sometimes need to view the print jobs in the queue. Administrators
- also need to view the queue to see what jobs may need to be
- expedited. This can be done from the workstation that remotely
- submitted the job if the LPR client has the ability to do this.
- The Windows 3.1 LPR client discussed earlier has this capability.
- Unfortunately, many LPR clients don't, which means that the
- administrator must Telnet into the UNIX machine that the print
- queues are on and view them there.</para>
-
- <para>The UNIX shell command used to view the queue is the
- <command>lpq</command> command. It is frequently run as
- <userinput>lpq -a</userinput> which shows jobs in all queues. The
- following is a sample output of the command:</para>
-
- <screen>&prompt.root; <userinput>lpq -a</userinput>
-nec-raw:
-Rank Owner Job Files Total Size
-1st tedm 19 C:/WLPRSPL/SPOOL/~LP00018.TMP 105221 bytes
-2nd tedm 20 C:/WLPRSPL/SPOOL/~LP00019.TMP 13488 bytes
-3rd root 3 hosts 1220 bytes
-4th tedm 1 Printer Test Page 765 bytes
-5th tedm 2 Microsoft Word - CHAPTE10.DOC 15411 bytes</screen>
-
- <para>The first two jobs and the last two jobs came from remote
- clients, the third came from the command prompt.</para>
- </sect3>
-
- <sect3>
- <title>Removing print jobs</title>
-
- <para>Deleting unwanted print jobs that haven't yet printed from the
- queue can be done by the remote workstations that submitted the
- job if their LPR implementations have the necessary commands. The
- Windows 3.1 LPR client I detailed earlier has this capability. Many
- LPR clients don't, however, which means that the administrator
- must Telnet into the UNIX machine that the print queues are on and
- delete the jobs there.</para>
-
- <para>The administrator can delete any print jobs from any queues by
- running the <command>lprm</command> command followed by the
- specified print queue and the job number. Below is a sample
- output of the command:</para>
-
- <screen>&prompt.root; <userinput>lprm -P nec-raw 19</userinput>
-dfA019tedmitte dequeued
-cfA019dostest dequeued
-&prompt.root; <userinput>lprm -P nec-raw 3</userinput>
-dfA003toybox.placo.com dequeued
-cfA003toybox.placo.com dequeued</screen>
-
- <para>The <command>lprm</command> command is also used under UNIX to
- delete remote print jobs.</para>
- </sect3>
-
- <sect3>
- <title>Advanced management</title>
-
- <para>The administrator logged into the FreeBSD system as the root
- user can also perform several other operations that ordinary users
- cannot. These include turning the queues on and off, and moving
- print jobs within the print queues. The command used to do this
- is the <command>lpc</command> command.</para>
-
- <para><command>lpc</command> has two modes of operation. In the
- first mode, the command is run by itself, which puts the
- administrator into an <prompt>lpc</prompt> prompt. Some general
- help is available for the commands, such as the following sample
- output:</para>
-
- <screen>&prompt.root; <userinput>lpc</userinput>
-<prompt>lpc&gt;</prompt> <userinput>help</userinput>
-Commands may be abbreviated.
-Commands are:
-abort enable disable help restart status topq ?
-clean exit down quit start stop up
-<prompt>lpc&gt;</prompt> <userinput>help disable</userinput>
-disable turn a spooling queue off
-<prompt>lpc&gt;</prompt> <userinput>help status</userinput>
-status show status of daemon and queue
-<prompt>lpc&gt;</prompt> <userinput>exit</userinput></screen>
-
- <para>In the second mode of operation the <command>lpc</command>
- command is just run by itself, followed by the command and the
- print queue name. Following is a sample output:</para>
-
- <screen>&prompt.root; <userinput>lpc disable lp</userinput>
-lp:
-queuing disabled</screen>
-
- <para>Under FreeBSD, there is no command that specifically allows
- the administrator to move jobs from one queue to another. This
- can be done, however, by changing into the raw queue directory
- then rerunning the <command>lpr</command> command. Following is a
- sample run showing three print jobs moved from a dysfunctional
- queue to a good one:</para>
-
- <screen>&prompt.root; <userinput>lpq -a</userinput>
-lp:
-Warning: lp is down: printing disabled
-printing disabled
-Rank Owner Job Files Total Size
-1st root 51 hosts 1220 bytes
-2nd root 52 services 60767 bytes
-3rd root 53 printcap 2383 bytes
-&prompt.root; <userinput>cd /var/spool/output/lpd</userinput>
-&prompt.root; <userinput>ls</userinput>
-.seq cfA053toybox.placo.com dfA053toybox.placo.com
-cfA051toybox.placo.com dfA051toybox.placo.com lock
-cfA052toybox.placo.com dfA052toybox.placo.com status
-&prompt.root; <userinput>lpr -P nec-raw dfA051toybox.placo.com</userinput>
-&prompt.root; <userinput>lpr -P nec-raw dfA052toybox.placo.com</userinput>
-&prompt.root; <userinput>lpr -P nec-raw dfA053toybox.placo.com</userinput>
-&prompt.root; <userinput>lprm -P lp -</userinput>
-&prompt.root; <userinput>lpq -a</userinput>
-nec-raw:
-Warning: nec-raw is down: printing disabled
-Warning: no daemon present
-Rank Owner Job Files Total Size
-1st root 5 dfA051toybox.placo.com 1220 bytes
-2nd root 6 dfA052toybox.placo.com 60767 bytes
-3rd root 7 dfA053toybox.placo.com 2383 bytes</screen>
-
- <note>
- <para>Moving jobs from queue to queue is feasible only when all
- printers are similar, as when all printers support
- PostScript.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Remote Management</title>
-
- <para>Just as the root user can manipulate remotely submitted jobs
- in the print queue, print jobs can be remotely managed by regular
- users with the LPR clients that created them. Unfortunately, some
- LPR clients, such as the ACITS LPR client for Win95, don't have
- enough programming to be able to do this. Others, like the Win31
- client, can manipulate the print jobs remotely.</para>
-
- <para>FreeBSD offers some level of protection against inadvertent
- deletion of print jobs from remote hosts by restricting
- manipulation of a job to the same host that originated it. Even
- if the owner of the job matches a local user account on the
- server, for an ordinary user to delete remotely submitted print
- jobs, the request still must come from the remote host.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-advanced">
- <title>Advanced Printing Topics</title>
-
- <para>The FreeBSD UNIX LPR/LPD printing system is very flexible, and,
- with the addition of filters, can be adapted to very unusual printing
- environments. To enhance this flexibility, several useful printing
- utilities are supplied on the FreeBSD CDROM which the administrator
- might wish to install.</para>
-
- <sect2>
- <title>Ghostscript</title>
-
- <para>The Ghostscript program, invoked as
- <filename>/usr/local/bin/gs</filename>, is one of the most useful
- printing utilities that have been developed for the free software
- community. Ghostscript reads incoming PostScript data, (or Adobe
- PDF files) interprets it, and outputs it as a raster image. This
- can be displayed on screen, for example, with the GhostView program
- under the X Window system, or printed on most graphics printers,
- such as Epson dot-matrix, HP DeskJet, or HP LaserJet. In effect, it
- is a way of adding PostScript printing capability to a printer that
- doesn't have PostScript firmware code. Ghostscript has been ported
- to numerous operating systems including Windows.</para>
-
- <para>The Ghostscript home page is located at
- <ulink url="http://www.cs.wisc.edu/~ghost/"></ulink>
- and contains the most current version of the program. A prebuilt
- FreeBSD binary of Ghostscript is located in the Packages section of
- the FreeBSD CDROM. This can be installed on the FreeBSD system by
- selecting the package from the prepackaged software list that is
- accessed through the <command>/stand/sysinstall</command>
- installation program. Many packaged programs on the CD depend on
- GhostScript, and so it may already be installed.</para>
-
- <para>Installation of the packaged version of GhostScript is
- recommended in the FreeBSD ports Section because it has been tested
- with the other packages that require it. The package creates a
- directory containing some documentation files in
- <filename>/usr/local/share/ghostscript/X.XX/doc</filename>.
- Unfortunately, because of the packaging process on the FreeBSD CDROM
- not all the useful installation files are copied into this location.
- So, if the package was version 5.03 (for example) the administrator
- will also want to get the file
- <ulink url="ftp://ftp.cs.wisc.edu/ghost/aladdin/gs502/ghostscript-5.02.tar.gz"></ulink>,
- and unzip and untar it into a temporary directory.</para>
-
- <para>Extracting the archive file creates a directory structure under
- the <filename>gs5.03</filename> subdirectory. To install
- ghostscript in the <filename>/etc/printcap</filename> file, read the
- <filename>gs5.03/devs.mak</filename> file to determine which printer
- driver definition works with your printer and then use the following
- instructions:</para>
-
- <procedure>
- <step>
- <para>Change to the root user with <command>su</command>.</para>
- </step>
-
- <step>
- <para>In the <filename>gs5.03</filename> directory, copy the
- <filename>lprsetup.sh</filename>,
- <filename>unix-lpr.txt</filename>, and
- <filename>unix-lpr.sh</filename> files to
- <filename>/usr/local/share/ghostscript/5.03</filename>.</para>
- </step>
-
- <step>
- <para>Change to the
- <filename>/usr/local/share/ghostscript/5.03</filename>
- directory. Edit <filename>lprsetup.sh</filename> with a text
- editor such as <command>vi</command>.</para>
- </step>
-
- <step>
- <para>Modify the <literal>DEVICES=</literal> entries
- to list your selected printer driver definitions per the
- instructions in <filename>unix-lpr.txt</filename>.</para>
- </step>
-
- <step>
- <para>Modify the <literal>PRINTERDEV=</literal> to
- <literal>/dev/lpt0</literal>, and the <literal>GSDIR=</literal>
- to <literal>/usr/local/share/ghostscript</literal>, and the
- <literal>SPOOLDIR=</literal> to
- <literal>/var/spool/output</literal>. Save the file.</para>
- </step>
-
- <step>
- <para>Edit the <filename>unix-lpr.sh</filename> file and change
- the <literal>PSFILTERPATH=</literal> to
- <literal>/usr/local/share/ghostscript</literal>.</para>
- </step>
-
- <step>
- <para>If the printer that you defined in the
- <filename>lprsetup.sh</filename> file is a monochrome printer,
- remove the <literal>"-dBitsPerPixel=${bpp}"</literal> and
- <literal>"$colorspec"</literal> entries on the
- <literal>gs</literal> invocation line and save the file.
- Otherwise, if it is a color definition leave them in. For
- example, the following line is for a monochrome LaserJet:</para>
-
- <programlisting>") | gs -q -dNOPAUSE -sDEVICE=${device} \"</programlisting>
-
- <para>Don't remove anything else. Exit the editor, and save the
- <filename>unix-lpr.sh</filename> file.</para>
- </step>
-
- <step>
- <para>Copy the <filename>unix-lpr.sh</filename> file to the parent
- directory, <filename>/usr/local/share/ghostscript</filename> and
- set the execute bit on it.</para>
- </step>
-
- <step>
- <para>Set the execute bit on <filename>lprsetup.sh</filename> with
- chmod and run the file by typing
- <userinput>./lprsetup.sh</userinput>.</para>
- </step>
-
- <step>
- <para>Follow the instructions on creating the Spool directories.
- If you will be using accounting and a separate log file, run the
- <command>touch</command> command to create the empty files per
- directions in script output.</para>
- </step>
-
- <step>
- <para>The sample <command>/etc/printcap</command> is located in
- the current directory; the filename is
- <filename>printcap.insert</filename>. Use this as a template to
- modify the <filename>/etc/printcap</filename> file. A sample
- <filename>/etc/printcap</filename> file for a LaserJet 3 is
- below:</para>
-
- <programlisting>#
-#
-ljet3.raw|Raw output device ljet3 for Ghostscript:\
- :rm=big.army.mil:rp=sherman:sd=/var/spool/output/ljet3/raw:\
- :mx#0:sf:sh:rs:
-
-#
-
-ljet3|Ghostscript device ljet3 (output to ljet3.raw):\
- :lp=/dev/null:sd=/var/spool/output/ljet3:\
- :lf=/var/log/lpd-errs:mx#0:sf:sh:rs:\
- :if=/usr/local/share/ghostscript/filt/indirect/ljet3/gsif:\
- :af=/var/spool/output/ljet3/acct:
-
-#</programlisting>
- </step>
- </procedure>
- </sect2>
-
- <sect2>
- <title>a2ps filter</title>
-
- <para>Another handy utility is the <command>a2ps</command> filter, short
- for ASCII-to-PostScript. This program takes an incoming ASCII
- datastream and converts it into PostScript. It can also print
- multiple pages on a single sheet of paper by shrinking them down. It
- is a useful tool for a printer that cannot interpret ASCII, such as
- a PostScript-only printer.</para>
-
- <para><command>A2ps</command> is not installed in the FreeBSD system
- by default; it is located in the ports section
- <filename>/usr/ports/print/a2ps43</filename>. A prepackaged binary
- can be installed with <command>/stand/sysinstall</command> but I
- have had problems with that port. It is best to install it by
- running <command>make</command> in the a2ps43 ports directory. A
- printcap entry and filter using this follow:</para>
-
- <example>
- <title><filename>/etc/printcap</filename></title>
-
- <programlisting>#
-lp|local line printer with output dumped through a2ps for raw listings:\
- :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:sh:mx#0:\
- :if=/usr/local/libexec/ascii2postscript:
-#</programlisting>
- </example>
-
- <example>
- <title><filename>/usr/local/libexec/ascii2postscript</filename></title>
-
- <programlisting>#!/bin/sh
-#
-# Simple filter that converts ASCII to PostScript for basic stuff like
-# directory listings.
-#
-
-/usr/local/bin/a2ps &amp;&amp; exit 0
-
-exit 2</programlisting>
- </example>
-
- <para>Read the system manual page for <command>a2ps</command> to see
- the options available with this program, and remember to set the
- filter script <filename>ascii2postscript</filename>
- all-executable.</para>
- </sect2>
- </sect1>
-
- <sect1 id="printserving-misc">
- <title>Miscellaneous</title>
-
- <para>The large number of other printing utilities cannot be covered
- here. Some add features such as automatic job type sensing, others
- handle bidirectional communication between the server and the printer.
- There are also a few other experimental LPR printing replacement
- systems. Commands such as ghostscript and <command>a2ps</command> can
- also be used in pipes that create pretty output on an ordinary impact
- printer.</para>
-
- <para>One last hint - the system manual pages can be printed with the
- <option>-t</option> option which turns their ordinary ASCII output to
- beautifully formatted PostScript. Try the command <command>man -t
- man</command> and send the output through GhostScript or a
- PostScript printer for easier to read manual pages.</para>
- </sect1>
- </chapter>
-</book>
diff --git a/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl b/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl
deleted file mode 100644
index 59efdeff4e..0000000000
--- a/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl
+++ /dev/null
@@ -1,18 +0,0 @@
-<!-- $FreeBSD$ -->
-
-<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
-<!ENTITY freebsd.dsl PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" CDATA DSSSL>
-]>
-
-<style-sheet>
- <style-specification use="docbook">
- <style-specification-body>
-
- ;; Keep the legalnotice together with the rest of the text
- (define %generate-legalnotice-link%
- #f)
- </style-specification-body>
- </style-specification>
-
- <external-specification id="docbook" document="freebsd.dsl">
-</style-sheet>
diff --git a/en_US.ISO8859-1/books/dev-model/book.xml b/en_US.ISO8859-1/books/dev-model/book.xml
index cd0f309f82..ad561cf0b0 100644
--- a/en_US.ISO8859-1/books/dev-model/book.xml
+++ b/en_US.ISO8859-1/books/dev-model/book.xml
@@ -44,7 +44,13 @@
<year>2002-2005</year>
<holder>Niklas Saers</holder>
</copyright>
- <revhistory>
+ <revhistory>
+ <revision>
+ <revnumber>1.3</revnumber>
+ <date>October, 2012</date>
+ <revremark>Remove hats held by specific people, these
+ are documented elsewhere.</revremark>
+ </revision>
<revision>
<revnumber>1.2</revnumber>
<date>April, 2005</date>
@@ -882,8 +888,6 @@
</para>
<para>
- <!-- [TODO] - check all email adresses and names -->
-
Hat held by:
The DocEng team <email>doceng@FreeBSD.org</email>.
The
@@ -908,27 +912,6 @@
</para>
</section>
- <section id="role-internationalisation" xreflabel="Internationalisation">
- <title>Internationalisation</title>
- <para>
- The Internationalisation hat is responsible for coordinating
- the localisation efforts of the FreeBSD kernel and userland
- utilities. The translation effort are coordinated by
- <xref linkend="sub-project-documentation"/>. The
- Internationalisation hat should suggest and promote standards
- and guidelines for writing and maintaining the software in a
- fashion that makes it easier to translate.
- </para>
- <para>
- Hat currently available.
- <!--
- [TODO] - Is this still the case?
- Although Ache does Localization
- Andrey A. Chernov <email>ache@FreeBSD.org</email>
- -->
- </para>
- </section>
-
<section id="role-postmaster" xreflabel="Postmaster">
<title>Postmaster</title>
<para>
@@ -944,21 +927,6 @@
</para>
</section>
- <section id="role-quality-assurance" xreflabel="Quality Assurance">
- <title>Quality Assurance</title>
-
- <para>
- The responsibilities of this role are to manage the quality assurance
- measures.
- </para>
-
- <para>
- Hat currently held by:
- Robert Watson <email>rwatson@FreeBSD.org</email>.
- </para>
-
- </section>
-
<section id="role-release-coordination" xreflabel="Release Coordination">
<title>Release Coordination</title>
@@ -993,8 +961,6 @@
<para id="role-releng" xreflabel="Release Engineering Team">
Hat held by:
the Release Engineering team <email>re@FreeBSD.org</email>.
- The current Release Engineer is
- Ken Smith <email>kensmith@FreeBSD.org</email>.
The
<ulink url="http://www.freebsd.org/releng/charter.html">
Release Engineering Charter</ulink>.
@@ -1052,16 +1018,6 @@
Officer Team <email>security-team@FreeBSD.org</email> to
help do the work.
</para>
- <para>
- Hat held by:
- the Security Officer <email>security-officer@FreeBSD.org</email>,
- currently headed by
- Colin Percival <email>cperciva@FreeBSD.org</email>.
- The
- <ulink url="http://www.freebsd.org/security/index.html#sec">
- Security Officer and The Security Officer Team's
- charter</ulink>.
- </para>
</section>
<section id="role-repo-manager" xreflabel="Source Repository Manager">
@@ -1069,7 +1025,7 @@
<para>
The Source Repository Manager is the only one who is allowed
to directly modify the repository without using the
- <xref linkend="tool-cvs"/> tool.
+ <xref linkend="tool-svn"/> tool.
It is his/her
responsibility to ensure that technical problems that arise in the
repository are resolved quickly. The source repository
@@ -1078,8 +1034,7 @@
</para>
<para>
Hat held by:
- the Source Repository Manager <email>cvs@FreeBSD.org</email>,
- currently headed by Peter Wemm <email>peter@FreeBSD.org</email>.
+ the Source Repository Manager <email>cvs@FreeBSD.org</email>.
</para>
</section>
@@ -1205,10 +1160,7 @@
</para>
<para>
Hat held by:
- the Donations Liaison Office <email>donations@FreeBSD.org</email>,
- currently headed by
- Michael W. Lucas <email>mwlucas@FreeBSD.org</email>.
-
+ the Donations Liaison Office <email>donations@FreeBSD.org</email>.
</para>
</section>
@@ -1230,8 +1182,7 @@
<para>
Hat held by:
- the Admin team <email>admin@FreeBSD.org</email>,
- currently headed by Mark Murray <email>markm@FreeBSD.org</email>
+ the Admin team <email>admin@FreeBSD.org</email>.
</para>
</section>
@@ -2237,11 +2188,9 @@
developed tools. These tools are commonly used in the open source world.
</para>
- <section id="tool-cvs" xreflabel="CVS">
- <title>Concurrent Versions System (CVS)</title>
- <para>
- Concurrent Versions System
- or simply <quote>CVS</quote>
+ <section id="tool-svn" xreflabel="SVN">
+ <title>Subversion (SVN)</title>
+ <para>Subversion (<quote>SVN</quote>)
is a system to handle multiple versions of text files and
tracking who committed what changes and why. A project lives
within a <quote>repository</quote> and different versions are
@@ -2261,7 +2210,6 @@
</para>
</section>
-
<section id="tool-gnats" xreflabel="GNATS">
<title>GNATS</title>
<para>
diff --git a/en_US.ISO8859-1/books/developers-handbook/Makefile b/en_US.ISO8859-1/books/developers-handbook/Makefile
index 436231ffd9..2d673e307e 100644
--- a/en_US.ISO8859-1/books/developers-handbook/Makefile
+++ b/en_US.ISO8859-1/books/developers-handbook/Makefile
@@ -19,11 +19,11 @@ INSTALL_ONLY_COMPRESSED?=
IMAGES_EN= sockets/layers.eps sockets/sain.eps sockets/sainfill.eps sockets/sainlsb.eps sockets/sainmsb.eps sockets/sainserv.eps sockets/serv.eps sockets/serv2.eps sockets/slayers.eps
#
-# SRCS lists the individual SGML files that make up the document. Changes
+# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
-# SGML content
+# XML content
SRCS= book.xml
SRCS+= introduction/chapter.xml
SRCS+= ipv6/chapter.xml
diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml
index 3f90f40252..aa80bb4bf9 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml
@@ -786,6 +786,254 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger")
stack, and do a backtrace with <command>where</command>.</para>
</sect1>
+ <sect1 id="kerneldebug-dcons">
+ <title>Kernel debugging with Dcons</title>
+
+ <para>&man.dcons.4; is a very simple console driver that is
+ not directly connected with any physical devices. It just reads
+ and writes characters from and to a buffer in a kernel or
+ loader. Due to its simple nature, it is very useful for kernel
+ debugging, especially with a &firewire; device. Currently, &os;
+ provides two ways to interact with the buffer from outside of
+ the kernel using &man.dconschat.8;.</para>
+
+ <sect2>
+ <title>Dcons over &firewire;</title>
+
+ <para>Most &firewire; (IEEE1394) host controllers are
+ based on the <acronym>OHCI</acronym> specification that
+ supports physical access to the host memory. This means that
+ once the host controller is initialized, we can access the
+ host memory without the help of software (kernel). We can
+ exploit this facility for interaction with &man.dcons.4;.
+ &man.dcons.4; provides similar functionality as a serial
+ console. It emulates two serial ports, one for the console
+ and <acronym>DDB</acronym>, the other for
+ <acronym>GDB</acronym>. Because remote memory access is fully
+ handled by the hardware, the &man.dcons.4; buffer is
+ accessible even when the system crashes.</para>
+
+ <para>&firewire; devices are not limited to those
+ integrated into motherboards. <acronym>PCI</acronym> cards
+ exist for desktops, and a cardbus interface can be purchased
+ for laptops.</para>
+
+ <sect3>
+ <title>Enabling &firewire; and Dcons support on the target
+ machine</title>
+
+ <para>To enable &firewire; and Dcons support in the kernel of
+ the <emphasis>target machine</emphasis>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Make sure your kernel supports
+ <literal>dcons</literal>, <literal>dcons_crom</literal>
+ and <literal>firewire</literal>.
+ <literal>Dcons</literal> should be statically linked
+ with the kernel. For <literal>dcons_crom</literal> and
+ <literal>firewire</literal>, modules should be
+ OK.</para>
+ </listitem>
+ <listitem>
+ <para>Make sure physical <acronym>DMA</acronym> is enabled.
+ You may need to add
+ <literal>hw.firewire.phydma_enable=1</literal> to
+ <filename>/boot/loader.conf</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Add options for debugging.</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>dcons_gdb=1</literal> in
+ <filename>/boot/loader.conf</filename> if you use GDB
+ over &firewire;.</para>
+ </listitem>
+ <listitem>
+ <para>Enable <literal>dcons</literal> in
+ <filename>/etc/ttys</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Optionally, to force <literal>dcons</literal> to
+ be the high-level console, add
+ <literal>hw.firewire.dcons_crom.force_console=1</literal>
+ to <filename>loader.conf</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To enable &firewire; and Dcons support in &man.loader.8;
+ on i386 or amd64:</para>
+
+ <para>Add
+ <literal>LOADER_FIREWIRE_SUPPORT=YES</literal> in
+ <filename>/etc/make.conf</filename> and rebuild
+ &man.loader.8;:</para>
+
+ <screen>&prompt.root; <userinput>cd /sys/boot/i386 &amp;&amp; make clean &amp;&amp; make &amp;&amp; make install</userinput></screen>
+
+ <para>To enable &man.dcons.4; as an active low-level
+ console, add <literal>boot_multicons="YES"</literal> to
+ <filename>/boot/loader.conf</filename>.</para>
+
+ <para>Here are a few configuration examples. A sample kernel
+ configuration file would contain:</para>
+
+ <screen>device dcons
+device dcons_crom
+options KDB
+options DDB
+options GDB
+options ALT_BREAK_TO_DEBUGGER</screen>
+
+ <para>And a sample <filename>/boot/loader.conf</filename>
+ would contain:</para>
+
+ <screen>dcons_crom_load="YES"
+dcons_gdb=1
+boot_multicons="YES"
+hw.firewire.phydma_enable=1
+hw.firewire.dcons_crom.force_console=1</screen>
+
+ </sect3>
+
+ <sect3>
+ <title>Enabling &firewire; and Dcons support on the host
+ machine</title>
+
+ <para>To enable &firewire; support in the kernel on the
+ <emphasis>host machine</emphasis>:</para>
+
+ <screen>&prompt.root; <userinput>kldload firewire</userinput></screen>
+
+ <para>Find out the <acronym>EUI64</acronym> (the unique 64
+ bit identifier) of the &firewire; host controller, and
+ use &man.fwcontrol.8; or <command>dmesg</command> to
+ find the <acronym>EUI64</acronym> of the target machine.</para>
+
+ <para>Run &man.dconschat.8;, with:</para>
+
+ <screen>&prompt.root; <userinput>dconschat -e \# -br -G 12345 -t <replaceable>00-11-22-33-44-55-66-77</replaceable></userinput></screen>
+
+ <para>The following key combinations can be used once
+ &man.dconschat.8; is running:</para>
+
+ <informaltable pgwide="1">
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <keycombo action="seq">
+ <keycap>~</keycap>
+ <keycap>.</keycap>
+ </keycombo>
+ </entry>
+ <entry>Disconnect</entry>
+ </row>
+ <row>
+ <entry>
+ <keycombo action="seq">
+ <keycap>~</keycap>
+ <keycombo action="simul">
+ <keycap>Ctrl</keycap>
+ <keycap>B</keycap>
+ </keycombo>
+ </keycombo>
+ </entry>
+ <entry>ALT BREAK</entry>
+ </row>
+ <row>
+ <entry>
+ <keycombo action="seq">
+ <keycap>~</keycap>
+ <keycombo action="simul">
+ <keycap>Ctrl</keycap>
+ <keycap>R</keycap>
+ </keycombo>
+ </keycombo>
+ </entry>
+ <entry>RESET target</entry>
+ </row>
+ <row>
+ <entry>
+ <keycombo action="seq">
+ <keycap>~</keycap>
+ <keycombo action="simul">
+ <keycap>Ctrl</keycap>
+ <keycap>Z</keycap>
+ </keycombo>
+ </keycombo>
+ </entry>
+ <entry>Suspend dconschat</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Attach remote <acronym>GDB</acronym> by starting
+ &man.kgdb.1; with a remote debugging session:</para>
+
+ <screen><userinput>kgdb -r :12345 kernel</userinput></screen>
+
+ </sect3>
+ <sect3>
+ <title>Some general tips</title>
+
+ <para>Here are some general tips:</para>
+
+ <para>To take full advantage of the speed of &firewire;,
+ disable other slow console drivers:</para>
+
+ <screen>&prompt.root; conscontrol delete ttyd0 # serial console
+&prompt.root; conscontrol delete consolectl # video/keyboard</screen>
+
+ <para>There exists a <acronym>GDB</acronym> mode for
+ &man.emacs.1;; this is what you will need to add to your
+ <filename>.emacs</filename>:</para>
+
+ <screen><userinput>(setq gud-gdba-command-name "kgdb -a -a -a -r :12345")
+(setq gdb-many-windows t)
+(xterm-mouse-mode 1)
+M-x gdba</userinput></screen>
+
+ <para>And for <acronym>DDD</acronym> (<filename>devel/ddd</filename>):</para>
+
+ <screen># remote serial protocol
+LANG=C ddd --debugger kgdb -r :12345 kernel
+# live core debug
+LANG=C ddd --debugger kgdb kernel /dev/fwmem0.2</screen>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Dcons with KVM</title>
+
+ <para>We can directly read the &man.dcons.4; buffer via
+ <filename>/dev/mem</filename> for live systems, and in the
+ core dump for crashed systems. These give you similar output
+ to <command>dmesg -a</command>, but the &man.dcons.4; buffer
+ includes more information.</para>
+
+ <sect3>
+ <title>Using Dcons with KVM</title>
+
+ <para>To use &man.dcons.4; with <acronym>KVM</acronym>:</para>
+
+ <para>Dump a &man.dcons.4; buffer of a live system:</para>
+
+ <screen>&prompt.root; <userinput>dconschat -1</userinput></screen>
+
+ <para>Dump a &man.dcons.4; buffer of a crash dump:</para>
+
+ <screen>&prompt.root; <userinput>dconschat -1 -M vmcore.XX</userinput></screen>
+
+ <para>Live core debugging can be done via:</para>
+
+ <screen>&prompt.root; <userinput>fwcontrol -m target_eui64</userinput>
+&prompt.root; <userinput>kgdb kernel /dev/fwmem0.2</userinput></screen>
+ </sect3>
+ </sect2>
+ </sect1>
+
<sect1 id="kerneldebug-options">
<title>Glossary of Kernel Options for Debugging</title>
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
index 2451e051e2..6d7432628c 100644
--- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
+++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
@@ -142,161 +142,12 @@
key issue in the decisions.</para>
<note>
- <para>Because of some unfortunate design limitations with the <acronym role="Revision Control System">RCS</acronym> file
- format and the use of vendor branches, minor, trivial and/or
+ <para>Because it makes it harder to import future versions
+ 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.
- The repository bloat impact from a single character
- change can be rather dramatic.</para>
+ files that are still tracking the vendor branch.</para>
</note>
- <sect2 id="vendor-import-cvs">
- <title>Vendor Imports with CVS</title>
-
- <para>The <application>file</application> utility, used to identify
- the format of a file, will be used as example of how this model
- works:</para>
-
- <para><filename>src/contrib/file</filename> contains the source as
- distributed by the maintainers of this package. Parts that are entirely
- not applicable for &os; can be removed. In the case of &man.file.1;, the
- <filename>python</filename> subdirectory and files with the <filename>lt</filename>
- prefix were eliminated before the import, amongst others.</para>
-
- <para><filename>src/lib/libmagic</filename> contains a <application>bmake</application> 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/file</filename> contains a <application>bmake</application> style
- <filename>Makefile</filename> which will produce and install the
- <command>file</command> program and its associated man-pages using the
- standard <filename>bsd.prog.mk</filename> rules.</para>
-
- <para>The important thing here is that the
- <filename>src/contrib/file</filename> directory is created according to
- the rules: it is supposed to contain the sources as distributed (on a
- proper vendor-branch and without <acronym>RCS</acronym> keyword expansion) with as few
- FreeBSD-specific changes as possible. 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>.</para>
-
- <para>Because of the previously mentioned design limitations with
- 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 <quote>committed</quote>, 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 than 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/file</filename> level directory, a file
- called <filename>FREEBSD-upgrade</filename> should be added and it
- should state 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>Example wording from
- <filename>src/contrib/groff/FREEBSD-upgrade</filename> is
- below:</para>
-
- <programlisting>&dollar;FreeBSD: src/contrib/groff/FREEBSD-upgrade,v 1.5.12.1 2005/11/15 22:06:18 ru Exp $
-
-This directory contains virgin copies 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.
-
-To upgrade to a newer version of groff, when it is available:
- 1. Unpack the new version into an empty directory.
- [Do not make ANY changes to the files.]
-
- 2. Use the command:
- cvs import -m 'Virgin import of FSF groff v&lt;version&gt;' \
- src/contrib/groff FSF v&lt;version&gt;
-
- For example, to do the import of version 1.19.2, I typed:
- cvs import -m 'Virgin import of FSF groff v1.19.2' \
- src/contrib/groff FSF v1_19_2
-
- 3. Follow the instructions printed out in step 2 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 groff, simply patch and commit to the main
-branch (aka HEAD). Never make local changes on the FSF branch.
-
-All local changes should be submitted to Werner Lemberg &lt;wl@gnu.org&gt; or
-Ted Harding &lt;ted.harding@nessie.mcc.ac.uk&gt; for inclusion in the next
-vendor release.
-
-ru@FreeBSD.org - 20 October 2005</programlisting>
-
- <para>Another approach my also be taken for the list of files to be
- excluded, which is especially useful when the list is large or
- complicated or where imports happen frequently. By creating a
- file <filename>FREEBSD-Xlist</filename> in the same directory the
- vendor source is imported into, containing a list of filename
- patterns to be excluded one per line, future imports can often
- performed with:</para>
-
- <screen>&prompt.user; <userinput><command>tar</command> <option>-X</option> <filename>FREEBSD-Xlist</filename> <option>-xzf</option> <filename><replaceable>vendor-source.tgz</replaceable></filename></userinput></screen>
-
- <para>An example of a <filename>FREEBSD-Xlist</filename> file, from
- <filename>src/contrib/tcsh</filename>, is here:</para>
-
- <programlisting>*/BUGS
-*/config/a*
-*/config/bs2000
-*/config/bsd
-*/config/bsdreno
-*/config/[c-z]*
-*/tests
-*/win32</programlisting>
-
- <note>
- <para>Please do not import <filename>FREEBSD-upgrade</filename> or
- <filename>FREEBSD-Xlist</filename> with the contributed source.
- Rather you should add these files after the initial
- import.</para>
- </note>
-
- </sect2>
-
<sect2 id="vendor-import-svn">
<sect2info>
<authorgroup>
diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
index bba1da5520..08710e0134 100644
--- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
+++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
@@ -349,9 +349,11 @@
<sect1 id="tools-compiling">
<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
+ <para>This section deals with the <application>gcc</application>
+ and <application>clang</application> compilers for C and C++,
+ since they come with the &os; base system. Starting with
+ &os;&nbsp;10.X <command>clang</command> is installed as
+ <command>cc</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
@@ -377,14 +379,7 @@
<step>
<para>Convert the source code into assembly
language&mdash;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>
+ understandable by humans. Allegedly.</para>
</step>
<step>
@@ -537,13 +532,7 @@
an executable that runs faster than normal. You can add a
number after the <option>-O</option> to specify a higher
level of optimization, but this often exposes bugs in the
- compiler's optimizer. 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>Optimization is usually only turned on when compiling
- a release version.</para>
+ compiler's optimizer.</para>
<informalexample>
<screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
diff --git a/en_US.ISO8859-1/books/faq/Makefile b/en_US.ISO8859-1/books/faq/Makefile
index e2e7548a0a..cfea6ba431 100644
--- a/en_US.ISO8859-1/books/faq/Makefile
+++ b/en_US.ISO8859-1/books/faq/Makefile
@@ -16,11 +16,11 @@ INSTALL_ONLY_COMPRESSED?=
WITH_BIBLIOXREF_TITLE?=YES
#
-# SRCS lists the individual SGML files that make up the document. Changes
+# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
-# SGML content
+# XML content
SRCS= book.xml
URL_RELPREFIX?= ../../../..
diff --git a/en_US.ISO8859-1/books/faq/book.xml b/en_US.ISO8859-1/books/faq/book.xml
index 813c654451..8f855241e8 100644
--- a/en_US.ISO8859-1/books/faq/book.xml
+++ b/en_US.ISO8859-1/books/faq/book.xml
@@ -50,6 +50,7 @@
<year>2010</year>
<year>2011</year>
<year>2012</year>
+ <year>2013</year>
<holder>The &os; Documentation Project</holder>
</copyright>
@@ -57,24 +58,18 @@
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
- &tm-attrib.3com;
&tm-attrib.adobe;
- &tm-attrib.creative;
- &tm-attrib.cvsup;
&tm-attrib.ibm;
&tm-attrib.ieee;
&tm-attrib.intel;
- &tm-attrib.iomega;
&tm-attrib.linux;
&tm-attrib.microsoft;
&tm-attrib.mips;
- &tm-attrib.netscape;
&tm-attrib.opengroup;
&tm-attrib.oracle;
&tm-attrib.sgi;
&tm-attrib.sparc;
&tm-attrib.sun;
- &tm-attrib.usrobotics;
&tm-attrib.general;
</legalnotice>
@@ -88,14 +83,13 @@
unless otherwise noted. 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/doc/en_US.ISO8859-1/books/faq/index.html">&os; World Wide Web server</ulink>.
+ url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">&os; website</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="book.html">HTML</ulink> file with HTTP or as a variety
+ of other formats from the <ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP
server</ulink>. You may also want to <ulink
- url="&url.base;/search/index.html">Search the FAQ</ulink>.
- </para>
+ url="&url.base;/search/index.html">Search the FAQ</ulink>.</para>
</abstract>
</bookinfo>
@@ -124,18 +118,18 @@
</question>
<answer>
- <para>Briefly, &os; is a &unix;&nbsp;like operating system for
- AMD64 and &intel; EM64T, &i386; PC-98, IA-64, &arm;,
- &powerpc; and &ultrasparc; platforms based on U.C.
+ <para>&os; is a modern operating system for desktops,
+ laptops, servers, and embedded systems with
+ support for a large number of <ulink
+ url="http://www.FreeBSD.org/platforms/">platforms</ulink>.</para>
+
+ <para>It is based on U.C.
Berkeley's <quote>4.4BSD-Lite</quote> release, with some
<quote>4.4BSD-Lite2</quote> enhancements. It is also based
indirectly on William Jolitz's port of U.C. Berkeley's
<quote>Net/2</quote> to the &i386;, known as
<quote>386BSD</quote>, though very little of the 386BSD code
- remains. A fuller description of what &os; is and how it
- can work for you may be found on the <ulink
- url="&url.base;/index.html">&os; home page</ulink>.
- </para>
+ remains.</para>
<para>&os; is used by companies, Internet Service Providers,
researchers, computer professionals, students and home users
@@ -144,8 +138,7 @@
<para>For more detailed information on &os;, please see the
<ulink
- url="&url.books.handbook;/index.html">&os; Handbook</ulink>.
- </para>
+ url="&url.books.handbook;/index.html">&os; Handbook</ulink>.</para>
</answer>
</qandaentry>
@@ -155,32 +148,11 @@
</question>
<answer>
- <para>The goal of the &os; Project is 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 definitely do not 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
- <ulink
- url="http://www.FreeBSD.org/copyright/COPYING">GNU General Public License (GPL)</ulink>
- or <ulink
- url="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU Library General Public License (LGPL)</ulink>
- 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 <ulink
- url="http://www.FreeBSD.org/copyright/freebsd-license.html">&os; license</ulink>
- whenever possible.</para>
+ <para>The goal of the &os; Project is to provide a
+ stable and fast general purpose
+ operating system that may
+ be used for any purpose
+ without strings attached.</para>
</answer>
</qandaentry>
@@ -205,7 +177,39 @@
<listitem>
<para>Do not sue us if it breaks.</para>
</listitem>
+
+ <listitem>
+ <para>Do not remove or modify the license.</para>
+ </listitem>
</itemizedlist>
+
+ <para>Many of us have a significant investment in the
+ project
+ and would certainly not mind a little financial
+ compensation now and then, but we definitely do not 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, we believe, is one of the most
+ fundamental
+ goals of Free Software and one that we enthusiastically
+ support.</para>
+
+ <para>Code in our source tree which falls under the
+ <ulink
+ url="http://www.FreeBSD.org/copyright/COPYING">GNU General Public License (GPL)</ulink>
+ or <ulink
+ url="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU Library General Public License (LGPL)</ulink>
+ 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 <ulink
+ url="http://www.FreeBSD.org/copyright/freebsd-license.html">&os; license</ulink>
+ whenever possible.</para>
</answer>
</qandaentry>
@@ -227,8 +231,7 @@
network servers, and just about everything else you might
want. Most of these applications can be managed through the
<ulink
- url="http://www.FreeBSD.org/ports/">Ports Collection</ulink>.
- </para>
+ url="http://www.FreeBSD.org/ports/">Ports Collection</ulink>.</para>
<para>If you need to use an application that is only available
on one operating system, you simply cannot replace that
@@ -244,7 +247,11 @@
<para>If you are migrating to &os; from some other &unix;
environment, you already know most of what you need to. If
your background is in graphic-driven operating systems such
- as &windows; and older versions of &macos;, expect to invest
+ as &windows; and &macos;, you may be interested in using
+ <ulink
+ url="http://www.pcbsd.org/">PC-BSD</ulink>, a &os; based
+ distribution, instead. If you have not used &unix; before
+ expect to invest
additional time learning the &unix; way of doing things.
This FAQ and the <ulink
url="&url.books.handbook;/index.html">&os; Handbook</ulink>
@@ -299,7 +306,37 @@
differences between the various projects,
called <ulink
url="http://www.freebsdworld.gr/freebsd/bsd-family-tree.html">The BSD Family Tree</ulink>
- which goes a fair way to answering this question.</para>
+ which goes a fair way to answering this question.
+ Some of the information is out of date, but the history
+ portion in particular remains accurate.</para>
+
+ <para>Most of the BSDs share patches and code, even today.
+ All of the BSDs have common ancestry.</para>
+
+ <para>The design goals of &os; are described in
+ <xref linkend="FreeBSD-goals"/>, above. The design goals
+ of the other most popular BSDs may be summarized as
+ follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>OpenBSD aims for operating system security above
+ all else. The OpenBSD team wrote &man.ssh.1; and
+ &man.pf.4;, which have both been ported to &os;.</para>
+ </listitem>
+
+ <listitem>
+ <para>NetBSD aims to be easily ported to other hardware
+ platforms.</para>
+ </listitem>
+
+ <listitem>
+ <para>DragonFlyBSD is a fork of &os;&nbsp;4.8 that has
+ since developed many interesting features of its own,
+ including the HAMMER file system and support for
+ user-mode <quote>vkernels</quote>.</para>
+ </listitem>
+ </itemizedlist>
</answer>
</qandaentry>
@@ -308,11 +345,6 @@
<para>What is the latest version of &os;?</para>
</question>
-<!--
- This answer is a hack to deal with the fact that for now there are
- multiple "latest" versions of FreeBSD.
--->
-
<answer>
<para>At any point in the development of &os;, there can be
multiple parallel branches. &rel.relx; releases are
@@ -372,29 +404,24 @@
<answer>
<para><ulink
- url="&url.books.handbook;/current-stable.html#CURRENT">&os.current;</ulink>
+ url="&url.books.handbook;/current-stable.html#current">&os.current;</ulink>
is the development version of the operating system, which
will in due course become the new &os.stable; branch. As
such, it is really only of interest to developers working on
the system and die-hard hobbyists. See the <ulink
- url="&url.books.handbook;/current-stable.html#CURRENT">relevant section</ulink>
+ url="&url.books.handbook;/current-stable.html#current">relevant section</ulink>
in the <ulink
url="&url.books.handbook;/index.html">Handbook</ulink> for
details on running <emphasis>-CURRENT</emphasis>.</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
+ <para>If you are not familiar with &os;
+ you should not use
&os.current;. This branch sometimes evolves quite quickly
- and can be un-buildable sometimes.
+ and due to mistake can be un-buildable at times.
People that use &os.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 &a.current; may be treated with
- contempt.</para>
+ analyze, debug, and report problems.</para>
- <para>Every month, <ulink
+ <para>&os; <ulink
url="&url.base;/snapshots/">snapshot</ulink>
releases are made based on the current state of the
<emphasis>-CURRENT</emphasis> and
@@ -437,15 +464,10 @@
<emphasis>-STABLE</emphasis> snapshots.</para>
<para>Snapshot releases are directly available from <ulink
- url="&url.base;/snapshots/">snapshot</ulink>.
- </para>
+ url="&url.base;/snapshots/">snapshot</ulink>.</para>
- <para>Official snapshots are generated each month on a regular
- basis for all actively developed branches. There are also
- daily snapshot builds of the popular &arch.i386; and
- &arch.amd64; branches, hosted on <ulink
- url="http://snapshots.us.freebsd.org/"></ulink>.
- </para>
+ <para>Official snapshots are generated on a regular
+ basis for all actively developed branches.</para>
</answer>
</qandaentry>
@@ -458,9 +480,9 @@
<answer>
<para>Back when &os;&nbsp;2.0.5 was released, &os; development
branched in two. One branch was named <ulink
- url="&url.books.handbook;/current-stable.html#STABLE">-STABLE</ulink>,
+ url="&url.books.handbook;/current-stable.html#stable">-STABLE</ulink>,
one <ulink
- url="&url.books.handbook;/current-stable.html#CURRENT">-CURRENT</ulink>.
+ url="&url.books.handbook;/current-stable.html#current">-CURRENT</ulink>.
<emphasis>&os;-STABLE</emphasis> is intended for Internet
Service Providers and other commercial enterprises for whom
sudden shifts or experimental features are quite
@@ -470,24 +492,10 @@
been one unbroken line since 2.0 was released, leading
towards &rel.current;-RELEASE and beyond. For more detailed
information on branches see <quote><ulink
- url="&url.articles.releng;/release-proc.html#REL-BRANCH">&os; Release Engineering: Creating the Release Branch</ulink></quote>,
+ url="&url.articles.releng;/release-proc.html#rel-branch">&os; Release Engineering: Creating the Release Branch</ulink></quote>,
the status of the branches and the upcoming release schedule
can be found on the <ulink
- url="http://www.FreeBSD.org/releng">Release Engineering Information</ulink> page.
- </para>
-
- <para>The 2.2-STABLE branch was retired with the release of
- 2.2.8. The 3-STABLE branch has ended with the release of
- 3.5.1, the final 3.<replaceable>X</replaceable> release.
- The 4-STABLE branch has ended with the release of 4.11, the
- final 4.<replaceable>X</replaceable> release. The only
- changes made to either of these branches will be, for the
- most part, security-related bug fixes. Support for the
- 5-STABLE branches has ended with the release of 5.5, the
- final 5.<replaceable>X</replaceable> release. Support for
- the 6-STABLE branch will continue for some time but focus
- primarily on security-related bug fixes and other serious
- issues.</para>
+ url="http://www.FreeBSD.org/releng">Release Engineering Information</ulink> page.</para>
<para>&rel.current;-STABLE is the actively developed
<emphasis>-STABLE</emphasis> branch. The latest release on
@@ -513,7 +521,7 @@
on average. Release dates are announced well in advance, so
that the people working on the system know when their
projects need to be finished and tested. A testing period
- precedes each release, in order to ensure that the addition
+ precedes each release, to ensure that the addition
of new features does not compromise the stability of the
release. Many users regard this caution as one of the best
things about &os;, even though waiting for all the latest
@@ -543,7 +551,7 @@
url="&url.base;/administration.html#t-core">core team</ulink> of
9 people. There is a much larger team of more than 350
<ulink
- url="&url.articles.contributors;/article.html#STAFF-COMMITTERS">committers</ulink>
+ url="&url.articles.contributors;/article.html#staff-committers">committers</ulink>
who are authorized to make changes directly to the &os;
source tree.</para>
@@ -562,15 +570,13 @@
<answer>
<para>Every significant release of &os; is available via
anonymous FTP from the <ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> &os; FTP site</ulink>:
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> &os; FTP site</ulink>:</para>
<itemizedlist>
<listitem>
<para>The latest &rel.stable; release, &rel.current;-RELEASE
can be found in the <ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</ulink>.
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</ulink>.</para>
</listitem>
<listitem>
@@ -585,22 +591,13 @@
<listitem>
<para>The latest &rel2.stable; release, &rel2.current;-RELEASE
can be found in the <ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory</ulink>.
- </para>
- </listitem>
-
- <listitem>
- <para>The latest &rel3.stable; release, &rel3.current;-RELEASE
- can be found in the <ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel3.current;-RELEASE/">&rel3.current;-RELEASE directory</ulink>.
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory</ulink>.</para>
</listitem>
</itemizedlist>
<para>Information about obtaining &os; on CD, DVD, and other
media can be found in <ulink
- url="&url.books.handbook;/mirrors.html">the Handbook</ulink>.
- </para>
+ url="&url.books.handbook;/mirrors.html">the Handbook</ulink>.</para>
</answer>
</qandaentry>
@@ -627,19 +624,6 @@
an article on how to write good problem reports.</para>
</answer>
</qandaentry>
-
- <qandaentry>
- <question id="other-info-sources">
- <para>What other sources of information are there?</para>
- </question>
-
- <answer>
- <para>Please check the <ulink
- url="http://www.FreeBSD.org/docs.html">Documentation</ulink>
- list on the main <ulink
- url="http://www.FreeBSD.org">&os;</ulink> web site.</para>
- </answer>
- </qandaentry>
</qandaset>
</chapter>
@@ -909,8 +893,7 @@
</listitem>
<listitem>
- <para>The compression and packaging scheme. There are
- three of these currently in use.</para>
+ <para>The compression and packaging scheme.</para>
<orderedlist>
<listitem>
@@ -928,42 +911,11 @@
(i.e., <filename>article.pdf</filename>,
<filename>book.html</filename>, and so on).</para>
- <para>These files are then compressed using two
- compression schemes.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Scheme</entry>
-
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>zip</literal></entry>
-
- <entry>The <literal>zip</literal> format. If you want to
- uncompress this on &os; you will need to
- install the <filename
- role="package">archivers/unzip</filename>
- port first.</entry>
- </row>
-
- <row>
- <entry><literal>bz2</literal></entry>
-
- <entry>The <literal>bzip2</literal> format. Less widespread than
- <literal>zip</literal>, but generally gives smaller files.
- Install the <filename
- role="package">archivers/bzip2</filename>
- port to uncompress these files.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <para>These files are then compressed using either
+ the <literal>zip</literal> or
+ <literal>bz2</literal> compression schemes.
+ &man.tar.1; can be used to uncompress these
+ files.</para>
<para>So the &postscript; version of the Handbook,
compressed using <literal>bzip2</literal> will be stored in a file
@@ -980,16 +932,18 @@
appropriate documents into place.</para>
<para>For example, the split HTML version of the FAQ,
- compressed using &man.bzip2.1;, can be found in the
+ compressed using &man.bzip2.1;, can be found in
<filename>doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2</filename>
- file. To download and uncompress that file you would have
- to do this.</para>
+ 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.ISO8859-1/books/faq/book.html-split.tar.bz2</userinput>
-&prompt.root; <userinput>bzip2 -d book.html-split.tar.bz2</userinput>
-&prompt.root; <userinput>tar xvf book.html-split.tar</userinput></screen>
+&prompt.root; <userinput>tar xvf book.html-split.tar.bz2</userinput></screen>
- <para>You will be left with a collection of
+ <para>If the file is compressed,
+ <application>tar</application> will automatically
+ detect the appropriate format and decompress it correctly.
+ 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
@@ -1000,22 +954,14 @@
<qandaentry>
<question id="mailing">
- <para>Where do I find info on the &os; mailing lists?</para>
- </question>
-
- <answer>
- <para>You can find full information in the <ulink
- url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">Handbook entry on mailing-lists</ulink>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="newsgroups">
- <para>What &os; news groups are available?</para>
+ <para>Where do I find info on the &os; mailing lists?
+ What &os; news groups are available?</para>
</question>
<answer>
<para>You can find full information in the <ulink
+ url="&url.books.handbook;/eresources.html#eresources-mail">Handbook entry on mailing-lists</ulink>
+ and the <ulink
url="&url.books.handbook;/eresources-news.html">Handbook entry on newsgroups</ulink>.</para>
</answer>
</qandaentry>
@@ -1102,6 +1048,10 @@
</listitem>
</itemizedlist>
+ <para>The &os; wiki has a <ulink
+ url="http://wiki.freebsd.org/IrcChannels">good list</ulink>
+ of IRC channels.</para>
+
<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
@@ -1114,13 +1064,13 @@
</qandaentry>
<qandaentry>
- <question id="forums">
- <para>Are there any web based forums to discuss &os;?</para>
- </question>
- <answer>
- <para>The official &os; forums are located at <ulink
- url="http://forums.FreeBSD.org/">http://forums.FreeBSD.org/</ulink>.</para>
- </answer>
+ <question id="forums">
+ <para>Are there any web based forums to discuss &os;?</para>
+ </question>
+ <answer>
+ <para>The official &os; forums are located at <ulink
+ url="http://forums.FreeBSD.org/">http://forums.FreeBSD.org/</ulink>.</para>
+ </answer>
</qandaentry>
<qandaentry>
@@ -1141,11 +1091,10 @@
<para>BSD Certification Group, Inc. provides system
administration certifications for DragonFly&nbsp;BSD, &os;, NetBSD,
OpenBSD. If you are interested in them, visit <ulink
- url="http://www.BSDCertification.org">their site</ulink>.
- </para>
+ url="http://www.BSDCertification.org">their site</ulink>.</para>
<para>Any other organizations providing training and support
- should contact the Project in order to be listed here.</para>
+ should contact the Project to be listed here.</para>
</answer>
</qandaentry>
</qandaset>
@@ -1165,70 +1114,105 @@
<title>Installation</title>
<qandaset>
+
+ <qandaentry>
+ <question id="which-architecture">
+ <para>Which platform should I download? I have a 64
+ bit capable &intel; CPU,
+ but I only see <literal>amd64</literal>.</para>
+ </question>
+
+ <answer>
+ <para>&arch.amd64; is the term &os; uses for 64-bit
+ compatible x86 architectures. Most modern computers
+ should use &arch.amd64;. Older hardware should use
+ &arch.i386;. If you are installing on a
+ non-x86-compatible architecture select the platform
+ which best matches the architecture you are
+ using.</para>
+ </answer>
+ </qandaentry>
+
<qandaentry>
<question id="floppy-download">
<para>Which file do I download to get &os;?</para>
</question>
<answer>
- <para>You need three floppy images:
- <filename>floppies/boot.flp</filename>,
- <filename>floppies/kern1.flp</filename>, and
- <filename>floppies/kern2.flp</filename>. These images need
- to be copied onto floppies by tools like
- <command>fdimage</command> or &man.dd.1;.</para>
+ <para>On the
+ <ulink url="http://www.freebsd.org/where.html">Getting &os;</ulink>
+ page select <literal>[iso]</literal> next to the
+ architecture you want to use.</para>
- <para>If you need to download the distributions yourself (for
- a DOS file system install, for instance), below are some
- recommendations for distributions to grab:</para>
+ <para>Any of the following can be used:</para>
- <itemizedlist>
- <listitem>
- <para>base/</para>
- </listitem>
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>file</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
- <listitem>
- <para>manpages/</para>
- </listitem>
+ <tbody>
+ <row>
+ <entry><filename>disc1.iso</filename></entry>
+ <entry>Contains enough to install &os; and
+ a minimal set of packages.</entry>
+ </row>
- <listitem>
- <para>compat*/</para>
- </listitem>
+ <row>
+ <entry><filename>dvd1.iso</filename></entry>
+ <entry>Similar to <filename>disc1.iso</filename>
+ but with additional packages.</entry>
+ </row>
- <listitem>
- <para>doc/</para>
- </listitem>
+ <row>
+ <entry><filename>memstick.img</filename></entry>
+ <entry>A bootable image sufficient for copying to a
+ USB stick.</entry>
+ </row>
- <listitem>
- <para>src/ssys.*</para>
- </listitem>
- </itemizedlist>
+ <row>
+ <entry><filename>bootonly.iso</filename></entry>
+ <entry>A minimal image that requires network
+ access during installation to completely
+ install &os;.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>&arch.pc98; users require these floppy images:
+ <filename>floppies/boot.flp</filename>,
+ <filename>floppies/kern1.flp</filename>,
+ <filename>floppies/kern2.flp</filename>, and
+ <filename>floppies/mfsroot1.flp</filename>. These images
+ need
+ to be copied onto floppies by tools like
+ &man.dd.1;.</para>
<para>Full instructions on this procedure and a little bit
more about installation issues in general can be found in
the <ulink
- url="&url.books.handbook;/install.html">Handbook entry on installing &os;</ulink>.
- </para>
+ url="&url.books.handbook;/install.html">Handbook entry on installing &os;</ulink>.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="floppy-image-too-large">
- <para>What do I do if the floppy images does not fit on a
- single floppy?</para>
+ <para>What do I do if the images do not fit on a
+ single disk?</para>
</question>
<answer>
- <para>A 3.5&nbsp;inch (1.44&nbsp;MB) floppy can accommodate
- 1,474,560&nbsp;bytes of data. The boot image is exactly
- 1,474,560&nbsp;bytes in size.</para>
-
- <para>Common mistakes when preparing the boot floppy
+ <para>Common mistakes when preparing the boot media
are:</para>
<itemizedlist>
<listitem>
- <para>Not downloading the floppy image in
+ <para>Not downloading the image in
<emphasis>binary</emphasis> mode when using
<acronym>FTP</acronym>.</para>
@@ -1236,7 +1220,8 @@
<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
+ invariably corrupt the boot image. Check the SHA-256
+ of
the downloaded boot image: if it is not
<emphasis>exactly</emphasis> that on the server, then
the download process is suspect.</para>
@@ -1258,10 +1243,9 @@
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
+ tools (e.g., <command>fdimage</command> or
<command>rawrite</command>) described in the <ulink
- url="&url.books.handbook;/install.html">installation guide to &os;</ulink>.
- </para>
+ url="&url.books.handbook;/install.html">installation guide to &os;</ulink>.</para>
</listitem>
</itemizedlist>
</answer>
@@ -1273,15 +1257,17 @@
</question>
<answer>
- <para>Installation instructions can be found in the <ulink
- url="&url.books.handbook;/install.html">Handbook entry on installing &os;</ulink>.
- </para>
+ <para>Installation instructions for versions since
+ &os;&nbsp;9.0 can be found at <ulink
+ url="&url.books.handbook;/bsdinstall.html">Handbook entry on installing &os;</ulink>.
+ Older instructions can be found in the <ulink
+ url="&url.books.handbook;/install.html">legacy entry on installing &os;</ulink>.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="need-to-run">
- <para>What do I need in order to run &os;?</para>
+ <para>What do I need to run &os;?</para>
</question>
<answer>
@@ -1295,7 +1281,7 @@
<qandaentry>
<question id="custom-boot-floppy">
- <para>How can I make my own custom install disk?</para>
+ <para>How can I make my own custom release or install disk?</para>
</question>
<answer>
@@ -1313,7 +1299,8 @@
</question>
<answer>
- <para>Install &windows; first, then &os;. &os;'s boot manager
+ <para>If &windows; is installed first, then yes.
+ &os;'s boot manager
will then manage to boot &windows; and &os;. If you install
&windows; second, it will boorishly overwrite your boot
manager without even asking. If that happens, see the next
@@ -1322,287 +1309,26 @@
</qandaentry>
<qandaentry>
- <question id="win95-damaged-boot-manager">
- <para>&windows; killed my boot manager! How do I get it
- back?</para>
- </question>
-
- <answer>
- <para>You can reinstall the boot manager &os; comes with in
- one of three ways:</para>
-
- <itemizedlist>
- <listitem>
- <para>Running DOS, go into the <filename
- class="directory">tools</filename> directory of your
- &os; distribution and look for
- <filename>bootinst.exe</filename>. You run it like
- so:</para>
-
- <screen><prompt>...\TOOLS&gt;</prompt> <userinput>bootinst.exe boot.bin</userinput></screen>
-
- <para>and the boot manager will be reinstalled.</para>
- </listitem>
-
- <listitem>
- <para>Boot the &os; boot floppy again and go to the
- <guimenuitem>Custom</guimenuitem> menu item for custom
- installation. Choose
- <guimenuitem>Partition</guimenuitem>. 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) press <keycap>W</keycap>. This will ask for
- confirmation, select &gui.yes;, and when you get the
- Boot Manager selection prompt, be sure to select the
- <application>&os; Boot Manager</application>. 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 &os; boot floppy (or CD-ROM) and choose the
- <guimenuitem>Fixit</guimenuitem> 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="boot-on-thinkpad">
- <para>My A, T, or X series IBM Thinkpad locks up when I first
- booted up my &os; installation. How can I solve
- this?</para>
- </question>
-
- <answer>
- <para>A bug in early revisions of IBM's BIOS on these machines
- mistakenly identifies the &os; partition as a potential FAT
- suspend-to-disk partition. When the BIOS tries to parse the
- &os; partition it hangs.</para>
-
- <para>According to IBM<footnote>
- <para>In an email from Keith Frechette
- <email>kfrechet@us.ibm.com</email>.</para></footnote>,
- the following model/BIOS release numbers incorporate the
- fix.</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Model</entry>
-
- <entry>BIOS revision</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>T20</entry>
-
- <entry>IYET49WW or later</entry>
- </row>
-
- <row>
- <entry>T21</entry>
-
- <entry>KZET22WW or later</entry>
- </row>
-
- <row>
- <entry>A20p</entry>
-
- <entry>IVET62WW or later</entry>
- </row>
-
- <row>
- <entry>A20m</entry>
-
- <entry>IWET54WW or later</entry>
- </row>
-
- <row>
- <entry>A21p</entry>
-
- <entry>KYET27WW or later</entry>
- </row>
-
- <row>
- <entry>A21m</entry>
-
- <entry>KXET24WW or later</entry>
- </row>
-
- <row>
- <entry>A21e</entry>
-
- <entry>KUET30WW</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>It has been reported that later IBM BIOS revisions may
- have reintroduced the bug. <ulink
- url="http://docs.FreeBSD.org/cgi/mid.cgi?20010427133759.A71732">This message</ulink>
- from &a.nectar; to the &a.mobile; describes a procedure
- which may work if your newer IBM laptop does not boot &os;
- properly, and you can upgrade or downgrade the BIOS.</para>
-
- <para>If you have an earlier BIOS, and upgrading is not an
- option, a workaround is to install &os;, change the partition
- ID &os; uses, and install new boot blocks that can handle
- the different partition ID.</para>
-
- <para>First, you will need to restore the machine to a state
- where it can get through its self-test screen. Doing this
- requires powering up the machine without letting it find a
- &os; partition on its primary disk. One way is to remove
- the hard disk and temporarily move it to an older ThinkPad
- (such as a ThinkPad 600) or a desktop PC with an appropriate
- conversion cable. Once it is there, you can delete the &os;
- partition and move the hard disk back. The ThinkPad should
- now be in a bootable state again.</para>
-
- <para>With the machine functional again, you can use the
- workaround procedure described here to get a working &os;
- installation.</para>
-
- <procedure>
- <step>
- <para>Download <filename>boot1</filename> and
- <filename>boot2</filename> from <ulink
- url="http://people.FreeBSD.org/~bmah/ThinkPad/"></ulink>.
- Put these files somewhere you will be able to retrieve
- them later.</para>
- </step>
-
- <step>
- <para>Install &os; as normal on to the ThinkPad.
- <emphasis>Do not</emphasis> use <literal>Dangerously
- Dedicated</literal> mode. <emphasis>Do not</emphasis>
- reboot when the install has finished.</para>
- </step>
-
- <step>
- <para>Either switch to the <quote>Emergency Holographic
- Shell</quote> (<keycombo
- action="simul"><keycap>Alt</keycap><keycap>F4</keycap></keycombo>)
- or start a <quote>fixit</quote> shell.</para>
- </step>
-
- <step>
- <para>Use &man.fdisk.8; to change the &os; partition ID
- from <literal>165</literal> to <literal>166</literal>
- (this is the type used by OpenBSD).</para>
- </step>
-
- <step>
- <para>Bring the <filename>boot1</filename> and
- <filename>boot2</filename> files to the local file
- system.</para>
- </step>
-
- <step>
- <para>Use &man.disklabel.8; to write
- <filename>boot1</filename> and <filename>boot2</filename>
- to your &os; slice.</para>
-
- <screen>&prompt.root; <userinput>disklabel -B -b boot1 -s boot2 ad0s<replaceable>n</replaceable></userinput></screen>
-
- <para><replaceable>n</replaceable> is the number of the
- slice where you installed &os;.</para>
- </step>
-
- <step>
- <para>Reboot. At the boot prompt you will be given the
- option of booting <literal>OpenBSD</literal>. This will
- actually boot &os;.</para>
- </step>
- </procedure>
-
- <para>Getting this to work in the case where you want to dual
- boot OpenBSD and &os; on the same laptop is left as an
- exercise for the reader.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="install-bad-blocks">
- <para>Can I install on a disk with bad blocks?</para>
- </question>
-
- <answer>
- <para>You can, but it is a bad idea.</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 buy 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!
- What is happening?</para>
+ <question id="bootmanager-restore">
+ <para>Another operating system destroyed my Boot Manager. How
+ do I get it back?</para>
</question>
<answer>
- <para>If you are 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>
+ <para>This depends on what boot manager you have installed.
+ The &os; boot selection menu (likely what you are using
+ if you end up in this situation) can be reinstalled using
+ &man.boot0cfg.8;. For example, to restore the boot menu
+ onto the disk <replaceable>ada0</replaceable>:</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 cover disk that has been
- lying under the bed for the last three years)?</para>
- </listitem>
+ <screen>&prompt.root; <userinput>boot0cfg -B ada0</userinput></screen>
- <listitem>
- <para>Did you download the floppy image in binary (or
- image) mode? (do not be embarrassed, even the best of us
- have accidentally downloaded a binary file in ASCII mode
- at least once!)</para>
- </listitem>
+ <para>The non-interactive MBR bootloader can be installed using
+ &man.gpart.8;:</para>
- <listitem>
- <para>If you are using &windows;&nbsp;95 or
- &windows;&nbsp;98 did you run <command>fdimage</command>
- or <command>rawrite</command> in pure DOS mode? These
- operating systems 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>
+ <screen>&prompt.root; <userinput>gpart bootcode -b /boot/mbr ada0</userinput></screen>
- <para>There have also been reports of &netscape; causing
- problems when downloading the boot floppy, so it is probably
- best to use a different FTP client if you can.</para>
+ <para>For more complex situations, including GPT disks, see &man.gpart.8;.</para>
</answer>
</qandaentry>
@@ -1631,174 +1357,6 @@
</qandaentry>
<qandaentry>
- <question id="install-PLIP">
- <para>Can I install on my laptop over PLIP (Parallel Line
- IP)?</para>
- </question>
-
- <answer>
- <para>Yes. Use a standard Laplink cable. If necessary, you
- can check out the <ulink
- url="&url.books.handbook;/network-plip.html">PLIP section of the Handbook</ulink>
- for details on parallel port networking.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="geometry">
- <para>Which geometry should I use for a disk drive?</para>
- </question>
-
- <answer>
- <note>
- <para>By the <quote>geometry</quote> of a disk, we mean
- the number of cylinders, heads and sectors/track on a
- disk. We will 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>
- </note>
-
- <para>This causes a lot of confusion among new system
- administrators. First of all, the
- <emphasis>physical</emphasis> geometry of a SCSI drive is
- totally irrelevant, as &os; works in term of disk blocks.
- In fact, there is no such thing as <quote>the</quote>
- physical geometry, as the sector density varies across the
- disk. What manufacturers claim is the <quote>physical
- geometry</quote> is usually the geometry that they have
- determined wastes the least space. For IDE disks, &os; does
- work in terms of C/H/S, but all modern drives internally
- convert this into block references.</para>
-
- <para>All that matters is the <emphasis>logical</emphasis>
- geometry. This is the answer that the BIOS gets when it
- asks the drive <quote>what is your geometry?</quote> It then
- uses this geometry to access the disk. As &os; uses the
- BIOS when booting, it is 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
- &gt;1GB</quote> or something similar). If it is 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 2&nbsp;GB disk
- should pretend to have 2048 cylinders, 64 heads and 32
- sectors/track.</para>
-
- <para>If it <emphasis>is</emphasis> turned on (it is often
- supplied this way to get around certain limitations in
- &ms-dos;) and the disk capacity is more than 1&nbsp;GB, use
- <replaceable>M</replaceable> cylinders, 63 sectors per track
- (<emphasis>not</emphasis> 64), and 255 heads, where
- <replaceable>M</replaceable> is the disk capacity in MB
- divided by 7.844238 (!). So our example 2&nbsp;GB drive
- would have 261 cylinders, 63 sectors per track and 255
- heads.</para>
-
- <para>If you are not sure about this, or &os; 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 BIOS should then detect the correct geometry,
- and you can always remove the DOS partition in the partition
- editor if you do not want to keep it. You might want to
- leave it around for programming network cards and the like,
- however.</para>
-
- <para>Alternatively, there is a freely available utility
- distributed with &os; called
- <filename>pfdisk.exe</filename>. You can find it in the
- <filename class="directory">tools</filename> subdirectory on
- the &os; CD-ROM or on the various &os; FTP sites. This
- program 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>Are there 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
- &os;).</para>
-
- <para>For a SCSI drive, this will normally imply that the root
- partition will be in the first 1024&nbsp;MB (or in the first
- 4096&nbsp;MB if extended translation is turned on &mdash; see
- previous question). For IDE, the corresponding figure is
- 504&nbsp;MB.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="disk-manager">
- <para>Is &os; compatible with any disk managers?</para>
- </question>
-
- <answer>
- <para>&os; recognizes the <application>Ontrack Disk
- Manager</application> and makes allowances for it. Other disk
- managers are not supported.</para>
-
- <para>If you just want to use the disk with &os; you do not
- need a disk manager. Just configure the disk for as much
- space as the BIOS can deal with (usually
- 504&nbsp;megabytes), and &os; should figure out how much
- space you really have. If you are using an old disk with an
- MFM controller, you may need to explicitly tell &os; how
- many cylinders to use.</para>
-
- <para>If you want to use the disk with &os; and another
- operating system, you may be able to do without a disk
- manager: just make sure the &os; boot partition and the
- slice for the other operating system are in the first 1024
- cylinders. If you are reasonably careful, a
- 20&nbsp;megabyte boot partition should be plenty.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="missing-os">
- <para>When I boot &os; for the first time after install I get
- <errorname>Missing Operating System</errorname>. What is
- happening?</para>
- </question>
-
- <answer>
- <para>This is classically a case of &os; and DOS or some other
- OS conflicting over their ideas of disk <link
- linkend="geometry">geometry</link>. You will have to
- reinstall &os;, but obeying the instructions given above
- will almost always get you going.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="stop-at-boot-manager">
- <para>Why can I not get past the boot manager's
- <prompt>F?</prompt> prompt?</para>
- </question>
-
- <answer>
- <para>This is another symptom of the problem described in the
- preceding question. Your BIOS geometry and &os; geometry
- settings do not agree! If your controller or BIOS supports
- cylinder translation (often marked as <quote>&gt;1GB drive
- support</quote>), try toggling its setting and reinstalling
- &os;.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="need-complete-sources">
<para>Do I need to install the source?</para>
</question>
@@ -1824,8 +1382,8 @@
kernel contains the drivers an ordinary computer will
need. &man.freebsd-update.8;, the &os; binary upgrade
tool, cannot upgrade custom kernels, another reason
- to stick with the GENERIC kernel when possible.
- For computers with very limited RAM, such as
+ to stick with the <literal>GENERIC</literal> kernel when
+ possible. For computers with very limited RAM, such as
embedded systems, it may be worthwhile to build a
smaller custom kernel containing just the required
drivers.</para>
@@ -1861,24 +1419,9 @@
</qandaentry>
<qandaentry>
- <question id="boot-floppy-hangs">
- <para>Why does the boot floppy start, but hang at the
- <literal>Probing Devices...</literal> screen?</para>
- </question>
-
- <answer>
- <para>If you have a IDE &iomegazip; 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>Why do I get a <errorname>panic: can't mount
- root</errorname> error when rebooting the system after
+ root</errorname> error when rebooting the system after
installation?</para>
</question>
@@ -1928,8 +1471,8 @@
</listitem>
<listitem>
- <para>Move the &os; disk onto the primary IDE
- controller, so the hard disks are consecutive.</para>
+ <para>Move the &os; disk onto the primary IDE
+ controller, so the hard disks are consecutive.</para>
</listitem>
</orderedlist>
</answer>
@@ -1944,8 +1487,7 @@
<para>Memory limits depend on the platform used. On a
standard &i386; install, the limit is 4&nbsp;GB but more
memory can be supported through &man.pae.4;. See <link
- linkend="memory-i386-over-4gb">instructions for using 4&nbsp;GB or more memory on &i386;</link>.
- </para>
+ linkend="memory-i386-over-4gb">instructions for using 4&nbsp;GB or more memory on &i386;</link>.</para>
<para>&os;/pc98 has a limit of 4&nbsp;GB memory, and PAE can
not be used with it. Other architectures supported by &os;
@@ -2067,6 +1609,21 @@
shows up before loader is started.</para>
</answer>
</qandaentry>
+
+ <qandaentry>
+ <question id="general-configuration-tool">
+ <para>Is there a tool to perform post-installation
+ configuration tasks?</para>
+ </question>
+
+ <answer>
+ <para>Yes, &rel.head.releng; users can set
+ <varname>WITH_BSDCONFIG</varname> in
+ <filename>/etc/src.conf</filename>. Users of &rel.relx;
+ and higher may also install
+ <filename role="package">sysutils/bsdconfig</filename>.</para>
+ </answer>
+ </qandaentry>
</qandaset>
</chapter>
@@ -2104,13 +1661,7 @@
a particular hardware type.</para>
</answer>
</qandaentry>
- </qandaset>
- </sect1>
-
- <sect1 id="compatibility-memory">
- <title>Memory</title>
- <qandaset>
<qandaentry>
<question id="memory-upper-limitation">
<para>Does &os; support more than 4&nbsp;GB of memory (RAM)?
@@ -2200,18 +1751,18 @@
</question>
<answer>
- <para>Yes. &os; currently runs on the Intel x86 and the
- AMD64 architectures. The Intel EM64T, IA-64, &arm;,
- &powerpc;, and &sparc64; architectures are also
- supported. Upcoming platforms are &mips; and &s390;, join
- the &a.mips; for more information about ongoing work on
- the &mips; platform. For general discussion on new
- architectures, join the &a.platforms;.</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>
+ <para>Yes. &os; divides support into multiple tiers.
+ Tier 1 architectures, such as i386 or amd64; are
+ fully supported. Tiers 2 and 3 are supported on a
+ if-possible basis. A full explanation of the tier
+ system is available in the
+ <ulink
+ url="&url.articles.committers-guide;/archs.html">Committer's Guide.</ulink></para>
+
+ <para>A complete list of supported architectures can be
+ found on the
+ <ulink
+ url="http://www.FreeBSD.org/platforms/">platforms page.</ulink></para>
</answer>
</qandaentry>
@@ -2227,7 +1778,7 @@
motherboard bugs may generate some problems.</para>
<para>&os; will take advantage of HyperThreading (HTT)
- support on Intel CPUs that support this feature. A kernel
+ support on &intel; CPUs that support this feature. A kernel
with the <literal>options SMP</literal> feature enabled
will automatically detect the additional logical
processors.</para>
@@ -2235,6 +1786,25 @@
<para>&man.smp.4; has more details.</para>
</answer>
</qandaentry>
+
+ <qandaentry>
+ <question id="microcode">
+ <para>What is microcode?
+ How do I install &intel; CPU microcode updates?</para>
+ </question>
+
+ <answer>
+ <para>Microcode is a method of programmatically
+ implementating hardware level instructions. This allows
+ for CPU bugs to be fixed without replacing the on board chip.</para>
+
+ <para>Install <filename role="package">sysutils/devcpu-data</filename>,
+ then add:</para>
+ <programlisting>microcode_update_enable="YES"</programlisting>
+
+ <para>to <filename>/etc/rc.conf</filename></para>
+ </answer>
+ </qandaentry>
</qandaset>
</sect1>
@@ -2266,8 +1836,7 @@
<para>See the complete list in the Hardware Notes for &os;
<ulink url="&rel.current.hardware;">&rel.current;</ulink>
or <ulink
- url="&rel2.current.hardware;">&rel2.current;</ulink>.
- </para>
+ url="&rel2.current.hardware;">&rel2.current;</ulink>.</para>
</answer>
</qandaentry>
@@ -2328,7 +1897,7 @@
drive. See &man.burncd.8; for details.</para>
<para>&os; also supports any SCSI CD-R or CD-RW drives.
- Install and use the <command>cdrecord</command> command
+ Install and use <command>cdrecord</command>
from the ports or packages system, and make sure that you
have the <devicename>pass</devicename> device compiled in
your kernel.</para>
@@ -2342,118 +1911,6 @@
<qandaset>
<qandaentry>
- <question id="usbkbd">
- <para>Does &os; support my USB keyboard?</para>
- </question>
-
- <answer>
- <para>&os; supports USB keyboards out-of-the-box. Once you
- have USB keyboard support enabled on your system, the AT
- keyboard becomes <devicename>/dev/kbd0</devicename> and
- the USB keyboard becomes
- <devicename>/dev/kbd1</devicename>, if both are connected
- to the system. If there is the USB keyboard only, it will
- be <devicename>/dev/ukbd0</devicename>.</para>
-
- <para>If you want to use the USB keyboard in the console,
- you have to explicitly tell the console driver to use the
- existing 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 &lt; /dev/console &gt; /dev/null</userinput></screen>
-
- <para>Note that if the USB keyboard is the only keyboard, it
- is accessed as <devicename>/dev/ukbd0</devicename>, thus,
- the command should look like:</para>
-
- <screen>&prompt.root; <userinput>kbdcontrol -k /dev/ukbd0 &lt; /dev/console &gt; /dev/null</userinput></screen>
-
- <note>
- <para>To make this change permanent across reboots, add
- <literal>keyboard="/dev/ukbd0"</literal> to
- <filename>/etc/rc.conf</filename>.</para>
- </note>
-
- <para>Once this is done, the USB keyboard should work in the
- X environment as well without any special settings.</para>
-
- <para>If you want to switch back to the default keyboard,
- use this command:</para>
-
- <screen>&prompt.root; <userinput>kbdcontrol -k /dev/kbd0 &gt; /dev/null</userinput></screen>
-
- <para>To allow using both the second USB keyboard and the
- first AT keyboard at the same time on a console via
- &man.kbdmux.4; driver type the following commands:</para>
-
- <screen>&prompt.root; <userinput>kbdcontrol -K &lt; /dev/console &gt; /dev/null</userinput>
-&prompt.root; <userinput>kbdcontrol -a atkbd0 &lt; /dev/kbdmux0 &gt; /dev/null</userinput>
-&prompt.root; <userinput>kbdcontrol -a ukbd1 &lt; /dev/kbdmux0 &gt; /dev/null</userinput>
-&prompt.root; <userinput>kbdcontrol -k /dev/kbdmux0 &lt; /dev/console &gt; /dev/null</userinput></screen>
-
- <para>See the &man.ukbd.4;, &man.kbdcontrol.1; and
- &man.kbdmux.4; manual pages for more information.</para>
-
- <note>
- <para>Hot-plugging and unplugging of the USB keyboard may
- not work quite right yet. We recommend connecting the
- keyboard before starting the system and leaving it
- connected until the system is shutdown to avoid
- issues.</para>
- </note>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="busmouse">
- <para>I have an unusual bus mouse. How do I set it
- up?</para>
- </question>
-
- <answer>
- <para>&os; supports the bus mouse and the InPort bus mouse
- from such manufacturers as Microsoft, Logitech and ATI. The
- <filename>GENERIC</filename> kernel does not include the
- device driver. To build a custom kernel with the bus mouse
- driver, add the following line to the kernel config
- file:</para>
-
- <programlisting>device mse0 at isa? port 0x23c irq5</programlisting>
-
- <para>Bus mice usually come 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; manual 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>The PS/2 mouse is supported out-of-the-box. The
- necessary device driver, <devicename>psm</devicename>, is
- included in the kernel.</para>
-
- <para>If your custom kernel does not have this, add the
- following line to your kernel configuration and compile a
- new kernel.</para>
-
- <programlisting>device psm0 at atkbdc? irq 12</programlisting>
-
- <para>Once the kernel detects <devicename>psm0</devicename>
- correctly at boot time, a device node
- <devicename>psm0</devicename> will be created
- automatically.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="moused">
<para>Is it possible to use a mouse in any way outside the X
Window system?</para>
@@ -2503,10 +1960,14 @@
</question>
<answer>
- <para>Once you get the mouse daemon running (see the <link
- linkend="moused">previous section</link>), hold down the
+ <para>It is not possible to remove data using the mouse.
+ However, it is possible to <quote>copy and
+ paste</quote>.
+ Once you get the mouse daemon running (see the
+ <link linkend="moused">previous question</link>)
+ hold down
button 1 (left button) and move the mouse to select a region
- of text. Then, press the button 2 (middle button) to paste
+ of text. Then, press button 2 (middle button) to paste
it at the text cursor. Pressing button 3 (right button)
will <quote>extend</quote> the selected region of
text.</para>
@@ -2534,20 +1995,7 @@
<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="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>.</para>
+ linkend="x-and-wheel">that section</link>.</para>
</answer>
</qandaentry>
@@ -2573,29 +2021,17 @@ bind ^[[3~ ed-delete-next-char # for xterm</programlisting>
bindkey ^[[3~ delete-char # for xterm</programlisting>
<para>For more information, see <ulink
- url="http://www.ibb.net/~anne/keyboard.html">this page</ulink>.
- </para>
+ url="http://www.ibb.net/~anne/keyboard.html">this page</ulink>.</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="compatibility-networking">
- <title>Networking and Serial Devices</title>
+ <title>Networking</title>
<qandaset>
<qandaentry>
- <question id="network-cards">
- <para>Which network cards does &os; support?</para>
- </question>
-
- <answer>
- <para>See the Hardware Notes supplied with each release of
- &os; for a more complete list.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="support-broadcom">
<para>Is there a native driver for the Broadcom 43xx
cards?</para>
@@ -2606,38 +2042,6 @@ bindkey ^[[3~ delete-char # for xterm</programlisting>
&man.bwn.4; and &man.bwi.4; drivers.</para>
</answer>
</qandaentry>
-
- <qandaentry>
- <question id="multiport-serial-support">
- <para>Which multi-port serial cards are supported by
- &os;?</para>
- </question>
-
- <answer>
- <para>There is a list of these in the <ulink
- url="&url.books.handbook;/serial.html">Serial Communications</ulink>
- chapter 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 &man.sio.4; manual page to get more
- information on configuring such cards.</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>See <ulink
- url="&url.books.handbook;/serialconsole-setup.html">this section of the handbook</ulink>.
- </para>
- </answer>
- </qandaentry>
</qandaset>
</sect1>
@@ -2646,30 +2050,6 @@ bindkey ^[[3~ delete-char # for xterm</programlisting>
<qandaset>
<qandaentry>
- <question id="sound-card-support">
- <para>Which sound cards are supported by &os;?</para>
- </question>
-
- <answer>
- <para>&os; supports various sound cards (for more details,
- see <ulink
- url="&url.base;/releases/">&os; Release Information</ulink>
- and the &man.snd.4; manual page). There is also limited
- support for MPU-401 and compatible MIDI cards. Cards
- conforming to the &microsoft; Sound System specification
- are also supported.</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 CD-ROMs are supported, but
- you cannot boot off this device.</para>
- </note>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="es1370-silent-pcm">
<para>Workarounds for no sound from my &man.pcm.4; sound
card?</para>
@@ -2697,59 +2077,9 @@ bindkey ^[[3~ delete-char # for xterm</programlisting>
</question>
<answer>
- <para>&os; supports <acronym>APM</acronym> on certain
- machines. Further information can be found in
- &man.apm.4;.</para>
-
- <para>&os; also supports the <acronym>ACPI</acronym>
- features found in most modern hardware. Further
- information can be found in &man.acpi.4;. If a system
- supports both <acronym>APM</acronym> and
- <acronym>ACPI</acronym>, either can be used. We suggest
- you try both and choose the one that best fits your
- needs.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="micron-hang-boot">
- <para>Why does my Micron system hang at boot time?</para>
- </question>
-
- <answer>
- <para>Certain Micron motherboards have a non-conforming PCI
- BIOS implementation that causes grief when &os; boots
- because PCI devices do not 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.</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 into the BIOS setup and disable the <quote>boot
- virus protection</quote>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="micron-3comnic-failure">
- <para>Why does my &tm.3com; PCI network card not work with my
- Micron computer?</para>
- </question>
-
- <answer>
- <para>See <link
- linkend="micron-hang-boot">the previous answer</link>.
- </para>
+ <para>&os; supports the <acronym>ACPI</acronym>
+ features found in modern hardware. Further
+ information can be found in &man.acpi.4;.</para>
</answer>
</qandaentry>
</qandaset>
@@ -2805,142 +2135,6 @@ bindkey ^[[3~ delete-char # for xterm</programlisting>
</qandaentry>
<qandaentry>
- <question id="awre">
- <para>What do I do when 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 ship
- with this feature disabled.</para>
-
- <para>To enable bad block remapping edit the first device page
- mode, which can be done by giving the command (as
- <username>root</username>)</para>
-
- <screen>&prompt.root; <userinput>camcontrol modepage sd0 -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>Modern IDE drives also have bad block remapping features
- in the controller, and they ship with this feature turned
- on.</para>
-
- <para>If you see warnings about bad blocks (on either type of
- drive), it is time to consider replacing the drive. You
- might be able to use the drive manufacturer's diagnostic
- program to lock out those bad blocks, but at best this will
- buy you some time.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="hpnetserver-scsi-failure">
- <para>Why does &os; not detect my HP Netserver's SCSI
- controller?</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
- &gt;= 10 collides with the address space assigned to PCI,
- and &os;'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="&url.books.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 the following command at the
- prompt and install your system as usual:</para>
-
- <programlisting>eisa 12
-quit</programlisting>
-
- <para>While it is recommended you compile and install a custom
- kernel anyway.</para>
-
- <para>Hopefully, future versions will have a proper fix for
- this problem.</para>
-
- <note>
- <para>You cannot use a <literal>dangerously
- dedicated</literal> disk with an HP Netserver. See <link
- linkend="dedicate">this note</link> for more info.
- </para>
- </note>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="ed1-timeout">
- <para>I keep seeing messages like <errorname>ed1:
- timeout</errorname>. What do these messages mean?</para>
- </question>
-
- <answer>
- <para>This is usually caused by an interrupt conflict (e.g.,
- two boards using the same IRQ). Boot with the
- <option>-c</option> option and change the
- <devicename>ed0</devicename>/<devicename>de0</devicename>/...
- entry to match your board.</para>
-
- <para>If you are 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="bad-3c509">
- <para>Why did my &tm.3com; 3C509 card stop working for no
- apparent reason?</para>
- </question>
-
- <answer>
- <para>This card has a bad habit of losing its configuration
- information. Refresh your card's settings with the DOS
- utility <command>3c5x9.exe</command>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="printer-slow">
- <para>My parallel printer is ridiculously slow. What can I
- do?</para>
- </question>
-
- <answer>
- <para>If the only problem is that the printer is terribly
- slow, try changing your <ulink
- url="&url.books.handbook;/printing-intro-setup.html#PRINTING-PARALLEL-PORT-MODE">printer port mode</ulink>
- as discussed in the <ulink
- url="&url.books.handbook;/printing-intro-setup.html">Printer Setup</ulink>
- section of the Handbook.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="signal11">
<para>Why do my programs occasionally die with
<errorname>Signal 11</errorname> errors?</para>
@@ -2990,7 +2184,7 @@ quit</programlisting>
<para>What you should do:</para>
- <para>In the first case you can use a debugger e.g.
+ <para>In the first case you can use a debugger e.g.,
&man.gdb.1; to find the point in the program which is
attempting to access a bogus address and then fix it.</para>
@@ -3012,8 +2206,8 @@ quit</programlisting>
on the processor might have died. In either case you
need to ensure that you have hardware running at what it
is specified to run at, at least while trying to solve
- this problem. i.e. Clock it back to the default
- settings.</para>
+ this problem (in other words, clock it back to the default
+ settings.)</para>
<para>If you are overclocking then note that it is far
cheaper to have a slow system than a fried system that
@@ -3064,8 +2258,7 @@ quit</programlisting>
instructions to send a problem report.</para>
<para>There is an extensive FAQ on this at <ulink
- url="http://www.bitwizard.nl/sig11/">the SIG11 problem FAQ</ulink>.
- </para>
+ url="http://www.bitwizard.nl/sig11/">the SIG11 problem FAQ</ulink>.</para>
</answer>
</qandaentry>
@@ -3090,88 +2283,6 @@ quit</programlisting>
</qandaentry>
<qandaentry>
- <question id="screen-loses-sync">
- <para>Why does the screen go black and lose sync when I
- boot?</para>
- </question>
-
- <answer>
- <para>This is a known problem with the ATI&nbsp;Mach64 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 &man.sio.4; driver it will
- touch this port even if you do not have the fourth serial
- port, and <emphasis>even</emphasis> if you disable
- <devicename>sio3</devicename> (the fourth port) which
- normally uses this address.</para>
-
- <para>Until the bug has been fixed, you can use this
- workaround:</para>
-
- <orderedlist>
- <listitem>
- <para>Enter <option>-c</option> at the boot prompt.
- (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 &man.sio.4; driver does not get activated &mdash; no
- problems.</para>
- </listitem>
-
- <listitem>
- <para>Type exit to continue booting.</para>
- </listitem>
- </orderedlist>
-
- <para>If you want to be able to use your serial ports, you
- will have to build a new kernel with the following
- modification: in
- <filename>/usr/src/sys/dev/sio/sio.c</filename> (or in
- <filename>/usr/src/sys/pc98/cbus/sio.c</filename> for pc98)
- 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>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="reallybigram">
- <para>Why does &os; only use 64&nbsp;MB of RAM when my system
- has 128&nbsp;MB of RAM installed?</para>
- </question>
-
- <answer>
- <para>Due to the manner in which &os; gets the memory size
- from the BIOS, it can only detect 16&nbsp;bits worth of
- Kbytes in size (65535&nbsp;Kbytes = 64&nbsp;MB) (or less...
- some BIOSes peg the memory size to 16&nbsp;MB). If you have
- more than 64&nbsp;MB, &os; 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 do not have room in
- the bootblocks to do it. Someday when lack of room in the
- bootblocks is fixed, we will use the extended BIOS functions
- to get the full memory information... but for now we are
- stuck with the kernel option.</para>
-
- <programlisting>options MAXMEM=<replaceable>n</replaceable></programlisting>
-
- <para>Where <replaceable>n</replaceable> is your memory in
- Kilobytes. For a 128&nbsp;MB machine, you would want to use
- <literal>131072</literal>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="kmem-map-too-small">
<para>My system has more than 1&nbsp;GB of RAM, and I'm
getting panics with <errorname>kmem_map too small</errorname>
@@ -3180,7 +2291,7 @@ quit</programlisting>
<answer>
<para>Normally, &os; determines a number of kernel parameters,
- such as as the maximum number of files that can be open
+ such as the maximum number of files that can be open
concurrently, from the amount of memory installed in the
system. On systems with one gigabyte of RAM or more, this
<quote>auto sizing</quote> mechanism may choose values that
@@ -3212,15 +2323,16 @@ quit</programlisting>
memory for network buffers (specifically, mbuf clusters).
You can increase the amount of VM available for mbuf
clusters by following the instructions in the <ulink
- url="&url.books.handbook;/configtuning-kernel-limits.html#NMBCLUSTERS">Network Limits</ulink>
+ url="&url.books.handbook;/configtuning-kernel-limits.html#nmbclusters">Network Limits</ulink>
section of the Handbook.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="proc-table-full">
- <para>Why do I get the error <errorname>kernel: proc: table is
- full</errorname>?</para>
+ <para>Why do I get the error <errorname>maxproc limit
+ exceeded by uid %i, please see tuning(7) and
+ login.conf(5)</errorname>?</para>
</question>
<answer>
@@ -3237,7 +2349,7 @@ quit</programlisting>
<para>To adjust your <varname>kern.maxusers</varname> value,
see the <ulink
- url="&url.books.handbook;/configtuning-kernel-limits.html#KERN-MAXFILES">File/Process Limits</ulink>
+ url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">File/Process Limits</ulink>
section of the Handbook. (While that section refers to open
files, the same limits apply to processes.)</para>
@@ -3247,77 +2359,13 @@ quit</programlisting>
this tunable needs adjustment it needs to be defined in
<filename>/boot/loader.conf</filename>. The tunable will
not get adjusted until the system is rebooted. For more
- information about tuning tunables, you should see the
- &man.loader.conf.5; and &man.sysctl.conf.5; manual pages.
+ information about tuning tunables, see
+ &man.loader.conf.5;.
If these processes are being run by a single user, you will
also need to adjust <varname>kern.maxprocperuid</varname> to
be one less than your new <varname>kern.maxproc</varname>
value. (It must be at least one less because one system
program, &man.init.8;, must always be running.)</para>
-
- <para>To make a sysctl change permanent place the proper value
- in <filename>/etc/sysctl.conf</filename>. More information
- about system tuning with &man.sysctl.8; can be found at the
- <ulink
- url="&url.books.handbook;/configtuning-sysctl.html">Tuning with sysctl</ulink>
- section of the Handbook.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="cmap-busy-panic">
- <para>Why do I get an error reading <errorname>CMAP
- busy</errorname> 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>What does the message <errorname>ahc0: brkadrint,
- Illegal Host Access at seqaddr 0x0</errorname> mean?</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 <devicename>uha0</devicename>, which is
- causing the problem.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="aci0-illegal-cable">
- <para>When I boot my system, I get the error <errorname>ahc0:
- illegal cable configuration</errorname>. My cabling is
- correct. What is going on?</para>
- </question>
-
- <answer>
- <para>Your motherboard lacks the external logic to support
- automatic termination. Switch your SCSI BIOS to specify the
- correct termination for your configuration rather than
- automatic termination. The &man.ahc.4; driver cannot
- determine if the external logic for cable detection (and
- thus auto-termination) is available. The driver simply
- assumes that this support must exist if the configuration
- contained in the serial EEPROM is set to <quote>automatic
- termination</quote>. Without the external cable detection
- logic the driver will often configure termination
- incorrectly, which can compromise the reliability of the
- SCSI bus.</para>
</answer>
</qandaentry>
@@ -3331,8 +2379,7 @@ quit</programlisting>
<answer>
<para>You can find a detailed answer for this question in the
<ulink
- url="&url.books.handbook;/mail-trouble.html#Q26.5.2.">Handbook</ulink>.
- </para>
+ url="&url.books.handbook;/mail-trouble.html#q26.5.2.">Handbook</ulink>.</para>
</answer>
</qandaentry>
@@ -3392,174 +2439,6 @@ quit</programlisting>
</qandaentry>
<qandaentry>
- <question id="pnp-not-found">
- <para>Why is my PnP card not found (or found as
- <literal>unknown</literal>)?</para>
- </question>
-
- <answer>
- <para>The reasons for this behavior are explained by the
- following email, posted to the &a.questions; by &a.peter;, in
- answer to a question about an internal modem that was no
- longer found after an upgrade to
- &os;&nbsp;4.<replaceable>X</replaceable> (the comments in
- <literal>[]</literal> have been added to clarify the
- context).</para>
-
- <note>
- <para>The contents of this quotation has been updated from
- its original text.</para>
- </note>
-
- <blockquote>
- <para>The PNP bios preconfigured it [the modem] and left it
- laying around in port space, so [in
- 3.<replaceable>X</replaceable>] 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.<replaceable>X</replaceable>] 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 IDs 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 &amp; 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 <literal>Vendor
- ID</literal> line at the start of the output. The
- hexadecimal number in parentheses
- (<literal>0x3024a341</literal> in this example) is the PnP
- ID and the string immediately before this
- (<literal>PMC2430</literal>) is a unique ASCII ID.</para>
-
- <para>Alternatively, if &man.pnpinfo.8; does not list the card
- in question, &man.pciconf.8; can be used instead. This is
- part of the output from <command>pciconf -vl</command> for
- an onboard sound chip:</para>
-
- <screen>&prompt.root; <userinput>pciconf -vl</userinput>
-chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02 hdr=0x00
- vendor = 'Intel Corporation'
- device = '82801AA 8xx Chipset AC'97 Audio Controller'
- class = multimedia
- subclass = audio</screen>
-
- <para>Here, you would use the <varname>chip</varname> value,
- <literal>0x24158086</literal>.</para>
-
- <para>This information (<literal>Vendor ID</literal> or
- <varname>chip</varname> value) needs adding to the file
- <filename>/usr/src/sys/dev/sio/sio_isa.c</filename>.</para>
-
- <para>You should first make a backup of
- <filename>sio_isa.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, are you not?) then edit
- <filename>sio_isa.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
- <devicename>sio</devicename> device.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="nlist-failed">
- <para>Why do I get the error <errorname>nlist
- failed</errorname> when running, for example,
- <command>top</command> or <command>systat</command>?</para>
- </question>
-
- <answer>
- <para>The problem is that the application you are trying to
- run is looking for a specific kernel symbol, but, for whatever
- reason, cannot find it; this error stems from one of two
- problems:</para>
-
- <itemizedlist>
- <listitem>
- <para>Your kernel and userland are not synchronized (i.e.,
- you built a new kernel but did not do an
- <maketarget>installworld</maketarget>, or vice versa),
- and thus the symbol table is different from what the
- user application thinks it is. If this is the case,
- simply complete the upgrade process (see
- <filename>/usr/src/UPDATING</filename> for the correct
- sequence).</para>
- </listitem>
-
- <listitem>
- <para>You are not using <command>/boot/loader</command> to
- load your kernel, but doing it directly from
- <filename>boot2</filename> (see &man.boot.8;). While
- there is nothing wrong with bypassing
- <command>/boot/loader</command>, it generally does a
- better job of making the kernel symbols available to
- user applications.</para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="connection-delay">
<para>Why does it take so long to connect to my computer via
<command>ssh</command> or <command>telnet</command>?</para>
@@ -3576,7 +2455,7 @@ chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02
address into a hostname. Many servers, including the
<application>Telnet</application> and
<application>SSH</application> servers that come with &os;,
- do this in order to, among other things, store the hostname
+ do this to store the hostname
in a log file for future reference by the
administrator.</para>
@@ -3608,9 +2487,9 @@ chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02
<filename>/etc/resolv.conf</filename>. This will often
cause a delay in <application>SSH</application>, as the
option <literal>UseDNS</literal> is set to
- <literal>yes</literal> by default in the
- <filename>sshd_config</filename> file in
- <filename class="directory">/etc/ssh</filename>. If this is causing the
+ <literal>yes</literal> by default in
+ <filename>/etc/ssh/sshd_config</filename>.
+ If this is causing the
problem, you will either need to fill in the missing
information in <filename>/etc/resolv.conf</filename> or set
<literal>UseDNS</literal> to <literal>no</literal> in
@@ -3620,46 +2499,6 @@ chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02
</qandaentry>
<qandaentry>
- <question id="stray-irq">
- <para>What does <errorname>stray IRQ</errorname> mean?</para>
- </question>
-
- <answer>
- <para>Stray IRQs are indications of hardware IRQ glitches,
- mostly from hardware that removes its interrupt request in
- the middle of the interrupt request acknowledge
- cycle.</para>
-
- <para>One has three options for dealing with this:</para>
-
- <itemizedlist>
- <listitem>
- <para>Live with the warnings. All except the first 5 per
- irq are suppressed anyway.</para>
- </listitem>
-
- <listitem>
- <para>Break the warnings by changing the value of
- <varname>MAX_STRAY_LOG</varname> from
- <literal>5</literal> to <literal>0</literal> in your
- platform's (e.g. &i386;)
- <filename>intr_machdep.c</filename> file and rebuild the
- new kernel and all the warnings will be
- suppressed.</para>
- </listitem>
-
- <listitem>
- <para>Break the warnings by installing parallel port
- hardware that uses IRQ&nbsp;7 and the PPP driver for it
- (this happens on most systems), and install an ide drive
- or other hardware that uses IRQ&nbsp;15 and a suitable
- driver for it.</para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="file-table-full">
<para>Why does <errorname>file: table is full</errorname> show
up repeatedly in &man.dmesg.8;?</para>
@@ -3669,7 +2508,7 @@ chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02
<para>This error message indicates you have exhausted the
number of available file descriptors on your system. Please
see the <ulink
- url="&url.books.handbook;/configtuning-kernel-limits.html#KERN-MAXFILES">kern.maxfiles</ulink>
+ url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">kern.maxfiles</ulink>
section of the <ulink
url="&url.books.handbook;/configtuning-kernel-limits.html">Tuning Kernel Limits</ulink>
section of the Handbook for a discussion and
@@ -3678,37 +2517,6 @@ chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02
</qandaentry>
<qandaentry>
- <question id="calcru-negative-runtime">
- <para>Why are <errorname>calcru: negative runtime</errorname>
- or <errorname>calcru: runtime went backwards</errorname>
- messages pounding the console?</para>
- </question>
-
- <answer>
- <para>There is a known problem when enabling &intel; Enhanced
- SpeedStep from the BIOS: it causes the kernel to start printing
- <errorname>calcru</errorname> messages like this:</para>
-
- <screen>calcru: runtime went backwards from 6 usec to 3 usec for pid 37 (pagezero)
-calcru: runtime went backwards from 6 usec to 3 usec for pid 36 (vmdaemon)
-calcru: runtime went backwards from 170 usec to 138 usec for pid 35 (pagedaemon)
-calcru: runtime went backwards from 553 usec to 291 usec for pid 15 (swi6: task queue)
-calcru: runtime went backwards from 15521 usec to 10366 usec for pid 2 (g_event)
-calcru: runtime went backwards from 25 usec to 12 usec for pid 11 (swi1: net)
-calcru: runtime went backwards from 4417 usec to 3960 usec for pid 1 (init)
-calcru: runtime went backwards from 2084385 usec to 1793542 usec for pid 1 (init)
-calcru: runtime went backwards from 408 usec to 204 usec for pid 0 (swapper)</screen>
-
- <para>It is because &intel; SpeedStep (EIST) is incompatible
- with some motherboards.</para>
-
- <para>Workaround: Disable the EIST feature in the BIOS. You
- can still achieve ACPI-based processor frequency throttling
- by using &man.powerd.8;.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="computer-clock-skew">
<para>Why does the clock on my computer keep incorrect time?</para>
</question>
@@ -3750,7 +2558,7 @@ kern.timecounter.hardware: ACPI-fast</screen>
<varname>kern.timecounter.hardware</varname>
&man.sysctl.3;.</para>
- <screen>&prompt.root; <userinput>sysctl -w kern.timecounter.hardware=i8254</userinput>
+ <screen>&prompt.root; <userinput>sysctl kern.timecounter.hardware=i8254</userinput>
kern.timecounter.hardware: TSC -&gt; i8254</screen>
<para>Your computer should now start keeping more accurate
@@ -3765,80 +2573,6 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaentry>
<qandaentry>
- <question id="null-null">
- <para>Why did my laptop fail to correctly probe PC
- cards?</para>
- </question>
-
- <answer>
- <para>This problem is common on laptops that boot more than
- one operating system. Some non-BSD operating systems leave
- PC card hardware in an inconsistent state. &man.pccardd.8;
- will detect the card as
- <errorname>"(null)""(null)"</errorname> instead of its
- actual model.</para>
-
- <para>You must remove all power from the PC card slot to fully
- reset the hardware. Completely power off the laptop. (Do
- not suspend it, do not let it go into standby; the power
- needs to be completely off.) Wait a few moments, and reboot.
- Your PC card should work now.</para>
-
- <para>Some laptop hardware lies when it claims to be off. If
- the above does not work shut down, remove the battery, wait
- a moment, replace the battery, and reboot.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="boot-read-error">
- <para>Why does &os;'s boot loader display <errorname>Read
- error</errorname> and stop after the BIOS screen?</para>
- </question>
-
- <answer>
- <para>&os;'s boot loader is incorrectly recognizing the hard
- drive's geometry. This must be manually set within
- &man.fdisk.8; when creating or modifying &os;'s
- slice.</para>
-
- <para>The correct drive geometry values can be found within
- the machine's BIOS. Look for the number of cylinders, heads
- and sectors for the particular drive.</para>
-
- <para>Within &man.sysinstall.8;'s fdisk, hit
- <keycap>G</keycap> to set the drive geometry.</para>
-
- <para>A dialog will pop up requesting the number of cylinders,
- heads and sectors. Type the numbers found from the BIOS
- separated by forward slashes. For example, values of 5000
- cylinders, 250 heads, and 60 sectors would be entered as
- <userinput>5000/250/60</userinput>.</para>
-
- <para>Press <keycap>Enter</keycap> to set the values, and hit
- <keycap>W</keycap> to write the new partition table to the
- drive.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="bootmanager-restore">
- <para>Another operating system destroyed my Boot Manager. How
- do I get it back?</para>
- </question>
-
- <answer>
- <para>Enter &man.sysinstall.8; and choose
- <guimenuitem>Configure</guimenuitem>, then
- <guimenuitem>Fdisk</guimenuitem>. Select the disk the Boot
- Manager resided on with the <keycap>Space</keycap> key.
- Press <keycap>W</keycap> to write changes to the drive. A
- prompt will appear asking which boot loader to install.
- Select this, and it will be restored.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="indefinite-wait-buffer">
<para>What does the error <errorname>swap_pager: indefinite
wait buffer:</errorname> mean?</para>
@@ -3858,41 +2592,6 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaentry>
<qandaentry>
- <question id="udma-icrc">
- <para>What are <errorname>UDMA ICRC</errorname> errors, and
- how do I fix them?</para>
- </question>
-
- <answer>
- <para>The &man.ata.4; driver reports <errorname>UDMA
- ICRC</errorname> errors when a DMA transfer to or from a drive
- is corrupted. The driver will retry the operation a few
- times. Should the retries fail, it will switch from DMA to
- the slower PIO mode of communication with the device.</para>
-
- <para>The problem can be caused by many factors, although
- perhaps the most common cause is faulty or incorrect
- cabling. Check that the ATA cables are undamaged and rated
- for the Ultra&nbsp;DMA mode in use. If you are using
- removable drive trays, they must also be compatible. Be
- sure that all connections are making good contact. Problems
- have also been noticed when an old drive is installed on the
- same ATA channel as an Ultra&nbsp;DMA&nbsp;66 (or faster)
- drive. Lastly, these errors can indicate that the drive is
- failing. Most drive vendors provide testing software for
- their drives, so test your drive, and, if necessary, back up
- your data and replace it.</para>
-
- <para>The &man.atacontrol.8; utility can be used to show and
- select the DMA or PIO modes used for each ATA device. In
- particular, <command>atacontrol mode
- <replaceable>channel</replaceable></command> will show the
- modes in use on a particular ATA channel, where the primary
- channel is numbered 0, and so on.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
<question id="lock-order-reversal">
<para>What is a <errorname>lock order
reversal</errorname>?</para>
@@ -3901,8 +2600,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<answer>
<para>An answer for this question can be found in the &os;
Glossary, see <ulink
- url="&url.books.handbook;/freebsd-glossary.html#LOR-GLOSSARY">LOR</ulink>.
- </para>
+ url="&url.books.handbook;/freebsd-glossary.html#lor-glossary">LOR</ulink>.</para>
</answer>
</qandaentry>
@@ -3936,6 +2634,9 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
unfortunate timing they could cause undesirable effects
ranging from a minor blip in the system's responsiveness to
a complete system lockup.</para>
+
+ <para>For additional information about locking in &os; see
+ &man.locking.9;.</para>
</answer>
</qandaentry>
@@ -3959,195 +2660,6 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaset>
</chapter>
- <chapter id="commercial">
- <title>Commercial Applications</title>
-
- <note>
- <para>This section is still very sparse, though we are hoping, of
- course, that companies will add to it! :) The &os; 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 &os; can have very positive effects on &os;'s
- long-term viability). We encourage commercial software vendors
- to send their entries here for inclusion. See <ulink
- url="&url.base;/commercial/index.html">the Vendors page</ulink>
- for a longer list.</para>
- </note>
-
- <qandaset>
- <qandaentry>
- <question id="officesuite">
- <para>Where can I get an Office Suite for &os;?</para>
- </question>
-
- <answer>
- <para>The open-source <application><ulink
- url="http://www.openoffice.org">OpenOffice.org</ulink></application>
- and <application><ulink
- url="http://www.libreoffice.org">LibreOffice</ulink></application>
- office suites work natively on &os;. The &linux; version of
- <application><ulink
- url="http://www.oracle.com/us/products/applications/open-office/index.html">Oracle Open Office</ulink></application>,
- the value-added closed-source version of OpenOffice.org,
- also works on &os;.</para>
-
- <para>&os; also includes a variety of text editors,
- spreadsheets, and drawing programs in the Ports
- Collection.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="motif">
- <para>Where can I get <application>&motif;</application> for
- &os;?</para>
- </question>
-
- <answer>
- <para>The Open Group has released the source code to
- <application>&motif;</application>. You can
- install the <filename
- role="package">x11-toolkits/open-motif</filename> package,
- or compile it from ports. Refer to <ulink
- url="&url.books.handbook;/ports.html">the ports section of the Handbook</ulink>
- for more information on how to do this.</para>
-
- <note>
- <para>The <application>Open&nbsp;&motif;</application>
- distribution only allows redistribution if it is running
- on an <ulink
- url="http://www.opensource.org/">open source</ulink>
- operating system.</para>
- </note>
-
- <para>In addition, there are commercial distributions of the
- <application>&motif;</application> software available. These,
- however, are not for free, but their license allows them to
- be used in closed-source software. Contact <link
- linkend="apps2go">Apps2go</link> for the least expensive ELF
- <application>&motif;&nbsp;2.1.20</application> distribution
- for &os; (&i386;).<anchor id="apps2go"/></para>
-
- <para>There are two distributions, the <quote>development
- edition</quote> and the <quote>runtime edition</quote> (for
- much less). These distributions includes:</para>
-
- <itemizedlist>
- <listitem>
- <para><application>OSF/&motif; manager</application>,
- <application>xmbind</application>,
- <application>panner</application>,
- <application>wsm</application>.</para>
- </listitem>
-
- <listitem>
- <para>Development kit with uil, mrm, xm, xmcxx, include
- and <application>Imake</application> files.</para>
- </listitem>
-
- <listitem>
- <para>Static and dynamic ELF libraries.</para>
- </listitem>
-
- <listitem>
- <para>Demonstration applets.</para>
- </listitem>
- </itemizedlist>
-
- <para>Be sure to specify that you want the &os; version of
- <application>&motif;</application> when ordering (do not
- 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>
-
- <variablelist>
- <varlistentry>
- <term>More info</term>
-
- <listitem>
- <para><ulink url="http://www.apps2go.com/"> Apps2go
- WWW page</ulink></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>or</term>
-
- <listitem>
- <para><email>sales@apps2go.com</email> or
- <email>support@apps2go.com</email></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>or</term>
-
- <listitem>
- <para>phone (817)&nbsp;431&nbsp;8775 or
- +1&nbsp;817&nbsp;431-8775</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="cde">
- <para>Where can I get <application>CDE</application> for
- &os;?</para>
- </question>
-
- <answer>
- <para><emphasis>Xi Graphics</emphasis> used to sell
- <application>CDE</application> for &os;, but no longer
- do.</para>
-
- <para><ulink
- url="http://www.kde.org/"><application>KDE</application></ulink>
- is an open source X11 desktop which is similar to
- <application>CDE</application> in many respects. You might
- also like the look and feel of <ulink
- url="http://www.xfce.org/"><application>xfce</application></ulink>.
- <application>KDE</application> and
- <application>xfce</application> are both in the <ulink
- url="&url.base;/ports/index.html">ports system</ulink>.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="database-systems">
- <para>Are there any Database systems for &os;?</para>
- </question>
-
- <answer>
- <para>Yes! See the <ulink
- url="&url.base;/commercial/software_bycat.html#CATEGORY_DATABASE">Commercial Vendors</ulink>
- section of &os;'s Web site.</para>
-
- <para>Also see the <ulink
- url="&url.base;/ports/databases.html">Databases</ulink>
- section of the Ports Collection.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="oracle-support">
- <para>Can I run <application>&oracle;</application> on
- &os;?</para>
- </question>
-
- <answer>
- <para>Yes. Instructions on how to set up &linux;
- <application>&oracle;</application> on &os; can be found
- under <ulink
- url="http://www.shadowcom.net/freebsd-oracle9i/">http://www.shadowcom.net/freebsd-oracle9i/</ulink>.</para>
- </answer>
- </qandaentry>
- </qandaset>
- </chapter>
-
<chapter id="applications">
<title>User Applications</title>
@@ -4179,10 +2691,8 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
can be installed and uninstalled again easily without having
to know the gory details of which files it includes.</para>
- <para>Use the <guimenuitem>Packages</guimenuitem> package
- installation menu in &man.sysinstall.8; (under the
- <guimenuitem>Configure</guimenuitem> menu item) or invoke
- the &man.pkg.add.1; command on the specific package files
+ <para>Use
+ &man.pkg.add.1; on the specific package files
you are interested in installing. Package files can usually
be identified by their <filename>.tbz</filename> suffix and
CD-ROM distribution people will have a
@@ -4197,8 +2707,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<listitem>
<para><ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;</ulink>
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;</ulink></para>
</listitem>
</varlistentry>
@@ -4207,8 +2716,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<listitem>
<para><ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;</ulink>
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;</ulink></para>
</listitem>
</varlistentry>
@@ -4217,8 +2725,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<listitem>
<para><ulink
- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;</ulink>
- </para>
+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;</ulink></para>
</listitem>
</varlistentry>
</variablelist>
@@ -4235,17 +2742,31 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaentry>
<qandaentry>
- <question id="configure-inn">
- <para>How do I configure INN (Internet News) for my
- machine?</para>
+ <question id="how-do-download-ports-tree">
+ <para>How do I download the Ports tree? Should I be using
+ SVN?</para>
</question>
<answer>
- <para>After installing the <filename
- role="package">news/inn</filename> package or port, an
- excellent place to start are the <ulink
- url="http://www.eyrie.org/~eagle/faqs/inn.html">INN
- FAQ</ulink>.</para>
+ <para>Any of the methods listed here work:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use portsnap for most use cases.</para>
+ </listitem>
+ <listitem>
+ <para>Use SVN directly if you need custom patches
+ to the ports tree.</para>
+ </listitem>
+ <listitem>
+ <para>Use CTM if you prefer getting patches
+ by email (this is a rarer use case).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Any other method should be considered a
+ legacy method. If you do not already use them,
+ do not start.</para>
</answer>
</qandaentry>
@@ -4256,8 +2777,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<answer>
<para>Yes. Please see <ulink
- url="&url.base;/java/index.html">http://www.FreeBSD.org/java/</ulink>.
- </para>
+ url="&url.base;/java/index.html">http://www.FreeBSD.org/java/</ulink>.</para>
</answer>
</qandaentry>
@@ -4294,38 +2814,12 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</question>
<answer>
- <para>First, always make sure that you have a completely
+ <para>First, always make sure that you have a complete
up-to-date Ports Collection. Errors that affect building
<filename>INDEX</filename> from an up-to-date copy of the
Ports Collection are high-visibility and are thus almost
always fixed immediately.</para>
- <para>However, if you are up-to-date, perhaps you are seeing
- another problem. <command>make <maketarget>index</maketarget></command>
- has a known bug in dealing with incomplete copies of the
- Ports Collection. It assumes that you have a local copy of
- every single port that every other port that you have a
- local copy of depends on. To explain, if you have a copy of
- <filename>foo/bar</filename> on your disk, and
- <filename>foo/bar</filename> depends on
- <filename>baz/quux</filename>, then you must also have a
- copy of <filename>baz/quux</filename> on your disk, and the
- ports <filename>baz/quux</filename> depends on, and so on.
- Otherwise, <command>make <maketarget>index</maketarget></command>
- has insufficient information to create its dependency
- tree.</para>
-
- <para>This is particularly a problem for &os; users who
- utilize &man.csup.1; to track the Ports
- Collection but choose not to install certain categories by
- specifying them in <filename>refuse</filename>. In theory,
- one should be able to refuse categories, but in practice
- there are too many ports that depend on ports in other
- categories. Until someone comes up with a solution for this
- problem, the general rule is that if you want to build
- <filename>INDEX</filename>, you must have a complete copy of
- the Ports Collection.</para>
-
<para>There are rare cases where <filename>INDEX</filename>
will not build due to odd cases involving
<makevar>WITH_<replaceable>*</replaceable></makevar> or
@@ -4373,7 +2867,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
fail to function properly.</para>
<para>For more information, see <ulink
- url="&url.books.handbook;/updating-upgrading-freebsdupdate.html#FREEBSDUPDATE-UPGRADE">the section on upgrades</ulink>
+ url="&url.books.handbook;/updating-upgrading-freebsdupdate.html#freebsdupdate-upgrade">the section on upgrades</ulink>
in the &os; Handbook.</para>
</answer>
</qandaentry>
@@ -4395,36 +2889,35 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<qandaentry>
<question id="minimal-sh">
- <para>Why is <command>/bin/sh</command> so minimal? Why does
- &os; not use <command>bash</command> or another
+ <para>Why is <command>/bin/sh</command> so minimal? Why
+ does &os; not 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 is 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>Many people need to write shell scripts which will be
+ portable across many systems. That is why &posix;
+ specifies the shell and utility commands in great detail.
+ Most scripts are written in Bourne shell (&man.sh.1;), 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 is why the Ports Collection
- includes more featureful shells like
+ can. To keep <command>/bin/sh</command> small,
+ we have not provided many of the convenience features that
+ other shells have. That is why other more
+ featureful shells like
<command>bash</command>, <command>scsh</command>,
- <command>tcsh</command>, and <command>zsh</command>. (You
- can compare for yourself the memory utilization of all these
+ &man.tcsh.1;, and <command>zsh</command> are available.
+ (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
<option>-u</option></command> listing.)</para>
@@ -4432,63 +2925,79 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaentry>
<qandaentry>
- <question id="netscape-slow-startup">
- <para>Why do <application>&netscape;</application> and
- <application>Opera</application> take so long to start?</para>
+ <question id="midi-sound-files">
+ <para>How do I create audio CDs from my MIDI files?</para>
</question>
<answer>
- <para>The usual answer is that DNS on your system is
- misconfigured. Both <application>&netscape;</application>
- and <application>Opera</application> perform DNS checks when
- starting up. The browser will not appear on your desktop
- until the program either gets a response or determines that
- the system has no network connection.</para>
+ <para>To create audio CDs from MIDI files, first install
+ <filename role="package">audio/timidity++</filename> from
+ ports then install manually the GUS patches set by Eric A.
+ Welsh, available at <ulink
+ url="http://alleg.sourceforge.net/digmid.html"></ulink>.
+ After <application>TiMidity++</application> has been installed
+ properly, MIDI files may be converted to WAV files with the
+ following command line:</para>
+
+ <screen>&prompt.user; <userinput>timidity -Ow -s 44100 -o <replaceable>/tmp/juke/01.wav</replaceable> <replaceable>01.mid</replaceable></userinput></screen>
+
+ <para>The WAV files can then be converted to other formats or
+ burned onto audio CDs, as described in the <ulink
+ url="&url.books.handbook;/creating-cds.html">&os; Handbook</ulink>.</para>
</answer>
</qandaentry>
<qandaentry>
- <question id="ports-base-update">
- <para>I updated parts of the Ports Collection using
- <application>CVSup</application>, and now many ports fail to
- build with mysterious error messages! What happened? Is
- the Ports Collection broken in some major way?</para>
+ <question id="officesuite">
+ <para>Where can I get an Office Suite for &os;?</para>
</question>
<answer>
- <para>If you only update parts of the Ports Collection, using
- one of its <application>CVSup</application> subcollections
- and not the <literal>ports-all</literal>
- <application>CVSup</application> collection, you should
- <emphasis>always</emphasis> update the
- <literal>ports-base</literal> subcollection too! The
- reasons are described <ulink
- url="&url.books.handbook;/cvsup.html#CVSUP-COLLEC-PBASE-WARN">in the Handbook</ulink>.
- </para>
+ <para>The open-source <application><ulink
+ url="http://www.openoffice.org">Apache OpenOffice</ulink></application>
+ and <application><ulink
+ url="http://www.libreoffice.org">LibreOffice</ulink></application>
+ office suites work natively on &os;.</para>
+
+ <para>&os; also includes a variety of text editors,
+ spreadsheets, and drawing programs in the Ports
+ Collection.</para>
</answer>
</qandaentry>
<qandaentry>
- <question id="midi-sound-files">
- <para>How do I create audio CDs from my MIDI files?</para>
+ <question id="database-systems">
+ <para>Are there any Database systems for &os;?</para>
</question>
<answer>
- <para>To create audio CDs from MIDI files, first install
- <filename role="package">audio/timidity++</filename> from
- ports then install manually the GUS patches set by Eric A.
- Welsh, available at <ulink
- url="http://alleg.sourceforge.net/digmid.html"></ulink>.
- After <application>TiMidity++</application> has been installed
- properly, MIDI files may be converted to WAV files with the
- following command line:</para>
+ <para>Yes! See the <ulink
+ url="&url.base;/commercial/software_bycat.html#category_database">Commercial Vendors</ulink>
+ section of &os;'s Web site.</para>
- <screen>&prompt.user; <userinput>timidity -Ow -s 44100 -o <replaceable>/tmp/juke/01.wav</replaceable> <replaceable>01.mid</replaceable></userinput></screen>
+ <para>Also see the <ulink
+ url="&url.base;/ports/databases.html">Databases</ulink>
+ section of the Ports Collection.</para>
+ </answer>
+ </qandaentry>
- <para>The WAV files can then be converted to other formats or
- burned onto audio CDs, as described in the <ulink
- url="&url.books.handbook;/creating-cds.html">&os; Handbook</ulink>.
- </para>
+ <qandaentry>
+ <question id="convert-back-from-pkgng">
+ <para>How can I convert from pkgng to the old package
+ tools?</para>
+ </question>
+
+ <answer>
+ <para>Short answer: it is not possible.</para>
+
+ <para>Longer answer: if you have made any changes using
+ <command>pkg</command> converting back is non-trivial and
+ requires lots of manual editing of internal package
+ database files. However, if you have just run
+ <command>pkg2ng</command> then you may remove
+ <filename>/var/db/pkg/local.sqlite</filename>
+ and extract
+ <filename>/var/backups/pkgdb.bak.tbz</filename>.</para>
</answer>
</qandaentry>
</qandaset>
@@ -4506,8 +3015,7 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<answer>
<para>Not at all! Check out the <ulink
- url="&url.books.handbook;/kernelconfig.html">kernel config section of the Handbook</ulink>.
- </para>
+ url="&url.books.handbook;/kernelconfig.html">kernel config section of the Handbook</ulink>.</para>
<note>
<para>The new <filename>kernel</filename> will be installed
@@ -4522,45 +3030,35 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
</qandaentry>
<qandaentry>
- <question id="missing-hw-float">
- <para>My kernel compiles fail because
- <literal>_hw_float</literal> is missing. How do I solve
- this problem?</para>
+ <question id="why-kernel-big">
+ <para>Why is my kernel so big?</para>
</question>
<answer>
- <para>You probably removed <devicename>npx0</devicename> (see
- &man.npx.4;) from your kernel configuration file because you
- do not have a math co-processor. The
- <devicename>npx0</devicename> device is
- <emphasis>MANDATORY</emphasis>. Somewhere inside your
- hardware lies a device that provides hardware floating-point
- support, even if it is no longer a separate device as used
- in the good old 386 days. You <emphasis>must</emphasis>
- include the <devicename>npx0</devicename> device. Even if
- you manage to build a kernel without
- <devicename>npx0</devicename> support, it will not boot
- anyway.</para>
- </answer>
- </qandaentry>
+ <para><literal>GENERIC</literal> kernels shipped with &os;
+ and later are compiled in <emphasis>debug mode</emphasis>.
+ Kernels built in debug mode
+ contain many symbols in separate files that are used for
+ debugging, thus greatly increasing the size of
+ <filename class="directory">/boot/kernel/</filename>.
+ Note that there will be little or no performance loss
+ from running a debug kernel, and it is useful to keep one
+ around in case of a system panic.</para>
- <qandaentry>
- <question id="why-kernel-big">
- <para>Why is my kernel so big (over 10&nbsp;MB)?</para>
- </question>
+ <para>However, if you are running low on disk space, there
+ are different options to reduce the size of <filename
+ class="directory">/boot/kernel/</filename>.</para>
- <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 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>If you do not want the symbol files to be installed,
+ make sure you have the following line present in
+ <filename>/etc/src.conf</filename>:</para>
- <para>However, if you are running low on disk space, or you
- simply do not want to run a debug kernel, make sure that
- both of the following are true:</para>
+ <programlisting>WITHOUT_KERNEL_SYMBOLS=yes</programlisting>
+
+ <para>For more information see &man.src.conf.5;.</para>
+
+ <para>If you do not want to build a debug kernel, make
+ sure that both of the following are true:</para>
<itemizedlist>
<listitem>
@@ -4578,36 +3076,31 @@ kern.timecounter.hardware: TSC -&gt; i8254</screen>
<para>Either of the above settings 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.5&nbsp;MB to 2&nbsp;MB.</para>
- </answer>
- </qandaentry>
+ the steps above, you can build your kernel normally.</para>
- <qandaentry>
- <question id="multiport-serial-interrupts">
- <para>Why do I get interrupt conflicts with multi-port serial
- code?</para>
- </question>
+ <para>If you want only the modules you use to be built
+ and installed, make sure you have a line like below in
+ <filename>/etc/make.conf</filename>:</para>
- <answer>
- <para>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>
+ <programlisting>MODULES_OVERRIDE= <replaceable>accf_http ipfw</replaceable></programlisting>
+
+ <para>Replace <emphasis>accf_httpd ipfw</emphasis> with
+ a list of modules you need. Only these modules will be
+ built. This does not only reduce the size of the kernel
+ directory but also decreases the amount of time needed to
+ build your kernel. For more information see
+ <filename>/usr/share/examples/etc/make.conf</filename>.</para>
- <para>The problem here is that &os; 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 an example:</para>
+ <para>You can also remove unneeded devices from your kernel
+ to further reduce the size. See
+ <xref linkend="make-kernel"/> for more information.</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>
+ <para>To put any of these options into effect you will have
+ to <ulink url="&url.books.handbook;/kernelconfig-building.html">build and install</ulink>
+ your new kernel.</para>
+
+ <para>Most kernels (<filename>/boot/kernel/kernel</filename>)
+ tend to be around 12&nbsp;MB to 16&nbsp;MB.</para>
</answer>
</qandaentry>
@@ -4630,8 +3123,8 @@ device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr</programlisting>
used to build the currently running system (e.g., you
are compiling &rel.current;-RELEASE on a
&rel2.current;-RELEASE system). If you are attempting
- an upgrade, please read the
- <filename>/usr/src/UPDATING</filename> file, paying
+ an upgrade, please read
+ <filename>/usr/src/UPDATING</filename>, paying
particular attention to the <quote>COMMON ITEMS</quote>
section at the end.</para>
</listitem>
@@ -4673,27 +3166,12 @@ device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr</programlisting>
</question>
<answer>
- <para>Check for the existence of the
- <varname>kern.sched.quantum</varname> sysctl. If you have
- it, you should see something like this:</para>
-
- <screen>&prompt.user; sysctl <replaceable>kern.sched.quantum</replaceable>
-kern.sched.quantum: 99960</screen>
-
- <para>If the <varname>kern.sched.quantum</varname> sysctl
- exists, you are using the 4BSD scheduler (&man.sched.4bsd.4;).
- If not, you will get an error printed by &man.sysctl.8;
- (which you can safely ignore):</para>
-
- <screen>&prompt.user; sysctl <replaceable>kern.sched.quantum</replaceable>
-sysctl: unknown oid 'kern.sched.quantum'</screen>
-
<para>The name of the scheduler currently being used is
directly available as the value of the
<varname>kern.sched.name</varname> sysctl:</para>
<screen>&prompt.user; sysctl <replaceable>kern.sched.name</replaceable>
-kern.sched.name: 4BSD</screen>
+kern.sched.name: ULE</screen>
</answer>
</qandaentry>
@@ -4704,10 +3182,8 @@ kern.sched.name: 4BSD</screen>
<answer>
<para><varname>kern.sched.quantum</varname> is the maximum
- number of ticks a process can run without being preempted. It
- is specific to the 4BSD scheduler, so you can use its
- presence or absence to determine which scheduler is in
- use.</para>
+ number of ticks a process can run without being preempted
+ in the 4BSD scheduler.</para>
</answer>
</qandaentry>
</qandaset>
@@ -4745,10 +3221,9 @@ kern.sched.name: 4BSD</screen>
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
- &man.sysinstall.8;, or &man.fdisk.8; and &man.disklabel.8;.
- You should also install booteasy on both disks with
+ <para>Alternatively, partition and label the new disk with either
+ &man.sade.8; or &man.gpart.8;. If the disks are MBR-formatted,
+ you can 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.</para>
@@ -4790,12 +3265,12 @@ kern.sched.name: 4BSD</screen>
</procedure>
<para>For example, if you are going to move root to
- <devicename>/dev/<replaceable>ad1s1a</replaceable></devicename>,
+ <devicename>/dev/<replaceable>ada1s1a</replaceable></devicename>,
with <filename class="directory"><replaceable>/mnt</replaceable></filename> as
the temporary mount point, it is:</para>
- <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ad1s1a</replaceable></userinput>
-&prompt.root; <userinput>mount /dev/<replaceable>ad1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
+ <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>dump 0af - / | restore rf -</userinput></screen>
@@ -4806,8 +3281,8 @@ kern.sched.name: 4BSD</screen>
as described above, then move the child partition into the
empty directory that the first move created:</para>
- <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ad1s1a</replaceable></userinput>
-&prompt.root; <userinput>mount /dev/<replaceable>ad1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
+ <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>dump 0af - / | restore rf -</userinput>
&prompt.root; <userinput>cd var</userinput>
@@ -4819,11 +3294,11 @@ kern.sched.name: 4BSD</screen>
partition on the appropriate directory in the temporary
mount point, then move the old single partition:</para>
- <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ad1s1a</replaceable></userinput>
-&prompt.root; <userinput>newfs /dev/<replaceable>ad1s1d</replaceable></userinput>
-&prompt.root; <userinput>mount /dev/<replaceable>ad1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
+ <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
+&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1d</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>mkdir <replaceable>/mnt</replaceable>/var</userinput>
-&prompt.root; <userinput>mount /dev/<replaceable>ad1s1d</replaceable> <replaceable>/mnt</replaceable>/var</userinput>
+&prompt.root; <userinput>mount /dev/<replaceable>ada1s1d</replaceable> <replaceable>/mnt</replaceable>/var</userinput>
&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
&prompt.root; <userinput>dump 0af - / | restore rf -</userinput></screen>
@@ -4835,134 +3310,28 @@ kern.sched.name: 4BSD</screen>
</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 hard
- disk(s). The default way makes it compatible with other
- operating systems on the same machine, by using
- &man.fdisk.8; table entries (called <quote>slices</quote> in
- &os;), with a &os; 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 &os;, 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 does not contain what normal PC utilities would
- consider a valid &man.fdisk.8; 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
- BIOSes, including those from AWARD (e.g. 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 is not a complete list, there are more.
- Symptoms of this confusion include the <errorname>read
- error</errorname> message printed by the &os; bootstrap when
- it cannot 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 &os; installers &mdash; 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 &os; 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 will not 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 is meant to be used as a
- last-ditch alternative &mdash; 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 are 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. Do not panic &mdash; 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
- &os; lists your disks, first IDE, then SCSI.</para>
-
- <para>When you are slicing up your disk, check that the disk
- geometry displayed in the FDISK screen is correct (ie. it
- matches the BIOS numbers); if it is wrong, use the
- <keycap>G</keycap> key to fix it. You may have to do this
- if there is 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 are going to boot from; &os;
- will sort itself out just fine with any other disks you may
- have.</para>
-
- <para>Once you have got the BIOS and &os; 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
- <errorname>read error</errorname> message when you try to
- boot, it is time to cross your fingers and go for it &mdash; there
- is 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 the following
- command:</para>
-
- <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/<replaceable>rda0</replaceable> count=15</userinput></screen>
-
- <para>Alternatively, the undocumented DOS
- <quote>feature</quote></para>
-
- <screen><prompt>C:\&gt;</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="safe-softupdates">
<para>Which partitions can safely use Soft Updates? I have
heard that Soft Updates on <filename class="directory">/</filename> can cause
- problems.</para>
+ problems. What about Journaled Soft Updates?</para>
</question>
<answer>
<para>Short answer: you can usually use Soft Updates safely on
all partitions.</para>
- <para>Long answer: There used to be some concern over using
- Soft Updates on the root partition. Soft Updates has two
- characteristics that caused this. First, a Soft Updates
+ <para>Long answer: Soft Updates has two
+ characteristics that may be undesirable on certain
+ paritions. First, a Soft Updates
partition has a small chance of losing data during a system
crash. (The partition will not be corrupted; the data will
- simply be lost.) Also, Soft Updates can cause temporary
+ simply be lost.) Second, Soft Updates can cause temporary
space shortages.</para>
<para>When using Soft Updates, the kernel can take up to
- thirty seconds to actually write changes to the physical
- disk. If you delete a large file, the file still resides on
+ thirty seconds to write changes to the physical
+ disk. When a large file is deleted the file still
+ resides on
disk until the kernel actually performs the deletion. This
can cause a very simple race condition. Suppose you delete
one large file and immediately create another large file.
@@ -4978,20 +3347,14 @@ kern.sched.name: 4BSD</screen>
<para>If a system should crash after the kernel accepts a
chunk of data for writing to disk, but before that data is
- actually written out, data could be lost or corrupted. This
- risk is extremely small, but generally manageable. Use of
- IDE write caching greatly increases this risk; it is
- strongly recommended that you disable IDE write caching when
- using Soft Updates.</para>
+ actually written out, data could be lost. This
+ risk is extremely small, but generally manageable.</para>
<para>These issues affect all partitions using Soft Updates.
So, what does this mean for the root partition?</para>
<para>Vital information on the root partition changes very
- rarely. Files such as
- <filename>/boot/kernel/kernel</filename> and the contents of
- <filename class="directory">/etc</filename> only change during system
- maintenance, or when users change their passwords. If the
+ rarely. If the
system crashed during the thirty-second window after such a
change is made, it is possible that data could be lost.
This risk is negligible for most applications, but you
@@ -5007,6 +3370,10 @@ kern.sched.name: 4BSD</screen>
problems. Symlinking <filename class="directory">/tmp</filename> to
<filename class="directory">/var/tmp</filename> will solve this
problem.</para>
+
+ <para>Finally, &man.dump.8; does not work in live mode (-L)
+ on a filesystem, with Journaled Soft Updates
+ (<acronym>SU+J</acronym>).</para>
</answer>
</qandaentry>
@@ -5095,11 +3462,10 @@ use "disklabel -r" to install initial label</screen>
<term>NTFS</term>
<listitem>
- <para>&os; includes a read-only NTFS driver. For more
- information, see &man.mount.ntfs.8;. A port of <ulink
- url="http://www.tuxera.com/community/"><application>ntfs-3g</application></ulink>
- supports write operations on NTFS (see <filename
- role="package">sysutils/fusefs-ntfs</filename>).</para>
+ <para>FUSE based NTFS support is available as a port
+ (<filename role="package">sysutils/fusefs-ntfs</filename>).
+ For more information see <ulink
+ url="http://www.tuxera.com/community/ntfs-3g-manual/"><application>ntfs-3g</application></ulink>.</para>
</listitem>
</varlistentry>
@@ -5175,7 +3541,7 @@ use "disklabel -r" to install initial label</screen>
DOS/&windowsnt; 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
+ then edit <filename>c:\boot.ini</filename> to come
up with something like this:</para>
<programlisting>[boot loader]
@@ -5280,12 +3646,11 @@ C:\="DOS"</programlisting>
following to your configuration file
<filename>/boot/grub/menu.lst</filename> (or
<filename>/boot/grub/grub.conf</filename> in some systems,
- e.g. Red Hat Linux and its derivatives).</para>
+ e.g., Red Hat Linux and its derivatives).</para>
<programlisting>title &os; 6.1
root <replaceable>(hd0,a)</replaceable>
- kernel /boot/loader
- </programlisting>
+ kernel /boot/loader</programlisting>
<para>Where <replaceable>hd0,a</replaceable> points to your
root partition on the first disk. If you need to specify
@@ -5335,69 +3700,38 @@ C:\="DOS"</programlisting>
</question>
<answer>
- <para>Whether it is a removable drive like a &iomegazip; or an
- EZ drive (or even a floppy, if you want to use it that way),
- or a new hard disk, once it is 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>(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 the drive already has a
+ file system on it, you can use a command like this:</para>
- <para>If it is a ZIP drive or a floppy, you have already got a
- DOS file system on it, you can use a command like this:</para>
+ <screen>&prompt.root; <userinput>mount -t msdosfs /dev/da0s1 /mnt</userinput></screen>
- <screen>&prompt.root; <userinput>mount -t msdosfs /dev/fd0c /floppy</userinput></screen>
+ <para>If the drive will only be used with &os;
+ systems it is better idea to
+ stick a BSD file system on it, like UFS or ZFS.
+ You will get long filename
+ support, at least a 2X improvement in performance,
+ and a lot more stability. If the drive will be
+ used by other operating systems a more portable
+ choice, such as msdosfs, is better.</para>
- <para>if it is a floppy, or this:</para>
+ <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da0 count=2</userinput>
+&prompt.root; <userinput>gpart create -s GPT /dev/da0</userinput>
+&prompt.root; <userinput>gpart add -t freebsd-ufs /dev/da0</userinput></screen>
- <screen>&prompt.root; <userinput>mount -t msdosfs /dev/da2s4 /zip</userinput></screen>
+ <para>Finally, create a new file system:</para>
- <para>for a ZIP disk with the factory configuration.</para>
-
- <para>For other disks, see how they are laid out using
- &man.fdisk.8; or &man.sysinstall.8;.</para>
-
- <para>The rest of the examples will be for a ZIP drive on
- <devicename>da2</devicename>, the third SCSI disk.</para>
-
- <para>Unless it is a floppy, or a removable you plan on
- sharing with other people, it is probably a better idea to
- stick a BSD file system on it. You will 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/file systems. You can either use &man.fdisk.8;
- or &man.sysinstall.8;, or for a small drive that you do not
- 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 &man.disklabel.8; or &man.sysinstall.8; to
- create multiple BSD partitions. You will certainly want to
- do this if you are adding swap space on a fixed disk, but it
- is probably irrelevant on a removable drive like a
- ZIP.</para>
-
- <para>Finally, create a new file system, this one is on our
- ZIP drive using the whole disk:</para>
-
- <screen>&prompt.root; <userinput>newfs /dev/rda2c</userinput></screen>
+ <screen>&prompt.root; <userinput>newfs /dev/da0p1</userinput></screen>
<para>and mount it:</para>
- <screen>&prompt.root; <userinput>mount /dev/da2c /zip</userinput></screen>
+ <screen>&prompt.root; <userinput>mount /dev/da0s1 /mnt</userinput></screen>
- <para>and it is probably a good idea to add a line like this
+ <para>It is a good idea to add a line
to <filename>/etc/fstab</filename> (see &man.fstab.5;) so
- you can just type <command>mount /zip</command> in the
+ you can just type <command>mount /mnt</command> in the
future:</para>
- <programlisting>/dev/da2c /zip ffs rw,noauto 0 0</programlisting>
+ <programlisting>/dev/da0p1 /mnt ufs rw,noauto 0 0</programlisting>
</answer>
</qandaentry>
@@ -5412,8 +3746,7 @@ C:\="DOS"</programlisting>
that you want to mount. This is described in the <ulink
url="&url.books.handbook;/creating-cds.html"> Handbook section on optical media</ulink>,
specifically the section <ulink
- url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CDs</ulink>.
- </para>
+ url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink>.</para>
</answer>
</qandaentry>
@@ -5427,7 +3760,7 @@ C:\="DOS"</programlisting>
<para>This generally means that there is no CD-ROM in the
CD-ROM drive, or the drive is not visible on the bus.
Please see the <ulink
- url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CDs</ulink>
+ url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink>
section of the Handbook for a detailed discussion of this
issue.</para>
</answer>
@@ -5446,8 +3779,7 @@ C:\="DOS"</programlisting>
<ulink
url="&url.books.handbook;/creating-cds.html">creating and using CD-ROMs</ulink>,
specifically the section on <ulink
- url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CD-ROMs</ulink>.
- </para>
+ url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CD-ROMs</ulink>.</para>
</answer>
</qandaentry>
@@ -5463,8 +3795,7 @@ C:\="DOS"</programlisting>
the <ulink
url="&url.books.handbook;/creating-cds.html">Handbook chapter on creating CD-ROMs</ulink>,
particularly the section on <ulink
- url="&url.books.handbook;/creating-cds.html#RAWDATA-CD">burning raw data CDs</ulink>.