os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

- Definitively upgrade to DocBook 5.0

Browse source
This commit is contained in:
Gabor Kovesdan 2013-11-07 15:39:28 +00:00
parent 35f1d6c78b
commit 24d129e8d1
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/projects/db5/; revision=43125
958 changed files with 96265 additions and 123971 deletions
Download patch file Download diff file Expand all files Collapse all files

64
en_US.ISO8859-1/articles/bsdl-gpl/article.xml
View file

@ -1,24 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<title>Why you should use a BSD style license for your Open Source Project</title>
<articleinfo>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Why you should use a BSD style license for your Open Source Project</title>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<!-- middle initial: R. -->
<surname>Montague</surname>
<affiliation>
<author><personname><firstname>Bruce</firstname><surname>Montague</surname></personname><affiliation>
<address><email>brucem@alumni.cse.ucsc.edu</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.general;
@ -27,9 +21,9 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>This document makes a case for using a BSD style license for
@ -38,13 +32,13 @@
GPL Open Source License introduction and summary.</para>
</sect1>
<sect1 id="history">
<sect1 xml:id="history">
<title>Very Brief Open Source History</title>
<para>Long before the term <quote>Open Source</quote> was used, software was
developed by loose associations of programmers and freely
exchanged. Starting in the early 1950's, organizations such as
<ulink url="http://www.share.org">SHARE</ulink> and <ulink url="http://www.decus.org">DECUS</ulink> developed much of the
<link xlink:href="http://www.share.org">SHARE</link> and <link xlink:href="http://www.decus.org">DECUS</link> developed much of the
software that computer hardware companies bundled with their
hardware offerings. At that time computer companies were in the
hardware business; anything that reduced software cost and made
@ -74,7 +68,7 @@
the customer.</para>
</sect1>
<sect1 id="unix-license">
<sect1 xml:id="unix-license">
<title>Unix from a BSD Licensing Perspective</title>
<para>AT&amp;T, who owned the original Unix implementation, was a
@ -129,11 +123,11 @@
soon terminated its support for BSD.</para>
</sect1>
<sect1 id="current-bsdl">
<sect1 xml:id="current-bsdl">
<title>The Current State of FreeBSD and BSD Licenses</title>
<para>The so-called <ulink url="http://www.opensource.org/licenses/bsd-license.php"> new BSD
license</ulink> applied to FreeBSD within the last few years is
<para>The so-called <link xlink:href="http://www.opensource.org/licenses/bsd-license.php"> new BSD
license</link> applied to FreeBSD within the last few years is
effectively a statement that you can do anything with the program
or its source, but you do not have any warranty and none of the
authors has any liability (basically, you cannot sue anybody). This
@ -148,7 +142,7 @@
</sect1>
<sect1 id="origins-gpl">
<sect1 xml:id="origins-gpl">
<title>The origins of the GPL</title>
<para>While the future of Unix had been so muddled in the late 1980s
@ -164,8 +158,8 @@
disagreement over access to the source code for this software).
Stallman devised an alternative to the commercial software license
and called it the GPL, or "GNU Public License". He also started a
non-profit foundation, the <ulink url="http://www.fsf.org">Free
Software Foundation</ulink> (FSF), which intended to develop an entire
non-profit foundation, the <link xlink:href="http://www.fsf.org">Free
Software Foundation</link> (FSF), which intended to develop an entire
operating system, including all associated software, that would
not be subject to proprietary licensing. This system was called
GNU, for "GNU is Not Unix".</para>
@ -183,7 +177,7 @@
incorporating your program into proprietary
programs.</quote>[1]</para>
<para>The <ulink url="http://www.opensource.org/licenses/gpl-license.php">GPL</ulink>
<para>The <link xlink:href="http://www.opensource.org/licenses/gpl-license.php">GPL</link>
is a complex license so here are some rules of thumb when using
the GPL:</para>
@ -226,7 +220,7 @@
</sect1>
<sect1 id="origins-lgpl">
<sect1 xml:id="origins-lgpl">
<title>The origins of Linux and the LGPL</title>
<para>While the commercial Unix wars raged, the Linux kernel was
@ -241,7 +235,7 @@
of the GPL. Pressure to put proprietary applications on Linux
became overwhelming. Such applications often must link with system
libraries. This resulted in a modified version of the GPL called
the <ulink url="http://www.opensource.org/licenses/lgpl-license.php">LGPL</ulink>
the <link xlink:href="http://www.opensource.org/licenses/lgpl-license.php">LGPL</link>
("Library", since renamed to "Lesser", GPL). The LGPL allows
proprietary code to be linked to the GNU C library, glibc. You do
not have to release the source to code which has been dynamically
@ -255,7 +249,7 @@
</sect1>
<sect1 id="orphaning">
<sect1 xml:id="orphaning">
<title>Open Source licenses and the Orphaning Problem</title>
<para>One of the serious problems associated with proprietary
@ -283,7 +277,7 @@
</sect1>
<sect1 id="license-cannot">
<sect1 xml:id="license-cannot">
<title>What a license cannot do</title>
<para>No license can guarantee future software
@ -315,7 +309,7 @@
</sect1>
<sect1 id="gpl-advantages">
<sect1 xml:id="gpl-advantages">
<title>GPL Advantages and Disadvantages</title>
<para>A common reason to use the GPL is when modifying or extending
@ -377,7 +371,7 @@
</sect1>
<sect1 id="bsd-advantages">
<sect1 xml:id="bsd-advantages">
<title>BSD Advantages</title>
<para>A BSD style license is a good choice for long duration
@ -446,7 +440,7 @@
</sect1>
<sect1 id="recommendations">
<sect1 xml:id="recommendations">
<title>Specific Recommendations for using a BSD license</title>
<itemizedlist>
@ -531,7 +525,7 @@
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<para>In contrast to the GPL, which is designed to prevent the
@ -549,7 +543,7 @@
</sect1>
<sect1 id="addenda">
<sect1 xml:id="addenda">
<title>Addenda</title>
<programlisting>

281
en_US.ISO8859-1/articles/building-products/article.xml
View file

@ -1,22 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Building Products with FreeBSD</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Building Products with FreeBSD</title>
<authorgroup>
<author>
<firstname>Joseph</firstname>
<surname>Koshy</surname>
<affiliation>
<author><personname><firstname>Joseph</firstname><surname>Koshy</surname></personname><affiliation>
<orgname>The FreeBSD Project</orgname>
<address><email>jkoshy@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -44,9 +39,9 @@
few <quote>best practices</quote> for organizations
collaborating with the FreeBSD project.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>FreeBSD today is well-known as a high-performance server
@ -58,8 +53,7 @@
commercial shrink-wrapped software (see
<xref linkend="freebsd-intro"/>).</para>
<para>In this article we look at the <ulink
url="&url.base;/">FreeBSD project</ulink> as a software
<para>In this article we look at the <link xlink:href="&url.base;/">FreeBSD project</link> as a software
engineering resource&mdash;as a collection of building blocks
and processes which you can use to build products.</para>
@ -166,7 +160,7 @@
</sect2>
</sect1>
<sect1 id="freebsd-intro">
<sect1 xml:id="freebsd-intro">
<title>FreeBSD as a set of building blocks</title>
<para>FreeBSD makes an excellent foundation on which to build
@ -254,9 +248,7 @@
<listitem>
<simpara>As a development environment supporting
cross-development for embedded OSes like <ulink
url="http://www.rtems.com/">RTEMS</ulink> and <ulink
url="http://ecos.sourceware.org/">eCOS</ulink>.</simpara>
cross-development for embedded OSes like <link xlink:href="http://www.rtems.com/">RTEMS</link> and <link xlink:href="http://ecos.sourceware.org/">eCOS</link>.</simpara>
<simpara>There are many full-fledged development environments
in the &os.numports;-strong collection of applications ported and
packaged with FreeBSD.</simpara>
@ -280,7 +272,7 @@
</itemizedlist>
</sect2>
<sect2 id="freebsd-technologies">
<sect2 xml:id="freebsd-technologies">
<title>Technologies</title>
<para>There are a large number of technologies supported by the
@ -403,9 +395,8 @@
<para>FreeBSD does not have <quote>corporate</quote> committers.
Individual committers are required to take responsibility for
the changes they introduce to the code. The <ulink
url="&url.articles.committers-guide;">FreeBSD Committer's
guide</ulink> <citation>ComGuide</citation> documents the
the changes they introduce to the code. The <link xlink:href="&url.articles.committers-guide;">FreeBSD Committer's
guide</link> <citation>ComGuide</citation> documents the
rules and responsibilities for committers.</para>
<para>FreeBSD's project model is examined in detail in
@ -441,7 +432,7 @@
</listitem>
</itemizedlist>
<figure id="fig-freebsd-branches">
<figure xml:id="fig-freebsd-branches">
<title>FreeBSD Release Branches</title>
<mediaobject>
<imageobject>
@ -459,13 +450,11 @@
engineering and security teams, <firstterm>Tier 2</firstterm>
architectures are supported on a best effort basis, and
experimental architectures comprise <firstterm>Tier
3</firstterm>. The list of <ulink
url="&url.articles.committers-guide;/archs.html">supported
architectures</ulink> is part of the FreeBSD documentation
3</firstterm>. The list of <link xlink:href="&url.articles.committers-guide;/archs.html">supported
architectures</link> is part of the FreeBSD documentation
collection.</para>
<para>The release engineering team publishes a <ulink
url="&url.base;/releng/">road map</ulink> for future
<para>The release engineering team publishes a <link xlink:href="&url.base;/releng/">road map</link> for future
releases of FreeBSD on the project's web site. The dates laid
down in the road map are not deadlines; FreeBSD is released
when its code and documentation are ready.</para>
@ -476,7 +465,7 @@
</sect2>
</sect1>
<sect1 id="freebsd-collaboration">
<sect1 xml:id="freebsd-collaboration">
<title>Collaborating with FreeBSD</title>
<para>Open-source projects like FreeBSD offer finished code of a
@ -520,16 +509,15 @@
<listitem>
<simpara>FreeBSD enjoys an open and transparent working
culture. Nearly all discussion in the project happens by
email, on <ulink url="&a.mailman.listinfo;">public mailing
lists</ulink> that are also archived for posterity. The
project's policies are <ulink
url="&url.base;/internal/policies.html">documented</ulink>
email, on <link xlink:href="&a.mailman.listinfo;">public mailing
lists</link> that are also archived for posterity. The
project's policies are <link xlink:href="&url.base;/internal/policies.html">documented</link>
and maintained under revision control. Participation in the
project is open to all.</simpara>
</listitem>
</itemizedlist>
<sect2 id="freebsd-org">
<sect2 xml:id="freebsd-org">
<title>Understanding FreeBSD culture</title>
<para>To be able to work effectively with the FreeBSD project,
@ -559,12 +547,10 @@
<para>FreeBSD traces its roots back nearly twenty years to the
work of the Computer Science Research Group at the
University of California Berkeley.<footnote>
<simpara>FreeBSD's <ulink
url="http://cvsweb.freebsd.org/">source
repository</ulink> contains a history of the project
since its inception, and there are <ulink
url="http://www.mckusick.com/csrg/">CDROMs
available</ulink> that contain earlier code from the
<simpara>FreeBSD's <link xlink:href="http://cvsweb.freebsd.org/">source
repository</link> contains a history of the project
since its inception, and there are <link xlink:href="http://www.mckusick.com/csrg/">CDROMs
available</link> that contain earlier code from the
CSRG.</simpara>
</footnote> A number of the original CSRG developers remain
associated with the project.</para>
@ -592,7 +578,7 @@
consensus and running code</quote>
<citation>Carp1996</citation>.</para>
<figure id="fig-change-log">
<figure xml:id="fig-change-log">
<title>A sample change log entry</title>
<programlisting>
bde 2005-10-29 16:34:50 UTC
@ -647,9 +633,8 @@ bde 2005-10-29 16:34:50 UTC
<formalpara>
<title>Track FreeBSD source code</title>
<para>The project makes it easy to mirror its CVS
repository using <ulink
url="&url.articles.cvsup-advanced;"><!--
--><application>CVSup</application></ulink>. Having
repository using <link xlink:href="&url.articles.cvsup-advanced;"><!--
--><application>CVSup</application></link>. Having
the complete history of the source is useful when
debugging complex problems and offers valuable insight
into the intentions of the original developers. Use a
@ -662,10 +647,9 @@ bde 2005-10-29 16:34:50 UTC
change log in <xref linkend="fig-change-log"/>. The
ancestry of each line of the source is clearly visible.
Annotated listings showing the history of every file
that is part of FreeBSD are <ulink
url="http://cvsweb.freebsd.org/">available on the
web</ulink>.</para>
<figure id="fig-cvs-annotate">
that is part of FreeBSD are <link xlink:href="http://cvsweb.freebsd.org/">available on the
web</link>.</para>
<figure xml:id="fig-cvs-annotate">
<title>An annotated source listing generated using <command>cvs annotate</command></title>
<programlisting>
<![CDATA[
@ -709,8 +693,8 @@ bde 2005-10-29 16:34:50 UTC
<formalpara>
<title>Report bugs upstream</title>
<para>If you notice bug in the FreeBSD code that you are
using, file a <ulink url="&url.base;/send-pr.html">bug
report</ulink>. This step helps ensure that you do
using, file a <link xlink:href="&url.base;/send-pr.html">bug
report</link>. This step helps ensure that you do
not have to fix the bug the next time you take a code
drop from upstream.</para>
</formalpara>
@ -750,18 +734,15 @@ bde 2005-10-29 16:34:50 UTC
agreement with a developer or firm with FreeBSD
experience. The &a.jobs; is a useful communication
channel to find talent. The FreeBSD project maintains a
<ulink
url="&url.base;/commercial/consult_bycat.html">gallery
of consultants and consulting firms</ulink>
undertaking FreeBSD work. The <ulink
url="http://www.bsdcertification.org/">BSD
Certification Group</ulink> offers certification for
<link xlink:href="&url.base;/commercial/consult_bycat.html">gallery
of consultants and consulting firms</link>
undertaking FreeBSD work. The <link xlink:href="http://www.bsdcertification.org/">BSD
Certification Group</link> offers certification for
all the major BSD derived OSes.</simpara>
<simpara>For less critical needs, you can ask for help on
the <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">project
mailing lists</ulink>. A useful guide to follow when
the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">project
mailing lists</link>. A useful guide to follow when
asking for help is given in
<citation>Ray2004</citation>.
</simpara>
@ -791,15 +772,12 @@ bde 2005-10-29 16:34:50 UTC
already looking at a related problem. Help can range
from hardware donations to direct financial assistance.
In some countries, donations to the FreeBSD project
enjoy tax benefits. The project has a dedicated <ulink
url="&url.base;/donations/">donations liaison</ulink>
enjoy tax benefits. The project has a dedicated <link xlink:href="&url.base;/donations/">donations liaison</link>
to assist donors. The project also maintains a web page
where developers <ulink
url="&url.base;/donations/wantlist.html">list their
needs</ulink>.
where developers <link xlink:href="&url.base;/donations/wantlist.html">list their
needs</link>.
</simpara>
<simpara>As a policy the FreeBSD project <ulink
url="&url.articles.contributors;">acknowledges</ulink>
<simpara>As a policy the FreeBSD project <link xlink:href="&url.articles.contributors;">acknowledges</link>
all contributions received on its web site.</simpara>
</listitem>
</varlistentry>
@ -807,7 +785,7 @@ bde 2005-10-29 16:34:50 UTC
</sect2>
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<para>The FreeBSD project's goals are to create and give away the
source code for a high-quality operating system. By working
@ -826,36 +804,25 @@ bde 2005-10-29 16:34:50 UTC
<bibliography>
<biblioentry>
<abbrev>Carp1996</abbrev>
<citetitle><ulink url="http://www.ietf.org/rfc/rfc1958.txt">The
Architectural Principles of the Internet</ulink></citetitle>
<author>
<firstname>B.</firstname>
<surname>Carpenter</surname>
<affiliation>
<citetitle><link xlink:href="http://www.ietf.org/rfc/rfc1958.txt">The
Architectural Principles of the Internet</link></citetitle>
<author><personname><firstname>B.</firstname><surname>Carpenter</surname></personname><affiliation>
<orgname>The Internet Architecture Board</orgname>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>1996</year>
</copyright>
</biblioentry>
<biblioentry xreflabel="Com2004">
<abbrev>Com2004</abbrev>
<citetitle><ulink
url="http://csdl.computer.org/comp/mags/so/2004/01/s1028.pdf">How
<citetitle><link xlink:href="http://csdl.computer.org/comp/mags/so/2004/01/s1028.pdf">How
is Open-Source Affecting Software
Development?</ulink></citetitle>
Development?</link></citetitle>
<authorgroup>
<author>
<firstname>Diomidis</firstname>
<surname>Spinellis</surname>
</author>
<author>
<firstname>Clemens</firstname>
<surname>Szyperski</surname>
</author>
<author><personname><firstname>Diomidis</firstname><surname>Spinellis</surname></personname></author>
<author><personname><firstname>Clemens</firstname><surname>Szyperski</surname></personname></author>
</authorgroup>
<title>IEEE Computer</title>
<citetitle>IEEE Computer</citetitle>
<copyright>
<year>Jan/Feb 2004</year>
</copyright>
@ -865,11 +832,10 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>ComGuide</abbrev>
<citetitle><ulink
url="&url.articles.committers-guide;">Committer's
Guide</ulink></citetitle>
<citetitle><link xlink:href="&url.articles.committers-guide;">Committer's
Guide</link></citetitle>
<authorgroup>
<corpauthor>The FreeBSD Project</corpauthor>
<author><orgname>The FreeBSD Project</orgname></author>
</authorgroup>
<copyright>
<year>2005</year>
@ -877,34 +843,26 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>Cov2005</abbrev>
<citetitle><ulink
url="http://www.coverity.com/news/nf_news_06_27_05_story_9.html">Coverity
study on kernel security holes in Linux and FreeBSD</ulink></citetitle>
<citetitle><link xlink:href="http://www.coverity.com/news/nf_news_06_27_05_story_9.html">Coverity
study on kernel security holes in Linux and FreeBSD</link></citetitle>
<authorgroup>
<corpauthor>Coverity Inc.</corpauthor>
<author><orgname>Coverity Inc.</orgname></author>
</authorgroup>
<copyright>
<year>2005</year>
</copyright>
</biblioentry>
<biblioentry>
<abbrev>GoldGab2005</abbrev> <citetitle><ulink
url="http://dreamsongs.com/IHE/IHE.html">Innovation Happens
Elsewhere: Open Source as Business Strategy</ulink></citetitle>
<abbrev>GoldGab2005</abbrev> <citetitle><link xlink:href="http://dreamsongs.com/IHE/IHE.html">Innovation Happens
Elsewhere: Open Source as Business Strategy</link></citetitle>
<authorgroup>
<author>
<firstname>Ron</firstname>
<surname>Goldman</surname>
</author>
<author>
<firstname>Richard</firstname>
<surname>Gabriel</surname>
</author>
<author><personname><firstname>Ron</firstname><surname>Goldman</surname></personname></author>
<author><personname><firstname>Richard</firstname><surname>Gabriel</surname></personname></author>
</authorgroup>
<copyright>
<year>2005</year>
</copyright>
<isbn>ISBN 1558608893</isbn>
<biblioid class="isbn">ISBN 1558608893</biblioid>
<publisher>
<publishername>Morgan-Kaufmann</publishername>
</publisher>
@ -912,12 +870,9 @@ bde 2005-10-29 16:34:50 UTC
<biblioentry xreflabel="Hub1994">
<!-- XXX Get the date of this article right -->
<abbrev>Hub1994</abbrev>
<citetitle><ulink url="&url.articles.contributing;">Contributing
to the FreeBSD Project</ulink></citetitle>
<author>
<firstname>Jordan</firstname>
<surname>Hubbard</surname>
</author>
<citetitle><link xlink:href="&url.articles.contributing;">Contributing
to the FreeBSD Project</link></citetitle>
<author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname></author>
<copyright>
<year>1994&mdash;2005</year>
</copyright>
@ -927,19 +882,12 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>McKu1999</abbrev>
<citetitle><ulink
url="http://www.usenix.org/publications/library/proceedings/usenix99/mckusick.html">Soft
<citetitle><link xlink:href="http://www.usenix.org/publications/library/proceedings/usenix99/mckusick.html">Soft
Updates: A Technique for Eliminating Most Synchronous Writes
in the Fast Filesystem</ulink></citetitle>
in the Fast Filesystem</link></citetitle>
<authorgroup>
<author>
<firstname>Kirk</firstname>
<surname>McKusick</surname>
</author>
<author>
<firstname>Gregory</firstname>
<surname>Ganger</surname>
</author>
<author><personname><firstname>Kirk</firstname><surname>McKusick</surname></personname></author>
<author><personname><firstname>Gregory</firstname><surname>Ganger</surname></personname></author>
</authorgroup>
<confgroup>
<conftitle>USENIX Annual Technical Conference</conftitle>
@ -950,21 +898,15 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>McKu1999-1</abbrev>
<citetitle><ulink
url="http://www.oreilly.com/catalog/opensources/book/kirkmck.html"
>Twenty Years of Berkeley Unix: From AT&amp;T-Owned to
Freely Redistributable</ulink></citetitle>
<citetitle><link xlink:href="http://www.oreilly.com/catalog/opensources/book/kirkmck.html">Twenty Years of Berkeley Unix: From AT&amp;T-Owned to
Freely Redistributable</link></citetitle>
<authorgroup>
<author>
<firstname>Marshall Kirk</firstname>
<surname>McKusick</surname>
</author>
<author><personname><firstname>Marshall Kirk</firstname><surname>McKusick</surname></personname></author>
</authorgroup>
<title><ulink
url="http://www.oreilly.com/catalog/opensources/book/toc.html">Open
<citetitle><link xlink:href="http://www.oreilly.com/catalog/opensources/book/toc.html">Open
Sources: Voices from the Open Source
Revolution</ulink></title>
<isbn>ISBN 1-56592-582-3</isbn>
Revolution</link></citetitle>
<biblioid class="isbn">ISBN 1-56592-582-3</biblioid>
<publisher>
<publishername>O'Reilly Inc.</publishername>
</publisher>
@ -974,13 +916,10 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>Mon2005</abbrev>
<citetitle><ulink url="&url.articles.bsdl-gpl;/article.html">Why you should
<citetitle><link xlink:href="&url.articles.bsdl-gpl;/article.html">Why you should
use a BSD style license for your Open Source
Project</ulink></citetitle>
<author>
<firstname>Bruce</firstname>
<surname>Montague</surname>
</author>
Project</link></citetitle>
<author><personname><firstname>Bruce</firstname><surname>Montague</surname></personname></author>
<publisher>
<publishername>The FreeBSD Project</publishername>
</publisher>
@ -990,12 +929,9 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry xreflabel="Nik2005">
<abbrev>Nik2005</abbrev>
<citetitle><ulink url="&url.books.dev-model;/book.html">A
project model for the FreeBSD Project</ulink></citetitle>
<author>
<firstname>Niklas</firstname>
<surname>Saers</surname>
</author>
<citetitle><link xlink:href="&url.books.dev-model;/book.html">A
project model for the FreeBSD Project</link></citetitle>
<author><personname><firstname>Niklas</firstname><surname>Saers</surname></personname></author>
<copyright>
<year>2005</year>
</copyright>
@ -1005,18 +941,11 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry xreflabel="Nor1993">
<abbrev>Nor1993</abbrev>
<citetitle><ulink
url="http://www.norvig.com/luv-slides.ps">Tutorial
on Good Lisp Programming Style</ulink></citetitle>
<citetitle><link xlink:href="http://www.norvig.com/luv-slides.ps">Tutorial
on Good Lisp Programming Style</link></citetitle>
<authorgroup>
<author>
<firstname>Peter</firstname>
<surname>Norvig</surname>
</author>
<author>
<firstname>Kent</firstname>
<surname>Pitman</surname>
</author>
<author><personname><firstname>Peter</firstname><surname>Norvig</surname></personname></author>
<author><personname><firstname>Kent</firstname><surname>Pitman</surname></personname></author>
</authorgroup>
<copyright>
<year>1993</year>
@ -1024,26 +953,19 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>Nor2001</abbrev>
<citetitle><ulink url="http://www.norvig.com/21-days.html">Teach
Yourself Programming in Ten Years</ulink></citetitle>
<author>
<firstname>Peter</firstname>
<surname>Norvig</surname>
</author>
<citetitle><link xlink:href="http://www.norvig.com/21-days.html">Teach
Yourself Programming in Ten Years</link></citetitle>
<author><personname><firstname>Peter</firstname><surname>Norvig</surname></personname></author>
<copyright>
<year>2001</year>
</copyright>
</biblioentry>
<biblioentry>
<abbrev>Ray2004</abbrev>
<citetitle><ulink
url="http://www.catb.org/~esr/faqs/smart-questions.html">How
to ask questions the smart way</ulink></citetitle>
<citetitle><link xlink:href="http://www.catb.org/~esr/faqs/smart-questions.html">How
to ask questions the smart way</link></citetitle>
<authorgroup>
<author>
<firstname>Eric Steven</firstname>
<surname>Raymond</surname>
</author>
<author><personname><firstname>Eric Steven</firstname><surname>Raymond</surname></personname></author>
</authorgroup>
<copyright>
<year>2004</year>
@ -1051,12 +973,9 @@ bde 2005-10-29 16:34:50 UTC
</biblioentry>
<biblioentry>
<abbrev>RelEngDoc</abbrev>
<citetitle><ulink url="&url.articles.releng;">FreeBSD Release
Engineering</ulink></citetitle>
<author>
<firstname>Murray</firstname>
<surname>Stokely</surname>
</author>
<citetitle><link xlink:href="&url.articles.releng;">FreeBSD Release
Engineering</link></citetitle>
<author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author>
<copyright>
<year>2001</year>
</copyright>

50
en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml
View file

@ -1,23 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<title>Argentina.com : A Case Study</title>
<articleinfo>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Argentina.com : A Case Study</title>
<authorgroup>
<author>
<firstname>Carlos</firstname>
<surname>Horowicz</surname>
<affiliation>
<author><personname><firstname>Carlos</firstname><surname>Horowicz</surname></personname><affiliation>
<address><email>ch@argentina.com</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.xfree86;
@ -27,9 +22,9 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<sect1 id="overview">
<sect1 xml:id="overview">
<title>Overview</title>
<para>Argentina.Com is an Argentine ISP with a small infrastructure
@ -69,7 +64,7 @@
business in the corporate and paid email arena.</para>
</sect1>
<sect1 id="challenge">
<sect1 xml:id="challenge">
<title>The Challenge</title>
<para>The main challenge for Argentina.Com is to achieve a dialup
@ -133,10 +128,10 @@
</sect1>
<sect1 id="freebsd">
<sect1 xml:id="freebsd">
<title>The FreeBSD solution</title>
<sect2 id="freebsd-intro">
<sect2 xml:id="freebsd-intro">
<title>Introduction</title>
<para>At the beginning of 2003 we had a CriticalPath mail system
@ -152,15 +147,14 @@
FreeBSD 4.8 with Linux emulation.</para>
</sect2>
<sect2 id="freebsd-choice">
<sect2 xml:id="freebsd-choice">
<title>The choice of FreeBSD</title>
<para>The FreeBSD operating system is well-known for its great
stability, plus its pragmatism and common sense to put
applications on-line thanks to its excellent <ulink
url="http://www.FreeBSD.org/ports">Ports System</ulink>. We
consider its <ulink url="http://www.FreeBSD.org/releng">release
engineering process</ulink> to be easily understandable, while
applications on-line thanks to its excellent <link xlink:href="http://www.FreeBSD.org/ports">Ports System</link>. We
consider its <link xlink:href="http://www.FreeBSD.org/releng">release
engineering process</link> to be easily understandable, while
the users' community at the official mailing lists keeps a
polite and civilized style when it comes to asking for support
or reading other people's problems and solutions.</para>
@ -186,7 +180,7 @@
</sect2>
<sect2 id="freebsd-engineer">
<sect2 xml:id="freebsd-engineer">
<title>Basic re-engineering</title>
<para>The first re-engineering step was to put in place two
@ -209,7 +203,7 @@
</sect2>
<sect2 id="freebsd-email">
<sect2 xml:id="freebsd-email">
<title>Email migration</title>
<para>The email migration required careful planning due to the
@ -285,7 +279,7 @@
</sect2>
<sect2 id="freebsd-web">
<sect2 xml:id="freebsd-web">
<title>Web migration</title>
<para>With the adoption of FreeBSD, there was almost no additional
@ -300,7 +294,7 @@
</sect1>
<sect1 id="results">
<sect1 xml:id="results">
<title>Results</title>
<para>We managed to deploy a FreeBSD based email architecture that
@ -320,5 +314,3 @@
</sect1>
</article>

676
en_US.ISO8859-1/articles/committers-guide/article.xml
View file

File diff suppressed because it is too large Load diff

65
en_US.ISO8859-1/articles/compiz-fusion/article.xml
View file

@ -1,18 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Installing and using Compiz&nbsp;Fusion</title>
<article lang="en">
<articleinfo>
<title>Installing and using Compiz&nbsp;Fusion</title>
<author>
<firstname>Manolis</firstname>
<surname>Kiagias</surname>
<affiliation>
<author><personname><firstname>Manolis</firstname><surname>Kiagias</surname></personname><affiliation>
<address><email>manolis@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2008</year>
@ -23,7 +18,7 @@
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -33,19 +28,18 @@
the latest fashion: 3D Desktop effects. While their usefulness is
rather heavily debated, the wow factor behind the composited desktop
holds quite well. Several different programs have emerged, like
<ulink url="http://compiz.org/"><application>Compiz</application></ulink>,
<ulink url="http://www.beryl-project.org/"><application>Beryl</application></ulink>,
and the latest <ulink
url="http://www.compiz-fusion.org/"><application>Compiz&nbsp;Fusion</application></ulink>.
<link xlink:href="http://compiz.org/"><application>Compiz</application></link>,
<link xlink:href="http://www.beryl-project.org/"><application>Beryl</application></link>,
and the latest <link xlink:href="http://www.compiz-fusion.org/"><application>Compiz&nbsp;Fusion</application></link>.
You do not need to miss these effects when using &os;. These
instructions will help you install and configure your system for the
latest 3D desktop experience using
<application>Compiz Fusion</application> and nVidia drivers
(if applicable).</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>While installing <application>Compiz&nbsp;Fusion</application> from
@ -82,7 +76,7 @@
</itemizedlist>
</sect1>
<sect1 id="nvidia-setup">
<sect1 xml:id="nvidia-setup">
<title>Setting up the &os; nVidia driver</title>
<para>Desktop effects can cause quite a load on your graphics card.
@ -92,7 +86,7 @@
desktop effects, you may skip this section and continue with the
<filename>xorg.conf</filename> configuration.</para>
<sect2 id="determine-driver">
<sect2 xml:id="determine-driver">
<title>Determining the correct driver to use</title>
<para>There are various versions of the nVidia drivers in the
@ -102,13 +96,13 @@
<itemizedlist>
<listitem>
<para>The latest versions of nVidia cards are supported by the
<filename role="package">x11/nvidia-driver</filename> port.</para>
<package>x11/nvidia-driver</package> port.</para>
</listitem>
<listitem>
<para>nVidia cards like the GeForce 2MX/3/4 series are supported by
the 96<replaceable>XX</replaceable> series of drivers, available
in the <filename role="package">x11/nvidia-driver-96xx</filename>
in the <package>x11/nvidia-driver-96xx</package>
port.</para>
</listitem>
@ -116,18 +110,17 @@
<para>Even older cards, like GeForce and RIVA TNT are supported
by the 71<replaceable>XX</replaceable> series of drivers,
available in the
<filename role="package">x11/nvidia-driver-71xx</filename>
<package>x11/nvidia-driver-71xx</package>
port.</para>
</listitem>
</itemizedlist>
<para>In fact, nVidia provides detailed information on which card is
supported by which driver. This information is available directly
on their web site: <ulink
url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para>
on their web site: <uri xlink:href="http://www.nvidia.com/object/IO_32667.html">http://www.nvidia.com/object/IO_32667.html</uri>.</para>
</sect2>
<sect2 id="install-driver">
<sect2 xml:id="install-driver">
<title>Installing the nVidia driver</title>
<para>Having determined the correct driver to use for your card,
@ -184,8 +177,8 @@
<note>
<para>Although not strictly necessary, you may also wish to install
<filename role="package">x11/nvidia-xconfig</filename> and
<filename role="package">x11/nvidia-settings</filename> ports. The
<package>x11/nvidia-xconfig</package> and
<package>x11/nvidia-settings</package> ports. The
former can assist you in writing settings to
<filename>/etc/X11/xorg.conf</filename> from the command line, and
the latter will allow you to modify screen settings from a GUI while
@ -194,7 +187,7 @@
</sect2>
</sect1>
<sect1 id="xorg-configuration">
<sect1 xml:id="xorg-configuration">
<title>Configuring xorg.conf for desktop effects</title>
<para>Before you install and run
@ -253,7 +246,7 @@ Load "glx"
<note>
<para>If you installed the
<filename role="package">x11/nvidia-xconfig</filename> port,
<package>x11/nvidia-xconfig</package> port,
you should be able to perform most of the above settings by
entering the following commands (as root):</para>
@ -266,7 +259,7 @@ Load "glx"
</note>
</sect1>
<sect1 id="compiz-fusion">
<sect1 xml:id="compiz-fusion">
<title>Installing and configuring Compiz&nbsp;Fusion</title>
<para>Installing <application>Compiz&nbsp;Fusion</application>
@ -340,7 +333,7 @@ emerald --replace &amp;</programlisting>
</para>
</sect1>
<sect1 id="compiz-troubleshooting">
<sect1 xml:id="compiz-troubleshooting">
<title>Troubleshooting Compiz&nbsp;Fusion</title>
<para>The following section covers frequently asked questions regarding
@ -349,7 +342,7 @@ emerald --replace &amp;</programlisting>
<qandaset>
<qandaentry>
<question id="no-decorations">
<question xml:id="no-decorations">
<para>I have installed
<application>Compiz&nbsp;Fusion</application>,
and after running the commands you mention, my windows are left
@ -365,7 +358,7 @@ emerald --replace &amp;</programlisting>
</qandaentry>
<qandaentry>
<question id="xorg-crash">
<question xml:id="xorg-crash">
<para>When I run the command to start
<application>Compiz&nbsp;Fusion</application>, the X server
crashes and I am back at the console. What is wrong?</para>
@ -384,7 +377,7 @@ emerald --replace &amp;</programlisting>
<para>This is usually the case when you upgrade
<application>&xorg;</application>. You will need to reinstall the
<filename role="package">x11/nvidia-driver</filename> port so
<package>x11/nvidia-driver</package> port so
glx is built again.</para>
</answer>
</qandaentry>

209
en_US.ISO8859-1/articles/console-server/article.xml
View file

@ -1,21 +1,15 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Console Server</title>
<article lang='en'>
<articleinfo>
<title>Console Server</title>
<author>
<firstname>Gregory</firstname>
<surname>Bond</surname>
<affiliation>
<author><personname><firstname>Gregory</firstname><surname>Bond</surname></personname><affiliation>
<address><email>gnb@itga.com.au</email></address>
</affiliation>
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cisco;
&tm-attrib.intel;
@ -36,11 +30,11 @@
a machine that you can use to monitor the consoles of many other
machines, instead of a bunch of serial terminals.</para>
</abstract>
</articleinfo>
</info>
<indexterm><primary>console-server</primary></indexterm>
<sect1 id="problem">
<sect1 xml:id="problem">
<title>The Problem</title>
<para>You have a computer room with lots of &unix; server machines and lots
@ -103,7 +97,7 @@
</itemizedlist>
</sect1>
<sect1 id="possible-solutions">
<sect1 xml:id="possible-solutions">
<title>Possible Solutions</title>
<para>If you use PC hardware for your servers, then a so-called <quote><acronym>KVM</acronym>
@ -122,7 +116,7 @@
<para>Actually, Doug Schache has pointed out that you
<emphasis>can</emphasis> get <acronym>KVM</acronym> switches that also do serial consoles
or Sun compatible <acronym>KVM</acronym> switching as well as PCs, but they are
expensive. See <ulink url="http://www.avocent.com/">Avocent</ulink>
expensive. See <link xlink:href="http://www.avocent.com/">Avocent</link>
for example.)</para>
</note>
@ -179,15 +173,15 @@
<para>Or, if your budget exceeds your willingness to hack, you can
buy an off-the-shelf solution. These vary in price and
capability. See, for example,
<ulink url="http://www.lightwavecom.com/">Lightwave</ulink>,
<ulink url="http://www.perle.com/">Perle</ulink>,
<ulink url="http://www.avocent.com/">Avocent</ulink> or
<ulink url="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black Box</ulink>.
<link xlink:href="http://www.lightwavecom.com/">Lightwave</link>,
<link xlink:href="http://www.perle.com/">Perle</link>,
<link xlink:href="http://www.avocent.com/">Avocent</link> or
<link xlink:href="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black Box</link>.
These solutions can be quite expensive - typically $USD100 - $USD400 per
port.</para>
</sect1>
<sect1 id="our-solution">
<sect1 xml:id="our-solution">
<title>Our Solution</title>
<para>In light of the above requirements, we chose a solution based on a
@ -204,18 +198,16 @@
</listitem>
<listitem>
<para>A PC &unix; system. We used <ulink
url="&url.base;/index.html">&os; 4.3</ulink> as that is used for
<para>A PC &unix; system. We used <link xlink:href="&url.base;/index.html">&os; 4.3</link> as that is used for
other tasks within our office.</para>
</listitem>
<listitem>
<para>A multi-port serial card. We chose the <ulink
url="http://www.stallion.com/html/products/easyio.html">&easyio; PCI</ulink>
8-port card from <ulink url="http://www.stallion.com/">Stallion
Technologies</ulink>. This cost us about $AUD740, or under
$100/port, from <ulink url="http://www.ht.com.au/">Harris
Technologies</ulink> (which has lots of stuff but is by no means the
<para>A multi-port serial card. We chose the <link xlink:href="http://www.stallion.com/html/products/easyio.html">&easyio; PCI</link>
8-port card from <link xlink:href="http://www.stallion.com/">Stallion
Technologies</link>. This cost us about $AUD740, or under
$100/port, from <link xlink:href="http://www.ht.com.au/">Harris
Technologies</link> (which has lots of stuff but is by no means the
cheapest place in town - shop around and you might get it a lot
cheaper). This card has a big DB80 connector on the back, and a
cable plugs into that which has a block with 8 RJ-45 sockets on it.
@ -246,8 +238,7 @@
</listitem>
<listitem>
<para>A program called <ulink
url="http://www.conserver.com/">conserver</ulink>. This program
<para>A program called <link xlink:href="http://www.conserver.com/">conserver</link>. This program
does all the magic required to enable remote access to consoles, and
do the replaying and logging etc. It comes in two parts: a server
called <application>conserver</application> that runs as a daemon
@ -313,35 +304,33 @@
</itemizedlist>
</sect1>
<sect1 id="setting-up-server">
<sect1 xml:id="setting-up-server">
<title>Setting Up The Server</title>
<sect2 id="patching-stallion">
<sect2 xml:id="patching-stallion">
<title>Checking the Stallion driver</title>
<para>&os; has adequate support for modern Stallion cards since
4.4 release. If you are running an older version of &os;, you
will need to upgrade to a more modern version of &os; (which
you should do anyway, to make sure your system is not
vulnerable to known security issues). See the <ulink
url="&url.books.handbook;/makeworld.html">&os;
Handbook</ulink> for information about updating your
vulnerable to known security issues). See the <link xlink:href="&url.books.handbook;/makeworld.html">&os;
Handbook</link> for information about updating your
system.</para>
</sect2>
<sect2 id="configuring-kernel">
<sect2 xml:id="configuring-kernel">
<title>Configuring a new kernel</title>
<para>The Stallion driver is not included in the default
<literal>GENERIC</literal> kernel, so you will need to create a kernel
config file with the appropriate entries. See &man.stl.4; and the
appropriate section of the <ulink
url="&url.books.handbook;/kernelconfig.html">&os;
Handbook</ulink>.</para>
appropriate section of the <link xlink:href="&url.books.handbook;/kernelconfig.html">&os;
Handbook</link>.</para>
</sect2>
<sect2 id="making-devices">
<sect2 xml:id="making-devices">
<title>Making The Devices</title>
<para>You will need to make the device notes for the Stallion card
@ -364,7 +353,7 @@
for more details.</para>
</sect2>
<sect2 id="compiling-conserver">
<sect2 xml:id="compiling-conserver">
<title>Compiling conserver</title>
<note>
@ -378,17 +367,17 @@
You can either compile
from the source or use the &os; ports framework.</para>
<sect3 id="using-ports">
<sect3 xml:id="using-ports">
<title>Using the ports framework</title>
<para>Using the ports is a bit cleaner, as the package system can then
keep track of installed software and cleanly delete them when not
being used. I recommend using the
<filename role="package">comms/conserver-com</filename> port.
<package>comms/conserver-com</package> port.
Change into the
port directory and (as <username>root</username>) type:</para>
port directory and (as <systemitem class="username">root</systemitem>) type:</para>
<screen>&prompt.root; <userinput>make DEFAULTHOST=<replaceable>consolehost</replaceable> install</userinput></screen>
<screen>&prompt.root; <userinput>make DEFAULTHOST=consolehost install</userinput></screen>
<para>where <replaceable>consolehost</replaceable> is the name of the
machine running the console server. Specifying this when the binary
@ -405,7 +394,7 @@
a <literal>DEFAULTHOST</literal> argument, and one for all the other
hosts with a <literal>DEFAULTHOST</literal> argument. This will
mean the console client program on the console server machine will
default to <hostid>localhost</hostid>, which will work in the
default to <systemitem>localhost</systemitem>, which will work in the
absence of name servers when the network is busted, and also allow
<quote>trusted</quote> (i.e.&nbsp;no password required) connections
via the localhost IP address for users logged into the console
@ -417,7 +406,7 @@
<filename>conserver.cf</filename> file on every machine.</para>
</sect3>
<sect3 id="from-tarball">
<sect3 xml:id="from-tarball">
<title>From the source tarball</title>
<para>If you prefer, you can download <application>conserver</application>
@ -429,9 +418,8 @@
whom have PCs and no &os; host access on their desk) to access
the console server.</para>
<para>Download the file from the <ulink
url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com
FTP site</ulink>. Extract it into a handy directory then
<para>Download the file from the <link xlink:href="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com
FTP site</link>. Extract it into a handy directory then
configure it by running</para>
<screen>&prompt.user; ./configure <option>--with-master=<replaceable>consoleserver</replaceable></option> <option>--with-port=<replaceable>782</replaceable></option></screen>
@ -447,7 +435,7 @@
</sect3>
</sect2>
<sect2 id="configuring-conserver">
<sect2 xml:id="configuring-conserver">
<title>Configuring conserver</title>
<para>The <application>conserver</application> program is configured via a file called
@ -469,24 +457,24 @@ trusted: 127.0.0.1 buzz</programlisting>
the <filename>/var/log/consoles</filename> directory. The
<quote>&amp;</quote> in each line says the log file for that machine
will be
<filename>/var/log/consoles/<replaceable>machine</replaceable></filename>.</para>
<filename>/var/log/consoles/machine</filename>.</para>
<para>The next three lines show three machines to which we need to
connect. We use the
<devicename>cuaE<replaceable>x</replaceable></devicename> devices
<filename>cuaEx</filename> devices
rather than the
<devicename>ttyE<replaceable>x</replaceable></devicename>
<filename>ttyEx</filename>
devices because console ports typically do not show carrier. This
means that opening
<devicename>ttyE<replaceable>x</replaceable></devicename> would hang
<filename>ttyEx</filename> would hang
and <application>conserver</application> would never connect. Using
the
<devicename>cuaE<replaceable>x</replaceable></devicename>
<filename>cuaEx</filename>
device avoids this problem. Another solution would be to use the
<devicename>ttyE<replaceable>x</replaceable></devicename>
<filename>ttyEx</filename>
devices and enable <quote>soft carrier</quote> on these ports, perhaps by
setting this using the
<devicename>ttyiE<replaceable>x</replaceable></devicename>
<filename>ttyiEx</filename>
device in the <filename>/etc/rc.serial</filename> file. See the
comments in this file for more details. Also see &man.sio.4;
for information on the initial-state and locked-state devices. (The
@ -504,7 +492,7 @@ trusted: 127.0.0.1 buzz</programlisting>
section).</para>
</sect2>
<sect2 id="setting-passwords">
<sect2 xml:id="setting-passwords">
<title>Setting conserver passwords</title>
<para>The <filename>conserver.passwd</filename> file contains the
@ -528,7 +516,7 @@ $salt = '$1$' . $salt . '$';
print 'Enter password: ';
`stty -echo`;
$cleartext = &lt;>;
$cleartext = &lt;&gt;;
`stty echo`;
chop($cleartext);
print crypt($cleartext, $salt), "\n";</programlisting>
@ -547,7 +535,7 @@ Password: <userinput>password</userinput>
$1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/</screen>
</sect2>
<sect2 id="starting-conserver">
<sect2 xml:id="starting-conserver">
<title>Starting <application>conserver</application> at system boot time</title>
<para>There are two ways this can be done. Firstly, you could start up
@ -563,7 +551,7 @@ $1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/</screen>
crashes so far), and it arranges for standard output of the
<application>conserver</application>
process to be directed to the named tty (in this case
<devicename>cuaE0</devicename>). This is useful because you
<filename>cuaE0</filename>). This is useful because you
can plug a terminal into this port, and the
<application>conserver</application> program
will show all console output not otherwise captured by a
@ -600,8 +588,8 @@ PATH=/usr/bin:/usr/local/bin
case "$1" in
'start')
TTY=/dev/cuaE7
conserver -d > $TTY
# get NL->CR+NL mapping so msgs look right
conserver -d &gt; $TTY
# get NL-&gt;CR+NL mapping so msgs look right
stty &lt; /dev/cuaE7 opost onlcr
echo -n ' conserver'
;;
@ -618,13 +606,13 @@ esac
exit 0</programlisting>
<note>
<para>Note the use of <devicename>cuaE0</devicename> device
<para>Note the use of <filename>cuaE0</filename> device
and the need to set tty modes for proper NL-&lt;CR
handling).</para>
</note>
</sect2>
<sect2 id="trimming-logs">
<sect2 xml:id="trimming-logs">
<title>Keeping the log files trimmed</title>
<para>&os; has a program called
@ -650,7 +638,7 @@ exit 0</programlisting>
</sect2>
</sect1>
<sect1 id="cabling">
<sect1 xml:id="cabling">
<title>Cabling</title>
<para>This is always the hardest part of this kind of problem. We had
@ -677,7 +665,7 @@ exit 0</programlisting>
represent serial connections on the RJ-45 plug. So the cabling has to
be very careful to use the right mapping.</para>
<sect2 id="rj45-colors">
<sect2 xml:id="rj45-colors">
<title>RJ-45 colors</title>
<para>RJ-45 cables and plugs have 8 pins/conductors. These are used as
@ -770,9 +758,8 @@ exit 0</programlisting>
<para>Note EIA 468A and EIA 568B are very similar, simply swapping the
colors assigned to pair 2 and pair 3.</para>
<para>See for example the <ulink
url="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron
Tech Support Site</ulink> for more details.</para>
<para>See for example the <link xlink:href="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron
Tech Support Site</link> for more details.</para>
<para>The pins in the RJ-45 plug are numbered from 1 to 8. Holding a
patch lead with the cable pointing down and the clip away from you,
@ -813,14 +800,12 @@ exit 0</programlisting>
into the DB-25 plug as required. This allows us to create a
custom RJ-45-DB-25 mapping. We used a couple of different
sorts, including the
<ulink url="http://www.molexpn.com.au/">MOD-TAP</ulink>
part no.&nbsp;<ulink
url="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</ulink>
and the <ulink
url="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730
series</ulink> from
<ulink url="http://www.blackboxoz.com.au/">Black
Box</ulink>.</para>
<link xlink:href="http://www.molexpn.com.au/">MOD-TAP</link>
part no.&nbsp;<link xlink:href="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</link>
and the <link xlink:href="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730
series</link> from
<link xlink:href="http://www.blackboxoz.com.au/">Black
Box</link>.</para>
<para>On our version of the headshells, these flyleads had the
following colours (from Pin 1-8): Blue, Orange, Black, Red,
@ -1106,8 +1091,8 @@ exit 0</programlisting>
<para>We run &os; 4 on a couple of &i386; PCs for various peripheral
uses. &os; usually uses a screen and keyboard for the
console, but can be configured to use a serial port (usually the
first serial port known as <devicename>COM1</devicename> in DOS/&windows; or
<devicename>ttyd0</devicename> in &unix;).</para>
first serial port known as <filename>COM1</filename> in DOS/&windows; or
<filename>ttyd0</filename> in &unix;).</para>
<para>The cabling for these servers depends on the PC hardware. If
the PC has DB-25 female socket on board (as most older PCs do),
@ -1209,7 +1194,7 @@ exit 0</programlisting>
</sect2>
</sect1>
<sect1 id="solaris">
<sect1 xml:id="solaris">
<title>On Sun Systems And Break</title>
<para>Anyone who has turned off a terminal used as a console for a Sun
@ -1267,27 +1252,27 @@ exit 0</programlisting>
power-on or reboot.</para>
</sect1>
<sect1 id="freebsd">
<sect1 xml:id="freebsd">
<title>Using a Serial Console on &os;</title>
<para>The procedure for doing this is described in detail in the
<ulink url="&url.books.handbook;/serialconsole-setup.html">&os;
Handbook</ulink>. This is a quick summary.</para>
<link xlink:href="&url.books.handbook;/serialconsole-setup.html">&os;
Handbook</link>. This is a quick summary.</para>
<sect2 id="freebsd-kernconf">
<sect2 xml:id="freebsd-kernconf">
<title>Check the kernel configuration</title>
<para>Check that the kernel configuration file has
<literal>flags 0x10</literal> in the config line for the
<devicename>sio0</devicename> device. This signals this device (known
as <devicename>COM1</devicename> in DOS/&windows; or
<devicename>/dev/ttyd0</devicename> in &os;) can be used as a
<filename>sio0</filename> device. This signals this device (known
as <filename>COM1</filename> in DOS/&windows; or
<filename>/dev/ttyd0</filename> in &os;) can be used as a
console. This flag is set on the <filename>GENERIC</filename> and
<filename>LINT</filename> sample configs, so is likely to be set in
your kernel.</para>
</sect2>
<sect2 id="freebsd-bootconf">
<sect2 xml:id="freebsd-bootconf">
<title>Create the <filename>/boot.conf</filename>
file</title>
@ -1296,14 +1281,14 @@ exit 0</programlisting>
tells the &os; boot blocks to use the serial console.</para>
</sect2>
<sect2 id="freebsd-ttys">
<sect2 xml:id="freebsd-ttys">
<title>Edit <filename>/etc/ttys</filename></title>
<para>Edit this file and make the following changes.</para>
<para>If you are not going to have any keyboard/video screen on this
server at all, you should find all the lines for
<devicename>ttyv</devicename> devices like</para>
<filename>ttyv</filename> devices like</para>
<programlisting>ttyv1 "/usr/libexec/getty Pc" cons25 on secure</programlisting>
@ -1311,7 +1296,7 @@ exit 0</programlisting>
will stop login screens being run on the useless video
consoles.</para>
<para>Find the line containing <devicename>ttyd0</devicename>. Change
<para>Find the line containing <filename>ttyd0</filename>. Change
it from</para>
<programlisting>ttyd0 "/usr/libexec/getty std.9600" dialup off secure</programlisting>
@ -1329,7 +1314,7 @@ exit 0</programlisting>
</sect2>
</sect1>
<sect1 id="security">
<sect1 xml:id="security">
<title>Security Implications</title>
<para>The client-server protocol for <application>conserver</application>
@ -1347,7 +1332,7 @@ exit 0</programlisting>
server machine, and run the console client there.</para>
</sect1>
<sect1 id="conserver-versions">
<sect1 xml:id="conserver-versions">
<title>On Conserver Versions</title>
<para>The <application>conserver</application> program has fractured into
@ -1359,7 +1344,7 @@ exit 0</programlisting>
<para>The &os; ports collection contains a port for version 8.5 of
<application>conserver</application> at
<filename role="package">comms/conserver</filename>.
<package>comms/conserver</package>.
This seems to be older and less featureful than the 8.1.9
version (in particular, it does not support consoles connected to
terminal server ports and does not support a
@ -1375,18 +1360,18 @@ exit 0</programlisting>
<para>Beginning with December 2001, Brian's version (currently 8.1.9) is
also presented in ports collection at
<filename role="package">comms/conserver-com</filename>. We therefore
<package>comms/conserver-com</package>. We therefore
recommend you to use this version as it is much more appropriate for
console server building.</para>
</sect1>
<sect1 id="links">
<sect1 xml:id="links">
<title>Links</title>
<variablelist>
<varlistentry>
<term><ulink url="http://www.conserver.com/"></ulink></term>
<term><uri xlink:href="http://www.conserver.com/">http://www.conserver.com/</uri></term>
<listitem>
<para>Homepage for the latest version of <application>conserver</application>.</para>
@ -1394,7 +1379,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz</ulink></term>
<term><link xlink:href="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz</link></term>
<listitem>
<para>The source tarball for version 8.1.9 of
@ -1403,7 +1388,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.stallion.com/"></ulink></term>
<term><uri xlink:href="http://www.stallion.com/">http://www.stallion.com/</uri></term>
<listitem>
<para>Homepage of Stallion Technologies.</para>
@ -1411,7 +1396,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.conserver.com/consoles/msock.html"></ulink></term>
<term><uri xlink:href="http://www.conserver.com/consoles/msock.html">http://www.conserver.com/consoles/msock.html</uri></term>
<listitem>
<para>Davis Harris' <quote>Minor Scroll of Console Knowledge</quote>
@ -1421,7 +1406,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.conserver.com/consoles/"></ulink></term>
<term><uri xlink:href="http://www.conserver.com/consoles/">http://www.conserver.com/consoles/</uri></term>
<listitem>
<para>The <quote>Greater Scroll of Console Knowledge</quote>
@ -1431,7 +1416,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.eng.auburn.edu/users/doug/console.html"></ulink></term>
<term><uri xlink:href="http://www.eng.auburn.edu/users/doug/console.html">http://www.eng.auburn.edu/users/doug/console.html</uri></term>
<listitem>
<para>Doug Hughes has a similar console server, based on the
@ -1440,7 +1425,7 @@ exit 0</programlisting>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.realweasel.com/"></ulink></term>
<term><uri xlink:href="http://www.realweasel.com/">http://www.realweasel.com/</uri></term>
<listitem>
<para>The Real Weasel company makes a ISA or PCI video card that
@ -1455,20 +1440,20 @@ exit 0</programlisting>
</variablelist>
</sect1>
<sect1 id="manpages">
<sect1 xml:id="manpages">
<title>Manual Pages</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.conserver.com/docs/console.man.html">console(8)</ulink></para>
<para><link xlink:href="http://www.conserver.com/docs/console.man.html">console(8)</link></para>
</listitem>
<listitem>
<para><ulink url="http://www.conserver.com/docs/conserver.man.html">conserver(8)</ulink></para>
<para><link xlink:href="http://www.conserver.com/docs/conserver.man.html">conserver(8)</link></para>
</listitem>
<listitem>
<para><ulink url="http://www.conserver.com/docs/conserver.cf.man.html">conserver.cf(5)</ulink></para>
<para><link xlink:href="http://www.conserver.com/docs/conserver.cf.man.html">conserver.cf(5)</link></para>
</listitem>
</itemizedlist>
</sect1>

139
en_US.ISO8859-1/articles/contributing-ports/article.xml
View file

@ -1,10 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Contributing to the FreeBSD Ports Collection</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Contributing to the FreeBSD Ports Collection</title>
<abstract>
<title>Abstract</title>
@ -14,17 +13,11 @@
</abstract>
<authorgroup>
<author>
<firstname>Sam</firstname>
<surname>Lawrance</surname>
</author>
<author>
<firstname>Mark</firstname>
<surname>Linimon</surname>
</author>
<author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -32,7 +25,7 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<indexterm><primary>contributing to ports</primary></indexterm>
@ -57,7 +50,7 @@
to take this into account before deciding to volunteer.</para>
</sect1>
<sect1 id="what-contribute">
<sect1 xml:id="what-contribute">
<title>What you can do to help</title>
<para>There are a number of easy ways you can contribute to
@ -91,18 +84,17 @@
</itemizedlist>
</sect1>
<sect1 id="create-port">
<sect1 xml:id="create-port">
<title>Creating a new port</title>
<para>There is a separate document available to help guide you
through creating (and upgrading) a port called the <ulink
url="&url.books.porters-handbook;">Porter's Handbook</ulink>.
through creating (and upgrading) a port called the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>.
The Porter's Handbook is the best reference to working with the
ports system. It provides details about how the ports system
operates and discusses recommended practices.</para>
</sect1>
<sect1 id="adopt-port">
<sect1 xml:id="adopt-port">
<title>Adopting an unmaintained port</title>
<sect2>
@ -116,12 +108,11 @@
you use regularly.</para>
<para>Unmaintained ports have their
<makevar>MAINTAINER</makevar> set to
<varname>MAINTAINER</varname> set to
<literal>ports@FreeBSD.org</literal>. A list of unmaintained
ports and their current errors and problem reports can be seen
at the <ulink
url="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
Ports Monitoring System</ulink>.</para>
at the <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
Ports Monitoring System</link>.</para>
<para>Some ports affect a large number of others due to
dependencies and slave port relationships. Generally, we
@ -145,13 +136,13 @@
<para>First make sure you understand your
<link linkend="maintain-port">responsibilities as a
maintainer</link>. Also read the
<ulink url="&url.books.porters-handbook;">Porter's
Handbook</ulink>. <emphasis>Please do not commit yourself
<link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link>. <emphasis>Please do not commit yourself
to more than you feel you can comfortably
handle.</emphasis></para>
<para>You may request maintainership of any unmaintained port
as soon as you wish. Simply set <makevar>MAINTAINER</makevar>
as soon as you wish. Simply set <varname>MAINTAINER</varname>
to your own email address and send a PR (Problem Report) with
the change. If the port has build errors or needs updating,
you may wish to include any other changes in the same PR.
@ -168,14 +159,14 @@
</sect2>
</sect1>
<sect1 id="maintain-port">
<sect1 xml:id="maintain-port">
<title>The challenge for port maintainers</title>
<para>This section will give you an idea of why ports need to be
maintained and outline the responsibilities of a port
maintainer.</para>
<sect2 id="why-maintenance">
<sect2 xml:id="why-maintenance">
<title>Why ports require maintenance</title>
<para>Creating a port is a once-off task. Ensuring that a
@ -284,8 +275,8 @@
<para>This is an overview. More information about upgrading a
port is available in the
<ulink url="&url.books.porters-handbook;">
Porter's Handbook</ulink>.</para>
<link xlink:href="&url.books.porters-handbook;">
Porter's Handbook</link>.</para>
<procedure>
<step>
@ -345,8 +336,7 @@
<listitem>
<para>Verify your port using &man.portlint.1; as a
guide. See <link
linkend="resources">resources</link> for important
guide. See <link linkend="resources">resources</link> for important
information about using
<application>portlint</application>.</para>
</listitem>
@ -358,7 +348,7 @@
those ports. This is especially important if your
update changes the shared library version; in this
case, at the very least, the dependent ports will
need to get a <makevar>PORTREVISION</makevar> bump
need to get a <varname>PORTREVISION</varname> bump
so that they will automatically be upgraded by
automated tools such as
<application>portmaster</application> or
@ -373,9 +363,8 @@
<para>Send your update by submitting a PR with an
explanation of the changes and a patch containing the
differences between the original port and the updated
one. Please refer to <ulink
url="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</ulink> for information on how to
one. Please refer to <link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> for information on how to
write a really good PR.</para>
<note>
@ -383,8 +372,7 @@
entire port; instead, use &man.diff.1;
<literal>-ruN</literal>. In this way, committers can
much more easily see exactly what changes are being
made. The Porter's Handbook section on <ulink
url="&url.books.porters-handbook;/port-upgrading.html">Upgrading</ulink>
made. The Porter's Handbook section on <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link>
has more information.</para>
</note>
</step>
@ -460,12 +448,10 @@
<title>Watch for build failures</title>
<para>Regularly check the automated ports building
cluster, <ulink
url="http://pointyhat.FreeBSD.org">pointyhat</ulink>,
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
cluster, <link xlink:href="http://pointyhat.FreeBSD.org">pointyhat</link>,
and the <link xlink:href="http://portscout.FreeBSD.org">distfiles
scanner</link> to see if any of the ports you
maintain are failing to build or fetch (see <link linkend="resources">resources</link> for more
information about these systems). Reports of failures
may also come to you from other users or automated
systems via email.</para>
@ -571,9 +557,8 @@
<title>Respond to bug reports</title>
<para>Bugs may be reported to you through email via the
<ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
GNATS Problem Report database</ulink>. Bugs may also be
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
GNATS Problem Report database</link>. Bugs may also be
reported directly to you by users.</para>
<para>You should respond to PRs and other reports within
@ -716,26 +701,24 @@
</sect2>
</sect1>
<sect1 id="fix-broken">
<sect1 xml:id="fix-broken">
<title>Finding and fixing a broken port</title>
<para>There are two really good places to find a port that needs
some attention.</para>
<para>You can use the <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web
interface</ulink> to the Problem Report database to search
<para>You can use the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web
interface</link> to the Problem Report database to search
through and view unresolved PRs. The majority of ports PRs are
updates, but with a little searching and skimming over synopses
you should be able to find something interesting to work on (the
<literal>sw-bug</literal> class is a good place to
start).</para>
<para>The other place is the <ulink
url="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</ulink>. In particular look for unmaintained ports
<para>The other place is the <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</link>. In particular look for unmaintained ports
with build errors and ports that are marked
<makevar>BROKEN</makevar>. It is OK to send changes for a
<varname>BROKEN</varname>. It is OK to send changes for a
maintained port as well, but remember to ask the maintainer in
case they are already working on the problem.</para>
@ -745,7 +728,7 @@
and, if everything checks out, committed.</para>
</sect1>
<sect1 id="mortal-coil">
<sect1 xml:id="mortal-coil">
<title>When to call it quits</title>
<para>As your interests and commitments change, you may find that
@ -766,39 +749,38 @@
have not been worked on during that time.</para>
</sect1>
<sect1 id="resources">
<sect1 xml:id="resources">
<title>Resources for ports maintainers and contributors</title>
<para>The <ulink url="&url.books.porters-handbook;">Porter's
Handbook</ulink> is your hitchhiker's guide to the ports
<para>The <link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link> is your hitchhiker's guide to the ports
system. Keep it handy!</para>
<para><ulink url="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</ulink> describes how to best formulate and
<para><link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> describes how to best formulate and
submit a PR. In 2005 more than eleven thousand ports PRs were
submitted! Following this article will greatly assist us in
reducing the time needed to handle your PRs.</para>
<para>The <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
Problem Report database</ulink>.</para>
<para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
Problem Report database</link>.</para>
<para><ulink url="http://pointyhat.FreeBSD.org/">Pointyhat</ulink>
<para><link xlink:href="http://pointyhat.FreeBSD.org/">Pointyhat</link>
is the ports build cluster. You can use Pointyhat to check port
build logs across all architectures and major releases.</para>
<para>The <ulink url="http://portsmon.FreeBSD.org/">FreeBSD Ports
Monitoring System</ulink> can show you cross-referenced
<para>The <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports
Monitoring System</link> can show you cross-referenced
information about ports such as build errors and problem
reports. If you are a maintainer you can use it to check on the
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://portscout.FreeBSD.org">FreeBSD Ports
distfile scanner</ulink> can show you ports for which the
<para>The <link xlink:href="http://portscout.FreeBSD.org">FreeBSD Ports
distfile scanner</link> 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
<makevar>MASTER_SITES</makevar> updated.</para>
<varname>MASTER_SITES</varname> updated.</para>
<para>The ports <application>tinderbox</application> is the most
thorough way to test a port through the entire cycle of
@ -806,9 +788,8 @@
command-line interface but also can be controlled via a web
interface. Please see
<filename>ports/ports-mgmt/tinderbox</filename>. More
documentation is located at the <ulink
url="http://tinderbox.marcuscom.com/">marcuscom tinderbox home
page</ulink>.</para>
documentation is located at the <link xlink:href="http://tinderbox.marcuscom.com/">marcuscom tinderbox home
page</link>.</para>
<para>&man.portlint.1; is an application which can be used to
verify that your port conforms to many important stylistic and
@ -816,14 +797,12 @@
simple heuristic application, so you should use it
<emphasis>only as a guide</emphasis>. If
<application>portlint</application> suggests changes which seem
unreasonable, consult the <ulink
url="&url.books.porters-handbook;">Porter's Handbook</ulink>
unreasonable, consult the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>
or ask for advice.</para>
<para>The &a.ports; is for general ports-related discussion. It
is a good place to ask for help. You can <ulink
url="http://lists.freebsd.org/mailman/listinfo">subscribe, or
read and search the list archives</ulink>. Reading the
is a good place to ask for help. You can <link xlink:href="http://lists.freebsd.org/mailman/listinfo">subscribe, or
read and search the list archives</link>. Reading the
archives of the &a.ports-bugs; and the &a.cvs-ports; may also be
of interest.</para>
</sect1>

97
en_US.ISO8859-1/articles/contributing/article.xml
View file

@ -1,10 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Contributing to FreeBSD</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Contributing to FreeBSD</title>
<abstract>
<para>This article describes the different ways in which an
@ -13,14 +12,10 @@
</abstract>
<authorgroup>
<author>
<firstname>Jordan</firstname>
<surname>Hubbard</surname>
<contrib>Contributed by </contrib>
</author>
<author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.ieee;
&tm-attrib.general;
@ -29,7 +24,7 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<indexterm><primary>contributing</primary></indexterm>
@ -64,14 +59,14 @@
developed, sold, and maintained, and we urge you to at least give
it a second look.</para>
<sect1 id="contrib-what">
<sect1 xml:id="contrib-what">
<title>What Is Needed</title>
<para>The following list of tasks and sub-projects represents
something of an amalgam of various <filename>TODO</filename>
lists and user requests.</para>
<sect2 id="non-programmer-tasks">
<sect2 xml:id="non-programmer-tasks">
<title>Ongoing Non-Programmer Tasks</title>
<para>Many people who are involved in FreeBSD are not
@ -94,9 +89,8 @@
language. If documentation already exists for your
language, you can help translate additional documents or
verify that the translations are up-to-date. First take a
look at the <ulink
url="&url.books.fdp-primer;/translations.html">Translations
FAQ</ulink> in the FreeBSD Documentation Project Primer.
look at the <link xlink:href="&url.books.fdp-primer;/translations.html">Translations
FAQ</link> in the FreeBSD Documentation Project Primer.
You are not committing yourself to translating every
single FreeBSD document by doing this &mdash; as a
volunteer, you can do as much or as little translation as
@ -117,7 +111,7 @@
</orderedlist>
</sect2>
<sect2 id="ongoing-programmer-tasks">
<sect2 xml:id="ongoing-programmer-tasks">
<title>Ongoing Programmer Tasks</title>
<para>Most of the tasks listed here require either a
@ -130,7 +124,7 @@
<listitem>
<para>If you run FreeBSD-CURRENT and have a good Internet
connection, there is a machine
<hostid role="fqdn">current.FreeBSD.org</hostid> which
<systemitem class="fqdomainname">current.FreeBSD.org</systemitem> which
builds a full release once a day&mdash;every now and
again, try to install the latest release from it and
report any failures in the process.</para>
@ -152,13 +146,13 @@
<listitem>
<para>Move contributed software to
<filename class="directory">src/contrib</filename> in the
<filename>src/contrib</filename> in the
source tree.</para>
</listitem>
<listitem>
<para>Make sure code in
<filename class="directory">src/contrib</filename> is up
<filename>src/contrib</filename> is up
to date.</para>
</listitem>
@ -183,8 +177,8 @@
<listitem>
<para>Get copies of formal standards like &posix;. You can
get some links about these standards at the
<ulink url="&url.base;/projects/c99/index.html">FreeBSD
C99 &amp; POSIX Standards Conformance Project</ulink>
<link xlink:href="&url.base;/projects/c99/index.html">FreeBSD
C99 &amp; POSIX Standards Conformance Project</link>
web site. Compare FreeBSD's behavior to that required by
the standard. If the behavior differs, particularly in
subtle or obscure corners of the specification, send in a
@ -207,9 +201,8 @@
<primary>problem reports database</primary>
</indexterm>
<para>The <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD
PR list</ulink> shows all the current active problem reports
<para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD
PR list</link> shows all the current active problem reports
and requests for enhancement that have been submitted by
FreeBSD users. The PR database includes both programmer and
non-programmer tasks. Look through the open PRs, and see if
@ -231,8 +224,8 @@
<title>Pick one of the items from the <quote>Ideas</quote>
page</title>
<para>The <ulink url="http://wiki.freebsd.org/IdeasPage">&os;
list of projects and ideas for volunteers</ulink> is also
<para>The <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os;
list of projects and ideas for volunteers</link> is also
available for people willing to contribute to the &os;
project. The list is being regularly updated and contains
items for both programmers and non-programmers with
@ -240,28 +233,27 @@
</sect2>
</sect1>
<sect1 id="contrib-how">
<sect1 xml:id="contrib-how">
<title>How to Contribute</title>
<para>Contributions to the system generally fall into one or more
of the following 5 categories:</para>
<sect2 id="contrib-general">
<sect2 xml:id="contrib-general">
<title>Bug Reports and General Commentary</title>
<para>An idea or suggestion of <emphasis>general</emphasis>
technical interest should be mailed to the &a.hackers;.
Likewise, people with an interest in such things (and a
tolerance for a <emphasis>high</emphasis> volume of mail!) may
subscribe to the &a.hackers;. See <ulink
url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The
FreeBSD Handbook</ulink> for more information about this and
subscribe to the &a.hackers;. See <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The
FreeBSD Handbook</link> for more information about this and
other mailing lists.</para>
<para>If you find a bug or are submitting a specific change,
please report it using the &man.send-pr.1; program or its
<ulink url="&url.base;/send-pr.html">WEB-based
equivalent</ulink>. Try to fill-in each field of the bug
<link xlink:href="&url.base;/send-pr.html">WEB-based
equivalent</link>. Try to fill-in each field of the bug
report. Unless they exceed 65KB, include any patches directly
in the report. If the patch is suitable to be applied to the
source tree put <literal>[PATCH]</literal> in the synopsis of
@ -287,9 +279,8 @@
then you may ask someone to file it for you by sending mail to
the &a.bugs;.</para>
<para>See also <ulink
url="&url.articles.problem-reports;/article.html">this
article</ulink> on how to write good problem
<para>See also <link xlink:href="&url.articles.problem-reports;/article.html">this
article</link> on how to write good problem
reports.</para>
</sect2>
@ -302,8 +293,8 @@
<para>Changes to the documentation are overseen by the &a.doc;.
Please look at the
<ulink url="&url.books.fdp-primer;/index.html">FreeBSD
Documentation Project Primer</ulink> for complete
<link xlink:href="&url.books.fdp-primer;/index.html">FreeBSD
Documentation Project Primer</link> for complete
instructions. Send submissions and changes (even small ones
are welcome!) using &man.send-pr.1; as described in
<link linkend="contrib-general">Bug Reports and General
@ -321,9 +312,8 @@
There is a special on-going release of FreeBSD known as
<quote>FreeBSD-CURRENT</quote> which is made available in a
variety of ways for the convenience of developers working
actively on the system. See <ulink
url="&url.books.handbook;/current-stable.html">The FreeBSD
Handbook</ulink> for more information about getting and
actively on the system. See <link xlink:href="&url.books.handbook;/current-stable.html">The FreeBSD
Handbook</link> for more information about getting and
using FreeBSD-CURRENT.</para>
<para>Working from older sources unfortunately means that your
@ -440,8 +430,8 @@
formatter, etc) it would be silly to refuse additional
contributions under this license. Code under the GPL also
goes into a different part of the tree, that being
<filename class="directory">/sys/gnu</filename> or
<filename class="directory">/usr/src/gnu</filename>, and
<filename>/sys/gnu</filename> or
<filename>/usr/src/gnu</filename>, and
is therefore easily identifiable to anyone for whom the
GPL presents a problem.</para>
</listitem>
@ -501,7 +491,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
peripherals since we generally lack the funds to buy such
items ourselves.</para>
<sect3 id="donation">
<sect3 xml:id="donation">
<title>Donating Funds</title>
<para>The FreeBSD Foundation is a non-profit, tax-exempt
@ -523,13 +513,12 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<para>The FreeBSD Foundation is now able to accept donations
through the web with PayPal. To place a donation, please
visit the Foundation
<ulink url="http://www.freebsdfoundation.org">web
site</ulink>.</para>
<link xlink:href="http://www.freebsdfoundation.org">web
site</link>.</para>
<para>More information about the FreeBSD Foundation can be
found in <ulink
url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
FreeBSD Foundation -- an Introduction</ulink>. To contact
found in <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
FreeBSD Foundation -- an Introduction</link>. To contact
the Foundation by email, write to
<email>bod@FreeBSDFoundation.org</email>.</para>
</sect3>
@ -542,8 +531,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
<para>The FreeBSD Project happily accepts donations of
hardware that it can find good use for. If you are
interested in donating hardware, please contact the
<ulink url="&url.base;/donations/">Donations Liaison
Office</ulink>.</para>
<link xlink:href="&url.base;/donations/">Donations Liaison
Office</link>.</para>
</sect3>
</sect2>
</sect1>

117
en_US.ISO8859-1/articles/contributors/article.xml
View file

@ -1,16 +1,15 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd" [
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd" [
<!ENTITY % contrib.ent SYSTEM "contrib.ent">
%contrib.ent;
<!ENTITY % not.published "IGNORE">
]>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Contributors to FreeBSD</title>
<article lang='en'>
<articleinfo>
<title>Contributors to FreeBSD</title>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.sun;
&tm-attrib.general;
@ -24,15 +23,15 @@
<para>This article lists individuals and organizations who have
made a contribution to FreeBSD.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="donors">
<sect1 xml:id="donors">
<title>Donors Gallery</title>
<note>
<para>As of 2010, the following section is several years out-of-date.
Donations from the past several years appear
<ulink url="&url.base;/donations/donors.html">here</ulink>.
<link xlink:href="&url.base;/donations/donors.html">here</link>.
</para>
</note>
@ -46,26 +45,24 @@
<para>The following individuals and businesses made it possible for
the FreeBSD Project to build a new central server machine, which
has replaced <hostid role="fqdn">freefall.FreeBSD.org</hostid> at
has replaced <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> at
one point, by donating the following items:</para>
<itemizedlist>
<listitem>
<para>&a.mbarkah.email; and his employer, <ulink
url="http://www.hemi.com/"> Hemisphere Online</ulink>,
<para>&a.mbarkah.email; and his employer, <link xlink:href="http://www.hemi.com/"> Hemisphere Online</link>,
donated a <emphasis>Pentium Pro (P6) 200MHz CPU</emphasis>
</para>
</listitem>
<listitem>
<para><ulink url="http://www.asacomputers.com/">ASA
Computers</ulink> donated a <emphasis>Tyan 1662
<para><link xlink:href="http://www.asacomputers.com/">ASA
Computers</link> donated a <emphasis>Tyan 1662
motherboard</emphasis>.</para>
</listitem>
<listitem>
<para>Joe McGuckin <email>joe@via.net</email> of <ulink
url="http://www.via.net/">ViaNet Communications</ulink> donated
<para>Joe McGuckin <email>joe@via.net</email> of <link xlink:href="http://www.via.net/">ViaNet Communications</link> donated
a <emphasis>Kingston ethernet controller.</emphasis></para>
</listitem>
@ -76,8 +73,7 @@
</listitem>
<listitem>
<para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink
url="http://www.Alameda.net/">Alameda Networks</ulink> donated
<para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <link xlink:href="http://www.Alameda.net/">Alameda Networks</link> donated
<emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk
drive and the case.</emphasis></para>
</listitem>
@ -101,13 +97,13 @@
</listitem>
<listitem>
<para><ulink url="http://www.bluemountain.com/">Blue Mountain
Arts</ulink></para>
<para><link xlink:href="http://www.bluemountain.com/">Blue Mountain
Arts</link></para>
</listitem>
<listitem>
<para><ulink url="http://www.epilogue.com/">Epilogue Technology
Corporation</ulink></para>
<para><link xlink:href="http://www.epilogue.com/">Epilogue Technology
Corporation</link></para>
</listitem>
<listitem>
@ -115,8 +111,8 @@
</listitem>
<listitem>
<para><ulink url="http://www.gta.com/">Global Technology
Associates, Inc</ulink></para>
<para><link xlink:href="http://www.gta.com/">Global Technology
Associates, Inc</link></para>
</listitem>
<listitem>
@ -142,8 +138,8 @@
<listitem>
<para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of
<ulink url="http://www.imagescape.com/">Imaginary Landscape,
LLC.</ulink></para>
<link xlink:href="http://www.imagescape.com/">Imaginary Landscape,
LLC.</link></para>
</listitem>
<listitem>
@ -151,41 +147,41 @@
</listitem>
<listitem>
<para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan
<para><link xlink:href="http://www.cdrom.co.jp/">Laser5</link> of Japan
(a portion of the profits from sales of their various FreeBSD
CDROMs).</para>
</listitem>
<listitem>
<para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan
Publishing Co.</ulink> donated a portion of their profits from
<para><link xlink:href="http://www.mmjp.or.jp/fuki/">Fuki Shuppan
Publishing Co.</link> donated a portion of their profits from
<emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting
started) to the FreeBSD and XFree86 projects.</para>
</listitem>
<listitem>
<para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink>
<para><link xlink:href="http://www.ascii.co.jp/">ASCII Corp.</link>
donated a portion of their profits from several FreeBSD-related
books to the FreeBSD project.</para>
</listitem>
<listitem>
<para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric
Corp</ulink> has generously donated significant funding to the
<para><link xlink:href="http://www.yokogawa.co.jp/">Yokogawa Electric
Corp</link> has generously donated significant funding to the
FreeBSD project.</para>
</listitem>
<listitem>
<para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para>
<para><link xlink:href="http://www.buffnet.net/">BuffNET</link></para>
</listitem>
<listitem>
<para><ulink url="http://www.pacificsolutions.com/">Pacific
Solutions</ulink></para>
<para><link xlink:href="http://www.pacificsolutions.com/">Pacific
Solutions</link></para>
</listitem>
<listitem>
<para><ulink url="http://www.siemens.de/">Siemens AG</ulink>
<para><link xlink:href="http://www.siemens.de/">Siemens AG</link>
via Andre Albsmeier
<email>andre.albsmeier@mchp.siemens.de</email></para>
</listitem>
@ -213,7 +209,7 @@
</listitem>
<listitem>
<para><ulink url="http://www.compaq.com">Compaq</ulink>
<para><link xlink:href="http://www.compaq.com">Compaq</link>
has donated a variety of Alpha systems to the FreeBSD
Project. Among the many generous donations are 4
AlphaStation DS10s, an AlphaServer DS20,
@ -243,24 +239,23 @@
<listitem>
<para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko.email;,
provided Wangtek and Archive QIC-02 tape drives in order to
improve the <devicename>wt</devicename> driver.</para>
improve the <filename>wt</filename> driver.</para>
</listitem>
<listitem>
<para>Ernst Winter (<ulink url="http://berklix.org/ewinter/">Deceased</ulink>)
<para>Ernst Winter (<link xlink:href="http://berklix.org/ewinter/">Deceased</link>)
contributed a 2.88 MB floppy drive to the project. This will hopefully
increase the pressure for rewriting the floppy disk driver.
</para>
</listitem>
<listitem>
<para><ulink url="http://www.tekram.com/">Tekram
Technologies</ulink> sent one each of their DC-390, DC-390U
<para><link xlink:href="http://www.tekram.com/">Tekram
Technologies</link> sent one each of their DC-390, DC-390U
and DC-390F FAST and ULTRA SCSI host adapter cards for
regression testing of the NCR and AMD drivers with their cards.
They are also to be applauded for making driver sources for free
operating systems available from their FTP server <ulink
url="ftp://ftp.tekram.com/scsi/FreeBSD/"></ulink>.</para>
operating systems available from their FTP server <uri xlink:href="ftp://ftp.tekram.com/scsi/FreeBSD/">ftp://ftp.tekram.com/scsi/FreeBSD/</uri>.</para>
</listitem>
<listitem>
@ -293,22 +288,20 @@
<itemizedlist>
<listitem>
<para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM)
<para><link xlink:href="http://www.osd.bsdi.com/">BSDi</link> (formerly Walnut Creek CDROM)
has donated almost more than we can say (see the 'About the FreeBSD Project'
section of the <ulink url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> for more details).
section of the <link xlink:href="&url.books.handbook;/index.html">FreeBSD Handbook</link> for more details).
In particular, we would like to thank them for the original
hardware used for <hostid
role="fqdn">freefall.FreeBSD.org</hostid>, our primary
development machine, and for <hostid
role="fqdn">thud.FreeBSD.org</hostid>, a testing and build
hardware used for <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem>, our primary
development machine, and for <systemitem class="fqdomainname">thud.FreeBSD.org</systemitem>, a testing and build
box. We are also indebted to them for funding various
contributors over the years and providing us with unrestricted
use of their T1 connection to the Internet.</para>
</listitem>
<listitem>
<para>The <ulink url="http://www.interface-business.de/">interface
business GmbH, Dresden</ulink> has been patiently supporting
<para>The <link xlink:href="http://www.interface-business.de/">interface
business GmbH, Dresden</link> has been patiently supporting
&a.joerg.email; who has often preferred FreeBSD work over paid work, and
used to fall back to their (quite expensive) EUnet Internet
connection whenever his private connection became too slow or
@ -316,8 +309,8 @@
</listitem>
<listitem>
<para><ulink url="http://www.bsdi.com/">Berkeley Software Design,
Inc.</ulink> has contributed their DOS emulator code to the
<para><link xlink:href="http://www.bsdi.com/">Berkeley Software Design,
Inc.</link> has contributed their DOS emulator code to the
remaining BSD world, which is used in the
<emphasis>doscmd</emphasis> command.</para>
</listitem>
@ -326,7 +319,7 @@
</itemizedlist>
</sect1>
<sect1 id="staff-committers">
<sect1 xml:id="staff-committers">
<title>The FreeBSD Developers</title>
<para>These are the people who have commit privileges and do the
@ -338,7 +331,7 @@
&contrib.committers;
</sect1>
<sect1 id="contrib-corealumni">
<sect1 xml:id="contrib-corealumni">
<title>Core Team Alumni</title>
<indexterm><primary>core team</primary></indexterm>
@ -351,7 +344,7 @@
&contrib.corealumni;
</sect1>
<sect1 id="contrib-develalumni">
<sect1 xml:id="contrib-develalumni">
<title>Development Team Alumni</title>
<indexterm><primary>development team</primary></indexterm>
@ -364,7 +357,7 @@
&contrib.develalumni;
</sect1>
<sect1 id="contrib-portmgralumni">
<sect1 xml:id="contrib-portmgralumni">
<title>Ports Management Team Alumni</title>
<indexterm><primary>portmgr team</primary></indexterm>
@ -377,7 +370,7 @@
&contrib.portmgralumni;
</sect1>
<sect1 id="contrib-develinmemoriam">
<sect1 xml:id="contrib-develinmemoriam">
<title>Development Team: In Memoriam</title>
<indexterm><primary>development team</primary></indexterm>
@ -391,7 +384,7 @@
&contrib.develinmemoriam;
</sect1>
<sect1 id="contrib-derived">
<sect1 xml:id="contrib-derived">
<title>Derived Software Contributors</title>
<para>This software was originally derived from William F. Jolitz's 386BSD
@ -406,7 +399,7 @@
all the contributors to NetBSD and OpenBSD for their work.</para>
</sect1>
<sect1 id="contrib-additional">
<sect1 xml:id="contrib-additional">
<title>Additional FreeBSD Contributors</title>
<para>(in alphabetical order by first name):</para>
@ -414,7 +407,7 @@
&contrib.additional;
</sect1>
<sect1 id="contrib-386bsd">
<sect1 xml:id="contrib-386bsd">
<title>386BSD Patch Kit Patch Contributors</title>
<para>(in alphabetical order by first name):</para>

3
en_US.ISO8859-1/articles/contributors/contrib.386bsd.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>Adam Glass
<email>glass@postgres.berkeley.edu</email></para>

10
en_US.ISO8859-1/articles/contributors/contrib.additional.xml
View file

@ -4,8 +4,7 @@
NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical
order by first name.
-->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>ABURAYA Ryushirou
<email>rewsirow@ff.iij4u.or.jp</email></para>
@ -2466,7 +2465,7 @@
<listitem>
<para>Denis Generalov
<email>gd@rambler-co.ru></email></para>
<email>gd@rambler-co.ru&gt;</email></para>
</listitem>
<listitem>
@ -3023,8 +3022,7 @@
</listitem>
<listitem>
<para>Ernst Winter (<ulink
url="http://berklix.org/ewinter/">Deceased</ulink>)</para>
<para>Ernst Winter (<link xlink:href="http://berklix.org/ewinter/">Deceased</link>)</para>
</listitem>
<listitem>
@ -6327,7 +6325,7 @@
<listitem>
<para>Martin Kropfinger
<email>freebsd@rakor-net.de></email></para>
<email>freebsd@rakor-net.de&gt;</email></para>
</listitem>
<listitem>

3
en_US.ISO8859-1/articles/contributors/contrib.committers.xml
View file

@ -5,8 +5,7 @@
alphabetical order by last name. Please keep in mind that fact while
adding your entity to the list of developers.
-->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>&a.tabthorpe.email;</para>
</listitem>

3
en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>&a.attilio.email; (2012)</para>
</listitem>

3
en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>&a.kmacy.email; (2005 - 2012)</para>

17
en_US.ISO8859-1/articles/contributors/contrib.develinmemoriam.xml
View file

@ -1,11 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>&a.jb.email; (1997 - 2009; RIP 2009)</para>
<para>
<ulink url="http://hub.opensolaris.org/bin/view/Community+Group+ogb/In+Memoriam">John</ulink>
<link xlink:href="http://hub.opensolaris.org/bin/view/Community+Group+ogb/In+Memoriam">John</link>
made major contributions to FreeBSD, the best known of which
is the import of the &man.dtrace.1; code. John's unique sense
of humor and plain-spokenness either ruffled feathers or
@ -18,10 +17,10 @@
<listitem>
<para>&a.jmz.email; (1994 - 2009; RIP 2009)</para>
<para>
<ulink url="http://www.obs-besancon.fr/article.php3?id_article=323">Jean-Marc</ulink>
<link xlink:href="http://www.obs-besancon.fr/article.php3?id_article=323">Jean-Marc</link>
was an astrophysicist who made important contributions to the modeling
of the atmospheres of both planets and comets at
<ulink url="http://www.obs-besancon.fr/">l'Observatoire de Besan&ccedil;on</ulink>
<link xlink:href="http://www.obs-besancon.fr/">l'Observatoire de Besan&ccedil;on</link>
in Besan&ccedil;on, France. While there, he participated in the
conception and construction of the Vega tricanal spectrometer
that studied Halley's Comet. He had also been a long-time
@ -31,9 +30,9 @@
<listitem>
<para>&a.itojun.email; (1997 - 2001; RIP 2008)</para>
<para>Known to everyone as
<ulink url="http://astralblue.livejournal.com/350702.html">itojun</ulink>,
<link xlink:href="http://astralblue.livejournal.com/350702.html">itojun</link>,
Jun-ichiro Hagino was was a core researcher at the
<ulink url="http://www.kame.net/">KAME Project</ulink>,
<link xlink:href="http://www.kame.net/">KAME Project</link>,
which aimed to provide IPv6 and IPsec technology in freely
redistributable form. Much of this code was incorporated
into FreeBSD. Without his efforts, the state of IPv6 on the
@ -43,7 +42,7 @@
<listitem>
<para>&a.cg.email; (1999 - 2005; RIP 2005)</para>
<para>
<ulink url="http://www.dbsi.org/cam/">Cameron</ulink>
<link xlink:href="http://www.dbsi.org/cam/">Cameron</link>
was a unique individual who contributed to the project
despite serious physical disabilities. He was responsible
for a complete rewrite of our sound system during the
@ -55,7 +54,7 @@
<listitem>
<para>&a.alane.email; (2002 - 2003; RIP 2003)</para>
<para>
<ulink url="http://freebsd.kde.org/memoriam/alane.php">Alan</ulink>
<link xlink:href="http://freebsd.kde.org/memoriam/alane.php">Alan</link>
was a major contributor to the KDE on FreeBSD group. In addition,
he maintained many other difficult and time-consuming ports such
as <application>autoconf</application>,

3
en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $FreeBSD$ -->
<itemizedlist>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<listitem>
<para>&a.beat.email; (2011 - 2013)</para>
</listitem>

79
en_US.ISO8859-1/articles/cups/article.xml
View file

@ -1,21 +1,16 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>CUPS on FreeBSD</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>CUPS on FreeBSD</title>
<authorgroup>
<author>
<firstname>Chess</firstname>
<surname>Griffin</surname>
<affiliation>
<author><personname><firstname>Chess</firstname><surname>Griffin</surname></personname><affiliation>
<address><email>chess@chessgriffin.com</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -27,9 +22,9 @@
<abstract>
<para>An article about configuring CUPS on &os;.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="printing-cups">
<sect1 xml:id="printing-cups">
<title>An Introduction to the Common Unix Printing System (CUPS)</title>
<indexterm><primary>printing</primary></indexterm>
@ -54,11 +49,10 @@
sharing and accessing printers in mixed environments of &os;,
&linux;, &macos;&nbsp;X, or &windows;.</para>
<para>The main site for <application>CUPS</application> is <ulink
url="http://www.cups.org/"></ulink>.</para>
<para>The main site for <application>CUPS</application> is <uri xlink:href="http://www.cups.org/">http://www.cups.org/</uri>.</para>
</sect1>
<sect1 id="printing-cups-install">
<sect1 xml:id="printing-cups-install">
<title>Installing the CUPS Print Server</title>
<para><application>CUPS</application> can be installed from ports or
@ -74,15 +68,15 @@
<screen>&prompt.root; <userinput>pkg_add -r cups</userinput></screen>
<para>Other optional, but recommended, ports or packages are
<filename role="package">print/gutenprint-cups</filename> and
<filename role="package">print/hplip</filename>, both of which add
<package>print/gutenprint-cups</package> and
<package>print/hplip</package>, both of which add
drivers and utilities for a variety of printers. Once installed,
the <application>CUPS</application> configuration files can be
found in the directory
<filename>/usr/local/etc/cups</filename>.</para>
</sect1>
<sect1 id="printing-cups-configuring-server">
<sect1 xml:id="printing-cups-configuring-server">
<title>Configuring the CUPS Print Server</title>
<para>After installation, a few files must edited in order to
@ -91,7 +85,7 @@
<filename>/etc/devfs.rules</filename> and add the following
information to set the proper permissions on all potential printer
devices and to associate printers with the
<groupname>cups</groupname> user group:</para>
<systemitem class="groupname">cups</systemitem> user group:</para>
<programlisting>[system=10]
add path 'unlpt*' mode 0660 group cups
@ -103,13 +97,12 @@ add path 'usb/<replaceable>X</replaceable>.<replaceable>Y</replaceable>.<replace
<para>Note that <replaceable>X</replaceable>,
<replaceable>Y</replaceable>, and <replaceable>Z</replaceable>
should be replaced with the target USB device listed in the
<filename class="directory">/dev/usb</filename> directory that
<filename>/dev/usb</filename> directory that
corresponds to the printer. To find the correct device, examine
the output of &man.dmesg.8;, where
<filename>ugen<replaceable>X</replaceable>.<replaceable>Y</replaceable></filename>
<filename>ugenX.Y</filename>
lists the printer device, which is a symbolic link to a USB
device in <filename
class="directory">/dev/usb</filename>.</para>
device in <filename>/dev/usb</filename>.</para>
</note>
<para>Next, add two lines to <filename>/etc/rc.conf</filename> as
@ -139,7 +132,7 @@ devfs_system_ruleset="system"</programlisting>
&prompt.root; <userinput>/usr/local/etc/rc.d/cupsd restart</userinput></screen>
</sect1>
<sect1 id="printing-cups-configuring-printers">
<sect1 xml:id="printing-cups-configuring-printers">
<title>Configuring Printers on the CUPS Print Server</title>
<para>After the <application>CUPS</application> system has been
@ -153,11 +146,11 @@ devfs_system_ruleset="system"</programlisting>
<para>The primary means for managing and administering the
<application>CUPS</application> server is through the web-based
interface, which can be found by launching a web browser and
entering <ulink url="http://localhost:631"></ulink> in the
entering <uri xlink:href="http://localhost:631">http://localhost:631</uri> in the
browser's URL bar. If the <application>CUPS</application> server
is on another machine on the network, substitute the server's
local <acronym>IP</acronym> address for
<hostid>localhost</hostid>. The <application>CUPS</application>
<systemitem>localhost</systemitem>. The <application>CUPS</application>
web interface is fairly self-explanatory, as there are sections
for managing printers and print jobs, authorizing users, and more.
Additionally, on the right-hand side of the Administration screen
@ -175,15 +168,13 @@ devfs_system_ruleset="system"</programlisting>
Administration screen. When presented with the
<quote>Device</quote> drop-down box, simply select the desired
locally-attached printer, and then continue through the process.
If one has added the <filename
role="package">print/gutenprint-cups</filename> or <filename
role="package">print/hplip</filename> ports or packages as
If one has added the <package>print/gutenprint-cups</package> or <package>print/hplip</package> ports or packages as
referenced above, then additional print drivers will be available
in the subsequent screens that might provide more stability or
features.</para>
</sect1>
<sect1 id="printing-cups-clients">
<sect1 xml:id="printing-cups-clients">
<title>Configuring CUPS Clients</title>
<para>Once the <application>CUPS</application> server has been
@ -194,7 +185,7 @@ devfs_system_ruleset="system"</programlisting>
desktop machine that is acting as both server and client, then
much of this information may not be needed.</para>
<sect2 id="printing-cups-clients-unix">
<sect2 xml:id="printing-cups-clients-unix">
<title>&unix; Clients</title>
<para><application>CUPS</application> will also need to be
@ -206,7 +197,7 @@ devfs_system_ruleset="system"</programlisting>
<application>GNOME</application> or
<application>KDE</application>. Alternatively, one can access
the local <application>CUPS</application> interface on the
client machine at <ulink url="http://localhost:631"></ulink> and
client machine at <uri xlink:href="http://localhost:631">http://localhost:631</uri> and
click on <quote>Add Printer</quote> in the Administration
section. When presented with the <quote>Device</quote>
drop-down box, simply select the networked
@ -235,7 +226,7 @@ devfs_system_ruleset="system"</programlisting>
<application>CUPS</application> server on the network.</para>
</sect2>
<sect2 id="printing-cups-clients-windows">
<sect2 xml:id="printing-cups-clients-windows">
<title>&windows; Clients</title>
<para>Versions of &windows; prior to XP did not have the
@ -253,20 +244,20 @@ devfs_system_ruleset="system"</programlisting>
<para>If one has an older version of &windows; without native
<acronym>IPP</acronym> printing support, then the general means
of connecting to a <application>CUPS</application> printer is to
use <filename role="package">net/samba3</filename> and
use <package>net/samba3</package> and
<application>CUPS</application> together, which is a topic
outside the scope of this chapter.</para>
</sect2>
</sect1>
<sect1 id="printing-cups-troubleshooting">
<sect1 xml:id="printing-cups-troubleshooting">
<title>CUPS Troubleshooting</title>
<para>Difficulties with <application>CUPS</application> often lies
in permissions. First, double check the &man.devfs.8; permissions
as outlined above. Next, check the actual permissions of the
devices created in the file system. It is also helpful to make
sure your user is a member of the <groupname>cups</groupname>
sure your user is a member of the <systemitem class="groupname">cups</systemitem>
group. If the permissions check boxes in the Administration
section of the <application>CUPS</application> web interface do
not seem to be working, another fix might be to manually backup
@ -363,7 +354,7 @@ CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default&gt;
&lt;/Policy&gt;</programlisting>
</sect1>
<sect1 id="printing-cups-ports-knobs">
<sect1 xml:id="printing-cups-ports-knobs">
<title>Fine Tuning CUPS-Related Ports</title>
<para>If <application>CUPS</application> is going to serve as the
@ -377,14 +368,14 @@ CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default&gt;
CUPS_OVERWRITE_BASE=YES
WITHOUT_LPR=YES</programlisting>
<para>The first knob, <makevar>WITH_CUPS</makevar>, adds
<para>The first knob, <varname>WITH_CUPS</varname>, adds
<application>CUPS</application> support to ports where applicable.
The second knob, <makevar>CUPS_OVERWRITE_BASE</makevar>, will fix
The second knob, <varname>CUPS_OVERWRITE_BASE</varname>, will fix
certain symlinks and paths that would otherwise apply to the
default &os; printing system, <application>LPR</application>, and
will prevent these fixes from being reverted upon the next
<maketarget>buildworld</maketarget> system upgrade. The third
knob, <makevar>WITHOUT_LPR</makevar>, will prevent
<buildtarget>buildworld</buildtarget> system upgrade. The third
knob, <varname>WITHOUT_LPR</varname>, will prevent
<application>LPR</application> support from being added to ports
where applicable.</para>
</sect1>

54
en_US.ISO8859-1/articles/custom-gcc/article.xml
View file

@ -1,22 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Using newer version of <application>GCC</application> and
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Using newer version of <application>GCC</application> and
<application>binutils</application> with the &os; Ports
Collection</title>
<author>
<firstname>Martin</firstname>
<surname>Matuska</surname>
<affiliation>
<author><personname><firstname>Martin</firstname><surname>Matuska</surname></personname><affiliation>
<address><email>mm@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -37,9 +32,9 @@
Custom <application>GCC</application> configurations are also
discussed.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>The default system compiler as of &os; 8.0 is
@ -56,10 +51,10 @@
tree.</para>
</sect1>
<sect1 id="prerequisites">
<sect1 xml:id="prerequisites">
<title>Prerequisites</title>
<sect2 id="installing-binutils">
<sect2 xml:id="installing-binutils">
<title>Installing binutils from ports</title>
<para>To make use of all of the new features in the latest
@ -77,25 +72,25 @@
<screen>&prompt.root; <userinput>cd /usr/ports/devel/binutils &amp;&amp; make install</userinput></screen>
</sect2>
<sect2 id="installing-gcc">
<sect2 xml:id="installing-gcc">
<title>Installing GCC from ports</title>
<para>The &os; ports tree offers several new versions of
<application>GCC</application>. The following example is for
the stable version 4.4. However, it is possible to install
previous or later development versions (e.g.
<filename role="package">lang/gcc43</filename> or
<filename role="package">lang/gcc45</filename>).</para>
<package>lang/gcc43</package> or
<package>lang/gcc45</package>).</para>
<para>To install one of the mentioned
<application>GCC</application> ports, run the following
command:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/lang/<replaceable>gcc44</replaceable> &amp;&amp; make install</userinput></screen>
<screen>&prompt.root; <userinput>cd /usr/ports/lang/gcc44 &amp;&amp; make install</userinput></screen>
</sect2>
</sect1>
<sect1 id="configuring-ports-gcc">
<sect1 xml:id="configuring-ports-gcc">
<title>Configuring ports for custom version of
<application>GCC</application></title>
@ -103,7 +98,7 @@
custom version of <application>GCC</application> installed from
the &os; ports tree.</para>
<sect2 id="adjusting-make.conf">
<sect2 xml:id="adjusting-make.conf">
<title>Adjusting <filename>make.conf</filename></title>
<para>Add the following lines to the
@ -129,7 +124,7 @@ CPP=cpp44
</note>
</sect2>
<sect2 id="adjusting-libmap.conf">
<sect2 xml:id="adjusting-libmap.conf">
<title>Adjusting <filename>libmap.conf</filename></title>
<para>Many of the ports' binaries and libraries link to libgcc_s
@ -161,7 +156,7 @@ libstdc++.so.6 gcc44/libstdc++.so.6</programlisting>
</warning>
</sect2>
<sect2 id="custom-cflags">
<sect2 xml:id="custom-cflags">
<title>Custom <literal>CFLAGS</literal> for the ports tree</title>
<para>To add custom <literal>CFLAGS</literal> for the ports tree
@ -183,7 +178,7 @@ CFLAGS+=-mssse3
optimizations flags based on this variable.</para>
</sect2>
<sect2 id="excluding-unbuildable-ports">
<sect2 xml:id="excluding-unbuildable-ports">
<title>Excluding ports that do not build with new version of
<application>GCC</application></title>
@ -202,14 +197,14 @@ CPP=cpp44
<para>The example above excludes the forced use of
<command>gcc</command> 4.4 for the
<filename role="package">net/openldap</filename>* ports. It is
<package>net/openldap</package>* ports. It is
also possible to specify more ports on a single line:</para>
<programlisting>.if empty(.CURDIR:M/usr/ports/net/openldap*) &amp;&amp; empty(.CURDIR:M/usr/ports/xxx/yyy) &amp;&amp; ...</programlisting>
</sect2>
</sect1>
<sect1 id="performance-imparct">
<sect1 xml:id="performance-imparct">
<title>Impact on the binary performance</title>
<para>Using <application>GCC</application> version 4.4 with
@ -219,8 +214,7 @@ CPP=cpp44
more than a 20% performance boost (e.g. in multimedia
processing).</para>
<para>The table located at <ulink
url="http://people.freebsd.org/~mm/benchmarks/perlbench/"></ulink>
<para>The table located at <uri xlink:href="http://people.freebsd.org/~mm/benchmarks/perlbench/">http://people.freebsd.org/~mm/benchmarks/perlbench/</uri>
shows a comparison of <application>GCC</application> versions
currently available in base &os; system,
<application>GCC</application> version 4.3 and

78
en_US.ISO8859-1/articles/cvs-freebsd/article.xml
View file

@ -1,18 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Setting up a CVS repository - the FreeBSD way</title>
<article lang='en'>
<articleinfo>
<title>Setting up a CVS repository - the FreeBSD way</title>
<author>
<firstname>Stijn</firstname>
<surname>Hoop</surname>
<affiliation>
<author><personname><firstname>Stijn</firstname><surname>Hoop</surname></personname><affiliation>
<address><email>stijn@win.tue.nl</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2001</year>
@ -25,7 +20,7 @@
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -37,9 +32,9 @@
granular access control to the source tree and generation of readable
email of every commit.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>Most of the open source software projects use
@ -62,7 +57,7 @@
<application>CVS</application>.</para>
</sect1>
<sect1 id="first-setup">
<sect1 xml:id="first-setup">
<title>First setup</title>
<warning>
@ -77,10 +72,10 @@
<para>The first thing to do when setting up a new repository is to tell
<application>CVS</application> to initialize it:</para>
<screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-repository</replaceable> init</userinput></screen>
<screen>&prompt.user; <userinput>cvs -d path-to-repository init</userinput></screen>
<para>This tells <application>CVS</application> to create the
<filename class="directory">CVSROOT</filename> administrative directory, where all the
<filename>CVSROOT</filename> administrative directory, where all the
customization takes place.</para>
</sect2>
@ -92,12 +87,12 @@
repository. We will assume the FreeBSD default of
<literal>ncvs</literal> for this group.</para>
<screen>&prompt.root; <userinput>pw groupadd <replaceable>ncvs</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>pw groupadd ncvs</userinput></screen>
<para>Next, you should &man.chown.8; the directory to the group
you just added:</para>
<screen>&prompt.root; <userinput>chown -R :<replaceable>ncvs</replaceable> <replaceable>path-to-your-repository</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>chown -R :ncvs path-to-your-repository</userinput></screen>
<para>This ensures that no one can write to the repository without proper
group permissions.</para>
@ -106,25 +101,24 @@
<sect2>
<title>Getting the sources</title>
<para>Now you need to obtain the <filename class="directory">CVSROOT</filename> directory
<para>Now you need to obtain the <filename>CVSROOT</filename> directory
from the FreeBSD repository. This is most easily done by checking it
out from a FreeBSD anonymous CVS mirror. See <ulink
url="&url.books.handbook;/anoncvs.html">the relevant chapter in
the handbook</ulink> for more information. Let us assume that the
sources are stored in <filename class="directory">CVSROOT-freebsd</filename> in the
out from a FreeBSD anonymous CVS mirror. See <link xlink:href="&url.books.handbook;/anoncvs.html">the relevant chapter in
the handbook</link> for more information. Let us assume that the
sources are stored in <filename>CVSROOT-freebsd</filename> in the
current directory.</para>
</sect2>
<sect2>
<title>Copying the FreeBSD scripts</title>
<para>Next, we will copy the FreeBSD <filename class="directory">CVSROOT</filename>
<para>Next, we will copy the FreeBSD <filename>CVSROOT</filename>
sources into your own repository. If you are accustomed to
<application>CVS</application>, you might be thinking that you can just
import the scripts, in an attempt to make synchronizing with later
versions easier. However, it turns out that
<application>CVS</application> has a deficiency in this area:
when importing sources into the <filename class="directory">CVSROOT</filename> directory,
when importing sources into the <filename>CVSROOT</filename> directory,
it will not update the needed administrative files. In order to make
it recognize those, you will need to checkin each file after importing
them, losing the value of <literal>cvs import</literal>. Therefore,
@ -132,10 +126,10 @@
<para>It does not matter if the above paragraph did not make sense to
you&mdash;the end result is the same. Simply check out your
<filename class="directory">CVSROOT</filename> and copy the FreeBSD files over your
<filename>CVSROOT</filename> and copy the FreeBSD files over your
local (untouched) copies:</para>
<screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-your-repository</replaceable> checkout CVSROOT</userinput>
<screen>&prompt.user; <userinput>cvs -d path-to-your-repository checkout CVSROOT</userinput>
&prompt.user; <userinput>cd CVSROOT</userinput>
&prompt.user; <userinput>cp ../CVSROOT-freebsd/* .</userinput>
&prompt.user; <userinput>cvs add *</userinput></screen>
@ -277,7 +271,7 @@
match one of the lines in this file are exempted from this check.
You should add expressions to this file as you checkin files that
cannot have a revision header. For the purpose of installing the
scripts, it may be best to exclude <filename class="directory">CVSROOT/</filename>
scripts, it may be best to exclude <filename>CVSROOT/</filename>
from header checks.</para>
</listitem>
@ -466,7 +460,7 @@
<para><literal>@LOG_FILE_MAP</literal> - change this array
as you wish - each regexp is matched on the directory of
the commit, and the commit log message gets stored in
the <filename class="directory">commitlogs</filename> subdirectory in
the <filename>commitlogs</filename> subdirectory in
the filename mentioned.</para>
</listitem>
@ -495,7 +489,7 @@
<literal>^CVSROOT/</literal>, and add one line with only
<literal>^CVSROOT/</literal> on it. After the wrapper is
installed, you can add your header to the files in the
<filename class="directory">CVSROOT</filename> directory and restore these lines,
<filename>CVSROOT</filename> directory and restore these lines,
but for now they will only be in the way when you try to commit
later on.</para>
</step>
@ -533,7 +527,7 @@
<para>The last thing to do before you are finished, is to make sure
the commitlogs can be stored. By default these are stored in
the repository, in the <filename>commitlogs</filename> subdirectory
of the <filename class="directory">CVSROOT</filename> directory. This directory
of the <filename>CVSROOT</filename> directory. This directory
needs to be created, so do the following:</para>
<screen>&prompt.user; <userinput>mkdir commitlogs</userinput>
@ -543,12 +537,12 @@
<para>Now, after careful review, you should commit your changes. Be
sure that you have granted yourself access to the
<filename class="directory">CVSROOT</filename> directory in your
<filename>CVSROOT</filename> directory in your
<filename>avail</filename> before you do this, because otherwise you
will lock yourself out. So make sure everything is as you intend, and
then do the following:</para>
<screen>&prompt.user; <userinput>cvs commit -m '<replaceable>- Initial FreeBSD scripts commit</replaceable>'</userinput></screen>
<screen>&prompt.user; <userinput>cvs commit -m '- Initial FreeBSD scripts commit'</userinput></screen>
</sect2>
<sect2>
@ -558,7 +552,7 @@
<filename>avail</filename> file, to make sure everything works as
expected.</para>
<screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' avail</userinput></screen>
<screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' avail</userinput></screen>
<para>If everything works, congratulations! You now have a working setup
of the FreeBSD scripts for your repository. If
@ -568,12 +562,12 @@
</sect2>
</sect1>
<sect1 id="freebsdspecific">
<sect1 xml:id="freebsdspecific">
<title>FreeBSD specific setup</title>
<para>The FreeBSD project itself uses a slightly different setup, which
also uses files from the <filename class="directory">freebsd</filename> subdirectory of
the FreeBSD <filename class="directory">CVSROOT</filename>. The project uses this because
also uses files from the <filename>freebsd</filename> subdirectory of
the FreeBSD <filename>CVSROOT</filename>. The project uses this because
of the large number of committers, which all would have to be in the
same group. So, a simple wrapper was written which ensures that people
have the correct credentials to commit, and then sets the group id
@ -642,7 +636,7 @@
<para>Next up is installing the wrapper to ensure you become the
correct group when committing. The sources for this live in
<filename>cvswrap.c</filename> in your
<filename class="directory">CVSROOT</filename>.</para>
<filename>CVSROOT</filename>.</para>
<para>Compile the sources that you edited to include the correct
paths:</para>
@ -653,7 +647,7 @@
<screen>&prompt.root; <userinput>mv /usr/bin/cvs /usr/bin/ncvs</userinput>
&prompt.root; <userinput>mv cvs /usr/bin/cvs</userinput>
&prompt.root; <userinput>chown root:<replaceable>ncvs</replaceable> /usr/bin/cvs /usr/bin/ncvs</userinput>
&prompt.root; <userinput>chown root:ncvs /usr/bin/cvs /usr/bin/ncvs</userinput>
&prompt.root; <userinput>chmod o-rx /usr/bin/ncvs</userinput>
&prompt.root; <userinput>chmod u-w,g+s /usr/bin/cvs</userinput></screen>
@ -676,7 +670,7 @@
<para>Your wrapper should now be setup. You can of course test this by
making a forced commit to the <filename>access</filename> file:</para>
<screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' access</userinput></screen>
<screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' access</userinput></screen>
<para>Again, if this fails, check to see whether all of the above steps have
been executed correctly.</para>

95
en_US.ISO8859-1/articles/explaining-bsd/article.xml
View file

@ -1,24 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Explaining BSD</title>
<article lang='en'>
<articleinfo>
<title>Explaining BSD</title>
<author>
<firstname>Greg</firstname>
<surname>Lehey</surname>
<affiliation>
<author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation>
<address><email>grog@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.amd;
&tm-attrib.apple;
@ -39,14 +32,11 @@
<para>In the open source world, the word <quote>Linux</quote> is almost
synonymous with <quote>Operating System</quote>, but it is not the only
open source &unix; operating system. According
to the <ulink
url="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet
Operating System Counter</ulink>, as of April 1999 31.3% of the
to the <link xlink:href="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet
Operating System Counter</link>, as of April 1999 31.3% of the
world's network connected machines run Linux. 14.6% run BSD &unix;.
Some of the world's largest web operations, such as <ulink
url="http://www.yahoo.com/">Yahoo!</ulink>, run BSD. The world's
busiest FTP server of 1999 (now defunct), <ulink
url="ftp://ftp.cdrom.com/">ftp.cdrom.com</ulink>, used BSD to
Some of the world's largest web operations, such as <link xlink:href="http://www.yahoo.com/">Yahoo!</link>, run BSD. The world's
busiest FTP server of 1999 (now defunct), <link xlink:href="ftp://ftp.cdrom.com/">ftp.cdrom.com</link>, used BSD to
transfer 1.4 TB of data a day. Clearly this is not a niche
market: BSD is a well-kept secret.</para>
@ -56,9 +46,9 @@
<para>Throughout this paper, differences between BSD and Linux will be
noted <emphasis>like this</emphasis>.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="what-is-bsd">
<sect1 xml:id="what-is-bsd">
<title>What is BSD?</title>
<para>BSD stands for <quote>Berkeley Software Distribution</quote>. It is
@ -100,7 +90,7 @@
<para>The X Window system used in most versions of BSD is maintained
by the
<ulink url="http://www.X.org/">X.Org project</ulink>.
<link xlink:href="http://www.X.org/">X.Org project</link>.
&os; allows the user to choose from a variety of desktop
environments, such as <application>Gnome</application>,
<application>KDE</application>, or <application>Xfce</application>;
@ -116,7 +106,7 @@
</itemizedlist>
</sect1>
<sect1 id="what-a-real-unix">
<sect1 xml:id="what-a-real-unix">
<title>What, a real &unix;?</title>
<para>The BSD operating systems are not clones, but open source
@ -165,29 +155,29 @@
CSRG members, William F. Jolitz, wrote the remaining code and released
it in early 1992 as <emphasis>386BSD</emphasis>. At the same time,
another group of ex-CSRG members formed a commercial company called
<ulink url="http://www.bsdi.com/">Berkeley Software Design Inc.</ulink>
<link xlink:href="http://www.bsdi.com/">Berkeley Software Design Inc.</link>
and released a beta version of an operating system called
<ulink url="http://www.bsdi.com/">BSD/386</ulink>, which was based on
<link xlink:href="http://www.bsdi.com/">BSD/386</link>, which was based on
the same sources. The name of the operating system was later changed
to BSD/OS.</para>
<para>386BSD never became a stable operating system. Instead, two other
projects split off from it in 1993:
<ulink url="http://www.NetBSD.org/">NetBSD</ulink> and
<ulink url="&url.base;/index.html">FreeBSD</ulink>. The two projects
<link xlink:href="http://www.NetBSD.org/">NetBSD</link> and
<link xlink:href="&url.base;/index.html">FreeBSD</link>. The two projects
originally diverged due to differences in patience waiting for
improvements to 386BSD: the NetBSD people started early in the year,
and the first version of FreeBSD was not ready until the end of the
year. In the meantime, the code base had diverged sufficiently to
make it difficult to merge. In addition, the projects had different
aims, as we will see below. In 1996,
<ulink url="http://www.OpenBSD.org/">OpenBSD</ulink> split off from
<link xlink:href="http://www.OpenBSD.org/">OpenBSD</link> split off from
NetBSD, and in 2003,
<ulink url="http://www.dragonflybsd.org/">DragonFlyBSD</ulink> split
<link xlink:href="http://www.dragonflybsd.org/">DragonFlyBSD</link> split
off from FreeBSD.</para>
</sect1>
<sect1 id="why-is-bsd-not-better-known">
<sect1 xml:id="why-is-bsd-not-better-known">
<title>Why is BSD not better known?</title>
<para>For a number of reasons, BSD is relatively unknown:</para>
@ -213,7 +203,7 @@
<listitem>
<para>In 1992, AT&amp;T sued
<ulink url="http://www.bsdi.com/">BSDI</ulink>,
<link xlink:href="http://www.bsdi.com/">BSDI</link>,
the vendor of BSD/386, alleging that the product contained
AT&amp;T-copyrighted code. The case was settled out of court in
1994, but the spectre of the litigation continues to haunt people.
@ -232,15 +222,15 @@
<listitem>
<para>There is a perception that the BSD projects are fragmented and
belligerent. The
<ulink url="http://interactive.wsj.com/bin/login?Tag=/&amp;URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&amp;">Wall Street
Journal</ulink> spoke of <quote>balkanization</quote> of the
<link xlink:href="http://interactive.wsj.com/bin/login?Tag=/&amp;URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&amp;">Wall Street
Journal</link> spoke of <quote>balkanization</quote> of the
BSD projects. Like the law suit, this perception bases mainly
on ancient history.</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="comparing-bsd-and-linux">
<sect1 xml:id="comparing-bsd-and-linux">
<title>Comparing BSD and Linux</title>
<para>So what is really the difference between, say, Debian Linux and
@ -269,8 +259,8 @@
<para>The BSD kernels are developed and updated following the Open
Source development model. Each project maintains a publicly
accessible <emphasis>source tree</emphasis> under the
<ulink url="http://www.cvshome.org/">Concurrent Versions
System</ulink> (CVS), which contains all source files for the
<link xlink:href="http://www.cvshome.org/">Concurrent Versions
System</link> (CVS), which contains all source files for the
project, including documentation and other incidental files. CVS
allows users to <quote>check out</quote> (in other words, to
extract a copy of) any desired version of the system.</para>
@ -474,12 +464,11 @@
</listitem>
<listitem>
<para><ulink url="http://www.apple.com/macosx/server/">&macos;
X</ulink> is the latest version of the operating system for
<ulink url="http://www.apple.com/">Apple Computer Inc.'s</ulink>
<para><link xlink:href="http://www.apple.com/macosx/server/">&macos;
X</link> is the latest version of the operating system for
<link xlink:href="http://www.apple.com/">Apple Computer Inc.'s</link>
&macintosh; line. The BSD core of this operating
system, <ulink
url="http://developer.apple.com/darwin/">Darwin</ulink>,
system, <link xlink:href="http://developer.apple.com/darwin/">Darwin</link>,
is available as a fully functional open source operating
system for x86 and PPC computers. The Aqua/Quartz
graphics system and many other proprietary aspects of
@ -495,13 +484,13 @@
license?</title>
<para>Linux is available under the
<ulink url="http://www.fsf.org/copyleft/gpl.html">GNU General Public
License</ulink> (GPL), which is designed to eliminate closed
<link xlink:href="http://www.fsf.org/copyleft/gpl.html">GNU General Public
License</link> (GPL), which is designed to eliminate closed
source software. In particular, any derivative work of a product
released under the GPL must also be supplied with source code if
requested. By contrast, the
<ulink url="http://www.opensource.org/licenses/bsd-license.html">BSD
license</ulink> is less restrictive: binary-only distributions are
<link xlink:href="http://www.opensource.org/licenses/bsd-license.html">BSD
license</link> is less restrictive: binary-only distributions are
allowed. This is particularly attractive for embedded
applications.</para>
</sect2>
@ -578,15 +567,15 @@
<sect2>
<title>Who provides support, service, and training for BSD?</title>
<para>BSDi / <ulink url="http://www.freebsdmall.com">FreeBSD
Mall, Inc.</ulink> have been providing support contracts for
<para>BSDi / <link xlink:href="http://www.freebsdmall.com">FreeBSD
Mall, Inc.</link> have been providing support contracts for
FreeBSD for nearly a decade.</para>
<para>In addition, each of the projects has a list of consultants for
hire:
<ulink url="&url.base;/commercial/consult_bycat.html">FreeBSD</ulink>,
<ulink url="http://www.netbsd.org/gallery/consultants.html">NetBSD</ulink>,
and <ulink url="http://www.openbsd.org/support.html">OpenBSD</ulink>.</para>
<link xlink:href="&url.base;/commercial/consult_bycat.html">FreeBSD</link>,
<link xlink:href="http://www.netbsd.org/gallery/consultants.html">NetBSD</link>,
and <link xlink:href="http://www.openbsd.org/support.html">OpenBSD</link>.</para>
</sect2>
</sect1>
</article>

109
en_US.ISO8859-1/articles/fbsd-from-scratch/article.xml
View file

@ -1,26 +1,21 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd" [
<!ENTITY scratch.ap "<application>FreeBSD From Scratch</application>">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd" [
<!ENTITY scratch.ap "<application xmlns='http://docbook.org/ns/docbook'>FreeBSD From Scratch</application>">
]>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>FreeBSD From Scratch</title>
<article xmlns:xi="http://www.w3.org/2001/XInclude" lang='en'>
<articleinfo>
<title>FreeBSD From Scratch</title>
<author>
<firstname>Jens</firstname>
<surname>Schweikhardt</surname>
<affiliation>
<author><personname><firstname>Jens</firstname><surname>Schweikhardt</surname></personname><affiliation>
<address><email>schweikh@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2002,2003,2004,2008</year>
<holder>Jens Schweikhardt</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.adobe;
&tm-attrib.general;
@ -38,16 +33,16 @@
think <command>make world</command> is a wonderful concept,
&scratch.ap; extends it to <command>make evenmore</command>.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>Have you ever upgraded your system with <command>make world</command>?
There is a problem if you have only one system on your disks. If
the <maketarget>installworld</maketarget> fails partway through,
the <buildtarget>installworld</buildtarget> fails partway through,
you are left with a broken system that might not even boot any
longer. Or maybe the <maketarget>installworld</maketarget> runs
longer. Or maybe the <buildtarget>installworld</buildtarget> runs
smoothly but the new kernel does not boot. Then it is time to
reach for the Fixit CD and dig for those backups you have taken
half a year ago.</para>
@ -61,7 +56,7 @@
If you think that this task should be automated as well, read on.</para>
</sect1>
<sect1 id="why">
<sect1 xml:id="why">
<title>Why would I (not) want &scratch.ap;?</title>
<para>This is a legitimate question. We have
@ -104,8 +99,8 @@
</itemizedlist>
<para>The well known way to build and install the world, as
described in <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html">the
Handbook</ulink>, by default replaces
described in <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html">the
Handbook</link>, by default replaces
the existing system. Only the kernel and modules are saved.
System binaries, headers and a lot of other files are overwritten;
obsolete files are still present and can cause surprises. If the
@ -148,8 +143,7 @@
you feel like an update is in order, you simply toggle the
partitions you want to wipe and reinstall.</para>
<para>Maybe you have heard of or even tried <ulink
url="http://www.linuxfromscratch.org/">Linux From Scratch</ulink>,
<para>Maybe you have heard of or even tried <link xlink:href="http://www.linuxfromscratch.org/">Linux From Scratch</link>,
or LFS for short. LFS also describes how to build and install a
system from scratch in empty partitions using a running system.
The focus in LFS seems to be to show the role of each system
@ -186,7 +180,7 @@
</itemizedlist>
</sect1>
<sect1 id="prerequisites">
<sect1 xml:id="prerequisites">
<title>Prerequisites</title>
<para>For going the &scratch.ap; way, you need to have:</para>
@ -224,7 +218,7 @@
</itemizedlist>
</sect1>
<sect1 id="stage1">
<sect1 xml:id="stage1">
<title>Stage One: System Installation</title>
<para>The first version of this article used a single shell script
@ -239,7 +233,7 @@
argument, like</para>
<informalexample>
<screen>&prompt.root; <userinput>./stage_1.sh <replaceable>default</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>./stage_1.sh default</userinput></screen>
</informalexample>
<para>will read its configuration from
@ -292,7 +286,7 @@
call, these binaries will die with <literal>SIGSYS, Bad
system call</literal>, because the old kernel does not have
that system call. I have seen other issues when I tried
building <filename role="package">lang/perl5.8</filename>.</para>
building <package>lang/perl5.8</package>.</para>
</listitem>
</itemizedlist>
@ -312,7 +306,7 @@
<listitem>
<para>successfully completed <command>make buildkernel
KERNCONF=<replaceable>whatever</replaceable></command></para>
KERNCONF=whatever</command></para>
</listitem>
</itemizedlist>
@ -376,16 +370,14 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput>
<para>The answer does not matter since <filename>stage_1.sh</filename> will
run &man.cap.mkdb.1; for you in any case.</para>
<para>Here is the author's <ulink
url="stage_1.conf.default"><filename>stage_1.conf.default</filename></ulink>,
<para>Here is the author's <link xlink:href="stage_1.conf.default"><filename>stage_1.conf.default</filename></link>,
which you need to modify substantially. The comments give you
enough information what to change.</para>
<programlisting><xi:include href="stage_1.conf.default" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_1.conf.default" parse="text"/></programlisting>
<para>Download <ulink
url="stage_1.conf.default"><filename>stage_1.conf.default</filename>
</ulink>.</para>
<para>Download <link xlink:href="stage_1.conf.default"><filename>stage_1.conf.default</filename>
</link>.</para>
<para>Running this script installs a system that when booted
provides:</para>
@ -414,7 +406,7 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput>
libraries and programs.</para>
</sect1>
<sect1 id="stage2">
<sect1 xml:id="stage2">
<title>Stage Two: Ports Installation</title>
<note>
@ -434,7 +426,7 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput>
with exactly one argument to denote a config file, e.g.</para>
<informalexample>
<screen>&prompt.root; <userinput>./stage_2.sh <replaceable>default</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>./stage_2.sh default</userinput></screen>
</informalexample>
<para>which will read the list of ports from
@ -454,14 +446,14 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput>
<para>In fact you can specify arbitrary shell commands, so you are
not restricted to simple <command>make</command> invocations:</para>
<programlisting>java jdk16 echo true > files/license.sh; make install BATCH=yes &lt; /dev/null
<programlisting>java jdk16 echo true &gt; files/license.sh; make install BATCH=yes &lt; /dev/null
print acroread8 yes accept | make install PAGER=ls
x11-fonts gnu-unifont make install &amp;&amp; mkfontdir /usr/local/lib/X11/fonts/local
news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install</programlisting>
<para>The first two lines are examples how you can handle ports
asking you to accept a licence. Note how the line for
<filename role="package">news/inn-stable</filename> is an example
<package>news/inn-stable</package> is an example
for a one-shot shell variable assignment to
<literal>CONFIGURE_ARGS</literal>. The port
<filename>Makefile</filename> will use this as an initial value
@ -485,13 +477,12 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews"
<filename>LOGDIR/category+port</filename> is created for each port
it actually installs.</para>
<programlisting><xi:include href="stage_2.conf.default" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_2.conf.default" parse="text"/></programlisting>
<para>Download <ulink
url="stage_2.conf.default"><filename>stage_2.conf.default</filename></ulink>.</para>
<para>Download <link xlink:href="stage_2.conf.default"><filename>stage_2.conf.default</filename></link>.</para>
</sect1>
<sect1 id="stage3">
<sect1 xml:id="stage3">
<title>Stage Three</title>
<para>You have installed your beloved ports during stage two. Some
@ -507,7 +498,7 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews"
what you want to configure simply by running:</para>
<informalexample>
<screen>&prompt.root; <userinput>make -f stage_3.mk <replaceable>target</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>make -f stage_3.mk target</userinput></screen>
</informalexample>
<para>As with <filename>stage_2.sh</filename> make sure you have
@ -516,7 +507,7 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews"
somewhere on the new system.</para>
</sect1>
<sect1 id="limitations">
<sect1 xml:id="limitations">
<title>Limitations</title>
<para>The automated installation of a port may prove difficult if it
@ -528,8 +519,8 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews"
make install</command>. For other ports you need to investigate
where exactly the interactive command is located and deal with it
appropriately. See the examples above for
<filename role="package">print/acroread8</filename> and
<filename role="package">java/jdk16</filename>.</para>
<package>print/acroread8</package> and
<package>java/jdk16</package>.</para>
<para>You should also be aware of upgrade issues for config files.
In general you do not know when and if the format or contents of a
@ -576,39 +567,33 @@ fi
</sect1>
<sect1 id="files">
<sect1 xml:id="files">
<title>The Files</title>
<para>Here are the three files you need beside the config files
already shown above.</para>
<para>This is the <ulink
url="stage_1.sh"><filename>stage_1.sh</filename></ulink>
<para>This is the <link xlink:href="stage_1.sh"><filename>stage_1.sh</filename></link>
script, which you should not need to modify.</para>
<programlisting><xi:include href="stage_1.sh" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_1.sh" parse="text"/></programlisting>
<para>Download <ulink
url="stage_1.sh"><filename>stage_1.sh</filename></ulink>.</para>
<para>Download <link xlink:href="stage_1.sh"><filename>stage_1.sh</filename></link>.</para>
<para>This is the <ulink
url="stage_2.sh"><filename>stage_2.sh</filename></ulink>
<para>This is the <link xlink:href="stage_2.sh"><filename>stage_2.sh</filename></link>
script. You may want to modify the variables at the
beginning.</para>
<programlisting><xi:include href="stage_2.sh" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_2.sh" parse="text"/></programlisting>
<para>Download <ulink
url="stage_2.sh"><filename>stage_2.sh</filename></ulink>.</para>
<para>Download <link xlink:href="stage_2.sh"><filename>stage_2.sh</filename></link>.</para>
<para>This is my <ulink
url="stage_3.mk"><filename>stage_3.mk</filename></ulink> to
<para>This is my <link xlink:href="stage_3.mk"><filename>stage_3.mk</filename></link> to
give you an idea how to automate all reconfiguration.</para>
<programlisting><xi:include href="stage_3.mk" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_3.mk" parse="text"/></programlisting>
<para>Download <ulink
url="stage_3.mk"><filename>stage_3.mk</filename></ulink>.</para>
<para>Download <link xlink:href="stage_3.mk"><filename>stage_3.mk</filename></link>.</para>
</sect1>
</article>

65
en_US.ISO8859-1/articles/filtering-bridges/article.xml
View file

@ -1,22 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Filtering Bridges</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Filtering Bridges</title>
<authorgroup>
<author>
<firstname>Alex</firstname>
<surname>Dupre</surname>
<affiliation>
<author><personname><firstname>Alex</firstname><surname>Dupre</surname></personname><affiliation>
<address><email>ale@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.3com;
&tm-attrib.intel;
@ -41,9 +36,9 @@
segments. Under many points of view a bridge is similar to an Ethernet
switch with only two ports.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="filtering-bridges-why">
<sect1 xml:id="filtering-bridges-why">
<title>Why use a filtering bridge?</title>
<para>More and more frequently, thanks to the lowering costs of broad band
@ -63,7 +58,7 @@
issues.</para>
</sect1>
<sect1 id="filtering-bridges-how">
<sect1 xml:id="filtering-bridges-how">
<title>How to Install</title>
<para>Adding bridge functionalities to a FreeBSD system is not difficult.
@ -89,7 +84,7 @@
which interface is connected to the router and which to the inner
network.</para>
<sect2 id="filtering-bridges-kernel">
<sect2 xml:id="filtering-bridges-kernel">
<title>Kernel Configuration</title>
<para>So you have decided to use the older but well tested installation
@ -105,13 +100,12 @@ options IPFIREWALL_VERBOSE</programlisting>
firewall.</para>
<para>Now it is necessary to build and install the new kernel. You may
find detailed instructions in the <ulink
url="&url.books.handbook;/kernelconfig-building.html">Building
and Installing a Custom Kernel</ulink> section of the FreeBSD
find detailed instructions in the <link xlink:href="&url.books.handbook;/kernelconfig-building.html">Building
and Installing a Custom Kernel</link> section of the FreeBSD
Handbook.</para>
</sect2>
<sect2 id="filtering-bridges-modules">
<sect2 xml:id="filtering-bridges-modules">
<title>Modules Loading</title>
<para>If you have chosen to use the new and simpler installation
@ -129,7 +123,7 @@ options IPFIREWALL_VERBOSE</programlisting>
</sect2>
</sect1>
<sect1 id="filtering-bridges-finalprep">
<sect1 xml:id="filtering-bridges-finalprep">
<title>Final Preparation</title>
<para>Before rebooting in order to load the new kernel or the required
@ -164,9 +158,9 @@ firewall_logging="YES"</programlisting>
assign an IP to the external interface (the one connected to Internet,
where <acronym>DNS</acronym> server resides), since the bridge will be
activated at the end of the startup procedure. It means that the
<devicename>fxp0</devicename> interface (in our case) must be mentioned
<filename>fxp0</filename> interface (in our case) must be mentioned
in the ifconfig section of the <filename>/etc/rc.conf</filename> file,
while the <devicename>xl0</devicename> is not. Assigning an IP to both
while the <filename>xl0</filename> is not. Assigning an IP to both
the network cards does not make much sense, unless, during the start
procedure, applications should access to services on both Ethernet
segments.</para>
@ -193,13 +187,13 @@ firewall_logging="YES"</programlisting>
before proceeding.</para>
</sect1>
<sect1 id="filtering-bridges-enabling">
<sect1 xml:id="filtering-bridges-enabling">
<title>Enabling the Bridge</title>
<para>At this point, to enable the bridge, you have to execute the
following commands (having the shrewdness to replace the names of the
two network interfaces <devicename>fxp0</devicename> and
<devicename>xl0</devicename> with your own ones):</para>
two network interfaces <filename>fxp0</filename> and
<filename>xl0</filename> with your own ones):</para>
<screen>&prompt.root; <userinput>sysctl net.link.ether.bridge.config=fxp0:0,xl0:0</userinput>
&prompt.root; <userinput>sysctl net.link.ether.bridge.ipfw=1</userinput>
@ -217,12 +211,12 @@ firewall_logging="YES"</programlisting>
<para>At this point you should be able to insert the machine between two
sets of hosts without compromising any communication abilities between
them. If so, the next step is to add the
<literal>net.link.ether.bridge.<replaceable>[blah]</replaceable>=<replaceable>[blah]</replaceable></literal>
<literal>net.link.ether.bridge.[blah]=[blah]</literal>
portions of these rows to the <filename>/etc/sysctl.conf</filename>
file, in order to have them execute at startup.</para>
</sect1>
<sect1 id="filtering-bridges-ipfirewall">
<sect1 xml:id="filtering-bridges-ipfirewall">
<title>Configuring The Firewall</title>
<para>Now it is time to create your own file with custom firewall rules,
@ -257,7 +251,7 @@ firewall_logging="YES"</programlisting>
<para>Let's look at an example setup. Note first that at the top of
<filename>/etc/rc.firewall</filename> there are already standard rules
for the loopback interface <devicename>lo0</devicename>, so we should not
for the loopback interface <filename>lo0</filename>, so we should not
have to care for them anymore. Custom rules should be put in a separate
file (say <filename>/etc/rc.firewall.local</filename>) and loaded at
system startup, by modifying the row of
@ -272,11 +266,10 @@ firewall_logging="YES"</programlisting>
network.</para>
</important>
<para>For our example imagine to have the <devicename>fxp0</devicename>
<para>For our example imagine to have the <filename>fxp0</filename>
interface connected towards the outside (Internet) and the
<devicename>xl0</devicename> towards the inside
(<acronym>LAN</acronym>). The bridge machine has the IP <hostid
role="ipaddr">1.2.3.4</hostid> (it is not possible that your
<filename>xl0</filename> towards the inside
(<acronym>LAN</acronym>). The bridge machine has the IP <systemitem class="ipaddress">1.2.3.4</systemitem> (it is not possible that your
<acronym>ISP</acronym> can give you an address quite like this, but for
our example it is good).</para>
@ -374,13 +367,13 @@ add drop log all from any to any</programlisting>
packet filter. The inside net will go through the bridge, while the
local machine will use the normal IP stack to speak. Thus the two rules
to handle the different cases. The <literal>in via
<devicename>fxp0</devicename></literal> rules work for both paths. In general, if
fxp0</literal> rules work for both paths. In general, if
you use <option>in via</option> rules throughout the filter, you will need to make an
exception for locally generated packets, because they did not come in
via any of our interfaces.</para>
</sect1>
<sect1 id="filtering-bridges-contributors">
<sect1 xml:id="filtering-bridges-contributors">
<title>Contributors</title>
<para>Many parts of this article have been taken, updated and adapted from

97
en_US.ISO8859-1/articles/fonts/article.xml
View file

@ -1,10 +1,8 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<!-- Recently, I wanted to figure out how to use some additional fonts that
I had accumulated. I finally figured out *how to do it* from the various
manual pages and documentation. Since it might be of use to other users,
@ -21,37 +19,29 @@
it is pretty raw. There are probably better ways to do some of this stuff,
and I would welcome being corrected.
-->
<!-- The section "Setting a virtual console to 80x60 line mode" was
updated to reflect changes in FreeBSD system configuration
files by Mark Ovens <mark@ukug.uk.FreeBSD.org> 27/5/00
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Fonts and FreeBSD</title><subtitle>A Tutorial</subtitle>
<article lang='en'>
<articleinfo>
<title>Fonts and FreeBSD</title>
<subtitle>A Tutorial</subtitle>
<authorgroup>
<author>
<firstname>Dave</firstname>
<surname>Bodenstab</surname>
<affiliation>
<author><personname><firstname>Dave</firstname><surname>Bodenstab</surname></personname><affiliation>
<address>
<email>imdave@synet.net</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<pubdate>Wed Aug 7, 1996</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.adobe;
&tm-attrib.apple;
@ -69,9 +59,9 @@
for switching the syscons display to 80x60 mode, and for using
type 1 fonts with the above application programs.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>There are many sources of fonts available, and one might ask
@ -82,7 +72,7 @@
might be interested.</para>
</sect1>
<sect1 id="terminology">
<sect1 xml:id="terminology">
<title>Basic terminology</title>
<para>There are many different font formats and associated font
@ -151,7 +141,7 @@
this font format with FreeBSD.</para>
</sect1>
<sect1 id="font-formats">
<sect1 xml:id="font-formats">
<title>What font formats can I use?</title>
<para>Which font file format is useful depends on the application
@ -234,7 +224,7 @@
other than those provided with FreeBSD.</para>
</sect1>
<sect1 id="virtual-console">
<sect1 xml:id="virtual-console">
<title>Setting a virtual console to 80x60 line mode</title>
<para>First, an 8x8 font must be loaded. To do this,
@ -272,7 +262,7 @@
<para>References: &man.rc.conf.5;, &man.vidcontrol.1;.</para>
</sect1>
<sect1 id="type1-fonts-x11">
<sect1 xml:id="type1-fonts-x11">
<title>Using type 1 fonts with <application>X11</application></title>
<para><application>X11</application> can use either the <filename>.pfa</filename> or the
@ -398,9 +388,7 @@ end readonly def
<term>Slant</term>
<listitem>
<para><emphasis remap="bf">r</emphasis>oman, <emphasis
remap="bf">i</emphasis>talic, <emphasis
remap="bf">o</emphasis>blique, etc. Since the
<para><emphasis remap="bf">r</emphasis>oman, <emphasis remap="bf">i</emphasis>talic, <emphasis remap="bf">o</emphasis>blique, etc. Since the
<emphasis>ItalicAngle</emphasis> is zero,
<emphasis>roman</emphasis> will be used.</para>
</listitem>
@ -472,7 +460,7 @@ showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
.
:wq</userinput>
<lineannotation><filename>fonts.scale</filename> seems to be identical to <filename>fonts.dir</filename>&hellip;</lineannotation>
<lineannotation>fonts.scale seems to be identical to fonts.dir&hellip;</lineannotation>
&prompt.user; <userinput>cp fonts.dir fonts.scale</userinput>
<lineannotation>Tell X11 that things have changed</lineannotation>
@ -483,12 +471,11 @@ showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
</informalexample>
<para>References: &man.xfontsel.1;, &man.xset.1;, <citetitle>The X
Windows System in a Nutshell</citetitle>, <ulink
url="http://www.ora.com/">O'Reilly &amp;
Associates</ulink>.</para>
Windows System in a Nutshell</citetitle>, <link xlink:href="http://www.ora.com/">O'Reilly &amp;
Associates</link>.</para>
</sect1>
<sect1 id="type1-fonts-ghostscript">
<sect1 xml:id="type1-fonts-ghostscript">
<title>Using type 1 fonts with Ghostscript</title>
<para><application>Ghostscript</application> references a font via its <filename>Fontmap</filename>
@ -532,7 +519,7 @@ GS&gt;<userinput>quit</userinput></screen>
<application>Ghostscript 4.01</application> distribution</para>
</sect1>
<sect1 id="type1-fonts-groff">
<sect1 xml:id="type1-fonts-groff">
<title>Using type 1 fonts with Groff</title>
<para>Now that the new font can be used by both <application>X11</application> and
@ -566,7 +553,7 @@ GS&gt;<userinput>quit</userinput></screen>
example:</para>
<informalexample>
<screen><lineannotation>Many <filename>.afm</filename> files are in Mac format&hellip; ^M delimited lines
<screen><lineannotation>Many .afm files are in Mac format&hellip; ^M delimited lines
We need to convert them to &unix; style ^J delimited lines</lineannotation>
&prompt.user; <userinput>cd /tmp</userinput>
&prompt.user; <userinput>cat /usr/local/share/fonts/type1/showboat.afm |
@ -594,7 +581,7 @@ We need to convert them to &unix; style ^J delimited lines</lineannotation>
the groff font file as illustrated:</para>
<informalexample>
<screen><lineannotation>Create the <filename>.pfa</filename> font file</lineannotation>
<screen><lineannotation>Create the .pfa font file</lineannotation>
&prompt.user; <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb &gt;showboat.pfa</userinput></screen>
</informalexample>
@ -658,7 +645,7 @@ EOF</userinput>
&man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;.</para>
</sect1>
<sect1 id="convert-truetype">
<sect1 xml:id="convert-truetype">
<title>Converting TrueType fonts to a groff/PostScript format for
groff</title>
@ -675,8 +662,7 @@ EOF</userinput>
allows conversion of a TrueType font to an ascii font
metric (<filename>.afm</filename>) file.</para>
<para>Currently available at <ulink
url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/"></ulink>.
<para>Currently available at <uri xlink:href="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/</uri>.
Note: These files are PostScript programs and must be
downloaded to disk by holding down the
<keycap>Shift</keycap> key when clicking on the link.
@ -752,7 +738,7 @@ EOF</userinput>
<para>Create the <filename>.afm</filename> file by
typing:</para>
<screen><prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput>
<screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name</userinput>
</screen>
<para>Where, <replaceable>TTF_name</replaceable> is your
@ -806,7 +792,7 @@ Converting 3of9.ttf to A.pfa and B.afm.
directory.)</para>
<screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \
generate/textmap <replaceable>PS_font_name</replaceable></userinput>
generate/textmap PS_font_name</userinput>
</screen>
<para>Where, <filename>file.afm</filename> is the
@ -841,7 +827,7 @@ Converting 3of9.ttf to A.pfa and B.afm.
</orderedlist>
</sect1>
<sect1 id="truetype-for-other-programs">
<sect1 xml:id="truetype-for-other-programs">
<title>Can TrueType fonts be used with other programs?</title>
<para>The TrueType font format is used by Windows, Windows 95, and
@ -857,8 +843,7 @@ Converting 3of9.ttf to A.pfa and B.afm.
fonts, but I rather doubt many people will be creating documents
as a series of raytraced pages :-).</para>
<para>This rather dismal situation may soon change. The <ulink
url="http://www.freetype.org/">FreeType Project</ulink> is
<para>This rather dismal situation may soon change. The <link xlink:href="http://www.freetype.org/">FreeType Project</link> is
currently developing a useful set of FreeType tools:</para>
<itemizedlist>
@ -867,26 +852,22 @@ Converting 3of9.ttf to A.pfa and B.afm.
<para>The <command>xfsft</command> font server for <application>X11</application> can
serve TrueType fonts in addition to regular fonts. Though
currently in beta, it is said to be quite usable. See
<ulink
url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz
Chroboczek's page</ulink> for further information.
Porting instructions for FreeBSD can be found at <ulink
url="http://math.missouri.edu/~stephen/software/">Stephen
Montgomery's software page</ulink>.</para>
<link xlink:href="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz
Chroboczek's page</link> for further information.
Porting instructions for FreeBSD can be found at <link xlink:href="http://math.missouri.edu/~stephen/software/">Stephen
Montgomery's software page</link>.</para>
</listitem>
<listitem>
<para><application>xfstt</application> is another font server for
<application>X11</application>,
available under <ulink url="
ftp://sunsite.unc.edu/pub/Linux/X11/fonts/"></ulink>.</para>
available under <uri xlink:href=" ftp://sunsite.unc.edu/pub/Linux/X11/fonts/"> ftp://sunsite.unc.edu/pub/Linux/X11/fonts/</uri>.</para>
</listitem>
<listitem>
<para>A program called <command>ttf2bdf</command> can produce
BDF files suitable for use in an X environment from TrueType
files. Linux binaries are said to be available from <ulink
url="ftp://crl.nmsu.edu/CLR/multiling/General/"></ulink>.</para>
files. Linux binaries are said to be available from <uri xlink:href="ftp://crl.nmsu.edu/CLR/multiling/General/">ftp://crl.nmsu.edu/CLR/multiling/General/</uri>.</para>
</listitem>
<listitem>
@ -895,7 +876,7 @@ Converting 3of9.ttf to A.pfa and B.afm.
</itemizedlist>
</sect1>
<sect1 id="obtaining-additional-fonts">
<sect1 xml:id="obtaining-additional-fonts">
<title>Where can additional fonts be obtained?</title>
<para>Many fonts are available on the Internet. They are either
@ -905,11 +886,11 @@ Converting 3of9.ttf to A.pfa and B.afm.
<itemizedlist>
<listitem>
<para><ulink url="http://www.simtel.net/"></ulink></para>
<para><uri xlink:href="http://www.simtel.net/">http://www.simtel.net/</uri></para>
</listitem>
<listitem>
<para><ulink url="http://www.freshmeat.net/"></ulink></para>
<para><uri xlink:href="http://www.freshmeat.net/">http://www.freshmeat.net/</uri></para>
</listitem>
<listitem>
@ -919,7 +900,7 @@ Converting 3of9.ttf to A.pfa and B.afm.
</itemizedlist>
</sect1>
<sect1 id="additional-questions">
<sect1 xml:id="additional-questions">
<title>Additional questions</title>
<itemizedlist>

72
en_US.ISO8859-1/articles/freebsd-questions/article.xml
View file

@ -1,22 +1,16 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>How to get best results from the FreeBSD-questions mailing
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>How to get best results from the FreeBSD-questions mailing
list</title>
<author>
<firstname>Greg</firstname>
<surname>Lehey</surname>
<affiliation>
<author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation>
<address><email>grog@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.microsoft;
&tm-attrib.opengroup;
@ -37,10 +31,10 @@
<para>This document is regularly posted to the FreeBSD-questions mailing
list.</para>
</abstract>
</articleinfo>
</info>
<sect1>
<title id="Introduction">Introduction</title>
<title xml:id="Introduction">Introduction</title>
<para><literal>FreeBSD-questions</literal> is a mailing list maintained by
the FreeBSD project to help people who have questions about the normal
@ -54,9 +48,8 @@
activity is <quote>cracker</quote>, but the popular press has not found
out yet. The FreeBSD hackers disapprove strongly of cracking
security, and have nothing to do with it. For a longer description of
hackers, see Eric Raymond's <ulink
url="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become
A Hacker</ulink></para>
hackers, see Eric Raymond's <link xlink:href="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become
A Hacker</link></para>
</note>
<para>This is a regular posting aimed to help both those seeking advice
@ -78,10 +71,10 @@
</sect1>
<sect1>
<title id="subscribe">How to subscribe to FreeBSD-questions</title>
<title xml:id="subscribe">How to subscribe to FreeBSD-questions</title>
<para>FreeBSD-questions is a mailing list, so you need mail access. Point
your WWW browser to the <ulink url="&a.questions.url;">information page of the FreeBSD-questions mailing list</ulink>.
your WWW browser to the <link xlink:href="&a.questions.url;">information page of the FreeBSD-questions mailing list</link>.
In the section titled <quote>Subscribing to freebsd-questions</quote> fill
in the <quote>Your email address</quote> field; the other fields are optional.
</para>
@ -105,7 +98,7 @@
</sect1>
<sect1>
<title id="unsubscribe">How to unsubscribe from FreeBSD-questions</title>
<title xml:id="unsubscribe">How to unsubscribe from FreeBSD-questions</title>
<para>When you subscribed to FreeBSD-questions, you got a welcome message
from <application>mailman</application>. In this message, amongst
@ -163,7 +156,7 @@ your options page that will email your current password to you.</literallayout>
</sect1>
<sect1>
<title id="askwho">Should I ask <literal>-questions</literal> or
<title xml:id="askwho">Should I ask <literal>-questions</literal> or
<literal>-hackers</literal>?</title>
<para>Two mailing lists handle general questions about FreeBSD,
@ -211,7 +204,7 @@ your options page that will email your current password to you.</literallayout>
</sect1>
<sect1>
<title id="before">Before submitting a question</title>
<title xml:id="before">Before submitting a question</title>
<para>You can (and should) do some things yourself before asking a question
on one of the mailing lists:</para>
@ -230,9 +223,9 @@ your options page that will email your current password to you.</literallayout>
<listitem>
<para>Read the manual pages, and the FreeBSD documentation (either
installed in <filename>/usr/doc</filename> or accessible via WWW at
<ulink url="http://www.FreeBSD.org"></ulink>), especially the
<ulink url="&url.books.handbook;/index.html">handbook</ulink>
and the <ulink url="&url.books.faq;/index.html">FAQ</ulink>.
<uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>), especially the
<link xlink:href="&url.books.handbook;/index.html">handbook</link>
and the <link xlink:href="&url.books.faq;/index.html">FAQ</link>.
</para>
</listitem>
@ -240,25 +233,24 @@ your options page that will email your current password to you.</literallayout>
<para>Browse and/or search the archives for the mailing list, to see if your
question or a similar one has been asked (and possibly answered) on the
list. You can browse and/or search the mailing list archives
at <ulink url="http://www.FreeBSD.org/mail"></ulink>
and <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink>
at <uri xlink:href="http://www.FreeBSD.org/mail">http://www.FreeBSD.org/mail</uri>
and <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
respectively. This can be done at other WWW sites as well, for example
at <ulink url="http://marc.theaimsgroup.com"></ulink>.
at <uri xlink:href="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com</uri>.
</para>
</listitem>
<listitem>
<para>Use a search engine such as <ulink url="http://www.google.com">Google</ulink>
or <ulink url="http://www.yahoo.com">Yahoo</ulink> to find answers to your question.
Google even has a <ulink
url="http://www.google.com/bsd">BSD-specific search interface</ulink>.
<para>Use a search engine such as <link xlink:href="http://www.google.com">Google</link>
or <link xlink:href="http://www.yahoo.com">Yahoo</link> to find answers to your question.
Google even has a <link xlink:href="http://www.google.com/bsd">BSD-specific search interface</link>.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title id="submit">How to submit a question</title>
<title xml:id="submit">How to submit a question</title>
<para>When submitting a question to FreeBSD-questions, consider the
following points:</para>
@ -301,8 +293,8 @@ your options page that will email your current password to you.</literallayout>
errors, it will give people a poor impression of you.</para>
<para>A lot of badly formatted messages come from
<ulink url="http://www.lemis.com/email.html">bad mailers or badly
configured mailers</ulink>. The following mailers are known to
<link xlink:href="http://www.lemis.com/email.html">bad mailers or badly
configured mailers</link>. The following mailers are known to
send out badly formatted messages without you finding out about
them:</para>
@ -459,7 +451,7 @@ fine, but when I try to reboot the system, I get the message
</sect1>
<sect1>
<title id="followup">How to follow up to a question</title>
<title xml:id="followup">How to follow up to a question</title>
<para>Often you will want to send in additional information to a question
you have already sent. The best way to do this is to reply to your
@ -481,7 +473,7 @@ fine, but when I try to reboot the system, I get the message
<listitem>
<para>The message reference numbers in the header will refer to the
previous message. Some mailers, such as
<ulink url="http://www.mutt.org/">mutt</ulink>, can
<link xlink:href="http://www.mutt.org/">mutt</link>, can
<emphasis>thread</emphasis> messages, showing the exact
relationships between the messages.</para>
</listitem>
@ -489,7 +481,7 @@ fine, but when I try to reboot the system, I get the message
</sect1>
<sect1>
<title id="answer">How to answer a question</title>
<title xml:id="answer">How to answer a question</title>
<para>Before you answer a question to FreeBSD-questions, consider:</para>

141
en_US.ISO8859-1/articles/freebsd-update-server/article.xml
View file

@ -1,20 +1,15 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd" [
<!ENTITY fbus.ap "<application>FreeBSD Update Server</application>">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd" [
<!ENTITY fbus.ap "<application xmlns='http://docbook.org/ns/docbook'>FreeBSD Update Server</application>">
]>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Build Your Own &os; Update Server</title>
<article lang="en">
<articleinfo>
<title>Build Your Own &os; Update Server</title>
<author>
<firstname>Jason</firstname>
<surname>Helfman</surname>
<affiliation>
<author><personname><firstname>Jason</firstname><surname>Helfman</surname></personname><affiliation>
<address>&a.jgh.email;</address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2009</year>
@ -24,7 +19,7 @@
<holder role="mailto:jgh@FreeBSD.org">Jason Helfman</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
&tm-attrib.intel;
@ -37,8 +32,7 @@
<abstract>
<para>This article describes building an internal &fbus.ap;.
The <ulink
url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink>
The <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</link>
is written by &a.cperciva.email;, Security Officer Emeritus of &os;.
For users that think it is convenient to update their systems
against an official update server, building their own &fbus.ap; may
@ -46,16 +40,15 @@
&os; releases or by providing a local mirror that will allow faster
updates for a number of machines.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="acknowledgments">
<sect1 xml:id="acknowledgments">
<title>Acknowledgments</title>
<para>This article was subsequently printed at <ulink
url="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD
Magazine</ulink>.</para>
<para>This article was subsequently printed at <link xlink:href="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD
Magazine</link>.</para>
</sect1>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>Experienced users or administrators are often responsible for
@ -69,7 +62,7 @@
&fbus.ap;.</para>
</sect1>
<sect1 id="prerequisites">
<sect1 xml:id="prerequisites">
<title>Prerequisites</title>
<para>To build an internal &fbus.ap; some requirements should be
@ -98,8 +91,7 @@
</listitem>
<listitem>
<para>A web server, like <ulink
url="&url.books.handbook;/network-apache.html">Apache</ulink>,
<para>A web server, like <link xlink:href="&url.books.handbook;/network-apache.html">Apache</link>,
with over half of the space required for the build. For instance,
test builds for 7.1 and 7.2 consume a total amount of 4&nbsp;GB,
and the webserver space needed to distribute these updates is
@ -113,13 +105,11 @@
</itemizedlist>
</sect1>
<sect1 id="Configuration">
<sect1 xml:id="Configuration">
<title>Configuration: Installation &amp; Setup</title>
<para>Download the <ulink
url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">
freebsd-update-server</ulink> software by installing <filename
role="package">devel/subversion </filename>, and execute:</para>
<para>Download the <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">
freebsd-update-server</link> software by installing <package>devel/subversion </package>, and execute:</para>
<screen>&prompt.user; <userinput>svn co http://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server</userinput></screen>
@ -137,22 +127,22 @@
# the scripts tree.
# Location from which to fetch releases
export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co id="ftp-id"/>
export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co xml:id="ftp-id"/>
# Host platform
export HOSTPLATFORM=`uname -m`
# Host name to use inside jails
export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co id="buildhost-id"/>
export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co xml:id="buildhost-id"/>
# Location of SSH key
export SSHKEY=/root/.ssh/id_dsa<co id="sshkey-id"/>
export SSHKEY=/root/.ssh/id_dsa<co xml:id="sshkey-id"/>
# SSH account into which files are uploaded
MASTERACCT=builder@wadham.daemonology.net<co id="mstacct-id"/>
MASTERACCT=builder@wadham.daemonology.net<co xml:id="mstacct-id"/>
# Directory into which files are uploaded
MASTERDIR=update-master.freebsd.org<co id="mstdir-id"/></programlisting>
MASTERDIR=update-master.freebsd.org<co xml:id="mstdir-id"/></programlisting>
</informalexample>
<para>Parameters for consideration would be:</para>
@ -228,7 +218,7 @@ MASTERDIR=update-master.freebsd.org<co id="mstdir-id"/></programlisting>
<informalexample>
<programlisting># SHA256 hash of RELEASE disc1.iso image.
export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co id="sha256-id"/>
export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co xml:id="sha256-id"/>
# Components of the world, source, and kernels
export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
@ -238,22 +228,20 @@ export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5 \
export KERNELPARTS="generic"
# EOL date
export EOL=1275289200<co id="eol-id"/></programlisting>
export EOL=1275289200<co xml:id="eol-id"/></programlisting>
</informalexample>
<calloutlist>
<callout arearefs="sha256-id">
<para>The &man.sha256.1; hash key for the desired release, is
published within the respective <ulink
url="&url.base;/releases/">release announcement</ulink>.</para>
published within the respective <link xlink:href="&url.base;/releases/">release announcement</link>.</para>
</callout>
<callout arearefs="eol-id">
<para>To generate the "End of Life" number for
<filename>build.conf</filename>, refer to the "Estimated
EOL" posted on the <ulink
url="&url.base;/security/security.html">&os;
Security Website</ulink>. The value
EOL" posted on the <link xlink:href="&url.base;/security/security.html">&os;
Security Website</link>. The value
of <literal>EOL</literal> can be derived from the date listed on
the web site, using the &man.date.1; utility, for example:</para>
<screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
@ -263,7 +251,7 @@ export EOL=1275289200<co id="eol-id"/></programlisting>
</procedure>
</sect1>
<sect1 id="build">
<sect1 xml:id="build">
<title>Building Update Code</title>
<para>The first step is to run <filename>scripts/make.sh</filename>.
@ -301,7 +289,7 @@ Verifying - enter aes-256-cbc encryption password:</screen>
<informalexample>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
&prompt.root; <userinput>sh scripts/init.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen>
&prompt.root; <userinput>sh scripts/init.sh amd64 7.2-RELEASE</userinput></screen>
</informalexample>
<para>What follows is a sample of an <emphasis>initial</emphasis> build
@ -353,8 +341,7 @@ world|base|/usr/lib/libalias_ftp.a
<warning>
<para>During this second build cycle, the network time protocol
daemon, &man.ntpd.8;, is turned off. Per &a.cperciva.email;,
Security Officer Emeritus of &os;, "the <ulink
url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink>
Security Officer Emeritus of &os;, "the <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</link>
build code needs to identify timestamps which are stored in files so
that they can be ignored when comparing builds to determine which
files need to be updated. This timestamp-finding works by doing two
@ -454,7 +441,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
<informalexample>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen>
&prompt.root; <userinput>sh scripts/upload.sh amd64 7.2-RELEASE</userinput></screen>
</informalexample>
<note>
@ -464,8 +451,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
<emphasis>uploaded</emphasis> file.</para>
<informalexample>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server/pub/<replaceable>7.2-RELEASE/amd64</replaceable></userinput>
&prompt.root; <userinput>touch -t <replaceable>200801010101.01</replaceable> uploaded</userinput></screen>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server/pub/7.2-RELEASE/amd64</userinput>
&prompt.root; <userinput>touch -t 200801010101.01 uploaded</userinput></screen>
</informalexample>
</note>
@ -477,9 +464,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
document root of the webserver in order for updates
to be distributed. The exact configuration will vary depending on the
web server used. For the <application>Apache</application> web server,
please refer to the <ulink
url="&url.books.handbook;/network-apache.html">Configuration of
Apache servers</ulink> section in the Handbook.</para>
please refer to the <link xlink:href="&url.books.handbook;/network-apache.html">Configuration of
Apache servers</link> section in the Handbook.</para>
<!-- This note seems either out of place. I find it hard to read and it
is a bit difficult to understand why it is related to the rest of
@ -504,9 +490,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
<para>Update client's <literal>KeyPrint</literal> and
<literal>ServerName</literal> in
<filename>/etc/freebsd-update.conf</filename>, and perform updates as
instructed in the <ulink
url="&url.books.handbook;/updating-upgrading-freebsdupdate.html">&os;
Update</ulink>
instructed in the <link xlink:href="&url.books.handbook;/updating-upgrading-freebsdupdate.html">&os;
Update</link>
<!-- One sentence, two instances of 'in'. We can probably reword this
part to avoid repetition. -->
<!-- What about "place client's new keyprint and servername values to
@ -525,17 +510,15 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
and uploaded to your distribution server for both versions.</para>
</important>
<para>For reference, the entire run of <ulink
url="init.txt"><filename>init.sh</filename></ulink> is
<para>For reference, the entire run of <link xlink:href="init.txt"><filename>init.sh</filename></link> is
attached.</para>
</sect1>
<sect1 id="patch">
<sect1 xml:id="patch">
<title>Building a Patch</title>
<para>Every time a <ulink
url="&url.base;/security/advisories.html">security advisory</ulink>
or <ulink url="&url.base;/security/notices.html">security notice</ulink>
<para>Every time a <link xlink:href="&url.base;/security/advisories.html">security advisory</link>
or <link xlink:href="&url.base;/security/notices.html">security notice</link>
is announced, a patch update can be built.</para>
<para>For this example, 7.1-RELEASE will be used.</para>
@ -555,8 +538,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
</itemizedlist>
<para>Create the patch directory of the respective release
under <filename
class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para>
under <filename>/usr/local/freebsd-update-server/patches/</filename>.</para>
<informalexample>
<screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/</userinput>
@ -564,14 +546,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
</informalexample>
<para>As an example, take the patch for &man.named.8;. Read the advisory,
and grab the necessary file from <ulink
url="&url.base;/security/advisories.html">&os; Security
Advisories</ulink>. More information on interpreting the advisory,
can be found in the <ulink
url="&url.books.handbook;/security-advisories.html">&os; Handbook</ulink>.</para>
and grab the necessary file from <link xlink:href="&url.base;/security/advisories.html">&os; Security
Advisories</link>. More information on interpreting the advisory,
can be found in the <link xlink:href="&url.books.handbook;/security-advisories.html">&os; Handbook</link>.</para>
<para>In the <ulink
url="http://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc">security brief</ulink>,
<para>In the <link xlink:href="http://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc">security brief</link>,
this advisory is called <literal>SA-09:12.bind</literal>. After
downloading the file, it is required to rename the file to an
appropriate patch level. It is suggested to keep this consistent with
@ -605,7 +584,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
<informalexample>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
&prompt.root; <userinput>sh scripts/diff.sh <replaceable>amd64 7.1-RELEASE 7</replaceable></userinput></screen>
&prompt.root; <userinput>sh scripts/diff.sh amd64 7.1-RELEASE 7</userinput></screen>
</informalexample>
<para>What follows is a sample of a <emphasis>differential</emphasis>
@ -722,15 +701,15 @@ the new builds.</screen>
<informalexample>
<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.1-RELEASE</replaceable></userinput></screen>
&prompt.root; <userinput>sh scripts/upload.sh amd64 7.1-RELEASE</userinput></screen>
</informalexample>
<para>For reference, the entire run of
<ulink url="diff.txt"><filename>diff.sh</filename></ulink> is
<link xlink:href="diff.txt"><filename>diff.sh</filename></link> is
attached.</para>
</sect1>
<sect1 id="tips">
<sect1 xml:id="tips">
<title>Tips</title>
<!-- These are nice tips, but there are only a few of them and they need a
@ -753,8 +732,7 @@ the new builds.</screen>
<itemizedlist>
<listitem>
<para>If a custom release is built using the native
<command>make release</command> <ulink
url="&url.articles.releng;/release-build.html">procedure</ulink>,
<command>make release</command> <link xlink:href="&url.articles.releng;/release-build.html">procedure</link>,
<application>freebsd-update-server</application> code will work
from your release. As an example, a release without ports or
documentation can be built by clearing functionality pertaining
@ -779,8 +757,8 @@ the new builds.</screen>
</listitem>
<listitem>
<para>Adding <option>-j <replaceable>NUMBER</replaceable></option>
flags to <maketarget>buildworld</maketarget> and
<maketarget>obj</maketarget> targets in the
flags to <buildtarget>buildworld</buildtarget> and
<buildtarget>obj</buildtarget> targets in the
<filename>scripts/build.subr</filename> script may speed up
processing depending on the hardware used, however it is not
necessary. Using these flags in other targets is not
@ -789,18 +767,17 @@ the new builds.</screen>
<screen> # Build the world
log "Building world"
cd /usr/src &amp;&amp;
make -j 2 ${COMPATFLAGS} buildworld 2>&amp;1
make -j 2 ${COMPATFLAGS} buildworld 2&gt;&amp;1
# Distribute the world
log "Distributing world"
cd /usr/src/release &amp;&amp;
make -j 2 obj &amp;&amp;
make ${COMPATFLAGS} release.1 release.2 2>&amp;1</screen>
make ${COMPATFLAGS} release.1 release.2 2&gt;&amp;1</screen>
</listitem>
<listitem>
<para>Create an appropriate <ulink
url="&url.books.handbook;/network-dns.html">DNS</ulink>
<para>Create an appropriate <link xlink:href="&url.books.handbook;/network-dns.html">DNS</link>
SRV record for the update server, and put others behind it with
variable weights. Using this facility will provide update
mirrors, however this tip is not necessary unless you wish to

112
en_US.ISO8859-1/articles/geom-class/article.xml
View file

@ -1,23 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<title>Writing a GEOM Class</title>
<articleinfo>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Writing a GEOM Class</title>
<authorgroup>
<author>
<firstname>Ivan</firstname>
<surname>Voras</surname>
<affiliation>
<author><personname><firstname>Ivan</firstname><surname>Voras</surname></personname><affiliation>
<address><email>ivoras@FreeBSD.org</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.general;
@ -35,13 +30,13 @@
</abstract>
</articleinfo>
</info>
<!-- Introduction -->
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<sect2 id="intro-docs">
<sect2 xml:id="intro-docs">
<title>Documentation</title>
<para>Documentation on kernel programming is scarce &mdash; it is one of
@ -53,30 +48,25 @@
<itemizedlist>
<listitem><para>The <ulink
url="&url.books.developers-handbook;/index.html">FreeBSD
Developer's Handbook</ulink> &mdash; part of the documentation
<listitem><para>The <link xlink:href="&url.books.developers-handbook;/index.html">FreeBSD
Developer's Handbook</link> &mdash; part of the documentation
project, it does not contain anything specific to kernel
programming, but rather some general useful information.</para></listitem>
<listitem><para>The <ulink
url="&url.books.arch-handbook;/index.html">FreeBSD
Architecture Handbook</ulink> &mdash; also from the documentation
<listitem><para>The <link xlink:href="&url.books.arch-handbook;/index.html">FreeBSD
Architecture Handbook</link> &mdash; also from the documentation
project, contains descriptions of several low-level facilities
and procedures. The most important chapter is 13, <ulink
url="&url.books.arch-handbook;/driverbasics.html">Writing
FreeBSD device drivers</ulink>.</para></listitem>
and procedures. The most important chapter is 13, <link xlink:href="&url.books.arch-handbook;/driverbasics.html">Writing
FreeBSD device drivers</link>.</para></listitem>
<listitem><para>The Blueprints section of <ulink
url="http://www.freebsddiary.org">FreeBSD Diary</ulink> web
<listitem><para>The Blueprints section of <link xlink:href="http://www.freebsddiary.org">FreeBSD Diary</link> web
site &mdash; contains several interesting articles on kernel
facilities.</para></listitem>
<listitem><para>The man pages in section 9 &mdash; for important
documentation on kernel functions.</para></listitem>
<listitem><para>The &man.geom.4; man page and <ulink
url="http://phk.freebsd.dk/pubs/">PHK's GEOM slides</ulink>
<listitem><para>The &man.geom.4; man page and <link xlink:href="http://phk.freebsd.dk/pubs/">PHK's GEOM slides</link>
&mdash; for general introduction of the GEOM
subsystem.</para></listitem>
@ -95,7 +85,7 @@
</sect2>
</sect1>
<sect1 id="prelim">
<sect1 xml:id="prelim">
<title>Preliminaries</title>
<para>The best way to do kernel development is to have (at least)
@ -112,11 +102,11 @@
<para>But, since not everybody has two or more computers handy, there are
a few things that can be done to prepare an otherwise <quote>live</quote>
system for developing kernel code. This setup is also applicable
for developing in a <ulink url="http://www.vmware.com/">VMWare</ulink>
or <ulink url="http://www.qemu.org/">QEmu</ulink> virtual machine (the
for developing in a <link xlink:href="http://www.vmware.com/">VMWare</link>
or <link xlink:href="http://www.qemu.org/">QEmu</link> virtual machine (the
next best thing after a dedicated development machine).</para>
<sect2 id="prelim-system">
<sect2 xml:id="prelim-system">
<title>Modifying a system for development</title>
<para>For any kernel programming a kernel with
@ -193,7 +183,7 @@ dumpdir="/usr/core </programlisting>
where in the filesystem to relocate the core dump on reboot.</para>
<para>Writing kernel core dumps is slow and takes a long time so
if you have lots of memory (>256M) and lots of panics it could
if you have lots of memory (&gt;256M) and lots of panics it could
be frustrating to sit and wait while it is done (twice &mdash; first
to write it to swap, then to relocate it to filesystem). It is
convenient then to limit the amount of RAM the system will use
@ -215,7 +205,7 @@ dumpdir="/usr/core </programlisting>
server.</para>
</sect2>
<sect2 id="prelim-starting">
<sect2 xml:id="prelim-starting">
<title>Starting the project</title>
<para>For the purpose of creating a new GEOM class, an empty
@ -224,7 +214,7 @@ dumpdir="/usr/core </programlisting>
<filename>/usr/src</filename>.</para>
</sect2>
<sect2 id="prelim-makefile">
<sect2 xml:id="prelim-makefile">
<title>The Makefile</title>
<para>It is good practice to create
@ -249,10 +239,10 @@ KMOD=geom_journal
</sect2>
</sect1>
<sect1 id="kernelprog">
<sect1 xml:id="kernelprog">
<title>On FreeBSD kernel programming</title>
<sect2 id="kernelprog-memalloc">
<sect2 xml:id="kernelprog-memalloc">
<title>Memory allocation</title>
<para>See &man.malloc.9;. Basic memory allocation is only
@ -278,7 +268,7 @@ KMOD=geom_journal
example, dynamic arrays of structs).</para>
</sect2>
<sect2 id="kernelprog-lists">
<sect2 xml:id="kernelprog-lists">
<title>Lists and queues</title>
<para>See &man.queue.3;. There are a LOT of cases when a list of
@ -295,17 +285,17 @@ KMOD=geom_journal
&man.tree.3; and &man.hashinit.9;.</para>
</sect2>
<sect2 id="kernelprog-bios">
<sect2 xml:id="kernelprog-bios">
<title>BIOs</title>
<para>Structure <structname>bio</structname> is used for any and
<para>Structure <varname remap="structname">bio</varname> is used for any and
all Input/Output operations concerning GEOM. It basically
contains information about what device ('provider') should
satisfy the request, request type, offset, length, pointer to
a buffer, and a bunch of <quote>user-specific</quote> flags
and fields that can help implement various hacks.</para>
<para>The important thing here is that <structname>bio</structname>s
<para>The important thing here is that <varname remap="structname">bio</varname>s
are handled asynchronously. That means that, in most parts of the code,
there is no analogue to userland's &man.read.2; and
&man.write.2; calls that do not return until a request is
@ -328,10 +318,10 @@ KMOD=geom_journal
</sect2>
</sect1>
<sect1 id="geom">
<sect1 xml:id="geom">
<title>On GEOM programming</title>
<sect2 id="geom-ggate">
<sect2 xml:id="geom-ggate">
<title>Ggate</title>
<para>If maximum performance is not needed, a much simpler way
@ -341,7 +331,7 @@ KMOD=geom_journal
two approaches.</para>
</sect2>
<sect2 id="geom-class">
<sect2 xml:id="geom-class">
<title>GEOM class</title>
<para>GEOM classes are transformations on the data. These transformations
@ -379,14 +369,14 @@ KMOD=geom_journal
copied to the geom instance.</para>
<para>Field <function>.geom</function> in the
<structname>g_class</structname> structure is a LIST of geoms
<varname remap="structname">g_class</varname> structure is a LIST of geoms
instantiated from the class.</para>
<para>These functions are called from the g_event kernel thread.</para>
</sect2>
<sect2 id="geom-softc">
<sect2 xml:id="geom-softc">
<title>Softc</title>
<para>The name <quote>softc</quote> is a legacy term for
@ -410,12 +400,12 @@ KMOD=geom_journal
are created on our behalf by GEOM).</para></listitem>
</itemizedlist>
<para>The <structname>softc</structname> structure contains all
<para>The <varname remap="structname">softc</varname> structure contains all
the state of geom instance. Every geom instance has its own
softc.</para>
</sect2>
<sect2 id="geom-metadata">
<sect2 xml:id="geom-metadata">
<title>Metadata</title>
<para>Format of metadata is more-or-less class-dependent, but
@ -440,7 +430,7 @@ KMOD=geom_journal
code works like that, and it is supported by libraries.)</para>
</sect2>
<sect2 id="geom-creating">
<sect2 xml:id="geom-creating">
<title>Labeling/creating a geom</title>
<para>The sequence of events is:</para>
@ -452,7 +442,7 @@ KMOD=geom_journal
<listitem><para>the utility figures out which geom class it is
supposed to handle and searches for
<filename>geom_<replaceable>CLASSNAME</replaceable>.so</filename>
<filename>geom_CLASSNAME.so</filename>
library (usually in
<filename>/lib/geom</filename>).</para></listitem>
@ -488,12 +478,12 @@ KMOD=geom_journal
</sect2>
<sect2 id="geom-command">
<sect2 xml:id="geom-command">
<title>Geom command structure</title>
<para>The helper <filename>geom_CLASSNAME.so</filename> library
exports <structname>class_commands</structname> structure,
which is an array of <structname>struct g_command</structname>
exports <varname remap="structname">class_commands</varname> structure,
which is an array of <varname remap="structname">struct g_command</varname>
elements. Commands are of uniform format and look like:</para>
<programlisting> verb [-options] geomname [other]</programlisting>
@ -518,8 +508,8 @@ KMOD=geom_journal
</itemizedlist>
<para>Many actions, such as labeling and destroying metadata can
be performed in userland. For this, <structname>struct
g_command</structname> provides field
be performed in userland. For this, <varname remap="structname">struct
g_command</varname> provides field
<varname>gc_func</varname> that can be set to a function (in
the same <filename>.so</filename>) that will be called to
process a verb. If <varname>gc_func</varname> is NULL, the
@ -528,7 +518,7 @@ KMOD=geom_journal
class.</para>
</sect2>
<sect2 id="geom-geoms">
<sect2 xml:id="geom-geoms">
<title>Geoms</title>
<para>Geoms are instances of GEOM classes. They have internal
@ -564,7 +554,7 @@ KMOD=geom_journal
managed by a instance of geom class.</para>
</sect2>
<sect2 id="geom-threads">
<sect2 xml:id="geom-threads">
<title>Geom threads</title>
<para>There are three kernel threads created and run by the GEOM
@ -619,7 +609,7 @@ KMOD=geom_journal
thread. First the partition slicer gets
<function>.done</function>() called in the
<literal>g_up</literal> thread, it uses information stored
in the bio to free the cloned <structname>bio</structname>
in the bio to free the cloned <varname remap="structname">bio</varname>
structure (with <function>g_destroy_bio</function>()) and
calls <function>g_io_deliver</function>() on the original
request.</para></listitem>
@ -629,7 +619,7 @@ KMOD=geom_journal
</itemizedlist>
<para>See &man.g.bio.9; man page for information how the data is
passed back and forth in the <structname>bio</structname>
passed back and forth in the <varname remap="structname">bio</varname>
structure (note in particular the <varname>bio_parent</varname>
and <varname>bio_children</varname> fields and how they are
handled).</para>
@ -667,7 +657,7 @@ KMOD=geom_journal
additional kernel threads.</para>
</sect2>
<sect2 id="geom-kernelthreads">
<sect2 xml:id="geom-kernelthreads">
<title>Kernel threads for use in geom code</title>
<para>Kernel threads are created with &man.kthread.create.9;

92
en_US.ISO8859-1/articles/gjournal-desktop/article.xml
View file

@ -1,18 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Implementing UFS Journaling on a Desktop PC</title>
<article lang="en">
<articleinfo>
<title>Implementing UFS Journaling on a Desktop PC</title>
<author>
<firstname>Manolis</firstname>
<surname>Kiagias</surname>
<affiliation>
<author><personname><firstname>Manolis</firstname><surname>Kiagias</surname></personname><affiliation>
<address><email>manolis@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2008</year>
@ -23,7 +18,7 @@
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -42,9 +37,9 @@
explains how to implement UFS journaling on a typical desktop PC
scenario.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>While professional servers are usually well protected from
@ -120,7 +115,7 @@
</warning>
</sect1>
<sect1 id="understanding-journaling">
<sect1 xml:id="understanding-journaling">
<title>Understanding Journaling in &os;</title>
<para>The journaling provided by GEOM in &os;&nbsp;7.<replaceable>X</replaceable> is not file system
@ -151,20 +146,19 @@
<itemizedlist>
<listitem>
<para>You wish to journal your <filename>/usr</filename> file system,
stored in <filename class="devicefile">/dev/ad0s1f</filename> (which
stored in <filename>/dev/ad0s1f</filename> (which
already contains data).</para>
</listitem>
<listitem>
<para>You reserved some free disk space in a partition in
<filename class="devicefile">/dev/ad0s1g</filename>.</para>
<filename>/dev/ad0s1g</filename>.</para>
</listitem>
<listitem>
<para>Using <command>gjournal</command>, a new <filename
class="devicefile">/dev/ad0s1f.journal</filename> device is created
where <filename class="devicefile">/dev/ad0s1f</filename> is the data
provider, and <filename class="devicefile">/dev/ad0s1g</filename> is
<para>Using <command>gjournal</command>, a new <filename>/dev/ad0s1f.journal</filename> device is created
where <filename>/dev/ad0s1f</filename> is the data
provider, and <filename>/dev/ad0s1g</filename> is
the journal provider. This new device is then used for all
subsequent file operations.</para>
</listitem>
@ -194,7 +188,7 @@
page of &man.gjournal.8;.</para>
</sect1>
<sect1 id="reserve-space">
<sect1 xml:id="reserve-space">
<title>Steps During the Installation of &os;</title>
<sect2>
@ -325,7 +319,7 @@
(packages) until you have completely setup journaling.</para>
</sect2>
<sect2 id="first-boot">
<sect2 xml:id="first-boot">
<title>Booting for the first time</title>
<para>Your system will come up normally, but you will need to edit
@ -340,15 +334,15 @@
</sect2>
</sect1>
<sect1 id="configure-journal">
<sect1 xml:id="configure-journal">
<title>Setting Up Journaling</title>
<sect2 id="running-gjournal">
<sect2 xml:id="running-gjournal">
<title>Executing <command>gjournal</command></title>
<para>Having prepared all the required partitions, it is quite easy
to configure journaling. We will need to switch to single user
mode, so login as <username>root</username> and type:</para>
mode, so login as <systemitem class="username">root</systemitem> and type:</para>
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
@ -364,11 +358,10 @@
<para>Now, use your notes to determine which partition will be used
for each journal. In our example, <filename>/usr</filename> is
<filename class="devicefile">ad0s1f</filename> and its journal will be
<filename class="devicefile">ad0s1g</filename>, while
<filename>/var</filename> is <filename
class="devicefile">ad0s1d</filename> and will
be journaled to <filename class="devicefile">ad0s1h</filename>.
<filename>ad0s1f</filename> and its journal will be
<filename>ad0s1g</filename>, while
<filename>/var</filename> is <filename>ad0s1d</filename> and will
be journaled to <filename>ad0s1h</filename>.
The following commands are required:</para>
<screen>&prompt.root; <userinput>gjournal label ad0s1f ad0s1g</userinput>
@ -393,8 +386,8 @@ GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.</screen>
anything will be actually overwritten.</para></note>
<para>At this point, two new devices are created, namely
<filename class="devicefile">ad0s1d.journal</filename> and
<filename class="devicefile">ad0s1f.journal</filename>. These represent
<filename>ad0s1d.journal</filename> and
<filename>ad0s1f.journal</filename>. These represent
the <filename>/var</filename> and <filename>/usr</filename>
partitions we have to mount. Before mounting, we must however set
the journal flag on them and clear the Soft Updates flag:</para>
@ -456,14 +449,14 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen>
state.</para>
</sect2>
<sect2 id="gjournal-new">
<sect2 xml:id="gjournal-new">
<title>Journaling Newly Created Partitions</title>
<para>While the above procedure is necessary for journaling partitions
that already contain data, journaling an empty partition is somewhat
easier, since both the data and the journal provider can be stored
in the same partition. For example, assume a new disk was installed,
and a new partition <filename class="devicefile">/dev/ad1s1d</filename>
and a new partition <filename>/dev/ad1s1d</filename>
was created. Creating the journal would be as simple as:</para>
<screen>&prompt.root; <userinput>gjournal label ad1s1d</userinput></screen>
@ -486,7 +479,7 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen>
<screen>&prompt.root; <userinput>newfs -J /dev/ad1s1d.journal</userinput></screen>
</sect2>
<sect2 id="configure-kernel">
<sect2 xml:id="configure-kernel">
<title>Building Journaling into Your Custom Kernel</title>
<para>If you do not wish to load <literal>geom_journal</literal> as a
@ -499,8 +492,8 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen>
options GEOM_JOURNAL # You will have to add this one</programlisting>
<para>Rebuild and reinstall your kernel following the relevant
<ulink url="&url.books.handbook;/kernelconfig.html">instructions in
the &os;&nbsp;Handbook.</ulink></para>
<link xlink:href="&url.books.handbook;/kernelconfig.html">instructions in
the &os;&nbsp;Handbook.</link></para>
<para>Do not forget to remove the relevant <quote>load</quote> entry
from <filename>/boot/loader.conf</filename> if you have previously
@ -508,7 +501,7 @@ options GEOM_JOURNAL # You will have to add this one</programlisting>
</sect2>
</sect1>
<sect1 id="troubleshooting-gjournal">
<sect1 xml:id="troubleshooting-gjournal">
<title>Troubleshooting Journaling</title>
<para>The following section covers frequently asked questions regarding
@ -516,7 +509,7 @@ options GEOM_JOURNAL # You will have to add this one</programlisting>
<qandaset>
<qandaentry>
<question id="kernel-panic">
<question xml:id="kernel-panic">
<para>I am getting kernel panics during periods of high disk
activity. How is this related to journaling?</para>
</question>
@ -526,13 +519,12 @@ options GEOM_JOURNAL # You will have to add this one</programlisting>
committed (flushed) to disk. Keep in mind the size of the
journal depends on the usage load, and not the size of the data
provider. If your disk activity is high, you need a larger
partition for the journal. See the note in the <link
linkend="understanding-journaling">Understanding Journaling</link> section.</para>
partition for the journal. See the note in the <link linkend="understanding-journaling">Understanding Journaling</link> section.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="unable-boot">
<question xml:id="unable-boot">
<para>I made some mistake during configuration, and I cannot boot
normally now. Can this be fixed some way?</para>
</question>
@ -572,7 +564,7 @@ GEOM_JOURNAL: Journal ad0s1f clean.
</qandaentry>
<qandaentry>
<question id="remove-journaling">
<question xml:id="remove-journaling">
<para>Can I remove journaling and return to my standard file system
with Soft Updates?</para>
</question>
@ -582,7 +574,7 @@ GEOM_JOURNAL: Journal ad0s1f clean.
changes. The partitions you created for the journal providers
can then be used for other purposes, if you so wish.</para>
<para>Login as <username>root</username> and switch to single user mode:</para>
<para>Login as <systemitem class="username">root</systemitem> and switch to single user mode:</para>
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
@ -639,7 +631,7 @@ tunefs: soft updates set</screen>
</qandaset>
</sect1>
<sect1 id="further-reading">
<sect1 xml:id="further-reading">
<title>Further Reading</title>
<para>Journaling is a fairly new feature of &os;, and as such, it is
@ -648,17 +640,17 @@ tunefs: soft updates set</screen>
<itemizedlist>
<listitem>
<para>A <ulink url="&url.books.handbook;/geom-gjournal.html">new section on journaling</ulink>
<para>A <link xlink:href="&url.books.handbook;/geom-gjournal.html">new section on journaling</link>
is now part of the &os;&nbsp;Handbook.</para>
</listitem>
<listitem>
<para><ulink url="http://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html">This post</ulink>
<para><link xlink:href="http://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html">This post</link>
in &a.current.name; by &man.gjournal.8;'s developer, &a.pjd.email;.</para>
</listitem>
<listitem>
<para><ulink url="http://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html">This post</ulink>
<para><link xlink:href="http://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html">This post</link>
in &a.questions.name; by &a.ivoras.email;.</para>
</listitem>

257
en_US.ISO8859-1/articles/hubs/article.xml
View file

@ -1,42 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Mirroring FreeBSD</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Mirroring FreeBSD</title>
<authorgroup>
<author>
<firstname>Jun</firstname>
<surname>Kuriyama</surname>
<affiliation>
<author><personname><firstname>Jun</firstname><surname>Kuriyama</surname></personname><affiliation>
<address><email>kuriyama@FreeBSD.org</email></address>
</affiliation>
</author>
<author>
<firstname>Valentino</firstname>
<surname>Vaschetto</surname>
<affiliation>
</affiliation></author>
<author><personname><firstname>Valentino</firstname><surname>Vaschetto</surname></personname><affiliation>
<address><email>logo@FreeBSD.org</email></address>
</affiliation>
</author>
<author>
<firstname>Daniel</firstname>
<surname>Lang</surname>
<affiliation>
</affiliation></author>
<author><personname><firstname>Daniel</firstname><surname>Lang</surname></personname><affiliation>
<address><email>dl@leo.org</email></address>
</affiliation>
</author>
<author>
<firstname>Ken</firstname>
<surname>Smith</surname>
<affiliation>
</affiliation></author>
<author><personname><firstname>Ken</firstname><surname>Smith</surname></personname><affiliation>
<address><email>kensmith@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cvsup;
&tm-attrib.general;
@ -50,13 +33,13 @@
<para>An in-progress article on how to mirror FreeBSD, aimed at
hub administrators.</para>
</abstract>
</articleinfo>
</info>
<note>
<para>We are not accepting new mirrors at this time.</para>
</note>
<sect1 id="mirror-contact">
<sect1 xml:id="mirror-contact">
<title>Contact Information</title>
<para>The Mirror System Coordinators can be reached through email
@ -64,9 +47,9 @@
a &a.hubs;.</para>
</sect1>
<sect1 id="mirror-requirements">
<sect1 xml:id="mirror-requirements">
<title>Requirements for FreeBSD mirrors</title>
<sect2 id="mirror-diskspace">
<sect2 xml:id="mirror-diskspace">
<title>Disk Space</title>
<para>
Disk space is one of the most important requirements.
@ -91,10 +74,10 @@
</itemizedlist>
<para>
The current disk usage of FTP Distribution can be found at
<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes">ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes</ulink>.
<link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes">ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes</link>.
</para>
</sect2>
<sect2 id="mirror-bandwidth">
<sect2 xml:id="mirror-bandwidth">
<title>Network Connection/Bandwidth</title>
<para>
Of course, you need to be connected to the Internet.
@ -114,7 +97,7 @@
should be connected as close as possible to your border router.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="mirror-system">
<sect2 xml:id="mirror-system">
<title>System Requirements, CPU, RAM</title>
<para>
One thing this depends on the expected number of clients,
@ -151,7 +134,7 @@
large number of small modifications to the disk.
</para>
</sect2>
<sect2 id="mirror-services">
<sect2 xml:id="mirror-services">
<title>Services to offer</title>
<para>
Every mirror site is required to have a set of core services
@ -160,7 +143,7 @@
server administrators may choose to offer. This section explains
which services you can provide and how to go about implementing them.
</para>
<sect3 id="mirror-serv-ftp">
<sect3 xml:id="mirror-serv-ftp">
<title>FTP (required for FTP fileset)</title>
<para>
This is one of the most basic services, and
@ -182,24 +165,24 @@
can be used. Be sure to read &man.ftpd.8;.</para>
</listitem>
<listitem>
<para><filename role="package">ftp/ncftpd</filename>: A commercial package,
<para><package>ftp/ncftpd</package>: A commercial package,
free for educational use.</para>
</listitem>
<listitem>
<para><filename role="package">ftp/oftpd</filename>: An ftpd designed with
<para><package>ftp/oftpd</package>: An ftpd designed with
security as a main focus.</para>
</listitem>
<listitem>
<para><filename role="package">ftp/proftpd</filename>: A modular and very flexible ftpd.</para>
<para><package>ftp/proftpd</package>: A modular and very flexible ftpd.</para>
</listitem>
<listitem>
<para><filename role="package">ftp/pure-ftpd</filename>: Another ftpd developed with
<para><package>ftp/pure-ftpd</package>: Another ftpd developed with
security in mind.</para>
</listitem>
<listitem><para><filename role="package">ftp/twoftpd</filename>: As above.</para></listitem>
<listitem><para><filename role="package">ftp/vsftpd</filename>: The <quote>very secure</quote> ftpd.</para></listitem>
<listitem><para><package>ftp/twoftpd</package>: As above.</para></listitem>
<listitem><para><package>ftp/vsftpd</package>: The <quote>very secure</quote> ftpd.</para></listitem>
<listitem>
<para><filename role="package">ftp/wu-ftpd</filename>: The ftpd from Washington
<para><package>ftp/wu-ftpd</package>: The ftpd from Washington
University. It has become infamous, because of the huge
amount of security issues that have been found in it.
If you do choose to use this software be sure to
@ -216,7 +199,7 @@
much network bandwidth and system resources are consumed.
</para>
</sect3>
<sect3 id="mirror-serv-rsync">
<sect3 xml:id="mirror-serv-rsync">
<title>Rsync (optional for FTP fileset)</title>
<para>
<application>Rsync</application> is often offered for access to the
@ -236,10 +219,10 @@
may be applied. There is just one software package
available:</para>
<itemizedlist>
<listitem><para><filename role="package">net/rsync</filename></para></listitem>
<listitem><para><package>net/rsync</package></para></listitem>
</itemizedlist>
</sect3>
<sect3 id="mirror-serv-http">
<sect3 xml:id="mirror-serv-http">
<title>HTTP (required for web pages, optional for FTP fileset)</title>
<para>
If you want to offer the FreeBSD web pages, you will need
@ -250,14 +233,14 @@
<itemizedlist>
<listitem>
<para><filename role="package">www/apache22</filename>:
<para><package>www/apache22</package>:
<application>Apache</application> is the most widely
deployed web server on the Internet. It is used
extensively by the FreeBSD Project.</para>
</listitem>
<listitem>
<para><filename role="package">www/thttpd</filename>:
<para><package>www/thttpd</package>:
If you are going to be serving a large amount of static content
you may find that using an application such as thttpd is more
efficient than <application>Apache</application>. It is
@ -265,7 +248,7 @@
</listitem>
<listitem>
<para><filename role="package">www/boa</filename>:
<para><package>www/boa</package>:
<application>Boa</application> is another alternative to
<application>thttpd</application> and
<application>Apache</application>. It should provide
@ -277,7 +260,7 @@
</listitem>
</itemizedlist>
</sect3>
<sect3 id="mirror-serv-cvsup">
<sect3 xml:id="mirror-serv-cvsup">
<title>CVSup (desired for CVS repository)</title>
<para>
<application>CVSup</application> is a very efficient way of distributing files.
@ -294,26 +277,26 @@
a Modula-3 environment. &a.jdp; has built a
stripped down version of M3 that is sufficient to
run <application>CVSup</application>, and can be installed much easier.
See <ulink url="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</ulink>
See <link xlink:href="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</link>
for details. Related ports are:</para>
<itemizedlist>
<listitem>
<para><filename role="package">net/cvsup</filename>: The native CVSup port (client and server)
which requires <filename role="package">lang/ezm3</filename> now.</para>
<para><package>net/cvsup</package>: The native CVSup port (client and server)
which requires <package>lang/ezm3</package> now.</para>
</listitem>
<listitem>
<para><filename role="package">net/cvsup-mirror</filename>: The CVSup mirror kit, which requires
<filename role="package">net/cvsup-without-gui</filename>, and configures it mirror-ready. Some
<para><package>net/cvsup-mirror</package>: The CVSup mirror kit, which requires
<package>net/cvsup-without-gui</package>, and configures it mirror-ready. Some
site administrators may want a different setup though.
</para>
</listitem>
</itemizedlist>
<para>There are a few more like
<filename role="package">net/cvsup-without-gui</filename> you might want to have
<package>net/cvsup-without-gui</package> you might want to have
a look at. If you prefer a static binary package, take a look
<ulink url="http://people.FreeBSD.org/~jdp/s1g/">here</ulink>.
<link xlink:href="http://people.FreeBSD.org/~jdp/s1g/">here</link>.
This page still refers to the S1G bug that was present
in <application>CVSup</application>. Maybe
John will set up a generic download-site to get
@ -327,7 +310,7 @@
client, since it needs to compare lots of files.
</para>
</sect3>
<sect3 id="mirror-anoncvs">
<sect3 xml:id="mirror-anoncvs">
<title>AnonCVS (optional for CVS repository)</title>
<para>
If you have the CVS repository, you may want to offer
@ -344,7 +327,7 @@
For anonymous access, <emphasis>pserver</emphasis> is
very well suited, but some still offer <command>ssh</command>
access as well. There is a custom crafted
<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</ulink>
<link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</link>
in the CVS repository, to be used as a login-shell for the
anonymous ssh account. It does a chroot, and therefore
requires the CVS repository to be available under the
@ -362,7 +345,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
<para>See the manpage for details of the options. Also see the CVS <emphasis>info</emphasis>
page about additional ways to make sure access is read-only.
It is advised that you create an unprivileged account,
preferably called <username>anoncvs</username>.
preferably called <systemitem class="username">anoncvs</systemitem>.
Also you need to create a file <filename>passwd</filename>
in your <filename>/home/ncvs/CVSROOT</filename> and assign a
CVS password (empty or <literal>anoncvs</literal>) to that user.
@ -382,7 +365,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</sect3>
</sect2>
</sect1>
<sect1 id="mirror-howto">
<sect1 xml:id="mirror-howto">
<title>How to Mirror FreeBSD</title>
<para>
Ok, now you know the requirements and how to offer
@ -391,7 +374,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
the various parts of FreeBSD, what tools to use,
and where to mirror from.
</para>
<sect2 id="mirror-ftp">
<sect2 xml:id="mirror-ftp">
<title>FTP</title>
<para>
The FTP area is the largest amount of data that
@ -405,21 +388,21 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
for various FreeBSD versions,
and various architectures.
</para>
<sect3 id="mirror-ftp-ftp">
<sect3 xml:id="mirror-ftp-ftp">
<title>With FTP mirror</title>
<para>
You can use a <application>FTP mirror</application>
program to get the files. Some of the most commonly used are:</para>
<itemizedlist>
<listitem><para><filename role="package">ftp/mirror</filename></para></listitem>
<listitem><para><filename role="package">ftp/ftpmirror</filename></para></listitem>
<listitem><para><filename role="package">ftp/emirror</filename></para></listitem>
<listitem><para><filename role="package">ftp/spegla</filename></para></listitem>
<listitem><para><filename role="package">ftp/omi</filename></para></listitem>
<listitem><para><filename role="package">ftp/wget</filename></para></listitem>
<listitem><para><package>ftp/mirror</package></para></listitem>
<listitem><para><package>ftp/ftpmirror</package></para></listitem>
<listitem><para><package>ftp/emirror</package></para></listitem>
<listitem><para><package>ftp/spegla</package></para></listitem>
<listitem><para><package>ftp/omi</package></para></listitem>
<listitem><para><package>ftp/wget</package></para></listitem>
</itemizedlist>
<para><filename role="package">ftp/mirror</filename> was very popular, but seemed
<para><package>ftp/mirror</package> was very popular, but seemed
to have some drawbacks, as it is written in &man.perl.1;,
and had real problems with mirroring large
directories like a FreeBSD site. There are rumors that
@ -434,11 +417,11 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
a large TCP congestion window.
</para>
</sect3>
<sect3 id="mirror-ftp-rsync">
<sect3 xml:id="mirror-ftp-rsync">
<title>With rsync</title>
<para>
A better way to mirror the FTP area is <application>rsync</application>.
You can install the port <filename role="package">net/rsync</filename> and then use
You can install the port <package>net/rsync</package> and then use
rsync to sync with your upstream host.
<application>rsync</application> is already mentioned
in <xref linkend="mirror-serv-rsync"/>.
@ -461,7 +444,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</screen>
<para>Consult the documentation for <application>rsync</application>,
which is also available at
<ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>,
<link xlink:href="http://rsync.samba.org/">http://rsync.samba.org/</link>,
about the various options to be used with rsync.
If you sync the whole module (unlike subdirectories),
be aware that the module-directory (here "FreeBSD")
@ -471,15 +454,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
via &man.cron.8;.
</para>
</sect3>
<sect3 id="mirror-ftp-cvsup">
<sect3 xml:id="mirror-ftp-cvsup">
<title>With CVSup</title>
<para>
A few sites, including the one-and-only <hostid role="fqdn">ftp-master.FreeBSD.org</hostid>
A few sites, including the one-and-only <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem>
even offer <application>CVSup</application> to mirror the contents of
the FTP space. You need to install a <application>CVSup</application>
client, preferably from the port <filename role="package">net/cvsup</filename>.
client, preferably from the port <package>net/cvsup</package>.
(Also reread <xref linkend="mirror-serv-cvsup"/>.)
A sample <filename>supfile</filename> suitable for <hostid role="fqdn">ftp-master.FreeBSD.org</hostid>
A sample <filename>supfile</filename> suitable for <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem>
looks like this:</para>
<programlisting>
#
@ -501,7 +484,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
<para>It seems <application>CVSup</application> would be the best
way to mirror the archive in terms of efficiency, but
it is only available from few sites.</para>
<note id="mirror-cvsup-s-option">
<note xml:id="mirror-cvsup-s-option">
<para>
Please have look at the <application>CVSup</application> documentation
like &man.cvsup.1; and consider using the <option>-s</option>
@ -510,12 +493,12 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</note>
</sect3>
</sect2>
<sect2 id="mirror-cvs">
<sect2 xml:id="mirror-cvs">
<title>Mirroring the CVS repository</title>
<para>There are various ways to mirror the CVS repository.
<application>CVSup</application> is the most common method.</para>
<sect3 id="mirror-cvs-cvsup">
<sect3 xml:id="mirror-cvs-cvsup">
<title>Using CVSup</title>
<para>
<application>CVSup</application> is described in some
@ -523,7 +506,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</para>
<para>It is very easy to setup a
<application>CVSup</application> mirror. Installing
<filename role="package">net/cvsup-mirror</filename> will
<package>net/cvsup-mirror</package> will
make sure all of the needed programs are installed and then
gather all the needed information to configure the mirror.</para>
<note>
@ -534,7 +517,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</para>
</note>
</sect3>
<sect3 id="mirror-cvs-other">
<sect3 xml:id="mirror-cvs-other">
<title>Using other methods</title>
<para>
Using other methods than <application>CVSup</application> is
@ -556,7 +539,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</important>
</sect3>
</sect2>
<sect2 id="mirror-www">
<sect2 xml:id="mirror-www">
<title>Mirroring the WWW pages</title>
<para>
The best way is to check out the <emphasis>www</emphasis>
@ -593,10 +576,10 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
www
</programlisting>
<para>
Using <filename role="package">ftp/wget</filename> or other web-mirror tools is
Using <package>ftp/wget</package> or other web-mirror tools is
not recommended.
</para>
<sect3 id="mirror-www-doc">
<sect3 xml:id="mirror-www-doc">
<title>Mirroring the FreeBSD documentation</title>
<para>
Since the documentation is referenced a lot from the
@ -628,7 +611,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
<para>
Then you need to install a couple of ports.
You are lucky, there is a meta-port:
<filename role="package">textproc/docproj</filename> to do the work
<package>textproc/docproj</package> to do the work
for you. You need to set up some
environment variables, like
<literal>SGML_CATALOG_FILES</literal>.
@ -645,15 +628,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
<para>
The building of the documentation, as well as lots
of side issues, is documented itself in the
<ulink url="&url.books.fdp-primer;">&os; Documentation
Project Primer</ulink>.
<link xlink:href="&url.books.fdp-primer;">&os; Documentation
Project Primer</link>.
Please read this piece of documentation, especially if you
have problems building the documentation.
</para>
</important>
</sect3>
</sect2>
<sect2 id="mirror-how-often">
<sect2 xml:id="mirror-how-often">
<title>How often should I mirror?</title>
<para>
Every mirror should be updated on a regular
@ -705,37 +688,37 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</itemizedlist>
</sect2>
</sect1>
<sect1 id="mirror-where">
<sect1 xml:id="mirror-where">
<title>Where to mirror from</title>
<para>
This is an important issue. So this section will
spend some effort to explain the backgrounds. We will say this
several times: under no circumstances should you mirror from
<hostid role="fqdn">ftp.FreeBSD.org</hostid>.
<systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>.
</para>
<sect2 id="mirror-where-organization">
<sect2 xml:id="mirror-where-organization">
<title>A few words about the organization</title>
<para>
Mirrors are organized by country. All
official mirrors have a DNS entry of the form
<hostid role="fqdn">ftpN.CC.FreeBSD.org</hostid>.
<systemitem class="fqdomainname">ftpN.CC.FreeBSD.org</systemitem>.
<emphasis>CC</emphasis> (i.e. country code) is the
<emphasis>top level domain</emphasis> (TLD)
of the country where this mirror is located.
<emphasis>N</emphasis> is a number,
telling that the host would be the <emphasis>Nth</emphasis>
mirror in that country.
(Same applies to <hostid>cvsupN.CC.FreeBSD.org</hostid>,
<hostid>wwwN.CC.FreeBSD.org</hostid>, etc.)
(Same applies to <systemitem>cvsupN.CC.FreeBSD.org</systemitem>,
<systemitem>wwwN.CC.FreeBSD.org</systemitem>, etc.)
There are mirrors with no <emphasis>CC</emphasis> part.
These are the mirror sites that are very well connected and
allow a large number of concurrent users.
<hostid role="fqdn">ftp.FreeBSD.org</hostid> is actually two machines, one currently
<systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> is actually two machines, one currently
located in Denmark and the other in the United States.
It is <emphasis>NOT</emphasis> a master site and should never be
used to mirror from. Lots of online documentation leads
<quote>interactive</quote>users to
<hostid role="fqdn">ftp.FreeBSD.org</hostid> so automated mirroring
<systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> so automated mirroring
systems should find a different machine to mirror from.
</para>
<para>
@ -758,16 +741,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
(this is just a rough hint, and there is no rule).
</para>
</sect2>
<sect2 id="mirror-where-where">
<sect2 xml:id="mirror-where-where">
<title>Ok, but where should I get the stuff now?</title>
<para>
Under no circumstances should you mirror from <hostid
role="fqdn">ftp.FreeBSD.org</hostid>.
Under no circumstances should you mirror from <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>.
The short answer is: from the
site that is closest to you in Internet terms, or gives you
the fastest access.
</para>
<sect3 id="mirror-where-simple">
<sect3 xml:id="mirror-where-simple">
<title>I just want to mirror from somewhere!</title>
<para>
If you have no special intentions or
@ -798,7 +780,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</step>
</procedure>
</sect3>
<sect3 id="mirror-where-official">
<sect3 xml:id="mirror-where-official">
<title>I am an official mirror, what is the right site for me?</title>
<para>
In general the description in <xref linkend="mirror-where-simple"/>
@ -809,7 +791,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
mirrors that are described in <xref linkend="mirror-official"/>.
</para>
</sect3>
<sect3 id="mirror-where-master">
<sect3 xml:id="mirror-where-master">
<title>I want to access the master sites!</title>
<para>
If you have good reasons and good prerequisites,
@ -834,13 +816,13 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
one for the CVS repository (the web pages and docs are
obtained from CVS, so there is no need for master).
</para>
<sect4 id="mirror-where-master-ftp">
<sect4 xml:id="mirror-where-master-ftp">
<title>ftp-master.FreeBSD.org</title>
<para>
This is the master site for the FTP fileset.
</para>
<para>
<hostid>ftp-master.FreeBSD.org</hostid> provides
<systemitem>ftp-master.FreeBSD.org</systemitem> provides
<application>rsync</application> and <application>CVSup</application>
access, in addition to FTP.
Refer to <xref linkend="mirror-ftp-rsync"/> and
@ -853,43 +835,43 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
<emphasis>Tier-1</emphasis>-mirrors.
</para>
</sect4>
<sect4 id="mirror-where-master-cvsup">
<sect4 xml:id="mirror-where-master-cvsup">
<title>cvsup-master.FreeBSD.org</title>
<para>
This is the master site for the CVS repository.
</para>
<para>
<hostid>cvsup-master.FreeBSD.org</hostid> provides
<systemitem>cvsup-master.FreeBSD.org</systemitem> provides
<application>CVSup</application> access only.
See <xref linkend="mirror-cvs-cvsup"/> for details.
</para>
<para>
To get access, you need to contact the &a.cvsup-master;.
Make sure you read the
<ulink url="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</ulink>
<link xlink:href="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</link>
first!
</para>
<para>
Set up the required authentication by following
<ulink url="http://people.FreeBSD.org/~jdp/cvpasswd/">these
instructions</ulink>. Make sure you specify the server as
<hostid>freefall.FreeBSD.org</hostid> on the <command>cvpasswd</command>
<link xlink:href="http://people.FreeBSD.org/~jdp/cvpasswd/">these
instructions</link>. Make sure you specify the server as
<systemitem>freefall.FreeBSD.org</systemitem> on the <command>cvpasswd</command>
command line, as described in this document,
even when you are contacting
<hostid>cvsup-master.FreeBSD.org</hostid>
<systemitem>cvsup-master.FreeBSD.org</systemitem>
</para>
</sect4>
</sect3>
</sect2>
</sect1>
<sect1 id="mirror-official">
<sect1 xml:id="mirror-official">
<title>Official Mirrors</title>
<para>
Official mirrors are mirrors that</para>
<itemizedlist>
<listitem>
<para>
a) have a <hostid>FreeBSD.org</hostid> DNS entry
a) have a <systemitem>FreeBSD.org</systemitem> DNS entry
(usually a CNAME).
</para>
</listitem>
@ -906,7 +888,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
However you probably will not find a <emphasis>Tier-1</emphasis>-mirror,
that is not also official.
</para>
<sect2 id="mirror-official-requirements">
<sect2 xml:id="mirror-official-requirements">
<title>Special Requirements for official (tier-1) mirrors</title>
<para>
It is not so easy to state requirements for all
@ -933,12 +915,12 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</itemizedlist>
<para>Furthermore, admins should be subscribed to the &a.hubs;.
See <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</ulink> for details, how to subscribe.
See <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</link> for details, how to subscribe.
</para>
<important>
<para>It is <emphasis>very</emphasis> important for a hub administrator, especially
Tier-1 hub admins, to check the
<ulink url="http://www.FreeBSD.org/releng/">release schedule</ulink>
<link xlink:href="http://www.FreeBSD.org/releng/">release schedule</link>
for the next FreeBSD release. This is important because it will tell you when the
next release is scheduled
to come out, and thus giving you time to prepare for the big spike of traffic which follows it.
@ -951,7 +933,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</para>
</important>
</sect2>
<sect2 id="mirror-official-become">
<sect2 xml:id="mirror-official-become">
<title>How to become official then?</title>
<!--
<para>
@ -1013,52 +995,51 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all
</para>
</sect2>
</sect1>
<sect1 id="mirror-statpages">
<sect1 xml:id="mirror-statpages">
<title>Some statistics from mirror sites</title>
<para>
Here are links to the stat pages of your favorite mirrors
(a.k.a. the only ones who feel like providing stats).
</para>
<sect2 id="mirror-statpagesftp">
<sect2 xml:id="mirror-statpagesftp">
<title>FTP site statistics</title>
<itemizedlist>
<listitem>
<para>ftp.is.FreeBSD.org - <email>hostmaster@is.FreeBSD.org</email> -
<ulink url="http://www.rhnet.is/status/draupnir/draupnir.html">
(Bandwidth)</ulink> <ulink url="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP
processes)</ulink> <ulink url="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes)
</ulink>
<link xlink:href="http://www.rhnet.is/status/draupnir/draupnir.html">
(Bandwidth)</link> <link xlink:href="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP
processes)</link> <link xlink:href="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes)
</link>
</para>
</listitem>
<listitem>
<para>ftp.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> -
<ulink url="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</ulink>
<ulink url="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</ulink>
<ulink url="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(rsync processes)</ulink>
<link xlink:href="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</link>
<link xlink:href="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</link>
<link xlink:href="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(rsync processes)</link>
</para>
</listitem>
<listitem>
<para>ftp2.ru.FreeBSD.org - <email>mirror@macomnet.ru</email> -
<ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</ulink>
<ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP users)</ulink>
<link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</link>
<link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP users)</link>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="mirror-statpagescvsup">
<sect2 xml:id="mirror-statpagescvsup">
<title>CVSup site stats</title>
<itemizedlist>
<listitem>
<para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <ulink
url="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/index.en.html">(CVSup processes)</ulink></para>
<para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <link xlink:href="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/index.en.html">(CVSup processes)</link></para>
</listitem>
<listitem>
<para>cvsup.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> -
<ulink url="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</ulink></para>
<link xlink:href="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</link></para>
</listitem>
<listitem>
<para>cvsup4.ru.FreeBSD.org - <email>maxim@FreeBSD.org</email> -
<ulink url="http://ftp.mtu.ru/mrtg/ftp.mtu.ru_proc2.html">(CVSup processes)</ulink></para>
<link xlink:href="http://ftp.mtu.ru/mrtg/ftp.mtu.ru_proc2.html">(CVSup processes)</link></para>
</listitem>
</itemizedlist>
</sect2>

71
en_US.ISO8859-1/articles/ipsec-must/article.xml
View file

@ -1,29 +1,22 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Independent Verification of IPsec Functionality in FreeBSD</title>
<article lang='en'>
<articleinfo>
<title>Independent Verification of IPsec Functionality in FreeBSD</title>
<author>
<firstname>David</firstname>
<surname>Honig</surname>
<affiliation>
<author><personname><firstname>David</firstname><surname>Honig</surname></personname><affiliation>
<address><email>honig@sprynet.com</email></address>
</affiliation>
</author>
</affiliation></author>
<pubdate>3 May 1999</pubdate>
<pubdate>1999-05-03</pubdate>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.opengroup;
&tm-attrib.general;
@ -36,9 +29,9 @@
know? I describe a method for experimentally verifying that IPsec is
working.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="problem">
<sect1 xml:id="problem">
<title>The Problem</title>
<para>First, lets assume you have <link linkend="ipsec-install">
@ -49,7 +42,7 @@
But can you independently confirm it?</para>
</sect1>
<sect1 id="solution">
<sect1 xml:id="solution">
<title>The Solution</title>
<para>First, some crypto-relevant info theory:</para>
@ -73,20 +66,18 @@
not encrypted---as the outermost IP header must be if the
packet is to be routable.</para>
<sect2 id="MUST">
<sect2 xml:id="MUST">
<title>MUST</title>
<para>Ueli Maurer's <quote>Universal Statistical Test for Random
Bit Generators</quote>(<ulink
url="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">
<acronym>MUST</acronym></ulink>) quickly measures the entropy
of a sample. It uses a compression-like algorithm. <link
linkend="code">The code is given below</link> for a variant
Bit Generators</quote>(<link xlink:href="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf">
<acronym>MUST</acronym></link>) quickly measures the entropy
of a sample. It uses a compression-like algorithm. <link linkend="code">The code is given below</link> for a variant
which measures successive (~quarter megabyte) chunks of a
file.</para>
</sect2>
<sect2 id="tcpdump">
<sect2 xml:id="tcpdump">
<title>Tcpdump</title>
<para>We also need a way to capture the raw network data. A
@ -97,7 +88,7 @@
<para>The command:</para>
<screen><userinput><command>tcpdump</command> -c 4000 -s 10000 -w <replaceable>dumpfile.bin</replaceable></userinput></screen>
<screen><userinput>tcpdump -c 4000 -s 10000 -w dumpfile.bin</userinput></screen>
<para>will capture 4000 raw packets to
<replaceable>dumpfile.bin</replaceable>. Up to 10,000 bytes per
@ -105,7 +96,7 @@
</sect2>
</sect1>
<sect1 id="experiment">
<sect1 xml:id="experiment">
<title>The Experiment</title>
<para>Here is the experiment:</para>
@ -136,8 +127,8 @@
the <quote>normal</quote> connection has 29% (2.1) of the
expected value.</para>
<screen>&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w <replaceable>ipsecdemo.bin</replaceable></userinput>
&prompt.user; <userinput>uliscan <replaceable>ipsecdemo.bin</replaceable></userinput>
<screen>&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w ipsecdemo.bin</userinput>
&prompt.user; <userinput>uliscan ipsecdemo.bin</userinput>
Uliscan 21 Dec 98
L=8 256 258560
@ -154,7 +145,7 @@ Expected value for L=8 is 7.1836656
</procedure>
</sect1>
<sect1 id="caveat">
<sect1 xml:id="caveat">
<title>Caveat</title>
<para>This experiment shows that IPsec <emphasis>does</emphasis>
@ -168,7 +159,7 @@ Expected value for L=8 is 7.1836656
code.</para>
</sect1>
<sect1 id="IPsec">
<sect1 xml:id="IPsec">
<title>IPsec---Definition</title>
<para>Internet Protocol security extensions to IPv4; required for
@ -179,7 +170,7 @@ Expected value for L=8 is 7.1836656
message. IPsec encrypts everything between two hosts.</para>
</sect1>
<sect1 id="ipsec-install">
<sect1 xml:id="ipsec-install">
<title>Installing IPsec</title>
<para>Most of the modern versions of FreeBSD have IPsec support
@ -189,12 +180,11 @@ Expected value for L=8 is 7.1836656
&man.setkey.8; command.</para>
<para>A comprehensive guide on running IPsec on FreeBSD is
provided in <ulink
url="&url.books.handbook;/ipsec.html">FreeBSD
Handbook</ulink>.</para>
provided in <link xlink:href="&url.books.handbook;/ipsec.html">FreeBSD
Handbook</link>.</para>
</sect1>
<sect1 id="kernel">
<sect1 xml:id="kernel">
<title>src/sys/i386/conf/KERNELNAME</title>
<para>This needs to be present in the kernel config file in order
@ -205,13 +195,12 @@ Expected value for L=8 is 7.1836656
<programlisting>device bpf</programlisting>
</sect1>
<sect1 id="code">
<sect1 xml:id="code">
<title>Maurer's Universal Statistical Test (for block size=8
bits)</title>
<para>You can find the same code at <ulink
url="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
this link</ulink>.</para>
<para>You can find the same code at <link xlink:href="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt">
this link</link>.</para>
<programlisting>/*
ULISCAN.c ---blocksize of 8

40
en_US.ISO8859-1/articles/laptop/article.xml
View file

@ -1,10 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>FreeBSD on Laptops</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>FreeBSD on Laptops</title>
<abstract>
<para>FreeBSD works fine on most laptops, with a few caveats.
@ -13,7 +12,7 @@
discussed below.</para>
</abstract>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.linux;
&tm-attrib.microsoft;
@ -23,7 +22,7 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<para>FreeBSD is often thought of as a server operating system, but
it works just fine on the desktop, and if you want to use it on
@ -43,15 +42,15 @@
word <quote>&os;</quote> into a search engine of your
choice. Additionally there is a &os;-specific online database
which aims to give information on hardware issues with laptops,
<ulink url="http://laptop.bsdgroup.de/freebsd/">The &os;
Laptop Compatibility List</ulink>.</para>
<link xlink:href="http://laptop.bsdgroup.de/freebsd/">The &os;
Laptop Compatibility List</link>.</para>
<para>If you want to communicate with other &os; laptop users,
check out the &a.mobile.name; list. You can also get additional
information about using Laptops on &os; at
<ulink url="http://tuxmobil.org/mobile_bsd.html"></ulink>.</para>
<uri xlink:href="http://tuxmobil.org/mobile_bsd.html">http://tuxmobil.org/mobile_bsd.html</uri>.</para>
<sect1 id="xorg">
<sect1 xml:id="xorg">
<title>&xorg;</title>
<para>Recent versions of <application>&xorg;</application> work with most display adapters
@ -91,7 +90,7 @@
section.</para>
</sect1>
<sect1 id="modems">
<sect1 xml:id="modems">
<title>Modems</title>
<para>
Laptops usually come with internal (on-board) modems.
@ -99,7 +98,7 @@
<quote>winmodems</quote> whose
functionality is implemented in software, for which only &windows;
drivers are normally available (though a few drivers are beginning
to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the <filename role="package">comms/ltmdm</filename> port). If that is the case, you
to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the <package>comms/ltmdm</package> port). If that is the case, you
need to buy an external modem: the most compact option is
probably a PC Card (PCMCIA) modem, discussed below, but
serial or USB modems may be cheaper. Generally, regular
@ -108,16 +107,16 @@
</sect1>
<sect1 id="pcmcia">
<sect1 xml:id="pcmcia">
<title>PCMCIA (PC Card) devices</title>
<para> Most laptops come with PCMCIA (also called PC Card)
slots; these are supported fine under FreeBSD. Look through
your boot-up messages (using &man.dmesg.8;) and see whether these were
detected correctly (they should appear as
<devicename>pccard0</devicename>,
<devicename>pccard1</devicename> etc on devices like
<devicename>pcic0</devicename>).</para>
<filename>pccard0</filename>,
<filename>pccard1</filename> etc on devices like
<filename>pcic0</filename>).</para>
<para>&os;&nbsp;4.X supports 16-bit PCMCIA cards, and
&os;&nbsp;5.X supports both 16-bit and
@ -156,7 +155,7 @@
</sect1>
<sect1 id="power-management">
<sect1 xml:id="power-management">
<title>Power management</title>
@ -225,8 +224,7 @@
SC_NO_SUSPEND_VTYSWITCH</literal>
in your kernel configuration file and recompile your kernel.
Another workaround is to switch to a virtual console (using
<keycombo
action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo>
<keycombo action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo>
or another function key) and then execute &man.apm.8;.
You can automate this with &man.vidcontrol.1;, if you are
running &man.apmd.8;. Simply edit

165
en_US.ISO8859-1/articles/ldap-auth/article.xml
View file

@ -1,19 +1,14 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang="en">
<articleinfo>
<title>LDAP Authentication</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>LDAP Authentication</title>
<authorgroup>
<author>
<firstname>Toby</firstname>
<surname>Burress</surname>
<affiliation>
<author><personname><firstname>Toby</firstname><surname>Burress</surname></personname><affiliation>
<address><email>kurin@causa-sui.net</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<copyright>
@ -22,7 +17,7 @@
<holder>The FreeBSD Documentation Project</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -38,16 +33,16 @@
where many servers need the same user accounts, for example as a
replacement for <application>NIS</application>.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="preface">
<sect1 xml:id="preface">
<title>Preface</title>
<para>This document is intended to give the reader enough of an
understanding of LDAP to configure an LDAP server. This document will
attempt to provide an
explanation of <filename role="package">net/nss_ldap</filename>
and <filename role="package">security/pam_ldap</filename> for use with
explanation of <package>net/nss_ldap</package>
and <package>security/pam_ldap</package> for use with
client machines services for use with the LDAP server.</para>
<para>When finished, the reader should be able to configure and
@ -65,32 +60,28 @@
analysis.</para>
</sect1>
<sect1 id="ldap">
<sect1 xml:id="ldap">
<title>Configuring LDAP</title>
<para>LDAP stands for <quote>Lightweight Directory Access
Protocol</quote> and is a subset of the X.500 Directory Access
Protocol. Its most recent specifications are in <ulink
url="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</ulink> and
Protocol. Its most recent specifications are in <link xlink:href="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</link> and
friends. Essentially it is a database that expects to be read from
more often than it is written to.</para>
<para>The LDAP server <ulink
url="http://www.openldap.org/">OpenLDAP</ulink> will be used in the
<para>The LDAP server <link xlink:href="http://www.openldap.org/">OpenLDAP</link> will be used in the
examples in this document; while the principles here should be
generally applicable to many different servers, most of the
concrete administration is
<application>OpenLDAP</application>-specific. There are several
server versions in ports, for example <filename
role="package">net/openldap24-server</filename>. Client servers
will need the corresponding <filename
role="package">net/openldap24-client</filename> libraries.</para>
server versions in ports, for example <package>net/openldap24-server</package>. Client servers
will need the corresponding <package>net/openldap24-client</package> libraries.</para>
<para>There are (basically) two areas of the LDAP service which need
configuration. The first is setting up a server to receive
connections properly, and the second is adding entries to the
server's directory so that &os; tools know how to interact with it.</para>
<sect2 id="ldap-connect">
<sect2 xml:id="ldap-connect">
<title>Setting Up the Server for Connections</title>
<note>
@ -100,12 +91,12 @@
documentation.</para>
</note>
<sect3 id="ldap-connect-install">
<sect3 xml:id="ldap-connect-install">
<title>Installing <application>OpenLDAP</application></title>
<para>First, install <application>OpenLDAP</application>:</para>
<example id="oldap-install">
<example xml:id="oldap-install">
<title>Installing <application>OpenLDAP</application></title>
<screen>&prompt.root; <userinput>cd /usr/ports/net/openldap24-server</userinput>
@ -117,7 +108,7 @@
<application>OpenLDAP</application> libraries.</para>
</sect3>
<sect3 id="ldap-connect-config">
<sect3 xml:id="ldap-connect-config">
<title>Configuring <application>OpenLDAP</application></title>
<para>Next we must configure
@ -179,7 +170,7 @@ TLSCACertificateFile /path/to/your/cacert.crt</programlisting>
server. If you simply want a server that runs, you can create a
self-signed certificate with OpenSSL:</para>
<example id="genrsa">
<example xml:id="genrsa">
<title>Generating an RSA key</title>
<screen>&prompt.user; <userinput>openssl genrsa -out cert.key 1024</userinput>
@ -204,7 +195,7 @@ e is 65537 (0x10001)
<para>Finally, the certificate signing request needs to be
signed:</para>
<example id="self-sign">
<example xml:id="self-sign">
<title>Self-signing the certificate</title>
<screen>&prompt.user; <userinput>openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt</userinput>
@ -236,16 +227,13 @@ Getting Private key</screen>
ldap slapd 3261 7 tcp4 *:389 *:*</screen>
</sect3>
<sect3 id="ldap-connect-client">
<sect3 xml:id="ldap-connect-client">
<title>Configuring the Client</title>
<para>Install the <filename
role="package">net/openldap24-client</filename> port for the
<para>Install the <package>net/openldap24-client</package> port for the
<application>OpenLDAP</application> libraries. The client
machines will always have <application>OpenLDAP</application>
libraries since that is all <filename
role="package">security/pam_ldap</filename> and <filename
role="package">net/nss_ldap</filename> support, at least for the
libraries since that is all <package>security/pam_ldap</package> and <package>net/nss_ldap</package> support, at least for the
moment.</para>
<para>The configuration file for the
@ -283,7 +271,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting>
</sect3>
</sect2>
<sect2 id="ldap-database">
<sect2 xml:id="ldap-database">
<title>Entries in the Database</title>
<para>Authentication against an LDAP directory is generally
@ -300,7 +288,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting>
<para>The base entry for our database is
<literal>dc=example,dc=org</literal>. The default location for
users that most clients seem to expect is something like
<literal>ou=people,<replaceable>base</replaceable></literal>, so
<literal>ou=people,base</literal>, so
that is what will be used here. However keep in mind that this is
configurable.</para>
@ -366,7 +354,7 @@ cn: tuser</programlisting>
<para>To enter these into your database, you can use
<command>slapadd</command> or <command>ldapadd</command>
on a file containing these entries. Alternatively, you can use
<filename role="package">sysutils/ldapvi</filename>.</para>
<package>sysutils/ldapvi</package>.</para>
<para>The <command>ldapsearch</command> utility on the client machine
should now return these entries. If it does, your database is
@ -374,25 +362,21 @@ cn: tuser</programlisting>
</sect2>
</sect1>
<sect1 id="client">
<sect1 xml:id="client">
<title>Client Configuration</title>
<para>The client should already have
<application>OpenLDAP</application> libraries from <xref
linkend="ldap-connect-client"/>, but if you are installing several
client machines you will need to install <filename
role="package">net/openldap24-client</filename> on each of
<application>OpenLDAP</application> libraries from <xref linkend="ldap-connect-client"/>, but if you are installing several
client machines you will need to install <package>net/openldap24-client</package> on each of
them.</para>
<para>&os; requires two ports to be installed to authenticate
against an LDAP server, <filename
role="package">security/pam_ldap</filename> and <filename
role="package">net/nss_ldap</filename>.</para>
against an LDAP server, <package>security/pam_ldap</package> and <package>net/nss_ldap</package>.</para>
<sect2 id="client-auth">
<sect2 xml:id="client-auth">
<title>Authentication</title>
<para><filename role="package">security/pam_ldap</filename> is
<para><package>security/pam_ldap</package> is
configured via <filename>/usr/local/etc/ldap.conf</filename>.</para>
<note>
@ -410,7 +394,7 @@ cn: tuser</programlisting>
configuration parameters from
<filename>openldap/ldap.conf</filename> to the new
<filename>ldap.conf</filename>. Once this is done, we want to
tell <filename role="package">security/pam_ldap</filename> what to
tell <package>security/pam_ldap</package> what to
look for on the directory server.</para>
<para>We are identifying our users with the <literal>uid</literal>
@ -418,21 +402,20 @@ cn: tuser</programlisting>
<literal>pam_login_attribute</literal> directive in
<filename>ldap.conf</filename>:</para>
<example id="set-pam-login-attr">
<example xml:id="set-pam-login-attr">
<title>Setting <literal>pam_login_attribute</literal></title>
<programlisting>pam_login_attribute uid</programlisting>
</example>
<para>With this set, <filename
role="package">security/pam_ldap</filename> will search the entire
<para>With this set, <package>security/pam_ldap</package> will search the entire
LDAP directory under <literal>base</literal> for the value
<literal>uid=<replaceable>username</replaceable></literal>. If it
<literal>uid=username</literal>. If it
finds one and only one entry, it will attempt to bind as that user
with the password it was given. If it binds correctly, then it
will allow access. Otherwise it will fail.</para>
<sect3 id="client-auth-pam">
<sect3 xml:id="client-auth-pam">
<title>PAM</title>
<para>PAM, which stands for <quote>Pluggable Authentication
@ -501,7 +484,7 @@ cn: tuser</programlisting>
<para>Your <filename>pam.d/sshd</filename> might then end up
looking like this:</para>
<example id="pam">
<example xml:id="pam">
<title>Sample <filename>pam.d/sshd</filename></title>
<programlisting>auth required pam_nologin.so no_warn
@ -525,7 +508,7 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a
</sect3>
</sect2>
<sect2 id="client-nss">
<sect2 xml:id="client-nss">
<title>Name Service Switch</title>
<para><application>NSS</application> is the service that maps
@ -539,9 +522,8 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a
tell <application>NSS</application> to look there when
queried.</para>
<para>The <filename role="package">net/nss_ldap</filename> port
does this. It uses the same configuration file as <filename
role="package">security/pam_ldap</filename>, and should not need
<para>The <package>net/nss_ldap</package> port
does this. It uses the same configuration file as <package>security/pam_ldap</package>, and should not need
any extra parameters once it is installed. Instead, what is left
is simply to edit <filename>/etc/nsswitch.conf</filename> to take
advantage of the directory. Simply replace the following
@ -562,7 +544,7 @@ passwd: files ldap</programlisting>
authentication.</para>
</sect2>
<sect2 id="caveats">
<sect2 xml:id="caveats">
<title>Caveats</title>
<para>Unfortunately, as of the time this was written &os; did not
@ -570,10 +552,9 @@ passwd: files ldap</programlisting>
this, most administrators are left to implement a solution
themselves. I provide some examples here. Note that if you write
your own password change script, there are some security issues
you should be made aware of; see <xref
linkend="security-passwd"/></para>
you should be made aware of; see <xref linkend="security-passwd"/></para>
<example id="chpw-shell">
<example xml:id="chpw-shell">
<title>Shell script for changing passwords</title>
<programlisting><![CDATA[#!/bin/sh
@ -611,7 +592,7 @@ ldappasswd -D uid="$USER",ou=people,dc=example,dc=org \
that can change LDAP passwords. It sees use both on the command
line, and on the web.</para>
<example id="chpw-ruby">
<example xml:id="chpw-ruby">
<title>Ruby script for changing passwords</title>
<programlisting><![CDATA[require 'ldap'
@ -658,7 +639,7 @@ conn.modify(luser, [replace])]]></programlisting>
</sect2>
</sect1>
<sect1 id="secure">
<sect1 xml:id="secure">
<title>Security Considerations</title>
<para>Now that your machines (and possibly other services) are
@ -672,20 +653,20 @@ conn.modify(luser, [replace])]]></programlisting>
continually review your configuration and procedures for
improvements.</para>
<sect2 id="secure-readonly">
<sect2 xml:id="secure-readonly">
<title>Setting attributes read-only</title>
<para>Several attributes in LDAP should be read-only. If left
writable by the user, for example, a user could change his
<literal>uidNumber</literal> attribute to <literal>0</literal> and
get <username>root</username> access!</para>
get <systemitem class="username">root</systemitem> access!</para>
<para>To begin with, the <literal>userPassword</literal> attribute
should not be world-readable. By default, anyone who can connect
to the LDAP server can read this attribute. To disable this, put
the following in <filename>slapd.conf</filename>:</para>
<example id="hide-userpass">
<example xml:id="hide-userpass">
<title>Hide passwords</title>
<programlisting>access to dn.subtree="ou=people,dc=example,dc=org"
@ -709,7 +690,7 @@ access to *
changes), such as <literal>uidNumber</literal>. To close this
hole, modify the above to</para>
<example id="attrib-readonly">
<example xml:id="attrib-readonly">
<title>Read-only attributes</title>
<programlisting>access to dn.subtree="ou=people,dc=example,dc=org"
@ -730,25 +711,25 @@ access to *
users.</para>
</sect2>
<sect2 id="secure-root">
<title><username>Root</username> account definition</title>
<sect2 xml:id="secure-root">
<title><systemitem class="username">Root</systemitem> account definition</title>
<para>Often the <username>root</username> or manager account for
<para>Often the <systemitem class="username">root</systemitem> or manager account for
the LDAP service will be defined in the configuration file.
<application>OpenLDAP</application> supports this, for example,
and it works, but it can lead to trouble if
<filename>slapd.conf</filename> is compromised. It may be better
to use this only to bootstrap yourself into LDAP, and then define
a <username>root</username> account there.</para>
a <systemitem class="username">root</systemitem> account there.</para>
<para>Even better is to define accounts that have limited
permissions, and omit a <username>root</username> account entirely.
permissions, and omit a <systemitem class="username">root</systemitem> account entirely.
For example, users to can add or remove user accounts are added to
one group, but they cannot themselves change the membership of
this group. Such a security policy would help mitigate the effects
of a leaked password.</para>
<sect3 id="manager-acct">
<sect3 xml:id="manager-acct">
<title>Creating a management group</title>
<para>Say you want your IT department to be able to change home
@ -756,7 +737,7 @@ access to *
to add or remove users. The way to do this is to add a group
for these admins:</para>
<example id="manager-acct-dn">
<example xml:id="manager-acct-dn">
<title>Creating a management group</title>
<programlisting>dn: cn=homemanagement,dc=example,dc=org
@ -771,7 +752,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting>
<para>And then change the permissions attributes in
<filename>slapd.conf</filename>:</para>
<example id="management-acct-acl">
<example xml:id="management-acct-acl">
<title>ACLs for a home directory management group</title>
<programlisting>access to dn.subtree="ou=people,dc=example,dc=org"
@ -780,19 +761,19 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting>
dnattr=memberUid write</programlisting>
</example>
<para>Now <username>tuser</username> and <username>user2</username>
<para>Now <systemitem class="username">tuser</systemitem> and <systemitem class="username">user2</systemitem>
can change other users' home directories.</para>
<para>In this example we've given a subset of administrative
power to certain users without giving them power in other
domains. The idea is that soon no single user account has the
power of a <username>root</username> account, but every power
root had is had by at least one user. The <username>root</username>
power of a <systemitem class="username">root</systemitem> account, but every power
root had is had by at least one user. The <systemitem class="username">root</systemitem>
account then becomes unnecessary and can be removed.</para>
</sect3>
</sect2>
<sect2 id="security-passwd">
<sect2 xml:id="security-passwd">
<title>Password storage</title>
<para>By default <application>OpenLDAP</application> will store
@ -807,41 +788,41 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting>
</sect2>
</sect1>
<appendix id="useful">
<appendix xml:id="useful">
<title>Useful Aids</title>
<para>There are a few other programs that might be useful,
particularly if you have many users and do not want to configure
everything manually.</para>
<para><filename role="package">security/pam_mkhomedir</filename> is
<para><package>security/pam_mkhomedir</package> is
a PAM module that always succeeds; its purpose is to create home
directories for users which do not have them. If you have dozens of
client servers and hundreds of users, it is much easier to use this
and set up skeleton directories than to prepare every home
directory.</para>
<para><filename role="package">sysutils/cpu</filename> is a
<para><package>sysutils/cpu</package> is a
&man.pw.8;-like utility that can be used to manage users in the LDAP
directory. You can call it directly, or wrap scripts around it. It
can handle both TLS (with the <option>-x</option> flag) and
SSL (directly).</para>
<para><filename role="package">sysutils/ldapvi</filename> is a great
<para><package>sysutils/ldapvi</package> is a great
utility for editing LDAP values in an LDIF-like syntax. The
directory (or subsection of the directory) is presented in the
editor chosen by the <envar>EDITOR</envar> environment variable.
This makes it easy to enable large-scale changes in the directory
without having to write a custom tool.</para>
<para><filename role="package">security/openssh-portable</filename>
<para><package>security/openssh-portable</package>
has the ability to contact an LDAP server to verify
<application>SSH</application> keys. This is extremely nice if you
have many servers and do not want to copy your public keys across
all of them.</para>
</appendix>
<appendix id="ssl-ca">
<appendix xml:id="ssl-ca">
<title><application>OpenSSL</application> Certificates For LDAP</title>
<para>If you are hosting two or more LDAP servers, you will probably
@ -859,7 +840,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting>
self-signed certificate and key. The steps for this again
are</para>
<example id="make-cert">
<example xml:id="make-cert">
<title>Creating a certificate</title>
<screen>&prompt.user; <userinput>openssl genrsa -out root.key 1024</userinput>
@ -890,7 +871,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting>
<option>-CAkey</option> instead of
<option>-signkey</option>:</para>
<example id="ca-sign">
<example xml:id="ca-sign">
<title>Signing as a certificate authority</title>
<screen>&prompt.user; <userinput>openssl x509 -req -days 1024 \

133
en_US.ISO8859-1/articles/linux-comparison/article.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!--
Copyright (c) 2005 Dru Lavigne
@ -34,18 +33,13 @@ Copyright (c) 2005 Dru Lavigne
$FreeBSD$
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>FreeBSD: An Open Source Alternative to Linux</title>
<article lang='en'>
<articleinfo>
<title>FreeBSD: An Open Source Alternative to Linux</title>
<author>
<firstname>Dru</firstname>
<surname>Lavigne</surname>
<affiliation>
<author><personname><firstname>Dru</firstname><surname>Lavigne</surname></personname><affiliation>
<address><email>dru@isecom.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2005</year>
@ -56,7 +50,7 @@ Copyright (c) 2005 Dru Lavigne
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.linux;
&tm-attrib.unix;
@ -72,9 +66,9 @@ Copyright (c) 2005 Dru Lavigne
provides a starting point for those interested in exploring
Open Source alternatives to &linux;.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>&os; is a &unix; like operating system based on the
@ -102,8 +96,7 @@ Copyright (c) 2005 Dru Lavigne
roots of Unix development.
<footnote>
<para>See also <ulink
url="http://www.oreilly.com/catalog/opensources/book/kirkmck.html"></ulink>
<para>See also <uri xlink:href="http://www.oreilly.com/catalog/opensources/book/kirkmck.html">http://www.oreilly.com/catalog/opensources/book/kirkmck.html</uri>
for a brief history.</para>
</footnote>
@ -114,8 +107,7 @@ Copyright (c) 2005 Dru Lavigne
addressed quickly by the security team. When new utilities
or kernel features are added, the user simply needs to read
one file, the Release Notes, which is publicly available on
the main page of the <ulink
url="http://www.FreeBSD.org">&os; website</ulink>.</para>
the main page of the <link xlink:href="http://www.FreeBSD.org">&os; website</link>.</para>
</listitem>
<listitem>
@ -142,11 +134,11 @@ Copyright (c) 2005 Dru Lavigne
<para>While both &os; and &linux; use an Open Source
licensing model, the actual licenses used differ. The Linux
kernel is under the <ulink url="http://www.opensource.org/licenses/gpl-license.php">GPL license</ulink> while
&os; uses the <ulink url="http://www.opensource.org/licenses/bsd-license.php">BSD license</ulink>. These,
kernel is under the <link xlink:href="http://www.opensource.org/licenses/gpl-license.php">GPL license</link> while
&os; uses the <link xlink:href="http://www.opensource.org/licenses/bsd-license.php">BSD license</link>. These,
and other Open Source licenses, are described in more detail
at the website of the <ulink url="http://www.opensource.org/licenses/">Open Source
Initiative</ulink>.</para>
at the website of the <link xlink:href="http://www.opensource.org/licenses/">Open Source
Initiative</link>.</para>
<para>The driving philosophy behind the GPL is to ensure that
code remains Open Source; it does this by placing
@ -157,13 +149,12 @@ Copyright (c) 2005 Dru Lavigne
<footnote>
<para>For a fairly unbiased view of the merits of each
license, see <ulink
url="http://en.wikipedia.org/wiki/BSD_and_GPL_licensing"></ulink>.</para>
license, see <uri xlink:href="http://en.wikipedia.org/wiki/BSD_and_GPL_licensing">http://en.wikipedia.org/wiki/BSD_and_GPL_licensing</uri>.</para>
</footnote>
Having
stable and reliable code under the attractive BSD license
means that many operating systems, such as <ulink url="http://developer.apple.com/darwin/projects/darwin/faq.html">Apple OS X</ulink>
means that many operating systems, such as <link xlink:href="http://developer.apple.com/darwin/projects/darwin/faq.html">Apple OS X</link>
are based on FreeBSD code. It also means that if you choose
to use BSD licensed code in your own projects, you can do so
without threat of future legal liability.</para>
@ -171,10 +162,10 @@ Copyright (c) 2005 Dru Lavigne
</orderedlist>
</sect1>
<sect1 id="freebsd-features">
<sect1 xml:id="freebsd-features">
<title>&os; Features</title>
<sect2 id="freebsd-features-platforms">
<sect2 xml:id="freebsd-features-platforms">
<title>Supported Platforms</title>
<para>&os; has gained a reputation as a secure, stable,
@ -210,8 +201,8 @@ Copyright (c) 2005 Dru Lavigne
third-party applications,
<footnote>
<para>Using <ulink url="&url.base;/ports">FreeBSD's ports
collection</ulink>: software installation is as easy as
<para>Using <link xlink:href="&url.base;/ports">FreeBSD's ports
collection</link>: software installation is as easy as
<command>pkg_add -r application_name</command>.</para>
</footnote>
@ -222,23 +213,20 @@ Copyright (c) 2005 Dru Lavigne
&os; as a desktop. The most notable are:</para>
<itemizedlist>
<listitem><para><ulink
url="http://www.desktopbsd.net">DesktopBSD</ulink> which
<listitem><para><link xlink:href="http://www.desktopbsd.net">DesktopBSD</link> which
aims at being a stable and powerful operating system for
desktop users.</para></listitem>
<listitem><para><ulink
url="http://www.freesbie.org">FreeSBIE</ulink> which
<listitem><para><link xlink:href="http://www.freesbie.org">FreeSBIE</link> which
provides a LiveCD of &os;.</para></listitem>
<listitem><para><ulink
url="http://www.pcbsd.com">PC-BSD</ulink> which provides an
<listitem><para><link xlink:href="http://www.pcbsd.com">PC-BSD</link> which provides an
easy-to-use GUI installer for &os; aimed at the desktop
user.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="freebsd-features-frameworks">
<sect2 xml:id="freebsd-features-frameworks">
<title>Extensible Frameworks</title>
<para>&os; provides many extensible frameworks to easily
@ -306,7 +294,7 @@ Copyright (c) 2005 Dru Lavigne
<varlistentry>
<term>MAC</term>
<listitem><para><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/mac.html">MAC</ulink>,
<listitem><para><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/mac.html">MAC</link>,
or Mandatory Access Control, provides fine-tuned access to
files and is meant to augment traditional operating system
authorization provided by file permissions. Since MAC is
@ -331,7 +319,7 @@ Copyright (c) 2005 Dru Lavigne
<varlistentry>
<term>PAM</term>
<listitem><para>Like &linux;, &os; provides support for <ulink url="&url.base;/doc/en_US.ISO8859-1/articles/pam/">PAM</ulink>,
<listitem><para>Like &linux;, &os; provides support for <link xlink:href="&url.base;/doc/en_US.ISO8859-1/articles/pam/">PAM</link>,
Pluggable Authentication Modules. This allows an administrator
to augment the traditional &unix; username/password
authentication model. &os; provides modules to integrate
@ -353,13 +341,12 @@ Copyright (c) 2005 Dru Lavigne
</sect2>
</sect1>
<sect1 id="freebsd-security">
<sect1 xml:id="freebsd-security">
<title>Security</title>
<para>Security is very important to the <ulink
url="&url.base;/doc/en_US.ISO8859-1/articles/releng/">FreeBSD
<para>Security is very important to the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/articles/releng/">FreeBSD
Release
Engineering Team</ulink>. This
Engineering Team</link>. This
manifests itself in several concrete areas:</para>
<itemizedlist>
@ -369,17 +356,15 @@ Release
resolving known security issues. Full information regarding
FreeBSD's security handling procedures and where to find
security information is available at
<ulink url="http://www.FreeBSD.org/security/"></ulink>.</para></listitem>
<uri xlink:href="http://www.FreeBSD.org/security/">http://www.FreeBSD.org/security/</uri>.</para></listitem>
<listitem><para>One of the problems associated with Open Source
software is the sheer volume of available applications. There
are literally tens of thousands of Open Source application projects
each with varying levels of responsiveness to security
incidents. &os; has met this challenge head-on with <ulink
url="http://www.vuxml.org/freebsd/">VuXML</ulink>. All software
incidents. &os; has met this challenge head-on with <link xlink:href="http://www.vuxml.org/freebsd/">VuXML</link>. All software
shipped with the FreeBSD operating system as well any software
available in the <ulink
url="&url.base;/ports/">Ports Collection</ulink>
available in the <link xlink:href="&url.base;/ports/">Ports Collection</link>
is compared to a database of known, unresolved
vulnerabilities. An administrator can use the &man.portaudit.1;
utility to quickly determine if any software on a &os;
@ -418,13 +403,13 @@ Release
</itemizedlist>
</sect1>
<sect1 id="freebsd-support">
<sect1 xml:id="freebsd-support">
<title>Support</title>
<para>Like &linux;, &os; offers many venues for support, both
freely available and commercial.</para>
<sect2 id="freebsd-support-free">
<sect2 xml:id="freebsd-support-free">
<title>Free Offerings</title>
<itemizedlist>
@ -433,26 +418,23 @@ Release
operating systems, and the documentation is available both
as part of the operating system and on the Internet. Manual
pages are clear, concise and provide working
examples. <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/">
The FreeBSD Handbook</ulink>
examples. <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/">
The FreeBSD Handbook</link>
provides background information and configuration examples
for nearly every task one would wish to complete using
&os;.</para></listitem>
<listitem><para>&os; provides many support <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">mailing
lists</ulink>.
<listitem><para>&os; provides many support <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">mailing
lists</link>.
where answers are archived and fully searchable. If you have
a question that wasn't addressed by the Handbook, it most
likely has already been answered on a mailing list. The
Handbook and mailing lists are also available in several
languages, all of which are easily accessible from
<ulink url="http://www.FreeBSD.org"></ulink>.</para></listitem>
<uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>.</para></listitem>
<listitem><para>There are many FreeBSD IRC channels, forums
and user groups. See <ulink
url="http://www.FreeBSD.org/support.html"></ulink> for a
and user groups. See <uri xlink:href="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</uri> for a
selection.</para></listitem>
</itemizedlist>
@ -461,7 +443,7 @@ Release
geographic location to <email>freebsd-jobs@FreeBSD.org</email>.</para>
</sect2>
<sect2 id="freebsd-support-commercial">
<sect2 xml:id="freebsd-support-commercial">
<title>Commercial Offerings</title>
<para>There are many vendors who provide commercial &os;
@ -470,30 +452,26 @@ Release
<itemizedlist>
<listitem><para>The Commercial Vendors page at the &os;
site: <ulink
url="http://www.FreeBSD.org/commercial/"></ulink></para></listitem>
site: <uri xlink:href="http://www.FreeBSD.org/commercial/">http://www.FreeBSD.org/commercial/</uri></para></listitem>
<listitem><para>FreeBSDMall, who have been selling support contracts
for nearly 10 years.
<ulink url="http://www.freebsdmall.com"></ulink></para></listitem>
<uri xlink:href="http://www.freebsdmall.com">http://www.freebsdmall.com</uri></para></listitem>
<listitem><para>The BSDTracker Database at: <ulink
url="http://www.nycbug.org/index.php?NAV=BSDTracker"></ulink></para></listitem>
<listitem><para>The BSDTracker Database at: <uri xlink:href="http://www.nycbug.org/index.php?NAV=BSDTracker">http://www.nycbug.org/index.php?NAV=BSDTracker</uri></para></listitem>
</itemizedlist>
<para>There is also an initiative to provide certification of BSD
system administrators. <ulink
url="http://www.bsdcertification.org"></ulink>.</para>
system administrators. <uri xlink:href="http://www.bsdcertification.org">http://www.bsdcertification.org</uri>.</para>
<para>If your project requires Common Criteria certification,
&os; includes the <ulink
url="http://www.trustedbsd.org">TrustedBSD</ulink> MAC
&os; includes the <link xlink:href="http://www.trustedbsd.org">TrustedBSD</link> MAC
framework to ease the certification process.</para>
</sect2>
</sect1>
<sect1 id="freebsd-advantages">
<sect1 xml:id="freebsd-advantages">
<title>Advantages to Choosing &os;</title>
<para>There are many advantages to including &os; solutions in
@ -510,8 +488,7 @@ Release
<footnote>
<para>In addition, all code is browsable through a
web-interface: <ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/"></ulink>.</para>
web-interface: <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/">http://www.FreeBSD.org/cgi/cvsweb.cgi/</uri>.</para>
</footnote>
for all releases going back to the original
@ -525,19 +502,17 @@ Release
<footnote>
<para>An interesting overview of the evolving Linux
development model can be found at <ulink
url="http://linuxdevices.com/articles/AT4155251624.html"></ulink>.</para>
development model can be found at <uri xlink:href="http://linuxdevices.com/articles/AT4155251624.html">http://linuxdevices.com/articles/AT4155251624.html</uri>.</para>
</footnote>
</para></listitem>
<listitem><para>In-house developers also have full access to
FreeBSD's <ulink
url="http://www.gnu.org/software/gnats/">GNATS</ulink>
FreeBSD's <link xlink:href="http://www.gnu.org/software/gnats/">GNATS</link>
bug-tracking database. They are able to query and track
existing bugs as well as submit their own patches for approval
and possible committal into the FreeBSD base code.
<ulink url="http://www.FreeBSD.org/support.html#gnats"></ulink></para></listitem>
<uri xlink:href="http://www.FreeBSD.org/support.html#gnats">http://www.FreeBSD.org/support.html#gnats</uri></para></listitem>
<listitem><para>The BSD license allows you to freely modify the
code to suit your business purposes. Unlike the GPL, there are
@ -546,7 +521,7 @@ Release
</itemizedlist>
</sect1>
<sect1 id="freebsd-conclusion">
<sect1 xml:id="freebsd-conclusion">
<title>Conclusion</title>
<para>&os; is a mature &unix;-like operating system which

245
en_US.ISO8859-1/articles/linux-emulation/article.xml
View file

@ -1,24 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>&linux; emulation in &os;</title>
<article lang='en'>
<articleinfo>
<title>&linux; emulation in &os;</title>
<author>
<firstname>Roman</firstname>
<surname>Divacky</surname>
<affiliation>
<author><personname><firstname>Roman</firstname><surname>Divacky</surname></personname><affiliation>
<address><email>rdivacky@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.adobe;
&tm-attrib.ibm;
&tm-attrib.freebsd;
@ -52,9 +45,9 @@
the emulation development team, are working on making the
&linux; 2.6 emulation the default emulation layer in &os;.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>In the last few years the open source &unix; based operating systems
@ -79,7 +72,7 @@
part of this project.</para>
</sect1>
<sect1 id="inside">
<sect1 xml:id="inside">
<title>A look inside&hellip;</title>
<para>In this section we are going to describe every operating system in
@ -89,7 +82,7 @@
subsection we talk about how &unix; on &unix; emulation could be done
in general.</para>
<sect2 id="what-is-unix">
<sect2 xml:id="what-is-unix">
<title>What is &unix;</title>
<para>&unix; is an operating system with a long history that has
@ -110,7 +103,7 @@
&unix; characteristics.</para>
</sect2>
<sect2 id="tech-details">
<sect2 xml:id="tech-details">
<title>Technical details</title>
<para>Every running program constitutes a process that represents a state
@ -122,7 +115,7 @@
provides a standard unified &unix; API to the user space. The most
important ones are covered below.</para>
<sect3 id="kern-proc-comm">
<sect3 xml:id="kern-proc-comm">
<title>Communication between kernel and user space process</title>
<para>Common &unix; API defines a syscall as a way to issue commands
@ -145,7 +138,7 @@
(division by zero).</para>
</sect3>
<sect3 id="proc-proc-comm">
<sect3 xml:id="proc-proc-comm">
<title>Communication between processes</title>
<para>There are other APIs (System V IPC, shared memory etc.) but the
@ -155,7 +148,7 @@
in a predefined action that cannot be altered or ignored.</para>
</sect3>
<sect3 id="proc-mgmt">
<sect3 xml:id="proc-mgmt">
<title>Process management</title>
<para>Kernel instances are processed first in the system (so called
@ -170,7 +163,7 @@
defined parent (identified by its PID).</para>
</sect3>
<sect3 id="thread-mgmt">
<sect3 xml:id="thread-mgmt">
<title>Thread management</title>
<para>Traditional &unix; does not define any API nor implementation
@ -218,7 +211,7 @@
</sect3>
</sect2>
<sect2 id="what-is-freebsd">
<sect2 xml:id="what-is-freebsd">
<title>What is &os;?</title>
<para>The &os; project is one of the oldest open source operating
@ -293,7 +286,7 @@
<para>More info about the &os; operating system can be found
at [2].</para>
<sect3 id="freebsd-tech-details">
<sect3 xml:id="freebsd-tech-details">
<title>Technical details</title>
<para>&os; is traditional flavor of &unix; in the sense of dividing the
@ -305,7 +298,7 @@
only exists there but the concept is similar on other architectures.
The information was taken from [1] and the source code.</para>
<sect4 id="freebsd-sys-entries">
<sect4 xml:id="freebsd-sys-entries">
<title>System entries</title>
<para>&os; has an abstraction called an execution class loader,
@ -320,7 +313,7 @@
kernel-space and the user-space at once.</para>
</sect4>
<sect4 id="freebsd-syscalls">
<sect4 xml:id="freebsd-syscalls">
<title>Syscalls</title>
<para>Syscalls on &os; are issued by executing interrupt
@ -349,7 +342,7 @@
parameters.</para>
</sect4>
<sect4 id="freebsd-traps">
<sect4 xml:id="freebsd-traps">
<title>Traps</title>
<para>Handling of traps in &os; is similar to the handling of
@ -363,7 +356,7 @@
<literal>userret()</literal>.</para>
</sect4>
<sect4 id="freebsd-exits">
<sect4 xml:id="freebsd-exits">
<title>Exits</title>
<para>Exits from kernel to userspace happen using the assembler
@ -372,7 +365,7 @@
status from the stack and returns to the userspace.</para>
</sect4>
<sect4 id="freebsd-unix-primitives">
<sect4 xml:id="freebsd-unix-primitives">
<title>&unix; primitives</title>
<para>&os; operating system adheres to the traditional &unix; scheme,
@ -419,7 +412,7 @@
</sect3>
</sect2>
<sect2 id="what-is-linux">
<sect2 xml:id="what-is-linux">
<title>What is &linux;</title>
<para>&linux; is a &unix;-like kernel originally developed by Linus
@ -453,7 +446,7 @@
<para>More information can be obtained from [4].</para>
<sect3 id="linux-tech-details">
<sect3 xml:id="linux-tech-details">
<title>Technical details</title>
<para>&linux; follows the traditional &unix; scheme of dividing the run
@ -463,7 +456,7 @@
&linux;&nbsp;2.6 on the &i386; architecture. This information was
taken from [3].</para>
<sect4 id="linux-syscalls">
<sect4 xml:id="linux-syscalls">
<title>Syscalls</title>
<para>Syscalls in &linux; are performed (in userspace) using
@ -483,22 +476,22 @@
<orderedlist>
<listitem>
<para>parameter -> <varname>%ebx</varname></para>
<para>parameter -&gt; <varname>%ebx</varname></para>
</listitem>
<listitem>
<para>parameter -> <varname>%ecx</varname></para>
<para>parameter -&gt; <varname>%ecx</varname></para>
</listitem>
<listitem>
<para>parameter -> <varname>%edx</varname></para>
<para>parameter -&gt; <varname>%edx</varname></para>
</listitem>
<listitem>
<para>parameter -> <varname>%esi</varname></para>
<para>parameter -&gt; <varname>%esi</varname></para>
</listitem>
<listitem>
<para>parameter -> <varname>%edi</varname></para>
<para>parameter -&gt; <varname>%edi</varname></para>
</listitem>
<listitem>
<para>parameter -> <varname>%ebp</varname></para>
<para>parameter -&gt; <varname>%ebp</varname></para>
</listitem>
</orderedlist>
@ -507,7 +500,7 @@
syscall).</para>
</sect4>
<sect4 id="linux-traps">
<sect4 xml:id="linux-traps">
<title>Traps</title>
<para>The trap handlers are introduced in
@ -516,7 +509,7 @@
where handling of the traps happens.</para>
</sect4>
<sect4 id="linux-exits">
<sect4 xml:id="linux-exits">
<title>Exits</title>
<para>Return from the syscall is managed by syscall &man.exit.3;,
@ -526,7 +519,7 @@
stack and the process returns to the userspace.</para>
</sect4>
<sect4 id="linux-unix-primitives">
<sect4 xml:id="linux-unix-primitives">
<title>&unix; primitives</title>
<para>In the 2.6 version, the &linux; operating system redefined some
@ -648,7 +641,7 @@
</sect3>
</sect2>
<sect2 id="what-is-emu">
<sect2 xml:id="what-is-emu">
<title>What is emulation</title>
<para>According to a dictionary definition, emulation is the ability of
@ -719,7 +712,7 @@
</sect2>
</sect1>
<sect1 id="freebsd-emulation">
<sect1 xml:id="freebsd-emulation">
<title>Emulation</title>
<sect2>
@ -763,14 +756,14 @@
only things necessary to implement the &linux; emulation layer.</para>
</sect2>
<sect2 id="freebsd-common-primitives">
<sect2 xml:id="freebsd-common-primitives">
<title>Common primitives in the &os; kernel</title>
<para>Emulation layers need some support from the operating system. I am
going to describe some of the supported primitives in the &os;
operating system.</para>
<sect3 id="freebsd-locking-primitives">
<sect3 xml:id="freebsd-locking-primitives">
<title>Locking primitives</title>
<para>Contributed by: &a.attilio.email;</para>
@ -799,7 +792,7 @@
you should really check the linked manpage (where possible) for
more detailed explanations.</para>
<sect4 id="freebsd-atomic-op">
<sect4 xml:id="freebsd-atomic-op">
<title>Atomic operations and memory barriers</title>
<para>Atomic operations are implemented through a set of functions
@ -828,7 +821,7 @@
mutexes).</para>
</sect4>
<sect4 id="freebsd-refcounts">
<sect4 xml:id="freebsd-refcounts">
<title>Refcounts</title>
<para>Refcounts are interfaces for handling reference counters.
@ -843,7 +836,7 @@
existing API.</para>
</sect4>
<sect4 id="freebsd-locks">
<sect4 xml:id="freebsd-locks">
<title>Locks</title>
<para>&os; kernel has huge classes of locks. Every lock is defined
@ -869,7 +862,7 @@
</note>
</sect4>
<sect4 id="freebsd-spinlocks">
<sect4 xml:id="freebsd-spinlocks">
<title>Spinning locks</title>
<para>Spin locks let waiters to spin until they cannot acquire the
@ -884,7 +877,7 @@
requested (explained later).</para>
</sect4>
<sect4 id="freebsd-blocking">
<sect4 xml:id="freebsd-blocking">
<title>Blocking</title>
<para>Block locks let waiters to be descheduled and blocked until
@ -896,7 +889,7 @@
particular conditions are met.</para>
</sect4>
<sect4 id="freebsd-sleeping">
<sect4 xml:id="freebsd-sleeping">
<title>Sleeping</title>
<para>Sleep locks let waiters to be descheduled and fall asleep
@ -958,7 +951,7 @@
supported by mutexes and lockmgrs.</para>
</sect4>
<sect4 id="freebsd-scheduling">
<sect4 xml:id="freebsd-scheduling">
<title>Scheduling barriers</title>
<para>Scheduling barriers are intended to be used in order to drive
@ -983,7 +976,7 @@
with locking debugging tools (as &man.witness.4;).</para>
</sect4>
<sect4 id="freebsd-critical">
<sect4 xml:id="freebsd-critical">
<title>Critical sections</title>
<para>The &os; kernel has been made preemptive basically to deal with
@ -1002,7 +995,7 @@
brings.</para>
</sect4>
<sect4 id="freebsd-schedpin">
<sect4 xml:id="freebsd-schedpin">
<title>sched_pin/sched_unpin</title>
<para>Another way to deal with preemption is the
@ -1017,7 +1010,7 @@
as a too strong condition for our code.</para>
</sect4>
<sect4 id="freebsd-schedbind">
<sect4 xml:id="freebsd-schedbind">
<title>sched_bind/sched_unbind</title>
<para><function>sched_bind</function> is an API used in order to bind
@ -1034,7 +1027,7 @@
</sect4>
</sect3>
<sect3 id="freebsd-proc">
<sect3 xml:id="freebsd-proc">
<title>Proc structure</title>
<para>Various emulation layers sometimes require some additional
@ -1055,7 +1048,7 @@
whether the process belongs to our emulation layer. The code
typically looks like:</para>
<programlisting>if (__predict_true(p->p_sysent != &amp;elf_&linux;_sysvec))
<programlisting>if (__predict_true(p-&gt;p_sysent != &amp;elf_&linux;_sysvec))
return;</programlisting>
<para>As you can see, we effectively use the
@ -1067,7 +1060,7 @@
on i386.</para>
</sect3>
<sect3 id="freebsd-vfs">
<sect3 xml:id="freebsd-vfs">
<title>VFS</title>
<para>The &os; VFS subsystem is very complex but the &linux; emulation
@ -1079,7 +1072,7 @@
an ordinary file. A file handler contains a pointer to its vnode.
More then one file handler can point to the same vnode.</para>
<sect4 id="freebsd-namei">
<sect4 xml:id="freebsd-namei">
<title>namei</title>
<para>The &man.namei.9; routine is a central entry point to pathname
@ -1092,7 +1085,7 @@
performance is very critical.</para>
</sect4>
<sect4 id="freebsd-vn">
<sect4 xml:id="freebsd-vn">
<title>vn_fullpath</title>
<para>The &man.vn.fullpath.9; function takes the best effort to
@ -1104,7 +1097,7 @@
Linuxulator.</para>
</sect4>
<sect4 id="freebsd-vnode">
<sect4 xml:id="freebsd-vnode">
<title>Vnode operations</title>
<itemizedlist>
@ -1151,7 +1144,7 @@
</itemizedlist>
</sect4>
<sect4 id="freebsd-file-handler">
<sect4 xml:id="freebsd-file-handler">
<title>File handler operations</title>
<itemizedlist>
@ -1174,7 +1167,7 @@
</sect2>
</sect1>
<sect1 id="md">
<sect1 xml:id="md">
<title>&linux; emulation layer -MD part</title>
<para>This section deals with implementation of &linux; emulation layer in
@ -1186,7 +1179,7 @@
independent part of the Linuxulator. This section only covers i386 and ELF
handling. A.OUT is obsolete and untested.</para>
<sect2 id="syscall-handling">
<sect2 xml:id="syscall-handling">
<title>Syscall handling</title>
<para>Syscall handling is mostly written in
@ -1195,7 +1188,7 @@
&linux; process running on &os; issues a syscall, the general syscall
routine calls linux prepsyscall routine for the &linux; ABI.</para>
<sect3 id="linux-prepsyscall">
<sect3 xml:id="linux-prepsyscall">
<title>&linux; prepsyscall</title>
<para>&linux; passes arguments to syscalls via registers (that is why
@ -1211,7 +1204,7 @@
in the <function>linux_clone</function> prototype.</para>
</sect3>
<sect3 id="syscall-writing">
<sect3 xml:id="syscall-writing">
<title>Syscall writing</title>
<para>Every syscall implemented in the Linuxulator must have its
@ -1274,7 +1267,7 @@
with linux as it calls the real &man.close.2; in the kernel.</para>
</sect3>
<sect3 id="dummy-syscalls">
<sect3 xml:id="dummy-syscalls">
<title>Dummy syscalls</title>
<para>The &linux; emulation layer is not complete, as some syscalls are
@ -1291,7 +1284,7 @@
</sect3>
</sect2>
<sect2 id="signal-handling">
<sect2 xml:id="signal-handling">
<title>Signal handling</title>
<para>Signal handling is done generally in the &os; kernel for all
@ -1299,7 +1292,7 @@
&linux; compatibility layer defines
<function>linux_sendsig</function> routine for this purpose.</para>
<sect3 id="linux-sendsig">
<sect3 xml:id="linux-sendsig">
<title>&linux; sendsig</title>
<para>This routine first checks whether the signal has been installed
@ -1315,7 +1308,7 @@
signal handler to run.</para>
</sect3>
<sect3 id="linux-rt-sendsig">
<sect3 xml:id="linux-rt-sendsig">
<title>linux_rt_sendsig</title>
<para>This routine is similar to <function>linux_sendsig</function>
@ -1326,7 +1319,7 @@
and possibly even faster execution.</para>
</sect3>
<sect3 id="linux-sigreturn">
<sect3 xml:id="linux-sigreturn">
<title>linux_sigreturn</title>
<para>This syscall is used for return from the signal handler. It does
@ -1335,7 +1328,7 @@
</sect3>
</sect2>
<sect2 id="ptrace">
<sect2 xml:id="ptrace">
<title>Ptrace</title>
<para>Many &unix; derivates implement the &man.ptrace.2; syscall in order
@ -1367,7 +1360,7 @@
implemented.</para>
</sect2>
<sect2 id="traps">
<sect2 xml:id="traps">
<title>Traps</title>
<para>Whenever a &linux; process running in the emulation layer traps
@ -1397,7 +1390,7 @@ translate_traps(int signal, int trap_code)
}</programlisting>
</sect2>
<sect2 id="stack-fixup">
<sect2 xml:id="stack-fixup">
<title>Stack fixup</title>
<para>The RTLD run-time link-editor expects so called AUX tags on stack
@ -1410,7 +1403,7 @@ translate_traps(int signal, int trap_code)
smart way.</para>
</sect2>
<sect2 id="aout-support">
<sect2 xml:id="aout-support">
<title>A.OUT support</title>
<para>The &linux; emulation layer on i386 also supports &linux; A.OUT
@ -1425,7 +1418,7 @@ translate_traps(int signal, int trap_code)
</sect2>
</sect1>
<sect1 id="mi">
<sect1 xml:id="mi">
<title>&linux; emulation layer -MI part</title>
<para>This section talks about machine independent part of the
@ -1433,7 +1426,7 @@ translate_traps(int signal, int trap_code)
2.6 emulation, the thread local storage (TLS) implementation (on i386)
and futexes. Then we talk briefly about some syscalls.</para>
<sect2 id="nptl-desc">
<sect2 xml:id="nptl-desc">
<title>Description of NPTL</title>
<para>One of the major areas of progress in development of &linux; 2.6
@ -1464,13 +1457,13 @@ translate_traps(int signal, int trap_code)
areas.</para>
</sect2>
<sect2 id="linux26-emu">
<sect2 xml:id="linux26-emu">
<title>&linux; 2.6 emulation infrastructure</title>
<para>These sections deal with the way &linux; threads are managed and
how we simulate that in &os;.</para>
<sect3 id="linux26-runtime">
<sect3 xml:id="linux26-runtime">
<title>Runtime determining of 2.6 emulation</title>
<para>The &linux; emulation layer in &os; supports runtime setting of
@ -1489,7 +1482,7 @@ translate_traps(int signal, int trap_code)
&linux; binary as it might harm things.</para>
</sect3>
<sect3 id="linux-proc-thread">
<sect3 xml:id="linux-proc-thread">
<title>&linux; processes and thread identifiers</title>
<para>The semantics of &linux; threading are a little confusing and
@ -1572,7 +1565,7 @@ translate_traps(int signal, int trap_code)
later.</para>
</sect3>
<sect3 id="pid-mangling">
<sect3 xml:id="pid-mangling">
<title>PID mangling</title>
<para>Because of the described different view knowing what a process
@ -1592,7 +1585,7 @@ translate_traps(int signal, int trap_code)
<function>child_set_tid</function> we copy out &os; PID.</para>
</sect3>
<sect3 id="clone-syscall">
<sect3 xml:id="clone-syscall">
<title>Clone syscall</title>
<para>The <function>clone</function> syscall is the way threads are
@ -1654,7 +1647,7 @@ void * child_tidptr);</programlisting>
to implement &man.fork.2; and &man.vfork.2; syscalls.</para>
</sect3>
<sect3 id="locking">
<sect3 xml:id="locking">
<title>Locking</title>
<para>The locking is implemented to be per-subsystem because we do not
@ -1671,13 +1664,13 @@ void * child_tidptr);</programlisting>
</sect3>
</sect2>
<sect2 id="tls">
<sect2 xml:id="tls">
<title>TLS</title>
<para>This section deals with TLS also known as thread local
storage.</para>
<sect3 id="trheading-intro">
<sect3 xml:id="trheading-intro">
<title>Introduction to threading</title>
<para>Threads in computer science are entities within a process that
@ -1717,7 +1710,7 @@ void * child_tidptr);</programlisting>
switches.</para>
</sect3>
<sect3 id="i386-segs">
<sect3 xml:id="i386-segs">
<title>Segments on i386</title>
<para>The i386 architecture implements the so called segments. A
@ -1743,7 +1736,7 @@ void * child_tidptr);</programlisting>
Both tables define up to 8191 entries.</para>
</sect3>
<sect3 id="linux-i386">
<sect3 xml:id="linux-i386">
<title>Implementation on &linux; i386</title>
<para>There are two main ways of setting up TLS in &linux;. It can be
@ -1761,10 +1754,10 @@ void * child_tidptr);</programlisting>
emulation and in fact depend on it.</para>
</sect3>
<sect3 id="tls-emu">
<sect3 xml:id="tls-emu">
<title>Emulation of &linux; TLS</title>
<sect4 id="tls-i386">
<sect4 xml:id="tls-i386">
<title>i386</title>
<para>Loading of TLS for the current thread happens by calling
@ -1799,7 +1792,7 @@ void * child_tidptr);</programlisting>
plain &os;.</para>
</sect4>
<sect4 id="tls-amd64">
<sect4 xml:id="tls-amd64">
<title>amd64</title>
<para>The amd64 implementation is similar to the i386 one but there
@ -1814,10 +1807,10 @@ void * child_tidptr);</programlisting>
</sect3>
</sect2>
<sect2 id="futexes">
<sect2 xml:id="futexes">
<title>Futexes</title>
<sect3 id="sync-intro">
<sect3 xml:id="sync-intro">
<title>Introduction to synchronization</title>
<para>Threads need some kind of synchronization and &posix; provides
@ -1847,7 +1840,7 @@ void * child_tidptr);</programlisting>
threaded programs show little locks contention.</para>
</sect3>
<sect3 id="futex-intro">
<sect3 xml:id="futex-intro">
<title>Futexes introduction</title>
<para>&linux; implements 1:1 threading, i.e. it has to use in-kernel
@ -1872,7 +1865,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
implementation.</para>
</sect3>
<sect3 id="futex-api">
<sect3 xml:id="futex-api">
<title>Futex API</title>
<para>The futex syscall looks like this:</para>
@ -1907,7 +1900,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
</listitem>
</itemizedlist>
<sect4 id="futex-wait">
<sect4 xml:id="futex-wait">
<title>FUTEX_WAIT</title>
<para>This operation verifies that on address
@ -1919,7 +1912,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
otherwise the sleeping is infinite.</para>
</sect4>
<sect4 id="futex-wake">
<sect4 xml:id="futex-wake">
<title>FUTEX_WAKE</title>
<para>This operation takes a futex at <varname>uaddr</varname>
@ -1927,14 +1920,14 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
on this futex.</para>
</sect4>
<sect4 id="futex-fd">
<sect4 xml:id="futex-fd">
<title>FUTEX_FD</title>
<para>This operations associates a file descriptor with a given
futex.</para>
</sect4>
<sect4 id="futex-requeue">
<sect4 xml:id="futex-requeue">
<title>FUTEX_REQUEUE</title>
<para>This operation takes <varname>val</varname> threads
@ -1943,7 +1936,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
on futex at <varname>uaddr2</varname>.</para>
</sect4>
<sect4 id="futex-cmp-requeue">
<sect4 xml:id="futex-cmp-requeue">
<title>FUTEX_CMP_REQUEUE</title>
<para>This operation does the same as
@ -1952,7 +1945,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
first.</para>
</sect4>
<sect4 id="futex-wake-op">
<sect4 xml:id="futex-wake-op">
<title>FUTEX_WAKE_OP</title>
<para>This operation performs an atomic operation on
@ -1995,7 +1988,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
</sect4>
</sect3>
<sect3 id="futex-emu">
<sect3 xml:id="futex-emu">
<title>Futex emulation in &os;</title>
<para>The futex emulation in &os; is taken from NetBSD and further
@ -2023,7 +2016,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
TAILQ_ENTRY(waiting_proc) wp_list;
};</programlisting>
<sect4 id="futex-get">
<sect4 xml:id="futex-get">
<title>futex_get / futex_put</title>
<para>A futex is obtained using the <function>futex_get</function>
@ -2034,7 +2027,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
reaches zero it is released.</para>
</sect4>
<sect4 id="futex-sleep">
<sect4 xml:id="futex-sleep">
<title>futex_sleep</title>
<para>When a futex queues a thread for sleeping it creates a
@ -2050,7 +2043,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
the actual requeueing is done in this function.</para>
</sect4>
<sect4 id="futex-wake-2">
<sect4 xml:id="futex-wake-2">
<title>futex_wake</title>
<para>Waking up a thread sleeping on a futex is performed in the
@ -2065,7 +2058,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
<function>futex_sleep</function>.</para>
</sect4>
<sect4 id="futex-wake-op-2">
<sect4 xml:id="futex-wake-op-2">
<title>futex_wake_op</title>
<para>The <literal>FUTEX_WAKE_OP</literal> operation is quite
@ -2078,7 +2071,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
<varname>timeout</varname>) waiter on the second futex.</para>
</sect4>
<sect4 id="futex-atomic-op">
<sect4 xml:id="futex-atomic-op">
<title>futex atomic operation</title>
<para>The atomic operation takes two parameters
@ -2097,7 +2090,7 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
<varname>cmparg</varname> argument with cmp comparator.</para>
</sect4>
<sect4 id="futex-locking">
<sect4 xml:id="futex-locking">
<title>Futex locking</title>
<para>Futex implementation uses two lock lists protecting
@ -2108,14 +2101,14 @@ pthread_mutex_unlock(&amp;mutex);</programlisting>
</sect3>
</sect2>
<sect2 id="syscall-impl">
<sect2 xml:id="syscall-impl">
<title>Various syscalls implementation</title>
<para>In this section I am going to describe some smaller syscalls that
are worth mentioning because their implementation is not obvious or
those syscalls are interesting from other point of view.</para>
<sect3 id="syscall-at">
<sect3 xml:id="syscall-at">
<title>*at family of syscalls</title>
<para>During development of &linux; 2.6.16 kernel, the *at syscalls
@ -2168,7 +2161,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
using the modified &man.namei.9; routine and simple
wrapping layer.</para>
<sect4 id="implementation">
<sect4 xml:id="implementation">
<title>Implementation</title>
<para>The implementation is done by altering the
@ -2194,7 +2187,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
levels. For example the <function>openat</function> goes like
this:</para>
<programlisting>openat() --> kern_openat() --> vn_open() -> namei()</programlisting>
<programlisting>openat() --&gt; kern_openat() --&gt; vn_open() -&gt; namei()</programlisting>
<para>For this reason <function>kern_open</function> and
<function>vn_open</function> must be altered to incorporate
@ -2206,7 +2199,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
</sect4>
</sect3>
<sect3 id="ioctl">
<sect3 xml:id="ioctl">
<title>Ioctl</title>
<para>The ioctl interface is quite fragile due to its generality.
@ -2234,7 +2227,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
because of the easy porting of applications.</para>
</sect3>
<sect3 id="debugging">
<sect3 xml:id="debugging">
<title>Debugging</title>
<para>Every syscall should be debuggable. For this purpose we
@ -2246,10 +2239,10 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
</sect2>
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<sect2 id="results">
<sect2 xml:id="results">
<title>Results</title>
<para>As of April 2007 the &linux; emulation layer is capable of
@ -2267,9 +2260,9 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
stuff.</para>
<para>We are able to run the most used applications like
<filename role="package">www/linux-firefox</filename>,
<filename role="package">www/linux-opera</filename>,
<filename role="package">net-im/skype</filename> and some games from
<package>www/linux-firefox</package>,
<package>www/linux-opera</package>,
<package>net-im/skype</package> and some games from
the Ports&nbsp;Collection. Some of the programs exhibit bad behaviour
under 2.6 emulation but this is currently under investigation and
hopefully will be fixed soon. The only big application that is
@ -2284,7 +2277,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
Fedora&nbsp;Core&nbsp;6 linux_base, which is the ultimate plan.</para>
</sect2>
<sect2 id="future-work">
<sect2 xml:id="future-work">
<title>Future work</title>
<para>Future work should focus on fixing the remaining issues with
@ -2310,7 +2303,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
improvements can also be made, finer grained locking and others.</para>
</sect2>
<sect2 id="team">
<sect2 xml:id="team">
<title>Team</title>
<para>I cooperated on this project with (in alphabetical order):</para>
@ -2350,7 +2343,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
</sect2>
</sect1>
<sect1 id="literatures">
<sect1 xml:id="literatures">
<title>Literatures</title>
<orderedlist>
@ -2360,13 +2353,13 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo
2005.</para>
</listitem>
<listitem>
<para><ulink url="http://www.FreeBSD.org"></ulink></para>
<para><uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri></para>
</listitem>
<listitem>
<para><ulink url="http://tldp.org"></ulink></para>
<para><uri xlink:href="http://tldp.org">http://tldp.org</uri></para>
</listitem>
<listitem>
<para><ulink url="http://www.linux.org"></ulink></para>
<para><uri xlink:href="http://www.linux.org">http://www.linux.org</uri></para>
</listitem>
</orderedlist>
</sect1>

130
en_US.ISO8859-1/articles/linux-users/article.xml
View file

@ -1,16 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>FreeBSD Quickstart Guide for &linux; Users</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>FreeBSD Quickstart Guide for &linux; Users</title>
<authorgroup>
<author>
<firstname>John</firstname>
<surname>Ferrell</surname>
</author>
<author><personname><firstname>John</firstname><surname>Ferrell</surname></personname></author>
</authorgroup>
<copyright>
@ -22,7 +18,7 @@
<releaseinfo>$FreeBSD$</releaseinfo>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.linux;
&tm-attrib.intel;
@ -35,9 +31,9 @@
<para>This document is intended to quickly familiarize intermediate to
advanced &linux; users with the basics of FreeBSD.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>This document will highlight the differences between &os; and
@ -50,11 +46,11 @@
<para>This document assumes that you have already installed &os;.
If you have not installed &os; or need help with the installation
process please refer to the
<ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/install.html">
Installing FreeBSD</ulink> chapter of the &os;&nbsp;Handbook.</para>
<link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/install.html">
Installing FreeBSD</link> chapter of the &os;&nbsp;Handbook.</para>
</sect1>
<sect1 id="shells">
<sect1 xml:id="shells">
<title>Shells: No Bash?</title>
<para>Those coming from &linux; are often surprised to find that
@ -62,35 +58,32 @@
In fact, <application>Bash</application> is not even in the default
installation. Instead, &os; uses &man.tcsh.1; as the default shell.
Although, <application>Bash</application> and your other favorite
shells are available in &os;'s <ulink
url="article.html#SOFTWARE">Packages and Ports&nbsp;Collection</ulink>.</para>
shells are available in &os;'s <link xlink:href="article.html#SOFTWARE">Packages and Ports&nbsp;Collection</link>.</para>
<para>If you do install other shells you can use &man.chsh.1; to set
a user's default shell. It is, however, recommended that the
<username>root</username>'s default shell remain unchanged. The
<systemitem class="username">root</systemitem>'s default shell remain unchanged. The
reason for this is that shells not included in the base distribution
are normally installed in <filename>/usr/local/bin</filename> or
<filename>/usr/bin</filename>. In the event of a problem the file
systems where <filename>/usr/local/bin</filename> and
<filename>/usr/bin</filename> are located may not be mounted. In this
case <username>root</username> would not have access to its default
shell, preventing <username>root</username> from logging in. For this
reason a second <username>root</username> account, the
<username>toor</username> account, was created for use with non-default
shells. See the security FAQ for information regarding the <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/faq/security.html#TOOR-ACCOUNT">toor account</ulink>.</para>
case <systemitem class="username">root</systemitem> would not have access to its default
shell, preventing <systemitem class="username">root</systemitem> from logging in. For this
reason a second <systemitem class="username">root</systemitem> account, the
<systemitem class="username">toor</systemitem> account, was created for use with non-default
shells. See the security FAQ for information regarding the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/faq/security.html#TOOR-ACCOUNT">toor account</link>.</para>
</sect1>
<sect1 id="software">
<sect1 xml:id="software">
<title>Packages and Ports: Adding software in &os;</title>
<para>In addition to the traditional &unix; method of installing software
(download source, extract, edit source code, and compile), &os; offers
two other methods for installing applications: packages and ports. A
complete list of of all available ports and packages can be found <ulink
url="http://www.freebsd.org/ports/master-index.html">here</ulink>.</para>
complete list of of all available ports and packages can be found <link xlink:href="http://www.freebsd.org/ports/master-index.html">here</link>.</para>
<sect2 id="packages">
<sect2 xml:id="packages">
<title>Packages</title>
<para>Packages are pre-compiled applications, the &os; equivalents
@ -100,13 +93,13 @@
the following command installs
<application>Apache 2.2</application>:</para>
<screen>&prompt.root; <userinput>pkg_add <replaceable>/tmp/apache-2.2.6_2.tbz</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>pkg_add /tmp/apache-2.2.6_2.tbz</userinput></screen>
<para>Using the <option>-r</option> switch will tell &man.pkg.add.1;
to automatically fetch a package and install it, as well as any
dependencies:</para>
<screen>&prompt.root; <userinput>pkg_add -r <replaceable>apache22</replaceable></userinput>
<screen>&prompt.root; <userinput>pkg_add -r apache22</userinput>
Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/Latest/apache22.tbz... Done.
Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/expat-2.0.0_1.tbz... Done.
Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/perl-5.8.8_1.tbz... Done.
@ -123,17 +116,16 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
version of the application. You can use the
<envar>PACKAGESITE</envar> variable to override this default
behavior. For example, set <envar>PACKAGESITE</envar> to
<ulink url="ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/"></ulink>
<uri xlink:href="ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/">ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/</uri>
to download the most recent packages built for the
6.X series.</para>
</note>
<para>For more information on packages please refer to section 4.4 of
the &os; Handbook: <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/packages-using.html">Using the Packages System</ulink>.</para>
the &os; Handbook: <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/packages-using.html">Using the Packages System</link>.</para>
</sect2>
<sect2 id="ports">
<sect2 xml:id="ports">
<title>Ports</title>
<para>&os;'s second method for installing applications is the
@ -151,8 +143,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
added from the installation discs using &man.sysinstall.8;, or pulled
from the &os; servers using &man.csup.1; or &man.portsnap.8;.
Detailed instructions for installing the Ports&nbsp;Collection can be
found in <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">section 4.5.1</ulink>
found in <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">section 4.5.1</link>
of the handbook.</para>
<para>Installing a port is as simple (generally) as changing in to the
@ -167,18 +158,17 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
ability to customize the installation options. For example, when
installing <application>Apache 2.2</application> from ports you can
enable <application>mod_ldap</application> by setting the
<makevar>WITH_LDAP</makevar> &man.make.1; variable:</para>
<varname>WITH_LDAP</varname> &man.make.1; variable:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/www/apache22</userinput>
&prompt.root; <userinput>make WITH_LDAP="YES" install clean</userinput></screen>
<para>Please see section 4.5 of the &os; Handbook, <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">Using
the Ports&nbsp;Collection</ulink>, for more information about the
<para>Please see section 4.5 of the &os; Handbook, <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">Using
the Ports&nbsp;Collection</link>, for more information about the
Ports&nbsp;Collection.</para>
</sect2>
<sect2 id="which">
<sect2 xml:id="which">
<title>Ports or packages, which one should I use?</title>
<para>Packages are just pre-compiled ports, so it is really a matter
@ -215,12 +205,12 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
customize, ports are the way to go. (And remember, if you
need to customize but prefer packages, you can build a custom
package from ports using <command>make</command>
<maketarget>package</maketarget> and then copy the package to
<buildtarget>package</buildtarget> and then copy the package to
other servers.)</para>
</sect2>
</sect1>
<sect1 id="startup">
<sect1 xml:id="startup">
<title>System Startup: Where are the run-levels?</title>
<para>&linux; uses the SysV init system, whereas &os; uses the
@ -257,8 +247,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
the <quote>base</quote> system, such as
<application>Apache</application>, <application>X11</application>,
<application>Mozilla&nbsp;Firefox</application>, etc. These
user-installed applications are generally installed using &os;'s <ulink
url="article.html#SOFTWARE">Packages and Ports&nbsp;Collection</ulink>.
user-installed applications are generally installed using &os;'s <link xlink:href="article.html#SOFTWARE">Packages and Ports&nbsp;Collection</link>.
In order to keep them separate from the <quote>base</quote> system,
user-installed applications are normally installed under
<filename>/usr/local/</filename>. Therefore the user-installed
@ -268,7 +257,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen>
</sidebar>
<para>Services are enabled by specifying
<literal><replaceable>ServiceName</replaceable>_enable="YES"</literal> in
<literal>ServiceName_enable="YES"</literal> in
<filename>/etc/rc.conf</filename> (&man.rc.conf.5;). Take a look at
<filename>/etc/defaults/rc.conf</filename> for the system defaults,
these default settings are overridden by settings in
@ -291,25 +280,25 @@ apache22_flags="-DSSL"</programlisting>
the service can be started from the command line (without rebooting the
system):</para>
<screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> start</userinput></screen>
<screen>&prompt.root; <userinput>/etc/rc.d/sshd start</userinput></screen>
<para>If a service has not been enabled it can be started from the
command line using <option>forcestart</option>:</para>
<screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> forcestart</userinput></screen>
<screen>&prompt.root; <userinput>/etc/rc.d/sshd forcestart</userinput></screen>
</sect1>
<sect1 id="network">
<sect1 xml:id="network">
<title>Network configuration</title>
<sect2 id="interfaces">
<sect2 xml:id="interfaces">
<title>Network Interfaces</title>
<para>Instead of a generic <emphasis>ethX</emphasis> identifier that
&linux; uses to identify a network interface, &os; uses the driver
name followed by a number as the identifier. The following output
from &man.ifconfig.8; shows two &intel;&nbsp;Pro&nbsp;1000 network
interfaces (<devicename>em0</devicename> and <devicename>em1</devicename>):</para>
interfaces (<filename>em0</filename> and <filename>em1</filename>):</para>
<screen>&prompt.user; <userinput>ifconfig</userinput>
em0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
@ -326,7 +315,7 @@ em1: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
status: active</screen>
</sect2>
<sect2 id="ipaddress">
<sect2 xml:id="ipaddress">
<title>IP Configuration</title>
<para>An IP address can be assigned to an interface using
@ -347,16 +336,16 @@ ifconfig_em0="DHCP"</programlisting>
</sect2>
</sect1>
<sect1 id="firewall">
<sect1 xml:id="firewall">
<title>Firewall</title>
<para>Like <application>IPTABLES</application> in &linux;, &os; also offers
a kernel level firewall; actually &os; offers three firewalls:</para>
<itemizedlist>
<listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html">IPFIREWALL</ulink></simpara></listitem>
<listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipf.html">IPFILTER</ulink></simpara></listitem>
<listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html">PF</ulink></simpara></listitem>
<listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html">IPFIREWALL</link></simpara></listitem>
<listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipf.html">IPFILTER</link></simpara></listitem>
<listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html">PF</link></simpara></listitem>
</itemizedlist>
<para><application>IPFIREWALL</application> or
@ -395,7 +384,7 @@ ifconfig_em0="DHCP"</programlisting>
<programlisting>pass in on $ext_if inet proto tcp from any to ($ext_if) port 22</programlisting>
</sect1>
<sect1 id="updates">
<sect1 xml:id="updates">
<title>Updating &os;</title>
<para>There are three methods for updating a &os; system: from source,
@ -407,7 +396,7 @@ ifconfig_em0="DHCP"</programlisting>
<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>
<link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/updating-upgrading.html">the chapter on updating</link>
in the &os;&nbsp;Handbook.</para>
<para>Binary updates are similar to using <command>yum</command> or
@ -429,7 +418,7 @@ ifconfig_em0="DHCP"</programlisting>
the option to upgrade.</para>
</sect1>
<sect1 id="procfs">
<sect1 xml:id="procfs">
<title>procfs: Gone But Not Forgotten</title>
<para>In &linux;, you may have looked at
@ -472,7 +461,7 @@ kern.posix1version: 200112
<para>There are occasions where procfs is required, such as running
older software, using &man.truss.1; to trace system calls, and
<ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/linuxemu.html">&linux; Binary Compatibility</ulink>.
<link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/linuxemu.html">&linux; Binary Compatibility</link>.
(Although, &linux; Binary Compatibility uses its own procfs, &man.linprocfs.5;.)
If you need to mount procfs you can add the following to
<filename>/etc/fstab</filename>:</para>
@ -489,10 +478,10 @@ kern.posix1version: 200112
<screen>&prompt.root; <userinput>mount /proc</userinput></screen>
</sect1>
<sect1 id="commands">
<sect1 xml:id="commands">
<title>Common Commands</title>
<sect2 id="packageCommands">
<sect2 xml:id="packageCommands">
<title>Package Management</title>
<para>
@ -508,14 +497,14 @@ kern.posix1version: 200112
<tbody>
<row>
<entry><command>yum install <replaceable>package</replaceable></command> / <command>apt-get install <replaceable>package</replaceable></command></entry>
<entry><command>pkg_add -r <replaceable>package</replaceable></command></entry>
<entry><command>yum install package</command> / <command>apt-get install package</command></entry>
<entry><command>pkg_add -r package</command></entry>
<entry>Install <replaceable>package</replaceable> from remote repository</entry>
</row>
<row>
<entry><command>rpm -ivh <replaceable>package</replaceable></command> / <command>dpkg -i <replaceable>package</replaceable></command></entry>
<entry><command>pkg_add -v <replaceable>package</replaceable></command></entry>
<entry><command>rpm -ivh package</command> / <command>dpkg -i package</command></entry>
<entry><command>pkg_add -v package</command></entry>
<entry>Install package</entry>
</row>
@ -530,7 +519,7 @@ kern.posix1version: 200112
</para>
</sect2>
<sect2 id="systemCommands">
<sect2 xml:id="systemCommands">
<title>System Management</title>
<para>
@ -575,12 +564,11 @@ kern.posix1version: 200112
</sect2>
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<para>Hopefully this document has provided you with enough to get
started with &os;. Be sure to take a look at the <ulink
url="&url.base;/doc/en_US.ISO8859-1/books/handbook/index.html">&os;&nbsp;Handbook</ulink>
started with &os;. Be sure to take a look at the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/index.html">&os;&nbsp;Handbook</link>
for more in depth coverage of the topics touched on as well as
the many topics not covered in this document.</para>
</sect1>

138
en_US.ISO8859-1/articles/mailing-list-faq/article.xml
View file

@ -1,18 +1,14 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<article lang='en'>
<articleinfo>
<title>Frequently Asked Questions About The &os; Mailing Lists</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Frequently Asked Questions About The &os; Mailing Lists</title>
<authorgroup>
<author>
<surname>The &os; Documentation Project</surname>
</author>
<author><personname><surname>The &os; Documentation Project</surname></personname></author>
</authorgroup>
<copyright>
@ -29,19 +25,16 @@
<para>This is the FAQ for the &os; mailing lists. 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/articles/mailing-list-faq/index.html">&os;
World Wide Web server</ulink>. It may also be downloaded as
one large <ulink url="article.html">HTML</ulink> file with HTTP
or as plain text, PostScript, PDF, etc. 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>
<link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/index.html">&os;
World Wide Web server</link>. It may also be downloaded as
one large <link xlink:href="article.html">HTML</link> file with HTTP
or as plain text, PostScript, PDF, etc. from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP
server</link>. You may also want to <link xlink:href="&url.base;/search/index.html">Search the
FAQ</link>.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>As is usual with FAQs, this document aims to cover the
@ -59,7 +52,7 @@
<qandaset>
<qandaentry>
<question id="purpose">
<question xml:id="purpose">
<para>What is the purpose of the &os; mailing lists?</para>
</question>
@ -71,21 +64,20 @@
</qandaentry>
<qandaentry>
<question id="audience">
<question xml:id="audience">
<para>Who is the audience for the &os; mailing lists?</para>
</question>
<answer>
<para>This depends on charter of each individual list. Some
lists are more oriented to developers; some are more oriented
towards the &os; community as a whole. Please see <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">this list</ulink>
towards the &os; community as a whole. Please see <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">this list</link>
for the current summary.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="participation-who">
<question xml:id="participation-who">
<para>Are the &os; mailing lists open for anyone to participate?</para>
</question>
@ -111,20 +103,19 @@
</qandaentry>
<qandaentry>
<question id="subscribe">
<question xml:id="subscribe">
<para>How can I subscribe?</para>
</question>
<answer>
<para>You can use <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">
the Mailman web interface</ulink> to subscribe to any
<para>You can use <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">
the Mailman web interface</link> to subscribe to any
of the public lists.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="unsubscribe">
<question xml:id="unsubscribe">
<para>How can I unsubscribe?</para>
</question>
@ -143,31 +134,30 @@
</qandaentry>
<qandaentry>
<question id="archives">
<question xml:id="archives">
<para>Are archives available?</para>
</question>
<answer>
<para>Yes. Threaded archives are available
<ulink url="http://docs.FreeBSD.org/mail/">here</ulink>.</para>
<link xlink:href="http://docs.FreeBSD.org/mail/">here</link>.</para>
</answer>
</qandaentry>
<qandaentry>
<question id="digest">
<question xml:id="digest">
<para>Are mailing lists available in a digest format?</para>
</question>
<answer>
<para>Yes. See <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">
the Mailman web interface</ulink>.</para>
<para>Yes. See <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">
the Mailman web interface</link>.</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="etiquette">
<sect1 xml:id="etiquette">
<title>Mailing List Etiquette</title>
<para>Participation in the mailing lists, like participation
@ -177,7 +167,7 @@
<qandaset>
<qandaentry>
<question id="before-posting">
<question xml:id="before-posting">
<para>What should I do before I post?</para>
</question>
@ -187,23 +177,18 @@
you may first need to familiarize yourself with the
software, and all the social history around it, by
reading the numerous
<ulink url="&url.base;/docs/books.html">books and articles</ulink>
<link xlink:href="&url.base;/docs/books.html">books and articles</link>
that are available. Items of particular interest
include the <ulink
url="&url.books.faq;/index.html">
&os; Frequently Asked Questions (FAQ)</ulink> document,
the <ulink
url="&url.books.handbook;/index.html">
&os; Handbook</ulink>,
and the articles <ulink
url="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</ulink>,
<ulink
url="&url.articles.explaining-bsd;/article.html">
Explaining BSD</ulink>,
and <ulink
url="&url.articles.new-users;/article.html">
&os; First Steps</ulink>.</para>
include the <link xlink:href="&url.books.faq;/index.html">
&os; Frequently Asked Questions (FAQ)</link> document,
the <link xlink:href="&url.books.handbook;/index.html">
&os; Handbook</link>,
and the articles <link xlink:href="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</link>,
<link xlink:href="&url.articles.explaining-bsd;/article.html">
Explaining BSD</link>,
and <link xlink:href="&url.articles.new-users;/article.html">
&os; First Steps</link>.</para>
<para>It is always considered bad form to ask a question that is
already answered in the above documents. This is not because
@ -219,7 +204,7 @@
</qandaentry>
<qandaentry>
<question id="inappropriate">
<question xml:id="inappropriate">
<para>What constitutes an inappropriate posting?</para>
</question>
@ -245,7 +230,7 @@
</qandaentry>
<qandaentry>
<question id="etiquette-posting">
<question xml:id="etiquette-posting">
<para>What is considered proper etiquette when posting
to the mailing lists?</para>
</question>
@ -284,8 +269,8 @@
<para>Please use an appropriate human language for a
particular mailing list. Many non-English mailing
lists are
<ulink url="&url.base;/community/mailinglists.html">
available</ulink>.</para>
<link xlink:href="&url.base;/community/mailinglists.html">
available</link>.</para>
<para>For the ones that are not, we do appreciate that many
people do not speak English as their first language,
@ -299,8 +284,8 @@
<listitem>
<para>Please use a standards-compliant Mail User Agent (MUA).
A lot of badly formatted messages come from
<ulink url="http://www.lemis.com/email.html">bad mailers
or badly configured mailers</ulink>. The following mailers
<link xlink:href="http://www.lemis.com/email.html">bad mailers
or badly configured mailers</link>. The following mailers
are known to send out badly formatted messages without you
finding out about them:</para>
@ -360,8 +345,8 @@
<filename>Makefiles</filename>, where <literal>tab</literal>
is a significant character. This is a very common,
and very annoying, problem with submissions to the
<ulink url="&url.base;/support.html#gnats">
GNATS Problem Reports database</ulink>.
<link xlink:href="&url.base;/support.html#gnats">
GNATS Problem Reports database</link>.
<filename>Makefiles</filename> with tabs changed to either
spaces, or the annoying <literal>=3B</literal> escape
sequence, create a great deal of aggravation for
@ -372,7 +357,7 @@
</qandaentry>
<qandaentry>
<question id="etiquette-replying">
<question xml:id="etiquette-replying">
<para>What are the special etiquette consideration when replying
to an existing posting on the mailing lists?</para>
</question>
@ -431,7 +416,7 @@
</qandaset>
</sect1>
<sect1 id="recurring">
<sect1 xml:id="recurring">
<title>Recurring Topics On The Mailing Lists</title>
<para>Participation in the mailing lists, like participation
@ -445,12 +430,11 @@
and probably save yourself being flamed in the process.</para>
<para>The best method to avoid this is to familiarize yourself
with the <ulink url="http://docs.FreeBSD.org/mail/">
mailing list archives</ulink>,
with the <link xlink:href="http://docs.FreeBSD.org/mail/">
mailing list archives</link>,
to help yourself understand the background of
what has gone before. In this, the <ulink
url="http://www.FreeBSD.org/search/search.html#mailinglists">
mailing list search interface</ulink>
what has gone before. In this, the <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">
mailing list search interface</link>
is invaluable. (If that method does not yield useful results,
please supplement it with a search with your favorite major
search engine).</para>
@ -469,16 +453,15 @@
to help avoid these recurring topics.</para>
</sect1>
<sect1 id="bikeshed">
<sect1 xml:id="bikeshed">
<title>What Is A "Bikeshed"?</title>
<para>Literally, a <literal>bikeshed</literal> is a small outdoor
shelter into which one may store one's two-wheeled form of
transportation. However, in &os; parlance, the term refers to
topics that are simple enough that (nearly) anyone can offer an
opinion about, and often (nearly) everyone does. The
genesis of this term is explained in more detail <ulink
url="&url.books.faq;/misc.html#BIKESHED-PAINTING">
in this document</ulink>. You simply must have a working
genesis of this term is explained in more detail <link xlink:href="&url.books.faq;/misc.html#BIKESHED-PAINTING">
in this document</link>. You simply must have a working
knowledge of this concept before posting to any &os; mailing
list.</para>
@ -491,7 +474,7 @@
Thanks.</para>
</sect1>
<sect1 id="acknowledgments">
<sect1 xml:id="acknowledgments">
<title>Acknowledgments</title>
<variablelist>
@ -499,9 +482,8 @@
<term>&a.grog.email;</term>
<listitem>
<para>Original author of most of the material on mailing
list etiquette, taken from the article on <ulink
url="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</ulink>.</para>
list etiquette, taken from the article on <link xlink:href="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</link>.</para>
</listitem>
</varlistentry>

64
en_US.ISO8859-1/articles/mh/article.xml
View file

@ -1,31 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- FreeBSD Documentation Project -->
<article lang='en'>
<articleinfo>
<title>An <application>MH</application> Primer</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>An <application>MH</application> Primer</title>
<authorgroup>
<author>
<firstname>Matt</firstname>
<surname>Midboe</surname>
<affiliation>
<author><personname><firstname>Matt</firstname><surname>Midboe</surname></personname><affiliation>
<address>
<email>matt@garply.com</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<pubdate>v1.0, 16 January 1996</pubdate>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.opengroup;
&tm-attrib.general;
@ -37,9 +29,9 @@
<para>This document contains an introduction to using
<application>MH</application> on FreeBSD</para>
</abstract>
</articleinfo>
</info>
<sect1 id="mhintro">
<sect1 xml:id="mhintro">
<title>Introduction</title>
<para><application>MH</application> started back in 1977 at the
@ -82,23 +74,18 @@
You will notice that it created a <filename>/usr/local/lib/mh</filename>
directory for you as well as adding several binaries to the
<filename>/usr/local/bin</filename> directory. If you would prefer to
compile it yourself then you can anonymous ftp it from <ulink
url="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink
url="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para>
compile it yourself then you can anonymous ftp it from <link xlink:href="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</link> or <link xlink:href="ftp://louie.udel.edu/">louie.udel.edu</link>.</para>
<para>This primer is not a full comprehensive explanation of how
<application>MH</application> works. This is just intended to
get you started on the road to happier, faster mail reading. You
should read the manual pages for the various commands. You might
also want to read the <ulink
url="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you
can read the <ulink
url="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for
<application>MH</application></ulink>. The best resource for
<application>MH</application> is <ulink
url="http://www.ics.uci.edu/~mh/book/">Jerry Peek's
also want to read the <link xlink:href="news:comp.mail.mh">comp.mail.mh</link> newsgroup. Also you
can read the <link xlink:href="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for
<application>MH</application></link>. The best resource for
<application>MH</application> is <link xlink:href="http://www.ics.uci.edu/~mh/book/">Jerry Peek's
<application>MH</application> &amp; nmh: Email for Users &amp;
Programmers</ulink>.</para>
Programmers</link>.</para>
</sect1>
<sect1>
@ -128,7 +115,7 @@
that refer to the current, last or first message in the
folder.</para>
<sect2 id="inc">
<sect2 xml:id="inc">
<title><command>inc</command>,
<command>msgchk</command>&mdash;read in your new email or
check it</title>
@ -162,7 +149,7 @@
command line arguments.</para>
<informalexample>
<screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</replaceable> -norpop</userinput></screen>
<screen>&prompt.user; <userinput>inc -host mail.pop.org -user username -norpop</userinput></screen>
</informalexample>
<para>That tells <command>inc</command> to go to
@ -183,7 +170,7 @@
options that <command>inc</command> takes.</para>
</sect2>
<sect2 id="show">
<sect2 xml:id="show">
<title><command>show</command>, <command>next</command> and
<command>prev</command>&mdash;displaying and moving through
email</title>
@ -211,7 +198,7 @@
it.</para>
</sect2>
<sect2 id="scan">
<sect2 xml:id="scan">
<title><command>scan</command>&mdash;shows you a scan of your
messages</title>
@ -241,11 +228,11 @@
have it read from a file. If you want to scan your incoming
mailbox on FreeBSD without having to <command>inc</command> it you
can do <command>scan -file
/var/mail/<replaceable>username</replaceable></command>. This can be used
/var/mail/username</command>. This can be used
with any file that is in the <database>mbox</database> format.</para>
</sect2>
<sect2 id="rmm">
<sect2 xml:id="rmm">
<title><command>rmm</command> and <command>rmf</command>&mdash;remove the
current message or folder</title>
@ -262,7 +249,7 @@
command.</para>
</sect2>
<sect2 id="samplereading">
<sect2 xml:id="samplereading">
<title>A typical session of reading with MH</title>
<para>The first thing that you will want to do is
@ -541,8 +528,7 @@ which I am probably the guilty party).</screen>
<screen>&prompt.user; <userinput>pick -to freebsd-hackers -or -cc freebsd-hackers</userinput></screen>
</informalexample>
<para>That will grab all the email in your <filename
class="directory">inbox</filename> that was sent to
<para>That will grab all the email in your <filename>inbox</filename> that was sent to
freebsd-hackers or cc'd to that list. The brace options allow
you to group search criteria together. This is sometimes very
necessary as in the following example</para>
@ -576,7 +562,7 @@ which I am probably the guilty party).</screen>
manipulating your folders. The <command>folder</command>
program is used to switch between folders, pack them, and list
them. At its simplest level you can do a <command>folder
+<replaceable>newfolder</replaceable></command> and you will
+newfolder</command> and you will
be switched into <replaceable>newfolder</replaceable>. From
there on out all your <application>MH</application> commands
like <command>comp</command>, <command>repl</command>,

79
en_US.ISO8859-1/articles/nanobsd/article.xml
View file

@ -1,17 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Introduction to NanoBSD</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Introduction to NanoBSD</title>
<authorgroup>
<author>
<firstname>Daniel</firstname>
<surname>Gerzo</surname>
<!-- 14 March 2006 -->
</author>
<author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname></author>
</authorgroup>
<copyright>
@ -19,7 +14,7 @@
<holder>The FreeBSD Documentation Project</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -34,9 +29,9 @@
create &os; system images for embedded applications, suitable for
use on a Compact Flash card (or other mass storage medium).</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction to NanoBSD</title>
<indexterm><primary>NanoBSD</primary></indexterm>
@ -87,10 +82,10 @@
</itemizedlist>
</sect1>
<sect1 id="howto">
<sect1 xml:id="howto">
<title>NanoBSD Howto</title>
<sect2 id="design">
<sect2 xml:id="design">
<title>The design of NanoBSD</title>
<para>Once the image is present on the medium, it is possible to
@ -105,24 +100,24 @@
<listitem>
<para>The configuration file partition, which can be mounted
under the <filename class="directory">/cfg</filename> directory
under the <filename>/cfg</filename> directory
at run time.</para>
</listitem>
</itemizedlist>
<para>These partitions are normally mounted read-only.</para>
<para>The <filename class="directory">/etc</filename> and
<filename class="directory">/var</filename> directories are
<para>The <filename>/etc</filename> and
<filename>/var</filename> directories are
&man.md.4; (malloc) disks.</para>
<para>The configuration file partition persists under the
<filename class="directory">/cfg</filename> directory. It
contains files for <filename class="directory">/etc</filename>
<filename>/cfg</filename> directory. It
contains files for <filename>/etc</filename>
directory and is briefly mounted read-only right after the
system boot, therefore it is required to copy modified files
from <filename class="directory">/etc</filename> back to the
<filename class="directory">/cfg</filename> directory if changes
from <filename>/etc</filename> back to the
<filename>/cfg</filename> directory if changes
are expected to persist after the system restarts.</para>
<example>
@ -137,11 +132,11 @@
<note>
<para>The partition containing
<filename class="directory">/cfg</filename> should be mounted
<filename>/cfg</filename> should be mounted
only at boot time and while overriding the configuration
files.</para>
<para>Keeping <filename class="directory">/cfg</filename> mounted at
<para>Keeping <filename>/cfg</filename> mounted at
all times is not a good idea, especially if
the <application>NanoBSD</application> system runs off a mass
storage medium that may be adversely affected by a large number
@ -156,17 +151,17 @@
<para>A <application>NanoBSD</application> image is built using a
simple <filename>nanobsd.sh</filename> shell script, which can
be found in the
<filename class="directory"><replaceable>/usr</replaceable>/src/tools/tools/nanobsd</filename>
<filename>/usr/src/tools/tools/nanobsd</filename>
directory. This script creates an image, which can be copied on
the storage medium using the &man.dd.1; utility.</para>
<para>The necessary commands to build a
<application>NanoBSD</application> image are:</para>
<screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co id="nbsd-cd"/>
&prompt.root; <userinput>sh nanobsd.sh</userinput> <co id="nbsd-sh"/>
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co id="nbsd-cd2"/>
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co id="nbsd-dd"/></screen>
<screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co xml:id="nbsd-cd"/>
&prompt.root; <userinput>sh nanobsd.sh</userinput> <co xml:id="nbsd-sh"/>
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co xml:id="nbsd-cd2"/>
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co xml:id="nbsd-dd"/></screen>
<calloutlist>
<callout arearefs="nbsd-cd">
@ -221,8 +216,8 @@
<title>Configuration options</title>
<para>With configuration settings, it is possible to configure options
passed to both the <maketarget>buildworld</maketarget>
and <maketarget>installworld</maketarget> stages of the
passed to both the <buildtarget>buildworld</buildtarget>
and <buildtarget>installworld</buildtarget> stages of the
<application>NanoBSD</application> build process, as well as internal
options passed to the main build process of
<application>NanoBSD</application>. Through these options it is
@ -253,18 +248,18 @@
<listitem>
<para><literal>CONF_BUILD</literal> &mdash; Options passed
to the <maketarget>buildworld</maketarget> stage of the build.</para>
to the <buildtarget>buildworld</buildtarget> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_INSTALL</literal> &mdash; Options passed
to the <maketarget>installworld</maketarget> stage of the build.</para>
to the <buildtarget>installworld</buildtarget> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_WORLD</literal> &mdash; Options passed to both
the <maketarget>buildworld</maketarget> and
the <maketarget>installworld</maketarget> stage of the build.</para>
the <buildtarget>buildworld</buildtarget> and
the <buildtarget>installworld</buildtarget> stage of the build.</para>
</listitem>
<listitem>
@ -291,7 +286,7 @@ customize_cmd cust_foo</programlisting>
<para>A more useful example of a customization function is the
following, which changes the default size of the
<filename class="directory">/etc</filename> directory
<filename>/etc</filename> directory
from 5MB to 30MB:</para>
<programlisting>cust_etc_size () (
@ -313,13 +308,13 @@ customize_cmd cust_etc_size</programlisting>
<listitem>
<para><literal>cust_allow_ssh_root</literal> &mdash; Allow
<username>root</username> to login via &man.sshd.8;.</para>
<systemitem class="username">root</systemitem> to login via &man.sshd.8;.</para>
</listitem>
<listitem>
<para><literal>cust_install_files</literal> &mdash;
Installs files from the
<filename class="directory">nanobsd/Files</filename>
<filename>nanobsd/Files</filename>
directory, which contains some useful scripts for system
administration.</para>
</listitem>
@ -447,7 +442,7 @@ customize_cmd cust_nobeastie</programlisting>
<application>NanoBSD</application> system, it is possible to use
either the <filename>updatep1</filename> or
<filename>updatep2</filename> script located in the
<filename class="directory">/root</filename> directory, depending
<filename>/root</filename> directory, depending
from which partition is running the current system.</para>
<para>According to which services are available on host serving
@ -485,7 +480,7 @@ get _.disk.image "| sh updatep1"</userinput></screen>
<para>At first, open a TCP listener on host serving the
image and make it send the image to client:</para>
<screen>myhost&prompt.root; <userinput>nc -l <replaceable>2222</replaceable> &lt; _.disk.image</userinput></screen>
<screen>myhost&prompt.root; <userinput>nc -l 2222 &lt; _.disk.image</userinput></screen>
<note>
<para>Make sure that the used port is not blocked to
@ -498,7 +493,7 @@ get _.disk.image "| sh updatep1"</userinput></screen>
<para>Connect to the host serving new image and execute
<filename>updatep1</filename> script:</para>
<screen>&prompt.root; <userinput>nc myhost <replaceable>2222</replaceable> | sh updatep1</userinput></screen>
<screen>&prompt.root; <userinput>nc myhost 2222 | sh updatep1</userinput></screen>
</step>
</procedure>
</sect3>

190
en_US.ISO8859-1/articles/new-users/article.xml
View file

@ -1,29 +1,21 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<article lang='en'>
<articleinfo>
<title>For People New to Both FreeBSD and &unix;</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>For People New to Both FreeBSD and &unix;</title>
<authorgroup>
<author>
<firstname>Annelise</firstname>
<surname>Anderson</surname>
<affiliation>
<author><personname><firstname>Annelise</firstname><surname>Anderson</surname></personname><affiliation>
<address><email>andrsn@andrsn.stanford.edu</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<pubdate>August 15, 1997</pubdate>
<pubdate>1997-08-15</pubdate>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.ibm;
&tm-attrib.microsoft;
@ -42,21 +34,21 @@
(you)&mdash;and you are probably pretty good with DOS/&windows;
or &os2;.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="in-and-out">
<sect1 xml:id="in-and-out">
<title>Logging in and Getting Out</title>
<para>Log in (when you see <prompt >login:</prompt>) as a user you
created during installation or as <username>root</username>.
<para>Log in (when you see <prompt>login:</prompt>) as a user you
created during installation or as <systemitem class="username">root</systemitem>.
(Your FreeBSD installation will already have an account for
<username>root</username>; who can go anywhere and do anything, including deleting
<systemitem class="username">root</systemitem>; who can go anywhere and do anything, including deleting
essential files, so be careful!) The symbols &prompt.user; and
&prompt.root; in the following stand for the prompt (yours may
be different), with &prompt.user; indicating an ordinary user
and &prompt.root; indicating <username>root</username>.</para>
and &prompt.root; indicating <systemitem class="username">root</systemitem>.</para>
<para>To log out (and get a new <prompt >login:</prompt> prompt)
<para>To log out (and get a new <prompt>login:</prompt> prompt)
type</para>
<informalexample>
@ -94,11 +86,11 @@
do not want to have to reinstall this thing, do you?</para>
</sect1>
<sect1 id="adding-a-user">
<sect1 xml:id="adding-a-user">
<title>Adding A User with Root Privileges</title>
<para>If you did not create any users when you installed the system
and are thus logged in as <username>root</username>, you should probably create a
and are thus logged in as <systemitem class="username">root</systemitem>, you should probably create a
user now with</para>
<informalexample>
@ -112,39 +104,39 @@
enter to accept each default. These defaults are saved in
<filename>/etc/adduser.conf</filename>, an editable file.</para>
<para>Suppose you create a user <username>jack</username> with
full name <emphasis>Jack Benimble</emphasis>. Give <username>jack</username> a
<para>Suppose you create a user <systemitem class="username">jack</systemitem> with
full name <emphasis>Jack Benimble</emphasis>. Give <systemitem class="username">jack</systemitem> a
password if security (even kids around who might pound on the
keyboard) is an issue. When it asks you if you want to invite
<username>jack</username> into other groups, type <groupname>wheel</groupname></para>
<systemitem class="username">jack</systemitem> into other groups, type <systemitem class="groupname">wheel</systemitem></para>
<informalexample>
<screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen>
</informalexample>
<para>This will make it possible to log in as
<username>jack</username> and use the &man.su.1;
command to become <username>root</username>. Then you will not get scolded any more for
logging in as <username>root</username>.</para>
<systemitem class="username">jack</systemitem> and use the &man.su.1;
command to become <systemitem class="username">root</systemitem>. Then you will not get scolded any more for
logging in as <systemitem class="username">root</systemitem>.</para>
<para>You can quit <command>adduser</command> any time by typing
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>,
and at the end you will have a chance to approve your new user or
simply type <keycap>n</keycap> for no. You might want to create
a second new user so that when you edit <username>jack</username>'s login
a second new user so that when you edit <systemitem class="username">jack</systemitem>'s login
files, you will have a hot spare in case something goes
wrong.</para>
<para>Once you have done this, use <command>exit</command> to get
back to a login prompt and log in as <username>jack</username>.
back to a login prompt and log in as <systemitem class="username">jack</systemitem>.
In general, it is a good idea to do as much work as possible as
an ordinary user who does not have the power&mdash;and
risk&mdash;of <username>root</username>.</para>
risk&mdash;of <systemitem class="username">root</systemitem>.</para>
<para>If you already created a user and you want the user to be
able to <command>su</command> to <username>root</username>, you can log in as <username>root</username>
and edit the file <filename>/etc/group</filename>, adding <username>jack</username>
to the first line (the group <groupname>wheel</groupname>). But
able to <command>su</command> to <systemitem class="username">root</systemitem>, you can log in as <systemitem class="username">root</systemitem>
and edit the file <filename>/etc/group</filename>, adding <systemitem class="username">jack</systemitem>
to the first line (the group <systemitem class="groupname">wheel</systemitem>). But
first you need to practice &man.vi.1;, the text editor&mdash;or
use the simpler text editor, &man.ee.1;, installed on recent
versions of FreeBSD.</para>
@ -153,7 +145,7 @@
command.</para>
</sect1>
<sect1 id="looking-around">
<sect1 xml:id="looking-around">
<title>Looking Around</title>
<para>Logged in as an ordinary user, look around and try out some
@ -189,7 +181,7 @@
</varlistentry>
<varlistentry>
<term><command>ls <option>-F</option></command></term>
<term><command>ls -F</command></term>
<listitem>
<para>Lists the files in the current directory with a
@ -200,7 +192,7 @@
</varlistentry>
<varlistentry>
<term><command>ls <option>-l</option></command></term>
<term><command>ls -l</command></term>
<listitem>
<para>Lists the files in long format&mdash;size, date,
@ -209,11 +201,11 @@
</varlistentry>
<varlistentry>
<term><command>ls <option>-a</option></command></term>
<term><command>ls -a</command></term>
<listitem>
<para>Lists hidden <quote>dot</quote> files with the others.
If you are <username>root</username>, the <quote>dot</quote> files show up
If you are <systemitem class="username">root</systemitem>, the <quote>dot</quote> files show up
without the <option>-a</option> switch.</para>
</listitem>
</varlistentry>
@ -223,13 +215,13 @@
<listitem>
<para>Changes directories. <command>cd
<parameter>..</parameter></command> backs up one level;
..</command> backs up one level;
note the space after <command>cd</command>. <command>cd
<parameter>/usr/local</parameter></command> goes there.
<command>cd <parameter>~</parameter></command> goes to the
/usr/local</command> goes there.
<command>cd ~</command> goes to the
home directory of the person logged in&mdash;e.g.,
<filename>/usr/home/jack</filename>. Try <command>cd
<parameter>/cdrom</parameter></command>, and then
/cdrom</command>, and then
<command>ls</command>, to find out if your CDROM is
mounted and working.</para>
</listitem>
@ -237,20 +229,20 @@
<varlistentry>
<term><command>view
<replaceable>filename</replaceable></command></term>
filename</command></term>
<listitem>
<para>Lets you look at a file (named
<replaceable>filename</replaceable>) without changing it.
Try <command>view
<parameter>/etc/fstab</parameter></command>.
/etc/fstab</command>.
Type <command>:q</command> to quit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>cat
<replaceable>filename</replaceable></command></term>
filename</command></term>
<listitem>
<para>Displays <replaceable>filename</replaceable> on
@ -261,9 +253,9 @@
<keycap>ScrollLock</keycap> again to quit scrolling. You
might want to try <command>cat</command> on some of the
dot files in your home directory&mdash;<command>cat
<parameter>.cshrc</parameter></command>, <command>cat
<parameter>.login</parameter></command>, <command>cat
<parameter>.profile</parameter></command>.</para>
.cshrc</command>, <command>cat
.login</command>, <command>cat
.profile</command>.</para>
</listitem>
</varlistentry>
</variablelist>
@ -277,7 +269,7 @@
<filename>/etc/csh.cshrc</filename>.</para>
</sect1>
<sect1 id="getting-help">
<sect1 xml:id="getting-help">
<title>Getting Help and Information</title>
<para>Here are some useful sources of help.
@ -288,7 +280,7 @@
<variablelist>
<varlistentry>
<term><command>apropos
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>Everything containing string
@ -299,12 +291,12 @@
<varlistentry>
<term><command>man
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>The manual page for <replaceable>text</replaceable>. The
major source of documentation for &unix; systems.
<command>man <parameter>ls</parameter></command> will tell
<command>man ls</command> will tell
you all the ways to use the <command>ls</command> command.
Press <keycap>Enter</keycap> to move through text,
<keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo>
@ -318,7 +310,7 @@
<varlistentry>
<term><command>which
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>Tells you where in the user's path the command
@ -328,7 +320,7 @@
<varlistentry>
<term><command>locate
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>All the paths where the string
@ -338,7 +330,7 @@
<varlistentry>
<term><command>whatis
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>Tells you what the command
@ -350,7 +342,7 @@
<varlistentry>
<term><command>whereis
<replaceable>text</replaceable></command></term>
text</command></term>
<listitem>
<para>Finds the file <replaceable>text</replaceable>, giving
@ -368,7 +360,7 @@
<command>script</command>. <command>more</command> lets you
read a page at a time as it does in DOS, e.g., <command>ls -l |
more</command> or <command>more
<replaceable>filename</replaceable></command>. The
filename</command>. The
<literal>*</literal> works as a wildcard&mdash;e.g., <command>ls
w*</command> will show you files beginning with
<literal>w</literal>.</para>
@ -378,7 +370,7 @@
on a database that is rebuilt weekly. If your machine is not
going to be left on over the weekend (and running FreeBSD), you
might want to run the commands for daily, weekly, and monthly
maintenance now and then. Run them as <username>root</username> and, for now, give each one
maintenance now and then. Run them as <systemitem class="username">root</systemitem> and, for now, give each one
time to finish before you start the next one.</para>
<informalexample>
@ -404,7 +396,7 @@
<para>Running such commands is part of system
administration&mdash;and as a single user of a &unix; system,
you are your own system administrator. Virtually everything you
need to be <username>root</username> to do is system administration. Such
need to be <systemitem class="username">root</systemitem> to do is system administration. Such
responsibilities are not covered very well even in those big fat
books on &unix;, which seem to devote a lot of space to pulling
down menus in windows managers. You might want to get one of
@ -417,12 +409,12 @@
ISBN 0-596-00343-9). I used Nemeth.</para>
</sect1>
<sect1 id="editing-text">
<sect1 xml:id="editing-text">
<title>Editing Text</title>
<para>To configure your system, you need to edit text files. Most
of them will be in the <filename>/etc</filename> directory; and
you will need to <command>su</command> to <username>root</username> to be able to
you will need to <command>su</command> to <systemitem class="username">root</systemitem> to be able to
change them. You can use the easy <command>ee</command>, but in
the long run the text editor <command>vi</command> is worth
learning. There is an excellent tutorial on vi in
@ -465,7 +457,7 @@
<para>To edit a file, type</para>
<informalexample>
<screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>vi filename</userinput></screen>
</informalexample>
<para>Move through the text with the arrow keys.
@ -538,11 +530,11 @@
</varlistentry>
<varlistentry>
<term><command>/<replaceable>text</replaceable></command></term>
<term><command>/text</command></term>
<listitem>
<para>to move the cursor to <replaceable>text</replaceable>;
<command>/<keycap>Enter</keycap></command> (the enter key)
<command>/Enter</command> (the enter key)
to find the next instance of
<replaceable>text</replaceable>.</para>
</listitem>
@ -557,7 +549,7 @@
</varlistentry>
<varlistentry>
<term><command><replaceable>n</replaceable>G</command></term>
<term><command>nG</command></term>
<listitem>
<para>to go to line <replaceable>n</replaceable> in the
@ -587,7 +579,7 @@
<para>Practice with <command>vi</command> in your home directory
by creating a new file with <command>vi
<replaceable>filename</replaceable></command> and adding and
filename</command> and adding and
deleting text, saving the file, and calling it up again.
<command>vi</command> delivers some surprises because it is
really quite complex, and sometimes you will inadvertently issue a
@ -601,9 +593,9 @@
<command>:w</command>) when you need to.</para>
<para>Now you can <command>cd</command> to
<filename>/etc</filename>, <command>su</command> to <username>root</username>, use
<filename>/etc</filename>, <command>su</command> to <systemitem class="username">root</systemitem>, use
<command>vi</command> to edit the file
<filename>/etc/group</filename>, and add a user to <groupname>wheel</groupname> so the
<filename>/etc/group</filename>, and add a user to <systemitem class="groupname">wheel</systemitem> so the
user has root privileges. Just add a comma and the user's login
name to the end of the first line in the file, press
<keycap>Esc</keycap>, and use <command>:wq</command> to write
@ -611,7 +603,7 @@
put a space after the comma, did you?)</para>
</sect1>
<sect1 id="printing-files-from-dos">
<sect1 xml:id="printing-files-from-dos">
<title>Printing Files from DOS</title>
<para>At this point you probably do not have the printer working,
@ -628,7 +620,7 @@
<para>will remove formatting codes and send the manual page to the
<filename>chmod.txt</filename> file instead of showing it on
your screen. Now put a dos-formatted diskette in your floppy
drive <devicename>a</devicename>, <command>su</command> to <username>root</username>, and type</para>
drive <filename>a</filename>, <command>su</command> to <systemitem class="username">root</systemitem>, and type</para>
<informalexample>
<screen>&prompt.root; <userinput>/sbin/mount -t msdosfs /dev/fd0 /mnt</userinput></screen>
@ -637,7 +629,7 @@
<para>to mount the floppy drive on
<filename>/mnt</filename>.</para>
<para>Now (you no longer need to be <username>root</username>, and you can type
<para>Now (you no longer need to be <systemitem class="username">root</systemitem>, and you can type
<command>exit</command> to get back to being user jack) you can
go to the directory where you created
<filename>chmod.txt</filename> and copy the file to the floppy
@ -666,7 +658,7 @@
what do I do?</quote>&mdash;people will want to know what
<command>dmesg</command> has to say.</para>
<para>You can now unmount the floppy drive (as <username>root</username>) to get the
<para>You can now unmount the floppy drive (as <systemitem class="username">root</systemitem>) to get the
disk out with</para>
<informalexample>
@ -688,18 +680,17 @@
<filename>/var/spool/output</filename>. If your printer is on
<hardware>lpt0</hardware> (what DOS calls
<hardware>LPT1</hardware>), you may only need to go to
<filename>/var/spool/output</filename> and (as <username>root</username>) create the
<filename>/var/spool/output</filename> and (as <systemitem class="username">root</systemitem>) create the
directory <filename>lpd</filename> by typing: <command>mkdir
lpd</command>, if it does not already exist. Then the printer
should respond if it is turned on when the system is booted, and
<command>lp</command> or <command>lpr</command> should send a
file to the printer. Whether or not the file actually prints
depends on configuring it, which is covered in the <ulink
url="&url.books.handbook;/index.html">FreeBSD
handbook.</ulink></para>
depends on configuring it, which is covered in the <link xlink:href="&url.books.handbook;/index.html">FreeBSD
handbook.</link></para>
</sect1>
<sect1 id="other-useful-commands">
<sect1 xml:id="other-useful-commands">
<title>Other Useful Commands</title>
<variablelist>
@ -721,7 +712,7 @@
</varlistentry>
<varlistentry>
<term><command>rm <replaceable>filename</replaceable></command></term>
<term><command>rm filename</command></term>
<listitem>
<para>remove <replaceable>filename</replaceable>.</para>
@ -729,7 +720,7 @@
</varlistentry>
<varlistentry>
<term><command>rm -R <replaceable>dir</replaceable></command></term>
<term><command>rm -R dir</command></term>
<listitem>
<para>removes a directory <replaceable>dir</replaceable> and all
@ -754,7 +745,7 @@
<term><command>passwd</command></term>
<listitem>
<para>to change user's password (or <username>root</username>'s password)</para>
<para>to change user's password (or <systemitem class="username">root</systemitem>'s password)</para>
</listitem>
</varlistentry>
@ -772,7 +763,7 @@
with</para>
<informalexample>
<screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</replaceable>"</userinput></screen>
<screen>&prompt.user; <userinput>find /usr -name "filename"</userinput></screen>
</informalexample>
<para>You can use <literal>*</literal> as a wildcard in
@ -789,18 +780,17 @@
There is also a lot of &unix; information on the Internet.</para>
</sect1>
<sect1 id="next-steps">
<sect1 xml:id="next-steps">
<title>Next Steps</title>
<para>You should now have the tools you need to get around and
edit files, so you can get everything up and running. There is
a great deal of information in the FreeBSD handbook (which is
probably on your hard drive) and <ulink
url="&url.base;/index.html">FreeBSD's web site</ulink>. A
probably on your hard drive) and <link xlink:href="&url.base;/index.html">FreeBSD's web site</link>. A
wide variety of packages and ports are on the CDROM as well as
the web site. The handbook tells you more about how to use them
(get the package if it exists, with <command>pkg_add
/cdrom/packages/All/<replaceable>packagename</replaceable></command>,
/cdrom/packages/All/packagename</command>,
where <replaceable>packagename</replaceable> is the filename of
the package). The CDROM has lists of the packages and ports
with brief descriptions in
@ -880,7 +870,7 @@
space after the slash.)</para>
</sect1>
<sect1 id="your-working-environment">
<sect1 xml:id="your-working-environment">
<title>Your Working Environment</title>
<para>Your shell is the most important part of your working
@ -920,7 +910,7 @@
</step>
<step>
<para>As <username>root</username>, edit <filename>/etc/shells</filename>, adding a
<para>As <systemitem class="username">root</systemitem>, edit <filename>/etc/shells</filename>, adding a
line in the file for the new shell, in this case
<filename>/usr/local/bin/tcsh</filename>, and save the file.
(Some ports may do this for you.)</para>
@ -935,13 +925,13 @@
</procedure>
<note>
<para>It can be dangerous to change <username>root</username>'s shell to something
<para>It can be dangerous to change <systemitem class="username">root</systemitem>'s shell to something
other than <command>sh</command> or <command>csh</command> on
early versions of FreeBSD and many other versions of &unix;; you
may not have a working shell when the system puts you into
single user mode. The solution is to use <command>su
-m</command> to become <username>root</username>, which will give you the
<command>tcsh</command> as <username>root</username>, because the shell is part of
-m</command> to become <systemitem class="username">root</systemitem>, which will give you the
<command>tcsh</command> as <systemitem class="username">root</systemitem>, because the shell is part of
the environment. You can make this permanent by adding it to
your <filename>.tcshrc</filename> file as an alias with:</para>
<programlisting>alias su su -m</programlisting>
@ -962,8 +952,8 @@
for <command>tcsh</command>, but here is a line to put in your
<filename>.tcshrc</filename> that will tell you how many
commands you have typed, what time it is, and what directory you
are in. It also produces a <literal>></literal> if you are an
ordinary user and a <literal>#</literal> if you are <username>root</username>, but
are in. It also produces a <literal>&gt;</literal> if you are an
ordinary user and a <literal>#</literal> if you are <systemitem class="username">root</systemitem>, but
tsch will do that in any case:</para>
<para>set prompt = "%h %t %~ %# "</para>
@ -984,10 +974,10 @@
vt100</command>.</para>
</sect1>
<sect1 id="other">
<sect1 xml:id="other">
<title>Other</title>
<para>As <username>root</username>, you can unmount the CDROM with
<para>As <systemitem class="username">root</systemitem>, you can unmount the CDROM with
<command>/sbin/umount /cdrom</command>, take it out of the
drive, insert another one, and mount it with
<command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming
@ -1007,7 +997,7 @@
<command>man lndir</command>.</para>
</sect1>
<sect1 id="comments-welcome">
<sect1 xml:id="comments-welcome">
<title>Comments Welcome</title>
<para>If you use this guide I would be interested in knowing where it

151
en_US.ISO8859-1/articles/p4-primer/article.xml
View file

@ -1,24 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<article lang='en'>
<title>Perforce in &os; Development</title>
<articleinfo>
<info><title>Perforce in &os; Development</title>
<authorgroup>
<author>
<firstname>Scott</firstname>
<surname>Long</surname>
<affiliation>
<author><personname><firstname>Scott</firstname><surname>Long</surname></personname><affiliation>
<address><email>scottl@FreeBSD.org</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cvsup;
&tm-attrib.general;
@ -27,25 +22,24 @@
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>The &os; project uses the <application>Perforce</application>
version control system to manage experimental projects that are
not ready for the main Subversion repository.</para>
<sect2 id="resources">
<sect2 xml:id="resources">
<title>Availability, Documentation, and Resources</title>
<para>While <application>Perforce</application> is a commercial
product, the client software for interacting with the server is
freely available from Perforce. It can be easily installed on
&os; via the <filename role="package">devel/p4</filename>
&os; via the <package>devel/p4</package>
port or can be downloaded from the <application>Perforce</application>
web site at <ulink
url="http://www.perforce.com/perforce/loadprog.html"></ulink>,
web site at <uri xlink:href="http://www.perforce.com/perforce/loadprog.html">http://www.perforce.com/perforce/loadprog.html</uri>,
which also offers client applications for other OS's.</para>
<para>While there is a GUI client available, most people use the
@ -53,8 +47,7 @@
document is written from the point of view of using this
command.</para>
<para>Detailed documentation is available online at <ulink
url="http://www.perforce.com/perforce/technical.html"></ulink>.</para>
<para>Detailed documentation is available online at <uri xlink:href="http://www.perforce.com/perforce/technical.html">http://www.perforce.com/perforce/technical.html</uri>.</para>
<para>Reading the <quote>Perforce User's Guide</quote> and
<quote>Perforce Command Reference</quote> is highly recommended.
@ -63,28 +56,25 @@
help</command> command.</para>
<para>The &os; <application>Perforce</application> server is
hosted on <hostid role="fqdn">perforce.freebsd.org</hostid>,
hosted on <systemitem class="fqdomainname">perforce.freebsd.org</systemitem>,
port <literal>1666</literal>. The repository is browsable
online at <ulink url="http://p4web.freebsd.org"></ulink>.
online at <uri xlink:href="http://p4web.freebsd.org">http://p4web.freebsd.org</uri>.
Some portions of the repository are also automatically exported
to a number of legacy <application>CVSup</application> servers.</para>
</sect2>
</sect1>
<sect1 id="start">
<sect1 xml:id="start">
<title>Getting Started</title>
<para>The first step to using <application>Perforce</application> is
to obtain an account on the server. If you already have a <hostid
role="domainname">FreeBSD.org</hostid> account, log into <hostid
role="hostname">freefall</hostid>, run the following command, and
to obtain an account on the server. If you already have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, log into <systemitem class="fqdomainname">freefall</systemitem>, run the following command, and
enter a password that is not the same as your &os; login or any
other SSH passphrase:</para>
<screen>&prompt.user; <userinput>/usr/local/bin/p4newuser</userinput></screen>
<para>Of course if you do not have a <hostid
role="domainname">FreeBSD.org</hostid> account, you will need to
<para>Of course if you do not have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, you will need to
coordinate with your sponsor.</para>
<warning>
@ -104,8 +94,7 @@
<screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen>
<note>
<para>Users with shell access on the <hostid
role="domainname">FreeBSD.org</hostid> cluster may wish to tunnel
<para>Users with shell access on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster may wish to tunnel
the <application>Perforce</application> client-server protocol via
an SSH tunnel, in which case the above string should be set to
<literal>localhost</literal>.</para>
@ -115,8 +104,8 @@
and <envar>P4PASSWD</envar> variables be set. Use the username
and password from above, like so:</para>
<screen>&prompt.user; <userinput>export P4USER=<replaceable>username</replaceable></userinput>
&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>export P4USER=username</userinput>
&prompt.user; <userinput>export P4PASSWD=password</userinput></screen>
<para>Test that this works by running the following command:</para>
@ -127,7 +116,7 @@
variable set correctly.</para>
</sect1>
<sect1 id="clients">
<sect1 xml:id="clients">
<title>Clients</title>
<para><application>Perforce</application> provides access to the
@ -156,7 +145,7 @@
you want, but it must be unique within the
<application>Perforce</application> server. A naming
convention that is commonly used is
<literal><replaceable>username</replaceable>_<replaceable>machinename</replaceable></literal>,
<literal>username_machinename</literal>,
which makes it easy to identify clients when browsing them.
A default name will be filled in that is just the machine
name.</para>
@ -217,13 +206,12 @@
<para>This will map the entire
<application>Perforce</application> repository to the
<filename class="directory">Root</filename> directory of your
<filename>Root</filename> directory of your
client. <emphasis>DO NOT USE THIS DEFAULT!</emphasis> The
&os; repo is huge, and trying to map and sync it all will
take an enormous amount of resources. Instead, only map the
section of the repo that you intend to work on. For
example, there is the smpng project tree at <filename
class="directory">//depot/projects/smpng</filename>. A
example, there is the smpng project tree at <filename>//depot/projects/smpng</filename>. A
mapping for this might look like:</para>
<programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting>
@ -264,14 +252,14 @@
<para>Existing clients can be listed via the <command>p4
clients</command> command. They can be viewed without being
modified via the <command>p4 client -o
<replaceable>clientname</replaceable></command> command.</para>
clientname</command> command.</para>
<para>Whenever you are interacting with files in
<application>Perforce</application>, the <envar>P4CLIENT</envar>
environment variable must be set to the name of the client that
you are using, like so:</para>
<screen>&prompt.user; <userinput>export P4CLIENT=<replaceable>myclientname</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>export P4CLIENT=myclientname</userinput></screen>
<para>Note that client mappings in the repository are not exclusive;
multiple clients can map in the same part of the repository. This
@ -280,7 +268,7 @@
code.</para>
</sect1>
<sect1 id="syncing">
<sect1 xml:id="syncing">
<title>Syncing</title>
<para>Once you have a client specification defined and the
@ -304,18 +292,18 @@
<para>You can sync a subset of your tree or client by specifying a
relative path to the sync command. For example, to only sync the
<filename class="directory">ufs</filename> directory of the
<filename>ufs</filename> directory of the
<literal>smpng</literal> project, you might do the
following:</para>
<screen>&prompt.user; <userinput>cd <replaceable>projectroot</replaceable>/smpng</userinput>
<screen>&prompt.user; <userinput>cd projectroot/smpng</userinput>
&prompt.user; <userinput>p4 sync src/sys/ufs/...</userinput></screen>
<para>Specifying a local relative path works for many other
<command>p4</command> commands.</para>
</sect1>
<sect1 id="branches">
<sect1 xml:id="branches">
<title>Branches</title>
<para>One of the strongest features of
@ -335,10 +323,9 @@
<application>Perforce</application> repository (the
<quote>depot</quote>) is a single flat tree. Every file, whether
a unique creation or a derivative from a branch, is accessible via
a simple path under the server <filename
class="directory">//depot</filename> directory. When you create a
a simple path under the server <filename>//depot</filename> directory. When you create a
branch, all you are doing is creating a new path under the
<filename class="directory">//depot</filename>. This is in sharp
<filename>//depot</filename>. This is in sharp
contrast to systems like CVS, where each branch lives in the same
path as its parent. With <application>Perforce</application>, the
server tracks the relationship between the files in the parent and
@ -347,7 +334,7 @@
<para>The first step to creating a branch is to create a branch
specification. This is similar to a client specification, but is
created via the command <command>p4 branch
<replaceable>branchname</replaceable></command>.</para>
branchname</command>.</para>
<para>The following important fields are explained:</para>
@ -411,7 +398,7 @@
command, as described in the next section.</para>
</sect1>
<sect1 id="Integrations">
<sect1 xml:id="Integrations">
<title>Integrations</title>
<para><quote>Integration</quote> is the term used by
@ -431,7 +418,7 @@
<para>The common way to do an integration is with the following
command:</para>
<screen>&prompt.user; <userinput>p4 integrate -b <replaceable>branchname</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 integrate -b branchname</userinput></screen>
<para><replaceable>branchname</replaceable> is the name given to a
branch spec, as discussed in the previous section. This command
@ -467,7 +454,7 @@
section.</para>
</sect1>
<sect1 id="submit">
<sect1 xml:id="submit">
<title>Submit</title>
<para>Changes that are made locally should be committed back to the
@ -521,7 +508,7 @@
case-by-case basis.</para>
</sect1>
<sect1 id="editing">
<sect1 xml:id="editing">
<title>Editing</title>
<para>The state of each file in the client is tracked and saved on
@ -534,7 +521,7 @@
<para>To open a file for editing, use the <command>p4 edit</command>
command like so:</para>
<screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 edit filename</userinput></screen>
<para>This marks the file on the server as being in the <emphasis>edit</emphasis> state,
which then allows it to be submitted after changes are made, or
@ -558,7 +545,7 @@
your changes and revert it to its original state, run the
<command>p4 revert</command> command like so:</para>
<screen>&prompt.user; <userinput>p4 revert <replaceable>filename</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 revert filename</userinput></screen>
<para>This resyncs the file to the contents of the server, and
removes the edit attribute from the server. Any local changes
@ -576,7 +563,7 @@
sync</command>.</para>
</sect1>
<sect1 id="changes">
<sect1 xml:id="changes">
<title>Changes, Descriptions, and History</title>
<para>Changes to the <application>Perforce</application> depot can
@ -584,7 +571,7 @@
will provide a brief description of each change, who made the
change, and what its change number was. A change can be examined
in detail via the <command>p4 describe
<replaceable>changenumber</replaceable></command> command. This
changenumber</command> command. This
will provide the submit log and the diffs of the actual change.</para>
<para>Commonly, the <command>p4&nbsp;describe</command> command is used in one
@ -592,7 +579,7 @@
<variablelist>
<varlistentry>
<term><command>p4 describe -s <replaceable>CHANGE</replaceable></command></term>
<term><command>p4 describe -s CHANGE</command></term>
<listitem>
<para>List a short description of
@ -602,7 +589,7 @@
</varlistentry>
<varlistentry>
<term><command>p4 describe -du <replaceable>CHANGE</replaceable></command></term>
<term><command>p4 describe -du CHANGE</command></term>
<listitem>
<para>List a description of changeset <emphasis>CHANGE</emphasis>,
@ -614,7 +601,7 @@
</varlistentry>
<varlistentry>
<term><command>p4 describe -dc <replaceable>CHANGE</replaceable></command></term>
<term><command>p4 describe -dc CHANGE</command></term>
<listitem>
<para>List a description of changeset <emphasis>CHANGE</emphasis>,
@ -627,12 +614,12 @@
</variablelist>
<para>The <command>p4 filelog
<replaceable>filename</replaceable></command> command will show
filename</command> command will show
the history of a file, including all submits, integrations, and
branches of it.</para>
</sect1>
<sect1 id="diffs">
<sect1 xml:id="diffs">
<title>Diffs</title>
<para>There are two methods of producing file diffs in
@ -667,11 +654,11 @@
<option>-dc</option> flags do work. The two forms of this
command are:</para>
<screen>&prompt.user; <userinput>p4 diff2 -b <replaceable>branchname</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 diff2 -b branchname</userinput></screen>
<para>and</para>
<screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>path1</replaceable> //depot/<replaceable>path2</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 diff2 //depot/path1 //depot/path2</userinput></screen>
</listitem>
</varlistentry>
</variablelist>
@ -686,11 +673,10 @@
(the <option>-u</option> flag of <option>diff2</option> will
produce unified diffs that are somewhat compatible, but it does
not include files that have been added or deleted). There is a
post-processing script at: <ulink
url="http://people.freebsd.org/~scottl/awkdiff"></ulink>.</para>
post-processing script at: <uri xlink:href="http://people.freebsd.org/~scottl/awkdiff">http://people.freebsd.org/~scottl/awkdiff</uri>.</para>
</sect1>
<sect1 id="add-rm-files">
<sect1 xml:id="add-rm-files">
<title>Adding and Removing Files</title>
<para>Integrating a branch will bring existing files into your tree,
@ -698,7 +684,7 @@
Adding files is easily done be creating the file and then running
the <command>p4 add</command> command like so:</para>
<screen>&prompt.user; <userinput>p4 add <replaceable>filename</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 add filename</userinput></screen>
<para>If you want to add a whole tree of files, run a command
like:</para>
@ -723,7 +709,7 @@
<para>Removing a file is just as easy with the <command>p4</command>
delete command like so:</para>
<screen>&prompt.user; <userinput>p4 delete <replaceable>filename</replaceable></userinput></screen>
<screen>&prompt.user; <userinput>p4 delete filename</userinput></screen>
<para>This will mark the file for deletion from the depot the next
time that a submit is run. It will also remove the local copy of
@ -739,7 +725,7 @@
admin access.</para>
</sect1>
<sect1 id="working-with-diffs">
<sect1 xml:id="working-with-diffs">
<title>Working with diffs</title>
<para>Sometimes you might need to apply a diff from another source
@ -775,7 +761,7 @@
<para>and just do a <command>p4 submit</command> after that.</para>
</sect1>
<sect1 id="renaming-files">
<sect1 xml:id="renaming-files">
<title>Renaming files</title>
<para><application>Perforce</application> does not have a built-in
@ -788,9 +774,9 @@
dealing with this is to do a one-time, in-tree integration, like
so:</para>
<screen>&prompt.user; <userinput>p4 integrate -i <replaceable>oldfile</replaceable> <replaceable>newfile</replaceable></userinput>
<screen>&prompt.user; <userinput>p4 integrate -i oldfile newfile</userinput>
&prompt.user; <userinput>p4 resolve</userinput>
&prompt.user; <userinput>p4 delete <replaceable>oldfile</replaceable></userinput>
&prompt.user; <userinput>p4 delete oldfile</userinput>
&prompt.user; <userinput>p4 submit</userinput></screen>
<para>The integration will force <application>Perforce</application>
@ -803,7 +789,7 @@
for normal branch-based integrations.</para>
</sect1>
<sect1 id="freebsd-cvs-and-p4">
<sect1 xml:id="freebsd-cvs-and-p4">
<title>Interactions between &os; Subversion and Perforce</title>
<para>The &os; <application>Perforce</application> and <application>Subversion</application>
@ -811,8 +797,7 @@
tracked at near-real-time in <application>Perforce</application>.
Every 2 minutes, the Subversion server is polled for updates in the HEAD
branch, and those updates are committed to
<application>Perforce</application> in the <filename
class="directory">//depot/vendor/freebsd/...</filename> tree. This
<application>Perforce</application> in the <filename>//depot/vendor/freebsd/...</filename> tree. This
tree is then available for branching and integrating to derivative
projects. Any project that directly modifies that &os; source
code should have this tree as its branch parent (or grandparent,
@ -831,7 +816,7 @@
something that you are interested in.</para>
</sect1>
<sect1 id="offline-ops">
<sect1 xml:id="offline-ops">
<title>Offline Operation</title>
<para>One weakness of <application>Perforce</application> is that it
@ -853,7 +838,7 @@
so be extra vigilant with this.</para>
</sect1>
<sect1 id="soc">
<sect1 xml:id="soc">
<title>Notes for Google Summer of Code</title>
<para>Most &os; projects under the Google Summer of Code program
@ -862,20 +847,16 @@
<itemizedlist>
<listitem>
<para><filename
class="directory">//depot/projects/soc2005/<replaceable>project-name</replaceable>/...</filename></para>
<para><filename>//depot/projects/soc2005/project-name/...</filename></para>
</listitem>
<listitem>
<para><filename
class="directory">//depot/projects/soc2006/<replaceable>project-name</replaceable>/...</filename></para>
<para><filename>//depot/projects/soc2006/project-name/...</filename></para>
</listitem>
<listitem>
<para><filename
class="directory">//depot/projects/soc2007/<replaceable>project-name</replaceable>/...</filename></para>
<para><filename>//depot/projects/soc2007/project-name/...</filename></para>
</listitem>
<listitem>
<para><filename
class="directory">//depot/projects/soc2008/<replaceable>project-name</replaceable>/...</filename></para>
<para><filename>//depot/projects/soc2008/project-name/...</filename></para>
</listitem>
</itemizedlist>

293
en_US.ISO8859-1/articles/pam/article.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!--
- Copyright (c) 2001-2003 Networks Associates Technology, Inc.
- All rights reserved.
@ -35,10 +34,9 @@
- OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGE.
-->
<article xmlns:xi="http://www.w3.org/2001/XInclude" lang='en'>
<articleinfo>
<title>Pluggable Authentication Modules</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Pluggable Authentication Modules</title>
<abstract>
<para>This article describes the underlying principles and
@ -55,14 +53,10 @@
</copyright>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
<contrib>Contributed by </contrib>
</author>
<author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname><contrib>Contributed by </contrib></author>
</authorgroup>
<legalnotice id="pam-legalnotice">
<legalnotice xml:id="pam-legalnotice">
<para>This article was written for the FreeBSD Project by
ThinkSec AS and Network Associates Laboratories, the Security
Research Division of Network Associates, Inc. under
@ -70,7 +64,7 @@
as part of the DARPA CHATS research program.</para>
</legalnotice>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.linux;
&tm-attrib.opengroup;
@ -79,10 +73,10 @@
</legalnotice>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
</info>
<section id="pam-intro">
<title id="pam-intro.title">Introduction</title>
<section xml:id="pam-intro">
<title xml:id="pam-intro.title">Introduction</title>
<para>The Pluggable Authentication Modules (PAM) library is a
generalized API for authentication-related services which allows
@ -104,11 +98,11 @@
Linux and &solaris;.</para>
</section>
<section id="pam-terms">
<title id="pam-terms.title">Terms and conventions</title>
<section xml:id="pam-terms">
<title xml:id="pam-terms.title">Terms and conventions</title>
<section id="pam-definitions">
<title id="pam-definitions.title">Definitions</title>
<section xml:id="pam-definitions">
<title xml:id="pam-definitions.title">Definitions</title>
<para>The terminology surrounding PAM is rather confused.
Neither Samar and Lai's original paper nor the XSSO
@ -253,8 +247,8 @@
</glosslist>
</section>
<section id="pam-usage-examples">
<title id="pam-usage-examples.title">Usage examples</title>
<section xml:id="pam-usage-examples">
<title xml:id="pam-usage-examples.title">Usage examples</title>
<para>This section aims to illustrate the meanings of some of
the terms defined above by way of a handful of simple
@ -392,11 +386,11 @@ sshd password required pam_permit.so</programlisting>
-->
</section>
<section id="pam-essentials">
<title id="pam-essentials.title">PAM Essentials</title>
<section xml:id="pam-essentials">
<title xml:id="pam-essentials.title">PAM Essentials</title>
<section id="pam-facilities-primitives">
<title id="pam-facilities-primitives.title">Facilities and
<section xml:id="pam-facilities-primitives">
<title xml:id="pam-facilities-primitives.title">Facilities and
primitives</title>
<para>The PAM API offers six different authentication primitives
@ -498,8 +492,8 @@ sshd password required pam_permit.so</programlisting>
</section>
<section id="pam-modules">
<title id="pam-modules.title">Modules</title>
<section xml:id="pam-modules">
<title xml:id="pam-modules.title">Modules</title>
<para>Modules are a very central concept in PAM; after all,
they are the <quote>M</quote> in <quote>PAM</quote>. A PAM
@ -509,12 +503,12 @@ sshd password required pam_permit.so</programlisting>
authentication facility, for instance, include the &unix;
password database, NIS, LDAP and Radius.</para>
<section id="pam-module-naming">
<title id="pam-module-naming.title">Module Naming</title>
<section xml:id="pam-module-naming">
<title xml:id="pam-module-naming.title">Module Naming</title>
<para>FreeBSD implements each mechanism in a single module,
named
<literal>pam_<replaceable>mechanism</replaceable>.so</literal>
<literal>pam_mechanism.so</literal>
(for instance, <literal>pam_unix.so</literal> for the &unix;
mechanism.) Other implementations sometimes have separate
modules for separate facilities, and include the facility
@ -524,8 +518,8 @@ sshd password required pam_permit.so</programlisting>
commonly used to authenticate dialup users.</para>
</section>
<section id="pam-module-versioning">
<title id="pam-module-versioning.title">Module Versioning</title>
<section xml:id="pam-module-versioning">
<title xml:id="pam-module-versioning.title">Module Versioning</title>
<para>FreeBSD's original PAM implementation, based on
Linux-PAM, did not use version numbers for PAM modules.
@ -549,8 +543,8 @@ sshd password required pam_permit.so</programlisting>
</section>
</section>
<section id="pam-chains-policies">
<title id="pam-chains-policies.title">Chains and
<section xml:id="pam-chains-policies">
<title xml:id="pam-chains-policies.title">Chains and
policies</title>
<para>When a server initiates a PAM transaction, the PAM library
@ -657,8 +651,8 @@ sshd password required pam_permit.so</programlisting>
in the same chain as different, unrelated modules.</para>
</section>
<section id="pam-transactions">
<title id="pam-transactions.title">Transactions</title>
<section xml:id="pam-transactions">
<title xml:id="pam-transactions.title">Transactions</title>
<para>The lifecycle of a typical PAM transaction is described
below. Note that if any of these steps fails, the server
@ -743,14 +737,14 @@ sshd password required pam_permit.so</programlisting>
</section>
</section>
<section id="pam-config">
<title id="pam-config.title">PAM Configuration</title>
<section xml:id="pam-config">
<title xml:id="pam-config.title">PAM Configuration</title>
<section id="pam-config-file">
<title id="pam-config-file.title">PAM policy files</title>
<section xml:id="pam-config-file">
<title xml:id="pam-config-file.title">PAM policy files</title>
<section id="pam-config-pam.conf">
<title id="pam-config-pam.conf.title">The
<section xml:id="pam-config-pam.conf">
<title xml:id="pam-config-pam.conf.title">The
<filename>/etc/pam.conf</filename> file</title>
<para>The traditional PAM policy file is
@ -776,8 +770,8 @@ sshd password required pam_permit.so</programlisting>
Either way is fine; either way makes equal sense.</para>
</section>
<section id="pam-config-pam.d">
<title id="pam-config-pam.d.title">The
<section xml:id="pam-config-pam.d">
<title xml:id="pam-config-pam.d.title">The
<filename>/etc/pam.d</filename> directory</title>
<para>OpenPAM and Linux-PAM support an alternate configuration
@ -816,8 +810,8 @@ sshd password required pam_permit.so</programlisting>
software packages.</para>
</section>
<section id="pam-config-file-order">
<title id="pam-config-file-order.title">The policy search
<section xml:id="pam-config-file-order">
<title xml:id="pam-config-file-order.title">The policy search
order</title>
<para>As we have seen above, PAM policies can be found in a
@ -830,8 +824,8 @@ sshd password required pam_permit.so</programlisting>
</section>
</section>
<section id="pam-config-breakdown">
<title id="pam-config-breakdown.title">Breakdown of a
<section xml:id="pam-config-breakdown">
<title xml:id="pam-config-breakdown.title">Breakdown of a
configuration line</title>
<para>As explained in <xref linkend="pam-config-file"/>, each line in
@ -864,8 +858,8 @@ sshd password required pam_permit.so</programlisting>
Unsurprisingly, OpenPAM does not support this syntax.</para>
</section>
<section id="pam-policies">
<title id="pam-policies.title">Policies</title>
<section xml:id="pam-policies">
<title xml:id="pam-policies.title">Policies</title>
<para>To configure PAM correctly, it is essential to understand
how policies are interpreted.</para>
@ -896,7 +890,7 @@ sshd password required pam_permit.so</programlisting>
<colspec colwidth="1*" colname="other"/>
<thead>
<row>
<entry colname="type"></entry>
<entry colname="type"/>
<entry colname="success"><literal>PAM_SUCCESS</literal></entry>
<entry colname="ignore"><literal>PAM_IGNORE</literal></entry>
<entry colname="other"><literal>other</literal></entry>
@ -965,11 +959,11 @@ sshd password required pam_permit.so</programlisting>
</section>
</section>
<section id="pam-freebsd-modules">
<title id="pam-freebsd-modules.title">FreeBSD PAM Modules</title>
<section xml:id="pam-freebsd-modules">
<title xml:id="pam-freebsd-modules.title">FreeBSD PAM Modules</title>
<section id="pam-modules-deny">
<title id="pam-modules-deny.title">&man.pam.deny.8;</title>
<section xml:id="pam-modules-deny">
<title xml:id="pam-modules-deny.title">&man.pam.deny.8;</title>
<para>The &man.pam.deny.8; module is one of the simplest modules
available; it responds to any request with
@ -979,8 +973,8 @@ sshd password required pam_permit.so</programlisting>
modules.</para>
</section>
<section id="pam-modules-echo">
<title id="pam-modules-echo.title">&man.pam.echo.8;</title>
<section xml:id="pam-modules-echo">
<title xml:id="pam-modules-echo.title">&man.pam.echo.8;</title>
<para>The &man.pam.echo.8; module simply passes its arguments to
the conversation function as a
@ -990,8 +984,8 @@ sshd password required pam_permit.so</programlisting>
starting the authentication procedure.</para>
</section>
<section id="pam-modules-exec">
<title id="pam-modules-exec.title">&man.pam.exec.8;</title>
<section xml:id="pam-modules-exec">
<title xml:id="pam-modules-exec.title">&man.pam.exec.8;</title>
<para>The &man.pam.exec.8; module takes its first argument to be
the name of a program to execute, and the remaining arguments
@ -1000,14 +994,14 @@ sshd password required pam_permit.so</programlisting>
time which mounts the user's home directory.</para>
</section>
<section id="pam-modules-ftpusers">
<title id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title>
<section xml:id="pam-modules-ftpusers">
<title xml:id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title>
<para>The &man.pam.ftpusers.8; module</para>
</section>
<section id="pam-modules-group">
<title id="pam-modules-group.title">&man.pam.group.8;</title>
<section xml:id="pam-modules-group">
<title xml:id="pam-modules-group.title">&man.pam.group.8;</title>
<para>The &man.pam.group.8; module accepts or rejects applicants
on the basis of their membership in a particular file group
@ -1017,8 +1011,8 @@ sshd password required pam_permit.so</programlisting>
certain groups of users from a particular service.</para>
</section>
<section id="pam-modules-guest">
<title id="pam-modules-guest.title">&man.pam.guest.8;</title>
<section xml:id="pam-modules-guest">
<title xml:id="pam-modules-guest.title">&man.pam.guest.8;</title>
<para>The &man.pam.guest.8; module allows guest logins using
fixed login names. Various requirements can be placed on the
@ -1028,26 +1022,26 @@ sshd password required pam_permit.so</programlisting>
anonymous FTP logins.</para>
</section>
<section id="pam-modules-krb5">
<title id="pam-modules-krb5.title">&man.pam.krb5.8;</title>
<section xml:id="pam-modules-krb5">
<title xml:id="pam-modules-krb5.title">&man.pam.krb5.8;</title>
<para>The &man.pam.krb5.8; module</para>
</section>
<section id="pam-modules-ksu">
<title id="pam-modules-ksu.title">&man.pam.ksu.8;</title>
<section xml:id="pam-modules-ksu">
<title xml:id="pam-modules-ksu.title">&man.pam.ksu.8;</title>
<para>The &man.pam.ksu.8; module</para>
</section>
<section id="pam-modules-lastlog">
<title id="pam-modules-lastlog.title">&man.pam.lastlog.8;</title>
<section xml:id="pam-modules-lastlog">
<title xml:id="pam-modules-lastlog.title">&man.pam.lastlog.8;</title>
<para>The &man.pam.lastlog.8; module</para>
</section>
<section id="pam-modules-login-access">
<title id="pam-modules-login-access.title">&man.pam.login.access.8;</title>
<section xml:id="pam-modules-login-access">
<title xml:id="pam-modules-login-access.title">&man.pam.login.access.8;</title>
<para>The &man.pam.login.access.8; module provides an
implementation of the account management primitive which
@ -1055,8 +1049,8 @@ sshd password required pam_permit.so</programlisting>
&man.login.access.5; table.</para>
</section>
<section id="pam-modules-nologin">
<title id="pam-modules-nologin.title">&man.pam.nologin.8;</title>
<section xml:id="pam-modules-nologin">
<title xml:id="pam-modules-nologin.title">&man.pam.nologin.8;</title>
<para>The &man.pam.nologin.8; module refuses non-root logins
when <filename>/var/run/nologin</filename> exists. This file
@ -1064,8 +1058,8 @@ sshd password required pam_permit.so</programlisting>
minutes remain until the scheduled shutdown time.</para>
</section>
<section id="pam-modules-opie">
<title id="pam-modules-opie.title">&man.pam.opie.8;</title>
<section xml:id="pam-modules-opie">
<title xml:id="pam-modules-opie.title">&man.pam.opie.8;</title>
<para>The &man.pam.opie.8; module implements the &man.opie.4;
authentication method. The &man.opie.4; system is a
@ -1078,8 +1072,8 @@ sshd password required pam_permit.so</programlisting>
answered, it is not vulnerable to replay attacks.</para>
</section>
<section id="pam-modules-opieaccess">
<title id="pam-modules-opieaccess.title">&man.pam.opieaccess.8;</title>
<section xml:id="pam-modules-opieaccess">
<title xml:id="pam-modules-opieaccess.title">&man.pam.opieaccess.8;</title>
<para>The &man.pam.opieaccess.8; module is a companion module to
&man.pam.opie.8;. Its purpose is to enforce the restrictions
@ -1096,14 +1090,14 @@ sshd password required pam_permit.so</programlisting>
<literal>auth</literal> chain.</para>
</section>
<section id="pam-modules-passwdqc">
<title id="pam-modules-passwdqc.title">&man.pam.passwdqc.8;</title>
<section xml:id="pam-modules-passwdqc">
<title xml:id="pam-modules-passwdqc.title">&man.pam.passwdqc.8;</title>
<para>The &man.pam.passwdqc.8; module</para>
</section>
<section id="pam-modules-permit">
<title id="pam-modules-permit.title">&man.pam.permit.8;</title>
<section xml:id="pam-modules-permit">
<title xml:id="pam-modules-permit.title">&man.pam.permit.8;</title>
<para>The &man.pam.permit.8; module is one of the simplest
modules available; it responds to any request with
@ -1112,20 +1106,20 @@ sshd password required pam_permit.so</programlisting>
empty.</para>
</section>
<section id="pam-modules-radius">
<title id="pam-modules-radius.title">&man.pam.radius.8;</title>
<section xml:id="pam-modules-radius">
<title xml:id="pam-modules-radius.title">&man.pam.radius.8;</title>
<para>The &man.pam.radius.8; module</para>
</section>
<section id="pam-modules-rhosts">
<title id="pam-modules-rhosts.title">&man.pam.rhosts.8;</title>
<section xml:id="pam-modules-rhosts">
<title xml:id="pam-modules-rhosts.title">&man.pam.rhosts.8;</title>
<para>The &man.pam.rhosts.8; module</para>
</section>
<section id="pam-modules-rootok">
<title id="pam-modules-rootok.title">&man.pam.rootok.8;</title>
<section xml:id="pam-modules-rootok">
<title xml:id="pam-modules-rootok.title">&man.pam.rootok.8;</title>
<para>The &man.pam.rootok.8; module reports success if and only
if the real user id of the process calling it (which is
@ -1135,14 +1129,14 @@ sshd password required pam_permit.so</programlisting>
access.</para>
</section>
<section id="pam-modules-securetty">
<title id="pam-modules-securetty.title">&man.pam.securetty.8;</title>
<section xml:id="pam-modules-securetty">
<title xml:id="pam-modules-securetty.title">&man.pam.securetty.8;</title>
<para>The &man.pam.securetty.8; module</para>
</section>
<section id="pam-modules-self">
<title id="pam-modules-self.title">&man.pam.self.8;</title>
<section xml:id="pam-modules-self">
<title xml:id="pam-modules-self.title">&man.pam.self.8;</title>
<para>The &man.pam.self.8; module reports success if and only if
the names of the applicant matches that of the target account.
@ -1151,8 +1145,8 @@ sshd password required pam_permit.so</programlisting>
verified.</para>
</section>
<section id="pam-modules-ssh">
<title id="pam-modules-ssh.title">&man.pam.ssh.8;</title>
<section xml:id="pam-modules-ssh">
<title xml:id="pam-modules-ssh.title">&man.pam.ssh.8;</title>
<para>The &man.pam.ssh.8; module provides both authentication
and session services. The authentication service allows users
@ -1166,14 +1160,14 @@ sshd password required pam_permit.so</programlisting>
console.</para>
</section>
<section id="pam-modules-tacplus">
<title id="pam-modules-tacplus.title">&man.pam.tacplus.8;</title>
<section xml:id="pam-modules-tacplus">
<title xml:id="pam-modules-tacplus.title">&man.pam.tacplus.8;</title>
<para>The &man.pam.tacplus.8; module</para>
</section>
<section id="pam-modules-unix">
<title id="pam-modules-unix.title">&man.pam.unix.8;</title>
<section xml:id="pam-modules-unix">
<title xml:id="pam-modules-unix.title">&man.pam.unix.8;</title>
<para>The &man.pam.unix.8; module implements traditional &unix;
password authentication, using &man.getpwnam.3; to obtain the
@ -1187,8 +1181,8 @@ sshd password required pam_permit.so</programlisting>
</section>
</section>
<section id="pam-appl-prog">
<title id="pam-appl-prog.title">PAM Application Programming</title>
<section xml:id="pam-appl-prog">
<title xml:id="pam-appl-prog.title">PAM Application Programming</title>
<para><!--XXX-->This section has not yet been written.</para>
@ -1207,33 +1201,31 @@ sshd password required pam_permit.so</programlisting>
</section>
<section id="pam-module-prog">
<title id="pam-module-prog.title">PAM Module Programming</title>
<section xml:id="pam-module-prog">
<title xml:id="pam-module-prog.title">PAM Module Programming</title>
<para><!--XXX-->This section has not yet been written.</para>
</section>
<appendix id="pam-sample-appl">
<title id="pam-sample-appl.title">Sample PAM Application</title>
<appendix xml:id="pam-sample-appl">
<title xml:id="pam-sample-appl.title">Sample PAM Application</title>
<para>The following is a minimal implementation of &man.su.1;
using PAM. Note that it uses the OpenPAM-specific
&man.openpam.ttyconv.3; conversation function, which is
prototyped in <filename
class="headerfile">security/openpam.h</filename>. If you wish
prototyped in <filename>security/openpam.h</filename>. If you wish
build this application on a system with a different PAM library,
you will have to provide your own conversation function. A
robust conversation function is surprisingly difficult to
implement; the one presented in <xref
linkend="pam-sample-conv"/> is a good
implement; the one presented in <xref linkend="pam-sample-conv"/> is a good
starting point, but should not be used in real-world
applications.</para>
<programlisting><xi:include href="su.c" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="su.c" parse="text"/></programlisting>
</appendix>
<appendix id="pam-sample-module">
<title id="pam-sample-module.title">Sample PAM Module</title>
<appendix xml:id="pam-sample-module">
<title xml:id="pam-sample-module.title">Sample PAM Module</title>
<para>The following is a minimal implementation of
&man.pam.unix.8;, offering only authentication services. It
@ -1242,11 +1234,11 @@ sshd password required pam_permit.so</programlisting>
&man.pam.get.authtok.3;, which enormously simplifies prompting
the user for a password.</para>
<programlisting><xi:include href="pam_unix.c" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_unix.c" parse="text"/></programlisting>
</appendix>
<appendix id="pam-sample-conv">
<title id="pam-sample-conv.title">Sample PAM Conversation
<appendix xml:id="pam-sample-conv">
<title xml:id="pam-sample-conv.title">Sample PAM Conversation
Function</title>
<para>The conversation function presented below is a greatly
@ -1258,59 +1250,46 @@ sshd password required pam_permit.so</programlisting>
your uses; we believe it to be as robust as a tty-oriented
conversation function can reasonably get.</para>
<programlisting><xi:include href="converse.c" parse="text"/></programlisting>
<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="converse.c" parse="text"/></programlisting>
</appendix>
<bibliography id="pam-further">
<bibliographyinfo>
<title id="pam-further.title">Further Reading</title>
<bibliography xml:id="pam-further">
<info><title xml:id="pam-further.title">Further Reading</title>
<abstract>
<para>This is a list of documents relevant to PAM and related
issues. It is by no means complete.</para>
</abstract>
</bibliographyinfo>
</info>
<bibliodiv>
<title>Papers</title>
<biblioentry>
<title><ulink
url="http://www.sun.com/software/solaris/pam/pam.external.pdf">
<citetitle><link xlink:href="http://www.sun.com/software/solaris/pam/pam.external.pdf">
Making Login Services Independent of Authentication
Technologies</ulink></title>
Technologies</link></citetitle>
<authorgroup>
<author>
<surname>Samar</surname>
<firstname>Vipin</firstname>
</author>
<author>
<surname>Lai</surname>
<firstname>Charlie</firstname>
</author>
<author><personname><surname>Samar</surname><firstname>Vipin</firstname></personname></author>
<author><personname><surname>Lai</surname><firstname>Charlie</firstname></personname></author>
</authorgroup>
<orgname>Sun Microsystems</orgname>
</biblioentry>
<biblioentry>
<title><ulink
url="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open
Single Sign-on Preliminary Specification</ulink></title>
<citetitle><link xlink:href="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open
Single Sign-on Preliminary Specification</link></citetitle>
<orgname>The Open Group</orgname>
<isbn>1-85912-144-6</isbn>
<biblioid class="isbn">1-85912-144-6</biblioid>
<pubdate>June 1997</pubdate>
</biblioentry>
<biblioentry>
<title><ulink
url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt">
Pluggable Authentication Modules</ulink></title>
<author>
<surname>Morgan</surname>
<firstname>Andrew</firstname>
<othername role="mi">G.</othername>
</author>
<pubdate>October 6, 1999</pubdate>
<citetitle><link xlink:href="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt">
Pluggable Authentication Modules</link></citetitle>
<author><personname><surname>Morgan</surname><firstname>Andrew</firstname><othername role="mi">G.</othername></personname></author>
<pubdate>1999-10-06</pubdate>
</biblioentry>
</bibliodiv>
@ -1318,9 +1297,8 @@ sshd password required pam_permit.so</programlisting>
<title>User Manuals</title>
<biblioentry>
<title><ulink
url="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM
Administration</ulink></title>
<citetitle><link xlink:href="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM
Administration</link></citetitle>
<orgname>Sun Microsystems</orgname>
</biblioentry>
</bibliodiv>
@ -1329,25 +1307,18 @@ sshd password required pam_permit.so</programlisting>
<title>Related Web pages</title>
<biblioentry>
<title><ulink url="http://openpam.sourceforge.net/">OpenPAM homepage</ulink></title>
<author>
<surname>Sm&oslash;rgrav</surname>
<firstname>Dag-Erling</firstname>
</author>
<citetitle><link xlink:href="http://openpam.sourceforge.net/">OpenPAM homepage</link></citetitle>
<author><personname><surname>Sm&oslash;rgrav</surname><firstname>Dag-Erling</firstname></personname></author>
<orgname>ThinkSec AS</orgname>
</biblioentry>
<biblioentry>
<title><ulink url="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</ulink></title>
<author>
<surname>Morgan</surname>
<firstname>Andrew</firstname>
<othername role="mi">G.</othername>
</author>
<citetitle><link xlink:href="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</link></citetitle>
<author><personname><surname>Morgan</surname><firstname>Andrew</firstname><othername role="mi">G.</othername></personname></author>
</biblioentry>
<biblioentry>
<title><ulink url="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</ulink></title>
<citetitle><link xlink:href="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</link></citetitle>
<orgname>Sun Microsystems</orgname>
</biblioentry>
</bibliodiv>

48
en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang="en">
<articleinfo>
<title>Port Mentor Guidelines</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Port Mentor Guidelines</title>
<authorgroup>
<corpauthor>The &os; Ports Management Team</corpauthor>
<author><orgname>The &os; Ports Management Team</orgname></author>
</authorgroup>
<pubdate>$FreeBSD$</pubdate>
@ -19,9 +18,9 @@
<holder role="mailto:tabthorpe@FreeBSD.org">Thomas Abthorpe</holder>
<holder role="mailto:crees@FreeBSD.org">Chris Rees</holder>
</copyright>
</articleinfo>
</info>
<sect1 id="port-mentor.guidelines">
<sect1 xml:id="port-mentor.guidelines">
<title>Guideline for Mentor/Mentee relationships</title>
<para>This section is intended to help demystify the
@ -33,7 +32,7 @@
working toward a common goal, maintaining the quality
assurance of the product we call the Ports Tree.</para>
<sect2 id="why.mentor">
<sect2 xml:id="why.mentor">
<title>Why mentor?</title>
<itemizedlist>
@ -55,7 +54,7 @@
</itemizedlist>
</sect2>
<sect2 id="mentor.comentor">
<sect2 xml:id="mentor.comentor">
<title>Mentor/Co-Mentor</title>
<para>Reasons for a co-mentorship:</para>
@ -109,7 +108,7 @@
</itemizedlist>
</sect2>
<sect2 id="mentor.expectations">
<sect2 xml:id="mentor.expectations">
<title>Expectations</title>
<para>We expect mentors to review and test-build all proposed
@ -122,17 +121,16 @@
and implicit.</para>
<para>We expect mentors to make sure their mentees read the
<ulink url="&url.books.porters-handbook;">Porter's
Handbook</ulink>, the <ulink
url="&url.articles.pr-guidelines;">PR handling guide</ulink>, and
the <ulink url="&url.articles.committers-guide;">Committer's
Guide</ulink>. While it's not necessary to memorize all the
<link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link>, the <link xlink:href="&url.articles.pr-guidelines;">PR handling guide</link>, and
the <link xlink:href="&url.articles.committers-guide;">Committer's
Guide</link>. While it's not necessary to memorize all the
details, every committer needs to have an overview of these
things to be an effective part of the community (and avoid as
many rookie mistakes as possible).</para>
</sect2>
<sect2 id="mentees">
<sect2 xml:id="mentees">
<title>Selecting a mentee</title>
<para>There is no defined rule for what makes a candidate ready; it
@ -171,15 +169,15 @@
and hope that portmgr agrees.</para>
</sect2>
<sect2 id="mentorship.duration">
<sect2 xml:id="mentorship.duration">
<title>Mentorship duration</title>
<para>As the trust level develops and grows, the mentee may be
granted <quote>implicit</quote> commit rights. This can include
trivial changes to a <filename>Makefile</filename>,
<filename>pkg-descr</filename> etc. Similarly, it may include
<makevar>PORTVERSION</makevar> updates that do not include
<makevar>plist</makevar> changes. Other circumstances may be
<varname>PORTVERSION</varname> updates that do not include
<varname>plist</varname> changes. Other circumstances may be
formulated at the discretion of the Mentor. However, during the
period of mentorship, a port version bump that affects dependent
ports should be checked by a mentor.</para>
@ -195,7 +193,7 @@
mistakes, they still require mentor guidance.</para>
</sect2>
<sect2 id="mentor.comentor.debate">
<sect2 xml:id="mentor.comentor.debate">
<title>Mentor/Co-Mentor debate</title>
<para>When a request gets to portmgr, it usually reads as,
@ -206,14 +204,14 @@
<quote>first among equals</quote>, the co-mentor is the backup.</para>
<para>Some reprobate, whose name shall be withheld, made the
<ulink url="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html">
first recorded co-mentor commit</ulink>. Similar co-mentor commits
<link xlink:href="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html">
first recorded co-mentor commit</link>. Similar co-mentor commits
have also been spotted in the src tree. Does this make it right?
Does this make it wrong? It seems to be part of the evolution of
how things are done.</para>
</sect2>
<sect2 id="mentee.expectations">
<sect2 xml:id="mentee.expectations">
<title>Expectations</title>
<para>We expect mentees to be prepared for constructive criticism

583
en_US.ISO8859-1/articles/portbuild/article.xml
View file

File diff suppressed because it is too large Load diff

69
en_US.ISO8859-1/articles/pr-guidelines/article.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<!-- :START of Article Metadata -->
<articleinfo>
<title>Problem Report Handling Guidelines</title>
<info><title>Problem Report Handling Guidelines</title>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.opengroup;
&tm-attrib.general;
@ -27,20 +26,14 @@
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
</author>
<author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname></author>
<author>
<firstname>Hiten</firstname>
<surname>Pandya</surname>
</author>
<author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname></author>
</authorgroup>
</articleinfo>
</info>
<!-- :END of Article Metadata-->
<section id="intro">
<section xml:id="intro">
<title>Introduction</title>
<para>GNATS is a defect management (bug reporting) system used by
@ -57,7 +50,7 @@
forth.</para>
</section>
<section id="pr-lifecycle">
<section xml:id="pr-lifecycle">
<title>Problem Report Life-cycle</title>
<itemizedlist>
@ -130,7 +123,7 @@
</note>
</section>
<section id="pr-states">
<section xml:id="pr-states">
<title>Problem Report State</title>
<para>It is important to update the state of a PR when certain
@ -229,7 +222,7 @@
</note>
</section>
<section id="pr-types">
<section xml:id="pr-types">
<title>Types of Problem Reports</title>
<para>While handling problem reports, either as a developer who has
@ -260,7 +253,7 @@
PRs is used for, when a PR belongs to one of these types, and what
treatment each different type receives.</para>
<section id="pr-unassigned">
<section xml:id="pr-unassigned">
<title>Unassigned PRs</title>
<para>When PRs arrive, they are initially assigned to a generic
@ -270,7 +263,7 @@
specific &os; mailing list. Here is the current list, with
the most common ones listed first:</para>
<table id="default-assignees-common">
<table xml:id="default-assignees-common">
<title>Default Assignees &mdash; most common</title>
<tgroup cols="3">
<thead>
@ -315,7 +308,7 @@
</tgroup>
</table>
<table id="default-assignees-other">
<table xml:id="default-assignees-other">
<title>Default Assignees &mdash; other</title>
<tgroup cols="3">
<thead>
@ -382,15 +375,14 @@
<note>
<para>Since the list of individuals who have volunteered to
be the default assignee for certain types of PRs changes
so often, it is much more suitable for <ulink
url="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</ulink>.
so often, it is much more suitable for <link xlink:href="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</link>.
</para>
</note>
<para>Here is a sample list of such entities; it is probably
not complete.</para>
<table id="common-assignees-base">
<table xml:id="common-assignees-base">
<title>Common Assignees &mdash; base system</title>
<tgroup cols="4">
<thead>
@ -568,7 +560,7 @@
</tgroup>
</table>
<table id="common-assignees-ports">
<table xml:id="common-assignees-ports">
<title>Common Assignees &mdash; Ports Collection</title>
<tgroup cols="4">
<thead>
@ -732,7 +724,7 @@
because everyone assumes that the assignee is already working
on it.</para>
<table id="common-assignees-other">
<table xml:id="common-assignees-other">
<title>Common Assignees &mdash; Other</title>
<tgroup cols="4">
<thead>
@ -764,7 +756,7 @@
</section>
<section id="pr-assigned">
<section xml:id="pr-assigned">
<title>Assigned PRs</title>
<para>If a PR has the <literal>responsible</literal> field set
@ -780,7 +772,7 @@
you please.</para>
</section>
<section id="pr-dups">
<section xml:id="pr-dups">
<title>Duplicate PRs</title>
<para>If you find more than one PR that describe the same issue,
@ -792,7 +784,7 @@
the other PRs (which are now completely superseded).</para>
</section>
<section id="pr-stale">
<section xml:id="pr-stale">
<title>Stale PRs</title>
<para>A PR is considered stale if it has not been modified in more
@ -844,7 +836,7 @@
</itemizedlist>
</section>
<section id="pr-misfiled">
<section xml:id="pr-misfiled">
<title>Misfiled PRs</title>
<para>GNATS is picky about the format of a submitted bug report.
@ -910,7 +902,7 @@
</listitem>
</itemizedlist>
<section id="pr-misfiled-followups">
<section xml:id="pr-misfiled-followups">
<title>Followups misfiled as new PRs</title>
<para>The first category of misfiled PRs, the one with the wrong
@ -975,7 +967,7 @@ This was misfiled because the subject did not have the format:
avoid the next time a followup to an existing PR is sent.</para>
</section>
<section id="pr-misfiled-format">
<section xml:id="pr-misfiled-format">
<title>PRs misfiled because of missing fields</title>
<para>The second type of misfiled PRs is usually the result of a
@ -998,7 +990,7 @@ This was misfiled because the subject did not have the format:
PR, but it is relatively easy to do most of the time.</para>
</section>
<section id="pr-misfiled-notpr">
<section xml:id="pr-misfiled-notpr">
<title>Misfiled PRs that are not really problem reports</title>
<para>Sometimes a user wants to submit a report for a problem
@ -1065,7 +1057,7 @@ This was misfiled because the subject did not have the format:
</section>
</section>
<section id="references">
<section xml:id="references">
<title>Further Reading</title>
<para>This is a list of resources relevant to the proper writing
@ -1073,9 +1065,8 @@ This was misfiled because the subject did not have the format:
<itemizedlist>
<listitem>
<para><ulink
url="&url.articles.problem-reports;/article.html">How to
Write FreeBSD Problem Reports</ulink>&mdash;guidelines
<para><link xlink:href="&url.articles.problem-reports;/article.html">How to
Write FreeBSD Problem Reports</link>&mdash;guidelines
for PR originators.</para>
</listitem>
</itemizedlist>

154
en_US.ISO8859-1/articles/problem-reports/article.xml
View file

@ -1,12 +1,11 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Writing &os; Problem Reports</title>
<article lang='en'>
<articleinfo>
<title>Writing &os; Problem Reports</title>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.ibm;
&tm-attrib.intel;
@ -25,22 +24,15 @@
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
<contrib>Contributed by </contrib>
</author>
<author><personname><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></personname><contrib>Contributed by </contrib></author>
<author>
<firstname>Mark</firstname>
<surname>Linimon</surname>
</author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
</articleinfo>
</info>
<indexterm><primary>problem reports</primary></indexterm>
<section id="pr-intro">
<section xml:id="pr-intro">
<title>Introduction</title>
<para>One of the most frustrating experiences one can have as a
@ -69,7 +61,7 @@
step-by-step tutorial.</para>
</section>
<section id="pr-when">
<section xml:id="pr-when">
<title>When to submit a problem report</title>
<para>There are many types of problems, and not all of them should
@ -107,7 +99,7 @@
system components such as BIND or various GNU
utilities).</para>
<para>For unmaintained ports (<makevar>MAINTAINER</makevar> contains
<para>For unmaintained ports (<varname>MAINTAINER</varname> contains
<literal>ports@FreeBSD.org</literal>), such update notifications
might get picked up by an interested
committer, or you might be asked to provide a patch to update
@ -120,12 +112,10 @@
a new version, they have probably worked with the developers on it,
they are probably testing to see there is no regression, etc.</para>
<para>In either case, following the process described in <ulink
url="&url.books.porters-handbook;/port-upgrading.html">Porter's
Handbook</ulink> will yield the best results. (You might
also wish to read <ulink
url="&url.articles.contributing-ports;/article.html">
Contributing to the FreeBSD Ports Collection</ulink>.)
<para>In either case, following the process described in <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
Handbook</link> will yield the best results. (You might
also wish to read <link xlink:href="&url.articles.contributing-ports;/article.html">
Contributing to the FreeBSD Ports Collection</link>.)
</para>
</listitem>
</itemizedlist>
@ -188,16 +178,16 @@
<para>If the problem is in the base system, you should first read
the FAQ section on
<ulink url="&url.books.faq;/introduction.html#LATEST-VERSION">
&os; versions</ulink>, if you are not already familiar with
<link xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION">
&os; versions</link>, if you are not already familiar with
the topic. It is not possible for &os; to fix problems in
anything other than certain recent branches of the base system,
so filing a bug report about an older version will probably
only result in a developer advising you to upgrade to a
supported version to see if the problem still recurs. The
Security Officer team maintains the
<ulink url="&url.base;/security/">list of supported
versions</ulink>.</para>
<link xlink:href="&url.base;/security/">list of supported
versions</link>.</para>
<para>If the problem is in a port, note that you must first
upgrade to the latest version of the Ports Collection and see
@ -207,7 +197,7 @@
with older version of applications simply cannot be fixed.</para>
</section>
<section id="pr-prep">
<section xml:id="pr-prep">
<title>Preparations</title>
<para>A good rule to follow is to always do a background search
@ -221,26 +211,24 @@
<itemizedlist>
<listitem>
<para>The &os;
<ulink url="&url.books.faq;/index.html">Frequently Asked
Questions</ulink> (FAQ) list.
<link xlink:href="&url.books.faq;/index.html">Frequently Asked
Questions</link> (FAQ) list.
The FAQ attempts to provide answers for a wide range of questions,
such as those concerning
<ulink url="&url.books.faq;/hardware.html">hardware
compatibility</ulink>,
<ulink url="&url.books.faq;/applications.html">user
applications</ulink>,
and <ulink url="&url.books.faq;/kernelconfig.html">kernel
configuration</ulink>.</para>
<link xlink:href="&url.books.faq;/hardware.html">hardware
compatibility</link>,
<link xlink:href="&url.books.faq;/applications.html">user
applications</link>,
and <link xlink:href="&url.books.faq;/kernelconfig.html">kernel
configuration</link>.</para>
</listitem>
<listitem>
<para>The
<ulink
url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing
lists</ulink>&mdash;if you are not subscribed, use
<ulink
url="http://www.FreeBSD.org/search/search.html#mailinglists">the
searchable archives</ulink> on the &os; web site. If your
<link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing
lists</link>&mdash;if you are not subscribed, use
<link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">the
searchable archives</link> on the &os; web site. If your
problem has not been discussed on the lists, you might try
posting a message about it and waiting a few days to see if
someone can spot something you have overlooked.</para>
@ -256,8 +244,8 @@
<listitem>
<para>Next, the searchable
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
&os; PR database</ulink> (GNATS). Unless your problem
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
&os; PR database</link> (GNATS). Unless your problem
is recent or obscure, there is a fair chance it has already
been reported.</para>
</listitem>
@ -270,7 +258,7 @@
carefully study the contents of the
<filename>/usr/src/UPDATING</filename> file on your system
or its latest version at
<ulink url="http://svnweb.freebsd.org/base/head/UPDATING?view=log"></ulink>.
<uri xlink:href="http://svnweb.freebsd.org/base/head/UPDATING?view=log">http://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>.
(This is vital information
if you are upgrading from one version to
another&mdash;especially if you are upgrading to the
@ -281,15 +269,15 @@
<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://svnweb.freebsd.org/ports/head/UPDATING?view=log"></ulink>
<uri xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
and
<ulink url="http://svnweb.freebsd.org/ports/head/CHANGES?view=log"></ulink>
<uri xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
are also available via svnweb.</para>
</listitem>
</itemizedlist>
</section>
<section id="pr-writing">
<section xml:id="pr-writing">
<title>Writing the problem report</title>
<para>Now that you have decided that your issue merits a problem
@ -450,7 +438,7 @@
<listitem>
<para>any environment variables that override the
defaults in <filename>bsd.port.mk</filename>, such
as <makevar>PORTSDIR</makevar></para>
as <varname>PORTSDIR</varname></para>
</listitem>
<listitem>
<para>the fact that you have read
@ -481,7 +469,7 @@
a similar PR.</emphasis> Although this has already been
mentioned above, it bears repeating here. It only take a
minute or two to use the web-based search engine at
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>.
<uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>.
(Of course, everyone is guilty of forgetting to do this
now and then.)</para>
</listitem>
@ -502,7 +490,7 @@
offer patches, but also justification for why the patches
are <quote>The Right Thing To Do</quote>. As noted above,
a careful search of the mailing lists using the archives
at <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink>
at <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
is always good preparation.</para>
</listitem>
@ -533,7 +521,7 @@
problem report will not reach the GNATS database. For details
on the setup of mail on &os;, see the <quote>Electronic
Mail</quote> chapter of the &os; Handbook at
<ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para>
<uri xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</para>
<para>Make sure that your mailer will not mangle the message on
its way to GNATS. In particular, if your mailer automatically
@ -544,8 +532,8 @@
so that the web display of the PR will be readable.</para>
<para>Similar considerations apply if you are using the
<ulink url="&url.base;/send-pr.html"> web-based
PR submission form</ulink> instead of &man.send-pr.1;. Note that
<link xlink:href="&url.base;/send-pr.html"> web-based
PR submission form</link> instead of &man.send-pr.1;. Note that
cut-and-paste operations can have their own side-effects on
text formatting. In certain cases it may be necessary to use
&man.uuencode.1; to ensure that patches arrive unmodified.</para>
@ -553,7 +541,7 @@
<para>Finally, if your submission will be lengthy, you should
to prepare your work offline so that nothing will be lost in
case there is a problem submitting it. This can especially be a
problem with the <ulink url="&url.base;/send-pr.html">web form</ulink>.</para>
problem with the <link xlink:href="&url.base;/send-pr.html">web form</link>.</para>
</section>
<section>
@ -680,8 +668,8 @@
<para>Security problems should <emphasis>not</emphasis>
be filed in GNATS, because all GNATS information is public
knowledge. Please send such problems according to our
<ulink url="http://security.freebsd.org/#how">security
report guidelines</ulink>.</para>
<link xlink:href="http://security.freebsd.org/#how">security
report guidelines</link>.</para>
</note>
</listitem>
@ -703,7 +691,7 @@
</itemizedlist>
<para>The next section describes fields that are common to both
the email interface and the <ulink url="&url.base;/send-pr.html">web interface</ulink>:</para>
the email interface and the <link xlink:href="&url.base;/send-pr.html">web interface</link>:</para>
<itemizedlist>
@ -781,18 +769,18 @@
&man.sh.1; or &man.mount.8;, you will first need to determine
whether these programs are in the base system or were added
via the Ports Collection. If you are unsure, you can do
<command>whereis <replaceable>programname</replaceable></command>.
<command>whereis programname</command>.
&os;'s convention for the Ports Collection is to install
everything underneath
<filename class="directory">/usr/local</filename>,
<filename>/usr/local</filename>,
although this can be overridden by a system administrator.
For these, you will use the <literal>ports</literal>
category (yes, even if the port's category is
<literal>www</literal>; see below). If the location is
<filename class="directory">/bin</filename>,
<filename class="directory">/usr/bin</filename>,
<filename class="directory">/sbin</filename>, or
<filename class="directory">/usr/sbin</filename>,
<filename>/bin</filename>,
<filename>/usr/bin</filename>,
<filename>/sbin</filename>, or
<filename>/usr/sbin</filename>,
it is part of the base system, and you should use the
<literal>bin</literal> category. (A few programs, such as
&man.gcc.1;, actually use the <literal>gnu</literal> category,
@ -816,13 +804,13 @@
<listitem>
<para>If you are having a problem with the
<ulink url="http://www.FreeBSD.org">FreeBSD web pages</ulink>,
<link xlink:href="http://www.FreeBSD.org">FreeBSD web pages</link>,
the proper choice is <literal>www</literal>.</para>
<note>
<para>if you are having a problem with something from a
port named
<literal>www/<replaceable>someportname</replaceable></literal>,
<literal>www/someportname</literal>,
this nevertheless goes in the <literal>ports</literal>
category.</para>
</note>
@ -913,7 +901,7 @@
</itemizedlist>
<para>Here is the current list of categories (taken from
<ulink url="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories"></ulink>):</para>
<uri xlink:href="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>
<itemizedlist>
<listitem>
@ -1127,7 +1115,7 @@
<para>This will read the specified file, validate the contents,
strip comments and send it off.</para>
<para>If you are using the <ulink url="&url.base;/send-pr.html">web form</ulink>:</para>
<para>If you are using the <link xlink:href="&url.base;/send-pr.html">web form</link>:</para>
<para>Before you hit <literal>submit</literal>, you will need to
fill in a field containing text that is represented in image
@ -1150,7 +1138,7 @@
</section>
<section id="pr-followup">
<section xml:id="pr-followup">
<title>Follow-up</title>
<para>Once your problem report has been filed, you will receive a
@ -1172,8 +1160,8 @@
<listitem>
<para>The easiest way is to use the followup link on
the individual PR's web page, which you can reach from the
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
PR search page</ulink>. Clicking on this link will bring up an
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
PR search page</link>. Clicking on this link will bring up an
an email window with the correct To: and Subject: lines filled in
(if your browser is configured to do this).</para>
</listitem>
@ -1210,7 +1198,7 @@
possible, explaining how or when the problem was fixed.</para>
</section>
<section id="pr-problems">
<section xml:id="pr-problems">
<title>If you are having problems</title>
<para>Most PRs go through the system and are accepted quickly;
@ -1241,15 +1229,15 @@
may have happened is that the database index has gotten out of
synchronization with the database itself. The way that you
can test whether this has happened is to pull up the
<ulink url="http://www.FreeBSD.org/cgi/query-pr.cgi">
view a single PR</ulink> page and see whether the PR shows up.
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr.cgi">
view a single PR</link> page and see whether the PR shows up.
If it does, please notify the GNATS administrators at
<email>bugmeister@FreeBSD.org</email>. Note that there is a
<literal>cron</literal> job that periodically rebuilds the database,
so unless you are in a hurry, no action needs to be taken.</para>
</section>
<section id="pr-further">
<section xml:id="pr-further">
<title>Further Reading</title>
<para>This is a list of resources relevant to the proper writing
@ -1257,16 +1245,14 @@
<itemizedlist>
<listitem>
<para><ulink
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
How to Report Bugs Effectively</ulink>&mdash;an excellent
<para><link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
How to Report Bugs Effectively</link>&mdash;an excellent
essay by Simon G. Tatham on composing useful (non-&os;-specific)
problem reports.</para>
</listitem>
<listitem>
<para><ulink
url="&url.articles.pr-guidelines;/article.html">Problem
Report Handling Guidelines</ulink>&mdash;valuable insight
<para><link xlink:href="&url.articles.pr-guidelines;/article.html">Problem
Report Handling Guidelines</link>&mdash;valuable insight
into how problem reports are handled by the &os;
developers.</para>
</listitem>

146
en_US.ISO8859-1/articles/rc-scripting/article.xml
View file

@ -1,20 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Practical rc.d scripting in BSD</title>
<article lang='en'>
<articleinfo>
<title>Practical rc.d scripting in BSD</title>
<author>
<firstname>Yar</firstname>
<surname>Tikhiy</surname>
<affiliation>
<author><personname><firstname>Yar</firstname><surname>Tikhiy</surname></personname><affiliation>
<address><email>yar@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2005</year>
@ -24,7 +17,7 @@
<holder>The FreeBSD Project</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.netbsd;
&tm-attrib.general;
@ -45,9 +38,9 @@
provide reference points for further study of the design
and efficient application of <filename>rc.d</filename>.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="rcng-intro">
<sect1 xml:id="rcng-intro">
<title>Introduction</title>
<para>The historical BSD had a monolithic startup script,
@ -164,7 +157,7 @@
authors.</para>
</sect1>
<sect1 id="rcng-task">
<sect1 xml:id="rcng-task">
<title>Outlining the task</title>
<para>A little consideration before starting
@ -193,28 +186,28 @@
important to know the answers to these questions.</para>
</sect1>
<sect1 id="rcng-dummy">
<sect1 xml:id="rcng-dummy">
<title>A dummy script</title>
<para>The following script just emits a message each time the
system boots up:</para>
<informalexample>
<programlisting>#!/bin/sh<co id="rcng-dummy-shebang"/>
<programlisting>#!/bin/sh<co xml:id="rcng-dummy-shebang"/>
. /etc/rc.subr<co id="rcng-dummy-include"/>
. /etc/rc.subr<co xml:id="rcng-dummy-include"/>
name="dummy"<co id="rcng-dummy-name"/>
start_cmd="${name}_start"<co id="rcng-dummy-startcmd"/>
stop_cmd=":"<co id="rcng-dummy-stopcmd"/>
name="dummy"<co xml:id="rcng-dummy-name"/>
start_cmd="${name}_start"<co xml:id="rcng-dummy-startcmd"/>
stop_cmd=":"<co xml:id="rcng-dummy-stopcmd"/>
dummy_start()<co id="rcng-dummy-startfn"/>
dummy_start()<co xml:id="rcng-dummy-startfn"/>
{
echo "Nothing started."
}
load_rc_config $name<co id="rcng-dummy-loadconfig"/>
run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting>
load_rc_config $name<co xml:id="rcng-dummy-loadconfig"/>
run_rc_command "$1"<co xml:id="rcng-dummy-runcommand"/></programlisting>
</informalexample>
<para>Things to note are:</para>
@ -283,7 +276,7 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting>
</callout>
<callout arearefs="rcng-dummy-name">
<para><anchor id="name-var"/>The mandatory variable
<para><anchor xml:id="name-var"/>The mandatory variable
<envar>name</envar> specifies the name of our script. It
is required by &man.rc.subr.8;. That is, each
<filename>rc.d</filename> script <emphasis>must</emphasis>
@ -369,7 +362,7 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting>
</calloutlist>
</sect1>
<sect1 id="rcng-confdummy">
<sect1 xml:id="rcng-confdummy">
<title>A configurable dummy script</title>
<para>Now let us add some controls to our dummy script. As you
@ -391,18 +384,18 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting>
. /etc/rc.subr
name=dummy
rcvar=dummy_enable<co id="rcng-confdummy-rcvar"/>
rcvar=dummy_enable<co xml:id="rcng-confdummy-rcvar"/>
start_cmd="${name}_start"
stop_cmd=":"
load_rc_config $name<co id="rcng-confdummy-loadconfig"/>
: ${dummy_enable:=no} <co id="rcng-confdummy-enable"/>
: ${dummy_msg="Nothing started."}<co id="rcng-confdummy-opt"/>
load_rc_config $name<co xml:id="rcng-confdummy-loadconfig"/>
: ${dummy_enable:=no} <co xml:id="rcng-confdummy-enable"/>
: ${dummy_msg="Nothing started."}<co xml:id="rcng-confdummy-opt"/>
dummy_start()
{
echo "$dummy_msg"<co id="rcng-confdummy-msg"/>
echo "$dummy_msg"<co xml:id="rcng-confdummy-msg"/>
}
run_rc_command "$1"</programlisting>
@ -509,7 +502,7 @@ run_rc_command "$1"</programlisting>
</calloutlist>
</sect1>
<sect1 id="rcng-daemon">
<sect1 xml:id="rcng-daemon">
<title>Startup and shutdown of a simple daemon</title>
<para>We said earlier that &man.rc.subr.8; could provide default
@ -527,7 +520,7 @@ run_rc_command "$1"</programlisting>
name=mumbled
rcvar=mumbled_enable
command="/usr/sbin/${name}"<co id="rcng-daemon-basic-cmd"/>
command="/usr/sbin/${name}"<co xml:id="rcng-daemon-basic-cmd"/>
load_rc_config $name
run_rc_command "$1"</programlisting>
@ -603,7 +596,7 @@ run_rc_command "$1"</programlisting>
</calloutlist>
</sect1>
<sect1 id="rcng-daemon-adv">
<sect1 xml:id="rcng-daemon-adv">
<title>Startup and shutdown of an advanced daemon</title>
<para>Let us add some meat onto the bones of the previous
@ -621,26 +614,26 @@ name=mumbled
rcvar=mumbled_enable
command="/usr/sbin/${name}"
command_args="mock arguments &gt; /dev/null 2&gt;&amp;1"<co id="rcng-daemon-adv-args"/>
command_args="mock arguments &gt; /dev/null 2&gt;&amp;1"<co xml:id="rcng-daemon-adv-args"/>
pidfile="/var/run/${name}.pid"<co id="rcng-daemon-adv-pid"/>
pidfile="/var/run/${name}.pid"<co xml:id="rcng-daemon-adv-pid"/>
required_files="/etc/${name}.conf /usr/share/misc/${name}.rules"<co id="rcng-daemon-adv-reqfiles"/>
required_files="/etc/${name}.conf /usr/share/misc/${name}.rules"<co xml:id="rcng-daemon-adv-reqfiles"/>
sig_reload="USR1"<co id="rcng-daemon-adv-sig"/>
sig_reload="USR1"<co xml:id="rcng-daemon-adv-sig"/>
start_precmd="${name}_prestart"<co id="rcng-daemon-adv-precmd"/>
stop_postcmd="echo Bye-bye"<co id="rcng-daemon-adv-postcmd"/>
start_precmd="${name}_prestart"<co xml:id="rcng-daemon-adv-precmd"/>
stop_postcmd="echo Bye-bye"<co xml:id="rcng-daemon-adv-postcmd"/>
extra_commands="reload plugh xyzzy"<co id="rcng-daemon-adv-extra"/>
extra_commands="reload plugh xyzzy"<co xml:id="rcng-daemon-adv-extra"/>
plugh_cmd="mumbled_plugh"<co id="rcng-daemon-adv-methods"/>
plugh_cmd="mumbled_plugh"<co xml:id="rcng-daemon-adv-methods"/>
xyzzy_cmd="echo 'Nothing happens.'"
mumbled_prestart()
{
if checkyesno mumbled_smart; then<co id="rcng-daemon-adv-yn"/>
rc_flags="-o smart ${rc_flags}"<co id="rcng-daemon-adv-rcflags"/>
if checkyesno mumbled_smart; then<co xml:id="rcng-daemon-adv-yn"/>
rc_flags="-o smart ${rc_flags}"<co xml:id="rcng-daemon-adv-rcflags"/>
fi
case "$mumbled_mode" in
foo)
@ -650,15 +643,15 @@ mumbled_prestart()
rc_flags="-baz ${rc_flags}"
;;
*)
warn "Invalid value for mumbled_mode"<co id="rcng-daemon-adv-warn"/>
return 1<co id="rcng-daemon-adv-preret"/>
warn "Invalid value for mumbled_mode"<co xml:id="rcng-daemon-adv-warn"/>
return 1<co xml:id="rcng-daemon-adv-preret"/>
;;
esac
run_rc_command xyzzy<co id="rcng-daemon-adv-run"/>
run_rc_command xyzzy<co xml:id="rcng-daemon-adv-run"/>
return 0
}
mumbled_plugh()<co id="rcng-daemon-adv-plugh"/>
mumbled_plugh()<co xml:id="rcng-daemon-adv-plugh"/>
{
echo 'A hollow voice says "plugh".'
}
@ -688,8 +681,7 @@ run_rc_command "$1"</programlisting>
A better way of passing additional options
to <envar>$command</envar> is to add them
to the beginning of <envar>${name}_flags</envar>.
Another way is to modify <envar>rc_flags</envar> <link
linkend="rc-flags">as shown later</link>.</para>
Another way is to modify <envar>rc_flags</envar> <link linkend="rc-flags">as shown later</link>.</para>
</note>
</callout>
@ -882,7 +874,7 @@ fi</programlisting>
</callout>
<callout arearefs="rcng-daemon-adv-rcflags">
<para><anchor id="rc-flags"/>We can affect the flags to be
<para><anchor xml:id="rc-flags"/>We can affect the flags to be
passed to <envar>$command</envar> by modifying
<envar>rc_flags</envar> in <envar>$start_precmd</envar>.</para>
</callout>
@ -918,7 +910,7 @@ fi</programlisting>
</calloutlist>
</sect1>
<sect1 id="rcng-hookup">
<sect1 xml:id="rcng-hookup">
<title>Connecting a script to the rc.d framework</title>
<para>After a script has been written, it needs to be integrated
@ -931,9 +923,9 @@ fi</programlisting>
the proper ownership and mode. System scripts should be
installed from <filename>src/etc/rc.d</filename> through the
<filename>Makefile</filename> found there. Port scripts can
be installed using <makevar>USE_RC_SUBR</makevar> as described
<ulink url="&url.books.porters-handbook;/rc-scripts.html">in
the Porter's Handbook</ulink>.</para>
be installed using <varname>USE_RC_SUBR</varname> as described
<link xlink:href="&url.books.porters-handbook;/rc-scripts.html">in
the Porter's Handbook</link>.</para>
<para>However, we should consider beforehand the place of
our script in the system startup sequence. The service handled
@ -995,10 +987,10 @@ fi</programlisting>
<informalexample>
<programlisting>#!/bin/sh
# PROVIDE: mumbled oldmumble <co id="rcng-hookup-provide"/>
# REQUIRE: DAEMON cleanvar frotz<co id="rcng-hookup-require"/>
# BEFORE: LOGIN<co id="rcng-hookup-before"/>
# KEYWORD: nojail shutdown<co id="rcng-hookup-keyword"/>
# PROVIDE: mumbled oldmumble <co xml:id="rcng-hookup-provide"/>
# REQUIRE: DAEMON cleanvar frotz<co xml:id="rcng-hookup-require"/>
# BEFORE: LOGIN<co xml:id="rcng-hookup-before"/>
# KEYWORD: nojail shutdown<co xml:id="rcng-hookup-keyword"/>
. /etc/rc.subr
@ -1011,8 +1003,8 @@ start_precmd="${name}_prestart"
mumbled_prestart()
{
if ! checkyesno frotz_enable &amp;&amp; \
! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&amp;1; then
force_depend frotz || return 1<co id="rcng-hookup-force"/>
! /etc/rc.d/frotz forcestatus 1&gt;/dev/null 2&gt;&amp;1; then
force_depend frotz || return 1<co xml:id="rcng-hookup-force"/>
fi
return 0
}
@ -1067,7 +1059,7 @@ run_rc_command "$1"</programlisting>
<quote>placeholder</quote> scripts used to ensure that
certain groups of operations are performed before others.
These are denoted by
<filename><replaceable>UPPERCASE</replaceable></filename>
<filename>UPPERCASE</filename>
names. Their list and purposes can be found in
&man.rc.8;.</para>
@ -1080,13 +1072,12 @@ run_rc_command "$1"</programlisting>
will not do that either. Consequently, the application
started by our script should be able to cope with any
required services being unavailable. In certain cases,
we can help it as discussed <link
linkend="forcedep">below.</link></para>
we can help it as discussed <link linkend="forcedep">below.</link></para>
</note>
</callout>
<callout arearefs="rcng-hookup-keyword">
<para><anchor id="keywords"/>As we remember from the above text,
<para><anchor xml:id="keywords"/>As we remember from the above text,
&man.rcorder.8; keywords can be used to select or leave
out some scripts. Namely any &man.rcorder.8; consumer
can specify through <option>-k</option> and <option>-s</option>
@ -1173,7 +1164,7 @@ run_rc_command "$1"</programlisting>
</callout>
<callout arearefs="rcng-hookup-force">
<para><anchor id="forcedep"/>To begin with,
<para><anchor xml:id="forcedep"/>To begin with,
<function>force_depend</function> should be used with
much care. It is generally better to revise the hierarchy
of configuration variables for your <filename>rc.d</filename>
@ -1200,7 +1191,7 @@ run_rc_command "$1"</programlisting>
</calloutlist>
</sect1>
<sect1 id="rcng-args">
<sect1 xml:id="rcng-args">
<title>Giving more flexibility to an rc.d script</title>
<para>When invoked during startup or shutdown, an
@ -1261,7 +1252,7 @@ extra_commands="kiss"
dummy_start()
{
if [ $# -gt 0 ]; then<co id="rcng-args-start"/>
if [ $# -gt 0 ]; then<co xml:id="rcng-args-start"/>
echo "Greeting message: $*"
else
echo "Nothing started."
@ -1271,7 +1262,7 @@ dummy_start()
dummy_kiss()
{
echo -n "A ghost gives you a kiss"
if [ $# -gt 0 ]; then<co id="rcng-args-kiss"/>
if [ $# -gt 0 ]; then<co xml:id="rcng-args-kiss"/>
echo -n " and whispers: $*"
fi
case "$*" in
@ -1285,7 +1276,7 @@ dummy_kiss()
}
load_rc_config $name
run_rc_command "$@"<co id="rcng-args-all"/></programlisting>
run_rc_command "$@"<co xml:id="rcng-args-all"/></programlisting>
</informalexample>
<para>What essential changes can we notice in the script?</para>
@ -1347,18 +1338,17 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen>
</calloutlist>
</sect1>
<sect1 id="rcng-furthur">
<sect1 xml:id="rcng-furthur">
<title>Further reading</title>
<para><anchor id="lukem"/><ulink
url="http://www.mewburn.net/luke/papers/rc.d.pdf">The original
article by Luke Mewburn</ulink> offers a general overview of
<para><anchor xml:id="lukem"/><link xlink:href="http://www.mewburn.net/luke/papers/rc.d.pdf">The original
article by Luke Mewburn</link> offers a general overview of
<filename>rc.d</filename> and detailed rationale for its
design decisions. It provides insight on the whole
<filename>rc.d</filename> framework and its place in a modern
BSD operating system.</para>
<para><anchor id="manpages"/>The manual pages &man.rc.8;,
<para><anchor xml:id="manpages"/>The manual pages &man.rc.8;,
&man.rc.subr.8;, and &man.rcorder.8; document the
<filename>rc.d</filename> components in great detail. You
cannot fully use the <filename>rc.d</filename> power without

52
en_US.ISO8859-1/articles/relaydelay/article.xml
View file

@ -1,22 +1,16 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!--
$FreeBSD$
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Using Greylist with &os;</title>
<article lang='en'>
<articleinfo>
<title>Using Greylist with &os;</title>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<affiliation>
<author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><affiliation>
<address><email>trhodes@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
<copyright>
<year>2004</year>
@ -53,14 +47,14 @@
comes into the server. From my personal experience, this
really does cut out 90% of the spam.</para>
</abstract>
</articleinfo>
</info>
<sect1>
<title>Basic Configuration</title>
<para>We need to install the threaded <command>perl</command>.
Install <filename role="package">lang/perl5.8</filename>
with the <makevar>USE_THREADS=yes</makevar> variable
Install <package>lang/perl5.8</package>
with the <varname>USE_THREADS=yes</varname> variable
set. The current version of <command>perl</command>
may need to be removed first; errors will be reported
by the install process if this is necessary.</para>
@ -68,7 +62,7 @@
<note>
<para>This will require all ports which require
<command>perl</command> to be rebuilt and reinstalled;
<filename role="package">ports-mgmt/portupgrade</filename>
<package>ports-mgmt/portupgrade</package>
is perfect for this. At least it will point out which
ports have been removed and which will need to be
reinstalled.</para>
@ -77,23 +71,23 @@
<para>Now for the database server;
<application>MySQL</application> is perfect for this
sort of work. Install the
<filename role="package">databases/mysql40-server</filename>
<package>databases/mysql40-server</package>
along with
<filename role="package">databases/p5-DBD-mysql40</filename>.
<package>databases/p5-DBD-mysql40</package>.
The previous port should imply the installation of
<filename role="package">databases/p5-DBI-137</filename>
<package>databases/p5-DBI-137</package>
so that knocks off another step.</para>
<para>Install the <command>perl</command> based portable
server plugin, <filename role="package">net/p5-Net-Daemon</filename>
server plugin, <package>net/p5-Net-Daemon</package>
port. Most of these port installations should have
been straight forward. The next step will be more
involved.</para>
<para>Now install the
<filename role="package">mail/p5-Sendmail-Milter</filename>
<package>mail/p5-Sendmail-Milter</package>
port. As of this writing the <filename>Makefile</filename>
contains a line beginning with <makevar>BROKEN</makevar>,
contains a line beginning with <varname>BROKEN</varname>,
just remove it or comment it out. It is only marked
this way because &os; neither has nor installs
a threaded <command>perl</command> package by default. Once that
@ -143,7 +137,7 @@
is beyond the scope of this document.</para>
<para>Change the working directory to the
<filename class="directory">relaydelay-0.04</filename>
<filename>relaydelay-0.04</filename>
directory:</para>
<screen>&prompt.root; <userinput>cd relaydelay-0.04</userinput></screen>
@ -166,7 +160,7 @@
<para>If everything worked correctly a new file,
<filename>relaydelay.log</filename>, should exist in
<filename class="directory">/var/log</filename>. It should
<filename>/var/log</filename>. It should
contain something similar to the following text:</para>
<programlisting>Loaded Config File: /etc/mail/relaydelay.conf
@ -188,13 +182,13 @@ Starting Sendmail::Milter 0.18 engine.</programlisting>
<para>Rebuild and reinstall the files in the
<filename>/etc/mail</filename> directory and restart
<command>sendmail</command>. A quick <command>make</command>
<maketarget>restart</maketarget> should do the trick.</para>
<buildtarget>restart</buildtarget> should do the trick.</para>
<para>Obtain the <command>perl</command> script located at
<ulink url="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html">
http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</ulink>
<link xlink:href="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html">
http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</link>
and save it in the
<filename class="directory">relaydelay-0.04</filename>
<filename>relaydelay-0.04</filename>
directory. In the following examples this script is
referred to as <filename>addlist.pl</filename>.</para>

29
en_US.ISO8859-1/articles/releng-packages/article.xml
View file

@ -1,22 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<title>FreeBSD Release Engineering for Third Party Software
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>FreeBSD Release Engineering for Third Party Software
Packages</title>
<articleinfo>
<authorgroup>
<author>
<firstname>Steve</firstname>
<surname>Price</surname>
<affiliation>
<author><personname><firstname>Steve</firstname><surname>Price</surname></personname><affiliation>
<address><email>steve@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.xfree86;
@ -39,7 +34,7 @@
consistent.</para>
</abstract>
</articleinfo>
</info>
<!-- Introduction
@ -51,11 +46,11 @@
</sect1>
-->
<sect1 id="portbuild">
<sect1 xml:id="portbuild">
<title>Building packages from the Ports Collection</title>
<para>The <ulink url="http://www.FreeBSD.org/ports">FreeBSD Ports
collection</ulink> is a collection of over &os.numports;
<para>The <link xlink:href="http://www.FreeBSD.org/ports">FreeBSD Ports
collection</link> is a collection of over &os.numports;
third-party software packages available for FreeBSD. The &a.portmgr;
is responsible for maintaining a consistent ports tree that can be used
to create the binary packages that accompany a given FreeBSD

145
en_US.ISO8859-1/articles/releng/article.xml
View file

@ -1,41 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd" [
<!ENTITY art.re.pkgs '<ulink url="&url.articles.releng-packages;/article.html">The Release Engineering of Third Party Packages</ulink>'>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd" [
<!ENTITY art.re.pkgs '<link xmlns="http://docbook.org/ns/docbook" xlink:href="{{{url.articles.releng-packages}}}/article.html">The Release Engineering of Third Party Packages</link>'>
]>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>&os; Release Engineering</title>
<article lang='en'>
<title>&os; Release Engineering</title>
<articleinfo>
<!-- This paper was presented at BSDCon Europe in Brighton, UK on
November 11, 2001. -->
<!-- The content in this paper was updated in March 2013 to
reflect the current FreeBSD Release process. -->
<confgroup>
<confdates>November 2001</confdates>
<conftitle>BSDCon Europe</conftitle>
</confgroup>
<authorgroup>
<author>
<firstname>Murray</firstname>
<surname>Stokely</surname>
<authorblurb>
<author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><personblurb>
<para>I've been involved in the development of &os; based products
since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems.
&os;&nbsp;4.4 was the first official release of &os; that I played
a significant part in.</para>
</authorblurb>
<affiliation>
</personblurb><affiliation>
<address><email>murray@FreeBSD.org</email>
<otheraddr><ulink url="http://www.FreeBSD.org/~murray/"></ulink></otheraddr>
<otheraddr xlink:href="http://www.FreeBSD.org/~murray/">http://www.FreeBSD.org/~murray/</otheraddr>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cvsup;
&tm-attrib.intel;
@ -64,10 +56,10 @@
productization.</para>
</abstract>
</articleinfo>
</info>
<!-- Introduction -->
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>The development of &os; is a very open process. &os; is
@ -76,7 +68,7 @@
Subversion
<footnote>
<simpara>
Subversion, <ulink url="http://subversion.apache.org"></ulink>
Subversion, <uri xlink:href="http://subversion.apache.org">http://subversion.apache.org</uri>
</simpara>
</footnote>
access to the general public so that
@ -88,22 +80,22 @@
access to the main repository was opened up to everyone on the Internet.
Therefore only a <quote>select</quote> group of nearly 300 people are
given write access to the Subversion repository. These
<ulink url="&url.articles.contributors;/article.html#staff-committers">committers</ulink>
<link xlink:href="&url.articles.contributors;/article.html#staff-committers">committers</link>
<footnote>
<simpara>
<ulink url="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</ulink>
<link xlink:href="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</link>
</simpara>
</footnote>
are usually the people who do the bulk of &os; development. An elected
<ulink url="&url.base;/administration.html#t-core">Core Team</ulink>
<link xlink:href="&url.base;/administration.html#t-core">Core Team</link>
<footnote>
<simpara>
<ulink url="&url.base;/administration.html#t-core">&os; Core Team</ulink>
<link xlink:href="&url.base;/administration.html#t-core">&os; Core Team</link>
</simpara>
</footnote>
of developers provide some level of direction over the project.</para>
<para>The rapid pace of <systemitem class="osname">&os;</systemitem>
<para>The rapid pace of <systemitem>&os;</systemitem>
development makes the main development branch unsuitable for the
everyday use by the general public. In particular, stabilizing
efforts are required for polishing the development system into a
@ -137,15 +129,14 @@
<para>In the interim period between releases, weekly snapshots are
built automatically by the &os; Project build machines and made
available for download from <systemitem
class="resource">ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/</systemitem>.
available for download from <systemitem>ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/</systemitem>.
The widespread availability of binary release snapshots, and the
tendency of our user community to keep up with -STABLE development
with Subversion and <quote><command>make</command>
<maketarget>buildworld</maketarget></quote>
<buildtarget>buildworld</buildtarget></quote>
<footnote>
<simpara>
<ulink url="&url.books.handbook;/makeworld.html">Rebuilding "world"</ulink>
<link xlink:href="&url.books.handbook;/makeworld.html">Rebuilding "world"</link>
</simpara>
</footnote>
helps to keep
@ -158,8 +149,7 @@
<application>VirtualBox</application>,
<application>qemu</application>, or other popular emulation
software. The virtual machine images can be downloaded from
<systemitem
class="resource">ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/</systemitem>.</para>
<systemitem>ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/</systemitem>.</para>
<para>The virtual machine images are approximately 150MB &man.xz.1;
compressed, and contain a 10GB sparse filesystem when attached to
@ -167,16 +157,15 @@
<para>Bug reports and feature requests are continuously submitted by
users throughout the release cycle. Problems reports are entered into our
<application class="software">GNATS</application> database
<application>GNATS</application> database
<footnote>
<simpara>
GNATS: The GNU Bug Tracking System
<ulink url="http://www.gnu.org/software/gnats"></ulink>
<uri xlink:href="http://www.gnu.org/software/gnats">http://www.gnu.org/software/gnats</uri>
</simpara>
</footnote>
through email, the &man.send-pr.1; application, or via the web
interface provided at <ulink
url="http://www.FreeBSD.org/send-pr.html"></ulink>.</para>
interface provided at <uri xlink:href="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</uri>.</para>
<para>To service our most conservative users, individual release
branches were introduced with &os;&nbsp;4.3.
@ -239,7 +228,7 @@
</sect1>
<!-- Release Process -->
<sect1 id="release-proc">
<sect1 xml:id="release-proc">
<title>Release Process</title>
<para>New releases of &os; are released from the -STABLE branch
@ -330,7 +319,7 @@
widespread testing and all major issues have been resolved, the
final release <quote>polishing</quote> can begin.</para>
<sect3 id="rel-branch">
<sect3 xml:id="rel-branch">
<title>Creating the Release Branch</title>
<note>
@ -340,10 +329,10 @@
</note>
<para>The layout of &os; branches in Subversion is
described in the <ulink url="&url.articles.committers-guide;/subversion-primer.html#subversion-primer-base-layout">Committer's Guide</ulink>.
described in the <link xlink:href="&url.articles.committers-guide;/subversion-primer.html#subversion-primer-base-layout">Committer's Guide</link>.
The first step in creating a branch is to
identify the revision of the
<literal>stable/<replaceable>X</replaceable></literal> sources
<literal>stable/X</literal> sources
that you want to branch <emphasis>from</emphasis>.</para>
<screen>&prompt.root; <userinput>svn log -v $FSVN/stable/9</userinput></screen>
@ -359,9 +348,8 @@
<note>
<para>Creating the <literal>releng</literal> branch and
<literal>release</literal> tags is done by the <ulink
url="&url.base;/administration.html#t-re">Release
Engineering Team</ulink>.
<literal>release</literal> tags is done by the <link xlink:href="&url.base;/administration.html#t-re">Release
Engineering Team</link>.
</para>
</note>
@ -446,7 +434,7 @@
</mediaobject>
</sect3>
<sect3 id="versionbump">
<sect3 xml:id="versionbump">
<title>Bumping up the Version Number</title>
<para>Before the final release can be tagged, built, and
@ -548,7 +536,7 @@
<footnote>
<simpara>
&os; Ports Collection
<ulink url="http://www.FreeBSD.org/ports"></ulink>
<uri xlink:href="http://www.FreeBSD.org/ports">http://www.FreeBSD.org/ports</uri>
</simpara>
</footnote>
This information is currently kept in
@ -561,7 +549,7 @@
<itemizedlist>
<listitem>
<para><filename>share/images/articles/releng/branches-releng<replaceable>X</replaceable>.pic</filename></para>
<para><filename>share/images/articles/releng/branches-relengX.pic</filename></para>
</listitem>
<listitem>
@ -621,15 +609,15 @@
</sect1>
<!-- Release Building -->
<sect1 id="release-build">
<sect1 xml:id="release-build">
<title>Release Building</title>
<para>&os; <quote>releases</quote> can be built by anyone with a
fast machine and access to a source repository. (That should be
everyone, since we offer Subversion access !
See the
<ulink url="&url.books.handbook;/svn.html">Subversion section
in the Handbook</ulink> for
<link xlink:href="&url.books.handbook;/svn.html">Subversion section
in the Handbook</link> for
details.) The <emphasis>only</emphasis> special requirement is
that the &man.md.4; device must be available. If the
device is not loaded into your kernel, then the kernel module
@ -666,7 +654,7 @@
<listitem>
<para>Creation of a sanitized system environment in a separate
directory hierarchy with <quote><command>make
<literal>installworld</literal></command></quote>.
installworld</command></quote>.
</para>
</listitem>
@ -745,8 +733,8 @@
<sect2>
<title>Contributed Software (<quote>ports</quote>)</title>
<para>The <ulink url="http://www.FreeBSD.org/ports">&os; Ports
collection</ulink> is a collection of over &os.numports;
<para>The <link xlink:href="http://www.FreeBSD.org/ports">&os; Ports
collection</link> is a collection of over &os.numports;
third-party software packages available for &os;. The &a.portmgr;
is responsible for maintaining a consistent ports tree that can be used
to create the binary packages that accompany official &os;
@ -775,7 +763,7 @@
<emphasis>manifest</emphasis> can be created with a simple
command:</para>
<screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/^\.\///' | sort > filename.txt</userinput></screen>
<screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/^\.\///' | sort &gt; filename.txt</userinput></screen>
<para>The specific requirements of each CD are outlined below.</para>
@ -849,22 +837,22 @@
</sect1>
<!-- Distribution -->
<sect1 id="distribution">
<sect1 xml:id="distribution">
<title>Distribution</title>
<sect2 id="dist-ftp">
<sect2 xml:id="dist-ftp">
<title>FTP Sites</title>
<para>When the release has been thoroughly tested and packaged for
distribution, the master FTP site must be updated. The official
&os; public FTP sites are all mirrors of a master server that
is open only to other FTP sites. This site is known as
<hostid>ftp-master</hostid>. When the release is ready, the
following files must be modified on <hostid>ftp-master</hostid>:</para>
<systemitem>ftp-master</systemitem>. When the release is ready, the
following files must be modified on <systemitem>ftp-master</systemitem>:</para>
<variablelist>
<varlistentry>
<term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/</filename></term>
<term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/</filename></term>
<listitem>
<para>The installable FTP directory as output from <command>make
release</command>.</para>
@ -872,25 +860,25 @@
</varlistentry>
<varlistentry>
<term><filename>/pub/FreeBSD/ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release/</filename></term>
<term><filename>/pub/FreeBSD/ports/arch/packages-X.Y-release/</filename></term>
<listitem><para>The complete package build for this
release.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/tools</filename></term>
<term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools</filename></term>
<listitem><para>A symlink to
<filename>../../../tools</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/packages</filename></term>
<term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages</filename></term>
<listitem><para>A symlink to
<filename>../../../ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release</filename>.</para></listitem>
<filename>../../../ports/arch/packages-X.Y-release</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>X.Y</replaceable>/<replaceable>X.Y</replaceable>-RELEASE-<replaceable>arch</replaceable>-*.iso</filename></term>
<term><filename>/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso</filename></term>
<listitem><para>The ISO images. The <quote>*</quote> is
<filename>disc1</filename>, <filename>disc2</filename>, etc.
Only if there is a <filename>disc1</filename> and there is an
@ -902,11 +890,10 @@
</variablelist>
<para>For more information about the distribution mirror
architecture of the &os; FTP sites, please see the <ulink
url="&url.articles.hubs;/">Mirroring &os;</ulink> article.</para>
architecture of the &os; FTP sites, please see the <link xlink:href="&url.articles.hubs;/">Mirroring &os;</link> article.</para>
<para>It may take many hours to two days after updating
<hostid>ftp-master</hostid> before a majority of the Tier-1 FTP
<systemitem>ftp-master</systemitem> before a majority of the Tier-1 FTP
sites have the new software depending on whether or not a package
set got loaded at the same time. It is imperative that the release
engineers coordinate with the &a.mirror-announce; before announcing the general
@ -924,7 +911,7 @@
time, for example make it relative to GMT.</para>
</sect2>
<sect2 id="dist-cdrom">
<sect2 xml:id="dist-cdrom">
<title>CD-ROM Replication</title>
<para>Coming soon: Tips for sending &os; ISOs to a replicator
@ -934,7 +921,7 @@
</sect1>
<!-- Extensibility -->
<sect1 id="extensibility">
<sect1 xml:id="extensibility">
<title>Extensibility</title>
<para>Although &os; forms a complete operating system, there is
@ -959,7 +946,7 @@
with &intel; PXE
<footnote>
<simpara>
<ulink url="&url.books.handbook;/network-pxe-nfs.html"></ulink>
<uri xlink:href="&url.books.handbook;/network-pxe-nfs.html">&url.books.handbook;/network-pxe-nfs.html</uri>
</simpara>
</footnote>
to bootstrap systems from the network.
@ -968,7 +955,7 @@
</sect1>
<!-- Lessons Learned -->
<sect1 id="lessons-learned">
<sect1 xml:id="lessons-learned">
<title>Lessons Learned from &os;&nbsp;4.4</title>
<para>The release engineering process for 4.4 formally began on
@ -993,7 +980,7 @@
</sect1>
<!-- Future Directions -->
<sect1 id="future">
<sect1 xml:id="future">
<title>Future Directions</title>
<para>It is imperative for our release engineering activities to
@ -1042,7 +1029,7 @@
</sect1>
<!-- Acknowledgements -->
<sect1 id="ackno">
<sect1 xml:id="ackno">
<title>Acknowledgements</title>
<para>I would like to thank Jordan Hubbard for giving me the
@ -1059,8 +1046,8 @@
<footnote>
<simpara>
Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic:
<ulink url="http://docs.FreeBSD.org/44doc/papers/releng.html">
<emphasis>The Release Engineering of 4.3BSD</emphasis></ulink>
<link xlink:href="http://docs.FreeBSD.org/44doc/papers/releng.html">
<emphasis>The Release Engineering of 4.3BSD</emphasis></link>
</simpara>
</footnote>
,
@ -1068,7 +1055,7 @@
<footnote>
<simpara>
NetBSD Developer Documentation: Release Engineering
<ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink>
<uri xlink:href="http://www.NetBSD.org/developers/releng/index.html">http://www.NetBSD.org/developers/releng/index.html</uri>
</simpara>
</footnote>
, and John
@ -1076,7 +1063,7 @@
<footnote>
<simpara>
John Baldwin's &os; Release Engineering Proposal
<ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink>
<uri xlink:href="http://people.FreeBSD.org/~jhb/docs/releng.txt">http://people.FreeBSD.org/~jhb/docs/releng.txt</uri>
</simpara>
</footnote>
</para>

111
en_US.ISO8859-1/articles/remote-install/article.xml
View file

@ -1,22 +1,16 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Remote Installation of the &os; Operating System without a
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Remote Installation of the &os; Operating System without a
Remote Console</title>
<author>
<firstname>Daniel</firstname>
<surname>Gerzo</surname>
<affiliation>
<author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><affiliation>
<address><email>danger@FreeBSD.org</email></address>
</affiliation>
<!-- 11 April 2008 -->
</author>
</affiliation></author>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -37,9 +31,9 @@
a collaboration with &a.mm.email; with valuable input provided by
&a.pjd.email;.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="background">
<sect1 xml:id="background">
<title>Background</title>
<para>There are many server hosting providers in the world, but very
@ -58,7 +52,7 @@
RAID-1 and <application>ZFS</application> capabilities.</para>
</sect1>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Introduction</title>
<para>This section will summarize the purpose of this article and
@ -68,8 +62,7 @@
<procedure>
<step>
<para>As we have mentioned in the <link
linkend="background">Background</link> section, many of the
<para>As we have mentioned in the <link linkend="background">Background</link> section, many of the
reputable server hosting companies provide some kind of rescue
system, which is booted from their <acronym>LAN</acronym> and
accessible over <application>SSH</application>. They usually
@ -97,7 +90,7 @@
</step>
</procedure>
<sect2 id="requirements">
<sect2 xml:id="requirements">
<title>Requirements</title>
<para>To continue successfully, you must:</para>
@ -124,7 +117,7 @@
</sect2>
</sect1>
<sect1 id="preparation">
<sect1 xml:id="preparation">
<title>Preparation - <application>mfsBSD</application></title>
<para>Before &os; may be installed on the target system, it is
@ -140,8 +133,7 @@
entirely from a ramdisk. Thanks to this feature, the manipulation
of hard drives will not be limited, therefore it will be possible
to install a complete &os; operating system. The home page of
<application>mfsBSD</application>, at <ulink
url="http://people.freebsd.org/~mm/mfsbsd/"></ulink>, includes
<application>mfsBSD</application>, at <uri xlink:href="http://people.freebsd.org/~mm/mfsbsd/">http://people.freebsd.org/~mm/mfsbsd/</uri>, includes
pointers to the latest release of the toolset.</para>
<para>Please note that the internals of
@ -156,10 +148,10 @@
<application>mfsBSD</application> scripts will reside:</para>
<screen>&prompt.root; <userinput>fetch http://people.freebsd.org/~mm/mfsbsd/mfsbsd-latest.tar.gz</userinput>
&prompt.root; <userinput>tar xvzf mfsbsd-<replaceable>1.0-beta1</replaceable>.tar.gz</userinput>
&prompt.root; <userinput>cd <replaceable>mfsbsd-1.0-beta1</replaceable>/</userinput></screen>
&prompt.root; <userinput>tar xvzf mfsbsd-1.0-beta1.tar.gz</userinput>
&prompt.root; <userinput>cd mfsbsd-1.0-beta1/</userinput></screen>
<sect2 id="mfsbsd-config">
<sect2 xml:id="mfsbsd-config">
<title>Configuration of <application>mfsBSD</application></title>
<para>Before booting <application>mfsBSD</application>, a few
@ -173,7 +165,7 @@
case.</para>
<para>Another important thing to set is the
<username>root</username> password. This can be done by editing
<systemitem class="username">root</systemitem> password. This can be done by editing
the <filename>conf/rootpw.conf</filename> file. Please keep in
mind that the file will contain your password in the plain text,
thus we do not recommend to use real password here.
@ -221,7 +213,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
</sect3>
</sect2>
<sect2 id="mfsbsd-build">
<sect2 xml:id="mfsbsd-build">
<title>Building an <application>mfsBSD</application> image</title>
<para>The process of building an <application>mfsBSD</application>
@ -229,26 +221,24 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
<para>The first step is to mount the &os; installation
<acronym>CD</acronym>, or the installation
<acronym>ISO</acronym> image to <filename
class="directory">/cdrom</filename>. For the sake of example,
<acronym>ISO</acronym> image to <filename>/cdrom</filename>. For the sake of example,
in this article we will assume that you have downloaded the &os;
7.0-RELEASE <acronym>ISO</acronym>. Mounting this ISO image to
the <filename class="directory">/cdrom</filename> directory is
the <filename>/cdrom</filename> directory is
easy with the &man.mdconfig.8; utility:</para>
<screen>&prompt.root; <userinput>mdconfig -a -t vnode -u 10 -f <replaceable>7.0-RELEASE-amd64-disc1.iso</replaceable></userinput>
<screen>&prompt.root; <userinput>mdconfig -a -t vnode -u 10 -f 7.0-RELEASE-amd64-disc1.iso</userinput>
&prompt.root; <userinput>mount_cd9660 /dev/md10 /cdrom</userinput></screen>
<para>Next, build the bootable <application>mfsBSD</application>
image:</para>
<screen>&prompt.root; <userinput>make BASE=/cdrom/<replaceable>7.0-RELEASE</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>make BASE=/cdrom/7.0-RELEASE</userinput></screen>
<note>
<para>The above <command>make</command> command has to be run
from the top level of the <application>mfsBSD</application>
directory tree, i.e. <filename
class="directory">~/mfsbsd-1.0-beta1/</filename>.</para>
directory tree, i.e. <filename>~/mfsbsd-1.0-beta1/</filename>.</para>
</note>
</sect2>
@ -266,7 +256,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
<para>To boot <application>mfsBSD</application> image properly, it
must be placed on the first (bootable) device of the given
machine. This may be accomplished using this example providing
that <devicename>sda</devicename> is the first bootable disk
that <filename>sda</filename> is the first bootable disk
device:</para>
<screen>&prompt.root; <userinput>dd if=/root/disk.img of=/dev/sda bs=1m</userinput></screen>
@ -276,11 +266,11 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
be rebooted. Watch for the machine to boot up properly with the
&man.ping.8; tool. Once it has came back on-line, it should be
possible to access it over &man.ssh.1; as user
<username>root</username> with the configured password.</para>
<systemitem class="username">root</systemitem> with the configured password.</para>
</sect2>
</sect1>
<sect1 id="installation">
<sect1 xml:id="installation">
<title>Installation of The &os; Operating System</title>
<para>The <application>mfsBSD</application> has been successfully
@ -304,7 +294,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
<para>At the start, mark all system disks as empty. Repeat the
following command for each hard drive:</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/<replaceable>ad0</replaceable> count=2</userinput></screen>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad0 count=2</userinput></screen>
<para>Next, create slices and label them with your preferred tool.
While it is considered easier to use
@ -312,15 +302,12 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
probably less buggy method will be to use standard text-based
&unix; tools, such as &man.fdisk.8; and &man.bsdlabel.8;, which
will also be covered in this section. The former option is well
documented in the <ulink
url="&url.books.handbook;/install-steps.html">Installing &os;</ulink>
documented in the <link xlink:href="&url.books.handbook;/install-steps.html">Installing &os;</link>
chapter of the &os; Handbook. As it was mentioned in the
introduction, this article will present how to set up a system
with RAID-1 and <application>ZFS</application> capabilities.
Our set up will consist of a small &man.gmirror.8; mirrored
<filename class="directory">/</filename> (root), <filename
class="directory">/usr</filename> and <filename
class="directory">/var</filename> file systems, and the rest of
<filename>/</filename> (root), <filename>/usr</filename> and <filename>/var</filename> file systems, and the rest of
the disk space will be allocated for a &man.zpool.8; mirrored
<application>ZFS</application> file system. Please note, that
the <application>ZFS</application> file system will be
@ -332,17 +319,17 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
create a <application>UFS2</application> file system in each
mirrored partition:</para>
<screen>&prompt.root; <userinput>fdisk -BI /dev/ad0</userinput> <co id="fdisk"/>
<screen>&prompt.root; <userinput>fdisk -BI /dev/ad0</userinput> <co xml:id="fdisk"/>
&prompt.root; <userinput>fdisk -BI /dev/ad1</userinput>
&prompt.root; <userinput>bsdlabel -wB /dev/ad0s1</userinput> <co id="bsdlabel-writing"/>
&prompt.root; <userinput>bsdlabel -wB /dev/ad0s1</userinput> <co xml:id="bsdlabel-writing"/>
&prompt.root; <userinput>bsdlabel -wB /dev/ad1s1</userinput>
&prompt.root; <userinput>bsdlabel -e /dev/ad0s1</userinput> <co id="bsdlabel-editing"/>
&prompt.root; <userinput>bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt &amp;&amp; bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt</userinput> <co id="bsdlabel-restore"/>
&prompt.root; <userinput>gmirror label root /dev/ad[01]s1a</userinput> <co id="gmirror1"/>
&prompt.root; <userinput>bsdlabel -e /dev/ad0s1</userinput> <co xml:id="bsdlabel-editing"/>
&prompt.root; <userinput>bsdlabel /dev/ad0s1 &gt; /tmp/bsdlabel.txt &amp;&amp; bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt</userinput> <co xml:id="bsdlabel-restore"/>
&prompt.root; <userinput>gmirror label root /dev/ad[01]s1a</userinput> <co xml:id="gmirror1"/>
&prompt.root; <userinput>gmirror label var /dev/ad[01]s1d</userinput>
&prompt.root; <userinput>gmirror label usr /dev/ad[01]s1e</userinput>
&prompt.root; <userinput>gmirror label -F swap /dev/ad[01]s1b</userinput> <co id="gmirror2"/>
&prompt.root; <userinput>newfs /dev/mirror/root</userinput> <co id="newfs"/>
&prompt.root; <userinput>gmirror label -F swap /dev/ad[01]s1b</userinput> <co xml:id="gmirror2"/>
&prompt.root; <userinput>newfs /dev/mirror/root</userinput> <co xml:id="newfs"/>
&prompt.root; <userinput>newfs /dev/mirror/var</userinput>
&prompt.root; <userinput>newfs /dev/mirror/usr</userinput></screen>
@ -363,12 +350,10 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
<para>Now, manually edit the label of the given disk. Refer
to the &man.bsdlabel.8; manual page in order to find out how
to create partitions. Create partitions
<literal>a</literal> for <filename
class="directory">/</filename> (root) file system,
<literal>a</literal> for <filename>/</filename> (root) file system,
<literal>b</literal> for swap, <literal>d</literal> for
<filename class="directory">/var</filename>,
<literal>e</literal> for <filename
class="directory">/usr</filename> and finally
<filename>/var</filename>,
<literal>e</literal> for <filename>/usr</filename> and finally
<literal>f</literal> which will later be used for
<application>ZFS</application>.</para>
</callout>
@ -417,8 +402,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
menu. Select <guimenuitem>Options</guimenuitem> and press
<keycap>Enter</keycap>. With the help of arrow keys, move the
cursor on the <literal>Install Root</literal> item, press
<keycap>Space</keycap> and change it to <filename
class="directory">/mnt</filename>. Press
<keycap>Space</keycap> and change it to <filename>/mnt</filename>. Press
<keycap>Enter</keycap> to submit your changes and exit the
<guimenuitem>Options</guimenuitem> menu by pressing
<keycap>q</keycap>.</para>
@ -475,7 +459,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting>
<itemizedlist>
<listitem>
<para>Copy the <literal>GENERIC</literal> kernel to the
<filename class="directory">/boot/kernel</filename>
<filename>/boot/kernel</filename>
directory:</para>
<screen>&prompt.root; <userinput>cp -Rp /boot/GENERIC/* /boot/kernel</userinput></screen>
@ -512,13 +496,13 @@ zfs_load="YES"</programlisting>
<application>ZFS</application> available on the next
boot:</para>
<screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >> /etc/rc.conf </userinput></screen>
<screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' &gt;&gt; /etc/rc.conf </userinput></screen>
</listitem>
<listitem>
<para>Add additional users to the system using the
&man.adduser.8; tool. Do not forget to add a user to the
<groupname>wheel</groupname> group so you may obtain root
<systemitem class="groupname">wheel</systemitem> group so you may obtain root
access after the reboot.</para>
</listitem>
@ -532,7 +516,7 @@ zfs_load="YES"</programlisting>
</sect2>
</sect1>
<sect1 id="zfs">
<sect1 xml:id="zfs">
<title>ZFS</title>
<para>If your system survived the reboot, it should now be possible
@ -556,8 +540,7 @@ zfs_load="YES"</programlisting>
&prompt.root; <userinput>zfs set mountpoint=/usr/src tank/src</userinput></screen>
<para>That's all. If you are interested in more details about
<application>ZFS</application> on &os;, please refer to the <ulink
url="http://wiki.freebsd.org/ZFS">ZFS</ulink> section of the &os;
<application>ZFS</application> on &os;, please refer to the <link xlink:href="http://wiki.freebsd.org/ZFS">ZFS</link> section of the &os;
Wiki.</para>
</sect1>
</article>

91
en_US.ISO8859-1/articles/serial-uart/article.xml
View file

@ -1,23 +1,17 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='en'>
<articleinfo>
<title>Serial and UART Tutorial</title>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Serial and UART Tutorial</title>
<authorgroup>
<author>
<firstname>Frank</firstname>
<surname>Durda</surname>
<affiliation>
<author><personname><firstname>Frank</firstname><surname>Durda</surname></personname><affiliation>
<address><email>uhclem@FreeBSD.org</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.microsoft;
&tm-attrib.general;
@ -30,9 +24,9 @@
<abstract>
<para>This article talks about using serial hardware with FreeBSD.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="uart">
<sect1 xml:id="uart">
<title>The UART: What it is and how it works</title>
<para><emphasis>Copyright &copy; 1996 &a.uhclem.email;, All Rights
@ -1151,16 +1145,16 @@
<para>The 8250/16450/16550 UART occupies eight contiguous I/O
port addresses. In the IBM PC, there are two defined
locations for these eight ports and they are known
collectively as <devicename>COM1</devicename> and <devicename>COM2</devicename>. The makers of PC-clones and
add-on cards have created two additional areas known as <devicename>COM3</devicename>
and <devicename>COM4</devicename>, but these extra COM ports conflict with other
collectively as <filename>COM1</filename> and <filename>COM2</filename>. The makers of PC-clones and
add-on cards have created two additional areas known as <filename>COM3</filename>
and <filename>COM4</filename>, but these extra COM ports conflict with other
hardware on some systems. The most common conflict is with
video adapters that provide IBM 8514 emulation.</para>
<para><devicename>COM1</devicename> is located from 0x3f8 to 0x3ff and normally uses
IRQ 4. <devicename>COM2</devicename> is located from 0x2f8 to 0x2ff and normally uses
IRQ 3. <devicename>COM3</devicename> is located from 0x3e8 to 0x3ef and has no
standardized IRQ. <devicename>COM4</devicename> is located from 0x2e8 to 0x2ef and has
<para><filename>COM1</filename> is located from 0x3f8 to 0x3ff and normally uses
IRQ 4. <filename>COM2</filename> is located from 0x2f8 to 0x2ff and normally uses
IRQ 3. <filename>COM3</filename> is located from 0x3e8 to 0x3ef and has no
standardized IRQ. <filename>COM4</filename> is located from 0x2e8 to 0x2ef and has
no standardized IRQ.</para>
<para>A description of the I/O ports of the 8250/16450/16550
@ -1969,10 +1963,10 @@
</sect2>
</sect1>
<sect1 id="sio">
<title>Configuring the <devicename>sio</devicename> driver</title>
<sect1 xml:id="sio">
<title>Configuring the <filename>sio</filename> driver</title>
<para>The <devicename>sio</devicename> driver provides support
<para>The <filename>sio</filename> driver provides support
for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C
(CCITT V.24) communications interfaces. Several multiport
cards are supported as well. See the &man.sio.4; manual page
@ -2039,9 +2033,8 @@ device sio11 at isa? port 0x138 flags 0xb05 irq 9</programlisting>
either.</para>
<para>If you do not already have a custom kernel
configuration file set up, refer to <ulink
url="&url.books.handbook;/kernelconfig.html">Kernel
Configuration</ulink> chapter of the FreeBSD Handbook for
configuration file set up, refer to <link xlink:href="&url.books.handbook;/kernelconfig.html">Kernel
Configuration</link> chapter of the FreeBSD Handbook for
general procedures. The following are the specifics for the
Boca 16 board and assume you are using the kernel name
MYKERNEL and editing with vi.</para>
@ -2057,7 +2050,7 @@ device sio11 at isa? port 0x138 flags 0xb05 irq 9</programlisting>
<step>
<para>Where the current <literal>device
sio<replaceable>n</replaceable></literal> lines are, you
sion</literal> lines are, you
will need to add 16 more devices. The
following example is for a Boca Board with an interrupt
of 3, and a base IO address 100h. The IO address for
@ -2147,7 +2140,7 @@ sio16: type 16550A (multiport master)</screen>
support compiled in.</para>
<para>If you do need to create the <filename>/dev</filename>
entries, run the following as <username>root</username>:</para>
entries, run the following as <systemitem class="username">root</systemitem>:</para>
<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>./MAKEDEV tty1</userinput>
@ -2187,14 +2180,14 @@ sio16: type 16550A (multiport master)</screen>
<para>Usually the only option to support these kind of boards
is to use a distinct IRQ for each port. For example, if
your CPU board has an on-board <devicename>COM1</devicename>
port (aka <devicename>sio0</devicename>&ndash;I/O address
your CPU board has an on-board <filename>COM1</filename>
port (aka <filename>sio0</filename>&ndash;I/O address
0x3F8 and IRQ 4) and you have an extension board with two
UARTs, you will commonly need to configure them as
<devicename>COM2</devicename> (aka
<devicename>sio1</devicename>&ndash;I/O address 0x2F8 and
<filename>COM2</filename> (aka
<filename>sio1</filename>&ndash;I/O address 0x2F8 and
IRQ 3), and the third port (aka
<devicename>sio2</devicename>) as I/O 0x3E8 and IRQ 5.
<filename>sio2</filename>) as I/O 0x3E8 and IRQ 5.
Obviously this is a waste of IRQ resources, as it should be
basically possible to run both extension board ports using a
single IRQ with the <literal>COM_MULTIPORT</literal>
@ -2237,7 +2230,7 @@ IRQ 2 3 4 5</programlisting>
above:</para>
<programlisting> Diode
+---------->|-------+
+----------&gt;|-------+
/ |
o * o o | 1 kOhm
Port A +----|######|-------+
@ -2245,7 +2238,7 @@ Port A +----|######|-------+
Port B `-------------------+ ==+==
o * o o | Ground
\ |
+--------->|-------+
+---------&gt;|-------+
IRQ 2 3 4 5 Diode</programlisting>
<para>The cathodes of the diodes are connected to a common
@ -2264,11 +2257,11 @@ device sio1 at isa? port "IO_COM2" flags 0x205
device sio2 at isa? port "IO_COM3" flags 0x205 irq 3</programlisting>
<para>Note that the <literal>flags</literal> setting for
<devicename>sio1</devicename> and
<devicename>sio2</devicename> is truly essential; refer to
<filename>sio1</filename> and
<filename>sio2</filename> is truly essential; refer to
&man.sio.4; for details. (Generally, the
<literal>2</literal> in the "flags" attribute refers to
<devicename>sio</devicename>2 which holds the IRQ, and you
<filename>sio</filename>2 which holds the IRQ, and you
surely want a <literal>5</literal> low nibble.) With kernel
verbose mode turned on this should yield something similar
to this:</para>
@ -2294,20 +2287,20 @@ sio2: type 16550A (multiport master)</screen>
</sect2>
</sect1>
<sect1 id="cy">
<title>Configuring the <devicename>cy</devicename> driver</title>
<sect1 xml:id="cy">
<title>Configuring the <filename>cy</filename> driver</title>
<para><emphasis>Contributed by Alex Nash. 6 June
1996.</emphasis></para>
<para>The Cyclades multiport cards are based on the
<devicename>cy</devicename> driver instead of the usual
<devicename>sio</devicename> driver used by other multiport
<filename>cy</filename> driver instead of the usual
<filename>sio</filename> driver used by other multiport
cards. Configuration is a simple matter of:</para>
<procedure>
<step>
<para>Add the <devicename>cy</devicename> device to your
<para>Add the <filename>cy</filename> device to your
kernel configuration (note that your irq and iomem
settings may differ).</para>
@ -2350,13 +2343,13 @@ ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting>
</sect1>
<sect1>
<title>Configuring the <devicename>si</devicename> driver</title>
<title>Configuring the <filename>si</filename> driver</title>
<para><emphasis>Contributed by &a.nsayer.email;. 25 March
1998.</emphasis></para>
<para>The Specialix SI/XIO and SX multiport cards use the
<devicename>si</devicename> driver. A single machine can have
<filename>si</filename> driver. A single machine can have
up to 4 host cards. The following host cards are
supported:</para>
@ -2420,7 +2413,7 @@ ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting>
you have and type:</para>
<screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>./MAKEDEV ttyA<replaceable>nn</replaceable> cuaA<replaceable>nn</replaceable></userinput></screen>
&prompt.root; <userinput>./MAKEDEV ttyAnn cuaAnn</userinput></screen>
<para>(where <replaceable>nn</replaceable> is the number of
ports)</para>

78
en_US.ISO8859-1/articles/solid-state/article.xml
View file

@ -1,7 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- Copyright (c) 2001 The FreeBSD Documentation Project
Redistribution and use in source (SGML DocBook) and 'compiled' forms
@ -33,20 +32,14 @@
$FreeBSD$
-->
<article lang='en'>
<articleinfo>
<title>&os; and Solid State Devices</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>&os; and Solid State Devices</title>
<authorgroup>
<author>
<firstname>John</firstname>
<surname>Kozubik</surname>
<affiliation>
<author><personname><firstname>John</firstname><surname>Kozubik</surname></personname><affiliation>
<address><email>john@kozubik.com</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<copyright>
@ -55,7 +48,7 @@
<holder>The FreeBSD Documentation Project</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
@ -85,9 +78,9 @@
The article will conclude with some general strategies for
small and read-only &os; environments.</para>
</abstract>
</articleinfo>
</info>
<sect1 id="intro">
<sect1 xml:id="intro">
<title>Solid State Disk Devices</title>
<para>The scope of this article will be limited to solid state
@ -126,7 +119,7 @@
beyond the scope of this article.</para>
</sect1>
<sect1 id="kernel">
<sect1 xml:id="kernel">
<title>Kernel Options</title>
<para>A few kernel options are of specific interest to those
@ -151,7 +144,7 @@ options MD_ROOT # md device usable as a potential root device
pseudo-device md # memory disk</programlisting>
</sect1>
<sect1 id="ro-fs">
<sect1 xml:id="ro-fs">
<title>The <literal>rc</literal> Subsystem and Read-Only
Filesystems</title>
@ -210,11 +203,11 @@ pseudo-device md # memory disk</programlisting>
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>
<screen>&prompt.root; <userinput>/sbin/mount -uw partition</userinput></screen>
<para>and can be toggled back to read-only with the command:</para>
<screen>&prompt.root; <userinput>/sbin/mount -ur <replaceable>partition</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>/sbin/mount -ur partition</userinput></screen>
</sect1>
<sect1>
@ -324,12 +317,12 @@ pseudo-device md # memory disk</programlisting>
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>
<screen><prompt>ftp&gt;</prompt> <userinput>get tarfile.tar "| tar xvf -"</userinput></screen>
<para>If your tarfile is gzipped, you can accomplish this as
well:</para>
<screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| zcat | tar xvf -"</userinput></screen>
<screen><prompt>ftp&gt;</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
@ -348,7 +341,7 @@ pseudo-device md # memory disk</programlisting>
</procedure>
</sect1>
<sect1 id="strategies">
<sect1 xml:id="strategies">
<title>System Strategies for Small and Read Only
Environments</title>
@ -363,12 +356,10 @@ pseudo-device md # memory disk</programlisting>
<sect2>
<title>cron</title>
<para>Upon boot, <filename class="directory">/var</filename>
<para>Upon boot, <filename>/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
<filename>cron</filename>, <filename>cron/tabs</filename>, <filename>at</filename>, and a few other standard
directories get created.</para>
<para>However, this does not solve the problem of maintaining
@ -411,15 +402,14 @@ pseudo-device md # memory disk</programlisting>
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
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
<command>make</command> <buildtarget>install</buildtarget>, 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
@ -442,7 +432,7 @@ pseudo-device md # memory disk</programlisting>
<para>Now, any time that you mount your filesystems as
read-write and install a package, the
<command>make</command> <maketarget>install</maketarget> will
<command>make</command> <buildtarget>install</buildtarget> 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
@ -456,24 +446,20 @@ pseudo-device md # memory disk</programlisting>
<note>
<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>
<filename>/var</filename>. By default,
Apache keeps its pid file in <filename>/var/run/httpd.pid</filename> and its
log files in <filename>/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>
outside of <filename class="directory">/var</filename>.
directory <filename>apache_log_dir</filename>
outside of <filename>/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
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>
<filename>apache_log_dir</filename>
to <filename>/var/log/apache</filename>. It is also necessary
to set permissions and ownership on this new directory.</para>
@ -488,13 +474,11 @@ pseudo-device md # memory disk</programlisting>
<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>apache_log_dir</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>
&prompt.root; <userinput>ln -s /var/log/apache <filename class="directory"><replaceable>apache_log_dir</replaceable></filename></userinput></screen>
<screen>&prompt.root; <userinput>rm -rf apache_log_dir</userinput>
&prompt.root; <userinput>ln -s /var/log/apache apache_log_dir</userinput></screen>
</sect2>
</sect1>
</article>

54
en_US.ISO8859-1/articles/vm-design/article.xml
View file

@ -1,29 +1,21 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd">
<!-- $FreeBSD$ -->
<!-- FreeBSD Documentation Project -->
<article lang='en'>
<articleinfo>
<title>Design elements of the &os; VM system</title>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Design elements of the &os; VM system</title>
<authorgroup>
<author>
<firstname>Matthew</firstname>
<surname>Dillon</surname>
<affiliation>
<author><personname><firstname>Matthew</firstname><surname>Dillon</surname></personname><affiliation>
<address>
<email>dillon@apollo.backplane.com</email>
</address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.linux;
&tm-attrib.microsoft;
@ -52,15 +44,15 @@
with peoples names, since I will invariably get it wrong.</para>
</abstract>
<legalnotice id="legalnotice">
<legalnotice xml:id="legalnotice">
<para>This article was originally published in the January 2000 issue of
<ulink url="http://www.daemonnews.org/">DaemonNews</ulink>. This
<link xlink:href="http://www.daemonnews.org/">DaemonNews</link>. This
version of the article may include updates from Matt and other authors
to reflect changes in &os;'s VM implementation.</para>
</legalnotice>
</articleinfo>
</info>
<sect1 id="introduction">
<sect1 xml:id="introduction">
<title>Introduction</title>
<para>Before moving along to the actual design let's spend a little time
@ -128,7 +120,7 @@
the parallels to algorithmic design and code generalization.</para>
</sect1>
<sect1 id="vm-objects">
<sect1 xml:id="vm-objects">
<title>VM Objects</title>
<para>The best way to begin describing the &os; VM system is to look at
@ -292,10 +284,10 @@
called the <quote>All Shadowed Case</quote>. This case occurs if either
C1 or C2 take sufficient COW faults to completely shadow all pages in B.
Lets say that C1 achieves this. C1 can now bypass B entirely, so rather
then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But
then have C1-&gt;B-&gt;A and C2-&gt;B-&gt;A we now have C1-&gt;A and C2-&gt;B-&gt;A. But
look what also happened&mdash;now B has only one reference (C2), so we
can collapse B and C2 together. The end result is that B is deleted
entirely and we have C1->A and C2->A. It is often the case that B will
entirely and we have C1-&gt;A and C2-&gt;A. It is often the case that B will
contain a large number of pages and neither C1 nor C2 will be able to
completely overshadow it. If we fork again and create a set of D
layers, however, it is much more likely that one of the D layers will
@ -321,7 +313,7 @@
that they can be ignored, leaving no real disadvantage.</para>
</sect1>
<sect1 id="swap-layers">
<sect1 xml:id="swap-layers">
<title>SWAP Layers</title>
<para>Private data pages are initially either copy-on-write or zero-fill
@ -416,7 +408,7 @@
I ensured that such an addition could be made.</para>
</sect1>
<sect1 id="freeing-pages">
<sect1 xml:id="freeing-pages">
<title>When to free a page</title>
<para>Since the VM system uses all available memory for disk caching,
@ -501,7 +493,7 @@
pages. I do not know whether this is still true today.</para>
</sect1>
<sect1 id="prefault-optimizations">
<sect1 xml:id="prefault-optimizations">
<title>Pre-Faulting and Zeroing Optimizations</title>
<para>Taking a VM fault is not expensive if the underlying page is already
@ -537,7 +529,7 @@
optimize the critical path.</para>
</sect1>
<sect1 id="page-table-optimizations">
<sect1 xml:id="page-table-optimizations">
<title>Page Table Optimizations</title>
<para>The page table optimizations make up the most contentious part of
@ -572,7 +564,7 @@
whether a page can be reused or not.</para>
</sect1>
<sect1 id="page-coloring-optimizations">
<sect1 xml:id="page-coloring-optimizations">
<title>Page Coloring</title>
<para>We will end with the page coloring optimizations. Page coloring is a
@ -607,7 +599,7 @@
performance.</para>
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<para>Virtual memory in modern operating systems must address a number of
@ -619,7 +611,7 @@
years, and work is ongoing.</para>
</sect1>
<sect1 id="allen-briggs-qa">
<sect1 xml:id="allen-briggs-qa">
<title>Bonus QA session by Allen Briggs
<email>briggs@ninthwonder.com</email></title>
@ -713,7 +705,7 @@
<para>What this means is that &os; will not try very hard to
separate out dirty pages (inactive queue) from clean pages (cache
queue) when the system is not being stressed, nor will it try to
deactivate pages (active queue -> inactive queue) when the system
deactivate pages (active queue -&gt; inactive queue) when the system
is not being stressed, even if they are not being used.</para>
</answer>
</qandaentry>

69
en_US.ISO8859-1/articles/wp-toolbox/article.xml
View file

@ -1,28 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd" [
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"../../../share/xml/freebsd50.dtd" [
<!ENTITY ports "Ports Collection">
<!ENTITY os.ports "&os; &ports;">
<!ENTITY frisbee "<application>Frisbee</application>">
<!ENTITY ghost "<application>Ghost</application>">
<!ENTITY nessus "<application>Nessus</application>">
<!ENTITY os.ports "{{{os}}} {{{ports}}}">
<!ENTITY frisbee "<application xmlns='http://docbook.org/ns/docbook'>Frisbee</application>">
<!ENTITY ghost "<application xmlns='http://docbook.org/ns/docbook'>Ghost</application>">
<!ENTITY nessus "<application xmlns='http://docbook.org/ns/docbook'>Nessus</application>">
]>
<article lang='en'>
<title>Creating a Software Testing Environment Using &os;</title>
<articleinfo>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Creating a Software Testing Environment Using &os;</title>
<authorgroup>
<author>
<firstname>Chris</firstname>
<surname>McMahon</surname>
<affiliation>
<author><personname><firstname>Chris</firstname><surname>McMahon</surname></personname><affiliation>
<address><email>christopher.mcmahon@gmail.com</email></address>
</affiliation>
</author>
</affiliation></author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.microsoft;
@ -38,10 +33,10 @@
published in the Pacific Northwest Software Quality Conference
Proceedings, 2005.</para></abstract>
</articleinfo>
</info>
<sect1 id="overview">
<sect1 xml:id="overview">
<title>Overview</title>
<para>From late 2003 until early 2005, I was a tester in an
@ -63,7 +58,7 @@
</sect1>
<sect1 id="challenge">
<sect1 xml:id="challenge">
<title>The Challenge</title>
<para>Software testing environments are radically more complex
@ -86,15 +81,14 @@
</sect1>
<sect1 id="freebsd-solution">
<sect1 xml:id="freebsd-solution">
<title>The &os; Solution</title>
<sect2 id="freebsd-intro">
<sect2 xml:id="freebsd-intro">
<title>Introduction</title>
<para>The set of tools available with the &os; Operating
System is amazing. The &os; <ulink
url="http://www.freebsd.org/ports">&ports;</ulink>
System is amazing. The &os; <link xlink:href="http://www.freebsd.org/ports">&ports;</link>
contains more than thirteen thousand separate applications,
all of which have a standard installation procedure and
conform to a set of guidelines that make them reliable without
@ -121,7 +115,7 @@
</sect2>
<sect2 id="freebsd-ports">
<sect2 xml:id="freebsd-ports">
<title>How To Use The Ports System</title>
<para>Installing an application from the &os.ports; is a simple matter of: </para>
@ -135,7 +129,7 @@
who typically is pressed for time!</para>
</sect2>
<sect2 id="freebsd-testing">
<sect2 xml:id="freebsd-testing">
<title>&os; For Testing</title>
<para>The test environment should be more stable than the SUT.
@ -148,8 +142,7 @@
services to be their network-testing person in an all-Windows
environment. My first assignment was to replace the obsolete,
buggy, disk imaging system. I chose to do that with an Open
Source disk imaging system called <ulink
url="http://www.cs.utah.edu/flux/papers/frisbee-usenix03-base.html">&frisbee;</ulink>
Source disk imaging system called <link xlink:href="http://www.cs.utah.edu/flux/papers/frisbee-usenix03-base.html">&frisbee;</link>
which was implemented originally on &os;. I built the
system&mdash;a feature-for-feature replacement for an expensive
proprietary system&mdash;but we never actually used it in our
@ -165,12 +158,12 @@
</sect2>
<sect2 id="freebsd-collab">
<sect2 xml:id="freebsd-collab">
<title>&os; For Collaboration: Twiki</title>
<para>A wiki is a simple set of web pages to allow many users to
share information and collaborate on any sort of documents.
<ulink url="http://twiki.org">Twiki</ulink> is a wiki fine-tuned for
<link xlink:href="http://twiki.org">Twiki</link> is a wiki fine-tuned for
document management. It has built-in version control and
security implemented at the user/password level. I used it
for requirements management and traceability.</para>
@ -220,7 +213,7 @@
the power of a unified system like &os;.</para>
</sect2>
<sect2 id="freebsd-frisbee">
<sect2 xml:id="freebsd-frisbee">
<title>&os; For Disk Imaging: Frisbee</title>
<para>A disk imaging system is a mechanism for saving and
@ -280,13 +273,12 @@
developers or managers.</para>
</sect2>
<sect2 id="freebsd-nessus">
<sect2 xml:id="freebsd-nessus">
<title>&os; Security Testing: &nessus;</title>
<para>Whenever you have more than one entity on a network, and
whenever you expose a server to the wider Internet, security
of the machine itself is always a concern. <ulink
url="http://www.nessus.org">&nessus;</ulink> is an Open Source
of the machine itself is always a concern. <link xlink:href="http://www.nessus.org">&nessus;</link> is an Open Source
remote vulnerability scanner for security and penetration
testing that consistently is rated among the top products of
its type throughout the security industry.</para>
@ -309,7 +301,7 @@
<application>NeWT</application>, <quote>Nessus on Windows Technology</quote>.</para>
</sect2>
<sect2 id="freebsd-network">
<sect2 xml:id="freebsd-network">
<title>&os; Network Tools</title>
<para>&os; is most widely used as a robust server platform.
@ -318,8 +310,7 @@
brief description of network diagnostic tools that I found
invaluable in testing in a networked environment.</para>
<para>From the name, one would assume that <ulink
url="http://www.ntop.org">ntop</ulink> emulates the functions of
<para>From the name, one would assume that <link xlink:href="http://www.ntop.org">ntop</link> emulates the functions of
the UNIX &man.top.1; command, but for the network
rather than for the local machine. Perhaps the first version
did; currently, <application>ntop</application> is capable of providing detailed
@ -344,7 +335,7 @@
host, over that port. Often it was a new build with a
bug.</para>
<para><ulink url="http://ettercap.sourceforge.net">Ettercap</ulink> is
<para><link xlink:href="http://ettercap.sourceforge.net">Ettercap</link> is
a tool for ARP poisoning which can also decipher passwords on
the fly and corrupt IP traffic by means of a Man In The Middle
(MITM) attack. However, I used <application>Ettercap</application> as a performance tool.
@ -396,7 +387,7 @@
</sect2>
</sect1>
<sect1 id="conclusion">
<sect1 xml:id="conclusion">
<title>Conclusion</title>
<para>I used tools from the &os.ports; in four