diff options
227 files changed, 47571 insertions, 34331 deletions
diff --git a/de_DE.ISO8859-1/books/handbook/basics/chapter.xml b/de_DE.ISO8859-1/books/handbook/basics/chapter.xml index 20c6598b89..014b90829a 100644 --- a/de_DE.ISO8859-1/books/handbook/basics/chapter.xml +++ b/de_DE.ISO8859-1/books/handbook/basics/chapter.xml @@ -4,8 +4,8 @@ The FreeBSD German Documentation Project $FreeBSD$ - $FreeBSDde: de-docproj/books/handbook/basics/chapter.xml,v 1.112 2012/02/16 20:26:02 bcr Exp $ - basiert auf: 1.159 + $FreeBSDde$ + basiert auf: r39631 --> <chapter id="basics"> @@ -2160,7 +2160,7 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse (ausgeschaltet, oder ein Netzwerkfehler), dann ist der Prozess nicht zu unterbrechen. Wenn der Prozess den Lesezugriff nach einem Timeout von typischerweise zwei Minuten aufgibt, - dann wir er beendet.</para> + dann wird er beendet.</para> </footnote>.</para> <para>Andere Signale, die Sie vielleicht verschicken wollen, sind diff --git a/de_DE.ISO8859-1/books/handbook/firewalls/chapter.xml b/de_DE.ISO8859-1/books/handbook/firewalls/chapter.xml index 2a0307233a..015b9b796d 100644 --- a/de_DE.ISO8859-1/books/handbook/firewalls/chapter.xml +++ b/de_DE.ISO8859-1/books/handbook/firewalls/chapter.xml @@ -464,8 +464,8 @@ pflog_flags="" # zusätzliche Parameter für den Start von pflogd </row> <row> - <entry><command>pfctl <option>-s</option> [ Regeln | NAT | - Zustand ]</command></entry> + <entry><command>pfctl <option>-s</option> [ rules | nat | + states ]</command></entry> <entry>Bericht über die Filterregeln, NAT-Regeln, oder Zustandstabellen</entry> </row> diff --git a/de_DE.ISO8859-1/htdocs/releases/index.xml b/de_DE.ISO8859-1/htdocs/releases/index.xml index baa7e07ee4..731b149f71 100644 --- a/de_DE.ISO8859-1/htdocs/releases/index.xml +++ b/de_DE.ISO8859-1/htdocs/releases/index.xml @@ -2,7 +2,7 @@ <!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN" "http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [ <!ENTITY dedate "$FreeBSDde$"> -<!ENTITY reference "basiert auf: r41873"> +<!ENTITY reference "basiert auf: r42928"> <!ENTITY title "Release Information"> ]> @@ -14,6 +14,7 @@ </head> <body class="navinclude.download"> + <img alt="FreeBSD Releases" src="&enbase;/gifs/releases.jpg" height="200" width="300" align="right" border="0"/> <p>Es gibt 2 Arten von &os;-Versionen: "Produktion" sowie "Produktion (alt)". Die ersteren sind am besten für @@ -49,7 +50,7 @@ <h3>Produktion</h3> - <p><b>Release &rel.current;</b> (Dezember 2012) <!--(&rel.current.date;) --> + <p><b>Release &rel.current;</b> (September 2013) <!--(&rel.current.date;) --> <em> <a href="&u.rel.announce;">Announcement</a> : <a href="&u.rel.notes;">Release Notes</a> : @@ -87,11 +88,37 @@ href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/current-stable.html#CURRENT">FreeBSD-CURRENT</a> sind ebenfalls verfügbar. Weitere Informationen finden Sie unter <a href="&base;/where.html">FreeBSD Bezugsquellen</a>.</p> -<!-- + <a name="prior-supported"></a> <h2>Alte, aber noch unterstützte Versionen</h2> ---> + + <ul> + <li><b>9.1</b> (Dezember 2012) + <em> + <a href="&enbase;/releases/9.1R/announce.html">Announcement</a>: + <a href="&enbase;/releases/9.1R/relnotes.html">Release Notes</a>: + <a href="&enbase;/releases/9.1R/installation.html">Installation + Instructions</a>: + <a href="&enbase;/releases/9.1R/hardware.html">Hardware Notes</a>: + <a href="&enbase;/releases/9.1R/readme.html">Readme</a>: + <a href="&enbase;/releases/9.1R/errata.html">Errata</a> + </em> + </li> + + <li><b>8.3</b> (April 2012) + <em> + <a href="&enbase;/releases/8.3R/announce.html">Announcement</a>: + <a href="&enbase;/releases/8.3R/relnotes.html">Release Notes</a>: + <a href="&enbase;/releases/8.3R/installation.html">Installation + Instructions</a>: + <a href="&enbase;/releases/8.3R/hardware.html">Hardware Notes</a>: + <a href="&enbase;/releases/8.3R/readme.html">Readme</a>: + <a href="&enbase;/releases/8.3R/errata.html">Errata</a> + </em> + </li> + </ul> + <a name="prior-unsupported"></a> <h2>Alte, nicht mehr unterstützte Versionen @@ -115,20 +142,8 @@ <a href="&enbase;/releases/9.0R/hardware.html">Hardware Notes</a>: <a href="&enbase;/releases/9.0R/readme.html">Readme</a>: <a href="&enbase;/releases/9.0R/errata.html">Errata</a> - </em> - </li> - - <li><b>8.3</b> (April 2012) - <em> - <a href="&enbase;/releases/8.3R/announce.html">Announcement</a>: - <a href="&enbase;/releases/8.3R/relnotes.html">Release Notes</a>: - <a href="&enbase;/releases/8.3R/installation.html">Installation - Instructions</a>: - <a href="&enbase;/releases/8.3R/hardware.html">Hardware Notes</a>: - <a href="&enbase;/releases/8.3R/readme.html">Readme</a>: - <a href="&enbase;/releases/8.3R/errata.html">Errata</a> - </em> - </li> + </em> + </li> <li><b>8.2</b> (Februar 2011) <em> diff --git a/de_DE.ISO8859-1/htdocs/where.xml b/de_DE.ISO8859-1/htdocs/where.xml index 61a9a4d655..a2ef16f53a 100644 --- a/de_DE.ISO8859-1/htdocs/where.xml +++ b/de_DE.ISO8859-1/htdocs/where.xml @@ -2,7 +2,7 @@ <!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN" "http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [ <!ENTITY dedate "$FreeBSDde$"> -<!ENTITY reference "basiert auf: r41269"> +<!ENTITY reference "basiert auf: r42767"> <!ENTITY title "FreeBSD Bezugsquellen"> <!ENTITY url.rel "ftp://ftp.FreeBSD.org/pub/FreeBSD/releases"> ]> @@ -69,10 +69,10 @@ <tr> <td colspan="2">FreeBSD &rel.current;-RELEASE</td> <td colspan="2"></td> - <td rowspan="5"><a href="&enbase;/releases/&rel.current;R/relnotes.html">[Lesen]</a></td> - <td rowspan="5"><a href="&enbase;/releases/&rel.current;R/hardware.html">[Lesen]</a></td> - <td rowspan="5"><a href="&enbase;/releases/&rel.current;R/installation.html">[Lesen]</a></td> - <td rowspan="5"><a href="&enbase;/releases/&rel.current;R/errata.html">[Lesen]</a></td> + <td rowspan="7"><a href="&enbase;/releases/&rel.current;R/relnotes.html">[Lesen]</a></td> + <td rowspan="7"><a href="&enbase;/releases/&rel.current;R/hardware.html">[Lesen]</a></td> + <td rowspan="7"><a href="&enbase;/releases/&rel.current;R/installation.html">[Lesen]</a></td> + <td rowspan="7"><a href="&enbase;/releases/&rel.current;R/errata.html">[Lesen]</a></td> </tr> <tr> <td></td> @@ -86,7 +86,6 @@ <td><a href="&url.rel;/i386/i386/&rel.current;-RELEASE">[Distribution]</a></td> <td><a href="&url.rel;/i386/i386/ISO-IMAGES/&rel.current;/">[ISO]</a></td> </tr> - <!-- <tr> <td></td> <td>ia64</td> @@ -99,7 +98,6 @@ <td><a href="&url.rel;/powerpc/powerpc/&rel.current;-RELEASE">[Distribution]</a></td> <td><a href="&url.rel;/powerpc/powerpc/ISO-IMAGES/&rel.current;/">[ISO]</a></td> </tr> - --> <tr> <td></td> <td>powerpc64</td> diff --git a/de_DE.ISO8859-1/share/xml/news.xml b/de_DE.ISO8859-1/share/xml/news.xml index e69075e12d..b6f1c4648d 100644 --- a/de_DE.ISO8859-1/share/xml/news.xml +++ b/de_DE.ISO8859-1/share/xml/news.xml @@ -4,7 +4,7 @@ <!-- $FreeBSD$ $FreeBSDde$ - basiert auf: r42507 + basiert auf: r43081 --> <!-- Simple schema for FreeBSD Project news. @@ -39,9 +39,231 @@ <name>2013</name> <month> + <name>10</name> + + <day> + <name>30</name> + + <event> + <title>Offizielle Binärpakete für Pkg verfügbar</title> + + <p>Offizielle Binärpakete sind ab sofort für die &os;-Versionen + 8.3, 8.4, 9.1, 9.2, 10.0 sowie head verfügbar. Lesen Sie + bitte die offizielle <a + href="&lists.pkg;/2013-October/000107.html">Ankündigung</a> + für weitere Informationen.</p> + </event> + </day> + + <day> + <name>28</name> + + <event> + <title>&os; 10.0-BETA2 verfügbar</title> + + <p>Die zweite BETA-Version aus dem &os;-10.0-Releasezyklus ist nun + <a href="&lists.stable;/2013-October/075591.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>20</name> + + <event> + <title>Statusreport Juli-September 2013</title> + + <p>Der Statusreport für die Monate Juli bis September 2013 + mit 30 Einträgen ist ab sofort <a + href="&enbase;/news/status/report-2013-07-2013-09.html">verfügbar</a>.</p> + </event> + </day> + + <day> + <name>14</name> + + <event> + <title>&os; 10.0-BETA1 verfügbar</title> + + <p>Die erste BETA-Version aus dem &os;-10.0-Releasezyklus ist nun + <a href="&lists.stable;/2013-October/075504.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>9</name> + + <event> + <p>Neuer Committer: <a + href="mailto:edavis@FreeBSD.org">Eric Davis</a> (src)</p> + </event> + </day> + + <day> + <name>7</name> + + <event> + <title>&os; 10.0-ALPHA5 verfügbar</title> + + <p>Die fünfte ALPHA-Version aus dem &os;-10.0-Releasezyklus ist + <a href="&lists.current;/2013-October/045097.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + </month> + + <month> + <name>9</name> + + <day> + <name>30</name> + + <event> + <title>&os; 9.2-RELEASE verfügbar</title> + + <p><a href="&enbase;/releases/9.2R/announce.html">&os; + 9.2-RELEASE</a> ist verfügbar. Lesen Sie unbedingt + die <a + href="&enbase;/releases/9.2R/relnotes.html">Release Notes</a> + sowie die <a + href="&enbase;/releases/9.2R/errata.html">Release Errata</a>, + bevor Sie mit der Installation beginnen, um + sich über aktuelle Neuigkeiten und/oder eventuelle + Probleme im Umgang mit 9.2-RELEASE zu informieren. + Weitere Informationen zu verschiedenen FreeBSD-Versionen + finden Sie auf der Seite <a + href="&base;/releases/index.html">Release Information</a>.</p> + </event> + </day> + + <day> + <name>29</name> + + <event> + <title>&os; 10.0-ALPHA4 verfügbar</title> + + <p>Die vierte ALPHA-Version aus dem &os;-10.0-Releasezyklus ist + <a href="&lists.current;/2013-September/044951.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc + sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>23</name> + + <event> + <p>Neuer Committer: <a + href="mailto:danilo@FreeBSD.org">Danilo Egêa Gondolfo</a> (ports)</p> + </event> + </day> + + <day> + <name>18</name> + + <event> + <title>&os; 10.0-ALPHA2 verfügbar</title> + + <p>Die zweite ALPHA-Version aus dem &os;-10.0-Releasezyklus ist + <a href="&lists.current;/2013-September/044676.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc + sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>13</name> + + <event> + <title>&os; 10.0-ALPHA1 verfügbar</title> + + <p>Die erste ALPHA-Version aus dem &os;-10.0-Releasezyklus ist + <a href="&lists.current;/2013-September/044522.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc + sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>12</name> + + <event> + <title>&os; 9.2-RC4 verfügbar</title> + + <p>Der vierte Release Candidate aus dem &os;-9.2 Releasezyklus ist + <a href="&lists.stable;/2013-September/075163.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>2</name> + + <event> + <p>Neuer Committer: <a + href="mailto:br@FreeBSD.org">Ruslan Bukin</a> (src)</p> + </event> + + <event> + <p>Neuer Committer: <a + href="mailto:zbb@FreeBSD.org">Zbigniew Bodek</a> (src)</p> + </event> + </day> + </month> + + <month> <name>8</name> <day> + <name>26</name> + + <event> + <title>&os; 9.2-RC3 verfügbar</title> + + <p>Der dritte Release Candidate aus dem &os;-9.2 Releasezyklus ist + <a href="&lists.stable;/2013-August/074920.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> + <name>16</name> + + <event> + <title>&os; 9.2-RC2 verfügbar</title> + + <p>Der zweite Release Candidate aus dem &os;-9.2 Releasezyklus ist + <a href="&lists.stable;/2013-August/074756.html">verfügbar</a>. + ISO-Images für die Architekturen amd64, i386, ia64, powerpc, + powerpc64 sowie sparc64 sind inzwischen auf den meisten <a + href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/mirrors-ftp.html">&os; + Spiegelservern</a> vorhanden.</p> + </event> + </day> + + <day> <name>6</name> <event> @@ -87,6 +309,15 @@ <name>7</name> <day> + <name>31</name> + + <event> + <p>Neuer Committer: <a + href="mailto:nemysis@FreeBSD.org">Rusmir Dusko</a> (ports)</p> + </event> + </day> + + <day> <name>29</name> <event> diff --git a/de_DE.ISO8859-1/share/xml/release.l10n.ent b/de_DE.ISO8859-1/share/xml/release.l10n.ent index 4c408cb638..006ea7b606 100644 --- a/de_DE.ISO8859-1/share/xml/release.l10n.ent +++ b/de_DE.ISO8859-1/share/xml/release.l10n.ent @@ -2,7 +2,7 @@ <!-- $FreeBSD$ $FreeBSDde$ - basiert auf: r42493 + basiert auf: r42658 --> <![%beta2.testing;[ <!ENTITY beta.plural 'en'> @@ -18,15 +18,15 @@ <td>Distribution</td> <td title="ISO9660 CD image"><a href="&enbase;/doc/de_DE.ISO8859-1/books/handbook/install-diff-media.html#install-cdrom">ISO</a></td> - <td>Statusseite</td> + <!--<td>Statusseite</td>--> </tr> </thead> <tbody> <tr> <td colspan="2">FreeBSD &betarel2.current;-&betarel2.vers;</td> - <td colspan="2"></td> - <td rowspan="7"><a href="http://wiki.freebsd.org/Releng/7.4TODO">[Lesen]</a></td> - + <td colspan="2"></td> + <!--<td><a href="&base;/releases/&betarel2.current;R/todo.html">[View]</a></td>--> + <!--<td rowspan="7"><a href="http://wiki.freebsd.org/Releng/7.4TODO">[Lesen]</a></td>--> </tr> <tr> <td></td> @@ -52,12 +52,14 @@ <td><a href="&url.rel;/powerpc/powerpc/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td> <td><a href="&url.rel;/powerpc/powerpc/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td> </tr> + <!-- <tr> <td></td> <td>powerpc64</td> <td><a href="&url.rel;/powerpc/powerpc64/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td> <td><a href="&url.rel;/powerpc/powerpc64/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td> </tr> + --> <tr> <td></td> <td>sparc64</td> diff --git a/el_GR.ISO8859-7/share/xml/teams.ent b/el_GR.ISO8859-7/share/xml/teams.ent index f69510c5d7..d234d8468b 100644 --- a/el_GR.ISO8859-7/share/xml/teams.ent +++ b/el_GR.ISO8859-7/share/xml/teams.ent @@ -61,3 +61,5 @@ <!ENTITY a.re "ÏìÜäá ÏñãÜíùóçò ôùí Åêäüóåùí <email xmlns='http://docbook.org/ns/docbook'>re@FreeBSD.org</email>"> <!ENTITY a.security-officer "ÏìÜäá ÁóöÜëåéáò <email xmlns='http://docbook.org/ns/docbook'>security-officer@FreeBSD.org</email>"> + +<!ENTITY a.secteam-secretary "Security Team Secretary <email xmlns='http://docbook.org/ns/docbook'>secteam-secretary@FreeBSD.org</email>"> diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml index fcf74d2279..5f93df96ba 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.xml +++ b/en_US.ISO8859-1/articles/committers-guide/article.xml @@ -145,6 +145,7 @@ <entry> <literal>stable/8</literal> (8.X-STABLE), <literal>stable/9</literal> (9.X-STABLE), + <literal>stable/10</literal> (10.X-STABLE), <literal>head</literal> (-CURRENT)</entry> </row> </tbody> @@ -1567,7 +1568,7 @@ U stable/9/share/man/man4/netmap.4 contain the original version tags. To do this:</para> <screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput> -&prompt.root; <userinput>svn commit</userinput></screen> +&prompt.user; <userinput>svn commit</userinput></screen> </sect5> <sect5> @@ -2346,6 +2347,45 @@ ControlPersist yes</screen> will review code.</para> </sect1> + <sect1 id="if-in-doubt"> + <title>If in doubt...</title> + + <para>When you are not sure about something, whether it be a + technical issue or a project convention be sure to ask. If you + stay silent you will never make progress.</para> + + <para>If it relates to a technical issue ask on the public + mailing lists. Avoid the temptation to email the individual + person that knows the answer. This way everyone will be able to + learn from the question and the answer.</para> + + <para>For project specific or administrative questions you should + ask, in order: </para> + + <itemizedlist> + <listitem> + <para>Your mentor or former mentor.</para> + </listitem> + + <listitem> + <para>An experienced committer on IRC, email, etc.</para> + </listitem> + + <listitem> + <para>Any team with a "hat", as they should give you a + definitive answer.</para> + </listitem> + + <listitem> + <para>If still not sure, ask on &a.developers;.</para> + </listitem> + </itemizedlist> + + <para>Once your question is answered, if no one pointed you to + documentation that spelled out the answer to your question, + document it, as others will have the same question.</para> + </sect1> + <sect1 id="gnats"> <title>GNATS</title> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml index a7f778cb6e..a99cb74711 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml @@ -529,6 +529,11 @@ </listitem> <listitem> + <para>Allan Jude + <email>freebsd@allanjude.com</email></para> + </listitem> + + <listitem> <para>Allan Saddi <email>asaddi@philosophysw.com</email></para> </listitem> @@ -2129,11 +2134,6 @@ </listitem> <listitem> - <para>Danilo Egêa Gondolfo - <email>danilogondolfo@gmail.com</email></para> - </listitem> - - <listitem> <para>Danny Braniss <email>danny@cs.huji.ac.il</email></para> </listitem> @@ -3960,6 +3960,11 @@ </listitem> <listitem> + <para>Horia Racoviceanu + <email>horia@racoviceanu.com</email></para> + </listitem> + + <listitem> <para>Horihiro Kumagai <email>kuma@jp.FreeBSD.org</email></para> </listitem> @@ -4856,6 +4861,11 @@ </listitem> <listitem> + <para>Johannes Meixner + <email>xmj@chaot.net</email></para> + </listitem> + + <listitem> <para>Johannes Stille</para> </listitem> @@ -7630,11 +7640,6 @@ <listitem> <para>No Name - <email>nemysis@gmx.ch</email></para> - </listitem> - - <listitem> - <para>No Name <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para> </listitem> @@ -10872,6 +10877,11 @@ </listitem> <listitem> + <para>Xiaoding Liu + <email>xiaoding+freebsd@xiaoding.org</email></para> + </listitem> + + <listitem> <para>Yamagi Burmeister <email>yamagi@yamagi.org</email></para> </listitem> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml index 27a6851deb..011458eae1 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml @@ -116,6 +116,10 @@ </listitem> <listitem> + <para>&a.zbb.email;</para> + </listitem> + + <listitem> <para>&a.novel.email;</para> </listitem> @@ -156,6 +160,10 @@ </listitem> <listitem> + <para>&a.br.email;</para> + </listitem> + + <listitem> <para>&a.oleg.email;</para> </listitem> @@ -244,6 +252,10 @@ </listitem> <listitem> + <para>&a.edavis.email;</para> + </listitem> + + <listitem> <para>&a.pjd.email;</para> </listitem> @@ -284,6 +296,10 @@ </listitem> <listitem> + <para>&a.nemysis.email;</para> + </listitem> + + <listitem> <para>&a.deischen.email;</para> </listitem> @@ -400,6 +416,10 @@ </listitem> <listitem> + <para>&a.danilo.email;</para> + </listitem> + + <listitem> <para>&a.daichi.email;</para> </listitem> @@ -840,6 +860,10 @@ </listitem> <listitem> + <para>&a.jmmv.email;</para> + </listitem> + + <listitem> <para>&a.ken.email;</para> </listitem> diff --git a/en_US.ISO8859-1/articles/linux-comparison/article.xml b/en_US.ISO8859-1/articles/linux-comparison/article.xml index 3d24209113..4e48dfcc31 100644 --- a/en_US.ISO8859-1/articles/linux-comparison/article.xml +++ b/en_US.ISO8859-1/articles/linux-comparison/article.xml @@ -182,7 +182,6 @@ Copyright (c) 2005 Dru Lavigne &os; also supports the following architectures:</para> <itemizedlist> - <listitem><simpara>alpha</simpara></listitem> <listitem><simpara>amd64</simpara></listitem> <listitem><simpara>ia64</simpara></listitem> <listitem><simpara>&i386;</simpara></listitem> diff --git a/en_US.ISO8859-1/books/dev-model/book.xml b/en_US.ISO8859-1/books/dev-model/book.xml index 607d0f2b8d..91f3e6b981 100644 --- a/en_US.ISO8859-1/books/dev-model/book.xml +++ b/en_US.ISO8859-1/books/dev-model/book.xml @@ -46,6 +46,12 @@ </copyright> <revhistory> <revision> + <revnumber>1.4</revnumber> + <date>September, 2013</date> + <revremark>Remove mention of CVS and CVSup which are no + longer used by the project.</revremark> + </revision> + <revision> <revnumber>1.3</revnumber> <date>October, 2012</date> <revremark>Remove hats held by specific people, these @@ -896,22 +902,6 @@ </para> </section> - <section id="role-cvsup-coordinator" xreflabel="CVSup Mirror Site Coordinator"> - <title>CVSup Mirror Site Coordinator</title> - <para> - The CVSup Mirror Site Coordinator coordinates all the - <xref linkend="role-cvsup-sitemaint"/>s to ensure that they - are distributing current versions of the software, that they - have the capacity to update themselves when major updates - are in progress, and making it easy for the general public - to find their closest CVSup mirror. - </para> - <para> - Hat currently held by: - The CVSup-master team <email>cvsup-master@FreeBSD.org</email>. - </para> - </section> - <section id="role-postmaster" xreflabel="Postmaster"> <title>Postmaster</title> <para> @@ -1030,11 +1020,11 @@ responsibility to ensure that technical problems that arise in the repository are resolved quickly. The source repository manager has the authority to back out commits if this is - necessary to resolve a CVS technical problem. + necessary to resolve a SVN technical problem. </para> <para> Hat held by: - the Source Repository Manager <email>cvs@FreeBSD.org</email>. + the Source Repository Manager <email>clusteradm@FreeBSD.org</email>. </para> </section> @@ -1240,20 +1230,6 @@ for review is posted. </para> </section> - - <section id="role-cvsup-sitemaint" xreflabel="CVSup Mirror Site - Admin"> - <title>CVSup Mirror Site Admin</title> - <para> - A CVSup Mirror Site Admin has accesses to a server that he/she - uses to mirror the CVS repository. The admin works with the - <xref linkend="role-cvsup-coordinator"/> to ensure the site - remains up-to-date and is following the general policy of - official mirror sites. - </para> - </section> - - </section> @@ -1402,93 +1378,6 @@ </section> - <section id="process-cvsupmirror" xreflabel="Adding an official - CVSup Mirror"> - <title>Adding/Removing an official CVSup Mirror</title> - - <para> - A <xref linkend="tool-cvsup"/> mirror is a replica of the - official CVSup master that contains all the up-to-date source - code for all the branches in the FreeBSD project, ports and - documentation. - </para> - - <para> - Adding an official CVSup mirror starts with the potential - <xref linkend="role-cvsup-sitemaint"/> installing the - <quote>cvsup-mirror</quote> package. Having done this and - updated the source code with a mirror site, he now runs a - fairly recent unofficial CVSup mirror. - </para> - - <para> - Deciding he has a stable environment, the processing - power, the network capacity and the - storage capacity to run an official mirror, he mails the - <xref linkend="role-cvsup-coordinator"/> who decides whether - the mirror should become an official mirror or not. - </para> - - <para> - In making this decision, the <xref linkend="role-cvsup-coordinator"/> - has to determine whether that geographical area needs - another mirror site, if the mirror administrator has the - skills to run it reliably, if the network bandwidth is - adequate and if the master server has the capacity to server - another mirror. - </para> - - <para> - If <xref linkend="role-cvsup-coordinator"/> decides that the - mirror should become an official mirror, he obtains an - authentication key from the mirror admin that he installs so - the mirror admin can update the mirror from the master server. - </para> - - <para> - <figure> - <title>Process summary: adding a CVSup mirror</title> - <graphic fileref="proc-add-cvsup"/> - </figure> - </para> - - <para> - When a CVSup mirror administrator of an unofficial mirror - offers to become an official mirror site, the CVSup - coordinator decides if another mirror is needed and if - there is sufficient capacity to accommodate it. If so, - an authorisation key is requested and the mirror is given - access to the main distribution site and added to the - list of official mirrors. - </para> - - - <para> - Tools used in this process: - <itemizedlist> - <listitem><para> - <xref linkend="tool-cvsup"/> - </para></listitem> - <listitem><para> - <xref linkend="tool-ssh2"/> - </para></listitem> - </itemizedlist> - </para> - - <para> - Hats involved in this process: - <itemizedlist> - <listitem><para> - <xref linkend="role-cvsup-coordinator"/> - </para></listitem> - <listitem><para> - <xref linkend="role-cvsup-sitemaint"/> - </para></listitem> - </itemizedlist> - </para> - - </section> - <section id="committing"> <title>Committing code</title> @@ -2183,9 +2072,8 @@ <para> The major support tools for supporting the development process are - CVS, CVSup, Perforce, GNATS, Mailman and OpenSSH. Except for - CVSup, these are externally - developed tools. These tools are commonly used in the open source world. + Perforce, GNATS, Mailman and OpenSSH. These are externally + developed tools and are commonly used in the open source world. </para> <section id="tool-svn" xreflabel="SVN"> @@ -2198,18 +2086,6 @@ </para> </section> - <section id="tool-cvsup" xreflabel="CVSup"> - <title>CVSup</title> - <para> - CVSup is a software package for distributing and updating - collections of files across a network. It consists of a - client program, cvsup, and a server program, cvsupd. The - package is tailored specifically for distributing CVS - repositories, and by taking advantage of CVS' properties, it - performs updates much faster than traditional systems. - </para> - </section> - <section id="tool-gnats" xreflabel="GNATS"> <title>GNATS</title> <para> diff --git a/en_US.ISO8859-1/books/developers-handbook/book.xml b/en_US.ISO8859-1/books/developers-handbook/book.xml index 6a9a7f220c..622e745d64 100644 --- a/en_US.ISO8859-1/books/developers-handbook/book.xml +++ b/en_US.ISO8859-1/books/developers-handbook/book.xml @@ -16,7 +16,7 @@ <corpauthor>The FreeBSD Documentation Project</corpauthor> - <pubdate>August 2000</pubdate> + <pubdate>$FreeBSD$</pubdate> <copyright> <year>2000</year> @@ -30,6 +30,9 @@ <year>2008</year> <year>2009</year> <year>2010</year> + <year>2011</year> + <year>2012</year> + <year>2013</year> <holder>The FreeBSD Documentation Project</holder> </copyright> diff --git a/en_US.ISO8859-1/books/faq/book.xml b/en_US.ISO8859-1/books/faq/book.xml index d72d9afc3f..886c6b2f43 100644 --- a/en_US.ISO8859-1/books/faq/book.xml +++ b/en_US.ISO8859-1/books/faq/book.xml @@ -2,18 +2,19 @@ <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" "../../../share/xml/freebsd45.dtd" [ <!ENTITY bibliography SYSTEM "../../../share/xml/bibliography.xml"> +<!ENTITY rel.numbranch "3"> <!-- number of branches that follow in this list --> <!ENTITY rel.head "<emphasis xmlns='http://docbook.org/ns/docbook'>10-CURRENT</emphasis>"> <!ENTITY rel.head.relx "10.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> -<!ENTITY rel.head.releng "<symbol xmlns='http://docbook.org/ns/docbook'>HEAD</symbol>"> +<!ENTITY rel.head.releng "<symbol xmlns='http://docbook.org/ns/docbook'>head/</symbol>"> <!ENTITY rel.head.packages "packages-10-current"> <!ENTITY rel.relx "9.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> <!ENTITY rel.stable "<emphasis xmlns='http://docbook.org/ns/docbook'>9-STABLE</emphasis>"> -<!ENTITY rel.releng "<symbol xmlns='http://docbook.org/ns/docbook'>RELENG_9</symbol>"> +<!ENTITY rel.releng "<symbol xmlns='http://docbook.org/ns/docbook'>stable/9/</symbol>"> <!ENTITY rel.relengdate "September 2011"> <!ENTITY rel.packages "packages-9-stable"> <!ENTITY rel2.relx "8.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> <!ENTITY rel2.stable "<emphasis xmlns='http://docbook.org/ns/docbook'>8-STABLE</emphasis>"> -<!ENTITY rel2.releng "<symbol xmlns='http://docbook.org/ns/docbook'>RELENG_8</symbol>"> +<!ENTITY rel2.releng "<symbol xmlns='http://docbook.org/ns/docbook'>stable/8/</symbol>"> <!ENTITY rel2.relengdate "August 2009"> <!ENTITY rel2.packages "packages-8-stable"> ]> @@ -964,7 +965,7 @@ </listitem> <listitem> - <para>Channel <literal>##FreeBSD</literal> on <ulink + <para>Channel <literal>#FreeBSD</literal> on <ulink url="http://freenode.net/">Freenode</ulink> is a general help channel with many users at any time. The conversations have been known to run off-topic for a @@ -5238,9 +5239,12 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> </question> <answer> - <para>Run the command <command>xmodmap -e "pointer = 3 2 1"</command> - from <filename>.xinitrc</filename> or - <filename>.xsession</filename>.</para> + <para>Run the command + <command>xmodmap -e "pointer = 3 2 1"</command>.</para> + <para>You add the above command to + <filename>.xinitrc</filename> or + <filename>.xsession</filename> to make it happen + automatically.</para> </answer> </qandaentry> @@ -7233,7 +7237,7 @@ hint.sio.7.irq="12"</programlisting> <qandaset> <qandaentry> <question id="more-swap"> - <para>&os; a lot of swap space even when the computer has + <para>&os; uses a lot of swap space even when the computer has free memory left. Why?</para> </question> @@ -7887,11 +7891,11 @@ hint.sio.7.irq="12"</programlisting> </question> <answer> - <para>There are currently four active/semi-active branches in + <para>There are currently &rel.numbranch; active/semi-active branches in the &os; <ulink url="http://svnweb.FreeBSD.org/base/">Subversion Repository</ulink>. (Earlier branches are only changed very rarely, which is why - there are only four active branches of development):</para> + there are only &rel.numbranch; active branches of development):</para> <itemizedlist> <listitem> diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile index cd17a0100c..fa7ad27323 100644 --- a/en_US.ISO8859-1/books/handbook/Makefile +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -273,7 +273,6 @@ SRCS+= preface/preface.xml SRCS+= printing/chapter.xml SRCS+= security/chapter.xml SRCS+= serialcomms/chapter.xml -SRCS+= users/chapter.xml SRCS+= virtualization/chapter.xml SRCS+= x11/chapter.xml diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml index 26dba92958..5ed0a17bdd 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml @@ -4468,7 +4468,7 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro option subnet-mask 255.255.255.0 ; option routers 192.168.0.1 ; option broadcast-address 192.168.0.255 ; - option domain-name-server 192.168.35.35, 192.168.35.36 ; + option domain-name-servers 192.168.35.35, 192.168.35.36 ; option domain-name "example.com"; # IP address of TFTP server @@ -5021,17 +5021,25 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <itemizedlist> <listitem> - <para>Running out of addresses. Today this is not so much of - a concern, since RFC1918 private address space (<hostid - role="ipaddr">10.0.0.0/8</hostid>, <hostid - role="ipaddr">172.16.0.0/12</hostid>, and <hostid - role="ipaddr">192.168.0.0/16</hostid>) and - <acronym>NAT</acronym> are being employed.</para> + <para>Running out of addresses. For years the use of + RFC1918 private address space + (<hostid role="ipaddr">10.0.0.0/8</hostid>, + <hostid role="ipaddr">172.16.0.0/12</hostid>, and + <hostid role="ipaddr">192.168.0.0/16</hostid>) and NAT + has slowed down the exhaustion. Even though, there are + very few remaining IPv4 addresses. The Internet + Assigned Numbers Authority (<acronym>IANA</acronym>) has + issued the last of the available major blocks to the + Regional Registries. Once each Regional Registry runs + out, there will be no more available and switching to + <acronym>IPv6</acronym> will be critical.</para> </listitem> <listitem> - <para>Router table entries were getting too large. This is - still a concern today.</para> + <para>Every block of IPv4 addresses allocated required + routing information to be exchanged between many routers + on the Internet, and these routing tables were getting + too large to allow efficient routing.</para> </listitem> </itemizedlist> @@ -5054,7 +5062,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </listitem> </itemizedlist> - <para>There are other useful features of + <para>There are many other useful features of <acronym>IPv6</acronym>:</para> <itemizedlist> @@ -5280,6 +5288,12 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para><ulink url="http://www.sixxs.net">SixXS</ulink> offers tunnels with end-points all around the globe.</para> </listitem> + + <listitem> + <para><ulink url="http://www.tunnelbroker.net">Hurricane + Electric</ulink> offers tunnels with end-points all around + the globe.</para> + </listitem> <listitem> <para>Tunnel via 6-to-4 as described in <ulink @@ -5295,53 +5309,44 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </sect2> <sect2> - <title><acronym>DNS</acronym> in the <acronym>IPv6</acronym> - World</title> - - <para>There used to be two types of <acronym>DNS</acronym> - records for <acronym>IPv6</acronym>. The - <acronym>IETF</acronym> has declared <acronym>AAAA</acronym> - records as the current standard.</para> - - <para>Using <acronym>AAAA</acronym> records is straightforward. - Assign the hostname to the <acronym>IPv6</acronym> address - in the primary zone <acronym>DNS</acronym> file:</para> - - <programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting> - - <para>Current versions of &man.named.8; and <filename - role="package">dns/djbdns</filename> support - <acronym>AAAA</acronym> records.</para> - </sect2> - - <sect2> <title>Applying the Needed Changes to <filename>/etc/rc.conf</filename></title> <sect3> - <title><acronym>IPv6</acronym> Client Settings</title> + <title><acronym>IPv6</acronym> Client + Auto-Configuration</title> - <para>These settings configure a machine on a + <para>To automatically configure a machine on a <acronym>LAN</acronym> which acts as a client, not a - router. To instruct &man.rtsol.8; to autoconfigure the - interface on boot on - &os; 9.<replaceable>x</replaceable> and later, add - this line to <filename>rc.conf</filename>:</para> - - <programlisting>ipv6_prefer="YES"</programlisting> + router, two items are required. First to enable the + <devicename>em0</devicename> to receive the router + solicitation messages, add this line to + <filename>rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>em0</replaceable>_ipv6="inet6 accept_rtadv"</programlisting> + + <para>Secondly, the router solicitation daemon, &man.rtsol.8;, + should be enabled by adding the following to + <filename>rc.conf</filename>:</para> + + <programlisting>rtsold_enable="YES"</programlisting> <para>For &os; 8.<replaceable>x</replaceable>, add:</para> <programlisting>ipv6_enable="YES"</programlisting> + </sect3> + <sect3> + <title><acronym>IPv6</acronym> Client Static + Configuration</title> <para>To statically assign the <acronym>IPv6</acronym> address, <hostid - role="ip6addr">2001:471:1f11:251:290:27ff:fee0:2093</hostid>, + role="ip6addr">2001:db8:4672:6565:2026:5043:2d42:5344</hostid>, to <devicename>fxp0</devicename>, add the following for &os; 9.<replaceable>x</replaceable>:</para> - <programlisting>ifconfig_fxp0_ipv6="inet6 2001:471:1f11:251:290:27ff:fee0:2093 prefixlen <replaceable>64</replaceable>"</programlisting> + <programlisting>ifconfig_<replaceable>fxp0</replaceable>_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64"</programlisting> <note> <para>Be sure to change <replaceable>prefixlen @@ -5349,16 +5354,16 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> subnet.</para> </note> - <para>For &os; 8<replaceable>x</replaceable>, + <para>For &os; 8.<replaceable>x</replaceable>, add:</para> - <programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting> + <programlisting>ipv6_ifconfig_<replaceable>fxp0</replaceable>="2001:db8:4672:6565:2026:5043:2d42:5344"</programlisting> <para>To assign a default router of <hostid - role="ip6addr">2001:471:1f11:251::1</hostid>, add the + role="ip6addr">2001:db8:4672:6565::1</hostid>, add the following to <filename>/etc/rc.conf</filename>:</para> - <programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting> + <programlisting>ipv6_defaultrouter="2001:db8:4672:6565::1"</programlisting> </sect3> <sect3> @@ -5372,9 +5377,9 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para>The first entry lists the generic tunneling interfaces to be configured. This example configures one interface, - <devicename>gif0</devicename>:</para> + <devicename>gif<replaceable>0</replaceable></devicename>:</para> - <programlisting>gif_interfaces="gif0"</programlisting> + <programlisting>gif_interfaces="gif<replaceable>0</replaceable>"</programlisting> <para>To configure that interface with a local endpoint of <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint @@ -5476,6 +5481,23 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> section 3.6 and 3.7 as well as <acronym>RFC</acronym> 4038 section 4.2 may be useful to some adminstrators.</para> </sect2> + + <sect2> + <title>Application Use of <acronym>IPv6</acronym></title> + + <para>Currently <acronym>IPv6</acronym> support for many + applications and services is very good, though for some + software it still needs work. For authoritative + information about the support of + <acronym>IPv6</acronym>, please consult the Official + Documentation for the software in question.</para> + + <para>Web, <acronym>DNS</acronym> and Mail applications + and servers have the best support for + <acronym>IPv6</acronym> because they are the most common + use case. Other applications may have varying degrees + of <acronym>IPv6</acronym> support.</para> + </sect2> </sect1> <sect1 id="network-atm"> diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.xml b/en_US.ISO8859-1/books/handbook/basics/chapter.xml index d9dd5a98eb..2e5a055f62 100644 --- a/en_US.ISO8859-1/books/handbook/basics/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/basics/chapter.xml @@ -6,16 +6,17 @@ --> <chapter id="basics"> + <!-- <chapterinfo> <authorgroup> <author> <firstname>Chris</firstname> <surname>Shumway</surname> - <contrib>Rewritten by </contrib> + <contrib>Rewritten by in Mar 2000</contrib> </author> </authorgroup> - <!-- 10 Mar 2000 --> </chapterinfo> + --> <title>UNIX Basics</title> @@ -31,7 +32,11 @@ <itemizedlist> <listitem> - <para>How to use the <quote>virtual consoles</quote> of + <para>How to use and configure virtual consoles.</para> + </listitem> + + <listitem> + <para>How to create and manage users and groups on &os;.</para> </listitem> @@ -70,10 +75,6 @@ </listitem> <listitem> - <para>What binary format is used under &os;.</para> - </listitem> - - <listitem> <para>How to read manual pages for more information.</para> </listitem> </itemizedlist> @@ -84,128 +85,99 @@ <indexterm><primary>virtual consoles</primary></indexterm> <indexterm><primary>terminals</primary></indexterm> + <indexterm><primary>console</primary></indexterm> - <para>&os; can be used in various ways. One of them is typing - commands to a text terminal. A lot of the flexibility and power - of a &unix; operating system is readily available when using - &os; this way. This section describes what - <quote>terminals</quote> and <quote>consoles</quote> are, and - how to use them in &os;.</para> + <para>Unless &os; has been configured to automatically start a + graphical environment during startup, the system will boot + into a command line login prompt, as seen in this + example:</para> - <sect2 id="consoles-intro"> - <title>The Console</title> - - <indexterm><primary>console</primary></indexterm> - - <para>Unless &os; has been configured to automatically start - a graphical environment during startup, the system will boot - into a command line login prompt, as seen in this - example:</para> - - <screen>FreeBSD/amd64 (pc3.example.org) (ttyv0) + <screen>FreeBSD/amd64 (pc3.example.org) (ttyv0) login:</screen> - <para>The first line contains some information about the - system. The <literal>amd64</literal> indicates that the - system in this example is running a 64-bit version of &os;. - The hostname is <hostid>pc3.example.org</hostid>, and - <devicename>ttyv0</devicename> indicates that this is the - system console.</para> - - <para>The second line is the login prompt. The next section - describes how to log into &os; at this prompt.</para> - </sect2> - - <sect2 id="consoles-login"> - <title>Logging into &os;</title> - - <para>&os; is a multiuser, multiprocessing system. This is - the formal description that is usually given to a system that - can be used by many different people, who simultaneously run a - lot of programs on a single machine.</para> - - <para>Every multiuser system needs some way to distinguish one - <quote>user</quote> from the rest. In &os; (and all the - &unix;-like operating systems), this is accomplished by - requiring that every user must <quote>log into</quote> the - system before being able to run programs. Every user has a - unique name (the <quote>username</quote>) and a personal, - secret key (the <quote>password</quote>). &os; will ask - for these two before allowing a user to run any - programs.</para> - - <indexterm><primary>startup scripts</primary></indexterm> - <para>When a &os; system boots, startup scripts are - automatically executed in order to prepare the system and to - start any services which have been configured to start at - system boot. Once the system finishes running its startup - scripts, it will present a login prompt:</para> - - <screen>login:</screen> - - <para>Type the username that was configured during system - installation, as described in <xref - linkend="bsdinstall-addusers"/>, and press - <keycap>Enter</keycap>. Then enter the password associated - with the username and press <keycap>Enter</keycap>. The - password is <emphasis>not echoed</emphasis> for security - reasons.</para> - - <para>Once the correct password is input, the message of the - day (<acronym>MOTD</acronym>) will be displayed followed - by a command prompt (a <literal>#</literal>, - <literal>$</literal>, or <literal>%</literal> character). You - are now logged into the &os; console and ready to try the - available commands.</para> - </sect2> + <para>The first line contains some information about the system. + The <literal>amd64</literal> indicates that the system in this + example is running a 64-bit version of &os;. The hostname is + <hostid>pc3.example.org</hostid>, and + <devicename>ttyv0</devicename> indicates that this is the + <quote>system console</quote>. The second line is the login + prompt.</para> + + <para>Since &os; is a multiuser system, it needs some way to + distinguish between different users. This is accomplished by + requiring every user to log into the system before gaining + access to the programs on the system. Every user has a + unique name <quote>username</quote> and a personal + <quote>password</quote>.</para> + + <para>To log into the system console, type the username that + was configured during system installation, as described in + <xref linkend="bsdinstall-addusers"/>, and press + <keycap>Enter</keycap>. Then enter the password associated + with the username and press <keycap>Enter</keycap>. The + password is <emphasis>not echoed</emphasis> for security + reasons.</para> + + <para>Once the correct password is input, the message of the + day (<acronym>MOTD</acronym>) will be displayed followed + by a command prompt. Depending upon the shell that was + selected when the user was created, this prompt will be a + <literal>#</literal>, <literal>$</literal>, or + <literal>%</literal> character. The prompt indicates that + the user is now logged into the &os; system console and ready + to try the available commands.</para> <sect2 id="consoles-virtual"> <title>Virtual Consoles</title> - <para>&os; can be configured to provide many virtual consoles - for inputting commands. Each virtual console has its own - login prompt and output channel, and &os; takes care of - properly redirecting keyboard input and monitor output as - switching occurs between virtual consoles.</para> - - <para>Special key combinations have been reserved by &os; for - switching consoles.<footnote> - <para>Refer to &man.syscons.4;, &man.atkbd.4;, - &man.vidcontrol.1; and &man.kbdcontrol.1; for a more - technical description of the &os; console and its keyboard - drivers.</para></footnote>. Use - <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>, - <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, + <para>While the system console can be used to interact with + the system, a user working from the command line at the + keyboard of a &os; system will typically instead log into a + virtual console. This is because system messages are + configured by default to display on the system console. + These messages will appear over the command or file that the + user is working on, making it difficult to concentrate on + the work at hand.</para> + + <para>By default, &os; is configured to provide several virtual + consoles for inputting commands. Each virtual console has + its own login prompt and shell and it is easy to switch + between virtual consoles. This essentially provides the + command line equivalent of having several windows open at the + same time in a graphical environment.</para> + + <para>The key combinations + <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo> through <keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> - to switch to a different virtual console in &os;.</para> + have been reserved by &os; for switching between virtual + consoles. Use + <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo> + to switch to the system console + (<devicename>ttyv0</devicename>), + <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> + to access the first virtual console + (<devicename>ttyv1</devicename>), + <keycombo><keycap>Alt</keycap><keycap>F3</keycap></keycombo> + to access the second virtual console + (<devicename>ttyv2</devicename>), and so on.</para> <para>When switching from one console to the next, &os; takes - care of saving and restoring the screen output. The result is - an <quote>illusion</quote> of having multiple - <quote>virtual</quote> screens and keyboards that can be used + manages the screen output. The result is an illusion of + having multiple virtual screens and keyboards that can be used to type commands for &os; to run. The programs that are - launched in one virtual console do not stop running when that - console is not visible because the user has switched to a - different virtual console.</para> - </sect2> - - <sect2 id="consoles-ttys"> - <title>The <filename>/etc/ttys</filename> File</title> + launched in one virtual console do not stop running when + the user switches to a different virtual console.</para> - <para>By default, &os; is configured to start eight virtual - consoles. The configuration can be customized to start - more or fewer virtual consoles. To change the number of and - the settings of the virtual consoles, edit - <filename>/etc/ttys</filename>.</para> + <para>Refer to &man.syscons.4;, &man.atkbd.4;, + &man.vidcontrol.1; and &man.kbdcontrol.1; for a more + technical description of the &os; console and its keyboard + drivers.</para> - <para>Each uncommented line in <filename>/etc/ttys</filename> - (lines that do not start with a <literal>#</literal> - character) contains settings for a single terminal or virtual - console. The default version configures nine virtual - consoles, and enables eight of them. They are the lines that - start with <literal>ttyv</literal>:</para> + <para>In &os;, the number of available virtual consoles is + configured in this section of + <filename>/etc/ttys</filename>:</para> <programlisting># name getty type status comments # @@ -220,20 +192,47 @@ ttyv6 "/usr/libexec/getty Pc" cons25 on secure ttyv7 "/usr/libexec/getty Pc" cons25 on secure ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> + + <para>To disable a virtual console, put a comment symbol + (<literal>#</literal>) at the beginning of the line + representing that virtual console. For example, to reduce + the number of available virtual consoles from eight to four, + put a <literal>#</literal> in front of the last four lines + representing virtual consoles + <devicename>ttyv5</devicename> through + <devicename>ttyv8</devicename>. <emphasis>Do not</emphasis> + comment out the line for the system console + <devicename>ttyv0</devicename>. Note that the last virtual + console (<devicename>ttyv8</devicename>) is used to access + the graphical environment if <application>&xorg;</application> + has been installed and configured as described in <xref + linkend="x11"/>.</para> + <para>For a detailed description of every column in this file and the available options for the virtual consoles, refer to &man.ttys.5;.</para> </sect2> <sect2 id="consoles-singleuser"> - <title>Single User Mode Console</title> - - <para>A detailed description of <quote>single user mode</quote> - can be found in <xref linkend="boot-singleuser"/>. There is - only one console when &os; is in single user mode as no other - virtual consoles are available in this mode. The settings - for single user mode are found in this section of - <filename>/etc/ttys</filename>:</para> + <title>Single User Mode</title> + + <para>The &os; boot menu provides an option labelled as + <quote>Boot Single User</quote>. If this option is selected, + the system will boot into a special mode known as + <quote>single user mode</quote>. This mode is typically used + to repair a system that will not boot or to reset the + <username>root</username> password when it is not known. + While in single user mode, networking and other virtual + consoles are not available. However, full + <username>root</username> access to the system is available, + and by default, the <username>root</username> password is not + needed. For these reasons, physical access to the keyboard + is needed to boot into this mode and determining who has + physical access to the keyboard is something to consider when + securing a &os; system.</para> + + <para>The settings which control single user mode are found in + this section of <filename>/etc/ttys</filename>:</para> <programlisting># name getty type status comments # @@ -241,19 +240,23 @@ ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> # when going to single-user mode. console none unknown off secure</programlisting> - <note> - <para>As the comments above the <literal>console</literal> - line indicate, editing <literal>secure</literal> to - <literal>insecure</literal> will prompt for the - <username>root</username> password when booting into single - user mode. The default setting enters single user mode - without prompting for a password.</para> + <para>By default, the status is set to + <literal>secure</literal>. This assumes that who has + physical access to the keyboard is either not important or it + is controlled by a physical security policy. If this setting + is changed to <literal>insecure</literal>, the assumption is + that the environment itself is insecure because anyone can + access the keyboard. When this line is changed to + <literal>insecure</literal>, &os; will prompt for the + <username>root</username> password when a user selects to + boot into single user mode.</para> + <note> <para><emphasis>Be careful when changing this setting to - <literal>insecure</literal></emphasis>. If the + <literal>insecure</literal></emphasis>! If the <username>root</username> password is forgotten, booting into single user mode is still possible, but may be - difficult for someone who is not comfortable with the &os; + difficult for someone who is not familiar with the &os; booting process.</para> </note> </sect2> @@ -274,8 +277,8 @@ console none unknown off secure</programlisting> <screen>&prompt.root; <userinput>vidcontrol -i mode</userinput></screen> - <para>The output of this command lists the video modes that - are supported by the hardware. To select a new video mode, + <para>The output of this command lists the video modes that are + supported by the hardware. To select a new video mode, specify the mode using &man.vidcontrol.1; as the <username>root</username> user:</para> @@ -289,48 +292,1085 @@ console none unknown off secure</programlisting> </sect2> </sect1> - <sect1 id="permissions"> - <title>Permissions</title> + <!-- + <chapterinfo> + <authorgroup> + <author> + <firstname>Neil</firstname> + <surname>Blakey-Milner</surname> + <contrib>Contributed by in Feb 2000</contrib> + </author> + </authorgroup> + </chapterinfo> + --> - <indexterm><primary>UNIX</primary></indexterm> + <sect1 id="users-synopsis"> + <title>Users and Basic Account Management</title> + + <para>&os; allows multiple users to use the computer at the same + time. While only one user can sit in front of the screen and + use the keyboard at any one time, any number of users can log + in to the system through the network. To use the system, each + user should have their own user account.</para> + + <para>This chapter describes:</para> + + <itemizedlist> + <listitem> + <para>The different types of user accounts on a + &os; system.</para> + </listitem> + + <listitem> + <para>How to add, remove, and modify user accounts.</para> + </listitem> + + <listitem> + <para>How to set limits to control the + resources that users and + groups are allowed to access.</para> + </listitem> + + <listitem> + <para>How to create groups and add users as members of a + group.</para> + </listitem> + </itemizedlist> + + <sect2 id="users-introduction"> + <title>Account Types</title> + + <para>Since all access to the &os; system is achieved using + accounts and all processes are run by users, user and account + management is important.</para> + + <para>There are three main types of accounts: system accounts, + user accounts, and the superuser account.</para> + + <sect3 id="users-system"> + <title>System Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>system</secondary> + </indexterm> + + <para>System accounts are used to run services such as DNS, + mail, and web servers. The reason for this is security; if + all services ran as the superuser, they could act without + restriction.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><username>daemon</username></secondary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary><username>operator</username></secondary> + </indexterm> + + <para>Examples of system accounts are + <username>daemon</username>, <username>operator</username>, + <username>bind</username>, <username>news</username>, and + <username>www</username>.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><username>nobody</username></secondary> + </indexterm> + + <para><username>nobody</username> is the generic unprivileged + system account. However, the more services that use + <username>nobody</username>, the more files and processes + that user will become associated with, and hence the more + privileged that user becomes.</para> + </sect3> + + <sect3 id="users-user"> + <title>User Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>user</secondary> + </indexterm> + + <para>User accounts are assigned to real people and are used + to log in and use the system. Every person accessing the + system should have a unique user account. This allows the + administrator to find out who is doing what and prevents + users from clobbering the settings of other users.</para> + + <para>Each user can set up their own environment to + accommodate their use of the system, by configuring their + default shell, editor, key bindings, and language + settings.</para> + + <para>Every user account on a &os; system has certain + information associated with it:</para> + + <variablelist> + <varlistentry> + <term>User name</term> + + <listitem> + <para>The user name is typed at the <prompt>login:</prompt> + prompt. User names must be unique on the system as no two + users can have the same user name. There are a number of + rules for creating valid user names which are documented + in &man.passwd.5;. It is recommended to use user names + that consist of eight or fewer, all lower case characters + in order to maintain backwards compatibility with + applications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password</term> + + <listitem> + <para>Each user account should have an associated password. + While the password can be blank, this is highly + discouraged.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User ID (<acronym>UID</acronym>)</term> + + <listitem> + <para>The User ID (<acronym>UID</acronym>) is a number used + to uniquely identify the user to the &os; system. + Commands that allow a user name to be specified will + first convert it to the <acronym>UID</acronym>. It is + recommended to use a UID of 65535 or lower as higher UIDs + may cause compatibility issues with software that does + not support integers larger than 32-bits.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group ID (<acronym>GID</acronym>)</term> + + <listitem> + <para>The Group ID (<acronym>GID</acronym>) is a number + used to uniquely identify the primary group that the user + belongs to. Groups are a mechanism for controlling + access to resources based on a user's + <acronym>GID</acronym> rather than their + <acronym>UID</acronym>. This can significantly reduce the + size of some configuration files and allows users to be + members of more than one group. It is recommended to use + a GID of 65535 or lower as higher GIDs may break some + software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Login class</term> + + <listitem> + <para>Login classes are an extension to the group mechanism + that provide additional flexibility when tailoring the + system to different users. Login classes are discussed + further in <xref linkend="users-limiting"/></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password change time</term> + + <listitem> + <para>By default, &os; does not force users to change their + passwords periodically. Password expiration can be + enforced on a per-user basis using &man.pw.8;, forcing + some or all users to change their passwords after a + certain amount of time has elapsed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Account expiry time</term> + + <listitem> + <para>By default, &os; does not expire accounts. When + creating accounts that need a limited lifespan, such as + student accounts in a school, specify the account expiry + date using &man.pw.8;. After the expiry time has + elapsed, the account cannot be used to log in to the + system, although the account's directories and files will + remain.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User's full name</term> + + <listitem> + <para>The user name uniquely identifies the account to &os;, + but does not necessarily reflect the user's real name. + Similar to a comment, this information can contain a + space, uppercase characters, and be more than 8 + characters long.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Home directory</term> + + <listitem> + <para>The home directory is the full path to a directory on + the system. This is the user's starting directory when + the user logs in. A common convention is to put all user + home directories under <filename + class="directory">/home/<replaceable>username</replaceable></filename> + or <filename + class="directory">/usr/home/<replaceable>username</replaceable></filename>. + Each user stores their personal files and subdirectories + in their own home directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User shell</term> + + <listitem> + <para>The shell provides the user's default environment for + interacting with the system. There are many different + kinds of shells and experienced users will have their own + preferences, which can be reflected in their account + settings.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="users-superuser"> + <title>The Superuser Account</title> + + <indexterm> + <primary>accounts</primary> + <secondary>superuser (root)</secondary> + </indexterm> + + <para>The superuser account, usually called + <username>root</username>, is used to + manage the system with no limitations on privileges. For this + reason, it should not be used for day-to-day + tasks like sending and receiving mail, general exploration of + the system, or programming.</para> + + <para>The superuser, unlike other user + accounts, can operate without limits, and misuse of the + superuser account may result in spectacular disasters. User + accounts are unable to destroy the operating system by + mistake, so it is recommended to login as a user account and + to only become the superuser when a command requires extra + privilege.</para> + + <para>Always double and triple-check any commands issued as the + superuser, since an extra space or missing character can mean + irreparable data loss.</para> + + <para>There are several ways to become gain superuser privilege. + While one can log in as <username>root</username>, this is + highly discouraged.</para> + + <para>Instead, use &man.su.1; to become the superuser. If + <literal>-</literal> is specified when running this command, + the user will also inherit the root user's environment. The + user running this command must be in the + <groupname>wheel</groupname> group or else the command will + fail. The user must also know the password for the + <username>root</username> user account.</para> + + <para>In this example, the user only becomes superuser in order + to run <command>make install</command> as this step requires + superuser privilege. Once the command completes, the user + types <command>exit</command> to leave the superuser account + and return to the privilege of their user account.</para> + + <example> + <title>Install a Program As The Superuser</title> + + <screen>&prompt.user; <userinput>configure</userinput> +&prompt.user; <userinput>make</userinput> +&prompt.user; <userinput>su -</userinput> +Password: +&prompt.root; <userinput>make install</userinput> +&prompt.root; <userinput>exit</userinput> +&prompt.user;</screen> + </example> + + <para>The built-in &man.su.1; framework works well for single + systems or small networks with just one system administrator. + An alternative is to install the <filename + role="package">security/sudo</filename> package or port. + This software provides activity logging and allows the + administrator to configure which users can run which commands + as the superuser.</para> + </sect3> + </sect2> + + <sect2 id="users-modifying"> + <title>Managing Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>modifying</secondary> + </indexterm> + + <para>&os; provides a variety of different commands to manage + user accounts. The most common commands are summarized in Table + 4.1, followed by some examples of their usage. Refer to the + manual page for each utility for more details and usage + examples.</para> + + <table frame="none" pgwide="1"> + <title>Utilities for Managing User Accounts</title> + + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2*"/> + + <thead> + <row> + <entry>Command</entry> + <entry>Summary</entry> + </row> + </thead> + <tbody> + <row> + <entry>&man.adduser.8;</entry> + <entry>The recommended command-line application for adding + new users.</entry> + </row> - <para>&os;, being a direct descendant of BSD &unix;, is based - on several key &unix; concepts. The first and most pronounced - is that &os; is a multi-user operating system that can handle - several users working simultaneously on completely unrelated - tasks. The system is responsible for properly sharing and - managing requests for hardware devices, peripherals, memory, and - CPU time fairly to each user.</para> - - <para>Much more information about user accounts is in the chapter - about <link linkend="users">accounts</link>. It is important to - understand that each person (user) who uses the computer should be - given their own username and password. The system keeps track - of the people using the computer based on this username. Since - it is often the case that several people are working on the same - project &unix; also provides groups. Several users can be placed - in the same group.</para> - - <para>Because the system is capable of supporting multiple users, - everything the system manages has a set of permissions governing - who can read, write, and execute the resource. These - permissions are stored as three octets broken into three pieces, - one for the owner of the file, one for the group that the file - belongs to, and one for everyone else. This numerical - representation works like this:</para> + <row> + <entry>&man.rmuser.8;</entry> + <entry>The recommended command-line application for + removing users.</entry> + </row> + + <row> + <entry>&man.chpass.1;</entry> + <entry>A flexible tool for changing user database + information.</entry> + </row> + + <row> + <entry>&man.passwd.1;</entry> + <entry>The command-line tool to change user + passwords.</entry> + </row> + + <row> + <entry>&man.pw.8;</entry> + <entry>A powerful and flexible tool for modifying all + aspects of user accounts.</entry> + </row> + </tbody> + </tgroup> + </table> + + <sect3 id="users-adduser"> + <title><command>adduser</command></title> + + <indexterm> + <primary>accounts</primary> + <secondary>adding</secondary> + </indexterm> + <indexterm> + <primary><command>adduser</command></primary> + </indexterm> + <indexterm> + <primary><filename + class="directory">/usr/share/skel</filename></primary> + </indexterm> + <indexterm><primary>skeleton directory</primary></indexterm> + <para>The recommended program for adding new users is + &man.adduser.8;. When a new user is added, this program + automatically updates <filename>/etc/passwd</filename> and + <filename>/etc/group</filename>. It also creates a home + directory for the new user, copies in the default + configuration files from <filename + class="directory">/usr/share/skel</filename>, and can + optionally mail the new user a welcome message. This utility + must be run as the <username>superuser</username></para> + + <para>The &man.adduser.8; utility is interactive and walks + through the steps for creating a new user account. As seen in + Example 4.2, either input the required information or press + <keycap>Return</keycap> to accept the default value shown in + square brackets. In this example, the user has been invited + into the <groupname>wheel</groupname> group, which is + required to provide the account with superuser access. When + finished, the utility will prompt to either create another + user or to exit.</para> + + <example> + <title>Adding a User on &os;</title> + + <screen>&prompt.root; <userinput>adduser</userinput> +Username: <userinput>jru</userinput> +Full name: <userinput>J. Random User</userinput> +Uid (Leave empty for default): +Login group [jru]: +Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput> +Login class [default]: +Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput> +Home directory [/home/jru]: +Home directory permissions (Leave empty for default): +Use password-based authentication? [yes]: +Use an empty password? (yes/no) [no]: +Use a random password? (yes/no) [no]: +Enter password: +Enter password again: +Lock out the account after creation? [no]: +Username : jru +Password : **** +Full Name : J. Random User +Uid : 1001 +Class : +Groups : jru wheel +Home : /home/jru +Shell : /usr/local/bin/zsh +Locked : no +OK? (yes/no): <userinput>yes</userinput> +adduser: INFO: Successfully added (jru) to the user database. +Add another user? (yes/no): <userinput>no</userinput> +Goodbye! +&prompt.root;</screen> + </example> + + <note> + <para>Since the password is not echoed when typed, be careful + to not mistype the password when creating the user + account.</para> + </note> + </sect3> + + <sect3 id="users-rmuser"> + <title><command>rmuser</command></title> + + <indexterm><primary><command>rmuser</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>removing</secondary> + </indexterm> + + <para>To completely remove a user from the system, run + &man.rmuser.8; as the superuser. This command performs the + following steps:</para> + + <procedure> + <step> + <para>Removes the user's &man.crontab.1; entry, if one + exists.</para> + </step> + + <step> + <para>Removes any &man.at.1; jobs belonging to the + user.</para> + </step> + + <step> + <para>Kills all processes owned by the user.</para> + </step> + + <step> + <para>Removes the user from the system's local password + file.</para> + </step> + + <step> + <para>Optionally removes the user's home directory, if it is + owned by the user.</para> + </step> + + <step> + <para>Removes the incoming mail files belonging to the user + from <filename + class="directory">/var/mail</filename>.</para> + </step> + + <step> + <para>Removes all files owned by the user from temporary + file storage areas such as <filename + class="directory">/tmp</filename>.</para> + </step> + + <step> + <para>Finally, removes the username from all groups to which + it belongs in <filename>/etc/group</filename>. If a group + becomes empty and the group name is the same as the + username, the group is removed. This complements the + per-user unique groups created by &man.adduser.8;.</para> + </step> + </procedure> + + <para>&man.rmuser.8; cannot be used to remove superuser + accounts since that is almost always an indication of massive + destruction.</para> + + <para>By default, an interactive mode is used, as shown + in the following example.</para> + + <example> + <title><command>rmuser</command> Interactive Account + Removal</title> + + <screen>&prompt.root; <userinput>rmuser jru</userinput> +Matching password entry: +jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh +Is this the entry you wish to remove? <userinput>y</userinput> +Remove user's home directory (/home/jru)? <userinput>y</userinput> +Removing user (jru): mailspool home passwd. +&prompt.root;</screen> + </example> + </sect3> + + <sect3 id="users-chpass"> + <title><command>chpass</command></title> + + <indexterm><primary><command>chpass</command></primary></indexterm> + <para>Any user can use &man.chpass.1; to change their default + shell and personal information associated with their user + account. The superuser can use this utility to change + additional account information for any user.</para> + + <para>When passed no options, aside from an optional username, + &man.chpass.1; displays an editor containing user information. + When the user exists from the editor, the user database is + updated with the new information.</para> + + <note> + <para>This utility will prompt for the user's password when + exiting the editor, unless the utility is run as the + superuser.</para> + </note> + + <para>In Example 4.4, the superuser has typed + <command>chpass jru</command> and is now viewing the fields + that can be changed for this user. If + <username>jru</username> runs this command instead, only the + last six fields will be displayed and available for editing. + This is shown in Example 4.5.</para> + + <example> + <title>Using <command>chpass</command> as + Superuser</title> + + <screen>#Changing user database information for jru. +Login: jru +Password: * +Uid [#]: 1001 +Gid [# or name]: 1001 +Change [month day year]: +Expire [month day year]: +Class: +Home directory: /home/jru +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <example> + <title>Using <command>chpass</command> as Regular + User</title> + + <screen>#Changing user database information for jru. +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <note> + <para>&man.chfn.1; and &man.chsh.1; are links to + &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and + &man.ypchsh.1;. Since <acronym>NIS</acronym> support is + automatic, specifying the <literal>yp</literal> before + the command is not necessary. How to configure NIS is + covered in <xref linkend="network-servers"/>.</para> + </note> + </sect3> + <sect3 id="users-passwd"> + <title><command>passwd</command></title> + + <indexterm><primary><command>passwd</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>changing password</secondary> + </indexterm> + <para>Any user can easily change their password using + &man.passwd.1;. To prevent accidental or unauthorized + changes, this command will prompt for the user's original + password before a new password can be set:</para> + + <example> + <title>Changing Your Password</title> + + <screen>&prompt.user; <userinput>passwd</userinput> +Changing local password for jru. +Old password: +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <para>The superuser can change any user's password by specifying + the username when running &man.passwd.1;. When this utility + is run as the superuser, it will not prompt for the user's + current password. This allows the password to be changed when + a user cannot remember the original password.</para> + + <example> + <title>Changing Another User's Password as the + Superuser</title> + + <screen>&prompt.root; <userinput>passwd jru</userinput> +Changing local password for jru. +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <note> + <para>As with &man.chpass.1;, &man.yppasswd.1; is a link to + &man.passwd.1;, so <acronym>NIS</acronym> works with either + command.</para> + </note> + </sect3> + + + <sect3 id="users-pw"> + <title><command>pw</command></title> + + <indexterm><primary><command>pw</command></primary></indexterm> + + <para>&man.pw.8; is a command line utility to create, remove, + modify, and display users and groups. It functions as a front + end to the system user and group files. &man.pw.8; has a very + powerful set of command line options that make it suitable for + use in shell scripts, but new users may find it more + complicated than the other commands presented in this + section.</para> + </sect3> + </sect2> + + <sect2 id="users-limiting"> + <title>Limiting Users</title> + + <indexterm><primary>limiting users</primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>limiting</secondary> + </indexterm> + <para>&os; provides several methods for an administrator to limit + the amount of system resources an individual may use. These + limits are discussed in two sections: disk quotas and other + resource limits.</para> + + <indexterm><primary>quotas</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>quotas</secondary> + </indexterm> + <indexterm><primary>disk quotas</primary></indexterm> + <para>Disk quotas limit the amount of disk space available to + users and provide a way to quickly check that usage without + calculating it every time. Quotas are discussed in <xref + linkend="quotas"/>.</para> + + <para>The other resource limits include ways to limit the amount + of CPU, memory, and other resources a user may consume. These + are defined using login classes and are discussed here.</para> + + <indexterm> + <primary><filename>/etc/login.conf</filename></primary> + </indexterm> + <para>Login classes are defined in + <filename>/etc/login.conf</filename> and are described in detail + in &man.login.conf.5;. Each user account is assigned to a login + class, <literal>default</literal> by default, and each login + class has a set of login capabilities associated with it. A + login capability is a + <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal> + pair, where <replaceable>name</replaceable> is a well-known + identifier and <replaceable>value</replaceable> is an arbitrary + string which is processed accordingly depending on the + <replaceable>name</replaceable>. Setting up login classes and + capabilities is rather straightforward and is also described in + &man.login.conf.5;.</para> <note> - <para>This section will discuss the traditional &unix; - permissions. For finer grained file system access - control, see the <link linkend="fs-acl">File System - Access Control Lists</link> section.</para> + <para>&os; does not normally read the configuration in + <filename>/etc/login.conf</filename> directly, but instead + reads the <filename>/etc/login.conf.db</filename> database + which provides faster lookups. Whenever + <filename>/etc/login.conf</filename> is edited, the + <filename>/etc/login.conf.db</filename> must be updated by + executing the following command:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> </note> + <para>Resource limits differ from the default login capabilities + in two ways. First, for every limit, there is a soft (current) + and hard limit. A soft limit may be adjusted by the user or + application, but may not be set higher than the hard limit. The + hard limit may be lowered by the user, but can only be raised + by the superuser. Second, most resource limits apply per + process to a specific user, not to the user as a whole. These + differences are mandated by the specific handling of the limits, + not by the implementation of the login capability + framework.</para> + + <para>Below are the most commonly used resource limits. The rest + of the limits, along with all the other login capabilities, can + be found in &man.login.conf.5;.</para> + + <variablelist> + <varlistentry> + <term><literal>coredumpsize</literal></term> + + <listitem> + <para>The limit on the size of a core file + <indexterm><primary>coredumpsize</primary></indexterm> + generated by a program is subordinate to other + limits <indexterm><primary>limiting users + </primary><secondary>coredumpsize</secondary></indexterm> + on disk usage, such as <literal>filesize</literal>, or + disk quotas. This limit is often used as a less-severe + method of controlling disk space consumption. Since + users do not generate core files themselves, and often do + not delete them, setting this may save them from running + out of disk space should a large program crash.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>cputime</literal></term> + + <listitem> + <para>The maximum amount of CPU + <indexterm><primary>cputime</primary></indexterm><indexterm><primary> + limiting users + </primary><secondary>cputime</secondary></indexterm> + time a user's process may consume. Offending processes + will be killed by the kernel.</para> + + <note> + <para>This is a limit on CPU <emphasis>time</emphasis> + consumed, not percentage of the CPU as displayed in + some fields by &man.top.1; and &man.ps.1;.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>filesize</literal></term> + + <listitem> + <para>The maximum size of a file + <indexterm><primary>filesize</primary></indexterm><indexterm><primary> + limiting users + </primary><secondary>filesize</secondary></indexterm> + the user may own. Unlike <link linkend="quotas">disk + quotas</link>, this limit is enforced on individual + files, not the set of all files a user owns.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>maxproc</literal></term> + + <listitem> + <para>The maximum number of processes + <indexterm><primary>maxproc</primary></indexterm><indexterm><primary> + limiting users + </primary><secondary>maxproc</secondary></indexterm> a + user can run. This includes foreground and background + processes. This limit may not be larger than the system + limit specified by the + <varname>kern.maxproc</varname> &man.sysctl.8;. Setting + this limit too small may hinder a user's productivity as + it is often useful to be logged in multiple times or to + execute pipelines. Some tasks, such as compiling a large + program, spawn multiple processes and other intermediate + preprocessors.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memorylocked</literal></term> + + <listitem> + <para>The maximum amount of memory + <indexterm><primary>memorylocked</primary></indexterm><indexterm><primary> + limiting users + </primary><secondary>memorylocked</secondary></indexterm> + a process may request to be locked into main memory using + &man.mlock.2;. Some system-critical programs, such as + &man.amd.8;, lock into main memory so that if the system + begins to swap, they do not contribute to disk + thrashing.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memoryuse</literal></term> + + <listitem> + <para>The maximum amount of memory + <indexterm><primary>memoryuse</primary></indexterm><indexterm><primary> + limiting + users</primary><secondary>memoryuse</secondary></indexterm> + a process may consume at any given time. It includes both + core memory and swap usage. This is not a catch-all limit + for restricting memory consumption, but is a good + start.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>openfiles</literal></term> + + <listitem> + <para>The maximum number of files a process may have open + <indexterm><primary>openfiles</primary></indexterm><indexterm><primary> + limiting + users</primary><secondary>openfiles</secondary></indexterm>. + In &os;, files are used to represent sockets and IPC + channels, so be careful not to set this too low. The + system-wide limit for this is defined by the + <varname>kern.maxfiles</varname> &man.sysctl.8;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sbsize</literal></term> + + <listitem> + <para>The limit on the amount of network memory, and + thus mbufs + <indexterm><primary>sbsize</primary></indexterm><indexterm><primary>limiting + users</primary><secondary>sbsize</secondary></indexterm>, + a user may consume in order to limit network + communications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>stacksize</literal></term> + + <listitem> + <para>The maximum size of a process stack + <indexterm><primary>stacksize</primary></indexterm><indexterm><primary>limiting + users</primary><secondary>stacksize</secondary></indexterm>. + This alone is not sufficient to limit the amount of memory + a program may use so it should be used in conjunction with + other limits.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There are a few other things to remember when setting + resource limits. Following are some general tips, suggestions, + and miscellaneous comments.</para> + + <itemizedlist> + <listitem> + <para>Processes started at system startup by + <filename>/etc/rc</filename> are assigned to the + <literal>daemon</literal> login class.</para> + </listitem> + + <listitem> + <para>Although the <filename>/etc/login.conf</filename> that + comes with the system is a good source of reasonable values + for most limits, they may not be appropriate for every + system. Setting a limit too high may open the system up to + abuse, while setting it too low may put a strain on + productivity.</para> + </listitem> + + <listitem> + <para>Users of <application>&xorg;</application> should + probably be granted more resources than other users. + <application>&xorg;</application> by itself takes a lot of + resources, but it also encourages users to run more programs + simultaneously.</para> + </listitem> + + <listitem> + <para>Many limits apply to individual processes, not the user + as a whole. For example, setting + <varname>openfiles</varname> to 50 means that each process + the user runs may open up to 50 files. The total amount + of files a user may open is the value of + <literal>openfiles</literal> multiplied by the value of + <literal>maxproc</literal>. This also applies to memory + consumption.</para> + </listitem> + </itemizedlist> + + <para>For further information on resource limits and login classes + and capabilities in general, refer to &man.cap.mkdb.1;, + &man.getrlimit.2;, and &man.login.conf.5;.</para> + </sect2> + + <sect2 id="users-groups"> + <title>Managing Groups</title> + + <indexterm><primary>groups</primary></indexterm> + <indexterm> + <primary><filename>/etc/groups</filename></primary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>groups</secondary> + </indexterm> + <para>A group is a list of users. A group is identified by its + group name and <acronym>GID</acronym>. In &os;, the + kernel uses the <acronym>UID</acronym> of a process, and the + list of groups it belongs to, to determine what the process is + allowed to do. Most of the time, the <acronym>GID</acronym> of + a user or process usually means the first group in the + list.</para> + + <para>The group name to <acronym>GID</acronym> mapping is listed + in <filename>/etc/group</filename>. This is a plain text file + with four colon-delimited fields. The first field is the group + name, the second is the encrypted password, the third the + <acronym>GID</acronym>, and the fourth the comma-delimited list + of members. For a more complete description of the syntax, + refer to &man.group.5;.</para> + + <para>The superuser can modify <filename>/etc/group</filename> + using a text editor. Alternatively, &man.pw.8; can be used to + add and edit groups. For example, to add a group called + <groupname>teamtwo</groupname> and then confirm that it + exists:</para> + + <example> + <title>Adding a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:</screen> + </example> + + <para>In this example, <literal>1100</literal> is the + <acronym>GID</acronym> of <groupname>teamtwo</groupname>. Right + now, <groupname>teamtwo</groupname> has no members. This + command will add <username>jru</username> as a member of + <groupname>teamtwo</groupname>.</para> + + <example> + <title>Adding User Accounts to a New Group Using + &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru</screen> + </example> + + <para>The argument to <option>-M</option> is a comma-delimited + list of users to be added to a new (empty) group or to replace + the members of an existing group. To the user, this group + membership is different from (and in addition to) the user's + primary group listed in the password file. This means that + the user will not show up as a member when using + <option>groupshow</option> with &man.pw.8;, but will show up + when the information is queried via &man.id.1; or a similar + tool. When &man.pw.8; is used to add a user to a group, it only + manipulates <filename>/etc/group</filename> and does not attempt + to read additional data from + <filename>/etc/passwd</filename>.</para> + + <example> + <title>Adding a New Member to a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru,db</screen> + </example> + + <para>In this example, the argument to <option>-m</option> is a + comma-delimited list of users who are to be added to the group. + Unlike the previous example, these users are appended to the + group list and do not replace the list of existing users in the + group.</para> + + <example> + <title>Using &man.id.1; to Determine Group Membership</title> + + <screen>&prompt.user; <userinput>id jru</userinput> +uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen> + </example> + + <para>In this example, <username>jru</username> is a member of + the groups <groupname>jru</groupname> and + <groupname>teamtwo</groupname>.</para> + + <para>For more information about this command and the format of + <filename>/etc/group</filename>, refer to &man.pw.8; and + &man.group.5;.</para> + </sect2> + </sect1> + + <sect1 id="permissions"> + <title>Permissions</title> + + <indexterm><primary>UNIX</primary></indexterm> + + <para>In &os;, every file and directory has an associated set of + permissions and several utilities are available for viewing + and modifying these permissions. Understanding how permissions + work is necessary to make sure that users are able to access + the files that they need and are unable to improperly access + the files used by the operating system or owned by other + users.</para> + + <para>This section discusses the traditional &unix; permissions + used in &os;. For finer grained file system access control, + refer to <xref linkend="fs-acl"/>.</para> + + <para>In &unix;, basic permissions are assigned using + three types of access: read, write, and execute. These access + types are used to determine file access to the file's owner, + group, and others (everyone else). The read, write, and execute + permissions can be represented as the letters + <literal>r</literal>, <literal>w</literal>, and + <literal>x</literal>. They can also be represented as binary + numbers as each permission is either on or off + (<literal>0</literal>). When represented as a number, the + order is always read as <literal>rwx</literal>, where + <literal>r</literal> has an on value of <literal>4</literal>, + <literal>w</literal> has an on value of <literal>2</literal> + and <literal>x</literal> has an on value of + <literal>1</literal>.</para> + + <para>Table 4.1 summarizes the possible numeric and alphabetic + possibilities. When reading the <quote>Directory + Listing</quote> column, a <literal>-</literal> is used to + represent a permission that is set to off.</para> + <indexterm><primary>permissions</primary></indexterm> <indexterm> <primary>file permissions</primary> </indexterm> - <informaltable frame="none" pgwide="1"> + <table frame="none" pgwide="1"> + <title>&unix; Permissions</title> + <tgroup cols="3"> <thead> <row> @@ -390,7 +1430,8 @@ console none unknown off secure</programlisting> </row> </tbody> </tgroup> - </informaltable> + </table> + <indexterm> <primary>&man.ls.1;</primary> </indexterm> @@ -1026,9 +2067,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> class="directory">/var/</filename></entry> <entry>Multi-purpose log, temporary, transient, and spool files. A memory-based file system is sometimes - mounted at <filename - class="directory">/var</filename>. This can be - automated using the varmfs-related variables in + mounted at + <filename class="directory">/var</filename>. This can + be automated using the varmfs-related variables in &man.rc.conf.5; or with an entry in <filename>/etc/fstab</filename>; refer to &man.mdmfs.8; for details.</entry> @@ -1057,8 +2098,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <entry><filename class="directory">/var/tmp/</filename></entry> <entry>Temporary files which are usually preserved - across a system reboot, unless <filename - class="directory">/var</filename> is a + across a system reboot, unless + <filename class="directory">/var</filename> is a memory-based file system.</entry> </row> @@ -1091,8 +2132,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>Files and directories are referenced by giving the file or directory name, followed by a forward slash, <literal>/</literal>, followed by any other directory names that - are necessary. For example, if the directory <filename - class="directory">foo</filename> contains a directory + are necessary. For example, if the directory + <filename class="directory">foo</filename> contains a directory <filename class="directory">bar</filename> which contains the file <filename>readme.txt</filename>, the full name, or <firstterm>path</firstterm>, to the file is @@ -1107,11 +2148,12 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> file system contains exactly one directory at the very top level, called the <firstterm>root directory</firstterm> for that file system. This root directory can contain other directories. - One file system is designated the <firstterm>root file - system</firstterm> or <literal>/</literal>. Every other file - system is <firstterm>mounted</firstterm> under the root file - system. No matter how many disks are on the &os; system, every - directory appears to be part of the same disk.</para> + One file system is designated the + <firstterm>root file system</firstterm> or <literal>/</literal>. + Every other file system is <firstterm>mounted</firstterm> under + the root file system. No matter how many disks are on the &os; + system, every directory appears to be part of the same + disk.</para> <para>Consider three file systems, called <literal>A</literal>, <literal>B</literal>, and <literal>C</literal>. Each file @@ -1167,10 +2209,10 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>Any files that are in the <literal>B1</literal> or <literal>B2</literal> directories can be reached with the path - <filename class="directory">/A1/B1</filename> or <filename - class="directory">/A1/B2</filename> as necessary. Any files - that were in <filename class="directory">/A1</filename> have - been temporarily hidden. They will reappear if + <filename class="directory">/A1/B1</filename> or + <filename class="directory">/A1/B2</filename> as necessary. Any + files that were in <filename class="directory">/A1</filename> + have been temporarily hidden. They will reappear if <literal>B</literal> is <firstterm>unmounted</firstterm> from <literal>A</literal>.</para> @@ -1197,8 +2239,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </mediaobject> <para>and the paths would be - <filename class="directory">/A2/B1</filename> and <filename - class="directory">/A2/B2</filename> respectively.</para> + <filename class="directory">/A2/B1</filename> and + <filename class="directory">/A2/B2</filename> + respectively.</para> <para>File systems can be mounted on top of one another. Continuing the last example, the <literal>C</literal> file @@ -1266,9 +2309,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <firstterm>mount options</firstterm>. For example, the root file system can be mounted read-only, making it impossible for users to inadvertently delete or edit a critical file. - Separating user-writable file systems, such as <filename - class="directory">/home</filename>, from other file - systems allows them to be mounted + Separating user-writable file systems, such as + <filename class="directory">/home</filename>, from other + file systems allows them to be mounted <firstterm>nosuid</firstterm>. This option prevents the <firstterm>suid</firstterm>/<firstterm>guid</firstterm> bits on executables stored on the file system from taking effect, @@ -1286,11 +2329,11 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <listitem> <para>&os;'s file systems are robust if power is lost. - However, a power loss at a critical point could still - damage the structure of the file system. By splitting - data over multiple file systems it is more likely that the - system will still come up, making it easier to restore from - backup as necessary.</para> + However, a power loss at a critical point could still damage + the structure of the file system. By splitting data over + multiple file systems it is more likely that the system will + still come up, making it easier to restore from backup as + necessary.</para> </listitem> </itemizedlist> @@ -1306,9 +2349,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> restoring the backed up data.</para> <important> - <para>&os; features the &man.growfs.8; command, which - makes it possible to increase the size of file system on - the fly, removing this limitation.</para> + <para>&os; features the &man.growfs.8; command, which makes + it possible to increase the size of file system on the + fly, removing this limitation.</para> </important> </listitem> </itemizedlist> @@ -1323,8 +2366,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> point in the file system hierarchy, or the letter of the partition they are contained in.</para> - <para>&os; also uses disk space for <firstterm>swap - space</firstterm> to provide + <para>&os; also uses disk space for + <firstterm>swap space</firstterm> to provide <firstterm>virtual memory</firstterm>. This allows your computer to behave as though it has much more memory than it actually does. When &os; runs out of memory, it moves some of @@ -1364,8 +2407,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> This allows utilities that need to work on the entire slice, such as a bad block scanner, to work on the <literal>c</literal> partition. A file system would not - normally be - created on this partition.</entry> + normally be created on this partition.</entry> </row> <row> @@ -1381,8 +2423,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>Disks in &os; are divided into slices, referred to in &windows; as partitions, which are numbered from 1 to 4. These - are then then divided into partitions, which contain file - systems, and are labeled using letters.</para> + are then divided into partitions, which contain file systems, + and are labeled using letters.</para> <indexterm><primary>slices</primary></indexterm> <indexterm><primary>partitions</primary></indexterm> @@ -1405,21 +2447,22 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> letter is appended to the device name, so <quote>da0<emphasis>a</emphasis></quote> is the <literal>a</literal> partition on the first - <literal>da</literal> drive, which is <quote>dangerously - dedicated</quote>. <quote>ad1s3<emphasis>e</emphasis></quote> - is the fifth partition in the third slice of the second IDE - disk drive.</para> + <literal>da</literal> drive, which is + <quote>dangerously dedicated</quote>. + <quote>ad1s3<emphasis>e</emphasis></quote> is the fifth + partition in the third slice of the second IDE disk + drive.</para> <para>Finally, each disk on the system is identified. A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is. Unlike slices, disk - numbering starts at 0. Common codes are listed in <xref - linkend="basics-dev-codes"/>.</para> + numbering starts at 0. Common codes are listed in + <xref linkend="basics-dev-codes"/>.</para> <para>When referring to a partition, include the disk name, <literal>s</literal>, the slice number, and then the partition - letter. Examples are shown in <xref - linkend="basics-disk-slice-part"/>.</para> + letter. Examples are shown in + <xref linkend="basics-disk-slice-part"/>.</para> <para><xref linkend="basics-concept-disk-model"/> shows a conceptual model of a disk layout.</para> @@ -1497,7 +2540,6 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <row> <entry><literal>da1s2e</literal></entry> - <entry>The fifth partition (<literal>e</literal>) on the second slice (<literal>s2</literal>) on the second SCSI disk (<literal>da1</literal>).</entry> @@ -1515,15 +2557,15 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> size, and contains two 2 GB slices (&ms-dos; partitions). The first slice contains a &ms-dos; disk, <devicename>C:</devicename>, and the second slice contains a - &os; installation. This example &os; installation has - three data partitions, and a swap partition.</para> + &os; installation. This example &os; installation has three + data partitions, and a swap partition.</para> <para>The three partitions will each hold a file system. Partition <literal>a</literal> will be used for the root file - system, <literal>e</literal> for the <filename - class="directory">/var/</filename> directory hierarchy, and - <literal>f</literal> for the <filename - class="directory">/usr/</filename> directory + system, <literal>e</literal> for the + <filename class="directory">/var/</filename> directory + hierarchy, and <literal>f</literal> for the + <filename class="directory">/usr/</filename> directory hierarchy.</para> <mediaobject> @@ -1566,29 +2608,31 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <sect1 id="mount-unmount"> <title>Mounting and Unmounting File Systems</title> - <para>The file system is best visualized as a tree, - rooted, as it were, at <filename class="directory">/</filename>. - <filename class="directory">/dev</filename>, <filename - class="directory">/usr</filename>, and the other directories - in the root directory are branches, which may have their own - branches, such as <filename - class="directory">/usr/local</filename>, and so on.</para> + <para>The file system is best visualized as a tree, rooted, as it + were, at <filename class="directory">/</filename>. + <filename class="directory">/dev</filename>, + <filename class="directory">/usr</filename>, and the other + directories in the root directory are branches, which may have + their own branches, such as + <filename class="directory">/usr/local</filename>, and so + on.</para> <indexterm><primary>root file system</primary></indexterm> <para>There are various reasons to house some of these - directories on separate file systems. <filename - class="directory">/var</filename> contains the directories - <filename class="directory">log/</filename>, + directories on separate file systems. + <filename class="directory">/var</filename> contains the + directories <filename class="directory">log/</filename>, <filename class="directory">spool/</filename>, and various types of temporary files, and as such, may get filled up. Filling up - the root file system is not a good idea, so splitting <filename - class="directory">/var</filename> from <filename - class="directory">/</filename> is often favorable.</para> + the root file system is not a good idea, so splitting + <filename class="directory">/var</filename> from + <filename class="directory">/</filename> is often + favorable.</para> <para>Another common reason to contain certain directory trees on other file systems is if they are to be housed on separate physical disks, or are separate virtual disks, such as Network - File System mounts, described in <xref linkend="network-nfs"/>, + File System mounts, described in <xref linkend="network-nfs"/>, or CDROM drives.</para> <sect2 id="disks-fstab"> @@ -1599,8 +2643,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <secondary>mounted with fstab</secondary> </indexterm> - <para>During the boot process (<xref linkend="boot"/>), - file systems listed in <filename>/etc/fstab</filename> are + <para>During the boot process (<xref linkend="boot"/>), file + systems listed in <filename>/etc/fstab</filename> are automatically mounted except for the entries containing <option>noauto</option>. This file contains entries in the following format:</para> @@ -1825,7 +2869,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </sect1> <sect1 id="basics-processes"> - <title>Processes</title> + <title>Processes and Daemons</title> <para>&os; is a multi-tasking operating system. Each program running at any one time is called a @@ -1843,168 +2887,170 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> process which has the shell as its parent process. The exception is a special process called &man.init.8; which is always the first process to start at boot time and which always - has a <acronym>PID</acronym> of 1.</para> - - <para>To see the processes on the system, use &man.ps.1; and - &man.top.1;. To display a static list of the currently running - processes, their <acronym>PID</acronym>s, how much memory they - are using, and the command they were started with, use - &man.ps.1;. To display all the running processes and update - the display every few seconds in order to interactively see - what the computer is doing, use &man.top.1;.</para> - - <para>By default, &man.ps.1; only shows the commands that are - running and owned by the user. For example:</para> - - <screen>&prompt.user; <userinput>ps</userinput> - PID TT STAT TIME COMMAND - 298 p0 Ss 0:01.10 tcsh - 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14) -37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14) -72210 p0 R+ 0:00.00 ps - 390 p1 Is 0:01.14 tcsh - 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y - 6688 p3 IWs 0:00.00 tcsh -10735 p4 IWs 0:00.00 tcsh -20256 p5 IWs 0:00.00 tcsh - 262 v0 IWs 0:00.00 -tcsh (tcsh) - 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16 - 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16 - 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc - 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish</screen> - - <para>The output from &man.ps.1; is organized into a number of - columns. The <literal>PID</literal> column displays the process - ID. <acronym>PID</acronym>s are assigned starting at 1, go up - to 99999, then wrap around back to the beginning. However, a - <acronym>PID</acronym> is not reassigned if it is already in - use. The <literal>TT</literal> column shows the tty the program - is running on and <literal>STAT</literal> shows the program's - state. <literal>TIME</literal> is the amount of time the - program has been running on the CPU. This is usually not the - elapsed time since the program was started, as most programs - spend a lot of time waiting for things to happen before they - need to spend time on the CPU. Finally, - <literal>COMMAND</literal> is the command that was used to start - the program.</para> - - <para>&man.ps.1; supports a number of different options to change - the information that is displayed. One of the most useful sets - is <literal>auxww</literal>. <option>a</option> displays - information about all the running processes of all users. - <option>u</option> displays the username of the process' owner, - as well as memory usage. <option>x</option> displays - information about daemon processes, and <option>ww</option> - causes &man.ps.1; to display the full command line for each - process, rather than truncating it once it gets too long to fit - on the screen.</para> - - <para>The output from &man.top.1; is similar. A sample session - looks like this:</para> - - <screen>&prompt.user; <userinput>top</userinput> + has a <acronym>PID</acronym> of <literal>1</literal>.</para> + + <para>Some programs are not designed to be run with continuous + user input and disconnect from the terminal at the first + opportunity. For example, a web server responds to web + requests, rather than user input. Mail servers are another + example of this type of application. These types of programs + are known as <firstterm>daemons</firstterm>. The term daemon + comes from Greek mythology and represents an entity that is + neither good nor evil, and which invisibly performs useful + tasks. This is why the BSD mascot is the cheerful-looking + daemon with sneakers and a pitchfork.</para> + + <para>There is a convention to name programs that normally run as + daemons with a trailing <quote>d</quote>. For example, + <application>BIND</application> is the Berkeley Internet Name + Domain, but the actual program that executes is + <command>named</command>. The + <application>Apache</application> web server program is + <command>httpd</command> and the line printer spooling daemon + is <command>lpd</command>. This is only a naming convention. + For example, the main mail daemon for the + <application>Sendmail</application> application is + <command>sendmail</command>, and not + <literal>maild</literal>.</para> + + <sect2> + <title>Viewing Processes</title> + + <para>To see the processes running on the system, use &man.ps.1; + or &man.top.1;. To display a static list of the currently + running processes, their <acronym>PID</acronym>s, how much + memory they are using, and the command they were started with, + use &man.ps.1;. To display all the running processes and + update the display every few seconds in order to interactively + see what the computer is doing, use &man.top.1;.</para> + + <para>By default, &man.ps.1; only shows the commands that are + running and owned by the user. For example:</para> + + <screen>&prompt.user; <userinput>ps</userinput> + PID TT STAT TIME COMMAND +8203 0 Ss 0:00.59 /bin/csh +8895 0 R+ 0:00.00 ps</screen> + + <para>The output from &man.ps.1; is organized into a number of + columns. The <literal>PID</literal> column displays the + process ID. <acronym>PID</acronym>s are assigned starting at + 1, go up to 99999, then wrap around back to the beginning. + However, a <acronym>PID</acronym> is not reassigned if it is + already in use. The <literal>TT</literal> column shows the + tty the program is running on and <literal>STAT</literal> + shows the program's state. <literal>TIME</literal> is the + amount of time the program has been running on the CPU. This + is usually not the elapsed time since the program was started, + as most programs spend a lot of time waiting for things to + happen before they need to spend time on the CPU. Finally, + <literal>COMMAND</literal> is the command that was used to + start the program.</para> + + <para>A number of different options are available to change the + information that is displayed. One of the most useful sets is + <literal>auxww</literal>, where <option>a</option> displays + information about all the running processes of all users, + <option>u</option> displays the username and memory usage of + the process' owner, <option>x</option> displays + information about daemon processes, and <option>ww</option> + causes &man.ps.1; to display the full command line for each + process, rather than truncating it once it gets too long to + fit on the screen.</para> + + <para>The output from &man.top.1; is similar:</para> + + <screen>&prompt.user; <userinput>top</userinput> last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10 47 processes: 1 running, 46 sleeping CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free Swap: 256M Total, 38M Used, 217M Free, 15% Inuse - PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND -72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top - 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14 - 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA - 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm - 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd - 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt -...</screen> - - <para>The output is split into two sections. The header (the - first five lines) shows the <acronym>PID</acronym> of the last - process to run, the system load averages (which are a measure - of how busy the system is), the system uptime (time since the - last reboot) and the current time. The other figures in the - header relate to how many processes are running (47 in this - case), how much memory and swap space has been used, and how - much time the system is spending in different CPU states.</para> - - <para>Below the header is a series of columns containing similar - information to the output from &man.ps.1;, such as the - <acronym>PID</acronym>, username, amount of CPU time, and the - command that started the process. By default, &man.top.1; also - displays the amount of memory space taken by the process. - This is split into two columns: one for total size and one for - resident size. Total size is how much memory the application - has needed and the resident size is how much it is actually - using at the moment. In this example, - <application>mutt</application> has required almost 8 MB - of RAM, but is currently only using 5 MB.</para> - - <para>&man.top.1; automatically updates the display every two - seconds. A different interval can be specified with - <option>-s</option>.</para> - </sect1> - - <sect1 id="basics-daemons"> - <title>Daemons, Signals, and Killing Processes</title> - - <para>When using an editor, it is easy to control the editor and - load files because the editor provides facilities to do so, and - because the editor is attached to a - <firstterm>terminal</firstterm>. Some programs are not designed - to be run with continuous user input and disconnect from the - terminal at the first opportunity. For example, a web server - responds to web requests, rather than user input. Mail servers - are another example of this type of application.</para> - - <para>These programs are known as <firstterm>daemons</firstterm>. - The term daemon comes from Greek mythology and represents an - entity that is neither good or evil, and which invisibly - performs useful tasks. This is why the BSD mascot is the - cheerful-looking daemon with sneakers and a pitchfork.</para> - - <para>There is a convention to name programs that normally run as - daemons with a trailing <quote>d</quote>. - <application>BIND</application> is the Berkeley Internet Name - Domain, but the actual program that executes is &man.named.8;. - The <application>Apache</application> web server program is - <command>httpd</command> and the line printer spooling daemon - is &man.lpd.8;. This is only a naming convention. For example, - the main mail daemon for the <application>Sendmail</application> - application is &man.sendmail.8;, and not - <literal>maild</literal>.</para> +last pid: 9609; load averages: 0.56, 0.45, 0.36 up 0+00:20:03 10:21:46 +107 processes: 2 running, 104 sleeping, 1 zombie +CPU: 6.2% user, 0.1% nice, 8.2% system, 0.4% interrupt, 85.1% idle +Mem: 541M Active, 450M Inact, 1333M Wired, 4064K Cache, 1498M Free +ARC: 992M Total, 377M MFU, 589M MRU, 250K Anon, 5280K Header, 21M Other +Swap: 2048M Total, 2048M Free + + PID USERNAME THR PRI NICE SIZE RES STATE C TIME WCPU COMMAND + 557 root 1 -21 r31 136M 42296K select 0 2:20 9.96% Xorg + 8198 dru 2 52 0 449M 82736K select 3 0:08 5.96% kdeinit4 + 8311 dru 27 30 0 1150M 187M uwait 1 1:37 0.98% firefox + 431 root 1 20 0 14268K 1728K select 0 0:06 0.98% moused + 9551 dru 1 21 0 16600K 2660K CPU3 3 0:01 0.98% top + 2357 dru 4 37 0 718M 141M select 0 0:21 0.00% kdeinit4 + 8705 dru 4 35 0 480M 98M select 2 0:20 0.00% kdeinit4 + 8076 dru 6 20 0 552M 113M uwait 0 0:12 0.00% soffice.bin + 2623 root 1 30 10 12088K 1636K select 3 0:09 0.00% powerd + 2338 dru 1 20 0 440M 84532K select 1 0:06 0.00% kwin + 1427 dru 5 22 0 605M 86412K select 1 0:05 0.00% kdeinit4</screen> + + <para>The output is split into two sections. The header (the + first five or six lines) shows the <acronym>PID</acronym> of + the last process to run, the system load averages (which are a + measure of how busy the system is), the system uptime (time + since the last reboot) and the current time. The other + figures in the header relate to how many processes are + running, how much memory and swap space has been used, and how + much time the system is spending in different CPU states. If + the system has been formatted with the <acronym>ZFS</acronym> + file system, the <literal>ARC</literal> line provides an + indication of how much data was read from the memory cache + instead of from disk.</para> + + <para>Below the header is a series of columns containing similar + information to the output from &man.ps.1;, such as the + <acronym>PID</acronym>, username, amount of CPU time, and the + command that started the process. By default, &man.top.1; + also displays the amount of memory space taken by the process. + This is split into two columns: one for total size and one for + resident size. Total size is how much memory the application + has needed and the resident size is how much it is actually + using now.</para> + + <para>&man.top.1; automatically updates the display every two + seconds. A different interval can be specified with + <option>-s</option>.</para> + </sect2> - <para>One way to communicate with a daemon, or any running - process, is to send a <firstterm>signal</firstterm> using - &man.kill.1;. There are a number of different signals; some - have a specific meaning while others are described in the - application's documentation. A user can only send a signal to a - process they own and sending a signal to someone else's process - will result in a permission denied error. The exception is the - <username>root</username> user, who can send signals to anyone's - processes.</para> - - <para>&os; can also send a signal to a process. If an application - is badly written and tries to access memory that it is not - supposed to, &os; will send the process the - <firstterm>Segmentation Violation</firstterm> signal - (<literal>SIGSEGV</literal>). If an application has used the - &man.alarm.3; system call to be alerted after a period of time - has elapsed, it will be sent the Alarm signal - (<literal>SIGALRM</literal>).</para> - - <para>Two signals can be used to stop a process: - <literal>SIGTERM</literal> and <literal>SIGKILL</literal>. - <literal>SIGTERM</literal> is the polite way to kill a process - as the process can read the signal, close any log files it may - have open, and attempt to finish what it is doing before - shutting down. In some cases, a process may ignore - <literal>SIGTERM</literal> if it is in the middle of some task - that can not be interrupted.</para> - - <para><literal>SIGKILL</literal> can not be ignored by a process. - This is the <quote>I do not care what you are doing, stop right - now</quote> signal. Sending a <literal>SIGKILL</literal> to a - process will usually stop that process there and then.<footnote> + <sect2 id="basics-daemons"> + <title>Killing Processes</title> + + <para>One way to communicate with any running process or daemon + is to send a <firstterm>signal</firstterm> using &man.kill.1;. + There are a number of different signals; some have a specific + meaning while others are described in the application's + documentation. A user can only send a signal to a process + they own and sending a signal to someone else's process will + result in a permission denied error. The exception is the + <username>root</username> user, who can send signals to + anyone's processes.</para> + + <para>The operating system can also send a signal to a process. + If an application is badly written and tries to access memory + that it is not supposed to, &os; will send the process the + <quote>Segmentation Violation</quote> signal + (<literal>SIGSEGV</literal>). If an application has been + written to use the &man.alarm.3; system call to be alerted + after a period of time has elapsed, it will be sent the + <quote>Alarm</quote> signal + (<literal>SIGALRM</literal>).</para> + + <para>Two signals can be used to stop a process: + <literal>SIGTERM</literal> and <literal>SIGKILL</literal>. + <literal>SIGTERM</literal> is the polite way to kill a process + as the process can read the signal, close any log files it may + have open, and attempt to finish what it is doing before + shutting down. In some cases, a process may ignore + <literal>SIGTERM</literal> if it is in the middle of some task + that can not be interrupted.</para> + + <para><literal>SIGKILL</literal> can not be ignored by a + process. Sending a <literal>SIGKILL</literal> to a + process will usually stop that process there and then. + <footnote> <para>There are a few tasks that can not be interrupted. For example, if the process is trying to read from a file that is on another computer on the network, and the other @@ -2014,90 +3060,91 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse out occurs the process will be killed.</para> </footnote>.</para> - <para>Other commonly used signals are <literal>SIGHUP</literal>, - <literal>SIGUSR1</literal>, and <literal>SIGUSR2</literal>. - These are general purpose signals and different applications - will respond differently.</para> - - <para>For example, after changing a web server's configuration - file, the web server needs to be told to re-read its - configuration. Restarting <command>httpd</command> would result - in a brief outage period on the web server. Instead, send the - daemon the <literal>SIGHUP</literal> signal. Be aware that - different daemons will have different behavior, so refer to the - documentation for the daemon to determine if - <literal>SIGHUP</literal> will achieve the desired - results.</para> - - <procedure> - <title>Sending a Signal to a Process</title> - - <para>This example shows how to send a signal to &man.inetd.8;. - The &man.inetd.8; configuration file is - <filename>/etc/inetd.conf</filename>, and &man.inetd.8; will - re-read this configuration file when it is sent a - <literal>SIGHUP</literal>.</para> - - <step> - <para>Find the <acronym>PID</acronym> of the process to send - the signal to using &man.pgrep.1;. In this example, the - <acronym>PID</acronym> for &man.inetd.8; is 198:</para> - - <screen>&prompt.user; <userinput>pgrep -l inetd</userinput> + <para>Other commonly used signals are <literal>SIGHUP</literal>, + <literal>SIGUSR1</literal>, and <literal>SIGUSR2</literal>. + Since these are general purpose signals, different + applications will respond differently.</para> + + <para>For example, after changing a web server's configuration + file, the web server needs to be told to re-read its + configuration. Restarting <command>httpd</command> would + result in a brief outage period on the web server. Instead, + send the daemon the <literal>SIGHUP</literal> signal. Be + aware that different daemons will have different behavior, so + refer to the documentation for the daemon to determine if + <literal>SIGHUP</literal> will achieve the desired + results.</para> + + <procedure> + <title>Sending a Signal to a Process</title> + + <para>This example shows how to send a signal to + &man.inetd.8;. The &man.inetd.8; configuration file is + <filename>/etc/inetd.conf</filename>, and &man.inetd.8; will + re-read this configuration file when it is sent a + <literal>SIGHUP</literal>.</para> + + <step> + <para>Find the <acronym>PID</acronym> of the process to send + the signal to using &man.pgrep.1;. In this example, the + <acronym>PID</acronym> for &man.inetd.8; is 198:</para> + + <screen>&prompt.user; <userinput>pgrep -l inetd</userinput> 198 inetd -wW</screen> - </step> + </step> - <step> - <para>Use &man.kill.1; to send the signal. Because - &man.inetd.8; is owned by <username>root</username>, use - &man.su.1; to become <username>root</username> first.</para> + <step> + <para>Use &man.kill.1; to send the signal. Because + &man.inetd.8; is owned by <username>root</username>, use + &man.su.1; to become <username>root</username> + first.</para> - <screen>&prompt.user; <userinput>su</userinput> + <screen>&prompt.user; <userinput>su</userinput> <prompt>Password:</prompt> &prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen> - <para>Like most &unix; commands, &man.kill.1; will not print - any output if it is successful. If a signal is sent to a - process not owned by that user, the message - <errorname>kill: <replaceable>PID</replaceable>: Operation - not permitted</errorname> will be displayed. Mistyping - the <acronym>PID</acronym> will either send the signal to - the wrong process, which could have negative results, or - will send the signal to a <acronym>PID</acronym> that is - not currently in use, resulting in the error - <errorname>kill: <replaceable>PID</replaceable>: No such - process</errorname>.</para> - - <note> - <title>Why Use <command>/bin/kill</command>?</title> - - <para>Many shells provide <command>kill</command> as a built - in command, meaning that the shell will send the signal - directly, rather than running - <filename>/bin/kill</filename>. Be aware that different - shells have a different syntax for specifying the name of - the signal to send. Rather than try to learn all of them, - it can be simpler to use <command>/bin/kill - <replaceable>...</replaceable></command> - directly.</para> - </note> - </step> - </procedure> - - <para>When sending other signals, substitute - <literal>TERM</literal> or <literal>KILL</literal> in the - command line as necessary.</para> - - <important> - <para>Killing a random process on the system can be a bad idea. - In particular, &man.init.8;, <acronym>PID</acronym> 1, is - special. Running <command>/bin/kill -s KILL 1</command> is - a quick, and unrecommended, way to shutdown the system. - <emphasis>Always</emphasis> double check the arguments to - &man.kill.1; <emphasis>before</emphasis> pressing - <keycap>Return</keycap>.</para> - </important> + <para>Like most &unix; commands, &man.kill.1; will not print + any output if it is successful. If a signal is sent to a + process not owned by that user, the message + <errorname>kill: <replaceable>PID</replaceable>: Operation + not permitted</errorname> will be displayed. Mistyping + the <acronym>PID</acronym> will either send the signal to + the wrong process, which could have negative results, or + will send the signal to a <acronym>PID</acronym> that is + not currently in use, resulting in the error + <errorname>kill: <replaceable>PID</replaceable>: No such + process</errorname>.</para> + + <note> + <title>Why Use <command>/bin/kill</command>?</title> + + <para>Many shells provide <command>kill</command> as a + built in command, meaning that the shell will send the + signal directly, rather than running + <filename>/bin/kill</filename>. Be aware that different + shells have a different syntax for specifying the name + of the signal to send. Rather than try to learn all of + them, it can be simpler to specify + <command>/bin/kill</command>.</para> + </note> + </step> + </procedure> + + <para>When sending other signals, substitute + <literal>TERM</literal> or <literal>KILL</literal> with the + name of the signal.</para> + + <important> + <para>Killing a random process on the system is a bad idea. + In particular, &man.init.8;, <acronym>PID</acronym> 1, is + special. Running <command>/bin/kill -s KILL 1</command> is + a quick, and unrecommended, way to shutdown the system. + <emphasis>Always</emphasis> double check the arguments to + &man.kill.1; <emphasis>before</emphasis> pressing + <keycap>Return</keycap>.</para> + </important> + </sect2> </sect1> <sect1 id="shells"> @@ -2106,14 +3153,15 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <indexterm><primary>shells</primary></indexterm> <indexterm><primary>command line</primary></indexterm> - <para>&os; provides a command line interface called a shell. A - shell receives commands from the input channel and executes - them. Many shells provide built in functions to help with - everyday tasks such as file management, file globbing, command - line editing, command macros, and environment variables. &os; - comes with several shells, including the Bourne shell - (&man.sh.1;) and the extended C shell (&man.tcsh.1;). Other - shells are available from the &os; Ports Collection, such as + <para>A <firstterm>shell</firstterm> provides a command line + interface for interacting with the operating system. A shell + receives commands from the input channel and executes them. + Many shells provide built in functions to help with everyday + tasks such as file management, file globbing, command line + editing, command macros, and environment variables. &os; comes + with several shells, including the Bourne shell (&man.sh.1;) and + the extended C shell (&man.tcsh.1;). Other shells are available + from the &os; Ports Collection, such as <command>zsh</command> and <command>bash</command>.</para> <para>The shell that is used is really a matter of taste. A C @@ -2125,23 +3173,22 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <para>One common shell feature is filename completion. After a user types the first few letters of a command or filename and - presses <keycap>Tab</keycap>, the shell will automatically - complete the rest of the command or filename. Consider two - files called <filename>foobar</filename> and - <filename>foo.bar</filename>. To delete - <filename>foo.bar</filename>, type <command>rm + presses <keycap>Tab</keycap>, the shell automatically completes + the rest of the command or filename. Consider two files called + <filename>foobar</filename> and <filename>foo.bar</filename>. + To delete <filename>foo.bar</filename>, type <command>rm fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para> - <para>The shell should print out <command>rm - foo[BEEP].bar</command>.</para> + <para>The shell should print out + <command>rm foo[BEEP].bar</command>.</para> <para>The [BEEP] is the console bell, which the shell used to indicate it was unable to complete the filename because there is more than one match. Both <filename>foobar</filename> and <filename>foo.bar</filename> start with <literal>fo</literal>. By typing <literal>.</literal>, then pressing - <keycap>Tab</keycap> again, the shell would be able to fill in - the rest of the filename.</para> + <keycap>Tab</keycap> again, the shell is able to fill in the + rest of the filename.</para> <indexterm><primary>environment variables</primary></indexterm> @@ -2149,10 +3196,13 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse variables. Environment variables are a variable/key pair stored in the shell's environment. This environment can be read by any program invoked by the shell, and thus contains a lot of program - configuration. Here is a list of common environment variables - and their meanings:</para> + configuration. Table 4.3 provides a list of common environment + variables and their meanings. Note that the names of + environment variables are always in uppercase.</para> + + <table frame="none" pgwide="1"> + <title>Common Environment Variables</title> - <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> @@ -2216,7 +3266,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <row> <entry><envar>PAGER</envar></entry> - <entry>The user's preferred text pager.</entry> + <entry>The user's preferred utility for viewing text one + page at a time.</entry> </row> <row> @@ -2226,7 +3277,7 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse </row> </tbody> </tgroup> - </informaltable> + </table> <indexterm><primary>Bourne shells</primary></indexterm> @@ -2255,28 +3306,29 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <para>Shells treat special characters, known as meta-characters, as special representations of data. The most common meta-character is <literal>*</literal>, which represents any - number of characters in a filename. Meta-characters can be - used to perform filename globbing. For example, <command>echo - *</command> is equivalent to &man.ls.1; because the shell - takes all the files that match <literal>*</literal> and - &man.echo.1; lists them on the command line.</para> + number of characters in a filename. Meta-characters can be used + to perform filename globbing. For example, <command>echo + *</command> is equivalent to <command>ls</command> because + the shell takes all the files that match <literal>*</literal> + and <command>echo</command> lists them on the command + line.</para> <para>To prevent the shell from interpreting a special character, escape it from the shell by starting it with a backslash - (<literal>\</literal>). For example, - <command>echo $TERM</command> prints the terminal setting - whereas <command>echo \$TERM</command> literally prints the - string <literal>$TERM</literal>.</para> + (<literal>\</literal>). For example, <command>echo + $TERM</command> prints the terminal setting whereas + <command>echo \$TERM</command> literally prints the string + <literal>$TERM</literal>.</para> <sect2 id="changing-shells"> - <title>Changing Your Shell</title> + <title>Changing the Shell</title> <para>The easiest way to permanently change the default shell is to use <command>chsh</command>. Running this command will open the editor that is configured in the <envar>EDITOR</envar> environment variable, which by default - is set to &man.vi.1;. Change the <quote>Shell:</quote> line - to the full path of the new shell.</para> + is set to &man.vi.1;. Change the <literal>Shell:</literal> + line to the full path of the new shell.</para> <para>Alternately, use <command>chsh -s</command> which will set the specified shell without opening an editor. For example, @@ -2289,13 +3341,12 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <filename>/etc/shells</filename>. If the shell was installed from the &os; Ports Collection as described in <xref linkend="ports"/>, it should be automatically added - to this file. If it is missing, add it using this - command, replacing the path with the path of the - shell:</para> + to this file. If it is missing, add it using this command, + replacing the path with the path of the shell:</para> <screen>&prompt.root; <userinput>echo <replaceable>/usr/local/bin/bash</replaceable> >> /etc/shells</userinput></screen> - <para>Then rerun &man.chsh.1;.</para> + <para>Then, rerun &man.chsh.1;.</para> </note> </sect2> </sect1> @@ -2325,43 +3376,38 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <replaceable>filename</replaceable> is the name of the file to be edited. Once inside the editor, all of the commands for manipulating the editor's functions are listed at the top of the - display. The caret <literal>^</literal> represents + display. The caret (<literal>^</literal>) represents <keycap>Ctrl</keycap>, so <literal>^e</literal> expands to <keycombo action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>. - To leave &man.ee.1;, press <keycap>Esc</keycap>, then choose - the <quote>leave editor</quote> option from the main menu. - The editor will prompt to save any changes if the file has been + To leave &man.ee.1;, press <keycap>Esc</keycap>, then choose the + <quote>leave editor</quote> option from the main menu. The + editor will prompt to save any changes if the file has been modified.</para> <indexterm> - <primary>&man.vi.1;</primary> + <primary><command>vi</command></primary> </indexterm> <indexterm> <primary>editors</primary> - <secondary>&man.vi.1;</secondary> </indexterm> <indexterm> <primary><command>emacs</command></primary> </indexterm> - <indexterm> - <primary>editors</primary> - <secondary><command>emacs</command></secondary> - </indexterm> <para>&os; also comes with more powerful text editors, such as &man.vi.1;, as part of the base system. Other editors, like <filename role="package">editors/emacs</filename> and <filename role="package">editors/vim</filename>, are part of the &os; Ports Collection. These editors offer more functionality - at the expense of being a more complicated to learn. Learning a + at the expense of being more complicated to learn. Learning a more powerful editor such as <application>vim</application> or <application>Emacs</application> can save more time in the long run.</para> <para>Many applications which modify files or require typed input - will automatically open a text editor. To alter the default - editor used, set the <envar>EDITOR</envar> environment + will automatically open a text editor. To change the default + editor, set the <envar>EDITOR</envar> environment variable as described in <xref linkend="shells"/>.</para> </sect1> @@ -2385,252 +3431,101 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <filename class="directory">/dev</filename>.</para> </sect1> - <sect1 id="binary-formats"> - <title>Binary Formats</title> + <sect1 id="basics-more-information"> + <title>Manual Pages</title> - <para>Typically when a command is passed to the shell, the shell - will arrange for an executable file to be loaded into memory and - a new process is created. Executable files can either be a binary - file (usually created by the linker as part of compiling a program) - or a shell script (text file to be interpreted by a binary file, - like &man.sh.1; or &man.perl.1;). The &man.file.1; command can - usually determine what is inside a file.</para> + <indexterm><primary>manual pages</primary></indexterm> - <para>Binary files need to have a well defined format for the system - to be able to use them properly. Part of the file will be the - executable machine code (the instructions that tell the CPU what - to do), part of it will be data space with pre-defined values, - part will be data space with no pre-defined values, etc. Through - time, different binary file formats have evolved.</para> + <para>The most comprehensive documentation on &os; is in the form + of manual pages. Nearly every program on the system comes with + a short reference manual explaining the basic operation and + available arguments. These manuals can be viewed using + <command>man</command>:</para> - <para>To understand why &os; uses the &man.elf.5; format, the three - currently <quote>dominant</quote>, executable formats for &unix; - must be described:</para> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - <itemizedlist> + <para>where <replaceable>command</replaceable> is the name of the + command to learn about. For example, to learn more about + &man.ls.1;, type:</para> + + <screen>&prompt.user; <userinput>man ls</userinput></screen> + + <para>Manual pages are divided into sections which represent the + type of topic. In &os;, the following sections are + available:</para> + + <orderedlist> <listitem> - <para>&man.a.out.5;</para> - - <para>The oldest and <quote>classic</quote> &unix; object - format. It uses a short and compact header with a - &man.magic.5; number at the beginning that is often used to - characterize the format. It contains three loaded segments: - .text, .data, and .bss, plus a symbol table and a string - table.</para> + <para>User commands.</para> </listitem> <listitem> - <para><acronym>COFF</acronym></para> - - <para>The SVR3 object format. The header comprises a section - table which can contain more than just .text, .data, and - .bss sections.</para> + <para>System calls and error numbers.</para> </listitem> <listitem> - <para>&man.elf.5;</para> - - <para>The successor to <acronym>COFF</acronym>, featuring - multiple sections and 32-bit or 64-bit possible values. One - major drawback is that <acronym>ELF</acronym> was designed - with the assumption that there would be only one ABI per - system architecture. That assumption is actually incorrect, - and not even in the commercial SYSV world (which has at - least three ABIs: SVR4, Solaris, SCO) does it hold - true.</para> - - <para>&os; tries to work around this problem somewhat by - providing a utility for <emphasis>branding</emphasis> a - known <acronym>ELF</acronym> executable with information - about its compliant ABI. Refer to &man.brandelf.1; for more - information.</para> + <para>Functions in the C libraries.</para> </listitem> - </itemizedlist> - - <para>&os; comes from the <quote>classic</quote> camp and used - the &man.a.out.5; format, a technology tried and proven through - many generations of BSD releases, until the beginning of the 3.X - branch. Though it was possible to build and run native - <acronym>ELF</acronym> binaries and kernels on a &os; system - for some time before that, &os; initially resisted the - <quote>push</quote> to switch to <acronym>ELF</acronym> as the - default format. Why? When Linux made its painful transition to - <acronym>ELF</acronym>, it was due to their inflexible - jump-table based shared library mechanism, which made the - construction of shared libraries difficult for vendors and - developers. Since <acronym>ELF</acronym> tools offered a - solution to the shared library problem and were generally seen - as <quote>the way forward</quote>, the migration cost was - accepted as necessary and the transition made. &os;'s shared - library mechanism is based more closely on the &sunos; style - shared library mechanism and is easy to use.</para> - - <para>So, why are there so many different formats? Back in the - PDP-11 days when simple hardware supported a simple, small - system, <filename>a.out</filename> was adequate for the job of - representing binaries. As &unix; was ported, the - <filename>a.out</filename> format was retained because it was - sufficient for the early ports of &unix; to architectures like - the Motorola 68k or VAXen.</para> - - <para>Then some hardware engineer decided that if he could force - software to do some sleazy tricks, a few gates could be shaved - off the design and the CPU core could run faster. - <filename>a.out</filename> was ill-suited for this new kind of - hardware, known as <acronym>RISC</acronym>. Many formats were - developed to get better performance from this hardware than the - limited, simple <filename>a.out</filename> format could offer. - <acronym>COFF</acronym>, <acronym>ECOFF</acronym>, and a few - others were invented and their limitations explored before - settling on <acronym>ELF</acronym>.</para> - - <para>In addition, program sizes were getting huge while disks - and physical memory were still relatively small, so the concept - of a shared library was born. The virtual memory system became - more sophisticated. While each advancement was done using the - <filename>a.out</filename> format, its usefulness was stretched - with each new feature. In addition, people wanted to - dynamically load things at run time, or to junk parts of their - program after the init code had run to save in core memory and - swap space. Languages became more sophisticated and people - wanted code called before the main() function automatically. - Lots of hacks were done to the <filename>a.out</filename> format - to allow all of these things to happen, and they basically - worked for a time. In time, <filename>a.out</filename> was not - up to handling all these problems without an ever increasing - overhead in code and complexity. While <acronym>ELF</acronym> - solved many of these problems, it would be painful to switch - from the system that basically worked. So - <acronym>ELF</acronym> had to wait until it was more painful to - remain with <filename>a.out</filename> than it was to migrate to - <acronym>ELF</acronym>.</para> - - <para>As time passed, the build tools that &os; derived their - build tools from, especially the assembler and loader, evolved - in two parallel trees. The &os; tree added shared libraries and - fixed some bugs. The GNU folks that originally wrote these - programs rewrote them and added simpler support for building - cross compilers and plugging in different formats. Those who - wanted to build cross compilers targeting &os; were out of luck - since the older sources that &os; had for &man.as.1; and - &man.ld.1; were not up to the task. The new GNU tools chain - (<application>binutils</application>) supports cross - compiling, <acronym>ELF</acronym>, shared libraries, and C++ - extensions. In addition, many vendors release - <acronym>ELF</acronym> binaries, and &os; should be able to run - them.</para> - - <para><acronym>ELF</acronym> is more expressive than - <filename>a.out</filename> and allows more extensibility in the - base system. The <acronym>ELF</acronym> tools are better - maintained and offer cross compilation support. - <acronym>ELF</acronym> may be a little slower than - <filename>a.out</filename>, but trying to measure it can be - difficult. There are also numerous details that are different - between the two such as how they map pages and handle init - code.</para> - </sect1> - - <sect1 id="basics-more-information"> - <title>For More Information</title> - - <sect2 id="basics-man"> - <title>Manual Pages</title> - <indexterm><primary>manual pages</primary></indexterm> - - <para>The most comprehensive documentation on &os; is in the - form of manual pages. Nearly every program on the system - comes with a short reference manual explaining the basic - operation and available arguments. These manuals can be - viewed using <command>man</command>:</para> - - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - - <para>where <replaceable>command</replaceable> is the name of - the command to learn about. For example, to learn more about - &man.ls.1;, type:</para> - - <screen>&prompt.user; <userinput>man ls</userinput></screen> - - <para>The online manual is divided into numbered - sections:</para> - - <orderedlist> - <listitem> - <para>User commands.</para> - </listitem> - - <listitem> - <para>System calls and error numbers.</para> - </listitem> - - <listitem> - <para>Functions in the C libraries.</para> - </listitem> - - <listitem> - <para>Device drivers.</para> - </listitem> - - <listitem> - <para>File formats.</para> - </listitem> + <listitem> + <para>Device drivers.</para> + </listitem> - <listitem> - <para>Games and other diversions.</para> - </listitem> + <listitem> + <para>File formats.</para> + </listitem> - <listitem> - <para>Miscellaneous information.</para> - </listitem> + <listitem> + <para>Games and other diversions.</para> + </listitem> - <listitem> - <para>System maintenance and operation commands.</para> - </listitem> + <listitem> + <para>Miscellaneous information.</para> + </listitem> - <listitem> - <para>Kernel developers.</para> - </listitem> - </orderedlist> + <listitem> + <para>System maintenance and operation commands.</para> + </listitem> - <para>In some cases, the same topic may appear in more than one - section of the online manual. For example, there is a - &man.chmod.1; user command and a - <function>chmod()</function> system call. To tell &man.man.1; - which section to display, specify the section number:</para> + <listitem> + <para>System kernel interfaces.</para> + </listitem> + </orderedlist> - <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> + <para>In some cases, the same topic may appear in more than one + section of the online manual. For example, there is a + <command>chmod</command> user command and a + <function>chmod()</function> system call. To tell &man.man.1; + which section to display, specify the section number:</para> - <para>This will display the manual page for the user command - &man.chmod.1;. References to a particular section of the - online manual are traditionally placed in parenthesis in - written documentation, so &man.chmod.1; refers to the user - command and &man.chmod.2; refers to the system call.</para> + <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> - <para>If the command name is unknown, use <command>man - -k</command> to search for keywords in the command - descriptions:</para> + <para>This will display the manual page for the user command + &man.chmod.1;. References to a particular section of the + online manual are traditionally placed in parenthesis in + written documentation, so &man.chmod.1; refers to the user + command and &man.chmod.2; refers to the system call.</para> - <screen>&prompt.user; <userinput>man -k <replaceable>mail</replaceable></userinput></screen> + <para>If the name of the manual page is unknown, use <command>man + -k</command> to search for keywords in the manual page + descriptions:</para> - <para>This command displays a list of commands that have the - keyword <quote>mail</quote> in their descriptions. This is - equivalent to using &man.apropos.1;.</para> + <screen>&prompt.user; <userinput>man -k <replaceable>mail</replaceable></userinput></screen> - <para>To determine what the commands in <filename - class="directory">/usr/bin</filename> do, - type:</para> + <para>This command displays a list of commands that have the + keyword <quote>mail</quote> in their descriptions. This is + equivalent to using &man.apropos.1;.</para> - <screen>&prompt.user; <userinput>cd /usr/bin</userinput> -&prompt.user; <userinput>man -f *</userinput></screen> + <para>To read the descriptions for the commands in <filename + class="directory">/usr/bin</filename>, type:</para> - <para>or</para> + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>man -f * | more</userinput></screen> - <screen>&prompt.user; <userinput>cd /usr/bin</userinput> -&prompt.user; <userinput>whatis *</userinput></screen> + <para>or</para> - </sect2> + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>whatis * |more</userinput></screen> <sect2 id="basics-info"> <title>GNU Info Files</title> @@ -2639,8 +3534,8 @@ Swap: 256M Total, 38M Used, 217M Free, 15% Inuse <primary>Free Software Foundation</primary> </indexterm> - <para>&os; includes many applications and utilities produced - by the Free Software Foundation (FSF). In addition to manual + <para>&os; includes many applications and utilities produced by + the Free Software Foundation (FSF). In addition to manual pages, these programs may include hypertext documents called <literal>info</literal> files. These can be viewed using &man.info.1; or, if <filename diff --git a/en_US.ISO8859-1/books/handbook/book.xml b/en_US.ISO8859-1/books/handbook/book.xml index a57a40a806..59144256ac 100644 --- a/en_US.ISO8859-1/books/handbook/book.xml +++ b/en_US.ISO8859-1/books/handbook/book.xml @@ -66,14 +66,11 @@ &tm-attrib.linux; &tm-attrib.lsilogic; &tm-attrib.m-systems; - &tm-attrib.macromedia; &tm-attrib.microsoft; - &tm-attrib.nexthop; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.realnetworks; &tm-attrib.redhat; - &tm-attrib.sap; &tm-attrib.sun; &tm-attrib.themathworks; &tm-attrib.thomson; @@ -228,7 +225,6 @@ &chap.config; &chap.boot; - &chap.users; &chap.security; &chap.jails; &chap.mac; diff --git a/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml index 818dc7c981..70e676e6c6 100644 --- a/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml @@ -936,7 +936,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>Check the probe results carefully to make sure that &os; found all the devices you expected. If a device was not found, then it will not be listed. <link - linkend="kernelconfig-modules">Kernel modules</link> allows + linkend="kernelconfig-custom-kernel">Kernel modules</link> allows you to add in support for devices which are not in the <filename>GENERIC</filename> kernel.</para> @@ -2291,7 +2291,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> installation.</para> <para>For more information on adding users and user management, - see <xref linkend="users"/>.</para> + see <xref linkend="users-synopsis"/>.</para> </sect2> <sect2 id="bsdinstall-final-conf"> diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent index f69b85229c..0bcc64c5d7 100644 --- a/en_US.ISO8859-1/books/handbook/chapters.ent +++ b/en_US.ISO8859-1/books/handbook/chapters.ent @@ -31,7 +31,6 @@ <!-- Part Three --> <!ENTITY chap.config SYSTEM "config/chapter.xml"> <!ENTITY chap.boot SYSTEM "boot/chapter.xml"> - <!ENTITY chap.users SYSTEM "users/chapter.xml"> <!ENTITY chap.security SYSTEM "security/chapter.xml"> <!ENTITY chap.jails SYSTEM "jails/chapter.xml"> <!ENTITY chap.mac SYSTEM "mac/chapter.xml"> diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml index 03aa4ce849..8f7638c6fe 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -1527,7 +1527,7 @@ Fetching 133 new ports or files... done.</screen> <secondary>syncing with <application>Subversion</application></secondary> </indexterm> - or <literal>releng/9.0</literal>. URL prefixes for + or <literal>releng/9.2</literal>. URL prefixes for <application>Subversion</application> checkout of the base system are shown in <link linkend="svn-mirrors">Subversion mirror @@ -1918,11 +1918,22 @@ Fetching 133 new ports or files... done.</screen> <para>After <maketarget>installkernel</maketarget> finishes successfully, boot into single user mode using <command>boot - -s</command> from the loader prompt. Then run:</para> + -s</command> from the loader prompt.</para> + + <para>If using UFS, run:</para> + <screen>&prompt.root; <userinput>mount -u /</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> -&prompt.root; <userinput>adjkerntz -i</userinput> +&prompt.root; <userinput>mount -a -t ufs</userinput></screen> + + <para>If using ZFS(assuming a zpool name of zroot), run:</para> + + <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput> +&prompt.root; <userinput>zfs mount -a</userinput></screen> + + <para>Then run:</para> + + <screen>&prompt.root; <userinput>adjkerntz -i</userinput> &prompt.root; <userinput>mergemaster -p</userinput> &prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make installworld</userinput> diff --git a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml index b26d01401e..ac7256323f 100644 --- a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml @@ -5,6 +5,7 @@ --> <chapter id="desktop"> + <!-- <chapterinfo> <authorgroup> <author> @@ -14,6 +15,7 @@ </author> </authorgroup> </chapterinfo> + --> <title>Desktop Applications</title> @@ -22,13 +24,19 @@ <para>While &os; is popular as a server for its performance and stability, it is also suited for day-to-day use as a desktop. - With over &os.numports; applications available as <link - linkend="packages-using">packages</link> or <link - linkend="ports-using">ports</link>, it is easy to build a - customized desktop that runs a wide variety of desktop - applications. This chapter demonstrates how to install some - popular desktop applications effortlessly using packages or the - &os; Ports Collection.</para> + With over &os.numports; applications available as &os; packages + or ports, it is easy to build a customized desktop that runs + a wide variety of desktop applications. This chapter + demonstrates how to install some popular desktop applications + using packages or the &os; Ports Collection.</para> + + <note> + <para>Users who prefer to install a pre-built desktop version + of FreeBSD rather than configuring one from scratch should + refer to the <ulink + url="http://www.pcbsd.org/">pcbsd.org + website.</ulink></para> + </note> <para>As &os; features <link linkend="linuxemu">&linux; binary compatibility</link>, many applications developed for &linux; @@ -115,7 +123,7 @@ OpenOffice</application></entry> <entry><literal>openoffice</literal></entry> <entry><filename - role="package">editors/openoffice-3</filename></entry> + role="package">editors/openoffice-4</filename></entry> </row> <row> @@ -191,18 +199,22 @@ <itemizedlist> <listitem> <para>Install additional software using packages or - ports.</para> + ports as described in <xref linkend="ports"/>.</para> </listitem> <listitem> - <para>Enable &linux; binary compatibility.</para> + <para>Install X and a window manager as described in <xref + linkend="x11"/>.</para> + </listitem> + + <listitem> + <para>Enable &linux; binary compatibility as described in + <xref linkend="linuxemu"/>.</para> </listitem> </itemizedlist> <para>For information on how to configure a multimedia - environment, refer to <xref linkend="multimedia"/>. For - information on how to set up and use electronic mail, refer to - <xref linkend="mail"/>.</para> + environment, refer to <xref linkend="multimedia"/>.</para> </sect1> <sect1 id="desktop-browsers"> @@ -226,10 +238,10 @@ for more information on how to set up these complete desktops.</para> - <para>Some light-weight browsers include - <filename role="package">www/dillo2</filename>, - <filename role="package">www/links</filename>, and - <filename role="package">www/w3m</filename>.</para> + <para>Some light-weight browsers include <filename + role="package">www/dillo2</filename>, <filename + role="package">www/links</filename>, and <filename + role="package">www/w3m</filename>.</para> <para>This section demonstrates how to install the following popular web browsers and indicates if the application is @@ -252,7 +264,8 @@ <entry><application>Firefox</application></entry> <entry>medium</entry> <entry>heavy</entry> - <entry>&os; and &linux; versions are available</entry> + <entry>&os;, &linux;, and localized versions are + available</entry> </row> <row> @@ -287,15 +300,15 @@ <primary><application>Firefox</application></primary> </indexterm> - <para><application>Firefox</application> is a modern, free, - open source browser that is fully ported to &os;. It - features a standards-compliant HTML display engine, tabbed - browsing, popup blocking, extensions, improved security, and - more. <application>Firefox</application> is based on the + <para><application>Firefox</application> is an open source + browser that is fully ported to &os;. It features a + standards-compliant HTML display engine, tabbed browsing, + popup blocking, extensions, improved security, and more. + <application>Firefox</application> is based on the <application>Mozilla</application> codebase.</para> - <para>Install the package of the latest release version of - <application>Firefox</application> by typing:</para> + <para>To install the package of the latest release version of + <application>Firefox</application>, type:</para> <screen>&prompt.root; <userinput>pkg_add -r firefox</userinput></screen> @@ -308,8 +321,8 @@ role="package">www/firefox-i18n</filename> and <filename role="package">www/firefox-esr-i18n</filename>.</para> - <para>The Ports Collection can instead be used to compile - the desired version of <application>firefox</application> from + <para>The Ports Collection can instead be used to compile the + desired version of <application>Firefox</application> from source code. This example builds <filename role="package">www/firefox</filename>, where <literal>firefox</literal> can be replaced with the ESR or @@ -321,16 +334,13 @@ <sect3 id="moz-java-plugin"> <title>Firefox and &java; Plugin</title> - <note> - <para>The following sections assume that - <application>Firefox</application> is already - installed.</para> - </note> - - <para><filename role="package">java/icedtea-web</filename> - provides a free software web browser plugin for running - Java applets. It can be installed as a package. To - alternately compile the port:</para> + <para>The installation of + <application>Firefox</application> does not include &java; + support. However, <filename + role="package">java/icedtea-web</filename> provides a free + software web browser plugin for running Java applets. It can + be installed as a package. To alternately compile the + port:</para> <screen>&prompt.root; <userinput>cd /usr/ports/java/icedtea-web</userinput> &prompt.root; <userinput>make install clean</userinput></screen> @@ -362,11 +372,12 @@ </indexterm> <para>A native &adobe; &flash; plugin is not available for &os;. - However, a software layer (wrapper) for running the &linux; - version of the plugin exists. This wrapper also provides + However, a software wrapper for running the &linux; version + of the plugin is available. This wrapper also provides support for other browser plugins such as &realplayer;.</para> - <para>To install and enable this plugin:</para> + <para>To install and enable this plugin, perform these + steps:</para> <procedure> <step> @@ -395,18 +406,20 @@ </step> <step> - <para>Before the plugin is first used, each user must run:</para> + <para>Before the plugin is first used, each user must + run:</para> <screen>&prompt.user; <userinput>nspluginwrapper -v -a -i</userinput></screen> - <para>When the plugin port has been updated and reinstalled, each user must run:</para> + <para>When the plugin port has been updated and reinstalled, + each user must run:</para> <screen>&prompt.user; <userinput>nspluginwrapper -v -a -u</userinput></screen> <para>Start the browser, enter <literal>about:plugins</literal> in the location bar and - press <keycap>Enter</keycap>. A list of - all the currently available plugins will be shown.</para> + press <keycap>Enter</keycap>. A list of all the currently + available plugins will be shown.</para> </step> </procedure> @@ -415,11 +428,11 @@ <sect3 id="moz-swfdec-flash-plugin"> <title>Firefox and Swfdec &flash; Plugin</title> - <para>Swfdec is the library for decoding and rendering &flash; - animations. Swfdec-Mozilla is a plugin for + <para><application>Swfdec</application> is a decoder and + renderer for &flash; animations. + <application>Swfdec-Mozilla</application> is a plugin for <application>Firefox</application> browsers that uses the - Swfdec library for playing SWF files. It is still in heavy - development.</para> + Swfdec library for playing SWF files.</para> <para>To install the package:</para> @@ -431,8 +444,7 @@ <screen>&prompt.root; <userinput>cd /usr/ports/www/swfdec-plugin</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <para>Restart the browser for this plugin to take - effect.</para> + <para>Restart the browser to activate this plugin.</para> </sect3> </sect2> @@ -473,7 +485,8 @@ as a package is not available due to licensing restrictions. Then install either the <filename role="package">www/opera-linuxplugins</filename> port - or package. This example compiles both from ports:</para> + or package. This example compiles both applications from + ports:</para> <screen>&prompt.root; <userinput>cd /usr/ports/www/linux-f10-flashplugin11</userinput> &prompt.root; <userinput>make install clean</userinput> @@ -487,8 +500,8 @@ all the currently available plugins.</para> <para>To add the <application>&java;</application> plugin, - follow the <link linkend="moz-java-plugin">instructions for - Firefox</link>.</para> + follow the instructions in <xref + linkend="moz-java-plugin"/>.</para> </sect2> <sect2> @@ -498,19 +511,18 @@ <primary><application>Konqueror</application></primary> </indexterm> - <para><application>Konqueror</application> is part of <filename - role="package">x11/kde4-baseapps</filename>. - <application>Konqueror</application> is more than a web + <para><application>Konqueror</application> is more than a web browser as it is also a file manager and a multimedia - viewer.</para> + viewer. It is included in the <filename + role="package">x11/kde4-baseapps</filename> package or + port.</para> <para><application>Konqueror</application> supports WebKit as well as its own KHTML. WebKit is a rendering engine used by many modern browsers including Chromium. To use WebKit with - <application>Konqueror</application> on &os;, install - the <filename - role="package">www/kwebkitpart</filename> package or - port. This example compiles the port:</para> + <application>Konqueror</application> on &os;, install the + <filename role="package">www/kwebkitpart</filename> package + or port. This example compiles the port:</para> <screen>&prompt.root; <userinput>cd /usr/ports/www/kwebkitpart</userinput> &prompt.root; <userinput>make install clean</userinput></screen> @@ -565,23 +577,19 @@ <sect3 id="chromium-java-plugin"> <title>Chromium and &java; Plugin</title> - <note> - <para>The following sections assume that - <application>Chromium</application> is already - installed.</para> - </note> - - <para>To install &java; plugin support, follow the instructions - in <xref linkend="moz-java-plugin"/>.</para> + <para>The installation of + <application>Chromium</application> does not include &java; + support. To install &java; plugin support, follow the + instructions in <xref linkend="moz-java-plugin"/>.</para> <para>Once &java; support is installed, start - <application>Chromium</application>, and enter + <application>Chromium</application> and enter <literal>about:plugins</literal> in the address bar. IcedTea-Web should be listed as one of the installed plugins.</para> <para>If <application>Chromium</application> does not display - the IcedTea-Web plugin, run the following commands, and + the IcedTea-Web plugin, run the following commands and restart the web browser:</para> <screen>&prompt.root; <userinput>mkdir -p /usr/local/share/chromium/plugins @@ -593,11 +601,11 @@ <title>Chromium and &adobe; &flash; Plugin</title> <para>Configuring <application>Chromium</application> and - &adobe; &flash; is similar to the - <link linkend="moz-flash-plugin">instructions for - Firefox</link>. No additional configuration should be - necessary, since <application>Chromium</application> is able - to use some plugins from other browsers.</para> + &adobe; &flash; is similar to the the instructions in + <xref linkend="moz-java-plugin"/>. No additional + configuration should be necessary, since + <application>Chromium</application> is able to use some + plugins from other browsers.</para> </sect3> </sect2> </sect1> @@ -605,13 +613,13 @@ <sect1 id="desktop-productivity"> <title>Productivity</title> - <para>When it comes to productivity, new users often look for a - good office suite or a friendly word processor. While some + <para>When it comes to productivity, new users often look for an + office suite or an easy-to-use word processor. While some <link linkend="x11-wm">desktop environments</link> like - <application>KDE</application> already provide an office suite, - there is no default productivity package. Several office - suites and word processors are available for &os;, regardless - of the installed desktop environment.</para> + <application>KDE</application> provide an office suite, there + is no default productivity package. Several office suites and + graphical word processors are available for &os;, regardless + of the installed window manager.</para> <para>This section demonstrates how to install the following popular productivity software and indicates if the application @@ -685,8 +693,8 @@ <secondary><application>Calligra</application></secondary> </indexterm> - <para>The KDE community provides its desktop environment with - an office suite which can be used outside of + <para>The KDE desktop environment includes + an office suite which can be installed separately from <application>KDE</application>. <application>Calligra</application> includes standard components that can be found in other office suites. @@ -696,7 +704,7 @@ and <application>Karbon</application> is used to draw graphical documents.</para> - <para><filename + <para>In &os;, <filename role="package">editors/calligra</filename> can be installed as a package or a port. To install the package:</para> @@ -718,13 +726,12 @@ <para><application>AbiWord</application> is a free word processing program similar in look and feel to - <application>µsoft; Word</application>. It is suitable - for typing papers, letters, reports, memos, and so forth. It - is fast, contains many features, and is user-friendly.</para> + <application>µsoft; Word</application>. It is fast, + contains many features, and is user-friendly.</para> <para><application>AbiWord</application> can import or export many file formats, including some proprietary ones like - µsoft; <filename>.doc</filename>.</para> + µsoft; <filename>.rtf</filename>.</para> <para>To install the <application>AbiWord</application> package:</para> @@ -763,11 +770,11 @@ <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <para>The <ulink - url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink> - category of the Ports Collection contains several - <application>GIMP</application>-related plugins, help - files, and user manuals.</para> + <para>The graphics category (<ulink + url="http://www.FreeBSD.org/ports/graphics.html">freebsd.org/ports/graphics.html</ulink>) + of the Ports Collection contains several + <application>GIMP</application>-related plugins, help files, + and user manuals.</para> </sect2> @@ -786,76 +793,54 @@ </secondary> </indexterm> - <para>On 1 June 2011, &oracle; donated the - <application>OpenOffice.org</application> code base to the - Apache Software Foundation. - <application>OpenOffice.org</application> is now known as - <application>Apache OpenOffice</application> and is developed - under the wing of the Apache Software Foundation's - Incubator.</para> - - <para><application>Apache OpenOffice</application> includes all - of the mandatory applications in a complete office - productivity suite: a word processor, spreadsheet, - presentation manager, and drawing program. Its user - interface is very similar to other office suites, and it can - import and export in various popular file formats. It is - available in a number of different languages and - internationalization has been extended to interfaces, spell - checkers, and dictionaries.</para> - - <para>The word processor of - <application>Apache OpenOffice</application> uses a native XML - file format for increased portability and flexibility. The - spreadsheet program features a macro language which can be - interfaced with external databases. - <application>Apache OpenOffice</application> is stable and - runs natively on &windows;, &solaris;, &linux;, &os;, and - &macos; X. More information about <application>Apache - OpenOffice</application> can be found on the <ulink - url="http://incubator.apache.org/openofficeorg/">Apache - OpenOffice web site</ulink>. For &os; specific - information, and to directly download packages, refer to the - web site of the <ulink - url="http://porting.openoffice.org/freebsd/">&os; Apache - OpenOffice Porting Team</ulink>.</para> + <para><application>Apache OpenOffice</application> is an open + source office suite which is developed under the wing of the + Apache Software Foundation's Incubator. It includes all of + the applications found in a complete office productivity + suite: a word processor, spreadsheet, presentation manager, + and drawing program. Its user interface is similar to other + office suites, and it can import and export in various popular + file formats. It is available in a number of different + languages and internationalization has been extended to + interfaces, spell checkers, and dictionaries.</para> + + <para>The word processor of <application>Apache + OpenOffice</application> uses a native XML file format for + increased portability and flexibility. The spreadsheet + program features a macro language which can be interfaced + with external databases. <application>Apache + OpenOffice</application> is stable and runs natively on + &windows;, &solaris;, &linux;, &os;, and &macos; X. + More information about <application>Apache + OpenOffice</application> can be found at <ulink + url="http://openoffice.org/">openoffice.org</ulink>. For + &os; specific information refer to <ulink + url="http://porting.openoffice.org/freebsd/">porting.openoffice.org/freebsd/</ulink>.</para> <para>To install the <application>Apache OpenOffice</application> package:</para> <screen>&prompt.root; <userinput>pkg_add -r apache-openoffice</userinput></screen> - <note> - <para>When running a -RELEASE version of &os;, this should - work. Otherwise, download the latest package from the - website of the &os; - <application>Apache OpenOffice</application> Porting Team - and install it using &man.pkg.add.1;. Both the current - release and development versions are available for download - at this web site.</para> - </note> - <para>Once the package is installed, type the following command to launch <application>Apache OpenOffice</application>:</para> <screen>&prompt.user; <userinput>openoffice-<replaceable>X.Y.Z</replaceable></userinput></screen> <para>where <replaceable>X.Y.Z</replaceable> is the version - number of the installed version of - <application>Apache OpenOffice</application>.</para> - - <note> - <para>During the first launch, some questions will be asked - and a <filename>.openoffice.org</filename> folder - will be created in the user's home directory.</para> - </note> + number of the installed version of <application>Apache + OpenOffice</application>. The first time + <application>Apache OpenOffice</application> launches, some + questions will be asked and a <filename + class="directory">.openoffice.org</filename> folder will + be created in the user's home directory.</para> <para>If the desired <application>Apache OpenOffice</application> package is not available, compiling - the port is still an opton. However, this requires a lot of + the port is still an option. However, this requires a lot of disk space and a fairly long time to compile:</para> - <screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice-3</userinput> + <screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice-4</userinput> &prompt.root; <userinput>make install clean</userinput></screen> <note> @@ -886,17 +871,17 @@ <para><application>LibreOffice</application> is a free software office suite developed by <ulink - url="http://www.documentfoundation.org/">The Document - Foundation</ulink>. It is compatible with other major - office suites and available on a variety of platforms. It is - a rebranded fork of <application>OpenOffice.org</application> - which includes all of the mandatory applications in a complete - office productivity suite: a word processor, spreadsheet, - presentation manager, drawing program, database management - program, and a tool for creating and editing mathematical - formula. It is available in a number of different languages - and internationalization has been extended to interfaces, - spell checkers, and dictionaries.</para> + url="http://www.documentfoundation.org/">documentfoundation.org</ulink>. + It is compatible with other major office suites and available + on a variety of platforms. It is a rebranded fork of + <application>OpenOffice.org</application> and includes + applications found in a complete office productivity suite: + a word processor, spreadsheet, presentation manager, drawing + program, database management program, and a tool for creating + and editing mathematical formulæ. It is available in + a number of different languages and internationalization has + been extended to interfaces, spell checkers, and + dictionaries.</para> <para>The word processor of <application>LibreOffice</application> uses a native XML file @@ -906,33 +891,30 @@ <application>LibreOffice</application> is stable and runs natively on &windows;, &linux;, &os;, and &macos; X. More information about - <application>LibreOffice </application> can be found on the - <ulink url="http://www.libreoffice.org/">LibreOffice web - site</ulink>.</para> + <application>LibreOffice </application> can be found at + <ulink + url="http://www.libreoffice.org/">libreoffice.org</ulink>.</para> <para>To install the English version of the <application>LibreOffice</application> package:</para> <screen>&prompt.root; <userinput>pkg_add -r libreoffice</userinput></screen> - <para>The <ulink - url="http://www.FreeBSD.org/ports/editors.html">editors</ulink> - category of the Ports Collection contains several - localizations for <application>LibreOffice</application>. - When installing a localized package, replace - <literal>libreoffice</literal> with the name of the - localized package.</para> + <para>The editors category (<ulink + url="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</ulink>) + of the Ports Collection contains several localizations for + <application>LibreOffice</application>. When installing a + localized package, replace <literal>libreoffice</literal> + with the name of the localized package.</para> <para>Once the package is installed, type the following command to run <application>LibreOffice</application>:</para> <screen>&prompt.user; <userinput>libreoffice</userinput></screen> - <note> - <para>During the first launch, some questions will be asked - and a <filename class="directory">.libreoffice</filename> - folder will be created in the user's home directory.</para> - </note> + <para>During the first launch, some questions will be asked + and a <filename class="directory">.libreoffice</filename> + folder will be created in the user's home directory.</para> <para>If the desired <application>LibreOffice</application> package is not available, compiling the port is still an @@ -945,11 +927,11 @@ <note> <para>To build a localized version, - <application>cd</application> into the port directory - of the desired language. Supported languages can be found - in the <ulink - url="http://www.FreeBSD.org/ports/editors.html">editors</ulink> - category of the Ports Collection.</para> + <application>cd</application> into the port directory of + the desired language. Supported languages can be found + in the editors category (<ulink + url="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</ulink>) + of the Ports Collection.</para> </note> </sect2> </sect1> @@ -960,7 +942,7 @@ <para>Some new document formats have gained popularity since the advent of &unix; and the viewers they require may not be available in the base system. This section demonstrates how to - install the following viewers:</para> + install the following document viewers:</para> <informaltable frame="none" pgwide="1"> <tgroup cols="4"> @@ -1018,15 +1000,15 @@ </indexterm> <para>Many documents are now distributed as Portable Document - Format (PDF) files. One popular viewer for PDFs is - <application>&acrobat.reader;</application>, - released by &adobe; for &linux;. As &os; can run &linux; - binaries, it is also available for &os;. Due to - licensing restrictions, a package is not available so it must - be compiled from ports. Several localizations are - available from the <ulink - url="http://www.FreeBSD.org/ports/print.html">print</ulink> - category of the Ports Collection.</para> + Format (PDF) files. One popular PDF viewer is + <application>&acrobat.reader;</application>, released by + &adobe; for &linux;. As &os; can run &linux; binaries, it + is also available for &os;. Due to licensing restrictions, + a package is not available, meaning that this application + must be compiled from ports. Several localizations are + available from the print category (<ulink + url="http://www.FreeBSD.org/ports/print.html">freebsd.org/ports/print.html</ulink>) + of the Ports Collection.</para> <para>This command installs the English version of <application>&acrobat.reader; 9</application> from the Ports @@ -1054,15 +1036,14 @@ <secondary>viewing</secondary> </indexterm> - <para><ulink - url="http://www.gnu.org/software/gv/">gv</ulink> is a - &postscript; and PDF viewer. It is based on - <application>ghostview</application>, but has a nicer look - due to the <application>Xaw3d</application> library. It is - fast with a clean interface. <application>gv</application> - has many configurable features, such as orientation, paper - size, scale, and anti-aliasing. Almost any operation can be - performed with either the keyboard or the mouse.</para> + <para><application>gv</application> is a &postscript; and PDF + viewer. It is based on <application>ghostview</application>, + but has a nicer look as it is based on the + <application>Xaw3d</application> widget toolkit. + <application>gv</application> has many configurable features, + such as orientation, paper size, scale, and anti-aliasing. + Almost any operation can be performed with either the + keyboard or the mouse.</para> <para>To install <application>gv</application> as a package:</para> @@ -1088,12 +1069,10 @@ </indexterm> <para>For users that prefer a small &os; PDF viewer, - <ulink - url="http://www.foolabs.com/xpdf/">xpdf</ulink> provides a - light-weight and efficient viewer which requires few - resources. It uses the standard X fonts and does not require - <application>&motif;</application> or any other X - toolkit.</para> + <application>Xpdf</application> provides a light-weight and + efficient viewer which requires few resources. It uses the + standard X fonts and does not require any additional + toolkits.</para> <para>To install the <application>Xpdf</application> package:</para> @@ -1118,17 +1097,16 @@ <primary><application>GQview</application></primary> </indexterm> - <para><ulink - url="http://gqview.sourceforge.net/">GQview</ulink> is - an image manager which supports viewing a file with a single - click, launching an external editor, and thumbnail previews. - It also features a slideshow mode and some basic file - operations, making it easy to manage image collections and to - find duplicate files. <application>GQview</application> - supports full screen viewing and internationalization.</para> + <para><application>GQview</application> is an image manager + which supports viewing a file with a single click, launching + an external editor, and thumbnail previews. It also features + a slideshow mode and some basic file operations, making it + easy to manage image collections and to find duplicate files. + <application>GQview</application> supports full screen viewing + and internationalization.</para> - <para>To install the - <application>GQview</application> package:</para> + <para>To install the <application>GQview</application> + package:</para> <screen>&prompt.root; <userinput>pkg_add -r gqview</userinput></screen> @@ -1195,8 +1173,7 @@ <primary><application>GnuCash</application></primary> </indexterm> - <para><ulink - url="http://www.gnucash.org/">GnuCash</ulink> is part of the + <para><application>GnuCash</application> is part of the <application>GNOME</application> effort to provide user-friendly, yet powerful, applications to end-users. <application>GnuCash</application> can be used to keep track @@ -1235,14 +1212,12 @@ <secondary><application>Gnumeric</application></secondary> </indexterm> - <para><ulink - url="http://projects.gnome.org/gnumeric/index.shtml">Gnumeric</ulink> - is a spreadsheet program developed by the - <application>GNOME</application> community. It features - convenient automatic <quote>guessing</quote> of user input - according to the cell format with an autofill system for many - sequences. It can import files in a number of popular - formats, including <application>Excel</application>, + <para><application>Gnumeric</application> is a spreadsheet + program developed by the <application>GNOME</application> + community. It features convenient automatic guessing of user + input according to the cell format with an autofill system + for many sequences. It can import files in a number of + popular formats, including <application>Excel</application>, <application>Lotus 1-2-3</application>, and <application>Quattro Pro</application>. It has a large number of built-in functions and allows all of the usual cell formats @@ -1270,16 +1245,14 @@ <secondary><application>KMyMoney</application></secondary> </indexterm> - <para><ulink - url="http://kmymoney2.sourceforge.net">KMyMoney</ulink> - is a personal finance created by the - <application>KDE</application> community. - <application>KMyMoney</application> intends to provide and - incorporate all the important features found in commercial - personal finance manager applications. It also highlights - ease-of-use and proper double-entry accounting among its - features. <application>KMyMoney</application> imports from - standard Quicken Interchange Format (QIF) files, tracks + <para><application>KMyMoney</application> is a personal finance + application created by the <application>KDE</application> + community. <application>KMyMoney</application> aims to + provide the important features found in commercial personal + finance manager applications. It also highlights ease-of-use + and proper double-entry accounting among its features. + <application>KMyMoney</application> imports from standard + <application>Quicken</application> QIF files, tracks investments, handles multiple currencies, and provides a wealth of reports.</para> diff --git a/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml b/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml index e527aab5b8..398a5d73ba 100644 --- a/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml @@ -176,8 +176,15 @@ options DDB_CTF</programlisting> </note> <para>All sources must be rebuilt and installed with - <acronym>CTF</acronym> options. - To accomplish this task, rebuild the &os; sources using:</para> + <acronym>CTF</acronym> options.</para> + + <note> + <para>Starting from 10.0, the following steps are not needed any + more as the <literal>WITH_CTF</literal> option is included in + the <filename>GENERIC</filename> kernel configuration.</para> + </note> + + <para>To accomplish this task, rebuild the &os; sources using:</para> <!-- XXXTR: WITH_CTF has been reported to leave a user with a broken system when used with buildworld. Until this is diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml index 0b4e63fbb2..77ca4417de 100644 --- a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml @@ -813,6 +813,13 @@ </row> <row> + <entry>&a.svn-src-stable-10.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>stable/10</filename> + branch of the src Subversion repository</entry> + </row> + + <row> <entry>&a.svn-src-stable-other.name;</entry> <entry><filename>/usr/src</filename></entry> <entry>All changes to the diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml index 420f9d3ec6..1105738cec 100644 --- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml @@ -1250,7 +1250,7 @@ pass out on $ext_if inet proto udp from any to any port 33433 >< 33626 kee <para>which in turn is used to initialize the table in <filename>/etc/pf.conf</filename>:</para> - <programlisting>table <clients> persist file /etc/clients</programlisting> + <programlisting>table <clients> persist file "/etc/clients"</programlisting> <para>Then, for example, one of our earlier rules can be changed to read</para> diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.xml b/en_US.ISO8859-1/books/handbook/geom/chapter.xml index 8fa6b4b1b8..b25ad6c2c1 100644 --- a/en_US.ISO8859-1/books/handbook/geom/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/geom/chapter.xml @@ -269,6 +269,13 @@ Done.</screen> first.</para> </warning> + <warning> + <para>&man.dump.8; is used in these procedures to copy file + systems. But &man.dump.8; does not work on file systems with + soft updates journaling. See &man.tunefs.8; for information + on detecting and disabling soft updates journaling.</para> + </warning> + <sect2 id="geom-mirror-metadata"> <title>Metadata Issues</title> diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml index 92da225d1a..9adbd535d2 100644 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml @@ -125,9 +125,8 @@ <para>The industry standard <emphasis>X Window System</emphasis><indexterm> <primary>X Window System</primary> - </indexterm> (X11R7) provides a graphical user interface - (GUI) for the cost of a common VGA card and monitor and - comes with full sources.</para> + </indexterm> (X11R7) can provide a graphical user interface + (GUI) on any machine and comes with full sources.</para> </listitem> <listitem> @@ -238,10 +237,9 @@ development. In addition to the fine work provided by CSRG, the &os; Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability - in real-life load situations. As many of the commercial - giants struggle to field PC operating systems with such - features, performance and reliability, &os; can offer them - <emphasis>now</emphasis>!</para> + in real-life load situations. &os; offers performance and + reliability on par with commercial offerings, combined with + many cutting-edge features not available anywhere else.</para> <para>The applications to which &os; can be put are truly limited only by your own imagination. From software @@ -272,12 +270,6 @@ <itemizedlist> <listitem> - <para>FTP servers<indexterm> - <primary>FTP servers</primary> - </indexterm></para> - </listitem> - - <listitem> <para>World Wide Web servers<indexterm> <primary>web servers</primary> </indexterm> @@ -299,6 +291,12 @@ </listitem> <listitem> + <para>FTP servers<indexterm> + <primary>FTP servers</primary> + </indexterm></para> + </listitem> + + <listitem> <para> <indexterm> <primary>electronic mail</primary> @@ -311,21 +309,9 @@ </listitem> <listitem> - <para>USENET<indexterm> - <primary>USENET</primary> - </indexterm> - News or Bulletin Board Systems</para> - </listitem> - - <listitem> <para>And more...</para> </listitem> </itemizedlist> - - <para>With &os;, you can easily start out small with an - inexpensive 386 class PC and upgrade all the way up to a - quad-processor Xeon with RAID storage as your enterprise - grows.</para> </listitem> <listitem> @@ -358,43 +344,63 @@ </indexterm> A name server (DNS)?<indexterm> <primary>DNS Server</primary> </indexterm> A firewall to keep people out of your - internal network? &os; can easily turn that unused 386 or - 486 PC sitting in the corner into an advanced router with + internal network? &os; can easily turn that unused + PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities.</para> </listitem> <listitem> + <para><emphasis>Embedded:</emphasis> &os; makes an + excellent platform to build embedded systems upon. + <indexterm> + <primary>embedded</primary> + </indexterm> + With support for the &arm;, &mips; and &powerpc; + platforms, coupled with a robust network stack, + cutting edge features and the permissive <ulink + url="&url.books.faq;/introduction.html#bsd-license-restrictions">BSD license</ulink> + &os; makes an excellent foundation for building + embedded routers, firewalls, and other devices.</para> + </listitem> + + <listitem> <para> <indexterm> <primary>X Window System</primary> </indexterm> <indexterm> - <primary>X Window System</primary> - <secondary>Accelerated-X</secondary> + <primary>GNOME</primary> </indexterm> - <emphasis>X Window workstation:</emphasis> &os; is a - fine choice for an inexpensive X terminal solution, + <indexterm> + <primary>KDE</primary> + </indexterm> + <emphasis>Desktop:</emphasis> &os; makes a + fine choice for an inexpensive desktop solution using the freely available X11 server. - Unlike an X terminal, &os; allows many applications to - be run locally if desired, thus relieving the burden on a - central server. &os; can even boot - <quote>diskless</quote>, making individual workstations + &os; offers a choice from many open-source desktop + environments, including the standard + <application>GNOME</application> and + <application>KDE</application> graphical user interfaces. + &os; can even boot <quote>diskless</quote> from + a central server, making individual workstations even cheaper and easier to administer.</para> </listitem> <listitem> <para><emphasis>Software Development:</emphasis> The basic &os; system comes with a full complement of development - tools including the renowned GNU + tools including a full C/C++<indexterm> - <primary>GNU Compiler Collection</primary> + <primary>Compiler</primary> </indexterm> - compiler and debugger.</para> + compiler and debugger suite. + Support for many other languages are also available + through the ports and packages collection.</para> </listitem> </itemizedlist> - <para>&os; is available in both source and binary form on - CD-ROM, DVD, and via anonymous FTP. Please see <xref + <para>&os; is available to download free of charge, or can be + obtained on either CD-ROM or DVD. Please see <xref linkend="mirrors"/> for more information about obtaining &os;.</para> </sect2> @@ -407,31 +413,297 @@ <secondary>large sites running &os;</secondary> </indexterm> - <para>&os; is used as a platform for devices and products from - many of the world's largest IT companies, including:</para> + <para>&os;'s advanced features, proven security, and predictable + release cycle, as well as its permissive license have lead to + its use as a platform for building many commericial and open + source appliances, devices, and products, including those from + many of the world's largest IT companies:</para> <itemizedlist> <listitem> <para><ulink + url="http://www.apache.org/">Apache</ulink><indexterm> + <primary>Apache</primary></indexterm> - The Apache + Software Foundation runs most of its public facing + infrastructure, including possibly one of the largest SVN + repositories in the world with over 1.4 million commits, + on &os;.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.apple.com/">Apple</ulink><indexterm> - <primary>Apple</primary></indexterm></para> + <primary>Apple</primary></indexterm> - OS X borrows + heavily from &os; for the network stack, virtual file + system, and many userland components. Apple iOS also + contains elements borrowed from &os;.</para> </listitem> <listitem> <para><ulink url="http://www.cisco.com/">Cisco</ulink><indexterm> - <primary>Cisco</primary></indexterm></para> + <primary>Cisco</primary></indexterm> - IronPort network + security and anti-spam appliances run a modified &os; + kernel.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.citrix.com/">Citrix</ulink><indexterm> + <primary>Citrix</primary></indexterm> - The NetScaler + line of security appliances provide layer 4-7 load + balancing, content caching, application firewall, secure + VPN, and mobile cloud network access, along with the power + of a &os; shell.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.dell.com/KACE">Dell + KACE</ulink><indexterm><primary>Dell + KACE</primary></indexterm> - The KACE system + management appliances run &os; because of its + reliability, scalability, and the community that supports + its continued development.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.experts-exchange.com/">Experts + Exchange</ulink><indexterm> + <primary>Experts Exchange</primary> + </indexterm> - All public facing web servers are powered + by &os; and they make extensive use of jails to isolate + development and testing environments without the overhead + of virtualization.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.isilon.com/">Isilon</ulink><indexterm> + <primary>Isilon</primary></indexterm> - Isilon's + enterprise storage appliances are based on &os;. The + extremely liberal &os; license allowed Isilon to integrate + their intellectual property throughout the kernel and + focus on building their product instead of an operating + system.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.ixsystems.com/">iXsystems</ulink><indexterm> + <primary>iXsystems</primary></indexterm> - The TrueNAS + line of unified storage appliances is based on &os;. In + addition to their commercial products, iXsystems also + manages development of the open source projects PC-BSD + and FreeNAS.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.juniper.net/">Juniper</ulink><indexterm> + <primary>Juniper</primary></indexterm> - The JunOS + operating system that powers all Juniper networking gear + (including routers, switches, security, and networking + appliances) is based on &os;. Juniper is one of many + vendors that showcases the symbiotic relationship between + the project and vendors of commercial products. + Improvements generated at Juniper are upstreamed into + &os; to reduce the complexity of integrating new + features from &os; back into JunOS in the future.</para> </listitem> <listitem> <para><ulink - url="http://www.juniper.net/">Juniper</ulink></para> + url="http://www.mcafee.com/">McAfee</ulink><indexterm> + <primary>McAfee</primary></indexterm> - SecurOS, the + basis of McAfee enterprise firewall products including + Sidewinder is based on &os;.</para> </listitem> <listitem> <para><ulink url="http://www.netapp.com/">NetApp</ulink><indexterm> - <primary>NetApp</primary></indexterm></para> + <primary>NetApp</primary></indexterm> - The Data ONTAP + GX line of storage appliances are based on &os;. In + addition, NetApp has contributed back many features, + including the new BSD licensed hypervisor, bhyve.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.netflix.com/">Netflix</ulink><indexterm> + <primary>Netflix</primary></indexterm> - The OpenConnect + appliance that Netflix uses to stream movies to its + customers is based on &os;. Netflix has make extensive + contributions to the codebase and works to maintain a zero + delta from mainline &os;. Netflix OpenConnect appliances + are responsible for delivering more than 32% of all + Internet traffic in North America.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.sandvine.com/">Sandvine</ulink> + <indexterm><primary>Sandvine</primary></indexterm> - + Sandvine uses &os; as the basis of their high + performance realtime network processing platforms that + make up their intelligent network policy control + products.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.sony.com/">Sony</ulink> + <indexterm><primary>Sony</primary></indexterm> - + Both the PlayStation 3 and PlayStation 4 gaming consoles + run modified versions of &os;.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.sophos.com/">Sophos</ulink> + <indexterm><primary>Sophos</primary></indexterm> - + The Sophos Email Appliance product is based on a + hardened &os; and scans inbound mail for spam and viruses, + while also monitoring outbound mail for malware as well as + the accidental loss of sensitive information.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.spectralogic.com/">Spectra Logic</ulink> + <indexterm><primary>Spectra Logic</primary></indexterm> - + The nTier line of archive grade storage appliances run + &os; and OpenZFS.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.weather.com/">The Weather + Channel</ulink><indexterm><primary>The Weather + Channel</primary></indexterm> - The IntelliStar + appliance that is installed at each local cable + providers headend and is responsible for injecting local + weather forecasts into the cable TV network's programming + runs &os;.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.verisign.com/">Verisign</ulink> + <indexterm><primary>Verisign</primary></indexterm> - + Verisign is responsible for operating the .com and .net + root domain registries as well as the accompanying DNS + infrastructure. They rely on a number of different + network operating systems including &os; to ensure there + is no common point of failure in their + infrastructure.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.whatsapp.com/">WhatsApp</ulink> + <indexterm><primary>WhatsApp</primary></indexterm> - When + WhatsApp needed a platform that would be able to handle + more than 1 million concurrent TCP connections per server, + they chose &os;. They then proceeded to scale past 2.5 + million connections per server.</para> + </listitem> + + <listitem> + <para><ulink + url="http://wheelsystems.com/en/">Wheel Systems</ulink> + <indexterm><primary>Wheel Systems</primary></indexterm> - + The FUDO security appliance allows enterprises to + monitor, control, record, and audit contractors and + administrators who work on their systems. Based on all of + the best security features of &os; including ZFS, GELI, + Capsicum, HAST, and auditdistd.</para> + </listitem> + </itemizedlist> + + <para>&os; has also spawned a number of related open source + projects:</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://bsdrp.net/">BSD Router</ulink><indexterm> + <primary>BSD Router</primary></indexterm> - A &os; based + replacement for large enterprise routers designed to run + on standard PC hardware.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.freenas.org/">FreeNAS</ulink><indexterm> + <primary>FreeNAS</primary></indexterm> - A customized + &os; designed to be used as a network file server + appliance. Provides a python based web interface to + simplify the management of both the UFS and ZFS file + systems. Includes support for NFS, SMB/CIFS, AFP, FTP, + and iSCSI. Includes an extensible plugin system based on + &os; jails.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.ghostbsd.org/">GhostBSD</ulink><indexterm> + <primary>GhostBSD</primary></indexterm> - A desktop + oriented distribution of &os; bundled with the Gnome + desktop environment.</para> + </listitem> + + <listitem> + <para><ulink + url="http://mfsbsd.vx.sk/">mfsBSD</ulink><indexterm> + <primary>mfsBSD</primary></indexterm> - A toolkit for + building a &os; system image that runs entirely from + memory.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.nas4free.org/">NAS4Free</ulink><indexterm> + <primary>NAS4Free</primary></indexterm> - A file server + distribution based on &os; with a PHP powered web + interface.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.pcbsd.org/">PC-BSD</ulink><indexterm> + <primary>PC-BSD</primary></indexterm> - A customized + version of &os; geared towards desktop users with + graphical utilities to exposing the power of &os; to + all users. Designed to ease the transition of Windows and + OS X users.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.pfsense.org/">pfSense</ulink><indexterm> + <primary>pfSense</primary></indexterm> - A firewall + distribution based on &os; with a huge array of features + and extensive IPv6 support.</para> + </listitem> + + <listitem> + <para><ulink + url="http://m0n0.ch/wall/">m0n0wall</ulink><indexterm> + <primary>m0n0wall</primary></indexterm> - A stripped + down version of &os; bundled with a web server and PHP. + Designed as an embedded firewall appliance with a + footprint of less than 12 MB.</para> + </listitem> + + <listitem> + <para><ulink + url="http://zrouter.org/">ZRouter</ulink><indexterm> + <primary>ZRouter</primary></indexterm> - An open source + alternative firmware for embedded devices based on &os;. + Designed to replace the proprietary firmware on + off-the-shelf routers.</para> </listitem> </itemizedlist> @@ -453,12 +725,6 @@ <listitem> <para><ulink - url="http://www.apache.org/">Apache</ulink><indexterm> - <primary>Apache</primary></indexterm></para> - </listitem> - - <listitem> - <para><ulink url="http://www.rambler.ru/">Rambler</ulink><indexterm> <primary>Rambler</primary></indexterm></para> </listitem> @@ -490,14 +756,20 @@ <listitem> <para><ulink + url="https://signup.netflix.com/openconnect">Netflix</ulink> + <indexterm><primary>Netflix</primary></indexterm></para> + </listitem> + + <listitem> + <para><ulink url="http://www.163.com/">NetEase</ulink><indexterm> <primary>NetEase</primary></indexterm></para> </listitem> <listitem> <para><ulink - url="http://www.weathernews.com/">Weathernews</ulink><indexterm> - <primary>Weathernews</primary></indexterm></para> + url="http://www.weathernews.com/">Weathernews</ulink> + <indexterm><primary>Weathernews</primary></indexterm></para> </listitem> <listitem> @@ -507,15 +779,11 @@ </indexterm></para> </listitem> - <listitem> - <para><ulink url="http://www.experts-exchange.com/">Experts - Exchange</ulink><indexterm> - <primary>Experts Exchange</primary> - </indexterm></para> - </listitem> </itemizedlist> - <para>and many more.</para> + <para>and many more. Wikipedia also maintains a <ulink + url="http://en.wikipedia.org/wiki/List_of_products_based_on_FreeBSD"> + list of products based on &os;</ulink></para> </sect2> </sect1> @@ -623,8 +891,8 @@ constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until November of 1994 - to make this transition, at which point it released - &os; 2.0 to the net and on CD-ROM (in late December). + to make this transition, and in December it released + &os; 2.0 to the world. Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install &os; 2.0.5 release in @@ -706,11 +974,11 @@ </indexterm> <para>The development of &os; is a very open and flexible process, being literally built from the contributions - of hundreds of people around the world, as can be seen from + of thousands of people around the world, as can be seen from our <ulink url="&url.articles.contributors;/article.html">list of contributors</ulink>. &os;'s development infrastructure - allow these hundreds of developers to collaborate over the + allow these thousands of contributors to collaborate over the Internet. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely involved with the project need simply contact us at the @@ -757,7 +1025,7 @@ was maintained by <ulink url="http://www.nongnu.org/cvs/">CVS</ulink> (Concurrent Versions System), a freely available source - code control tool that comes bundled with &os;. In June + code control tool. In June 2008, the Project switched to using <ulink url="http://subversion.tigris.org">SVN</ulink> (Subversion). The switch was deemed necessary, as the @@ -817,16 +1085,9 @@ committer candidates in July 2012. Elections are held every 2 years.</para> - <para>Some core team members also have specific areas of - responsibility, meaning that they are committed to - ensuring that some large portion of the system works as - advertised. For a complete list of &os; developers - and their areas of responsibility, please see the <ulink - url="&url.articles.contributors;/article.html">Contributors - List</ulink></para> - <note> - <para>Most members of the core team are volunteers when + <para>Like most developers, most members of the + core team are also volunteers when it comes to &os; development and do not benefit from the project financially, so <quote>commitment</quote> should also not be misconstrued as meaning diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml index e3ac479e91..911c0e0a7e 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml @@ -6,24 +6,23 @@ --> <chapter id="kernelconfig"> - <chapterinfo> +<!--<chapterinfo> <authorgroup> <author> <firstname>Jim</firstname> <surname>Mock</surname> - <contrib>Updated and restructured by </contrib> - <!-- Mar 2000 --> + <contrib>Updated and restructured in Mar 2000 by </contrib> </author> </authorgroup> <authorgroup> <author> <firstname>Jake</firstname> <surname>Hamby</surname> - <contrib>Originally contributed by </contrib> - <!-- 6 Oct 1995 --> + <contrib>Originally contributed 6 Oct 1995 by </contrib> </author> </authorgroup> </chapterinfo> + --> <title>Configuring the FreeBSD Kernel</title> @@ -49,6 +48,10 @@ </listitem> <listitem> + <para>How to take a hardware inventory.</para> + </listitem> + + <listitem> <para>How to customize a kernel configuration file.</para> </listitem> @@ -73,10 +76,10 @@ <sect1 id="kernelconfig-custom-kernel"> <title>Why Build a Custom Kernel?</title> - <para>Traditionally, &os; used a <quote>monolithic</quote> kernel. + <para>Traditionally, &os; used a monolithic kernel. The kernel was one large program, supported a fixed list of devices, and in order to change the kernel's behavior, one had - to compile a new kernel, and then reboot into the new + to compile and then reboot into a new kernel.</para> <para>Today, most of the functionality in the &os; kernel is @@ -87,10 +90,10 @@ a modular kernel.</para> <para>Occasionally, it is still necessary to perform static kernel - configuration. This may be because the functionality is so tied + configuration. Sometimes the needed functionality is so tied to the kernel that it can not be made dynamically loadable. Some security environments prevent the loading and unloading of - kernel modules, and require that only needed functionality is + kernel modules and require that only needed functionality is statically compiled into the kernel.</para> <para>Building a custom kernel is often a rite of passage for @@ -120,14 +123,40 @@ </listitem> <listitem> - <para>Additional hardware support. A custom kernel can add in + <para>Additional hardware support. A custom kernel can add support for devices which are not present in the <filename>GENERIC</filename> kernel.</para> </listitem> </itemizedlist> + + <para>Before building a custom kernel, consider the reason for + doing so. If there is a need for specific hardware support, + it may already exist as a module.</para> + + <para>Kernel modules exist in <filename + class="directory">/boot/kernel</filename> and may be + dynamically loaded into the running kernel using + &man.kldload.8;. Most kernel drivers have a + loadable module and manual page. For example, the &man.ath.4; + wireless Ethernet driver has the following information in its + manual page:</para> + + <programlisting>Alternatively, to load the driver as a module at boot time, place the +following line in &man.loader.conf.5;: + + if_ath_load="YES"</programlisting> + + <para>Adding <literal>if_ath_load="YES"</literal> to + <filename>/boot/loader.conf</filename> will load this + module dynamically at boot time.</para> + + <para>In some cases, there is no associated module in <filename + class="directory">/boot/kernel</filename>. This is + mostly true for certain subsystems.</para> </sect1> <sect1 id="kernelconfig-devices"> + <!-- <sect1info> <authorgroup> <author> @@ -137,28 +166,28 @@ </author> </authorgroup> </sect1info> + --> <title>Finding the System Hardware</title> - <para>Before venturing into kernel configuration, it would be - wise to get an inventory of the machine's hardware. In cases - where &os; is not the primary operating system, the inventory - list can be created by viewing the current operating system - configuration. For example, µsoft;'s + <para>Before editing the kernel configuration file, it is recommended + to perform an inventory of the machine's hardware. On a dual-boot + system, the inventory + can be created from the other operating system. + For example, µsoft;'s <application>Device Manager</application> contains information about installed devices.</para> <note> <para>Some versions of µsoft.windows; have a - <application>System</application> icon which will display a - screen where <application>Device Manager</application> may - be accessed.</para> + <application>System</application> icon which can be used to + access <application>Device Manager</application>.</para> </note> - <para>If another operating system does not exist on the machine, - the administrator must find this information out manually. One - method is using &man.dmesg.8; and &man.man.1;. Most device - drivers on &os; have a manual page, listing supported hardware. - During the boot probe, found hardware will be listed. For + <para>If &os; is the only installed operating system, + use &man.dmesg.8; to determine the hardware that was found and + listed during the boot probe. Most device + drivers on &os; have a manual page which lists the hardware supported by that driver. + For example, the following lines indicate that the &man.psm.4; driver found a mouse:</para> @@ -167,32 +196,29 @@ psm0: [GIANT-LOCKED] psm0: [ITHREAD] psm0: model Generic PS/2 mouse, device ID 0</programlisting> - <para>This driver will need to be included in the custom kernel - configuration file or loaded using &man.loader.conf.5;.</para> + <para>Since this hardware exists, this driver should not be removed from a custom kernel + configuration file.</para> - <para>On occasion, the data from <command>dmesg</command> will - only show system messages instead of the boot probe output. In - these situations, the output may be obtained by reading + <para>If the output of <command>dmesg</command> does not display + the results of the boot probe output, instead read the contents of <filename>/var/run/dmesg.boot</filename>.</para> - <para>Another method for finding hardware is to use - &man.pciconf.8; which provides more verbose output. For + <para>Another tool for finding hardware is + &man.pciconf.8;, which provides more verbose output. For example:</para> - <programlisting>ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 + <programlisting><command>pciconf <option>-lv</option></command> + ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 vendor = 'Atheros Communications Inc.' device = 'AR5212 Atheros AR5212 802.11abg wireless' class = network subclass = ethernet</programlisting> - <para>This output, obtained by using - <command>pciconf <option>-lv</option></command>, shows that the + <para>This output shows that the <devicename>ath</devicename> driver located a wireless Ethernet - device. Type <command>man - <replaceable>ath</replaceable></command> to read - &man.ath.4;.</para> + device.</para> - <para>The <option>-k</option> flag, when passed to &man.man.1; + <para>The <option>-k</option> flag of &man.man.1; can be used to provide useful information. For example, to display a list of manual pages which contain the specified word:</para> @@ -202,253 +228,87 @@ psm0: model Generic PS/2 mouse, device ID 0</programlisting> <programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting> - <para>Armed with a hardware inventory list, the process of - building a custom kernel should appear less daunting.</para> - </sect1> - - <sect1 id="kernelconfig-modules"> - <title>Kernel Drivers, Subsystems, and Modules</title> - - <indexterm> - <primary>kernel</primary> - <secondary>drivers / modules / subsystems</secondary> - </indexterm> - - <para>Before building a custom kernel, consider the reason for - doing so. If there is a need for specific hardware support, - it may already exist as a module.</para> - - <para>Kernel modules exist in <filename - class="directory">/boot/kernel</filename> and may be - dynamically loaded into the running kernel using - &man.kldload.8;. Most, if not all kernel drivers have a - loadable module and manual page. For example, the &man.ath.4; - wireless Ethernet driver has the following information in its - manual page:</para> - - <programlisting>Alternatively, to load the driver as a module at boot time, place the -following line in &man.loader.conf.5;: - - if_ath_load="YES"</programlisting> - - <para>Adding <literal>if_ath_load="YES"</literal> to - <filename>/boot/loader.conf</filename> will enable loading this - module dynamically at boot time.</para> - - <para>In some cases, there is no associated module. This is - mostly true for certain subsystems. One way to tell if a driver - is available is to check for the module itself.</para> - - <warning> - <para>It is easy to remove support for a device or option and - end up with a broken kernel. For example, if the &man.ata.4; - driver is removed from the kernel configuration file, a system - using <acronym>ATA</acronym> disk drivers may not boot. When - in doubt, just leave support in the kernel.</para> - </warning> + <para>Once the hardware inventory list is created, refer to it + to ensure that installed hardware is not removed as you edit the custom + kernel configuration file.</para> </sect1> - <sect1 id="kernelconfig-building"> - <title>Building and Installing a Custom Kernel</title> - - <indexterm> - <primary>kernel</primary> - <secondary>building / installing</secondary> - </indexterm> + <sect1 id="kernelconfig-config"> + <!-- + <sect1info> + <authorgroup> + <author> + <firstname>Joel</firstname> + <surname>Dahl</surname> + <contrib>Updated by </contrib> + </author> + </authorgroup> + </sect1info> + --> + <title>The Configuration File</title> - <note> - <para>It is required to have the full &os; source tree installed - to build the kernel.</para> - </note> + <para>In order to create a custom kernel configuration file and + build a custom kernel, the full &os; source tree must first be installed.</para> - <para>The kernel build is located at <filename - class="directory">/usr/src/sys</filename>. It contains a - number of subdirectories representing different parts of the - kernel. These include <filename - class="directory"><replaceable>arch</replaceable>/conf</filename>, - which contains the kernel configuration file, and - <filename class="directory">compile</filename>, which is the - staging area where the kernel will be built. - <replaceable>arch</replaceable> contains subdirectories for each - supported architecture: <filename - class="directory">i386</filename>, <filename + <para>If <filename class="directory">/usr/src/</filename> does + not exist or it is empty, source has not been installed. + Source can be installed using + <application>svn</application>, which is described in <xref + linkend="svn"/>, or by installing the + <literal>src</literal> distribution using &man.sysinstall.8;. This + distribution can be selected by navigating to the + <literal>Configuration</literal> and then to the + <literal>Distributions</literal> menu within &man.sysinstall.8;.</para> + + <para>Once source is installed, review the contents of <filename + class="directory">/usr/src/sys</filename>. This directory contains a + number of subdirectories, including those which represent the following + supported architectures: <filename class="directory">amd64</filename>, <filename + class="directory">i386</filename>, <filename class="directory">ia64</filename>, <filename - class="directory">powerpc</filename>, <filename - class="directory">sparc64</filename>, and <filename - class="directory">pc98</filename>. Everything inside a + class="directory">pc98</filename>, <filename + class="directory">powerpc</filename>, and <filename + class="directory">sparc64</filename>. Everything inside a particular architecture's directory deals with that architecture only and the rest of the code is machine independent code common - to all platforms. Notice the logical organization of the - directory structure, with each supported device, file system, - and option in its own subdirectory.</para> - - <para>The examples in this chapter assume the i386 architecture. - If the system has a different architecture, change the path - names accordingly.</para> - - <note> - <para>If <filename class="directory">/usr/src/</filename> does - not exist or it is empty, source has not been installed. The - easiest way to install source is to use - <application>svn</application> as described in <xref - linkend="svn"/>. One should also create a symlink to - <filename class="directory">/usr/src/sys/</filename>:</para> - - <screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen> - </note> - - <para>Next, <application>cd</application> to <filename - class="directory"><replaceable>arch</replaceable>/conf</filename> - and copy the <filename>GENERIC</filename> configuration file to - the name of the custom kernel. For example:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput> -&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen> - - <para>Traditionally, this name is in all capital letters. When + to all platforms. Each supported architecture has a <filename + class="directory">conf</filename> subdirectory + which contains the <filename>GENERIC</filename> kernel + configuration file for that architecture.</para> + + <para>Do not make edits to <filename>GENERIC</filename>. Instead, + copy the file to a different name and make edits to the copy. + The convention is to use a name with all capital letters. When maintaining multiple &os; machines with different hardware, it is a good idea to name it after the machine's hostname. This - example uses - <filename><replaceable>MYKERNEL</replaceable></filename>.</para> + example creates a custom configuration file for the + <literal>amd64</literal> architecture:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput> +&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen> <tip> <para>When finished customizing the kernel configuration file, save a backup copy to a location outside of <filename - class="directory">/usr/src</filename>. Do not edit - <filename>GENERIC</filename> directly.</para> + class="directory">/usr/src</filename>.</para> <para>Alternately, keep the kernel configuration file elsewhere - and create a symbolic link to the file in <filename - class="directory"><replaceable>i386</replaceable></filename>.</para> - - <para>For example:</para> + and create a symbolic link to the file:</para> - <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput> + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput> &prompt.root; <userinput>mkdir /root/kernels</userinput> &prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput> &prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen> </tip> - <para>Edit - <filename><replaceable>MYKERNEL</replaceable></filename> - with a text editor. The default editor is - <application>vi</application>, whose usage is covered well in - many books in the <link - linkend="bibliography">bibliography</link>. An easier editor + <para>The configuration file + <filename><replaceable>MYKERNEL</replaceable></filename> can now be customized + with any ASCII text editor. The default editor is + <application>vi</application>, though an easier editor for beginners, called <application>ee</application>, is also - available. Feel free to change the comment lines at the top to - reflect the configuration or the changes made to differentiate - it from <filename>GENERIC</filename>.</para> - - <para>If the <filename>GENERIC</filename> configuration file seems - overwhelming, follow the descriptions in the <link - linkend="kernelconfig-config">Configuration File</link> - section slowly and carefully.</para> - - <note> - <para>After <link linkend="svn">syncing the source tree</link> - with the latest sources, <emphasis>always</emphasis> read - <filename class="directory">/usr/src/UPDATING</filename> - before performing any update steps. This file describes any - important issues or areas requiring special attention within - the updated source code. - <filename>/usr/src/UPDATING</filename> always matches - the version of the &os; source and contains more up-to-date - information than this Handbook.</para> - </note> - - <para>After saving the edits, compile the source code for the - kernel.</para> - - <procedure> - <title>Building a Kernel</title> - - <note> - <para>It is required to have the full &os; source tree - installed to build the kernel.</para> - </note> - - <step> - <para><command>cd</command> to <filename - class="directory">/usr/src</filename>:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> - </step> - - <step> - <para>Compile the new kernel by specifying the name of the - custom kernel configuration file:</para> - - <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> - </step> - - <step> - <para>Install the new kernel:</para> - - <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> - </step> - </procedure> - - <tip> - <para>By default, when a custom kernel is compiled, - <emphasis>all</emphasis> kernel modules are rebuilt as well. - To update a kernel faster or to build only custom modules, - edit <filename>/etc/make.conf</filename> before starting to - build the kernel:</para> - - <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting> - - <para>This variable specifies the list of modules to build - instead the default of building of all of them.</para> - - <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting> - - <para>This variable sets up a list of top level modules to - exclude from the build process. For other available - variables, refer to &man.make.conf.5;.</para> - </tip> - - <indexterm> - <primary><filename - class="directory">/boot/kernel.old</filename></primary> - </indexterm> - - <para>The new kernel will be copied to <filename - class="directory">/boot/kernel</filename> as - <filename>/boot/kernel/kernel</filename> and the old kernel - will be moved to <filename>/boot/kernel.old/kernel</filename>. - Now, shutdown the system and reboot into the new kernel. - If something goes wrong, refer to the <link - linkend="kernelconfig-trouble">troubleshooting</link> - instructions and the section which explains how to - recover when the new kernel <link - linkend="kernelconfig-noboot">does not boot</link>.</para> - - <note> - <para>Other files relating to the boot process, such as the boot - &man.loader.8; and configuration, are stored in <filename - class="directory">/boot</filename>. Third party or - custom modules can be placed in <filename - class="directory">/boot/kernel</filename>, although users - should be aware that keeping modules in sync with the compiled - kernel is very important. Modules not intended to run with - the compiled kernel may result in instability.</para> - </note> - </sect1> - - <sect1 id="kernelconfig-config"> - <sect1info> - <authorgroup> - <author> - <firstname>Joel</firstname> - <surname>Dahl</surname> - <contrib>Updated by </contrib> - </author> - </authorgroup> - </sect1info> - <title>The Configuration File</title> - + installed with &os;.</para> + <indexterm> <primary>kernel</primary> <secondary>NOTES</secondary> @@ -459,14 +319,18 @@ following line in &man.loader.conf.5;: <secondary>configuration file</secondary> </indexterm> - <para>The general format of a configuration file is quite simple. - Each line contains a keyword and one or more arguments. For - simplicity, most lines only contain one argument. Anything - following a <literal>#</literal> is considered a comment and - ignored. The following sections describe each keyword, in - the order they are listed in <filename>GENERIC</filename>. - For an exhaustive list of architecture dependent options and - devices, refer to <filename>NOTES</filename> in the same + <para>The format of the kernel configuration file is simple. + Each line contains a keyword that represents a device or + subsystem, an argument, and a brief description. Any text + after a <literal>#</literal> is considered a comment and + ignored. To remove kernel support for a device or subsystem, + put a <literal>#</literal> at the beginning of the line + representing that device or subsystem. Do not add or remove a + <literal>#</literal> for any line that you do not understand.</para> + + <para>In addition to the brief descriptions provided in this file, additional + descriptions are contained in + <filename>NOTES</filename>, which can be found in the same directory as <filename>GENERIC</filename> for that architecture. For architecture independent options, refer to <filename>/usr/src/sys/conf/NOTES</filename>.</para> @@ -490,60 +354,18 @@ options IPDIVERT</programlisting> <para>Using this method, the local configuration file expresses local differences from a <filename>GENERIC</filename> kernel. As upgrades are performed, new features added to - <filename>GENERIC</filename> will be also be added to the local + <filename>GENERIC</filename> will also be added to the local kernel unless they are specifically prevented using <literal>nooptions</literal> or <literal>nodevice</literal>. A comprehensive list of configuration directives and their descriptions may be found in &man.config.5;.</para> - <para>The remainder of this chapter addresses the contents of a - typical configuration file and the role various options and - devices play.</para> - <note> <para>To build a file which contains all available options, run the following command as <username>root</username>:</para> <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen> </note> - <indexterm> - <primary>kernel</primary> - <secondary>configuration file</secondary> - </indexterm> - - <para>The following is an example of the - <filename>GENERIC</filename> kernel configuration file with - various additional comments where needed for clarity. This - example should match the copy in - <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename> - fairly closely.</para> - - <indexterm> - <primary>kernel options</primary> - <secondary>machine</secondary> - </indexterm> - - <programlisting>machine i386</programlisting> - - <para>This is the machine architecture. It must be either - <literal>amd64</literal>, <literal>i386</literal>, - <literal>ia64</literal>, <literal>pc98</literal>, - <literal>powerpc</literal>, or - <literal>sparc64</literal>.</para> - - <indexterm> - <primary>kernel options</primary> - <secondary>cpu</secondary> - </indexterm> - <programlisting>cpu I486_CPU -cpu I586_CPU -cpu I686_CPU</programlisting> - - <para>This option specifies the type of CPU. It is fine to have - multiple instances of the CPU entries, but for a custom kernel - it is best to specify the CPU. To determine the CPU type, - review the boot messages in - <filename>/var/run/dmesg.boot</filename>.</para> <indexterm> <primary>kernel options</primary> @@ -558,19 +380,6 @@ cpu I686_CPU</programlisting> The value in the <literal>ident</literal> string will print when the kernel boots.</para> - <programlisting>#To statically compile in device wiring instead of /boot/device.hints -#hints "GENERIC.hints" # Default places to look for devices.</programlisting> - - <para>&man.device.hints.5; is used to configure options for device - drivers. The default location is - <filename>/boot/device.hints</filename>. The - <literal>hints</literal> option compiles these hints statically - into the kernel so that there is no need to create - <filename>/boot/device.hints</filename>.</para> - - <!-- XXX: Add a comment here that explains when compiling hints into - the kernel is a good idea and why. --> - <programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting> <para>This option enables debugging information when passed to @@ -580,12 +389,6 @@ cpu I686_CPU</programlisting> <para>The default system scheduler for &os;. Keep this.</para> - <programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting> - - <para>Allows kernel threads to be preempted by higher priority - threads. This helps with interactivity and allows interrupt - threads to run sooner rather than waiting.</para> - <programlisting>options INET # InterNETworking</programlisting> <para>Networking support. This is mandatory as most programs @@ -962,7 +765,7 @@ device splash # Splash screen and screen saver support</programlist <para>Required by the boot splash screen and screen savers.</para> - <programlisting># syscons is the default console driver, resembling an SCO console + <programlisting># syscons is the default console driver, resembling a SCO console device sc</programlisting> <para>&man.sc.4; is the default console driver and resembles a SCO @@ -1370,6 +1173,112 @@ device fwe # Ethernet over FireWire (non-standard!)</programl </sect2> </sect1> + <sect1 id="kernelconfig-building"> + <title>Building and Installing a Custom Kernel</title> + + <para>After saving the edits, compile the source code for the + kernel.</para> + + <note> + <para>After <link linkend="svn">syncing the source tree</link> + with the latest sources, <emphasis>always</emphasis> read + <filename class="directory">/usr/src/UPDATING</filename> + before performing any update steps. This file describes any + important issues or areas requiring special attention within + the updated source code. + <filename>/usr/src/UPDATING</filename> always matches + the version of the &os; source and contains more up-to-date + information than this Handbook.</para> + </note> + + <warning> + <para>It is easy to remove support for a device or option and + end up with a broken kernel. For example, if the &man.ata.4; + driver is removed from the kernel configuration file, a system + using <acronym>ATA</acronym> disk drivers may not boot. When + in doubt, just leave support in the kernel.</para> + </warning> + + <procedure> + <title>Building a Kernel</title> + <indexterm> + <primary>kernel</primary> + <secondary>building / installing</secondary> + </indexterm> + + <note> + <para>It is required to have the full &os; source tree + installed to build the kernel.</para> + </note> + + <step> + <para><command>cd</command> to <filename + class="directory">/usr/src</filename>:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> + </step> + + <step> + <para>Compile the new kernel by specifying the name of the + custom kernel configuration file:</para> + + <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + </step> + + <step> + <para>Install the new kernel:</para> + + <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + </step> + </procedure> + + <tip> + <para>By default, when a custom kernel is compiled, + <emphasis>all</emphasis> kernel modules are rebuilt as well. + To update a kernel faster or to build only custom modules, + edit <filename>/etc/make.conf</filename> before starting to + build the kernel:</para> + + <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting> + + <para>This variable specifies the list of modules to build + instead the default of building of all of them.</para> + + <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting> + + <para>This variable sets up a list of top level modules to + exclude from the build process. For other available + variables, refer to &man.make.conf.5;.</para> + </tip> + + <indexterm> + <primary><filename + class="directory">/boot/kernel.old</filename></primary> + </indexterm> + + <para>The new kernel will be copied to <filename + class="directory">/boot/kernel</filename> as + <filename>/boot/kernel/kernel</filename> and the old kernel + will be moved to <filename>/boot/kernel.old/kernel</filename>. + Now, shutdown the system and reboot into the new kernel. + If something goes wrong, refer to the <link + linkend="kernelconfig-trouble">troubleshooting</link> + instructions and the section which explains how to + recover when the new kernel <link + linkend="kernelconfig-noboot">does not boot</link>.</para> + + <note> + <para>Other files relating to the boot process, such as the boot + &man.loader.8; and configuration, are stored in <filename + class="directory">/boot</filename>. Third party or + custom modules can be placed in <filename + class="directory">/boot/kernel</filename>, although users + should be aware that keeping modules in sync with the compiled + kernel is very important. Modules not intended to run with + the compiled kernel may result in instability.</para> + </note> + </sect1> + <sect1 id="kernelconfig-trouble"> <title>If Something Goes Wrong</title> diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml index 517e5c2c02..e339f273d9 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml @@ -326,6 +326,11 @@ multi on</programlisting> </sect2> </sect1> +<?ignore + While the installer works, the binaries do not. As of Oct 2013, Linux + emulation is 32-bit but the trial version of Mathematica is only + available as 64-bit. This section should be revisited if Linux + emulation gets 64-bit binary support. <sect1 id="linuxemu-mathematica"> <sect1info> <authorgroup> @@ -336,6 +341,7 @@ multi on</programlisting> </author> </authorgroup> </sect1info> + <title>Installing &mathematica;</title> <indexterm> @@ -344,95 +350,49 @@ multi on</programlisting> </indexterm> <para>This section describes the process of installing the - &linux; version of <application>&mathematica; 5.X</application> + &linux; version of <application>&mathematica; 9.X</application> onto a &os; system. <application>&mathematica;</application> is a commercial, computational software program used in - scientific, engineering, and mathematical fields. It is - available from <ulink - url="http://www.wolfram.com/mathematica/">Wolfram - Research</ulink>.</para> + scientific, engineering, and mathematical fields. A 30 day trial version is + available for download from <ulink + url="http://www.wolfram.com/mathematica/">wolfram.com/mathematica</ulink>.</para> <sect2> <title>Running the &mathematica; Installer</title> - <para>First, tell &os; that - <application>&mathematica;</application>'s &linux; - binaries use the &linux; Application Binary Interface - <acronym>ABI</acronym>. The easiest way to do this is to - set the default ELF brand to &linux; for all unbranded - binaries with the command:</para> - + <para>Before installing &mathematica;, make sure that the + <filename role="package">textproc/linux-f10-aspell</filename> + package or port is installed and that the &man.linprocfs.5; + file system is mounted.</para> + <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen> <para>&os; will now assume that unbranded ELF binaries use the &linux; <acronym>ABI</acronym> which should allow the installer to execute from the CDROM.</para> - <para>Copy the <filename>MathInstaller</filename> to the hard - drive:</para> - - <screen>&prompt.root; <userinput>mount /cdrom</userinput> -&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen> - - <para>In this file, replace <literal>/bin/sh</literal> in - the first line with <literal>/compat/linux/bin/sh</literal>. - This ensures that the installer is executed by the &linux; - version of &man.sh.1;. Next, replace all occurrences of - <literal>Linux)</literal> with <literal>FreeBSD)</literal> - using a text editor or the script below in the next section. - This tells the <application>&mathematica;</application> - installer, to treat &os; as a &linux;-like operating - system. Invoking <command>MathInstaller</command> should now - install <application>&mathematica;</application>.</para> - </sect2> + <para>The downloaded file will be saved to + <filename>/tmp/Mathematica_9.0.1_LINUX.sh</filename>. Become + the superuser and run this installer file:</para> - <sect2> - <title>Modifying the &mathematica; Executables</title> + <programlisting>&prompt.root; <userinput>sh /tmp/Mathematica_9.0.1_LINUX.sh</userinput> +Mathematica Secured 9.0.1 for LINUX Installer Archive - <para>The shell scripts that - <application>&mathematica;</application> created during - installation have to be modified before use. When using - <filename - class="directory">/usr/local/bin</filename> as the directory - for the <application>&mathematica;</application> - executables, symlinks in this directory will point to files - called <filename>math</filename>, - <filename>mathematica</filename>, - <filename>Mathematica</filename>, and - <filename>MathKernel</filename>. In each of these, replace - <literal>Linux)</literal> with <literal>FreeBSD)</literal> - using a text editor or the following shell script:</para> - - <programlisting>#!/bin/sh -cd /usr/local/bin -for i in math mathematica Mathematica MathKernel - do sed 's/Linux)/FreeBSD)/g' $i > $i.tmp - sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp > $i - rm $i.tmp - chmod a+x $i -done</programlisting> - </sect2> +Verifying archive integrity. +Extracting installer. ... + Wolfram Mathematica 9 Installer +Copyright (c) 1988-2013 Wolfram Research, Inc. All rights reserved. - <sect2> - <title>Obtaining a &mathematica; Password</title> +WARNING: Wolfram Mathematica is protected by copyright law and international treaties. Unauthorized +reproduction or distribution may result in severe civil and criminal +penalties and will be prosecuted to the maximum extent possible under law. - <indexterm> - <primary>Ethernet</primary> - <secondary>MAC address</secondary> - </indexterm> +Enter the installation directory, or press ENTER to select /usr/local/Wolfram/Mathematica/9.0: +> +Now installing... +*********************** +Installation complete.</programlisting> - <para>When <application>&mathematica;</application> is started - for the first time, it will ask for a password. If a password - had not yet been obtained from Wolfram Research, run - <command>mathinfo</command> in the installation directory to - obtain the <quote>machine ID</quote>. This machine ID is - based solely on the MAC address of the first Ethernet card, - as the copy of <application>&mathematica;</application> cannot - run on different machines.</para> - - <para>When registering with Wolfram Research, provide the - <quote>machine ID</quote> and they will respond with a - corresponding password consisting of groups of numbers.</para> </sect2> <sect2> @@ -495,14 +455,19 @@ done</programlisting> class="directory">Type1</filename>.</para> </sect2> </sect1> + --> + <!-- + As of October 2013, the trial version is only available in the + Professional and Academic editions (not the Student or Personal + editions) and requires a contact with a product specialist before + the evaluation download link is made available. <sect1 id="linuxemu-maple"> <sect1info> <authorgroup> <author> <firstname>Aaron</firstname> <surname>Kaplan</surname> -<!-- <address><email>aaron@lo-res.org</email></address>--> <contrib>Contributed by </contrib> </author> </authorgroup> @@ -510,7 +475,6 @@ done</programlisting> <author> <firstname>Robert</firstname> <surname>Getschmann</surname> -<!-- <address><email>rob@getschmann.org</email></address>--> <contrib>Thanks to </contrib> </author> </authorgroup> @@ -557,12 +521,13 @@ done</programlisting> <filename>/usr/local/maple/bin/maple.system.type</filename> with the following:</para> + <programlisting> ----- snip ------------------ *** maple.system.type.orig Sun Jul 8 16:35:33 2001 ---- maple.system.type Sun Jul 8 16:35:51 2001 +-- - maple.system.type Sun Jul 8 16:35:51 2001 *************** *** 72,77 **** ---- 72,78 ---- +-- - 72,78 ---- # the IBM RS/6000 AIX case MAPLE_BIN="bin.IBM_RISC_UNIX" ;; @@ -662,7 +627,9 @@ FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ </itemizedlist> </sect2> </sect1> - + --> + <!-- + As of October, 2013, the Linux version of Matlab is only available for 64-bit. <sect1 id="linuxemu-matlab"> <sect1info> <authorgroup> @@ -671,7 +638,6 @@ FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ <surname>Pelleg</surname> <contrib>Contributed by </contrib> </author> - <!-- daniel+handbook@pelleg.org --> </authorgroup> </sect1info> <title>Installing &matlab;</title> @@ -908,6 +874,9 @@ exit 0</programlisting> </sect1> <sect1 id="linuxemu-oracle"> + While the Oracle website is unclear, the installation script is: You + are attempting to install 64-bit Oracle on a 32-bit operating system. + This is not supported and will not work. <sect1info> <authorgroup> <author> @@ -915,7 +884,6 @@ exit 0</programlisting> <surname>Moolenaar</surname> <contrib>Contributed by </contrib> </author> - <!-- marcel@cup.hp.com --> </authorgroup> </sect1info> <title>Installing &oracle;</title> @@ -1118,7 +1086,7 @@ export PATH</programlisting> ! CHOWN=/bin/chown # # Define variables to be used in this script ---- 31,37 ---- + --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h @@ -1169,6 +1137,7 @@ export PATH</programlisting> running on &linux;.</para> </sect2> </sect1> +?> <sect1 id="linuxemu-advanced"> <title>Advanced Topics</title> diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml index 693b0e797d..f46b6db93e 100644 --- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml @@ -608,9 +608,11 @@ -CURRENT under <literal>head</literal> and the respective latest versions of the -STABLE branches under <literal>stable/8</literal> (for - 8.<replaceable>x</replaceable>) and + 8.<replaceable>x</replaceable>), <literal>stable/9</literal> - (9.<replaceable>x</replaceable>).</para> + (9.<replaceable>x</replaceable>) and + <literal>stable/10</literal> + (10.<replaceable>x</replaceable>).</para> </listitem> <listitem> @@ -2108,6 +2110,14 @@ usr.bin/</programlisting> <variablelist> <varlistentry> + <term>RELENG_9_2_0_RELEASE</term> + + <listitem> + <para>&os; 9.2</para> + </listitem> + </varlistentry> + + <varlistentry> <term>RELENG_9_1_0_RELEASE</term> <listitem> diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml index 529bd216e4..bdcac98391 100644 --- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml @@ -6,6 +6,7 @@ --> <chapter id="multimedia"> + <!-- <chapterinfo> <authorgroup> <author> @@ -15,6 +16,7 @@ </author> </authorgroup> </chapterinfo> + --> <title>Multimedia</title> @@ -30,9 +32,10 @@ recorded audio, adding sound effects, and controlling attached MIDI devices.</para> - <para>&os; also supports the playback of video files and DVDs. - The &os; Ports Collection contains applications to encode, - convert, and playback various video media.</para> + <para>&os; also supports the playback of video files and + <acronym>DVD</acronym>s. The &os; Ports Collection contains + applications to encode, convert, and playback various video + media.</para> <para>This chapter describes how to configure sound cards, video playback, TV tuner cards, and scanners on &os;. It also @@ -43,7 +46,7 @@ <itemizedlist> <listitem> - <para>Configure a sound card on os;.</para> + <para>Configure a sound card on &os;.</para> </listitem> <listitem> @@ -59,12 +62,13 @@ </listitem> <listitem> - <para>Playback DVDs, <filename>.mpg</filename>, and - <filename>.avi</filename> files.</para> + <para>Play <acronym>DVD</acronym>s, <filename>.mpg</filename>, + and <filename>.avi</filename> files.</para> </listitem> <listitem> - <para>Rip CD and DVD content into files.</para> + <para>Rip CD and <acronym>DVD</acronym> content into + files.</para> </listitem> <listitem> @@ -78,79 +82,65 @@ <listitem> <para>Configure an image scanner.</para> </listitem> - - <listitem> - <para>How to configure an image scanner.</para> - </listitem> </itemizedlist> <para>Before reading this chapter, you should:</para> <itemizedlist> - <listitem><para>Know how to configure and install a new kernel - (<xref linkend="kernelconfig"/>).</para></listitem> + <listitem><para>Know how to install applications as described in + <xref linkend="ports"/>.</para></listitem> </itemizedlist> - - <warning> - <para>Audio CDs have specialized encodings which differ from the - usual ISO-filesystem. This means that they should not be - mounted using &man.mount.8;.</para> - </warning> - </sect1> <sect1 id="sound-setup"> + <!-- <sect1info> <authorgroup> <author> <firstname>Moses</firstname> <surname>Moore</surname> - <contrib>Contributed by </contrib> - <!-- 20 November 2000 --> + <contrib>Contributed by in November 2000</contrib> </author> </authorgroup> <authorgroup> <author> <firstname>Marc</firstname> <surname>Fonvieille</surname> - <contrib>Enhanced by </contrib> - <!-- 13 September 2004 --> + <contrib>Enhanced by in September 2004</contrib> </author> </authorgroup> </sect1info> + --> <title>Setting Up the Sound Card</title> - <sect2 id="sound-device"> - <title>Configuring the System</title> + <indexterm><primary>PCI</primary></indexterm> + <indexterm><primary>sound cards</primary></indexterm> + <para>Before beginning the configuration, determine the model of + the sound card and the chip it uses. &os; supports a wide + variety of sound cards. Check the supported audio devices + list of the <ulink url="&rel.current.hardware;">Hardware + Notes</ulink> to see if the card is supported and which &os; + driver it uses.</para> - <indexterm><primary>PCI</primary></indexterm> - <indexterm><primary>sound cards</primary></indexterm> - <para>Before beginning the configuration, determine the model of - the sound card and the chip it uses. &os; supports a wide - variety of sound cards. Check the supported audio devices - list of the <ulink url="&rel.current.hardware;">Hardware - Notes</ulink> to see if the card is supported and which &os; - driver it uses.</para> - - <indexterm> - <primary>kernel</primary> - <secondary>configuration</secondary> - </indexterm> + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> - <para>In order to use the sound device, the proper device driver - must be loaded. This may be accomplished in one of two ways. - The easiest way is to load a kernel module for the sound card - with &man.kldload.8;. This example loads the driver for a - Creative &soundblaster; Live! sound card:</para> + <para>In order to use the sound device, its device driver must be + loaded. The easiest way is to load a kernel module for the + sound card with &man.kldload.8;. This example loads the driver + for a built-in audio chipset based on the Intel + specification:</para> - <screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen> + <screen>&prompt.root; <userinput>kldload snd_hda</userinput></screen> <para>To automate the loading of this driver at boot time, add the driver to <filename>/boot/loader.conf</filename>. The line for this driver is:</para> - <programlisting>snd_emu10k1_load="YES"</programlisting> + <programlisting>snd_hda_load="YES"</programlisting> <para>Other available sound modules are listed in <filename>/boot/defaults/loader.conf</filename>. When unsure @@ -169,32 +159,29 @@ after loading the <filename>snd_driver</filename> metadriver, type <command>cat /dev/sndstat</command>.</para> - <para>Users who prefer to statically compile in support for the - sound card in a custom kernel should refer to the instructions - in the next section. For more information about recompiling a - kernel, refer to <xref linkend="kernelconfig"/>.</para> + <sect2> + <title>Configuring a Custom Kernel with Sound Support</title> - <sect3> - <title>Configuring a Custom Kernel with Sound Support</title> + <para>This section is for users who prefer to statically compile + in support for the sound card in a custom kernel. For more + information about recompiling a kernel, refer to <xref + linkend="kernelconfig"/>.</para> - <para>When using a custom kernel to provide sound support, make - sure that the audio framework driver exists in the custom kernel - configuration file:</para> + <para>When using a custom kernel to provide sound support, make + sure that the audio framework driver exists in the custom + kernel configuration file:</para> - <programlisting>device sound</programlisting> + <programlisting>device sound</programlisting> - <para>Next, add support for the sound card. Therefore, you need - to know which driver supports the card. To continue the example - of the Creative &soundblaster; Live! sound card from the - previous section, use the following line in the custom kernel - configuration file:</para> + <para>Next, add support for the sound card. To continue the + example of the built-in audio chipset based on the Intel + specification from the previous section, use the following + line in the custom kernel configuration file:</para> - <programlisting>device snd_emu10k1</programlisting> + <programlisting>device snd_hda</programlisting> <para>Be sure to read the manual page of the driver for the - syntax to use. The explicit syntax for the kernel - configuration of every supported sound driver can also be - found in <filename>/usr/src/sys/conf/NOTES</filename>.</para> + device name to use for the driver.</para> <para>Non-PnP ISA sound cards may require the IRQ and I/O port settings of the card to be added to @@ -231,77 +218,87 @@ hint.sbc.0.flags="0x15"</programlisting> cases, the IRQ or other settings may need to be changed to match the card. Refer to &man.snd.sbc.4; for more information about this card.</para> - </sect3> - </sect2> + </sect2> - <sect2 id="sound-testing"> - <title>Testing the Sound Card</title> + <sect2 id="sound-testing"> + <title>Testing Sound</title> - <para>After rebooting into the custom kernel, or after loading - the required module, the sound card should appear in the system - message buffer. Run &man.dmesg.8; and look for a message - like:</para> + <para>After loading the required module or rebooting into the + custom kernel, the sound card should be detected. To confirm, + run <command>dmesg | grep pcm</command>. This example is + from a system with a built-in Conexant CX20590 chipset:</para> - <screen>pcm0: <Intel ICH3 (82801CA)> port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0 -pcm0: [GIANT-LOCKED] -pcm0: <Cirrus Logic CS4205 AC97 Codec></screen> + <screen>pcm0: <NVIDIA (0x001c) (HDMI/DP 8ch)> at nid 5 on hdaa0 +pcm1: <NVIDIA (0x001c) (HDMI/DP 8ch)> at nid 6 on hdaa0 +pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> at nid 31,25 and 35,27 on hdaa1</screen> - <para>The status of the sound card may also be checked using this - command:</para> + <para>The status of the sound card may also be checked using + this command:</para> - <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput> -FreeBSD Audio Driver (newpcm) + <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput> +FreeBSD Audio Driver (newpcm: 64bit 2009061500/amd64) Installed devices: -pcm0: <Intel ICH3 (82801CA)> at io 0xd800, 0xdc80 irq 5 bufsz 16384 -kld snd_ich (1p/2r/0v channels duplex default)</screen> - - <para>The output may vary between systems. If no - <devicename>pcm</devicename> devices are listed, go back and - review the kernel configuration file and make sure the correct - device driver was chosen. Common problems are listed in <xref - linkend="troubleshooting"/>.</para> - - <para>If all goes well, the sound card should now work in os;. If - the CD-ROM or DVD-ROM drive's audio-out pins are properly - connected to the sound card, one can insert an audio CD in the - drive and play it with &man.cdcontrol.1;:</para> +pcm0: <NVIDIA (0x001c) (HDMI/DP 8ch)> (play) +pcm1: <NVIDIA (0x001c) (HDMI/DP 8ch)> (play) +pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec) default</screen> + + <para>The output will vary depending upon the sound card. If no + <devicename>pcm</devicename> devices are listed, double-check + that the correct device driver was loaded or compiled into the + kernel. The next section lists some common problems and their + solutions.</para> + + <para>If all goes well, the sound card should now work in os;. + If the <acronym>CD</acronym> or <acronym>DVD</acronym> drive + is properly connected to the sound card, one can insert an + audio CD in the drive and play it with + &man.cdcontrol.1;:</para> <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen> - <para>Various applications, such as <filename - role="package">audio/workman</filename> provide a friendlier - interface. The <filename role="package">audio/mpg123</filename> - port can be installed to listen to MP3 audio files.</para> + <warning> + <para>Audio CDs have specialized encodings which means that + they should not be mounted using &man.mount.8;.</para> + </warning> - <para>Another quick way to test the card is to send data to - <filename>/dev/dsp</filename>:</para> + <para>Various applications, such as <filename + role="package">audio/workman</filename>, provide a + friendlier interface. The <filename + role="package">audio/mpg123</filename> port can be installed + to listen to MP3 audio files.</para> - <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen> + <para>Another quick way to test the card is to send data to + <devicename>/dev/dsp</devicename>:</para> - <para>where - <filename><replaceable>filename</replaceable></filename> can - be any file. This command should produce some noise, confirming - that the sound card is actually working.</para> + <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen> - <note> - <para>The <devicename>/dev/dsp*</devicename> device nodes will - be created automatically as needed. When not in use, they - do not exist and will not appear in the output of - &man.ls.1;.</para> - </note> + <para>where + <filename><replaceable>filename</replaceable></filename> can + be any type of file. This command should produce some noise, + confirming that the sound card is working.</para> - <para>Sound card mixer levels can be changed using &man.mixer.8;. - More details can be found in &man.mixer.8;.</para> + <note> + <para>The <devicename>/dev/dsp*</devicename> device nodes will + be created automatically as needed. When not in use, they + do not exist and will not appear in the output of + &man.ls.1;.</para> + </note> + </sect2> - <sect3 id="troubleshooting"> - <title>Common Problems</title> + <sect2 id="troubleshooting"> + <title>Troubleshooting Sound</title> <indexterm><primary>device nodes</primary></indexterm> <indexterm><primary>I/O port</primary></indexterm> <indexterm><primary>IRQ</primary></indexterm> <indexterm><primary>DSP</primary></indexterm> - <informaltable frame="none" pgwide="1"> + <para>Table 8.1 lists some common error messages and their + solutions:</para> + + <table frame="none" pgwide="1"> + <title>Common Error Messages</title> + <tgroup cols="2"> <thead> <row> @@ -335,22 +332,21 @@ kld snd_ich (1p/2r/0v channels duplex default)</screen> <row> <entry><errorname>xxx: can't open /dev/dsp!</errorname></entry> - <entry><para>Check with <command>fstat | grep - dsp</command> if another application is holding the - device open. Noteworthy troublemakers are + <entry><para>Type <command>fstat | grep + dsp</command> to check if another application is + holding the device open. Noteworthy troublemakers are <application>esound</application> and <application>KDE</application>'s sound support.</para></entry> </row> </tbody> </tgroup> - </informaltable> + </table> - <para>Another issue is that modern graphics cards often come - with their own sound driver, for use with - <acronym>HDMI</acronym> and similar. This sound device will - sometimes be enumerated before the sound card and the sound - card will subsequently not be used as the default playback + <para>Modern graphics cards often come with their own sound + driver for use with <acronym>HDMI</acronym>. This sound + device is sometimes enumerated before the sound card meaning + that the sound card will not be used as the default playback device. To check if this is the case, run <application>dmesg</application> and look for <literal>pcm</literal>. The output looks something like @@ -374,25 +370,26 @@ pcm6: <HDA Realtek ALC889 PCM #2 Digital> at cad 2 nid 1 on hdac1 pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 ...</programlisting> - <para>Here the graphics card (<literal>NVidia</literal>) has - been enumerated before the sound card (<literal>Realtek - ALC889</literal>). To use the sound card as the default - playback device, change <varname>hw.snd.default_unit</varname> - to the unit that should be used for playback:</para> + <para>In this example, the graphics card + (<literal>NVidia</literal>) has been enumerated before the + sound card (<literal>Realtek ALC889</literal>). To use the + sound card as the default playback device, change + <varname>hw.snd.default_unit</varname> to the unit that should + be used for playback:</para> <screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=<replaceable>n</replaceable></userinput></screen> - <para>Here, <literal>n</literal> is the number of the sound + <para>where <literal>n</literal> is the number of the sound device to use. In this example, it should be <literal>4</literal>. Make this change permanent by adding the following line to <filename>/etc/sysctl.conf</filename>:</para> <programlisting>hw.snd.default_unit=<replaceable>4</replaceable></programlisting> - </sect3> </sect2> <sect2 id="sound-multiple-sources"> + <!-- <sect2info> <authorgroup> <author> @@ -402,35 +399,32 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </author> </authorgroup> </sect2info> + --> <title>Utilizing Multiple Sound Sources</title> <para>It is often desirable to have multiple sources of sound that - are able to play simultaneously. &os; uses <emphasis>Virtual - Sound Channels</emphasis>, which can be enabled using - &man.sysctl.8;. Virtual channels allow one to multiplex the + are able to play simultaneously. &os; uses <quote>Virtual + Sound Channels</quote> to multiplex the sound card's playback by mixing sound in the kernel.</para> - <para>To set the number of virtual channels, three - &man.sysctl.8; knobs are available:</para> + <para>Three &man.sysctl.8; knobs are available for configuring + virtual channels:</para> <screen>&prompt.root; <userinput>sysctl dev.pcm.0.play.vchans=4</userinput> &prompt.root; <userinput>sysctl dev.pcm.0.rec.vchans=4</userinput> &prompt.root; <userinput>sysctl hw.snd.maxautovchans=4</userinput></screen> - <para>The above example allocates four virtual channels, which - is a practical number for everyday use. Both + <para>This example allocates four virtual channels, which is a + practical number for everyday use. Both <varname>dev.pcm.0.play.vchans=4</varname> and - <varname>dev.pcm.0.rec.vchans=4</varname> are the number of - virtual channels <devicename>pcm0</devicename> has for playback - and recording, and are configurable after a device has been - attached. <literal>hw.snd.maxautovchans</literal> is the number - of virtual channels a new audio device is given when it is - attached using &man.kldload.8;. Since the - <devicename>pcm</devicename> module can be loaded independently - of the hardware drivers, <varname>hw.snd.maxautovchans</varname> - indicates how many virtual channels will be given to devices - when they are attached. Refer to &man.pcm.4; for more - information.</para> + <varname>dev.pcm.0.rec.vchans=4</varname> are configurable after + a device has been attached and represent the number of virtual + channels <devicename>pcm0</devicename> has for playback and + recording. Since the <devicename>pcm</devicename> module can be + loaded independently of the hardware drivers, + <varname>hw.snd.maxautovchans</varname> indicates how many + virtual channels will be given to an audio device when it is + attached. Refer to &man.pcm.4; for more information.</para> <note> <para>The number of virtual channels for a device cannot be @@ -445,6 +439,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </sect2> <sect2> + <!-- <sect2info> <authorgroup> <author> @@ -454,16 +449,16 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </author> </authorgroup> </sect2info> + --> <title>Setting Default Values for Mixer Channels</title> <para>The default values for the different mixer channels are - hardcoded in the source code of the &man.pcm.4; driver. There - are many different applications and daemons that allow values to - be set for the mixer that are remembered between invocations, - but this is not a clean solution. It is possible to set default - mixer values at the driver level. This is accomplished by - defining the appropriate values in + hardcoded in the source code of the &man.pcm.4; driver. While + sound card mixer levels can be changed using &man.mixer.8; or + third-party applications and daemons, this is not a permanent + solution. To instead set default mixer values at the driver + level, define the appropriate values in <filename>/boot/device.hints</filename>, as seen in this example:</para> @@ -476,16 +471,17 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </sect1> <sect1 id="sound-mp3"> + <!-- <sect1info> <authorgroup> <author> <firstname>Chern</firstname> <surname>Lee</surname> - <contrib>Contributed by </contrib> + <contrib>Contributed by in Sept 2001</contrib> </author> </authorgroup> - <!-- 11 Sept 2001 --> </sect1info> + --> <title>MP3 Audio</title> @@ -705,7 +701,7 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> <acronym>MP3</acronym> into raw PCM audio data. Both of these formats can be used with <application>cdrecord</application> to create audio CDs, whereas &man.burncd.8; requires a raw - Pulse-Code Modulation (<acronym>PCM</acronym>. When using + Pulse-Code Modulation (<acronym>PCM</acronym>). When using <acronym>WAV</acronym> files, there will be a small tick sound at the beginning of each track. This sound is the header of the <acronym>WAV</acronym> file. One can remove the @@ -721,48 +717,49 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> </sect1> <sect1 id="video-playback"> + <!-- <sect1info> <authorgroup> <author> <firstname>Ross</firstname> <surname>Lippert</surname> - <contrib>Contributed by </contrib> + <contrib>Contributed by in June 2002</contrib> </author> </authorgroup> - <!-- 5 June 2002 --> </sect1info> + --> <title>Video Playback</title> - <para>Before configuring video playback, determine the model - of the video card and the chip it uses. While + <para>Before configuring video playback, determine the model and + chipset of the video card. While <application>&xorg;</application> supports a wide variety of - video cards, fewer give good playback performance. To obtain - a list of extensions supported by the + video cards, not all provide good playback performance. To + obtain a list of extensions supported by the <application>&xorg;</application> server using the card, run - &man.xdpyinfo.1; while <application>&xorg;</application> is - running.</para> + <command>xdpyinfo</command> while + <application>&xorg;</application> is running.</para> <para>It is a good idea to have a short MPEG test file for - evaluating various players and options. Since some DVD - applications look for DVD media in <filename + evaluating various players and options. Since some + <acronym>DVD</acronym> applications look for + <acronym>DVD</acronym> media in <filename class="directory">/dev/dvd</filename> by default, or have this - device name hardcoded in them, it might be useful to make - symbolic links to the proper devices:</para> + device name hardcoded in them, it might be useful to make a + symbolic links to the proper device:</para> - <screen>&prompt.root; <userinput>ln -sf /dev/acd0 /dev/dvd</userinput> -&prompt.root; <userinput>ln -sf /dev/acd0 /dev/rdvd</userinput></screen> + <screen>&prompt.root; <userinput>ln -sf /dev/cd0 /dev/dvd</userinput></screen> <para>Due to the nature of &man.devfs.5;, manually created links - will not persist after a system reboot. In order to create the - symbolic links automatically when the system boots, add the - following lines to <filename>/etc/devfs.conf</filename>:</para> + will not persist after a system reboot. In order to recreate + the symbolic link automatically when the system boots, add the + following line to <filename>/etc/devfs.conf</filename>:</para> - <programlisting>link acd0 dvd -link acd0 rdvd</programlisting> + <programlisting>link cd0 dvd</programlisting> - <para>DVD decryption invokes special DVD-ROM functions and - requires write permission on the DVD devices.</para> + <para><acronym>DVD</acronym> decryption invokes certain functions + that require write permission to the <acronym>DVD</acronym> + device.</para> <para>To enhance the shared memory <application>&xorg;</application> interface, it is @@ -780,7 +777,7 @@ kern.ipc.shmall=32768</programlisting> <indexterm><primary>DGA</primary></indexterm> <para>There are several possible ways to display video under - <application>&xorg;</application>. What works is largely + <application>&xorg;</application> and what works is largely hardware dependent. Each method described below will have varying quality across different hardware.</para> @@ -794,41 +791,55 @@ kern.ipc.shmall=32768</programlisting> <listitem> <para>XVideo: an extension to the - <application>&xorg;</application> interface which supports - video in any drawable object.</para> + <application>&xorg;</application> interface which + allows video to be directly displayed in drawable objects + through a special acceleration. This extension provides + good quality playback even on low-end machines. The next + section describes how to determine if this extension is + running.</para> </listitem> <listitem> - <para><acronym>SDL</acronym>: the Simple Directmedia - Layer.</para> + <para><acronym>SDL</acronym>: the Simple Directmedia Layer is + a porting layer for many operating systems, allowing + cross-platform applications to be developed which make + efficient use of sound and graphics. <acronym>SDL</acronym> + provides a low-level abstraction to the hardware which can + sometimes be more efficient than the + <application>&xorg;</application> interface. On &os;, + <acronym>SDL</acronym> can be installed using the <filename + role="package">devel/sdl20</filename> package or + port.</para> </listitem> <listitem> - <para><acronym>DGA</acronym>: the Direct Graphics - Access.</para> + <para><acronym>DGA</acronym>: the Direct Graphics Access is an + <application>&xorg;</application> extension which allows a + program to bypass the <application>&xorg;</application> + server and directly alter the framebuffer. Because it + relies on a low level memory mapping, programs using it must + be run as <username>root</username>. The + <acronym>DGA</acronym> extension can be tested and + benchmarked using &man.dga.1;. When <command>dga</command> + is running, it changes the colors of the display whenever a + key is pressed. To quit, press <keycap>q</keycap>.</para> </listitem> <listitem> - <para>SVGAlib: low level console graphics layer.</para> + <para>SVGAlib: a low level console graphics layer.</para> </listitem> </orderedlist> <sect3 id="video-interface-xvideo"> <title>XVideo</title> - <para><application>&xorg;</application> has an extension called - <emphasis>XVideo</emphasis>, also known as Xvideo, Xv, and xv. - It allows video to be directly displayed in drawable objects - through a special acceleration. This extension provides - good quality playback even on low-end machines.</para> - - <para>To check whether the extension is running, use + <para>To check whether this extension is running, use <command>xvinfo</command>:</para> <screen>&prompt.user; <userinput>xvinfo</userinput></screen> - <para>XVideo is supported for the card if the result looks - like:</para> + <para>XVideo is supported for the card if the result is similar + to:</para> <screen>X-Video Extension version 2.2 screen #0 @@ -899,57 +910,22 @@ kern.ipc.shmall=32768</programlisting> depth: 1 red, green, blue masks: 0x0, 0x0, 0x0</screen> - <para>The formats listed, such as YUV2 and YUV12, are not present - with every implementation of XVideo and their absence may hinder - some players.</para> + <para>The formats listed, such as YUV2 and YUV12, are not + present with every implementation of XVideo and their absence + may hinder some players.</para> - <para>If the result looks like:</para> + <para>If the result instead looks like:</para> - <screen>X-Video Extension version 2.2 + <screen>X-Video Extension version 2.2 screen #0 no adaptors present</screen> - <para>XVideo is probably not supported for the card. This means - that it will be more difficult for the display to meet the - computational demands of rendering video. Depending on the - video card and processor, one might still be able to have a - satisfying experience.</para> - - </sect3> - - <sect3 id="video-interface-SDL"> - <title>Simple Directmedia Layer</title> - - <para>The Simple Directmedia Layer, SDL, is a - porting layer for many operating systems - allowing cross-platform applications to be developed which make - efficient use of sound and graphics. The SDL layer provides a - low-level abstraction to the hardware which can sometimes be - more efficient than the <application>&xorg;</application> - interface.</para> - - <para><acronym>SDL</acronym> can be installed using the <filename - role="package">devel/sdl12</filename> package or port.</para> - - </sect3> - - <sect3 id="video-interface-DGA"> - <title>Direct Graphics Access</title> - - <para><acronym>DGA</acronym> is an - <application>&xorg;</application> extension which allows a - program to bypass the <application>&xorg;</application> server - and directly alter the framebuffer. Because it relies on a low - level memory mapping, programs using it must be run as - <username>root</username>.</para> - - <para>The <acronym>DGA</acronym> extension can be tested and - benchmarked using &man.dga.1;. When <command>dga</command> is - running, it changes the colors of the display whenever a key is - pressed. To quit, press <keycap>q</keycap>.</para> - - </sect3> -</sect2> + <para>XVideo is probably not supported for the card. This means + that it will be more difficult for the display to meet the + computational demands of rendering video, depending on the + video card and processor.</para> + </sect3> + </sect2> <sect2 id="video-ports"> <title>Ports and Packages Dealing with Video</title> @@ -961,258 +937,164 @@ no adaptors present</screen> the &os; Ports Collection which can be used for video playback.</para> - <para>Many of the video applications which run on &os; were - developed as &linux; applications. Many of these applications - are still beta-quality. Some of the problems commonly - encountered with video packages on &os; include:</para> + <sect3 id="video-mplayer"> + <title><application>MPlayer</application> and + <application>MEncoder</application></title> - <orderedlist> + <para><application>MPlayer</application> is a command-line video + player with an optional graphical interface which aims to + provide speed and flexibility. Other graphical front-ends to + <application>MPlayer</application> are available from the &os; + Ports Collection.</para> + + <indexterm><primary>MPlayer</primary></indexterm> + + <para><application>MPlayer</application> can be installed using + the <filename role="package">multimedia/mplayer</filename> + package or port. Several compile options are available and a + variety of hardware checks occur during the build process. + For these reasons, some users prefer to build the port rather + than install the package.</para> + + <para>When compiling the port, the menu options should be + reviewed to determine the type of support to compile into the + port. If an option is not selected, + <application>MPlayer</application> will not be able to + display that type of video format. Use the arrow keys and + spacebar to select the required formats. When finished, + press <keycap>Enter</keycap> to continue the port compile + and installation.</para> + + <para>By default, the package or port will build the + <command>mplayer</command> command line utility and the + <command>gmplayer</command> graphical utility. To encode + videos, compile the <filename + role="package">multimedia/mencoder</filename> port. Due to + licensing restrictions, a package is not available for + <application>MEncoder</application>.</para> + + <para>The first time <application>MPlayer</application> is run, + it will create <filename + class="directory">~/.mplayer</filename> in the user's home + directory. This subdirectory contains default versions of + the user-specific configuration files.</para> + + <para>This section describes only a few common uses. Refer to + mplayer(1) for a complete description of its numerous + options.</para> + + <para>To play the file + <filename><replaceable>testfile.avi</replaceable></filename>, + specify the video interfaces with <option>-vo</option>, as + seen in the following examples:</para> + + <screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen> + + <screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen> + + <screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen> + + <para>It is worth trying all of these options, as their + relative performance depends on many factors and will vary + significantly with hardware.</para> + + <para>To play a <acronym>DVD</acronym>, replace + <filename><replaceable>testfile.avi</replaceable></filename> + with <option>dvd://<replaceable>N</replaceable> -dvd-device + <replaceable>DEVICE</replaceable></option>, where + <replaceable>N</replaceable> is the title number to play and + <replaceable>DEVICE</replaceable> is the device node for the + <acronym>DVD</acronym>. For example, to play title 3 from + <devicename>/dev/dvd</devicename>:</para> + + <screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen> - <listitem> - <para>An application cannot playback a file which another - application produced.</para> - </listitem> + <note> + <para>The default <acronym>DVD</acronym> device can be defined + during the build of the <application>MPlayer</application> + port by including the + <makevar>WITH_DVD_DEVICE=/path/to/desired/device</makevar> + option. By default, the device is + <filename>/dev/cd0</filename>. More details can be found in + the port's <filename>Makefile.options</filename>.</para> + </note> - <listitem> - <para>An application cannot playback a file which the - application itself produced.</para> - </listitem> + <para>To stop, pause, advance, and so on, use a keybinding. To + see the list of keybindings, run <command>mplayer + -h</command> or read mplayer(1).</para> - <listitem> - <para>The same application on two different machines, - rebuilt on each machine for that machine, plays back the - same file differently.</para> - </listitem> + <para>Additional playback options include <option>-fs + -zoom</option>, which engages fullscreen mode, and + <option>-framedrop</option>, which helps performance.</para> - <listitem> - <para>A seemingly trivial filter, like rescaling of the image - size, results in bad artifacts from a buggy rescaling - routine.</para> - </listitem> + <para>Each user can add commonly used options to their + <filename>~/.mplayer/config</filename> like so:</para> - <listitem> - <para>An application frequently dumps core.</para> - </listitem> + <programlisting>vo=xv +fs=yes +zoom=yes</programlisting> - <listitem> - <para>Documentation is not installed with the port and can be - found either on the web or under the port's <filename - class='directory'>work</filename> - directory.</para> - </listitem> + <para><command>mplayer</command> can be used to rip a + <acronym>DVD</acronym> title to a <filename>.vob</filename>. + To dump the second title from a <acronym>DVD</acronym>:</para> - </orderedlist> + <screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen> - <para>Many applications may also exhibit - <quote>&linux;-isms</quote>. There may be issues resulting from - the way some standard libraries are implemented in the &linux; - distributions, or some features of the &linux; kernel which have - been assumed by the authors of the applications. These issues - are not always noticed and worked around by the port - maintainers, which can lead to problems like these:</para> + <para>The output file, <filename>out.vob</filename>, will be in + <acronym>MPEG</acronym> format.</para> - <orderedlist> - <listitem> - <para>The use of <filename>/proc/cpuinfo</filename> to detect - processor characteristics.</para> - </listitem> + <para>Anyone wishing to obtain a high level of expertise with + &unix; video should consult <ulink + url="http://www.mplayerhq.hu/DOCS/">mplayerhq.hu/DOCS</ulink> + as it is technically informative. This documentation should + be considered as required reading before submitting any bug + reports.</para> - <listitem> - <para>A misuse of threads which causes a program to hang upon - completion instead of truly terminating.</para> - </listitem> + <indexterm> + <primary>mencoder</primary> + </indexterm> - <listitem> - <para>Relies on software which is not yet available in the - &os; Ports Collection.</para> - </listitem> - </orderedlist> + <para>Before using <command>mencoder</command>, it is a good + idea to become familiar with the options described at + <ulink + url="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">mplayerhq.hu/DOCS/HTML/en/mencoder.html</ulink>. + There are innumerable ways to improve quality, lower bitrate, + and change formats, and some of these options may make the + difference between good or bad performance. Improper + combinations of command line options can yield output files + that are unplayable even by <command>mplayer</command>.</para> - <sect3 id="video-mplayer"> - <title>MPlayer</title> + <para>Here is an example of a simple copy:</para> - <para><application>MPlayer</application> is a command-line video - player with an optional graphical interface which aims to - provide speed and flexibility. This application, as well as - other graphical front-ends, is available from the &os; Ports - Collection.</para> + <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen> - <sect4 id="video-mplayer-building"> - <title>Building MPlayer</title> - - <indexterm><primary>MPlayer</primary> - <secondary>making</secondary></indexterm> - - <para><application>MPlayer</application> is available as a - package or port in <filename - role="package">multimedia/mplayer</filename>. Several - compile options are available and a variety of hardware - checks occur during the build process. For these reasons, - some users prefer to build the port rather than install the - package. The available options will be displayed in a - menu after these commands are input:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mplayer</userinput> -&prompt.root; <userinput>make</userinput></screen> - - <para>The menu options should be reviewed to determine the - type of support to compile into the port. If an option is - not selected, <application>MPlayer</application> will not be - able to display that type of video format. Use the arrow - keys and spacebar to select the required formats. When - finished, press <keycap>Enter</keycap> to continue the port - compile and installation.</para> - - <para>By default, this package or port will build the - <command>mplayer</command> command line utility and the - <command>gmplayer</command> graphical utility. To encode - videos, install the <filename - role="package">multimedia/mencoder</filename> port. Due - to licensing restrictions, a package is not available for - <command>MEncoder</command>.</para> - - </sect4> - - <sect4 id="video-mplayer-using"> - <title>Using MPlayer</title> - - <indexterm><primary>MPlayer</primary> - <secondary>use</secondary></indexterm> - - <para>The first time <application>MPlayer</application> is - run, it will create <filename - class="directory">~/.mplayer</filename> in the user's - home directory. This subdirectory contains default versions - of the user-specific configuration files.</para> - - <para>This section describes only a few common uses. Refer - to the <command>mplayer</command> manual page for a complete - description of its numerous options.</para> - - <para>To play the file - <filename><replaceable>testfile.avi</replaceable></filename>, - specify the video interfaces with - <option>-vo</option>:</para> - - <screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen> - - <screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen> - -<screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen> - -<screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen> - -<screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen> - - <para>It is worth trying all of these options, as their - relative performance depends on many factors and will vary - significantly with hardware.</para> - - <para>To play a DVD, replace the - <filename><replaceable>testfile.avi</replaceable></filename> - with <option>dvd://<replaceable>N</replaceable> -dvd-device - <replaceable>DEVICE</replaceable></option>, where - <replaceable>N</replaceable> is the title number to play - and <filename><replaceable>DEVICE</replaceable></filename> - is the device node for the DVD-ROM. For example, to play - title 3 from <devicename>/dev/dvd</devicename>:</para> - - <screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen> - - <note> - <para>The default DVD device can be defined during the build - of the <application>MPlayer</application> port by - including the - <makevar>WITH_DVD_DEVICE=/path/to/desired/device</makevar> - option. By default, the device is - <filename>/dev/acd0</filename>. More details can be found - in the port's - <filename>Makefile.options</filename>.</para> - </note> - - <para>To stop, pause, advance, and so on, consult the - keybindings, which are displayed by running <command>mplayer - -h</command>, or read the manual page.</para> - - <para>Additional playback options include - <option>-fs -zoom</option>, which engages fullscreen mode, - and <option>-framedrop</option>, which helps - performance.</para> - - <para>Each user can add commonly used options to their - <filename>~/.mplayer/config</filename> like so:</para> - - <programlisting>vo=xv -fs=yes -zoom=yes</programlisting> + <para>To rip to a file, use <option>-dumpfile</option> with + <command>mplayer</command>.</para> - <para><command>mplayer</command> can be used to rip a DVD - title to a <filename>.vob</filename>. To dump the second - title from a DVD:</para> - - <screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen> - - <para>The output file, <filename>out.vob</filename>, will be - MPEG and can be manipulated by the other packages described - in this section.</para> - - <para>The <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer - documentation</ulink> is technically informative and - should be consulted by anyone wishing to obtain a high level - of expertise with &unix; video. The - <application>MPlayer</application> mailing list is hostile - to anyone who has not bothered to read the documentation, so - before making a bug report, read the documentation - first.</para> - - </sect4> - <sect4 id="video-mencoder"> - <title><application>MEncoder</application></title> - - <indexterm> - <primary>mencoder</primary> - </indexterm> - - <para>Before using <command>mencoder</command>, it is a good - idea to become familiar with the options described in the - <ulink - url="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">HTML - documentation</ulink>. There are innumerable ways to - improve quality, lower bitrate, and change formats, and some - of these options may make the difference between good or bad - performance. Improper combinations of command line options - can yield output files that are unplayable even by - <command>mplayer</command>.</para> - - <para>Here is an example of a simple copy:</para> - - <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen> - - <para>To rip to a file, use <option>-dumpfile</option> with - <command>mplayer</command>.</para> - - <para>To convert - <filename><replaceable>input.avi</replaceable></filename> - to the MPEG4 codec with MPEG3 audio encoding, first install - the <filename role="package">audio/lame</filename> port. - Due to licensing restrictions, a package is not available. - Once installed, type:</para> - - <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \ - -ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen> + <para>To convert + <filename><replaceable>input.avi</replaceable></filename> to + the MPEG4 codec with MPEG3 audio encoding, first install the + <filename role="package">audio/lame</filename> port. Due to + licensing restrictions, a package is not available. Once + installed, type:</para> - <para>This will produce output playable by applications such - as <command>mplayer</command> and - <command>xine</command>.</para> + <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \ + -ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen> - <para><filename><replaceable>input.avi</replaceable></filename> - can be replaced with <option>dvd://1 -dvd-device - /dev/dvd</option> and run as <username>root</username> - to re-encode a DVD title directly. Since it may take a few - tries to get the desired result, it is recommended to dump - the title to a file and to work on the file.</para> - </sect4> + <para>This will produce output playable by applications such as + <command>mplayer</command> and <command>xine</command>.</para> + <para><filename><replaceable>input.avi</replaceable></filename> + can be replaced with <option>dvd://1 -dvd-device + /dev/dvd</option> and run as <username>root</username> to + re-encode a <acronym>DVD</acronym> title directly. Since it + may take a few tries to get the desired result, it is + recommended to instead dump the title to a file and to work on + the file.</para> </sect3> <sect3 id="video-xine"> @@ -1234,40 +1116,35 @@ zoom=yes</programlisting> to open a specific file.</para> <para>Alternatively, <application>xine</application> may be - invoked to play a file immediately without the graphical - interface:</para> - - <screen>&prompt.user; <userinput>xine</userinput></screen> - - <para>Alternatively, it may be invoked to play a file - immediately without the GUI with the command:</para> + invoked from the command line + by specifying the name of the file to play:</para> <screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen> - <para>The <ulink - url="http://dvd.sourceforge.net/xine-howto/en_GB/html/howto.html"> - xine HOWTO</ulink> contains a chapter on performance - improvement which is general to all players.</para> + <para>Refer to <ulink + url="http://www.xine-project.org/faq"> + xine-project.org/faq</ulink> for more information and + troubleshooting tips.</para> </sect3> <sect3 id="video-ports-transcode"> - <title>The <application>transcode</application> + <title>The <application>Transcode</application> Utilities</title> - <para><application>transcode</application> provides a suite of + <para><application>Transcode</application> provides a suite of tools for re-encoding video and audio files. - <application>transcode</application> can be used to merge + <application>Transcode</application> can be used to merge video files or repair broken files using command line tools - with <filename>stdin/stdout</filename> stream + with stdin/stdout stream interfaces.</para> - <para><application>transcode</application> can be installed - using the <filename + <para>In &os;, <application>Transcode</application> can be + installed using the <filename role="package">multimedia/transcode</filename> package or port. Many users prefer to compile the port as it provides a menu of compile options for specifying the support and codecs to compile in. If an option is not selected, - <application>transcode</application> will not be able to + <application>Transcode</application> will not be able to encode that format. Use the arrow keys and spacebar to select the required formats. When finished, press <keycap>Enter</keycap> to continue the port compile and @@ -1276,27 +1153,29 @@ zoom=yes</programlisting> <para>This example demonstrates how to convert a DivX file into a PAL MPEG-1 file (PAL VCD):</para> - <screen>&prompt.user; <userinput>transcode -i + <screen>&prompt.user; <userinput>transcode -i <replaceable>input.avi</replaceable> -V --export_prof vcd-pal -o output_vcd</userinput> &prompt.user; <userinput>mplex -f 1 -o <replaceable>output_vcd.mpg output_vcd.m1v output_vcd.mpa</replaceable></userinput></screen> - <para>The resulting MPEG file, - <filename><replaceable>output_vcd.mpg</replaceable></filename>, - is ready to be played with <application>MPlayer</application>. - The file can be burned on a CD-R media to create a Video CD. In - this, install and use the <filename - role="package">multimedia/vcdimager</filename> and <filename - role="package">sysutils/cdrdao</filename> programs.</para> - - <para>In addition to the manual page for - <command>transcode</command>, refer to the <ulink - url="http://www.transcoding.org/cgi-bin/transcode">transcode - wiki</ulink> for further information and examples.</para> - </sect3> -</sect2> + <para>The resulting <acronym>MPEG</acronym> file, + <filename><replaceable>output_vcd.mpg</replaceable></filename>, + is ready to be played with <application>MPlayer</application>. + The file can be burned on a <acronym>CD</acronym> media to + create a video <acronym>CD</acronym> using a utility such as + <filename + role="package">multimedia/vcdimager</filename> or <filename + role="package">sysutils/cdrdao</filename>.</para> + + <para>In addition to the manual page for + <command>transcode</command>, refer to <ulink + url="http://www.transcoding.org/cgi-bin/transcode">transcoding.org/cgi-bin/transcode</ulink> + for further information and examples.</para> + </sect3> + </sect2> </sect1> <sect1 id="tvcard"> + <!-- <sect1info> <authorgroup> <author> @@ -1309,31 +1188,28 @@ zoom=yes</programlisting> <author> <firstname>Marc</firstname> <surname>Fonvieille</surname> - <contrib>Enhanced and adapted by </contrib> - <!-- 02 January 2004 --> + <contrib>Enhanced and adapted by in January 2004</contrib> </author> </authorgroup> </sect1info> + --> - <title>Setting Up TV Cards</title> + <title>TV Cards</title> <indexterm> <primary>TV cards</primary> </indexterm> - <sect2> - <title>Introduction</title> + <para>TV cards can be used to watch broadcast or cable TV on a + computer. Most cards accept composite video via an + <acronym>RCA</acronym> or S-video input and some cards include a + <acronym>FM</acronym> radio tuner.</para> - <para>TV cards allow can be used to watch broadcast or cable TV on - a computer. Most cards accept composite video via an RCA or - S-video input and some cards include a FM radio tuner.</para> - - <para>&os; provides support for PCI-based TV cards using a - Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a - video capture chip with the &man.bktr.4; driver. Ensure the - board comes with a supported tuner. Consult &man.bktr.4; for a - list of supported tuners.</para> - </sect2> + <para>&os; provides support for PCI-based TV cards using a + Brooktree Bt848/849/878/879 video capture chip with the + &man.bktr.4; driver. This driver supports most Pinnacle PCTV + video cards. Before purchasing a TV card, consult &man.bktr.4; for + a list of supported tuners.</para> <sect2> <title>Loading the Driver</title> @@ -1358,9 +1234,9 @@ device smbus</programlisting> components are interconnected via an I2C bus. Then, build and install a new kernel.</para> - <para>To test the driver, reboot the system. The TV card - should appear in the boot messages, as seen in this - example:</para> + <para>To test that the tuner is correctly detected, reboot the + system. The TV card should appear in the boot messages, as + seen in this example:</para> <programlisting>bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0 iicbb0: <I2C bit-banging driver> on bti2c0 @@ -1369,11 +1245,10 @@ iicbus1: <Philips I2C bus> on iicbb0 master-only smbus0: <System Management Bus> on bti2c0 bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> - <para>The messages will differ according to the hardware. Check - the messages to determine if the tuner is correctly detected. - It is still possible to override some of the detected - parameters with &man.sysctl.8; MIBs and kernel configuration - file options. For example, to force the tuner to a Philips + <para>The messages will differ according to the hardware. + If necessary, it is possible to override some of the detected + parameters using &man.sysctl.8; or custom kernel configuration + options. For example, to force the tuner to a Philips SECAM tuner, add the following line to a custom kernel configuration file:</para> @@ -1383,9 +1258,8 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <screen>&prompt.root; <userinput>sysctl hw.bt848.tuner=6</userinput></screen> - <para>Refer to &man.bktr.4; and - <filename>/usr/src/sys/conf/NOTES</filename> for more - details on the available options.</para> + <para>Refer to &man.bktr.4; for a description of the available + &man.sysctl.8; parameters and kernel options.</para> </sect2> <sect2> @@ -1418,11 +1292,11 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <sect2> <title>Troubleshooting</title> - <para>If any problems are encountered with the TV card, - check that the video capture chip and the tuner are - supported by &man.bktr.4; and that the right configuration - options were used. For more support and various questions - about TV cards, refer to the archives of the + <para>If any problems are encountered with the TV card, check + that the video capture chip and the tuner are supported by + &man.bktr.4; and that the right configuration options were + used. For more support or to ask questions + about supported TV cards, refer to the &a.multimedia.name; mailing list.</para> </sect2> </sect1> @@ -1430,68 +1304,66 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <sect1 id="mythtv"> <title>MythTV</title> - <para>MythTV is a popular, open source <acronym - role="Personal Video Recorder">PVR</acronym> - application. This section demonstrates how to install and - setup MythTV on &os;. Refer to the <ulink - url="http://www.mythtv.org/wiki/">MythTV wiki</ulink> for + <para>MythTV is a popular, open source Personal Video Recorder + (<acronym>PVR</acronym>) application. This section demonstrates + how to install and setup MythTV on &os;. Refer to <ulink + url="http://www.mythtv.org/wiki/">mythtv.org/wiki</ulink> for more information on how to use MythTV.</para> - <para>MythTV requires a frontend and a backend; however, - it allows the user to have the frontend and backend on - different machines.</para> - - <para>For the frontend, <filename - role="package">multimedia/mythtv-frontend</filename> is - required, as well as an X server, which can be found in - <filename role="package">x11/xorg</filename>. Ideally, the - frontend computer also has a video card that supports <acronym - role="X-Video Motion Compensation">XvMC</acronym> and, - optionally, a <acronym role="Linux Infrared Remote - Control">LIRC</acronym>-compatible remote.</para> - - <para>For the backend, <filename - role="package">multimedia/mythtv</filename> is required, - along with the &mysql; database server. Optionally a tuner - and storage for any recorded data. The &mysql; package should - be automatically installed as a dependency when installing - <filename role="package">multimedia/mythtv</filename>.</para> + <para>MythTV requires a frontend and a backend. These + components can either be installed on the same system or on + different machines.</para> + + <para>The frontend can be installed on &os; using the <filename + role="package">multimedia/mythtv-frontend</filename> package + or port. <application>&xorg;</application> must also be + installed and configured as described in <xref + linkend="x11"/>. Ideally, this system has a video card that + supports X-Video Motion Compensation + (<acronym>XvMC</acronym>) and, optionally, a Linux Infrared + Remote Control (<acronym>LIRC</acronym>)-compatible + remote.</para> + + <para>To install both the backend and the frontend on &os;, use + the <filename role="package">multimedia/mythtv</filename> + package or port. A &mysql; database server is also required + and should automatically be installed as a dependency. + Optionally, this system should have a tuner card and + sufficient storage to hold recorded data.</para> <sect2> <title>Hardware</title> - <para>MythTV is designed to utilize <acronym - role="Video for Linux">V4L</acronym> to access video input - devices such as encoders and tuners. At this time, MythTV - works best with <acronym role="Universal Serial - Bus">USB</acronym> DVB-S/C/T cards supported by <filename - role="package">multimedia/webcamd</filename>, as it provides - a <acronym - role="Video for Linux">V4L</acronym> userland application. - Any <acronym role="Digital Video Broadcasting">DVB</acronym> - card supported by <application>webcamd</application> should - work with MythTV. A list of known working cards can be - found <ulink - url="http://wiki.freebsd.org/WebcamCompat">here</ulink>. + <para>MythTV uses Video for Linux (<acronym>V4L</acronym>) to + access video input devices such as encoders and tuners. In + &os;, MythTV works best with <acronym>USB</acronym> DVB-S/C/T + cards as they are well supported by the <filename + role="package">multimedia/webcamd</filename> package or port + which provides a <acronym>V4L</acronym> userland application. + Any Digital Video Broadcasting (<acronym>DVB</acronym>) card + supported by <application>webcamd</application> should work + with MythTV. A list of known working cards can be found at + <ulink + url="http://wiki.freebsd.org/WebcamCompat">wiki.freebsd.org/WebcamCompat</ulink>. Drivers are also available for Hauppauge cards in the - following ports: <filename + <filename role="package">multimedia/pvr250</filename> and <filename - role="package">multimedia/pvrxxx</filename>, but they + role="package">multimedia/pvrxxx</filename> ports, but they provide a non-standard driver interface that does not work with versions of MythTV greater than 0.23. Due to licensing restrictions, no packages are available and these two ports must be compiled.</para> - <para>The <ulink url="http://wiki.freebsd.org/HTPC">HTPC - wiki page</ulink> contains a list of all available <acronym - role="Digital Video Broadcasting">DVB</acronym> + <para>The <ulink + url="http://wiki.freebsd.org/HTPC">wiki.freebsd.org/HTPC</ulink> + page contains a list of all available <acronym>DVB</acronym> drivers.</para> </sect2> <sect2> - <title>Setting up MythTV</title> + <title>Setting up the MythTV Backend</title> - <para>To install the MythTV port:</para> + <para>To install MythTV using the port:</para> <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mythtv</userinput> &prompt.root; <userinput>make install</userinput></screen> @@ -1500,11 +1372,11 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <screen>&prompt.root; <userinput>mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql</userinput></screen> - <para>Configure the backend:</para> + <para>Then, configure the backend:</para> <screen>&prompt.root; <userinput>mythtv-setup</userinput></screen> - <para>Start the backend:</para> + <para>Finally, start the backend:</para> <screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' >> /etc/rc.conf</userinput> &prompt.root; <userinput>service mythbackend start</userinput></screen> @@ -1512,16 +1384,17 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> </sect1> <sect1 id="scanners"> + <!-- <sect1info> <authorgroup> <author> <firstname>Marc</firstname> <surname>Fonvieille</surname> - <contrib>Written by </contrib> - <!-- 04 August 2004 --> + <contrib>Written by in August 2004</contrib> </author> </authorgroup> </sect1info> + --> <title>Image Scanners</title> @@ -1540,9 +1413,9 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <para>&os; supports both SCSI and USB scanners. Be sure the scanner is supported by <application>SANE</application> prior to performing any configuration. Refer to the <ulink - url="http://www.sane-project.org/sane-supported-devices.html"> - supported devices list</ulink> for more information about supported - scanners.</para> + url="http://www.sane-project.org/sane-supported-devices.html"> + supported devices list</ulink> for more information about + supported scanners.</para> <sect2> <title>Kernel Configuration</title> @@ -1584,7 +1457,7 @@ device ehci</programlisting> <para>If the scanner uses a SCSI interface, it is important to know which SCSI controller board it will use. Depending upon the SCSI chipset, a custom kernel configuration file - may be needed. The <filename>GENERIC</filename> kernel + may be needed. The <filename>GENERIC</filename> kernel supports the most common SCSI controllers. Refer to <filename>/usr/src/sys/conf/NOTES</filename> to determine the correct line to add to a custom kernel configuration diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml index 0d57931e90..8a270095e9 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -6,28 +6,28 @@ --> <chapter id="network-servers"> + <!-- <chapterinfo> <authorgroup> <author> <firstname>Murray</firstname> <surname>Stokely</surname> - <contrib>Reorganized by </contrib> + <contrib>Reorganized by in July 2004</contrib> </author> </authorgroup> - <!-- 23 July 2004 --> </chapterinfo> + --> <title>Network Servers</title> <sect1 id="network-servers-synopsis"> <title>Synopsis</title> - <para>This chapter covers some of the more frequently used - network services on &unix; systems. This includes - installing, configuring, testing, and maintaining - many different types of network services. Example - configuration files are included throughout this - chapter for reference.</para> + <para>This chapter covers some of the more frequently used network + services on &unix; systems. This includes installing, + configuring, testing, and maintaining many different types of + network services. Example configuration files are included + throughout this chapter for reference.</para> <para>By the end of this chapter, readers will know:</para> @@ -89,6 +89,10 @@ <command>syslogd</command>, to accept logs from remote hosts.</para> </listitem> + + <listitem> + <para>How to set up <acronym>iSCSI</acronym>.</para> + </listitem> </itemizedlist> <para>This chapter assumes a basic knowledge of:</para> @@ -110,6 +114,7 @@ </sect1> <sect1 id="network-inetd"> + <!-- <sect1info> <authorgroup> <author> @@ -125,6 +130,7 @@ </author> </authorgroup> </sect1info> + --> <title>The <application>inetd</application> <quote>Super-Server</quote></title> @@ -134,16 +140,15 @@ <para>The &man.inetd.8; daemon is sometimes referred to as the <quote>Internet Super-Server</quote> because it manages - connections for many services. When a connection is - received by <application>inetd</application>, it determines - which program the connection is destined for, spawns the - particular process and delegates the socket to it (the program - is invoked with the service socket as its standard input, - output and error descriptors). Running - <application>inetd</application> for servers that are not - heavily used can reduce the overall system load, when compared - to running each daemon individually in stand-alone - mode.</para> + connections for many services. When a connection is received + by <application>inetd</application>, it determines which + program the connection is destined for, spawns the particular + process and delegates the socket to it (the program is invoked + with the service socket as its standard input, output and + error descriptors). Running <application>inetd</application> + for servers that are not heavily used can reduce the overall + system load, when compared to running each daemon individually + in stand-alone mode.</para> <para>Primarily, <application>inetd</application> is used to spawn other daemons, but several trivial protocols are handled @@ -151,7 +156,7 @@ <application>auth</application>, and <application>daytime</application>.</para> - <para>This section will cover the basics in configuring + <para>This section covers the basics in configuring <application>inetd</application> through its command-line options and its configuration file, <filename>/etc/inetd.conf</filename>.</para> @@ -186,7 +191,7 @@ <para>Like most server daemons, <application>inetd</application> has a number of options that it can be passed in order to - modify its behaviour. See the &man.inetd.8; manual page for + modify its behaviour. Refer to &man.inetd.8; for the full list of options.</para> <para>Options can be passed to <application>inetd</application> @@ -195,15 +200,15 @@ <literal>inetd_flags</literal> is set to <literal>-wW -C 60</literal>, which turns on TCP wrapping for <application>inetd</application>'s services, and prevents any - single IP address from requesting any service more than 60 - times in any given minute.</para> + single <acronym>IP</acronym> address from requesting any + service more than 60 times in any given minute.</para> <para>Although we mention rate-limiting options below, novice users may be pleased to note that these parameters usually do not need to be modified. These options may be useful if an excessive amount of connections are being established. - A full list of options can be found in the - &man.inetd.8; manual.</para> + A full list of options can be found in + &man.inetd.8;.</para> <variablelist> <varlistentry> @@ -222,9 +227,10 @@ <listitem> <para>Specify the default maximum number of times a - service can be invoked from a single IP address in one - minute; the default is unlimited. May be overridden on - a per-service basis with the + service can be invoked from a single + <acronym>IP</acronym> address in one minute; the default + is unlimited. May be overridden on a per-service basis + with the <option>max-connections-per-ip-per-minute</option> parameter.</para> </listitem> @@ -245,9 +251,9 @@ <listitem> <para>Specify the maximum number of times a service can be - invoked from a single IP address at any one time; the - default is unlimited. May be overridden on a - per-service basis with the + invoked from a single <acronym>IP</acronym> address at + any one time; the default is unlimited. May be + overridden on a per-service basis with the <option>max-child-per-ip</option> parameter.</para> </listitem> </varlistentry> @@ -259,7 +265,7 @@ <title><filename>inetd.conf</filename></title> <para>Configuration of <application>inetd</application> is - done via the file <filename>/etc/inetd.conf</filename>.</para> + done by editing <filename>/etc/inetd.conf</filename>.</para> <para>When a modification is made to <filename>/etc/inetd.conf</filename>, @@ -342,7 +348,7 @@ server-program-arguments</programlisting> <row> <entry>udp, udp4</entry> - <entry>UDP IPv4</entry> + <entry><acronym>UDP</acronym> IPv4</entry> </row> <row> @@ -352,7 +358,7 @@ server-program-arguments</programlisting> <row> <entry>udp6</entry> - <entry>UDP IPv6</entry> + <entry><acronym>UDP</acronym> IPv6</entry> </row> <row> @@ -362,7 +368,7 @@ server-program-arguments</programlisting> <row> <entry>udp46</entry> - <entry>Both UDP IPv4 and v6</entry> + <entry>Both <acronym>UDP</acronym> IPv4 and v6</entry> </row> </tbody> </tgroup> @@ -398,14 +404,15 @@ server-program-arguments</programlisting> options which limit the maximum connections from a single place to a particular daemon can be enabled. <option>max-connections-per-ip-per-minute</option> - limits the number of connections from any particular IP - address per minutes, e.g., a value of ten would limit - any particular IP address connecting to a particular - service to ten attempts per minute. - <option>max-child-per-ip</option> limits the number of - children that can be started on behalf on any single IP - address at any moment. These options are useful to - prevent intentional or unintentional excessive resource + limits the number of connections from any particular + <acronym>IP</acronym> address per minutes, e.g., a value + of ten would limit any particular <acronym>IP</acronym> + address connecting to a particular service to ten + attempts per minute. <option>max-child-per-ip</option> + limits the number of children that can be started on + behalf on any single <acronym>IP</acronym> address at + any moment. These options are useful to prevent + intentional or unintentional excessive resource consumption and Denial of Service (DoS) attacks to a machine.</para> @@ -413,8 +420,7 @@ server-program-arguments</programlisting> <option>nowait</option> is mandatory. <option>max-child</option>, <option>max-connections-per-ip-per-minute</option> and - <option>max-child-per-ip</option> are - optional.</para> + <option>max-child-per-ip</option> are optional.</para> <para>A stream-type multi-threaded daemon without any <option>max-child</option>, @@ -426,8 +432,8 @@ server-program-arguments</programlisting> would read: <literal>nowait/10</literal>.</para> <para>The same setup with a limit of twenty connections - per IP address per minute and a maximum total limit of - ten child daemons would read: + per <acronym>IP</acronym> address per minute and a + maximum total limit of ten child daemons would read: <literal>nowait/10/20</literal>.</para> <para>These options are utilized by the default @@ -438,7 +444,7 @@ server-program-arguments</programlisting> <para>Finally, an example of this field with a maximum of 100 children in total, with a maximum of 5 for any one - IP address would read: + <acronym>IP</acronym> address would read: <literal>nowait/100/0/5</literal>.</para> </listitem> </varlistentry> @@ -511,8 +517,8 @@ server-program-arguments</programlisting> <literal>max-child-per-ip</literal> can be used to limit such attacks.</para> - <para>By default, TCP wrapping is turned on. Consult the - &man.hosts.access.5; manual page for more information on + <para>By default, TCP wrapping is turned on. Consult + &man.hosts.access.5; for more information on placing TCP restrictions on various <application>inetd</application> invoked daemons.</para> </sect2> @@ -532,12 +538,13 @@ server-program-arguments</programlisting> identity network services, and is configurable to a certain degree, whilst the others are simply on or off.</para> - <para>Consult the &man.inetd.8; manual page for more in-depth + <para>Consult &man.inetd.8; for more in-depth information.</para> </sect2> </sect1> <sect1 id="network-nfs"> + <!-- <sect1info> <authorgroup> <author> @@ -554,59 +561,59 @@ server-program-arguments</programlisting> </author> </authorgroup> </sect1info> + --> <title>Network File System (NFS)</title> <indexterm><primary>NFS</primary></indexterm> - <para>Among the many different file systems that FreeBSD supports - is the Network File System, also known as <acronym role="Network - File System">NFS</acronym>. <acronym role="Network File - System">NFS</acronym> allows a system to share directories and - files with others over a network. By using <acronym - role="Network File System">NFS</acronym>, users and programs can - access files on remote systems almost as if they were local - files.</para> - - <para>Some of the most notable benefits that - <acronym>NFS</acronym> can provide are:</para> + <para>&os; supports the Network File System + (<acronym>NFS</acronym>), which allows a server to share + directories and files with clients over a network. With + <acronym>NFS</acronym>, users and programs can access files on + remote systems as if they were stored locally.</para> + + <para>The most notable benefits that + <acronym>NFS</acronym> provides are:</para> <itemizedlist> <listitem> - <para>Local workstations use less disk space because commonly - used data can be stored on a single machine and still remain - accessible to others over the network.</para> + <para>Data that would otherwise be duplicated on each client + can be kept in a single location and accessed by clients + on the network.</para> </listitem> <listitem> - <para>There is no need for users to have separate home - directories on every network machine. Home directories - could be set up on the <acronym>NFS</acronym> server and - made available throughout the network.</para> + <para>User home directories can be stored in one location + and accessed by their owners over the network.</para> </listitem> <listitem> - <para>Storage devices such as floppy disks, CDROM drives, and - &iomegazip; drives can be used by other machines on the - network. This may reduce the number of removable media - drives throughout the network.</para> + <para>Administration of <acronym>NFS</acronym> exports is + also simplified. For example, there is only one file + system where security or backup policies must be + set.</para> </listitem> - </itemizedlist> - <sect2> - <title>How <acronym>NFS</acronym> Works</title> + <listitem> + <para>Removable media storage devices can be used by other + machines on the network. This reduces the number of devices + throughout the network and provides a centralized location + to manage their security.</para> + </listitem> + </itemizedlist> - <para><acronym>NFS</acronym> consists of at least two main - parts: a server and one or more clients. The client remotely - accesses the data that is stored on the server machine. In - order for this to function properly a few processes have to be - configured and running.</para> + <para><acronym>NFS</acronym> consists of at least two main + parts: a server and one or more clients. The client + remotely accesses the data that is stored on the server + machine. In order for this to function properly a few + processes have to be configured and running.</para> - <para>The server has to be running the following daemons:</para> - <indexterm> - <primary>NFS</primary> + <para>These daemons must be running on the server:</para> + <indexterm> + <primary>NFS</primary> <secondary>server</secondary> - </indexterm> - <indexterm> - <primary>file server</primary> + </indexterm> + <indexterm> + <primary>file server</primary> <secondary>UNIX clients</secondary> </indexterm> @@ -657,132 +664,124 @@ server-program-arguments</programlisting> </tgroup> </informaltable> - <para>The client can also run a daemon, known as - <application>nfsiod</application>. The - <application>nfsiod</application> daemon services the requests - from the <acronym>NFS</acronym> server. This is optional, and - improves performance, but is not required for normal and - correct operation. See the &man.nfsiod.8; manual page for - more information.</para> - </sect2> + <para>Running &man.nfsiod.8; can improve performance on the + client, but is not required.</para> - <sect2 id="network-configuring-nfs"> - <title>Configuring <acronym>NFS</acronym></title> + <sect2 id="network-configuring-nfs"> + <title>Configuring <acronym>NFS</acronym></title> - <indexterm> - <primary>NFS</primary> - <secondary>configuration</secondary> - </indexterm> - - <para><acronym>NFS</acronym> configuration is a relatively - straightforward process. The processes that need to be - running can all start at boot time with a few modifications - to <filename>/etc/rc.conf</filename>.</para> + <indexterm> + <primary>NFS</primary> + <secondary>configuration</secondary> + </indexterm> - <para>On the <acronym>NFS</acronym> server, make sure that the - following options are configured in the - <filename>/etc/rc.conf</filename> file:</para> + <para>Enabling the <acronym>NFS</acronym> server + is straightforward. The required processes + can be set to start at boot time by adding + these options to + <filename>/etc/rc.conf</filename>:</para> - <programlisting>rpcbind_enable="YES" + <programlisting>rpcbind_enable="YES" nfs_server_enable="YES" mountd_flags="-r"</programlisting> <para><application>mountd</application> runs automatically whenever the <acronym>NFS</acronym> server is enabled.</para> - <para>On the client, make sure this option is present in + <para>To enable the client, set this option in <filename>/etc/rc.conf</filename>:</para> <programlisting>nfs_client_enable="YES"</programlisting> - <para>The <filename>/etc/exports</filename> file specifies which - file systems <acronym>NFS</acronym> should export (sometimes - referred to as <quote>share</quote>). Each line in - <filename>/etc/exports</filename> specifies a file system to - be exported and which machines have access to that file - system. Along with what machines have access to that file - system, access options may also be specified. There are many - such options that can be used in this file but only a few will - be mentioned here. Other options are discussed in - the &man.exports.5; manual page.</para> - - <para>Here are a few example <filename>/etc/exports</filename> - entries:</para> + <para><filename>/etc/exports</filename> specifies which file + systems the <acronym>NFS</acronym> server will export. Each + line in <filename>/etc/exports</filename> specifies a file + system to be exported and which clients have access to that + file system, as well as any access options. There are many + such options that can be used in this file, but only a few + will be mentioned here. See &man.exports.5; for the full list + of options.</para> <indexterm> <primary>NFS</primary> <secondary>export examples</secondary> </indexterm> - <para>The following examples give an idea of how to export file - systems, although the settings may be different depending on - the environment and network configuration. For instance, to - export the <filename>/cdrom</filename> directory to three - example machines that have the same domain name as the server - (hence the lack of a domain name for each) or have entries in - the <filename>/etc/hosts</filename> file. The - <option>-ro</option> flag makes the exported file system - read-only. With this flag, the remote system will not be able - to write any changes to the exported file system.</para> - - <programlisting>/cdrom -ro host1 host2 host3</programlisting> - - <para>The following line exports <filename>/home</filename> to - three hosts by IP address. This is a useful setup on - a private network without a <acronym>DNS</acronym> server - configured. Optionally the <filename>/etc/hosts</filename> - file could be configured for internal hostnames; please review - &man.hosts.5; for more information. The - <option>-alldirs</option> flag allows the subdirectories to be - mount points. In other words, it will not mount the - subdirectories but permit the client to mount only the - directories that are required or needed.</para> + <para>These examples give an idea of how to export file systems. + Minor modifications may be required for the examples to work + on the reader's network.</para> + + <para>This example shows how to export the + <filename class="directory">/cdrom</filename> directory to + three clients called <replaceable>alpha</replaceable>, + <replaceable>bravo</replaceable>, and + <replaceable>charlie</replaceable>:</para> + + <programlisting>/cdrom -ro <replaceable>alpha</replaceable> <replaceable>bravo</replaceable> <replaceable>charlie</replaceable></programlisting> + + <para>The <literal>-ro</literal> flag makes the file systems + read-only, preventing clients from making any changes to + those exported file systems.</para> + + <para>The next example exports + <filename class="directory">/home</filename> to three clients + by <acronym>IP</acronym> address. This can be useful for + networks without <acronym>DNS</acronym>. Optionally, + <filename>/etc/hosts</filename> could be configured for + internal hostnames; please review &man.hosts.5; for more + information. The <literal>-alldirs</literal> flag allows + subdirectories to be mount points. In other words, it will + not mount the subdirectories but permit the client to mount + only the directories that are required or needed.</para> <programlisting>/home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4</programlisting> - <para>The following line exports <filename>/a</filename> so that - two clients from different domains may access the file system. - The <option>-maproot=root</option> flag allows the + <para>This next line exports + <filename class="directory">/a</filename> so that two clients + from different domains may access the file system. The + <option>-maproot=root</option> flag allows the <username>root</username> user on the remote system to write data on the exported file system as <username>root</username>. If the <literal>-maproot=root</literal> flag is not specified, - then even if a user has <username>root</username> access on - the remote system, he will not be able to modify files on - the exported file system.</para> + the client's <username>root</username> user will be mapped to + the server's <username>nobody</username> account and will be + subject to the access limitations defined for user, + <username>nobody</username>.</para> <programlisting>/a -maproot=root host.example.com box.example.org</programlisting> - <para>In order for a client to access an exported file system, - the client must have permission to do so. Make sure the - client is listed in <filename>/etc/exports</filename>.</para> + <para>For a client to have access to an exported file system, + the client must be listed in + <filename>/etc/exports</filename>.</para> - <para>In <filename>/etc/exports</filename>, each line represents - the export information for one file system to one host. A - remote host can only be specified once per file system, and - may only have one default entry. For example, assume that - <filename>/usr</filename> is a single file system. The - following <filename>/etc/exports</filename> would be - invalid:</para> + <para>In <filename>/etc/exports</filename>, each line defines + the export information for one file system to one or more + clients. A remote host can only be specified once per file + system. For example, assume that + <filename class="directory">/usr</filename> is a single file + system. This entry, in <filename>/etc/exports</filename>, + would be invalid:</para> <programlisting># Invalid when /usr is one file system /usr/src client /usr/ports client</programlisting> - <para>One file system, <filename>/usr</filename>, has two lines - specifying exports to the same host, <hostid>client</hostid>. - The correct format for this situation is:</para> + <para>The <filename class="directory">/usr</filename> file + system has two lines specifying exports to the same host, + <hostid>client</hostid>. The correct format for this + situation is:</para> <programlisting>/usr/src /usr/ports client</programlisting> - <para>The properties of one file system exported to a given host - must all occur on one line. Lines without a client specified - are treated as a single host. This limits how file systems - may be exported; however, for most environments, this is not - an issue.</para> + <para>The exported file system, its properties, and allowed + hosts must occur on a single line. If no clients are listed, + then any client on the network may mount the exported file + system.</para> <para>The following is an example of a valid export list, where - <filename>/usr</filename> and <filename>/exports</filename> - are local file systems:</para> + <filename class="directory">/usr</filename> and + <filename class="directory">/exports</filename> are local + file systems:</para> <programlisting># Export src and ports to client01 and client02, but only # client01 has root privileges on it @@ -793,25 +792,20 @@ mountd_flags="-r"</programlisting> /exports -alldirs -maproot=root client01 client02 /exports/obj -ro</programlisting> - <para>The <application>mountd</application> daemon must be - forced to recheck the <filename>/etc/exports</filename> file - whenever it has been modified, so the changes can take effect. - This can be accomplished either by sending a HUP signal to the - running daemon:</para> - - <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen> - - <para>or by invoking the <command>mountd</command> &man.rc.8; - script with the appropriate parameter:</para> + <para>The <application>mountd</application> daemon reads + <filename>/etc/exports</filename> when started. To make + <acronym>NFS</acronym> server changes take effect immediately, + force <application>mountd</application> to reread + <filename>/etc/exports</filename>:</para> - <screen>&prompt.root; <userinput>service mountd onereload</userinput></screen> + <screen>&prompt.root; <userinput>service mountd reload</userinput></screen> <para>Please refer to <xref linkend="configtuning-rcd"/> for more information about using rc scripts.</para> - <para>NFS services can now be started by running the following - command, on the <acronym>NFS</acronym> server, as - <username>root</username>:</para> + <para>On a new server being configured with + <acronym>NFS</acronym> services, the server can be started by + running this command as <username>root</username>:</para> <screen>&prompt.root; <userinput>service nfsd start</userinput></screen> @@ -819,12 +813,13 @@ mountd_flags="-r"</programlisting> <screen>&prompt.root; <userinput>service nfsclient restart</userinput></screen> - <para>Now everything should be ready to actually mount a remote - file system. In these examples the server's name will be - <hostid>server</hostid> and the client's name will be + <para>The client now has everything it needs to mount a remote + file system. In these examples, the server's name is + <hostid>server</hostid> and the client's name is <hostid>client</hostid>. For testing or to temporarily mount - a remote file system execute a command like this as - <username>root</username> on the client:</para> + a remote file system, execute <application>mount</application> + as <username>root</username> on + <hostid>client</hostid>:</para> <indexterm> <primary>NFS</primary> @@ -832,20 +827,21 @@ mountd_flags="-r"</programlisting> </indexterm> <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen> - <para>This will mount the <filename>/home</filename> directory - on the server at <filename>/mnt</filename> on the client. If - everything is set up correctly, the server's files should be - visible and available in the <filename>/mnt</filename> - directory.</para> + <para>This mounts the <hostid>server</hostid>: + <filename class="directory">/home</filename> file system to + the <hostid>client</hostid>: + <filename class="directory">/mnt</filename> mount point. The + files and directories in the <hostid>server</hostid> + <filename class="directory">/home</filename> file system will + now be available on <hostid>client</hostid>, in the + <filename class="directory">/mnt</filename> directory.</para> - <para>To permanently mount a remote file system each time the - computer boots, add the file system to the - <filename>/etc/fstab</filename> file. Here is an - example:</para> + <para>To mount a remote file system each time the client + boots, add it to <filename>/etc/fstab</filename>:</para> <programlisting>server:/home /mnt nfs rw 0 0</programlisting> - <para>The &man.fstab.5; manual page lists all the available + <para>Refer to &man.fstab.5; for a description of all available options.</para> </sect2> @@ -855,24 +851,27 @@ mountd_flags="-r"</programlisting> <para>Some applications (e.g., <application>mutt</application>) require file locking to operate correctly. In the case of <acronym>NFS</acronym>, <application>rpc.lockd</application> - can be used for file locking. To enable it, add the following - to the <filename>/etc/rc.conf</filename> file on both client - and server (it is assumed that the <acronym>NFS</acronym> - client and server are configured already):</para> + can be used for file locking. To enable it, add this line to + <filename>/etc/rc.conf</filename> on both client + and server:</para> <programlisting>rpc_lockd_enable="YES" rpc_statd_enable="YES"</programlisting> - <para>Start the application by using:</para> + <para>Please note that this assumes that both + <acronym>NFS</acronym> client and server are already + configured.</para> + + <para>Start the application, as <username>root</username>, + with:</para> <screen>&prompt.root; <userinput>service lockd start</userinput> &prompt.root; <userinput>service statd start</userinput></screen> - <para>If real locking between the <acronym>NFS</acronym> clients - and <acronym>NFS</acronym> server is not required, it is - possible to let the <acronym>NFS</acronym> client do locking + <para>If locking is not required on the server, the + <acronym>NFS</acronym> client can be configured to lock locally by passing <option>-L</option> to &man.mount.nfs.8;. - Refer to the &man.mount.nfs.8; manual page for further + Refer to &man.mount.nfs.8; for further details.</para> </sect2> @@ -880,7 +879,7 @@ rpc_statd_enable="YES"</programlisting> <title>Practical Uses</title> <para><acronym>NFS</acronym> has many practical uses. Some of - the more common ones are listed below:</para> + the more common uses:</para> <indexterm> <primary>NFS</primary> @@ -888,30 +887,32 @@ rpc_statd_enable="YES"</programlisting> </indexterm> <itemizedlist> <listitem> - <para>Set several machines to share a CDROM or other media - among them. This is cheaper and often a more convenient - method to install software on multiple machines.</para> + <para>Share a <acronym>CD-ROM</acronym> or other media with + any number of clients. It is often more convenient to + install software on multiple machines from a single + location.</para> </listitem> <listitem> - <para>On large networks, it might be more convenient to - configure a central <acronym>NFS</acronym> server in which - to store all the user home directories. These home - directories can then be exported to the network so that - users would always have the same home directory, - regardless of which workstation they log in to.</para> + <para>On large networks, it is often more convenient to + configure a central <acronym>NFS</acronym> server on which + all user home directories are stored. Users can log into + a client anywhere on the network and have access to their + home directories.</para> </listitem> <listitem> - <para>Several machines could have a common - <filename>/usr/ports/distfiles</filename> directory. This - allows for quick access to the source files without - downloading them on each machine.</para> + <para>Several clients may need access to the <filename + class="directory">/usr/ports/distfiles</filename> + directory. Sharing that directory allows for quick access + to the source files without having to download them to + each client.</para> </listitem> </itemizedlist> </sect2> <sect2 id="network-amd"> + <!-- <sect2info> <authorgroup> <author> @@ -928,6 +929,7 @@ rpc_statd_enable="YES"</programlisting> </author> </authorgroup> </sect2info> + --> <title>Automatic Mounts with <application>amd</application></title> @@ -940,34 +942,37 @@ rpc_statd_enable="YES"</programlisting> mounts a remote file system whenever a file or directory within that file system is accessed. Filesystems that are inactive for a period of time will also be automatically - unmounted by <application>amd</application>. Using - <application>amd</application> provides a simple alternative - to permanent mounts, as permanent mounts are usually listed in - <filename>/etc/fstab</filename>.</para> + unmounted by <application>amd</application>. + <application>amd</application> provides an alternative to + modifying <filename>/etc/fstab</filename> to list every + client.</para> <para><application>amd</application> operates by attaching - itself as an NFS server to the <filename>/host</filename> and - <filename>/net</filename> directories. When a file is - accessed within one of these directories, + itself as an NFS server to the + <filename class="directory">/host</filename> and + <filename class="directory">/net</filename> directories. When + a file is accessed within one of these directories, <application>amd</application> looks up the corresponding - remote mount and automatically mounts it. - <filename>/net</filename> is used to mount an exported file - system from an IP address, while <filename>/host</filename> is - used to mount an export from a remote hostname.</para> - - <para>An access to a file within - <filename>/host/foobar/usr</filename> would tell - <application>amd</application> to attempt to mount the - <filename>/usr</filename> export on the host + remote mount and automatically mounts it. <filename + class="directory">/net</filename> is used to mount an + exported file system from an <acronym>IP</acronym> address, + while <filename class="directory">/host</filename> is used to + mount an export from a remote hostname.</para> + + <para>For instance, an attempt to access a file within + <filename class="directory">/host/foobar/usr</filename> would + tell <application>amd</application> to mount the + <filename class="directory">/usr</filename> export on the host <hostid>foobar</hostid>.</para> <example> <title>Mounting an Export with <application>amd</application></title> - <para>The <command>showmount</command> command shows the - available mounts on a remote host. For example, to view the - mounts of a host named <hostid>foobar</hostid>:</para> + <para><command>showmount -e</command> shows the + exported file systems that can be mounted from + the <acronym>NFS</acronym> server, + <hostid>foobar</hostid>:</para> <screen>&prompt.user; <userinput>showmount -e foobar</userinput> Exports list on foobar: @@ -976,158 +981,42 @@ Exports list on foobar: &prompt.user; <userinput>cd /host/foobar/usr</userinput></screen> </example> - <para>As seen in the example, the <command>showmount</command> - shows <filename>/usr</filename> as an export. When changing - directories to <filename>/host/foobar/usr</filename>, - <application>amd</application> attempts to resolve the - hostname <hostid>foobar</hostid> and automatically mount the - desired export.</para> + <para>The output from <command>showmount</command> shows + <filename class="directory">/usr</filename> as an export. + When changing directories to + <filename class="directory">/host/foobar/usr</filename>, + <application>amd</application> intercepts the request and + attempts to resolve the hostname <hostid>foobar</hostid>. If + successful, <application>amd</application> automatically + mounts the desired export.</para> - <para><application>amd</application> can be started by the - startup scripts by placing the following lines in - <filename>/etc/rc.conf</filename>:</para> + <para><application>amd</application> is enabled by placing + this line in <filename>/etc/rc.conf</filename>:</para> <programlisting>amd_enable="YES"</programlisting> - <para>Additionally, custom flags can be passed to + <para>It can then be started using the &os; &man.rc.8; scripts + or by using the &man.service.8; command.</para> + + <para>Custom flags can be passed to <application>amd</application> from the - <varname>amd_flags</varname> option. By default, - <varname>amd_flags</varname> is set to:</para> + <varname>amd_flags</varname> environment variable. By + default, <varname>amd_flags</varname> is set to:</para> <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting> - <para>The <filename>/etc/amd.map</filename> file defines the - default options that exports are mounted with. The - <filename>/etc/amd.conf</filename> file defines some of the - more advanced features of - <application>amd</application>.</para> + <para><filename>/etc/amd.map</filename> defines the default + options with which exports are mounted. + <filename>/etc/amd.conf</filename> defines some of the more + advanced features of <application>amd</application>.</para> - <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages + <para>Consult &man.amd.8; and &man.amd.conf.5; for more information.</para> </sect2> - - <sect2 id="network-nfs-integration"> - <sect2info> - <authorgroup> - <author> - <firstname>John</firstname> - <surname>Lind</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - </sect2info> - <title>Problems Integrating with Other Systems</title> - - <para>Certain Ethernet adapters for ISA PC systems have - limitations which can lead to serious network problems, - particularly with NFS. This difficulty is not specific to - FreeBSD, but FreeBSD systems are affected by it.</para> - - <para>The problem nearly always occurs when (FreeBSD) PC systems - are networked with high-performance workstations, such as - those made by Silicon Graphics, Inc., and Sun Microsystems, - Inc. The NFS mount will work fine, and some operations may - succeed, but suddenly the server will seem to become - unresponsive to the client, even though requests to and from - other systems continue to be processed. This happens to the - client system, whether the client is the FreeBSD system or the - workstation. On many systems, there is no way to shut down - the client gracefully once this problem has manifested itself. - The only solution is often to reset the client, because the - NFS situation cannot be resolved.</para> - - <para>Though the <quote>correct</quote> solution is to get a - higher performance and capacity Ethernet adapter for the - FreeBSD system, there is a simple workaround that will allow - satisfactory operation. If the FreeBSD system is the - <emphasis>server</emphasis>, include the option - <option>-w=1024</option> on the mount from the client. If the - FreeBSD system is the <emphasis>client</emphasis>, then mount - the NFS file system with the option <option>-r=1024</option>. - These options may be specified using the fourth field of the - <filename>fstab</filename> entry on the client for automatic - mounts, or by using the <option>-o</option> parameter of the - &man.mount.8; command for manual mounts.</para> - - <para>It should be noted that there is a different problem, - sometimes mistaken for this one, when the NFS servers and - clients are on different networks. If that is the case, make - <emphasis>certain</emphasis> that the routers are routing the - necessary <acronym>UDP</acronym> information.</para> - - <para>In the following examples, <hostid>fastws</hostid> is the - host (interface) name of a high-performance workstation, and - <hostid>freebox</hostid> is the host (interface) name of a - FreeBSD system with a lower-performance Ethernet adapter. - Also, <filename>/sharedfs</filename> will be the exported NFS - file system (see &man.exports.5;), and - <filename>/project</filename> will be the mount point on the - client for the exported file system. In all cases, note that - additional options, such as <option>hard</option> or - <option>soft</option> and <option>bg</option> may be desirable - in the application.</para> - - <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) - as the client in <filename>/etc/fstab</filename> on - <hostid>freebox</hostid>:</para> - - <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting> - - <para>As a manual mount command on - <hostid>freebox</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen> - - <para>Examples for the FreeBSD system as the server in - <filename>/etc/fstab</filename> on - <hostid>fastws</hostid>:</para> - - <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting> - - <para>As a manual mount command on - <hostid>fastws</hostid>:</para> - - <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen> - - <para>Nearly any 16-bit Ethernet adapter will allow operation - without the above restrictions on the read or write - size.</para> - - <para>For anyone who cares, here is what happens when the - failure occurs, which also explains why it is unrecoverable. - NFS typically works with a <quote>block</quote> size of - 8 K (though it may do fragments of smaller sizes). Since - the maximum Ethernet packet is around 1500 bytes, the NFS - <quote>block</quote> gets split into multiple Ethernet - packets, even though it is still a single unit to the - upper-level code, and must be received, assembled, and - <emphasis>acknowledged</emphasis> as a unit. The - high-performance workstations can pump out the packets which - comprise the NFS unit one right after the other, just as close - together as the standard allows. On the smaller, lower - capacity cards, the later packets overrun the earlier packets - of the same unit before they can be transferred to the host - and the unit as a whole cannot be reconstructed or - acknowledged. As a result, the workstation will time out and - try again, but it will try again with the entire 8 K - unit, and the process will be repeated, ad infinitum.</para> - - <para>By keeping the unit size below the Ethernet packet size - limitation, we ensure that any complete Ethernet packet - received can be acknowledged individually, avoiding the - deadlock situation.</para> - - <para>Overruns may still occur when a high-performance - workstations is slamming data out to a PC system, but with the - better cards, such overruns are not guaranteed on NFS - <quote>units</quote>. When an overrun occurs, the units - affected will be retransmitted, and there will be a fair - chance that they will be received, assembled, and - acknowledged.</para> - </sect2> </sect1> <sect1 id="network-nis"> + <!-- <sect1info> <authorgroup> <author> @@ -1148,10 +1037,9 @@ Exports list on foobar: </author> </authorgroup> </sect1info> - <title>Network Information System (NIS/YP)</title> - - <sect2> - <title>What Is It?</title> + --> + <title>Network Information System + (<acronym>NIS</acronym>)</title> <indexterm><primary>NIS</primary></indexterm> <indexterm><primary>Solaris</primary></indexterm> @@ -1160,52 +1048,42 @@ Exports list on foobar: <indexterm><primary>Linux</primary></indexterm> <indexterm><primary>NetBSD</primary></indexterm> <indexterm><primary>OpenBSD</primary></indexterm> - - <para><acronym role="Network Information System">NIS</acronym>, - which stands for Network Information Services, was developed - by Sun Microsystems to centralize administration of &unix; - (originally &sunos;) systems. It has now essentially become - an industry standard; all major &unix; like systems - (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD, - etc) support <acronym - role="Network Information System">NIS</acronym>.</para> - <indexterm> <primary>yellow pages</primary> <see>NIS</see> </indexterm> - <para><acronym role="Network Information System">NIS</acronym> - was formerly known as Yellow Pages, but because of trademark - issues, Sun changed the name. The old term (and yp) is still - often seen and used.</para> + <para>Network Information System (<acronym>NIS</acronym>) + is designed to centralize administration of &unix;-like + systems such as &solaris;, HP-UX, &aix;, Linux, NetBSD, + OpenBSD, and &os;. <acronym>NIS</acronym> was originally + known as Yellow Pages but the name was changed due to + trademark issues. This is the reason why + <acronym>NIS</acronym> commands begin with + <literal>yp</literal>.</para> <indexterm> <primary>NIS</primary> <secondary>domains</secondary> </indexterm> - <para>It is a RPC-based client/server system that allows a group - of machines within an NIS domain to share a common set of - configuration files. This permits a system administrator to - set up NIS client systems with only minimal configuration data - and add, remove or modify configuration data from a single - location.</para> + <para><acronym>NIS</acronym> is a Remote Procedure Call + (<acronym>RPC</acronym>)-based client/server system that + allows a group of machines within an <acronym>NIS</acronym> + domain to share a common set of configuration files. This + permits a system administrator to set up + <acronym>NIS</acronym> client systems with only minimal + configuration data and to add, remove, or modify configuration + data from a single location.</para> - <indexterm><primary>Windows NT</primary></indexterm> - - <para>It is similar to the &windowsnt; domain system; although - the internal implementation of the two are not at all similar, - the basic functionality can be compared.</para> - </sect2> + <para>&os; uses version 2 of the <acronym>NIS</acronym> + protocol.</para> <sect2> - <title><acronym>NIS</acronym>Terms and Processes</title> + <title><acronym>NIS</acronym> Terms and Processes</title> - <para>There are several terms and important user processes that - will be explained while attempting to implement NIS on - FreeBSD, regardless if the system is a NIS server or a NIS - client:</para> + <para>Table 28.1 summarizes the terms and important processes + used by <acronym>NIS</acronym>:</para> <indexterm> <primary><application>rpcbind</application></primary> @@ -1214,7 +1092,9 @@ Exports list on foobar: <primary><application>portmap</application></primary> </indexterm> - <informaltable frame="none" pgwide="1"> + <table frame="none" pgwide="1"> + <title><acronym>NIS</acronym> Terminology</title> + <tgroup cols="2"> <colspec colwidth="1*"/> <colspec colwidth="3*"/> @@ -1228,171 +1108,152 @@ Exports list on foobar: <tbody> <row> - <entry>NIS domainname</entry> + <entry><acronym>NIS</acronym> domain name</entry> - <entry>An NIS master server and all of its clients - (including its slave servers) have a NIS domainname. - Similar to an &windowsnt; domain name, the NIS - domainname does not have anything to do with + <entry><acronym>NIS</acronym> servers and clients share + an <acronym>NIS</acronym> domain name. Typically, + this name does not have anything to do with <acronym>DNS</acronym>.</entry> </row> <row> - <entry><application>rpcbind</application></entry> + <entry>&man.rpcbind.8;</entry> - <entry>Must be running in order to enable - <acronym>RPC</acronym> (Remote Procedure Call, a - network protocol used by NIS). If - <application>rpcbind</application> is not running, it - will be impossible to run an NIS server, or to act as - an NIS client.</entry> + <entry>This service enables <acronym>RPC</acronym> and + must be running in order to run an + <acronym>NIS</acronym> server or act as an + <acronym>NIS</acronym> client.</entry> </row> <row> - <entry><application>ypbind</application></entry> - - <entry><quote>Binds</quote> an NIS client to its NIS - server. It will take the NIS domainname from the - system, and using <acronym>RPC</acronym>, connect to - the server. <application>ypbind</application> is the - core of client-server communication in an NIS - environment; if <application>ypbind</application> dies - on a client machine, it will not be able to access the - NIS server.</entry> + <entry>&man.ypbind.8;</entry> + <entry>This service binds an <acronym>NIS</acronym> + client to its <acronym>NIS</acronym> server. It will + take the <acronym>NIS</acronym> domain name and use + <acronym>RPC</acronym> to connect to the server. It + is the core of client/server communication in an + <acronym>NIS</acronym> environment. If this service + is not running on a client machine, it will not be + able to access the <acronym>NIS</acronym> + server.</entry> </row> <row> - <entry><application>ypserv</application></entry> - <entry>Should only be running on NIS servers; this is - the NIS server process itself. If &man.ypserv.8; - dies, then the server will no longer be able to - respond to NIS requests (hopefully, there is a slave - server to take over for it). There are some - implementations of NIS (but not the FreeBSD one), that - do not try to reconnect to another server if the - server it used before dies. Often, the only thing - that helps in this case is to restart the server - process (or even the whole server) or the - <application>ypbind</application> process on the - client.</entry> + <entry>&man.ypserv.8;</entry> + <entry>This is the process for the + <acronym>NIS</acronym> server. If this service stops + running, the server will no longer be able to respond + to <acronym>NIS</acronym> requests so hopefully, there + is a slave server to take over. Some non-&os; clients + will not try to reconnect using a slave server and the + <application>ypbind</application> process may need to + be restarted on these + clients.</entry> </row> <row> - <entry><application>rpc.yppasswdd</application></entry> - <entry>Another process that should only be running on - NIS master servers; this is a daemon that will allow - NIS clients to change their NIS passwords. If this - daemon is not running, users will have to login to the - NIS master server and change their passwords - there.</entry> + <entry>&man.rpc.yppasswdd.8;</entry> + <entry>This process only runs on + <acronym>NIS</acronym> master servers. This daemon + allows <acronym>NIS</acronym> clients to change their + <acronym>NIS</acronym> passwords. If this daemon is + not running, users will have to login to the + <acronym>NIS</acronym> master server and change their + passwords there.</entry> </row> </tbody> </tgroup> - </informaltable> + </table> <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run on the master --> </sect2> <sect2> - <title>How Does It Work?</title> - - <para>There are three types of hosts in an NIS environment: - master servers, slave servers, and clients. Servers act as a - central repository for host configuration information. Master - servers hold the authoritative copy of this information, while - slave servers mirror this information for redundancy. Clients - rely on the servers to provide this information to - them.</para> - - <para>Information in many files can be shared in this manner. - The <filename>master.passwd</filename>, - <filename>group</filename>, and <filename>hosts</filename> - files are commonly shared via NIS. Whenever a process on a - client needs information that would normally be found in these - files locally, it makes a query to the NIS server that it is - bound to instead.</para> + <title>Machine Types</title> - <sect3> - <title>Machine Types</title> + <indexterm><primary>NIS</primary> + <secondary>master server</secondary> + </indexterm> + <indexterm><primary>NIS</primary> + <secondary>slave server</secondary> + </indexterm> + <indexterm><primary>NIS</primary> + <secondary>client</secondary> + </indexterm> - <itemizedlist> - <listitem> - <para>A <emphasis>NIS master server</emphasis><indexterm> - <primary>NIS</primary> - <secondary>master server</secondary> - </indexterm>. - This server, analogous to a &windowsnt; primary domain - controller, maintains the files used by all of the NIS - clients. The <filename>passwd</filename>, - <filename>group</filename>, and other various files used - by the NIS clients live on the master server.</para> - - <note> - <para>It is possible for one machine to be an NIS master - server for more than one NIS domain. However, this - will not be covered in this introduction, which - assumes a relatively small-scale NIS - environment.</para> - </note> - </listitem> + <para>There are three types of hosts in an + <acronym>NIS</acronym> environment:</para> - <listitem> - <para><emphasis>NIS slave servers</emphasis><indexterm> - <primary>NIS</primary> - <secondary>slave server</secondary> - </indexterm>. Similar to the &windowsnt; backup domain - controllers, NIS slave servers maintain copies of the - NIS master's data files. NIS slave servers provide the - redundancy, which is needed in important environments. - They also help to balance the load of the master server: - NIS Clients always attach to the NIS server whose - response they get first, and this includes - slave-server-replies.</para> - </listitem> + <itemizedlist> + <listitem> + <para><acronym>NIS</acronym> master server</para> + + <para>This server acts as a central repository for host + configuration information and maintains the + authoritative copy of the files used by all of the + <acronym>NIS</acronym> clients. The + <filename>passwd</filename>, <filename>group</filename>, + and other various files used by <acronym>NIS</acronym> + clients are stored on the master server. While it is + possible for one machine to be an <acronym>NIS</acronym> + master server for more than one <acronym>NIS</acronym> + domain, this type of configuration will not be covered in + this chapter as it assumes a relatively small-scale + <acronym>NIS</acronym> environment.</para> + </listitem> - <listitem> - <para><emphasis>NIS clients</emphasis><indexterm> - <primary>NIS</primary> - <secondary>client</secondary> - </indexterm>. - NIS clients, like most &windowsnt; workstations, - authenticate against the NIS server (or the &windowsnt; - domain controller in the &windowsnt; workstations case) - to log on.</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> + <listitem> + <para><acronym>NIS</acronym> slave servers</para> + + <para><acronym>NIS</acronym> slave servers maintain copies + of the <acronym>NIS</acronym> master's data files in + order to provide redundancy. Slave servers also help to + balance the load of the master server as + <acronym>NIS</acronym> clients always attach to the + <acronym>NIS</acronym> server which responds + first.</para> + </listitem> - <sect2> - <title>Using NIS/YP</title> + <listitem> + <para><acronym>NIS</acronym> clients</para> - <para>This section will deal with setting up a sample NIS - environment.</para> + <para><acronym>NIS</acronym> clients authenticate + against the <acronym>NIS</acronym> server during log + on.</para> + </listitem> + </itemizedlist> - <sect3> - <title>Planning</title> + <para>Information in many files can be shared using + <acronym>NIS</acronym>. The + <filename>master.passwd</filename>, + <filename>group</filename>, and <filename>hosts</filename> + files are commonly shared via <acronym>NIS</acronym>. + Whenever a process on a client needs information that would + normally be found in these files locally, it makes a query to + the <acronym>NIS</acronym> server that it is bound to + instead.</para> + </sect2> - <para>Let us assume that an administrator of a small - university lab, which consists of 15 FreeBSD machines, - currently has no centralized point of administration. Each + <sect2> + <title>Planning Considerations</title> + + <para>This section describes a sample <acronym>NIS</acronym> + environment which consists of 15 &os; machines with + no centralized point of administration. Each machine has its own <filename>/etc/passwd</filename> and <filename>/etc/master.passwd</filename>. These files are kept in sync with each other only through manual - intervention; currently, a user is added to the lab, the - process must be ran on all 15 machines. The lab would - clearly benefit from the addition of two - <acronym>NIS</acronym> servers.</para> + intervention. Currently, when a user is added to the lab, + the process must be repeated on all 15 machines.</para> - <para>Therefore, the configuration of the lab now looks - something like:</para> + <para>The configuration of the lab will be as follows:</para> <informaltable frame="none" pgwide="1"> <tgroup cols="3"> <thead> <row> <entry>Machine name</entry> - <entry>IP address</entry> + <entry><acronym>IP</acronym> address</entry> <entry>Machine role</entry> </row> </thead> @@ -1401,13 +1262,13 @@ Exports list on foobar: <row> <entry><hostid>ellington</hostid></entry> <entry><hostid role="ipaddr">10.0.0.2</hostid></entry> - <entry>NIS master</entry> + <entry><acronym>NIS</acronym> master</entry> </row> <row> <entry><hostid>coltrane</hostid></entry> <entry><hostid role="ipaddr">10.0.0.3</hostid></entry> - <entry>NIS slave</entry> + <entry><acronym>NIS</acronym> slave</entry> </row> <row> @@ -1432,199 +1293,189 @@ Exports list on foobar: </tgroup> </informaltable> - <para>If this is the first time a <acronym>NIS</acronym> + <para>If this is the first time an <acronym>NIS</acronym> scheme is being developed, it should be thoroughly planned ahead of time. Regardless of network size, several decisions need to be made as part of the planning process.</para> - <sect4> - <title>Choosing a NIS Domain Name</title> + <sect3> + <title>Choosing a <acronym>NIS</acronym> Domain Name</title> <indexterm> <primary>NIS</primary> - <secondary>domainname</secondary> + <secondary>domain name</secondary> </indexterm> - <para>This might not be the normal <quote>domainname</quote> - for the network. It is more accurately called the - <quote>NIS domainname</quote>. When a client broadcasts - its requests for info, it includes the name of the NIS - domain that it is part of. This is how multiple servers - on one network can tell which server should answer which - request. Think of the NIS domainname as the name for a - group of hosts that are related in some way.</para> - - <para>Some organizations choose to use their Internet - domainname for their NIS domainname. This is not - recommended as it can cause confusion when trying to debug - network problems. The NIS domainname should be unique - within the network and it is helpful if it describes the - group of machines it represents. For example, the Art - department at Acme Inc. might be in the - <quote>acme-art</quote> NIS domain. For this example, - assume the chosen name will be - <literal>test-domain</literal>.</para> - - <indexterm><primary>SunOS</primary></indexterm> - <para>However, some operating systems (notably &sunos;) use - their NIS domain name as their Internet domain name. If - one or more machines on the network have this - restriction, it <emphasis>must</emphasis> be used as the - Internet domain name for the NIS domain name.</para> - </sect4> - - <sect4> + <para>When a client broadcasts its requests for info, it + includes the name of the <acronym>NIS</acronym> domain + that it is part of. This is how multiple servers on one + network can tell which server should answer which request. + Think of the <acronym>NIS</acronym> domain name as the + name for a group of hosts.</para> + + <para>Some organizations choose to use their Internet domain + name for their <acronym>NIS</acronym> domain name. This + is not recommended as it can cause confusion when trying + to debug network problems. The <acronym>NIS</acronym> + domain name should be unique within the network and it is + helpful if it describes the group of machines it + represents. For example, the Art department at Acme Inc. + might be in the <quote>acme-art</quote> + <acronym>NIS</acronym> domain. This example will use the + domain name <literal>test-domain</literal>.</para> + + <para>However, some non-&os; operating systems require the + <acronym>NIS</acronym> domain name to be the same as the + Internet domain name. If one or more machines on the + network have this restriction, the Internet domain name + <emphasis>must</emphasis> be used as the + <acronym>NIS</acronym> domain name.</para> + </sect3> + + <sect3> <title>Physical Server Requirements</title> <para>There are several things to keep in mind when choosing - a machine to use as a NIS server. One of the unfortunate - things about NIS is the level of dependency the clients - have on the server. If a client cannot contact the server - for its NIS domain, very often the machine becomes - unusable. The lack of user and group information causes - most systems to temporarily freeze up. With this in mind - be sure to choose a machine that will not be prone to - being rebooted frequently, or one that might be used for - development. The NIS server should ideally be a stand - alone machine whose sole purpose in life is to be an NIS - server. If the network is not very heavily used, it is - acceptable to put the NIS server on a machine running - other services, however; if the NIS server becomes - unavailable, it will adversely affect - <emphasis>all</emphasis> NIS clients.</para> - </sect4> - </sect3> + a machine to use as a <acronym>NIS</acronym> server. + Since <acronym>NIS</acronym> clients depend upon the + availability of the server, choose a machine that is not + rebooted frequently. The <acronym>NIS</acronym> server + should ideally be a stand alone machine whose sole purpose + is to be an <acronym>NIS</acronym> server. If the network + is not heavily used, it is acceptable to put the + <acronym>NIS</acronym> server on a machine running other + services. However, if the <acronym>NIS</acronym> server + becomes unavailable, it will adversely affect all + <acronym>NIS</acronym> clients.</para> + </sect3> + </sect2> - <sect3> - <title>NIS Servers</title> + <sect2> + <title>Configuring the <acronym>NIS</acronym> Master + Server</title> - <para> The canonical copies of all NIS information are stored - on a single machine called the NIS master server. The - databases used to store the information are called NIS maps. - In FreeBSD, these maps are stored in + <para> The canonical copies of all <acronym>NIS</acronym> + files are stored on the master server. The databases used + to store the information are called <acronym>NIS</acronym> + maps. In &os;, these maps are stored in <filename>/var/yp/[domainname]</filename> where - <filename>[domainname]</filename> is the name of the NIS - domain being served. A single NIS server can support - several domains at once, therefore it is possible to have - several such directories, one for each supported domain. - Each domain will have its own independent set of - maps.</para> - - <para>NIS master and slave servers handle all NIS requests - with the <command>ypserv</command> daemon. - <command>ypserv</command> is responsible for receiving - incoming requests from NIS clients, translating the + <filename>[domainname]</filename> is the name of the + <acronym>NIS</acronym> domain. Since multiple domains are + supported, it is possible to have several directories, one + for each domain. Each domain will have its own independent + set of maps.</para> + + <para><acronym>NIS</acronym> master and slave servers handle + all <acronym>NIS</acronym> requests through &man.ypserv.8;. + This daemon is responsible for receiving incoming requests + from <acronym>NIS</acronym> clients, translating the requested domain and map name to a path to the corresponding - database file and transmitting data from the database back + database file, and transmitting data from the database back to the client.</para> - <sect4> - <title>Setting Up a NIS Master Server</title> - - <indexterm> - <primary>NIS</primary> - <secondary>server configuration</secondary> - </indexterm> - <para>Setting up a master NIS server can be relatively - straight forward, depending on environmental needs. &os; - comes with support for NIS out-of-the-box. It only needs - to be enabled by adding the following lines to - <filename>/etc/rc.conf</filename>:</para> - - <procedure> - <step> - <programlisting>nisdomainname="test-domain"</programlisting> - - <para>This line will set the NIS domainname to - <literal>test-domain</literal> - upon network setup (e.g., after reboot).</para> - </step> - - <step> - <programlisting>nis_server_enable="YES"</programlisting> - - <para>This will tell FreeBSD to start up the NIS server - processes when the networking is next brought - up.</para> - </step> - - <step> - <programlisting>nis_yppasswdd_enable="YES"</programlisting> - - <para>This will enable the - <command>rpc.yppasswdd</command> daemon which, as - mentioned above, will allow users to change their NIS - password from a client machine.</para> - </step> - </procedure> - - <note> - <para>Depending on the NIS setup, additional entries may - be required. See the <link - linkend="network-nis-server-is-client">section about - NIS servers that are also NIS clients</link>, below, for - details.</para> - </note> + <indexterm><primary>NIS</primary> + <secondary>server configuration</secondary> + </indexterm> + <para>Setting up a master <acronym>NIS</acronym> server can + be relatively straight forward, depending on environmental + needs. Since &os; provides built-in + <acronym>NIS</acronym> support, it only needs to be + enabled by adding the following lines to + <filename>/etc/rc.conf</filename>:</para> + + <procedure> + <step> + <programlisting>nisdomainname="test-domain"</programlisting> + + <para>This line sets the <acronym>NIS</acronym> domain + name to <literal>test-domain</literal>.</para> + </step> + + <step> + <programlisting>nis_server_enable="YES"</programlisting> + + <para>This automates the start up of the + <acronym>NIS</acronym> server processes when the + system boots.</para> + </step> + + <step> + <programlisting>nis_yppasswdd_enable="YES"</programlisting> + + <para>This enables the &man.rpc.yppasswdd.8; daemon so + that users can change their <acronym>NIS</acronym> + password from a client machine.</para> + </step> + </procedure> + + <para>Care must be taken in a multi-server domain where the + server machines are also <acronym>NIS</acronym> clients. It + is generally a good idea to force the servers to bind to + themselves rather than allowing them to broadcast bind + requests and possibly become bound to each other. Strange + failure modes can result if one server goes down and others + are dependent upon it. Eventually, all the clients will + time out and attempt to bind to other servers, but the delay + involved can be considerable and the failure mode is still + present since the servers might bind to each other all over + again.</para> + + <para>A server that is also a client can be forced to bind to + a particular server by adding these additional lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>nis_client_enable="YES" # run client stuff as well +nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting> - <para>After setting up the above entries, run the command - <command>/etc/netstart</command> as superuser. It will - set up everything, using the values defined in - <filename>/etc/rc.conf</filename>. As a last step, before - initializing the NIS maps, start the - <application>ypserv</application> daemon manually:</para> + <para>After saving the edits, type + <command>/etc/netstart</command> to restart the network + and apply the values defined in + <filename>/etc/rc.conf</filename>. Before initializing + the <acronym>NIS</acronym> maps, start + &man.ypserv.8;:</para> <screen>&prompt.root; <userinput>service ypserv start</userinput></screen> - </sect4> - <sect4> - <title>Initializing the NIS Maps</title> + <sect3> + <title>Initializing the <acronym>NIS</acronym> + Maps</title> <indexterm> <primary>NIS</primary> <secondary>maps</secondary> </indexterm> - <para>The <emphasis>NIS maps</emphasis> are database files, - that are kept in the <filename>/var/yp</filename> - directory. They are generated from configuration files in - the <filename>/etc</filename> directory of the NIS master, - with one exception: - <filename>/etc/master.passwd</filename>. This is for a - good reason, never propagate passwords for - <username>root</username> and other administrative - accounts to all the servers in the NIS domain. Therefore, - before the NIS maps are initialized, configure the + <para><acronym>NIS</acronym> maps + are generated from the configuration files in <filename + class="directory">/etc</filename> on the + <acronym>NIS</acronym> master, with one exception: + <filename>/etc/master.passwd</filename>. This is to + prevent the propagation of passwords to all the servers in + the <acronym>NIS</acronym> domain. Therefore, before the + <acronym>NIS</acronym> maps are initialized, configure the primary password files:</para> <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput> &prompt.root; <userinput>cd /var/yp</userinput> &prompt.root; <userinput>vi master.passwd</userinput></screen> - <para>It is advisable to remove all entries regarding system - accounts (<username>bin</username>, - <username>tty</username>, <username>kmem</username>, - <username>games</username>, etc), as well as any accounts - that do not need to be propagated to the NIS clients - (for example <username>root</username> and any other UID 0 - (superuser) accounts).</para> + <para>It is advisable to remove all entries for system + accounts as well as any user accounts that do not need to + be propagated to the <acronym>NIS</acronym> clients, such + as the <username>root</username> and any other + administrative accounts.</para> - <note><para>Ensure the + <note><para>Ensure that the <filename>/var/yp/master.passwd</filename> is neither - group or world readable (mode 600)! Use the - <command>chmod</command> command, as - appropriate.</para></note> - - <indexterm><primary>Tru64 UNIX</primary></indexterm> - - <para>When this task has been completed, it is time to - initialize the NIS maps. FreeBSD includes a script named - <command>ypinit</command> to do this (see its - manual page for more information). Note that this script - is available on most &unix; Operating Systems, but not on - all. On Digital UNIX/Compaq Tru64 UNIX it is called - <command>ypsetup</command>. Because we are generating - maps for an NIS master, we are going to pass the - <option>-m</option> option to <command>ypinit</command>. - To generate the NIS maps run:</para> + group or world readable by setting its permissions to + <literal>600</literal>.</para> + </note> + + <para>After completing this task, initialize the + <acronym>NIS</acronym> maps. &os; includes the + &man.ypinit.8; script to do this. When generating maps + for the master server, include + <option>-m</option> and specify the <acronym>NIS</acronym> + domain name:</para> <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput> Server Type: MASTER Domain: test-domain @@ -1650,39 +1501,61 @@ Is this correct? [y/n: y] <userinput>y</userinput> NIS Map update completed. ellington has been setup as an YP master server without any errors.</screen> - <para>At this point, <command>ypinit</command> should have - created <filename>/var/yp/Makefile</filename> from - <filename>/var/yp/Makefile.dist</filename>. - When created, this file assumes that the operating - environment is a single server NIS system with only &os; - machines. Since <literal>test-domain</literal> has - a slave server as well, edit - <filename>/var/yp/Makefile</filename> as well:</para> - - <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen> - - <para>You should comment out the line that says</para> - - <programlisting>NOPUSH = "True"</programlisting> + <para>This will create + <filename>/var/yp/Makefile</filename> from + <filename>/var/yp/Makefile.dist</filename>. By + default, this file assumes that the environment has a + single <acronym>NIS</acronym> server with only &os; + clients. Since <literal>test-domain</literal> has a + slave server, edit this line in + <filename>/var/yp/Makefile</filename> so that it begins + with a comment (<literal>#</literal>):</para> + + <programlisting>NOPUSH = "True"</programlisting> + </sect3> + + <sect3> + <title>Adding New Users</title> + + <para>Every time a new user is created, the user account + must be added to the master <acronym>NIS</acronym> + server and the <acronym>NIS</acronym> maps rebuilt. + Until this occurs, the new user will not be able to + login anywhere except on the <acronym>NIS</acronym> + master. For example, to add the new user + <username>jsmith</username> to the + <literal>test-domain</literal> domain, run these + commands on the master server:</para> + + <screen>&prompt.root; <userinput>pw useradd jsmith</userinput> +&prompt.root; <userinput>cd /var/yp</userinput> +&prompt.root; <userinput>make test-domain</userinput></screen> - <para>(if it is not commented out already).</para> - </sect4> + <para>The user could also be added using <command>adduser + jsmith</command> instead of <command>pw useradd + jsmith</command>.</para> + </sect3> + </sect2> - <sect4> - <title>Setting up a NIS Slave Server</title> + <sect2> + <title>Setting up a <acronym>NIS</acronym> Slave + Server</title> <indexterm> <primary>NIS</primary> <secondary>slave server</secondary> </indexterm> - <para>Setting up an NIS slave server is even more simple - than setting up the master. Log on to the slave server - and edit the file <filename>/etc/rc.conf</filename> as you - did before. The only difference is that we now must use - the <option>-s</option> option when running - <command>ypinit</command>. The <option>-s</option> option - requires the name of the NIS master be passed to it as - well, so our command line looks like:</para> + <para>To set up an <acronym>NIS</acronym> slave server, log + on to the slave server and edit + <filename>/etc/rc.conf</filename> as for the master + server. Do not generate any <acronym>NIS</acronym> maps, + as these already exist on the master server. When running + <command>ypinit</command> on the slave server, use + <option>-s</option> (for slave) instead of + <option>-m</option> (for master). This option requires + the name of the <acronym>NIS</acronym> master in + addition to the domain name, as seen in this + example:</para> <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput> @@ -1741,155 +1614,139 @@ ypxfr: Exiting: Map successfully transferred coltrane has been setup as an YP slave server without any errors. Remember to update map ypservers on ellington.</screen> - <para>There should be a directory called - <filename>/var/yp/test-domain</filename>. Copies of the - NIS master server's maps should be in this directory. - These files must always be up to date. The following - <filename>/etc/crontab</filename> entries on the slave - servers should do the job:</para> + <para>This will generate a directory on the slave server + called <filename + class="directory">/var/yp/test-domain</filename> which + contains copies of the <acronym>NIS</acronym> master + server's maps. Adding these + <filename>/etc/crontab</filename> entries on each slave + server will force the slaves to sync their maps with the + maps on the master server:</para> - <programlisting>20 * * * * root /usr/libexec/ypxfr passwd.byname + <programlisting>20 * * * * root /usr/libexec/ypxfr passwd.byname 21 * * * * root /usr/libexec/ypxfr passwd.byuid</programlisting> - <para>These two lines force the slave to sync its maps with - the maps on the master server. These entries are not - mandatory because the master server automatically attempts - to push any map changes to its slaves; however, due to - the importance of correct password information on other - clients depending on the slave server, it is recommended - to specifically force the password map updates frequently. - This is especially important on busy networks where map - updates might not always complete.</para> - - <para>Now, run the command <command>/etc/netstart</command> - on the slave server as well, which again starts the NIS - server.</para> - </sect4> - </sect3> + <para>These entries are not + mandatory because the master server automatically attempts + to push any map changes to its slaves. However, since + clients may depend upon the slave server to provide correct + password information, it is recommended to force frequent + password map updates. This is especially important on busy + networks where map updates might not always complete.</para> + + <para>To finish the configuration, run + <command>/etc/netstart</command> on the slave server in + order to start the <acronym>NIS</acronym> + services.</para> + </sect2> - <sect3> - <title>NIS Clients</title> - - <para>An NIS client establishes what is called a binding to a - particular NIS server using the <command>ypbind</command> - daemon. The <command>ypbind</command> command checks the - system's default domain (as set by the - <command>domainname</command> command), and begins - broadcasting RPC requests on the local network. These - requests specify the name of the domain for which - <command>ypbind</command> is attempting to establish a - binding. If a server that has been configured to serve the - requested domain receives one of the broadcasts, it will - respond to <command>ypbind</command>, which will record the - server's address. If there are several servers available (a - master and several slaves, for example), - <command>ypbind</command> will use the address of the first - one to respond. From that point on, the client system will - direct all of its NIS requests to that server. - <command>ypbind</command> will occasionally - <quote>ping</quote> the server to make sure it is still up - and running. If it fails to receive a reply to one of its - pings within a reasonable amount of time, - <command>ypbind</command> will mark the domain as unbound - and begin broadcasting again in the hopes of locating - another server.</para> - - <sect4> - <title>Setting Up a NIS Client</title> + <sect2> + <title>Setting Up an <acronym>NIS</acronym> Client</title> + + <para>An <acronym>NIS</acronym> client binds to an + <acronym>NIS</acronym> server using &man.ypbind.8;. This + daemon broadcasts RPC requests on the local network. These + requests specify the domain name configured on the client. + If an <acronym>NIS</acronym> server in the same domain + receives one of the broadcasts, it will respond to + <application>ypbind</application>, which will record the + server's address. If there are several servers available, + the client will use the address of the first server to + respond and will direct all of its <acronym>NIS</acronym> + requests to that server. The client will automatically + <application>ping</application> the server on a regular + basis to make sure it is still available. If it fails to + receive a reply within a reasonable amount of time, + <application>ypbind</application> will mark the domain as + unbound and begin broadcasting again in the hopes of + locating another server.</para> + + <indexterm><primary>NIS</primary> + <secondary>client configuration</secondary> + </indexterm> - <indexterm> - <primary>NIS</primary> - <secondary>client configuration</secondary> - </indexterm> - <para>Setting up a FreeBSD machine to be a NIS client is - fairly straightforward.</para> + <para>To configure a &os; machine to be an + <acronym>NIS</acronym> client:</para> - <procedure> - <step> - <para>Edit <filename>/etc/rc.conf</filename> and add the - following lines in order to set the NIS domainname and - start <command>ypbind</command> during network - startup:</para> + <procedure> + <step> + <para>Edit <filename>/etc/rc.conf</filename> and add the + following lines in order to set the + <acronym>NIS</acronym> domain name and start + &man.ypbind.8; during network + startup:</para> - <programlisting>nisdomainname="test-domain" + <programlisting>nisdomainname="test-domain" nis_client_enable="YES"</programlisting> </step> <step> <para>To import all possible password entries from the - NIS server, remove all user accounts from the - <filename>/etc/master.passwd</filename> file and use - <command>vipw</command> to add the following line to - the end of the file:</para> + <acronym>NIS</acronym> server, use + <command>vipw</command> to remove all user accounts + except one from + <filename>/etc/master.passwd</filename>. When + removing the accounts, keep in mind that at least one + local account should remain and this account should be + a member of <groupname>wheel</groupname>. If there is + a problem with <acronym>NIS</acronym>, this local + account can be used to log in remotely, become the + superuser, and fix the problem. Before saving the + edits, add the following line to the end of the + file:</para> <programlisting>+:::::::::</programlisting> - <note> - <para>This line will afford anyone with a valid - account in the NIS server's password maps an - account. There are many ways to configure the NIS - client by changing this line. See the - <link linkend="network-netgroups">netgroups - section</link> below for more information. For - more detailed reading see O'Reilly's book on - <literal>Managing NFS and NIS</literal>.</para> - </note> - - <note> - <para>Keep in mind that at least one local account - (i.e. not imported via NIS) must exist in - <filename>/etc/master.passwd</filename> and this - account should also be a member of the group - <groupname>wheel</groupname>. If there is something - wrong with NIS, this account can be used to log in - remotely, become <username>root</username>, and fix - things.</para> - </note> + <para>This line configures the client to provide + anyone with a valid account in the + <acronym>NIS</acronym> server's password maps an + account on the client. There are many ways to + configure the <acronym>NIS</acronym> client by + modifying this line. One method is described in + <xref linkend="network-netgroups"/>. For + more detailed reading, refer to the book + <literal>Managing NFS and NIS</literal>, published + by O'Reilly Media.</para> </step> <step> - <para>To import all possible group entries from the NIS - server, add this line to + <para>To import all possible group entries from the + <acronym>NIS</acronym> server, add this line to <filename>/etc/group</filename>:</para> <programlisting>+:*::</programlisting> </step> </procedure> - <para>To start the NIS client immediately, execute the - following commands as the superuser:</para> + <para>To start the <acronym>NIS</acronym> client + immediately, execute the following commands as the + superuser:</para> <screen>&prompt.root; <userinput>/etc/netstart</userinput> &prompt.root; <userinput>service ypbind start</userinput></screen> - <para>After completing these steps, the command, - <command>ypcat passwd</command>, should show the - server's passwd map.</para> - </sect4> - </sect3> + <para>After completing these steps, running + <command>ypcat passwd</command> on the client should show + the server's <filename>passwd</filename> map.</para> </sect2> <sect2> - <title>NIS Security</title> - - <para>In general, any remote user may issue an RPC to - &man.ypserv.8; and retrieve the contents of the NIS maps, - provided the remote user knows the domainname. To prevent - such unauthorized transactions, &man.ypserv.8; supports a - feature called <quote>securenets</quote> which can be used to - restrict access to a given set of hosts. At startup, - &man.ypserv.8; will attempt to load the securenets information - from a file called - <filename>/var/yp/securenets</filename>.</para> - - <note> - <para>This path varies depending on the path specified with - the <option>-p</option> option. This file contains entries - that consist of a network specification and a network mask - separated by white space. Lines starting with - <quote>#</quote> are considered to be comments. A sample - securenets file might look like this:</para> - </note> + <title><acronym>NIS</acronym> Security</title> + + <para>Since <acronym>RPC</acronym> is a broadcast-based service, + any system running <application>ypbind</application> within + the same domain can retrieve the contents of the + <acronym>NIS</acronym> maps. To prevent unauthorized + transactions, &man.ypserv.8; supports a feature called + <quote>securenets</quote> which can be used to restrict access + to a given set of hosts. By default, this information is + stored in <filename>/var/yp/securenets</filename>, unless + &man.ypserv.8; is started with <option>-p</option> and an + alternate path. This file contains entries that consist of a + network specification and a network mask separated by white + space. Lines starting with <literal>#</literal> are + considered to be comments. A sample + <filename>securenets</filename> might look like this:</para> <programlisting># allow connections from local host -- mandatory 127.0.0.1 255.255.255.255 @@ -1905,86 +1762,65 @@ nis_client_enable="YES"</programlisting> matches one of these rules, it will process the request normally. If the address fails to match a rule, the request will be ignored and a warning message will be logged. If the - <filename>/var/yp/securenets</filename> file does not exist, + <filename>securenets</filename> does not exist, <command>ypserv</command> will allow connections from any host.</para> - <para>The <command>ypserv</command> program also has support for - Wietse Venema's <application>TCP Wrapper</application> - package. This allows the administrator to use the - <application>TCP Wrapper</application> configuration files for - access control instead of - <filename>/var/yp/securenets</filename>.</para> - - <note> - <para>While both of these access control mechanisms provide - some security, they, like the privileged port test, are - vulnerable to <quote>IP spoofing</quote> attacks. All - NIS-related traffic should be blocked at the - firewall.</para> - - <para>Servers using <filename>/var/yp/securenets</filename> - may fail to serve legitimate NIS clients with archaic TCP/IP - implementations. Some of these implementations set all host - bits to zero when doing broadcasts and/or fail to observe - the subnet mask when calculating the broadcast address. - While some of these problems can be fixed by changing the - client configuration, other problems may force - the retirement of the client systems in question or the - abandonment of - <filename>/var/yp/securenets</filename>.</para> - - <para>Using <filename>/var/yp/securenets</filename> on a - server with such an archaic implementation of TCP/IP is a - really bad idea and will lead to loss of NIS functionality - for large parts of the network.</para> - - <indexterm><primary>TCP Wrappers</primary></indexterm> - <para>The use of <application>TCP Wrapper</application> - increases the latency of the NIS server. The additional - delay may be long enough to cause timeouts in client - programs, especially in busy networks or with slow NIS - servers. If one or more of the client systems suffers from - these symptoms, convert the client systems in question into - NIS slave servers and force them to bind to - themselves.</para> - </note> - </sect2> - - <sect2> - <title>Barring Some Users from Logging On</title> - - <para>In our lab, there is a machine <hostid>basie</hostid> that - is supposed to be a faculty only workstation. We do not want - to take this machine out of the NIS domain, yet the - <filename>passwd</filename> file on the master NIS server - contains accounts for both faculty and students. What can we - do?</para> - - <para>There is a way to bar specific users from logging on to a - machine, even if they are present in the NIS database. To do - this, add - <literal>-<replaceable>username</replaceable></literal> with - the correct number of colons like other entries to the end of - the <filename>/etc/master.passwd</filename> file on the client - machine, where <replaceable>username</replaceable> is the - username of the user to bar from logging in. The line with - the blocked user must be before the <literal>+</literal> line - for allowing NIS users. This should preferably be done using - <command>vipw</command>, since <command>vipw</command> will - sanity check the changes to - <filename>/etc/master.passwd</filename>, as well as - automatically rebuild the password database after editing. - For example, to bar user <username>bill</username> from - logging on to <hostid>basie</hostid>:</para> - - <screen>basie&prompt.root; <userinput>vipw</userinput> -<userinput>[add -bill::::::::: to the end, exit]</userinput> -vipw: rebuilding the database... -vipw: done - -basie&prompt.root; <userinput>cat /etc/master.passwd</userinput> + <para><xref linkend="tcpwrappers"/> is an alternate mechanism + for providing access control instead of + <filename>securenets</filename>. While either access control + mechanism adds some security, they are both vulnerable to + <quote><acronym>IP</acronym> spoofing</quote> attacks. All + <acronym>NIS</acronym>-related traffic should be blocked at + the firewall.</para> + + <para>Servers using <filename>securenets</filename> + may fail to serve legitimate <acronym>NIS</acronym> clients + with archaic TCP/IP implementations. Some of these + implementations set all host bits to zero when doing + broadcasts or fail to observe the subnet mask when + calculating the broadcast address. While some of these + problems can be fixed by changing the client configuration, + other problems may force the retirement of these client + systems or the abandonment of + <filename>securenets</filename>.</para> + + <indexterm><primary>TCP Wrapper</primary></indexterm> + <para>The use of <application>TCP Wrapper</application> + increases the latency of the <acronym>NIS</acronym> server. + The additional delay may be long enough to cause timeouts in + client programs, especially in busy networks with slow + <acronym>NIS</acronym> servers. If one or more clients suffer + from latency, convert those clients into + <acronym>NIS</acronym> slave servers and force them to bind to + themselves.</para> + <sect3> + <title>Barring Some Users</title> + + <para>In this example, the <hostid>basie</hostid> system + is a faculty workstation within the <acronym>NIS</acronym> + domain. The <filename>passwd</filename> map on the master + <acronym>NIS</acronym> server contains accounts for both + faculty and students. This section demonstrates how to + allow faculty logins on this system while refusing student + logins.</para> + + <para>To prevent specified users from logging on to a + system, even if they are present in the + <acronym>NIS</acronym> database, use <command>vipw</command> + to add + <literal>-<replaceable>username</replaceable></literal> with + the correct number of colons towards the end of + <filename>/etc/master.passwd</filename> on the client, + where <replaceable>username</replaceable> is the username of + a user to bar from logging in. The line with the blocked + user must be before the <literal>+</literal> line that + allows <acronym>NIS</acronym> users. In this example, + <username>bill</username> is barred from logging on to + <hostid>basie</hostid>:</para> + + <screen>basie&prompt.root; <userinput>cat /etc/master.passwd</userinput> root:[password]:0:0::0:0:The super-user:/root:/bin/csh toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin @@ -2004,9 +1840,11 @@ nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin +::::::::: basie&prompt.root;</screen> + </sect3> </sect2> <sect2 id="network-netgroups"> + <!-- <sect2info> <authorgroup> <author> @@ -2016,40 +1854,30 @@ basie&prompt.root;</screen> </author> </authorgroup> </sect2info> + --> <title>Using Netgroups</title> <indexterm><primary>netgroups</primary></indexterm> - <para>The method shown in the previous section works reasonably - well for special rules in an environment with small numbers of - users and/or machines. On larger networks, administrators - <emphasis>will</emphasis> likely forget to bar some users from - logging onto sensitive machines, or may even have to modify - each machine separately, thus losing the main benefit of NIS: + <para>Barring specified users from logging on to individual + systems becomes unscaleable on larger networks and quickly + loses the main benefit of <acronym>NIS</acronym>: <emphasis>centralized</emphasis> administration.</para> - <para>The NIS developers' solution for this problem is called - <emphasis>netgroups</emphasis>. Their purpose and semantics - can be compared to the normal groups used by &unix; file - systems. The main differences are the lack of a numeric ID - and the ability to define a netgroup by including both user - accounts and other netgroups.</para> - <para>Netgroups were developed to handle large, complex networks - with hundreds of users and machines. On one hand, this is a - Good Thing in such a situation. On the other hand, this - complexity makes it almost impossible to explain netgroups - with really simple examples. The example used in the - remainder of this section demonstrates this problem.</para> - - <para>Let us assume that the successful introduction of NIS in - the laboratory caught a superiors' interest. The next task is - to extend the NIS domain to cover some of the other machines - on campus. The two tables contain the names of the new users - and new machines as well as brief descriptions of them.</para> + with hundreds of users and machines. Their use is comparable + to &unix; groups, where the main difference is the lack of a + numeric ID and the ability to define a netgroup by including + both user accounts and other netgroups.</para> + + <para>To expand on the example used in this chapter, the + <acronym>NIS</acronym> domain will be extended to add the + users and systems shown in Tables 28.2 and 28.3:</para> + + <table frame="none" pgwide="1"> + <title>Additional Users</title> - <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> @@ -2062,32 +1890,34 @@ basie&prompt.root;</screen> <row> <entry><username>alpha</username>, <username>beta</username></entry> - <entry>Normal employees of the IT department</entry> + <entry>IT department employees</entry> </row> <row> <entry><username>charlie</username>, <username>delta</username></entry> - <entry>The new apprentices of the IT department</entry> + <entry>IT department apprentices</entry> </row> <row> <entry><username>echo</username>, <username>foxtrott</username>, <username>golf</username>, ...</entry> - <entry>Ordinary employees</entry> + <entry>employees</entry> </row> <row> <entry><username>able</username>, <username>baker</username>, ...</entry> - <entry>The current interns</entry> + <entry>interns</entry> </row> </tbody> </tgroup> - </informaltable> + </table> + + <table frame="none" pgwide="1"> + <title>Additional Systems</title> - <informaltable frame="none" pgwide="1"> <tgroup cols="2"> <thead> <row> @@ -2103,9 +1933,8 @@ basie&prompt.root;</screen> <entry><hostid>war</hostid>, <hostid>death</hostid>, <hostid>famine</hostid>, <hostid>pollution</hostid></entry> - <entry>The most important servers deployed. Only the IT - employees are allowed to log onto these - machines.</entry> + <entry>Only IT employees are allowed to log onto these + servers.</entry> </row> <row> @@ -2113,62 +1942,45 @@ basie&prompt.root;</screen> <entry><hostid>pride</hostid>, <hostid>greed</hostid>, <hostid>envy</hostid>, <hostid>wrath</hostid>, <hostid>lust</hostid>, <hostid>sloth</hostid></entry> - <entry>Less important servers. All members of the IT - department are allowed to login onto these - machines.</entry> + <entry>All members of the IT department are allowed to + login onto these servers.</entry> </row> <row> <entry><hostid>one</hostid>, <hostid>two</hostid>, <hostid>three</hostid>, <hostid>four</hostid>, ...</entry> - <entry>Ordinary workstations. Only the - <emphasis>real</emphasis> employees are allowed to use - these machines.</entry> + <entry>Ordinary workstations used by + employees.</entry> </row> <row> <entry><hostid>trashcan</hostid></entry> <entry>A very old machine without any critical data. - Even the intern is allowed to use this box.</entry> + Even interns are allowed to use this system.</entry> </row> </tbody> </tgroup> - </informaltable> + </table> - <para>An attempt to implement these restrictions by separately - blocking each user, would require the addition of the - <literal>-<replaceable>user</replaceable></literal> line to - each system's <filename>passwd</filename>. One line for each - user who is not allowed to login onto that system. Forgetting - just one entry could cause significant trouble. It may be - feasible to do this correctly during the initial setup; - however, eventually someone will forget to add these lines for - new users.</para> - - <para>Handling this situation with netgroups offers several - advantages. Each user need not be handled separately; they - would be assigned to one or more netgroups and logins would be - allowed or forbidden for all members of the netgroup. While + <para>When using netgroups to configure this scenario, each user + is assigned to one or more netgroups and logins are then + allowed or forbidden for all members of the netgroup. When adding a new machine, login restrictions must be defined for - all netgroups. If a new user is added, they must be added to - one or more netgroups. Those changes are independent of each - other: no more - <quote>for each combination of user and machine do...</quote> - If the NIS setup is planned carefully, only one central - configuration file needs modification to grant or deny access - to machines.</para> + all netgroups. When a new user is added, the account must be + added to one or more netgroups. If the + <acronym>NIS</acronym> setup is planned carefully, only one + central configuration file needs modification to grant or deny + access to machines.</para> - <para>The first step is the initialization of the NIS map - netgroup. &os;'s &man.ypinit.8; does not create this map by - default, but its NIS implementation will support it after - creation. To create an empty map, simply type</para> + <para>The first step is the initialization of the + <acronym>NIS</acronym> <literal>netgroup</literal> map. In + &os;, this map is not created by default. On the + <acronym>NIS</acronym> master server, use an editor to create + a map named <filename>/var/yp/netgroup</filename>.</para> - <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen> - - <para>and begin adding content. For our example, we need at - least four netgroups: IT employees, IT apprentices, normal - employees and interns.</para> + <para>This example creates four netgroups to represent IT + employees, IT apprentices, employees, and interns:</para> <programlisting>IT_EMP (,alpha,test-domain) (,beta,test-domain) IT_APP (,charlie,test-domain) (,delta,test-domain) @@ -2176,17 +1988,17 @@ USERS (,echo,test-domain) (,foxtrott,test-domain) \ (,golf,test-domain) INTERNS (,able,test-domain) (,baker,test-domain)</programlisting> - <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc. - are the names of the netgroups. Each bracketed group adds - one or more user accounts to it. The three fields inside a - group are:</para> + <para>Each entry configures a netgroup. The first column in an + entry is the name of the netgroup. Each set of brackets + represents either a group of one or more users or the name of + another netgroup. When specifying a user, the three + comma-delimited fields inside each group represent:</para> <orderedlist> <listitem> - <para>The name of the host(s) where the following items are - valid. If a hostname is not specified, the entry is valid - on all hosts. If a hostname is specified, it will need to - be micro-managed within this configuration.</para> + <para>The name of the host(s) where the other fields + representing the user are valid. If a hostname is not + specified, the entry is valid on all hosts.</para> </listitem> <listitem> @@ -2195,51 +2007,48 @@ INTERNS (,able,test-domain) (,baker,test-domain)</programlisting> </listitem> <listitem> - <para>The NIS domain for the account. Accounts may be - imported from other NIS domains into a netgroup.</para> + <para>The <acronym>NIS</acronym> domain for the account. + Accounts may be imported from other <acronym>NIS</acronym> + domains into a netgroup.</para> </listitem> </orderedlist> - <para>Each of these fields may contain wildcards. See - &man.netgroup.5; for details.</para> + <para>If a group contains multiple users, separate each user + with whitespace. Additionally, each field may contain + wildcards. See &man.netgroup.5; for details.</para> - <note> - <indexterm><primary>netgroups</primary></indexterm> - <para>Netgroup names longer than 8 characters should not be - used, especially with machines running other operating - systems within the NIS domain. The names are case - sensitive; using capital letters for netgroup names is an - easy way to distinguish between user, machine and netgroup - names.</para> - - <para>Some NIS clients (other than &os;) cannot handle - netgroups with a large number of entries. For example, some - older versions of &sunos; start to cause trouble if a - netgroup contains more than 15 <emphasis>entries</emphasis>. - This limit may be circumvented by creating several - sub-netgroups with 15 users or fewer and a real netgroup - consisting of the sub-netgroups:</para> - - <programlisting>BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] + <indexterm><primary>netgroups</primary></indexterm> + <para>Netgroup names longer than 8 characters should not be + The names are case sensitive and using capital letters + letters for netgroup names is an easy way to distinguish + between user, machine and netgroup names.</para> + + <para>Some non-&os; <acronym>NIS</acronym> clients cannot + handle netgroups containing more than 15 entries. This + limit may be circumvented by creating several sub-netgroups + with 15 users or fewer and a real netgroup consisting of the + sub-netgroups, as seen in this example:</para> + + <programlisting>BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] BIGGRP2 (,joe16,domain) (,joe17,domain) [...] BIGGRP3 (,joe31,domain) (,joe32,domain) BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3</programlisting> - <para>Repeat this process if more than 225 users will exist - within a single netgroup.</para> - </note> + <para>Repeat this process if more than 225 (15 times 15) users + exist within a single netgroup.</para> - <para>Activating and distributing the new NIS map is - easy:</para> + <para>To activate and distribute the new + <acronym>NIS</acronym> map:</para> <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput> ellington&prompt.root; <userinput>make</userinput></screen> - <para>This will generate the three NIS maps + <para>This will generate the three <acronym>NIS</acronym> maps <filename>netgroup</filename>, <filename>netgroup.byhost</filename> and - <filename>netgroup.byuser</filename>. Use &man.ypcat.1; to - check if the new NIS maps are available:</para> + <filename>netgroup.byuser</filename>. Use the map key option + of &man.ypcat.1; to check if the new <acronym>NIS</acronym> + maps are available:</para> <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput> ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput> @@ -2247,13 +2056,13 @@ ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> <para>The output of the first command should resemble the contents of <filename>/var/yp/netgroup</filename>. The second - command will not produce output without specified - host-specific netgroups. The third command may be used to get - the list of netgroups for a user.</para> + command only produces output if host-specific netgroups were + created. The third command is used to get the list of + netgroups for a user.</para> - <para>The client setup is quite simple. To configure the server - <hostid>war</hostid>, use &man.vipw.8; to replace the - line</para> + <para>To configure a client, use &man.vipw.8; to specify the + name of the netgroup. For example, on the server named + <hostid>war</hostid>, replace this line:</para> <programlisting>+:::::::::</programlisting> @@ -2261,84 +2070,64 @@ ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> <programlisting>+@IT_EMP:::::::::</programlisting> - <para>Now, only the data for the users defined in the netgroup - <literal>IT_EMP</literal> is imported into - <hostid>war</hostid>'s password database and only these users - are allowed to login.</para> + <para>This specifies that only the users defined in the netgroup + <literal>IT_EMP</literal> will be imported into this system's + password database and only those users are allowed to login to + this system.</para> - <para>Unfortunately, this limitation also applies to the + <para>This configuration also applies to the <literal>~</literal> function of the shell and all routines - converting between user names and numerical user IDs. In + which convert between user names and numerical user IDs. In other words, <command>cd ~<replaceable>user</replaceable></command> will not work, <command>ls -l</command> will show the numerical ID - instead of the username and - <command>find . -user joe -print</command> will fail with + instead of the username, and <command>find . -user joe + -print</command> will fail with the message <errorname>No such user</errorname>. To fix this, import all - user entries <emphasis>without allowing them to login into the - servers</emphasis>.</para> + user entries without allowing them to login into the servers. + This can be achieved by adding an extra line:</para> - <para>This can be achieved by adding another line to - <filename>/etc/master.passwd</filename>. This line should - contain:</para> + <programlisting>+:::::::::/sbin/nologin</programlisting> - <para><literal>+:::::::::/sbin/nologin</literal>, meaning - <quote>Import all entries but replace the shell with - <filename>/sbin/nologin</filename> in the imported - entries</quote>. It is possible to replace any field in the - <literal>passwd</literal> entry by placing a default value in - <filename>/etc/master.passwd</filename>.</para> + <para>This line configures the client to import all entries but + to replace the shell in those entries with + <filename>/sbin/nologin</filename>.</para> <!-- Been there, done that, got the scars to prove it - ue --> - <warning> - <para>Make sure that the line - <literal>+:::::::::/sbin/nologin</literal> is placed after - <literal>+@IT_EMP:::::::::</literal>. Otherwise, all user - accounts imported from NIS will have - <filename>/sbin/nologin</filename> as their login - shell.</para> - </warning> - - <para>After this change, the NIS map will only need modification - when a new employee joins the IT department. A similar - approach for the less important servers may be used by - replacing the old <literal>+:::::::::</literal> in their local - version of <filename>/etc/master.passwd</filename> with - something like this:</para> + <para>Make sure that extra line is placed + <emphasis>after</emphasis> + <literal>+@IT_EMP:::::::::</literal>. Otherwise, all user + accounts imported from <acronym>NIS</acronym> will have + <filename>/sbin/nologin</filename> as their login + shell and noone will be able to login to the system.</para> + + <para>To configure the less important servers, replace the old + <literal>+:::::::::</literal> on the servers with these + lines:</para> <programlisting>+@IT_EMP::::::::: +@IT_APP::::::::: +:::::::::/sbin/nologin</programlisting> - <para>The corresponding lines for the normal workstations - could be:</para> + <para>The corresponding lines for the workstations + would be:</para> <programlisting>+@IT_EMP::::::::: +@USERS::::::::: +:::::::::/sbin/nologin</programlisting> - <para>And everything would be fine until there is a policy - change a few weeks later: The IT department starts hiring - interns. The IT interns are allowed to use the normal - workstations and the less important servers; and the IT - apprentices are allowed to login onto the main servers. Add a - new netgroup <literal>IT_INTERN</literal>, then add the new IT - interns to this netgroup and start to change the configuration - on each and every machine. As the old saying goes: - <quote>Errors in centralized planning lead to global - mess</quote>.</para> - - <para>NIS' ability to create netgroups from other netgroups can - be used to prevent situations like these. One possibility is - the creation of role-based netgroups. For example, one might - create a netgroup called <literal>BIGSRV</literal> to define - the login restrictions for the important servers, another - netgroup called <literal>SMALLSRV</literal> for the less - important servers and a third netgroup called - <literal>USERBOX</literal> for the normal workstations. Each - of these netgroups contains the netgroups that are allowed to - login onto these machines. The new entries for the NIS map - netgroup should look like this:</para> + <para>NIS supports the creation of netgroups from other + netgroups which can be useful if the policy regarding user + access changes. One possibility is the creation of role-based + netgroups. For example, one might create a netgroup called + <literal>BIGSRV</literal> to define the login restrictions for + the important servers, another netgroup called + <literal>SMALLSRV</literal> for the less important servers, + and a third netgroup called <literal>USERBOX</literal> for the + workstations. Each of these netgroups contains the netgroups + that are allowed to login onto these machines. The new + entries for the <acronym>NIS</acronym> + <literal>netgroup</literal> map would look like this:</para> <programlisting>BIGSRV IT_EMP IT_APP SMALLSRV IT_EMP IT_APP ITINTERN @@ -2351,16 +2140,15 @@ USERBOX IT_EMP ITINTERN USERS</programlisting> to define login restrictions on a per-machine basis is required.</para> - <para>Machine-specific netgroup definitions are the other - possibility to deal with the policy change outlined above. In - this scenario, the <filename>/etc/master.passwd</filename> of - each box contains two lines starting with <quote>+</quote>. - The first of them adds a netgroup with the accounts allowed to - login onto this machine, the second one adds all other + <para>Machine-specific netgroup definitions are another + possibility to deal with the policy changes. In this + scenario, the <filename>/etc/master.passwd</filename> of each + system contains two lines starting with <quote>+</quote>. + The first line adds a netgroup with the accounts allowed to + login onto this machine and the second line adds all other accounts with <filename>/sbin/nologin</filename> as shell. It - is a good idea to use the <quote>ALL-CAPS</quote> version of - the machine name as the name of the netgroup. In other words, - the lines should look like this:</para> + is recommended to use the <quote>ALL-CAPS</quote> version of + the hostname as the name of the netgroup:</para> <programlisting>+@<replaceable>BOXNAME</replaceable>::::::::: +:::::::::/sbin/nologin</programlisting> @@ -2368,9 +2156,9 @@ USERBOX IT_EMP ITINTERN USERS</programlisting> <para>Once this task is completed on all the machines, there is no longer a need to modify the local versions of <filename>/etc/master.passwd</filename> ever again. All - further changes can be handled by modifying the NIS map. Here - is an example of a possible netgroup map for this scenario - with some additional goodies:</para> + further changes can be handled by modifying the + <acronym>NIS</acronym> map. Here is an example of a possible + <literal>netgroup</literal> map for this scenario:</para> <programlisting># Define groups of users first IT_EMP (,alpha,test-domain) (,beta,test-domain) @@ -2408,116 +2196,12 @@ ONE SECURITY TWO (,hotel,test-domain) # [...more groups to follow]</programlisting> - <para>If some kind of database is used to manage the user - accounts, it may be possible to create the first part of the - map using the database's reporting tools. This way, new users - will automatically have access to the boxes.</para> - - <para>One last word of caution: It may not always be advisable + <para>It may not always be advisable to use machine-based netgroups. When deploying a couple of - dozen or even hundreds of identical machines for student labs, + dozen or hundreds of systems, role-based netgroups instead of machine-based netgroups may be - used to keep the size of the NIS map within reasonable - limits.</para> - </sect2> - - <sect2> - <title>Important Things to Remember</title> - - <para>There are still a couple of things administrators need to - do differently now that machines are in an NIS - environment.</para> - - <itemizedlist> - <listitem> - <para>Every time a new user is added to the lab, they must - be added to the master NIS server and the - <acronym>NIS</acronym> maps will need rebuilt. If this - step is omitted, the new user will not be able to login - anywhere except on the NIS master. For example, if we - needed to add a new user <username>jsmith</username> to - the lab, we would:</para> - - <screen>&prompt.root; <userinput>pw useradd jsmith</userinput> -&prompt.root; <userinput>cd /var/yp</userinput> -&prompt.root; <userinput>make test-domain</userinput></screen> - - <para>The user may also be added using - <command>adduser jsmith</command> - instead of <command>pw useradd jsmith</command>.</para> - </listitem> - - <listitem> - <para><emphasis>Keep the administration accounts out of the - NIS maps</emphasis>. This is undesirable as it will - create a security risk. These users and passwords should - not be propagated to all machines. Especially if these - machines will have users whom should not have access to - those accounts.</para> - </listitem> - - <listitem> - <para><emphasis>Keep the NIS master and slave secure, and - minimize their downtime</emphasis>. If somebody either - hacks or simply turns off these machines, they have - effectively rendered many people without the ability to - login to the lab.</para> - - <para>This is the chief weakness of any centralized - administration system. If the NIS servers are not - protected, there will be a lot of angry users and - unhappy management!</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>NIS v1 Compatibility</title> - - <para>&os;'s <application>ypserv</application> has some support - for serving NIS v1 clients. &os;'s NIS implementation only - uses the NIS v2 protocol; however, other implementations - include support for the v1 protocol for backwards - compatibility with older systems. The - <application>ypbind</application> daemons supplied with these - systems will attempt to establish a binding to an NIS v1 - server even though they may never actually need it (and they - may persist in broadcasting in search of one even after they - receive a response from a v2 server). Note that while support - for normal client calls is provided, this version of - <application>ypserv</application> does not handle v1 map - transfer requests. Additionally, it cannot be used as a - master or slave in conjunction with older NIS servers that - only support the v1 protocol. Fortunately, there probably are - not any such servers still in use today.</para> - </sect2> - - <sect2 id="network-nis-server-is-client"> - <title>NIS Servers That Are Also NIS Clients</title> - - <para>Care must be taken when running - <application>ypserv</application> in a multi-server domain - where the server machines are also NIS clients. It is - generally a good idea to force the servers to bind to - themselves rather than allowing them to broadcast bind - requests and possibly become bound to each other. Strange - failure modes can result if one server goes down and others - are dependent upon it. Eventually all the clients will time - out and attempt to bind to other servers, but the delay - involved can be considerable and the failure mode is still - present since the servers might bind to each other all over - again.</para> - - <para>A host may be forced to bind to a particular server by - running <command>ypbind</command> with the <option>-S</option> - flag. Add the following lines to - <filename>/etc/rc.conf</filename> to enable this feature - during every system boot:</para> - - <programlisting>nis_client_enable="YES" # run client stuff as well -nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting> - - <para>See &man.ypbind.8; for further information.</para> + used to keep the size of the <acronym>NIS</acronym> map within + reasonable limits.</para> </sect2> <sect2> @@ -2525,69 +2209,48 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ <indexterm> <primary>NIS</primary> - <secondary>password formats</secondary> + <secondary>password formats</secondary> </indexterm> - <para>One of the most common issues that people run into when - trying to implement NIS is password format compatibility. If - the NIS server is using DES encrypted passwords, it will only - support clients that are also using DES. For example, if any - &solaris; NIS clients exist on the network, there is a highly - likelihood DES must be used for encrypted passwords.</para> - - <para>To check which format the servers and clients are using, - look at <filename>/etc/login.conf</filename>. If the host is - configured to use DES encrypted passwords, then the - <literal>default</literal> class will contain an entry like - this:</para> + <para><acronym>NIS</acronym> requires that all hosts within an + <acronym>NIS</acronym> domain use the same format for + encrypting passwords. If users have trouble authenticating on + an <acronym>NIS</acronym> client, it may be due to a differing + password format. In a heterogeneous network, the format must + be supported by all operating systems, where + <acronym>DES</acronym> is the lowest common standard.</para> + + <para>To check which format a server or client is using, look + at this section of + <filename>/etc/login.conf</filename>:</para> <programlisting>default:\ :passwd_format=des:\ :copyright=/etc/COPYRIGHT:\ [Further entries elided]</programlisting> - <para>Other possible values for the - <literal>passwd_format</literal> capability include - <literal>blf</literal> and <literal>md5</literal> (for - Blowfish and MD5 encrypted passwords, respectively).</para> + <para>In this example, the system is using the + <acronym>DES</acronym> format. Other possible values are + <literal>blf</literal> for Blowfish and <literal>md5</literal> + for MD5 encrypted passwords.</para> - <para>If any changes were made to - <filename>/etc/login.conf</filename>, the - login capability database must be rebuilt by - running the following command as - <username>root</username>:</para> + <para>If the format on a host needs to be edited to match the + one being used in the <acronym>NIS</acronym> domain, the + login capability database must be rebuilt after saving the + change:</para> <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> <note> - <para>The format of passwords already in - <filename>/etc/master.passwd</filename> will not be updated - until a user changes his password for the first time + <para>The format of passwords for existing user accounts will + not be updated until each user changes their password <emphasis>after</emphasis> the login capability database is rebuilt.</para> </note> - - <para>Next, in order to ensure that passwords are encrypted with - the chosen format, check that the - <literal>crypt_default</literal> in - <filename>/etc/auth.conf</filename> gives precedence to the - chosen password format. To do this, place the chosen format - first in the list. For example, when using DES encrypted - passwords, the entry would be:</para> - - <programlisting>crypt_default = des blf md5</programlisting> - - <para>Having followed the above steps on each of the &os; based - NIS servers and clients, verify that they all agree on which - password format is used within the network. If users have - trouble authenticating on an NIS client, this is a pretty good - place to start looking for possible problems. Remember: to - deploy an NIS server for a heterogeneous network, they will - probably have to use DES on all systems because it is the - lowest common standard.</para> </sect2> </sect1> <sect1 id="network-ldap"> + <!-- <sect1info> <authorgroup> <author> @@ -2597,6 +2260,7 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ </author> </authorgroup> </sect1info> + --> <title>&os; and <acronym>LDAP</acronym></title> <indexterm><primary>LDAP</primary></indexterm> @@ -2714,12 +2378,12 @@ result: 0 Success during the certificate creation process below.</para> <para>The following commands must be executed in the - <filename class="directory"> - /usr/local/etc/openldap/private</filename> directory. This - is important as the file permissions will need to be - restrictive and users should not have access to these files - directly. To create the certificates, issues the following - commands.</para> + <filename + class="directory">/usr/local/etc/openldap/private</filename> + directory. This is important as the file permissions will + need to be restrictive and users should not have access to + these files directly. To create the certificates, issues the + following commands.</para> <screen>&prompt.root; <userinput>openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt</userinput></screen> @@ -2800,9 +2464,9 @@ TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting> <para>There will be a prompt for entering the password and, if the process does not fail, a password hash will be added - to the end of <filename>slapd.conf</filename>. The + to the end of <filename>slapd.conf</filename>. <command>slappasswd</command> understands several hashing - formats, refer to the manual page for more information.</para> + formats, refer to its manual page for more information.</para> <para>Edit <filename>/usr/local/etc/openldap/slapd.conf</filename> and @@ -2944,6 +2608,7 @@ result: 0 Success </sect1> <sect1 id="network-dhcp"> + <!-- <sect1info> <authorgroup> <author> @@ -2953,478 +2618,372 @@ result: 0 Success </author> </authorgroup> </sect1info> - <title>Automatic Network Configuration (DHCP)</title> - - <sect2> - <title>What Is DHCP?</title> + --> + <title>Dynamic Host Configuration Protocol + (<acronym>DHCP</acronym>)</title> - <indexterm> - <primary>Dynamic Host Configuration Protocol</primary> - <see>DHCP</see> - </indexterm> - <indexterm> - <primary>Internet Systems Consortium (ISC)</primary> - </indexterm> - - <para>DHCP, the Dynamic Host Configuration Protocol, describes - the means by which a system can connect to a network and - obtain the necessary information for communication upon that - network. FreeBSD uses the OpenBSD <command>dhclient</command> - taken from OpenBSD 3.7. All information here regarding - <command>dhclient</command> is for use with either of the ISC - or OpenBSD DHCP clients. The DHCP server is the one included - in the ISC distribution.</para> - </sect2> - - <sect2> - <title>What This Section Covers</title> - - <para>This section describes both the client-side components of - the ISC and OpenBSD DHCP client and server-side components of - the ISC DHCP system. The client-side program, - <command>dhclient</command>, comes integrated within FreeBSD, - and the server-side portion is available from the <filename - role="package">net/isc-dhcp42-server</filename> port. The - &man.dhclient.8;, &man.dhcp-options.5;, and - &man.dhclient.conf.5; manual pages, in addition to the - references below, are useful resources.</para> - </sect2> - - <sect2> - <title>How It Works</title> + <indexterm> + <primary>Dynamic Host Configuration Protocol</primary> + <see><acronym>DHCP</acronym></see> + </indexterm> + <indexterm> + <primary>Internet Systems Consortium (ISC)</primary> + </indexterm> - <indexterm><primary>UDP</primary></indexterm> - <para>When <command>dhclient</command>, the DHCP client, is - executed on the client machine, it begins broadcasting - requests for configuration information. By default, these - requests are on UDP port 68. The server replies on UDP 67, - giving the client an IP address and other relevant network - information such as netmask, router, and DNS servers. All of - this information comes in the form of a DHCP - <quote>lease</quote> and is only valid for a certain time - (configured by the DHCP server maintainer). In this manner, - stale IP addresses for clients no longer connected to the - network can be automatically reclaimed.</para> - - <para>DHCP clients can obtain a great deal of information from - the server. An exhaustive list may be found in - &man.dhcp-options.5;.</para> - </sect2> + <para>The Dynamic Host Configuration Protocol + (<acronym>DHCP</acronym>) allows a system to connect to a + network in order to be assigned the necessary addressing + information for communication on that network. &os; includes + the OpenBSD version of <command>dhclient</command> which is used + by the client to obtain the addressing information. &os; does + not install a <acronym>DHCP</acronym> server, but several + servers are available in the &os; Ports Collection. The + <acronym>DHCP</acronym> protocol is fully described in <ulink + url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>. + Informational resources are also available at <ulink + url="http://www.isc.org/downloads/dhcp/">isc.org/downloads/dhcp/</ulink>.</para> + + <para>This section describes how to use the built-in + <acronym>DHCP</acronym> client. It then describes how to + install and configure a <acronym>DHCP</acronym> server.</para> + + <note> + <para>In &os;, the &man.bpf.4; device is needed by both the + <acronym>DHCP</acronym> server and <acronym>DHCP</acronym> + client. This device is included in the + <filename>GENERIC</filename> kernel that is installed with + &os;. Users who prefer to create a custom kernel need to keep + this device if <acronym>DHCP</acronym> is used.</para> + + <para>It should be noted that <devicename>bpf</devicename> also + allows privileged users to run network packet sniffers on + that system.</para> + </note> <sect2> - <title>FreeBSD Integration</title> - - <para>&os; fully integrates the OpenBSD DHCP client, - <command>dhclient</command>. DHCP client support is provided - within both the installer and the base system, obviating the - need for detailed knowledge of network configurations on any - network that runs a DHCP server.</para> + <title>Configuring a <acronym>DHCP</acronym> Client</title> + + <para><acronym>DHCP</acronym> client support is included in the + &os; installer, making it easy to configure a newly installed + system to automatically receive its networking addressing + information from an existing <acronym>DHCP</acronym> server. + Refer to <xref linkend="bsdinstall-post"/> for examples of + network configuration.</para> + + <indexterm><primary><acronym>UDP</acronym></primary></indexterm> + <para>When <command>dhclient</command> is executed on the client + machine, it begins broadcasting requests for configuration + information. By default, these requests use + <acronym>UDP</acronym> port 68. The server replies on + <acronym>UDP</acronym> port 67, giving the client an + <acronym>IP</acronym> address and other relevant network + information such as a subnet mask, default gateway, and + <acronym>DNS</acronym> server addresses. This information is + in the form of a <acronym>DHCP</acronym> + <quote>lease</quote> and is valid for a configurable time. + This allows stale <acronym>IP</acronym> addresses for clients + no longer connected to the network to automatically be reused. + <acronym>DHCP</acronym> clients can obtain a great deal of + information from the server. An exhaustive list may be found + in &man.dhcp-options.5;.</para> + + <para>By default, when a &os; system boots, its + <acronym>DHCP</acronym> client runs in the background, or + <firstterm>asynchronously</firstterm>. Other startup scripts + continue to run while the <acronym>DHCP</acronym> process + completes, which speeds up system startup.</para> + + <para>Background <acronym>DHCP</acronym> works well when the + <acronym>DHCP</acronym> server responds quickly to the + client's requests. However, <acronym>DHCP</acronym> may take + a long time to complete on some systems. If network services + attempt to run before <acronym>DHCP</acronym> has assigned the + network addressing information, they will fail. Using + <acronym>DHCP</acronym> in <firstterm>synchronous</firstterm> + mode prevents this problem as it pauses startup until the + <acronym>DHCP</acronym> configuration has completed.</para> + + <para>This line in <filename>/etc/rc.conf</filename> is used to + configure background or asynchronous mode:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting> + + <para>This line may already exist if the system was configured + to use <acronym>DHCP</acronym> during installation. Replace + the <replaceable>fxp0</replaceable> shown in these examples + with the name of the interface to be dynamically configured, + as described in <xref linkend="config-network-setup"/>.</para> + + <para>To instead configure the system to use synchronous mode, + and to pause during startup while <acronym>DHCP</acronym> + completes, use + <quote><literal>SYNCDHCP</literal></quote>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="SYNCDHCP"</programlisting> + + <para>Additional client options are available. Search for + <literal>dhclient</literal> in &man.rc.conf.5; for + details.</para> <indexterm> - <primary><application>sysinstall</application></primary> + <primary><acronym>DHCP</acronym></primary> + <secondary>configuration files</secondary> </indexterm> - <para>DHCP is supported by - <application>sysinstall</application>. When configuring a - network interface within - <application>sysinstall</application>, the second question - asked is: <quote>Do you want to try DHCP configuration of - the interface?</quote>. Answering affirmatively will - execute <command>dhclient</command>, and if successful, will - fill in the network configuration information - automatically.</para> - - <para>There are two things required to have the system use - DHCP upon startup:</para> - <indexterm> - <primary>DHCP</primary> - <secondary>requirements</secondary> - </indexterm> - <itemizedlist> - <listitem> - <para>Make sure that the <devicename>bpf</devicename> - device is compiled into the kernel. To do this, add - <literal>device bpf</literal> to the kernel - configuration file, and rebuild the kernel. For more - information about building kernels, see - <xref linkend="kernelconfig"/>.</para> - - <para>The <devicename>bpf</devicename> device is already - part of the <filename>GENERIC</filename> kernel that is - supplied with &os;, thus there is no need to build a - custom kernel for <acronym>DHCP</acronym>. In the case - of a custom kernel configuration file, this device must - be present for <acronym>DHCP</acronym> to function - properly.</para> - - <note> - <para>For those who are particularly security conscious, - take note that <devicename>bpf</devicename> - is also the device that allows packet sniffers to work - correctly (although they still have to be run as - <username>root</username>). - <devicename>bpf</devicename> <emphasis>is</emphasis> - required to use DHCP; however, the security sensitive - types should probably not add - <devicename>bpf</devicename> to the - kernel in the expectation that at some point in the - future the system will be using DHCP.</para> - </note> - </listitem> - - <listitem> - <para>By default, DHCP configuration on &os; runs in the - background, or <firstterm>asynchronously</firstterm>. - Other startup scripts continue to run while DHCP - completes, speeding up system startup.</para> - - <para>Background DHCP works well when the DHCP server - responds quickly to requests and the DHCP configuration - process goes quickly. However, DHCP may take a long - time to complete on some systems. If network services - attempt to run before DHCP has completed, they will - fail. Using DHCP in <firstterm>synchronous</firstterm> - mode prevents the problem, pausing startup until DHCP - configuration has completed.</para> - - <para>To connect to a DHCP server in the background while - other startup continues (asynchronous mode), use the - <quote><literal>DHCP</literal></quote> value in - <filename>/etc/rc.conf</filename>:</para> - - <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting> - - <para>To pause startup while DHCP completes, use - synchronous mode with the - <quote><literal>SYNCDHCP</literal></quote> value:</para> - - <programlisting>ifconfig_<replaceable>fxp0</replaceable>="SYNCDHCP"</programlisting> - - <note> - <para>Replace the <replaceable>fxp0</replaceable> shown - in these examples with the name of the interface to be - dynamically configured, as described in - <xref linkend="config-network-setup"/>.</para> - </note> - - <para>When using a different file system location for - <command>dhclient</command>, or if - additional flags must be passed to - <command>dhclient</command>, - include (editing as necessary):</para> - - <programlisting>dhclient_program="/sbin/dhclient" -dhclient_flags=""</programlisting> - </listitem> - </itemizedlist> - - <indexterm> - <primary>DHCP</primary> - <secondary>server</secondary> - </indexterm> - <para>The DHCP server, <application>dhcpd</application>, is - included as part of the - <filename role="package">net/isc-dhcp42-server</filename> - port in the ports collection. This port contains the ISC - DHCP server and documentation.</para> - </sect2> - - <sect2> - <title>Files</title> - - <indexterm> - <primary>DHCP</primary> - <secondary>configuration files</secondary> - </indexterm> - <itemizedlist> - <listitem> - <para><filename>/etc/dhclient.conf</filename></para> - <para><command>dhclient</command> requires a configuration - file, <filename>/etc/dhclient.conf</filename>. - Typically the file contains only comments, the defaults - being reasonably sane. This configuration file is - described by the &man.dhclient.conf.5; manual - page.</para> - </listitem> + <para>The <acronym>DHCP</acronym> client uses the following + files:</para> - <listitem> - <para><filename>/sbin/dhclient</filename></para> - <para><command>dhclient</command> is statically linked and - resides in <filename>/sbin</filename>. The - &man.dhclient.8; manual page gives more information - about <command>dhclient</command>.</para> - </listitem> + <itemizedlist> + <listitem> + <para><filename>/etc/dhclient.conf</filename></para> - <listitem> - <para><filename>/sbin/dhclient-script</filename></para> - <para><command>dhclient-script</command> is the - FreeBSD-specific DHCP client configuration script. It - is described in &man.dhclient-script.8;, but should not - need any user modification to function properly.</para> - </listitem> + <para>The configuration file used by + <command>dhclient</command>. Typically, this file + contains only comments as the defaults are suitable for + most clients. This configuration file is described in + &man.dhclient.conf.5;.</para> + </listitem> - <listitem> - <para><filename>/var/db/dhclient.leases.<replaceable>interface</replaceable></filename></para> - <para>The DHCP client keeps a database of valid leases - in this file, which is written as a log. - &man.dhclient.leases.5; gives a slightly longer - description.</para> - </listitem> - </itemizedlist> - </sect2> + <listitem> + <para><filename>/sbin/dhclient</filename></para> - <sect2> - <title>Further Reading</title> + <para>More information about the command itself can + be found in &man.dhclient.8;.</para> + </listitem> - <para>The DHCP protocol is fully described in <ulink - url="http://www.freesoft.org/CIE/RFC/2131/">RFC - 2131</ulink>. An informational resource has also been set - up at <ulink url="http://www.dhcp.org/"></ulink>.</para> - </sect2> + <listitem> + <para><filename>/sbin/dhclient-script</filename></para> - <sect2 id="network-dhcp-server"> - <title>Installing and Configuring a DHCP Server</title> + <para>The + &os;-specific <acronym>DHCP</acronym> client configuration + script. It is described in &man.dhclient-script.8;, but + should not need any user modification to function + properly.</para> + </listitem> - <sect3> - <title>What This Section Covers</title> + <listitem> + <para><filename>/var/db/dhclient.leases.<replaceable>interface</replaceable></filename></para> - <para>This section provides information on how to configure - a FreeBSD system to act as a DHCP server using the ISC - (Internet Systems Consortium) implementation of the DHCP - server.</para> + <para>The <acronym>DHCP</acronym> client keeps a database of + valid leases in this file, which is written as a log and + is described in &man.dhclient.leases.5;.</para> + </listitem> + </itemizedlist> + </sect2> - <para>The server is not provided as part of &os;, and so the - <filename role="package">net/isc-dhcp42-server</filename> - port must be installed to provide this service. See - <xref linkend="ports"/> for more information on using the - Ports Collection.</para> - </sect3> + <sect2 id="network-dhcp-server"> + <title>Installing and Configuring a <acronym>DHCP</acronym> + Server</title> - <sect3> - <title>DHCP Server Installation</title> + <para>This section demonstrates how to configure a &os; system + to act as a <acronym>DHCP</acronym> server using the Internet + Systems Consortium (<acronym>ISC</acronym>) implementation of + the <acronym>DHCP</acronym> server. This implementation and + its documentation can be installed using the <filename + role="package">net/isc-dhcp42-server</filename> package or + port.</para> - <indexterm> - <primary>DHCP</primary> - <secondary>installation</secondary> - </indexterm> - <para>In order to configure the &os; system as a DHCP - server, first ensure that the &man.bpf.4; device is - compiled into the kernel. To do this, add - <literal>device bpf</literal> to the kernel configuration - file, and rebuild the kernel. For more information about - building kernels, see - <xref linkend="kernelconfig"/>.</para> - - <para>The <devicename>bpf</devicename> device is already - part of the <filename>GENERIC</filename> kernel that is - supplied with &os;, so there is no need to create a - custom kernel in order to get <acronym>DHCP</acronym> - working.</para> - - <note> - <para>Those who are particularly security conscious - should note that <devicename>bpf</devicename> is also - the device that allows packet sniffers to function - correctly (although such programs still need - privileged access). The <devicename>bpf</devicename> - device <emphasis>is</emphasis> required to use DHCP, but - if the sensitivity of the system's security is high, - this device should not be included in the kernel purely - because the use of <acronym>DHCP</acronym> may, at some - point in the future, be desired.</para> - </note> + <indexterm> + <primary><acronym>DHCP</acronym></primary> + <secondary>server</secondary> + </indexterm> - <para>The next thing that is needed is to edit the - sample <filename>dhcpd.conf</filename> which was installed - by the <filename - role="package">net/isc-dhcp42-server</filename> port. - By default, this will be - <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and - you should copy this to - <filename>/usr/local/etc/dhcpd.conf</filename> before - proceeding to make changes.</para> - </sect3> + <indexterm> + <primary><acronym>DHCP</acronym></primary> + <secondary>installation</secondary> + </indexterm> - <sect3> - <title>Configuring the DHCP Server</title> + <para>The installation of <filename + role="package">net/isc-dhcp42-server</filename> installs a + sample configuration file. Copy + <filename>/usr/local/etc/dhcpd.conf.example</filename> to + <filename>/usr/local/etc/dhcpd.conf</filename> and make any + edits to this new file.</para> - <indexterm> - <primary>DHCP</primary> - <secondary>dhcpd.conf</secondary> - </indexterm> - <para><filename>dhcpd.conf</filename> is comprised of - declarations regarding subnets and hosts, and is perhaps - most easily explained using an example :</para> + <indexterm> + <primary><acronym>DHCP</acronym></primary> + <secondary>dhcpd.conf</secondary> + </indexterm> + <para>The configuration file is comprised of declarations for + subnets and hosts which define the information that is + provided to <acronym>DHCP</acronym> clients. For example, + these lines configure the following:</para> - <programlisting>option domain-name "example.com";<co id="domain-name"/> -option domain-name-servers 192.168.4.100;<co id="domain-name-servers"/> + <programlisting>option domain-name "example.org";<co id="domain-name"/> +option domain-name-servers ns1.example.org;<co id="domain-name-servers"/> option subnet-mask 255.255.255.0;<co id="subnet-mask"/> -default-lease-time 3600;<co id="default-lease-time"/> -max-lease-time 86400;<co id="max-lease-time"/> +default-lease-time 600;<co id="default-lease-time"/> +max-lease-time 72400;<co id="max-lease-time"/> ddns-update-style none;<co id="ddns-update-style"/> -subnet 192.168.4.0 netmask 255.255.255.0 { - range 192.168.4.129 192.168.4.254;<co id="range"/> - option routers 192.168.4.1;<co id="routers"/> +subnet 10.254.239.0 netmask 255.255.255.224 { + range 10.254.239.10 10.254.239.20;<co id="range"/> + option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co id="routers"/> } -host mailhost { - hardware ethernet 02:03:04:05:06:07;<co id="hardware"/> - fixed-address mailhost.example.com;<co id="fixed-address"/> +host fantasia { + hardware ethernet 08:00:07:26:c0:a5;<co id="hardware"/> + fixed-address fantasia.fugue.com;<co id="fixed-address"/> }</programlisting> <calloutlist> <callout arearefs="domain-name"> - <para>This option specifies the domain that will be - provided to clients as the default search domain. See - &man.resolv.conf.5; for more information on what this - means.</para> + <para>This option specifies the default search domain that + will be provided to clients. Refer to + &man.resolv.conf.5; for more information.</para> </callout> <callout arearefs="domain-name-servers"> <para>This option specifies a comma separated list of - DNS servers that the client should use.</para> + <acronym>DNS</acronym> servers that the client should + use. They can be listed by their Fully Qualified Domain + Names (<acronym>FQDN</acronym>), as seen in the example, + or by their <acronym>IP</acronym> addresses.</para> </callout> <callout arearefs="subnet-mask"> - <para>The netmask that will be provided to + <para>The subnet mask that will be provided to clients.</para> </callout> <callout arearefs="default-lease-time"> - <para>A client may request a specific length of time - that a lease will be valid. Otherwise the server will - assign a lease with this expiry value (in - seconds).</para> + <para>The default lease expiry time in seconds. A client + can be configured to override this value. </para> </callout> <callout arearefs="max-lease-time"> - <para>This is the maximum length of time that the server - will lease for. Should a client request a longer - lease, a lease will be issued, although it will only - be valid for <literal>max-lease-time</literal> - seconds.</para> + <para>The maximum allowed length of time, in seconds, for + a lease. Should a client request a longer lease, a + lease will still be issued, but it will only be valid + for <literal>max-lease-time</literal>.</para> </callout> <callout arearefs="ddns-update-style"> - <para>This option specifies whether the DHCP server - should attempt to update DNS when a lease is accepted - or released. In the ISC implementation, this option - is <emphasis>required</emphasis>.</para> + <para>The default of <option>none</option> disables + dynamic DNS updates. Changing this to + <option>interim</option> configures the + <acronym>DHCP</acronym> server to update a + <acronym>DNS</acronym> server whenever it hands out a + lease so that the <acronym>DNS</acronym> server knows + which <acronym>IP</acronym> addresses are associated + with which computers in the network. Do not change the + default setting unless the <acronym>DNS</acronym> server + has been configured to support dynamic + <acronym>DNS</acronym>.</para> </callout> <callout arearefs="range"> - <para>This denotes which IP addresses should be used in - the pool reserved for allocating to clients. IP - addresses between, and including, the ones stated are - handed out to clients.</para> + <para>This line creates a pool of available + <acronym>IP</acronym> addresses which are reserved for + allocation to <acronym>DHCP</acronym> clients. The + range of addresses must be valid for the network or + subnet specified in the previous line.</para> </callout> <callout arearefs="routers"> - <para>Declares the default gateway that will be provided - to clients.</para> + <para>Declares the default gateway that is valid for the + network or subnet specified before the opening + <literal>{</literal> bracket.</para> </callout> <callout arearefs="hardware"> - <para>The hardware MAC address of a host (so that the - DHCP server can recognize a host when it makes a - request).</para> + <para>Specifies the hardware <acronym>MAC</acronym> + address of a client so that the + <acronym>DHCP</acronym> server can recognize the client + when it makes a request.</para> </callout> <callout arearefs="fixed-address"> - <para>Specifies that the host should always be given the - same IP address. Note that using a hostname is - correct here, since the DHCP server will resolve the - hostname itself before returning the lease + <para>Specifies that this host should always be given the + same <acronym>IP</acronym> address. Using the hostname + is correct, since the <acronym>DHCP</acronym> server + will resolve the hostname before returning the lease information.</para> </callout> </calloutlist> + <para>This configuration file supports many more options. + Refer to dhcpd.conf(5), installed with the server, for + details and examples.</para> + <para>Once the configuration of - <filename>dhcpd.conf</filename> has been completed, - enable the DHCP server in - <filename>/etc/rc.conf</filename>, i.e., by adding:</para> + <filename>dhcpd.conf</filename> is complete, enable the + <acronym>DHCP</acronym> server in + <filename>/etc/rc.conf</filename>:</para> <programlisting>dhcpd_enable="YES" dhcpd_ifaces="dc0"</programlisting> - <para>Replace the <literal>dc0</literal> interface name with + <para>Replace the <literal>dc0</literal> with the interface (or interfaces, separated by whitespace) - that the DHCP server should listen on for DHCP client - requests.</para> + that the <acronym>DHCP</acronym> server should listen on for + <acronym>DHCP</acronym> client requests.</para> - <para>Proceed to start the server by issuing + <para>Start the server by issuing the following command:</para> <screen>&prompt.root; <userinput>service isc-dhcpd start</userinput></screen> - <para>Any future changes to the configuration - of the server will require the sending of a - <literal>SIGTERM</literal> signal to - <application>dhcpd</application> rather than a - <literal>SIGHUP</literal>. It is definitely more - simple to use &man.service.8; to completely restart - the service.</para> - </sect3> + <para>Any future changes to the configuration of the server + will require the <application>dhcpd</application> service to + be stopped and then started using &man.service.8;.</para> - <sect3> - <title>Files</title> + <para>The <acronym>DHCP</acronym> server uses the following + files. Note that the manual pages are installed with the + server software.</para> <indexterm> - <primary>DHCP</primary> + <primary><acronym>DHCP</acronym></primary> <secondary>configuration files</secondary> </indexterm> <itemizedlist> <listitem> <para><filename>/usr/local/sbin/dhcpd</filename></para> - <para><application>dhcpd</application> is statically - linked and resides in - <filename>/usr/local/sbin</filename>. The - &man.dhcpd.8; manual page installed with the port - gives more information about - <application>dhcpd</application>.</para> + + <para>More + information about the + <application>dhcpd</application> server can be found in + dhcpd(8).</para> </listitem> <listitem> <para><filename>/usr/local/etc/dhcpd.conf</filename></para> - <para><application>dhcpd</application> requires a - configuration file, - <filename>/usr/local/etc/dhcpd.conf</filename> before - it will start providing service to clients. This file - needs to contain all the information that should be - provided to clients that are being serviced, along - with information regarding the operation of the - server. This configuration file is described - by the &man.dhcpd.conf.5; manual page installed - by the port.</para> + + <para>The server configuration file needs to contain all + the information that should be provided to clients, + along with information regarding the operation of the + server. This configuration file is described in + dhcpd.conf(5).</para> </listitem> <listitem> <para><filename>/var/db/dhcpd.leases</filename></para> - <para>The DHCP server keeps a database of leases it has - issued in this file, which is written as a log. The - manual page &man.dhcpd.leases.5;, installed by the - port gives a slightly longer description.</para> + + <para>The <acronym>DHCP</acronym> server keeps a database + of leases it has issued in this file, which is written + as a log. Refer to dhcpd.leases(5), which gives a + slightly longer description.</para> </listitem> <listitem> <para><filename>/usr/local/sbin/dhcrelay</filename></para> - <para><application>dhcrelay</application> is used in - advanced environments where one DHCP server forwards a - request from a client to another DHCP server on a - separate network. If this functionality is required, - then install the <filename - role="package">net/isc-dhcp42-relay</filename> port. - The &man.dhcrelay.8; manual page provided with the - port contains more detail.</para> + + <para>This daemon is used in advanced environments where + one <acronym>DHCP</acronym> server forwards a request + from a client to another <acronym>DHCP</acronym> server + on a separate network. If this functionality is + required, install the <filename + role="package">net/isc-dhcp42-relay</filename> + package or port. The installation includes dhcrelay(8) + which provides more detail.</para> </listitem> </itemizedlist> - </sect3> </sect2> </sect1> <sect1 id="network-dns"> + <!-- <sect1info> <authorgroup> <author> @@ -3444,168 +3003,146 @@ dhcpd_ifaces="dc0"</programlisting> </author> </authorgroup> </sect1info> + --> <title>Domain Name System (<acronym>DNS</acronym>)</title> - <sect2> - <title>Overview</title> - - <indexterm><primary>BIND</primary></indexterm> - - <para>&os; utilizes, by default, a version of BIND (Berkeley - Internet Name Domain), which is the most common implementation - of the <acronym>DNS</acronym> protocol. - <acronym>DNS</acronym> is the protocol through which names are - mapped to <acronym>IP</acronym> addresses, and vice versa. - For example, a query for <hostid - role="fqdn">www.FreeBSD.org</hostid> will receive a reply - with the <acronym>IP</acronym> address of The &os; Project's - web server, whereas, a query for <hostid - role="fqdn">ftp.FreeBSD.org</hostid> will return the - <acronym>IP</acronym> address of the corresponding - <acronym>FTP</acronym> machine. Likewise, the opposite can - happen. A query for an <acronym>IP</acronym> address can - resolve its hostname. It is not necessary to run a name - server to perform <acronym>DNS</acronym> lookups on a - system.</para> - - <para>&os; currently comes with <acronym>BIND</acronym>9 - <acronym>DNS</acronym> server software by default. Our - installation provides enhanced security features, a new file - system layout and automated &man.chroot.8; - configuration.</para> - - <indexterm><primary>DNS</primary></indexterm> - <para><acronym>DNS</acronym> is coordinated across the Internet - through a somewhat complex system of authoritative root, Top - Level Domain (<acronym>TLD</acronym>), and other smaller-scale - name servers which host and cache individual domain - information.</para> - - <para>Currently, BIND is maintained by the - Internet Systems Consortium - <ulink url="https://www.isc.org/"></ulink>.</para> - </sect2> - - <sect2> - <title>Terminology</title> - - <para>To understand this document, some terms related to - <acronym>DNS</acronym> must be understood.</para> - - <indexterm><primary>resolver</primary></indexterm> - <indexterm><primary>reverse DNS</primary></indexterm> - <indexterm><primary>root zone</primary></indexterm> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <colspec colwidth="1*"/> - <colspec colwidth="3*"/> - - <thead> - <row> - <entry>Term</entry> - <entry>Definition</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Forward <acronym>DNS</acronym></entry> - <entry>Mapping of hostnames to IP addresses.</entry> - </row> - - <row> - <entry>Origin</entry> - <entry>Refers to the domain covered in a particular zone - file.</entry> - </row> - - <row> - <entry><application>named</application>, BIND</entry> - <entry>Common names for the BIND name server package - within &os;.</entry> - </row> - - <row> - <entry>Resolver</entry> - <entry>A system process through which a machine queries - a name server for zone information.</entry> - </row> - - <row> - <entry>Reverse <acronym>DNS</acronym></entry> - <entry>Mapping of <acronym>IP</acronym> addresses to - hostnames.</entry> - </row> - - <row> - <entry>Root zone</entry> - - <entry>The beginning of the Internet zone hierarchy. - All zones fall under the root zone, similar to how - all files in a file system fall under the root - directory.</entry> - </row> - - <row> - <entry>Zone</entry> - <entry>An individual domain, subdomain, or portion of - the <acronym>DNS</acronym> administered by the same - authority.</entry> - </row> - </tbody> - </tgroup> - </informaltable> + <indexterm><primary>BIND</primary></indexterm> + + <para>Domain Name System (<acronym>DNS</acronym>) is the protocol + through which domain names are mapped to <acronym>IP</acronym> + addresses, and vice versa. By default, &os; installs the + Berkeley Internet Name Domain (<acronym>BIND</acronym>), which + is the most common implementation of the <acronym>DNS</acronym> + protocol. The &os; version provides enhanced security features, + a new file system layout, and automated &man.chroot.8; + configuration. BIND is maintained by the <ulink + url="https://www.isc.org/">isc.org</ulink>. It is not + necessary to run a name server to perform <acronym>DNS</acronym> + lookups on a system.</para> + + <indexterm><primary>DNS</primary></indexterm> + <para><acronym>DNS</acronym> is coordinated across the Internet + through a somewhat complex system of authoritative root, Top + Level Domain (<acronym>TLD</acronym>), and other smaller-scale + name servers, which host and cache individual domain + information. Table 28.4 describes some of the terms associated + with <acronym>DNS</acronym>:</para> + + <indexterm><primary>resolver</primary></indexterm> + <indexterm><primary>reverse + <acronym>DNS</acronym></primary></indexterm> + <indexterm><primary>root zone</primary></indexterm> + + <table frame="none" pgwide="1"> + <title><acronym>DNS</acronym> Terminology</title> + + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="3*"/> + + <thead> + <row> + <entry>Term</entry> + <entry>Definition</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Forward <acronym>DNS</acronym></entry> + <entry>Mapping of hostnames to <acronym>IP</acronym> + addresses.</entry> + </row> + + <row> + <entry>Origin</entry> + <entry>Refers to the domain covered in a particular zone + file.</entry> + </row> + + <row> + <entry><application>named</application>, BIND</entry> + <entry>Common names for the BIND name server package + within &os;.</entry> + </row> + + <row> + <entry>Resolver</entry> + <entry>A system process through which a machine queries + a name server for zone information.</entry> + </row> + + <row> + <entry>Reverse <acronym>DNS</acronym></entry> + <entry>Mapping of <acronym>IP</acronym> addresses to + hostnames.</entry> + </row> + + <row> + <entry>Root zone</entry> + + <entry>The beginning of the Internet zone hierarchy. All + zones fall under the root zone, similar to how all files + in a file system fall under the root directory.</entry> + </row> + + <row> + <entry>Zone</entry> + <entry>An individual domain, subdomain, or portion of the + <acronym>DNS</acronym> administered by the same + authority.</entry> + </row> + </tbody> + </tgroup> + </table> - <indexterm> - <primary>zones</primary> - <secondary>examples</secondary> - </indexterm> + <indexterm> + <primary>zones</primary> + <secondary>examples</secondary> + </indexterm> - <para>Examples of zones:</para> + <para>Examples of zones:</para> - <itemizedlist> - <listitem> - <para><hostid>.</hostid> is how the root zone is usually - referred to in documentation.</para> - </listitem> + <itemizedlist> + <listitem> + <para><hostid>.</hostid> is how the root zone is usually + referred to in documentation.</para> + </listitem> - <listitem> - <para><hostid>org.</hostid> is a Top Level Domain - (<acronym>TLD</acronym>) under the root zone.</para> - </listitem> + <listitem> + <para><hostid>org.</hostid> is a Top Level Domain + (<acronym>TLD</acronym>) under the root zone.</para> + </listitem> - <listitem> - <para><hostid role="domainname">example.org.</hostid> is a - zone under the <hostid>org.</hostid> - <acronym>TLD</acronym>.</para> - </listitem> + <listitem> + <para><hostid role="domainname">example.org.</hostid> is a + zone under the <hostid>org.</hostid> + <acronym>TLD</acronym>.</para> + </listitem> - <listitem> - <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone - referencing all <acronym>IP</acronym> addresses which fall - under the <hostid role="ipaddr">192.168.1.*</hostid> - <acronym>IP</acronym> address space.</para> - </listitem> - </itemizedlist> + <listitem> + <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone + referencing all <acronym>IP</acronym> addresses which fall + under the <hostid role="ipaddr">192.168.1.*</hostid> + <acronym>IP</acronym> address space.</para> + </listitem> + </itemizedlist> - <para>As one can see, the more specific part of a hostname - appears to its left. For example, <hostid - role="domainname">example.org.</hostid> is more specific - than <hostid>org.</hostid>, as <hostid>org.</hostid> is more - specific than the root zone. The layout of each part of a - hostname is - much like a file system: the - <filename class="directory">/dev</filename> directory falls - within the root, and so on.</para> - </sect2> + <para>As one can see, the more specific part of a hostname + appears to its left. For example, <hostid + role="domainname">example.org.</hostid> is more specific than + <hostid>org.</hostid>, as <hostid>org.</hostid> is more specific + than the root zone. The layout of each part of a hostname is + much like a file system: the <filename + class="directory">/dev</filename> directory falls within the + root, and so on.</para> <sect2> <title>Reasons to Run a Name Server</title> <para>Name servers generally come in two forms: authoritative - name servers, and caching (also known as resolving) - name servers.</para> + name servers, and caching (also known as resolving) name + servers.</para> <para>An authoritative name server is needed when:</para> @@ -3616,10 +3153,10 @@ dhcpd_ifaces="dc0"</programlisting> </listitem> <listitem> - <para>A domain, such as <hostid - role="domainname">example.org</hostid>, is registered - and <acronym>IP</acronym> addresses need to be assigned - to hostnames under it.</para> + <para>A domain, such as + <hostid role="domainname">example.org</hostid>, is + registered and <acronym>IP</acronym> addresses need to be + assigned to hostnames under it.</para> </listitem> <listitem> @@ -3733,13 +3270,13 @@ dhcpd_ifaces="dc0"</programlisting> <programlisting>named_enable="YES"</programlisting> - <para>There are obviously many configuration options for + <para>There are many configuration options for <filename>/etc/namedb/named.conf</filename> that are beyond - the scope of this document. There are other startup options - for <application>named</application> on &os;, take a look at + the scope of this document. Other startup options + for <application>named</application> on &os; can be found in the <literal>named_<replaceable>*</replaceable></literal> - flags in <filename>/etc/defaults/rc.conf</filename> and - consult the &man.rc.conf.5; manual page. The + flags in <filename>/etc/defaults/rc.conf</filename> and in + &man.rc.conf.5;. The <xref linkend="configtuning-rcd"/> section is also a good read.</para> </sect2> @@ -3836,7 +3373,7 @@ options { </warning> <programlisting> /* - Modern versions of BIND use a random UDP port for each outgoing + Modern versions of BIND use a random <acronym>UDP</acronym> port for each outgoing query by default in order to dramatically reduce the possibility of cache poisoning. All users are strongly encouraged to utilize this feature, and to configure their firewalls to accommodate it. @@ -4161,11 +3698,12 @@ www IN CNAME example.org.</programlisting> <programlisting>recordname IN recordtype value</programlisting> <indexterm> - <primary>DNS</primary> + <primary><acronym>DNS</acronym></primary> <secondary>records</secondary> </indexterm> - <para>The most commonly used DNS records:</para> + <para>The most commonly used <acronym>DNS</acronym> + records:</para> <variablelist> <varlistentry> @@ -4205,7 +3743,7 @@ www IN CNAME example.org.</programlisting> <listitem> <para>a domain name pointer (used in reverse - DNS)</para> + <acronym>DNS</acronym>)</para> </listitem> </varlistentry> </variablelist> @@ -4220,7 +3758,7 @@ www IN CNAME example.org.</programlisting> <variablelist> <varlistentry> <term><hostid - role="domainname">example.org.</hostid></term> + role="domainname">example.org.</hostid></term> <listitem> <para>the domain name, also the origin for this @@ -4252,16 +3790,16 @@ www IN CNAME example.org.</programlisting> <term><literal>2006051501</literal></term> <listitem> - <para>the serial number of the file. This - must be incremented each time the zone file is - modified. Nowadays, many admins prefer a + <para>the serial number of the file. This must be + incremented each time the zone file is modified. + Nowadays, many admins prefer a <literal>yyyymmddrr</literal> format for the serial - number. <literal>2006051501</literal> would mean - last modified 05/15/2006, the latter - <literal>01</literal> being the first time the zone - file has been modified this day. The serial number - is important as it alerts slave name servers for a - zone when it is updated.</para> + number. <literal>2006051501</literal> would mean last + modified 05/15/2006, the latter <literal>01</literal> + being the first time the zone file has been modified + this day. The serial number is important as it alerts + slave name servers for a zone when it is + updated.</para> </listitem> </varlistentry> </variablelist> @@ -4284,7 +3822,7 @@ mail IN A 192.168.1.5</programlisting> <programlisting> IN A 192.168.1.1</programlisting> - <para>This line assigns IP address + <para>This line assigns <acronym>IP</acronym> address <hostid role="ipaddr">192.168.1.1</hostid> to the current origin, in this case <hostid role="domainname">example.org</hostid>.</para> @@ -4319,9 +3857,9 @@ mail IN A 192.168.1.5</programlisting> priority number), then the second highest, etc, until the mail can be properly delivered.</para> - <para>For in-addr.arpa zone files (reverse DNS), the same - format is used, except with PTR entries instead of A or - CNAME.</para> + <para>For in-addr.arpa zone files (reverse + <acronym>DNS</acronym>), the same format is used, except + with PTR entries instead of A or CNAME.</para> <programlisting>$TTL 3600 @@ -4341,8 +3879,8 @@ mail IN A 192.168.1.5</programlisting> 4 IN PTR mx.example.org. 5 IN PTR mail.example.org.</programlisting> - <para>This file gives the proper IP address to hostname - mappings for the above fictitious domain.</para> + <para>This file gives the proper <acronym>IP</acronym> address + to hostname mappings for the above fictitious domain.</para> <para>It is worth noting that all names on the right side of a PTR record need to be fully qualified (i.e., end in @@ -4370,16 +3908,17 @@ mail IN A 192.168.1.5</programlisting> <indexterm> <primary>BIND</primary> - <secondary>DNS security extensions</secondary> + <secondary><acronym>DNS</acronym> security + extensions</secondary> </indexterm> <para>Domain Name System Security Extensions, or <acronym - role="Domain Name Security Extensions">DNSSEC</acronym> - for short, is a suite of specifications to protect resolving - name servers from forged <acronym>DNS</acronym> data, such - as spoofed <acronym>DNS</acronym> records. By using digital - signatures, a resolver can verify the integrity of the - record. Note that <acronym role="Domain Name Security + role="Domain Name Security Extensions">DNSSEC</acronym> for + short, is a suite of specifications to protect resolving name + servers from forged <acronym>DNS</acronym> data, such as + spoofed <acronym>DNS</acronym> records. By using digital + signatures, a resolver can verify the integrity of the record. + Note that <acronym role="Domain Name Security Extensions">DNSSEC</acronym> only provides integrity via digitally signing the Resource Records (<acronym role="Resource Record">RR</acronym>s). It provides neither @@ -4471,7 +4010,7 @@ mail IN A 192.168.1.5</programlisting> file containing these <acronym role="Resource Record">RR</acronym>s with</para> - <screen>&prompt.user; <userinput>dnssec-dsfromkey -f root-dnskey . > root.ds</userinput></screen> + <screen>&prompt.user; <userinput>dnssec-dsfromkey -f root.dnskey . > root.ds</userinput></screen> <para>These records use SHA-1 and SHA-256 respectively, and should look similar to the following example, where the @@ -4735,9 +4274,10 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <sect2> <title>Security</title> - <para>Although BIND is the most common implementation of DNS, - there is always the issue of security. Possible and - exploitable security holes are sometimes found.</para> + <para>Although BIND is the most common implementation of + <acronym>DNS</acronym>, there is always the issue of security. + Possible and exploitable security holes are sometimes + found.</para> <para>While &os; automatically drops <application>named</application> into a &man.chroot.8; @@ -4781,7 +4321,8 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <listitem> <para><ulink url="http://www.oreilly.com/catalog/dns5/">O'Reilly - DNS and BIND 5th Edition</ulink></para> + <acronym>DNS</acronym> and BIND 5th + Edition</ulink></para> </listitem> <listitem> @@ -4813,22 +4354,22 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <listitem> <para><ulink url="http://tools.ietf.org/html/rfc4033">RFC4033 - - DNS Security Introduction and + - <acronym>DNS</acronym> Security Introduction and Requirements</ulink></para> </listitem> <listitem> <para><ulink url="http://tools.ietf.org/html/rfc4034">RFC4034 - - Resource Records for the DNS Security - Extensions</ulink></para> + - Resource Records for the <acronym>DNS</acronym> + Security Extensions</ulink></para> </listitem> <listitem> <para><ulink url="http://tools.ietf.org/html/rfc4035">RFC4035 - - Protocol Modifications for the DNS Security - Extensions</ulink></para> + - Protocol Modifications for the <acronym>DNS</acronym> + Security Extensions</ulink></para> </listitem> <listitem> @@ -4840,7 +4381,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <listitem> <para><ulink url="http://tools.ietf.org/html/rfc5011">RFC 5011 - - Automated Updates of DNS Security + - Automated Updates of <acronym>DNS</acronym> Security (<acronym>DNSSEC</acronym> Trust Anchors</ulink></para> </listitem> @@ -4849,6 +4390,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> </sect1> <sect1 id="network-apache"> + <!-- <sect1info> <authorgroup> <author> @@ -4858,66 +4400,53 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> </author> </authorgroup> </sect1info> + --> <title>Apache HTTP Server</title> <indexterm><primary>web servers</primary> <secondary>setting up</secondary></indexterm> <indexterm><primary>Apache</primary></indexterm> - <sect2> - <title>Overview</title> - - <para>&os; is used to run some of the busiest web sites in the - world. The majority of web servers on the Internet are using - the <application>Apache HTTP Server</application>. - <application>Apache</application> software packages should be - included on the &os; installation media. If - <application>Apache</application> was not installed while - installing &os;, then it can be installed from the - <filename role="package">www/apache22</filename> port.</para> + <para>The open source <application>Apache HTTP Server + </application> is the most widely used web server. &os; does + not install this web server by default, but it can be installed + from the <filename + role="package">www/apache24</filename> package or port.</para> - <para>Once <application>Apache</application> has been installed - successfully, it must be configured.</para> - - <note> - <para>This section covers version 2.2.X of the - <application>Apache HTTP Server</application> as that is the - most widely used version for &os;. For more detailed - information beyond the scope of this document about - <application>Apache</application> 2.X, please see - <ulink url="http://httpd.apache.org/"></ulink>.</para> - </note> - </sect2> + <para>This section summarizes how to configure and start version + 2.<replaceable>x</replaceable> of the <application>Apache HTTP + Server</application>, the most widely used version, on &os;. + For more detailed information about + <application>Apache</application> 2.X and its configuration + directives, refer to <ulink + url="http://httpd.apache.org/">httpd.apache.org</ulink>.</para> <sect2> - <title>Configuration</title> + <title>Configuring and Starting Apache</title> <indexterm><primary>Apache</primary> <secondary>configuration file</secondary></indexterm> - <para>The main <application>Apache HTTP Server</application> - configuration file is installed as - <filename>/usr/local/etc/apache22/httpd.conf</filename> on - &os;. This file is a typical &unix; text configuration file - with comment lines beginning with the <literal>#</literal> - character. A comprehensive description of all possible - configuration options is outside the scope of this book, so - only the most frequently modified directives will be described - here.</para> + <para>In &os;, the main <application>Apache HTTP + Server</application> configuration file is installed as + <filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>. + This ASCII text file begins comment lines with the + <literal>#</literal>. The most frequently modified directives + are:</para> <variablelist> <varlistentry> <term><literal>ServerRoot "/usr/local"</literal></term> <listitem> - <para>This specifies the default directory hierarchy for - the <application>Apache</application> installation. + <para>Specifies the default directory hierarchy for the + <application>Apache</application> installation. Binaries are stored in the <filename class="directory">bin</filename> and <filename class="directory">sbin</filename> subdirectories of the server root, and configuration files are stored in <filename - class="directory">etc/apache</filename>.</para> + class="directory">etc/apache2<replaceable>x</replaceable></filename>.</para> </listitem> </varlistentry> @@ -4925,8 +4454,8 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <term><literal>ServerAdmin you@your.address</literal></term> <listitem> - <para>The address to which problems with the server should - be emailed. This address also appears on some + <para>The email address to receive problems with the + server. This address also appears on some server-generated pages, such as error documents.</para> </listitem> </varlistentry> @@ -4935,21 +4464,20 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <term><literal>ServerName www.example.com</literal></term> <listitem> - <para><literal>ServerName</literal> allows an + <para>Allows an administrator to set a host name which is sent back to - clients for the server. This is useful if the host is - different than the one that it is configured with (i.e., - use <hostid>www</hostid> instead of the host's real - name).</para> + clients for the server. For example, + <hostid>www</hostid> can be used instead of the actual + host name.</para> </listitem> </varlistentry> <varlistentry> <term><literal>DocumentRoot - "/usr/local/www/apache22/data"</literal></term> + "/usr/local/www/apache2<replaceable>x</replaceable>/data"</literal></term> <listitem> - <para><literal>DocumentRoot</literal>: The directory + <para>The directory where documents will be served from. By default, all requests are taken from this directory, but symbolic links and aliases may be used to point to other @@ -4962,18 +4490,14 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <application>Apache</application> configuration file before making changes. When the configuration of <application>Apache</application>, is complete, save the - file and verify the configuration using &man.apachectl.8;. - To do this, issue <command>apachectl configtest</command> - which should return <literal>Syntax OK</literal>.</para> - </sect2> - - <sect2> - <title>Running <application>Apache</application></title> + file and verify the configuration using apachectl(8). + Running <command>apachectl configtest</command> should return + <literal>Syntax OK</literal>.</para> <indexterm><primary>Apache</primary> <secondary>starting or stopping</secondary></indexterm> - <para>The <filename role="package">www/apache22</filename> port + <para>The <filename role="package">www/apache24</filename> port installs an &man.rc.8; script to aid in starting, stopping, and restarting <application>Apache</application>, which can be found in <filename @@ -4983,22 +4507,23 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> startup, add the following line to <filename>/etc/rc.conf</filename>:</para> - <programlisting>apache22_enable="YES"</programlisting> + <programlisting>apache24_enable="YES"</programlisting> <para>If <application>Apache</application> should be started with non-default options, the following line may be added to - <filename>/etc/rc.conf</filename>:</para> + <filename>/etc/rc.conf</filename> to specify the needed + flags:</para> - <programlisting>apache22_flags=""</programlisting> + <programlisting>apache24_flags=""</programlisting> <para>The <application>Apache</application> configuration can be - tested for errors after making subsequent - configuration changes while <command>httpd</command> is - running. This can be done by the &man.rc.8; script directly, - or by the &man.service.8; utility by issuing one of the - following commands:</para> + tested for errors after making subsequent configuration + changes while <command>httpd</command> is running. This can + be done by the &man.rc.8; script directly, or by the + &man.service.8; utility by issuing one of the following + commands:</para> - <screen>&prompt.root; <userinput>service apache22 configtest</userinput></screen> + <screen>&prompt.root; <userinput>service apache24 configtest</userinput></screen> <note> <para>It is important to note that the @@ -5008,11 +4533,10 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> </note> <para>If <application>Apache</application> does not report - configuration errors, the - <application>Apache</application> <command>httpd</command> - can be started with &man.service.8;:</para> + configuration errors, start <command>httpd</command> + with &man.service.8;:</para> - <screen>&prompt.root; <userinput>service apache22 start</userinput></screen> + <screen>&prompt.root; <userinput>service apache24 start</userinput></screen> <para>The <command>httpd</command> service can be tested by entering <literal>http://<hostid @@ -5022,7 +4546,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> domain name of the machine running <command>httpd</command>, if it is not the local machine. The default web page that is displayed is - <filename>/usr/local/www/apache22/data/index.html</filename>.</para> + <filename>/usr/local/www/apache24/data/index.html</filename>.</para> </sect2> <sect2> @@ -5032,7 +4556,8 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> types of Virtual Hosting. The first method is Name-based Virtual Hosting. Name-based virtual hosting uses the clients HTTP/1.1 headers to figure out the hostname. This allows many - different domains to share the same IP address.</para> + different domains to share the same <acronym>IP</acronym> + address.</para> <para>To setup <application>Apache</application> to use Name-based Virtual Hosting add an entry like the following to @@ -5040,10 +4565,10 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <programlisting>NameVirtualHost *</programlisting> - <para>If the webserver was named <hostid - role="fqdn">www.domain.tld</hostid> and - a virtual domain for <hostid - role="fqdn">www.someotherdomain.tld</hostid> then + <para>If the webserver was named + <hostid role="fqdn">www.domain.tld</hostid> and + a virtual domain for + <hostid role="fqdn">www.someotherdomain.tld</hostid> then add the following entries to <filename>httpd.conf</filename>:</para> @@ -5057,8 +4582,8 @@ ServerName www.someotherdomain.tld DocumentRoot /www/someotherdomain.tld </VirtualHost></screen> - <para>Replace the addresses with the addresses needed - and the path to the documents with what are being used.</para> + <para>Replace the addresses with the addresses needed and the + path to the documents with what are being used.</para> <para>For more information about setting up virtual hosts, please consult the official <application>Apache</application> @@ -5074,7 +4599,7 @@ DocumentRoot /www/someotherdomain.tld <para>There are many different <application>Apache</application> modules available to add functionality to the basic server. - The FreeBSD Ports Collection provides an easy way to install + The &os; Ports Collection provides an easy way to install <application>Apache</application> together with some of the more popular add-on modules.</para> @@ -5092,9 +4617,9 @@ DocumentRoot /www/someotherdomain.tld OpenSSL library to provide strong cryptography via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. This module provides - everything necessary to request a signed certificate from - a trusted certificate signing authority to run - a secure web server on &os;.</para> + everything necessary to request a signed certificate from a + trusted certificate signing authority to run a secure web + server on &os;.</para> <para>The <application>mod_ssl</application> module is built by default, but can be enabled by specifying @@ -5227,6 +4752,7 @@ DocumentRoot /www/someotherdomain.tld </sect3> <sect3> + <!-- <sect3info> <authorgroup> <author> @@ -5236,6 +4762,7 @@ DocumentRoot /www/someotherdomain.tld </author> </authorgroup> </sect3info> + --> <title><application>mod_php</application></title> <indexterm> @@ -5243,18 +4770,17 @@ DocumentRoot /www/someotherdomain.tld <secondary>PHP</secondary> </indexterm> - <para><acronym>PHP</acronym>, also known as <quote>PHP: - Hypertext Preprocessor</quote> is a general-purpose - scripting language that is especially suited for Web - development. Capable of being embedded into - <acronym>HTML</acronym> its syntax draws upon C, &java;, - and Perl with the intention of allowing web developers to - write dynamically generated webpages quickly.</para> + <para><acronym>PHP</acronym>, also known as + <quote>PHP: Hypertext Preprocessor</quote> is a + general-purpose scripting language that is especially suited + for Web development. Capable of being embedded into + <acronym>HTML</acronym> its syntax draws upon C, &java;, and + Perl with the intention of allowing web developers to write + dynamically generated webpages quickly.</para> <para>To gain support for <acronym>PHP</acronym>5 for the <application>Apache</application> web server, begin by - installing the - <filename role="package">lang/php5</filename> + installing the <filename role="package">lang/php5</filename> port.</para> <para>If the <filename role="package">lang/php5</filename> @@ -5339,6 +4865,7 @@ DocumentRoot /www/someotherdomain.tld </sect1> <sect1 id="network-ftp"> + <!-- <sect1info> <authorgroup> <author> @@ -5348,139 +4875,122 @@ DocumentRoot /www/someotherdomain.tld </author> </authorgroup> </sect1info> - <title>File Transfer Protocol (FTP)</title> + --> + <title>File Transfer Protocol (<acronym>FTP</acronym>)</title> - <indexterm><primary>FTP servers</primary></indexterm> + <indexterm><primary><acronym>FTP</acronym> + servers</primary></indexterm> - <sect2> - <title>Overview</title> + <para>The File Transfer Protocol (<acronym>FTP</acronym>) provides + users with a simple way to transfer files to and from an + <acronym>FTP</acronym> server. &os; includes + <acronym>FTP</acronym> server software, + <application>ftpd</application>, in the base system.</para> - <para>The File Transfer Protocol (FTP) provides users with a - simple way to transfer files to and from an - <acronym role="File Transfer Protocol">FTP</acronym> server. - &os; includes - <acronym role="File Transfer Protocol">FTP</acronym> server - software, <application>ftpd</application>, in the base system. - This makes setting up and administering an - <acronym role="File Transfer Protocol">FTP</acronym> server on - FreeBSD very straightforward.</para> - </sect2> + <para>&os; provides several configuration files for controlling + access to the <acronym>FTP</acronym> server. This section + summarizes these files. Refer to &man.ftpd.8; for more details + about the built-in <acronym>FTP</acronym> server.</para> <sect2> <title>Configuration</title> <para>The most important configuration step is deciding which - accounts will be allowed access to the FTP server. A normal - &os; system has a number of system accounts used for - various daemons, but unknown users should not be allowed to - log in with these accounts. The - <filename>/etc/ftpusers</filename> file is a list of users - disallowed any FTP access. By default, it includes the - aforementioned system accounts, but it is possible to add - specific users here that should not be allowed access to - FTP.</para> + accounts will be allowed access to the <acronym>FTP</acronym> + server. A &os; system has a number of system accounts which + should not be allowed <acronym>FTP</acronym> access. The list + of users disallowed any <acronym>FTP</acronym> access can be + found in <filename>/etc/ftpusers</filename>. By default, it + includes system accounts. Additional users that should not be + allowed access to <acronym>FTP</acronym> can be added.</para> <para>In some cases it may be desirable to restrict the access of some users without preventing them completely from using - FTP. This can be accomplished with the - <filename>/etc/ftpchroot</filename> file. This file lists - users and groups subject to FTP access restrictions. The - &man.ftpchroot.5; manual page has all of the details so it - will not be described in detail here.</para> + <acronym>FTP</acronym>. This can be accomplished be creating + <filename>/etc/ftpchroot</filename> as described in + &man.ftpchroot.5;. This file lists users and groups subject + to <acronym>FTP</acronym> access restrictions.</para> <indexterm> - <primary>FTP</primary> + <primary><acronym>FTP</acronym></primary> <secondary>anonymous</secondary> </indexterm> - <para>To enable anonymous FTP access to the server, create a - user named <username>ftp</username> on the &os; system. Users - will then be able to log on to the FTP server with a username - of <username>ftp</username> or <username>anonymous</username> - and with any password (by convention an email address for the - user should be used as the password). The FTP server will - call &man.chroot.2; when an anonymous user logs in, to - restrict access to only the home directory of the + <para>To enable anonymous <acronym>FTP</acronym> access to the + server, create a user named <username>ftp</username> on the + &os; system. Users will then be able to log on to the + <acronym>FTP</acronym> server with a username of + <username>ftp</username> or <username>anonymous</username>. + When prompted for the password, any input will be accepted, + but by convention, an email address should be used as the + password. The <acronym>FTP</acronym> server will call + &man.chroot.2; when an anonymous user logs in, to restrict + access to only the home directory of the <username>ftp</username> user.</para> - <para>There are two text files that specify welcome messages to - be displayed to FTP clients. The contents of the file + <para>There are two text files that can be created to specify + welcome messages to be displayed to <acronym>FTP</acronym> + clients. The contents of <filename>/etc/ftpwelcome</filename> will be displayed to users before they reach the login prompt. After a successful - login, the contents of the file + login, the contents of <filename>/etc/ftpmotd</filename> will be displayed. Note that the path to this file is relative to the login - environment, so the file <filename>~ftp/etc/ftpmotd</filename> - would be displayed for anonymous users.</para> - - <para>Once the FTP server has been configured properly, it must - be enabled in <filename>/etc/inetd.conf</filename>. All that - is required here is to remove the comment symbol - <quote>#</quote> from in front of the existing - <application>ftpd</application> line :</para> - - <programlisting>ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l</programlisting> - - <para>As explained in <xref linkend="network-inetd-reread"/>, - the <application>inetd</application> configuration must be - reloaded after this configuration file is changed. Please - refer to <xref linkend="network-inetd-settings"/> for details - on enabling <application>inetd</application> on the - system.</para> + environment, so the contents of + <filename>~ftp/etc/ftpmotd</filename> would be displayed for + anonymous users.</para> - <para>Alternatively, <application>ftpd</application> can also be - started as a stand-alone server. In this case, it is - sufficient to set the appropriate variable in - <filename>/etc/rc.conf</filename>:</para> + <para>Once the <acronym>FTP</acronym> server has been + configured, set the appropriate variable in + <filename>/etc/rc.conf</filename> to start the service during + boot:</para> <programlisting>ftpd_enable="YES"</programlisting> - <para>After setting the above variable, the stand-alone server - will be started at the next reboot, or it can be started - manually by executing the following command as - <username>root</username>:</para> + <para>To start the service now:</para> <screen>&prompt.root; <userinput>service ftpd start</userinput></screen> - <para>You can now log on to the FTP server by typing:</para> + <para>Test the connection to the <acronym>FTP</acronym> server + by typing:</para> <screen>&prompt.user; <userinput>ftp localhost</userinput></screen> - </sect2> - - <sect2> - <title>Maintaining</title> - <indexterm><primary>syslog</primary></indexterm> <indexterm><primary>log files</primary> - <secondary>FTP</secondary></indexterm> + <secondary><acronym>FTP</acronym></secondary></indexterm> <para>The <application>ftpd</application> daemon uses &man.syslog.3; to log messages. By default, the system log - daemon will put messages related to FTP in the - <filename>/var/log/xferlog</filename> file. The location of - the FTP log can be modified by changing the following line in + daemon will write messages related to <acronym>FTP</acronym> + in <filename>/var/log/xferlog</filename>. The location of + the <acronym>FTP</acronym> log can be modified by changing the + following line in <filename>/etc/syslog.conf</filename>:</para> <programlisting>ftp.info /var/log/xferlog</programlisting> <indexterm> - <primary>FTP</primary> + <primary><acronym>FTP</acronym></primary> <secondary>anonymous</secondary> </indexterm> - <para>Be aware of the potential problems involved with running - an anonymous FTP server. In particular, think twice about - allowing anonymous users to upload files. It may turn out - that the FTP site becomes a forum for the trade of unlicensed - commercial software or worse. If anonymous FTP uploads are - required, then verify the permissions so that these files can - not be read by other anonymous users until they have been - reviewed by an administrator.</para> + <note> + <para>Be aware of the potential problems involved with running + an anonymous <acronym>FTP</acronym> server. In particular, + think twice about allowing anonymous users to upload files. + It may turn out that the <acronym>FTP</acronym> site becomes + a forum for the trade of unlicensed commercial software or + worse. If anonymous <acronym>FTP</acronym> uploads are + required, then verify the permissions so that these files + can not be read by other anonymous users until they have + been reviewed by an administrator.</para> + </note> </sect2> </sect1> <sect1 id="network-samba"> + <!-- <sect1info> <authorgroup> <author> @@ -5490,6 +5000,7 @@ DocumentRoot /www/someotherdomain.tld </author> </authorgroup> </sect1info> + --> <title>File and Print Services for µsoft.windows; Clients (Samba)</title> @@ -5504,24 +5015,20 @@ DocumentRoot /www/someotherdomain.tld <secondary>Windows clients</secondary> </indexterm> - <sect2> - <title>Overview</title> - - <para><application>Samba</application> is a popular open source - software package that provides file and print services for - µsoft.windows; clients. Such clients can connect to and - use &os; filespace as if it was a local disk drive, or - &os; printers as if they were local printers.</para> + <para><application>Samba</application> is a popular open source + software package that provides file and print services for + µsoft.windows; clients. Such clients can connect to and + use &os; filespace as if it was a local disk drive, or + &os; printers as if they were local printers.</para> - <para><application>Samba</application> software packages should - be included on the &os; installation media. If they were not - installed when first installing &os;, then they may be - installed from the - <filename role="package">net/samba34</filename> port or - package.</para> + <para><application>Samba</application> software packages should + be included on the &os; installation media. If they were not + installed when first installing &os;, then they may be + installed from the <filename + role="package">net/samba34</filename> port or + package.</para> <!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. --> - </sect2> <sect2> <title>Configuration</title> @@ -5604,7 +5111,7 @@ DocumentRoot /www/someotherdomain.tld <para>This sets the NetBIOS name by which a <application>Samba</application> server is known. By default it is the same as the first component of - the host's DNS name.</para> + the host's <acronym>DNS</acronym> name.</para> </listitem> </varlistentry> @@ -5755,10 +5262,10 @@ Starting smbd.</screen> functionality beyond the basic installation described here, please see <ulink url="http://www.samba.org"></ulink>.</para> </sect2> - </sect1> <sect1 id="network-ntp"> + <!-- <sect1info> <authorgroup> <author> @@ -5768,38 +5275,35 @@ Starting smbd.</screen> </author> </authorgroup> </sect1info> + --> <title>Clock Synchronization with NTP</title> <indexterm><primary>NTP</primary></indexterm> - <sect2> - <title>Overview</title> - - <para>Over time, a computer's clock is prone to drift. The - Network Time Protocol (NTP) is one way to ensure the clock - stays accurate.</para> - - <para>Many Internet services rely on, or greatly benefit from, - computers' clocks being accurate. For example, a web server - may receive requests to send a file if it has been modified - since a certain time. In a local area network environment, it - is essential that computers sharing files from the same file - server have synchronized clocks so that file timestamps stay - consistent. Services such as &man.cron.8; also rely on - an accurate system clock to run commands at the specified - times.</para> + <para>Over time, a computer's clock is prone to drift. The + Network Time Protocol (NTP) is one way to ensure the clock + stays accurate.</para> + + <para>Many Internet services rely on, or greatly benefit from, + computers' clocks being accurate. For example, a web server + may receive requests to send a file if it has been modified + since a certain time. In a local area network environment, it + is essential that computers sharing files from the same file + server have synchronized clocks so that file timestamps stay + consistent. Services such as &man.cron.8; also rely on an + accurate system clock to run commands at the specified + times.</para> + + <indexterm><primary>NTP</primary> + <secondary>ntpd</secondary> + </indexterm> - <indexterm> - <primary>NTP</primary> - <secondary>ntpd</secondary> - </indexterm> - <para>&os; ships with the &man.ntpd.8; - <acronym role="Network Time Protocol">NTP</acronym> server - which can be used to query other - <acronym role="Network Time Protocol">NTP</acronym> servers to - set the clock on the machine or provide time services to - others.</para> - </sect2> + <para>&os; ships with the &man.ntpd.8; + <acronym role="Network Time Protocol">NTP</acronym> server + which can be used to query other + <acronym role="Network Time Protocol">NTP</acronym> servers to + set the clock on the machine or provide time services to + others.</para> <sect2> <title>Choosing Appropriate NTP Servers</title> @@ -5923,8 +5427,8 @@ driftfile /var/db/ntp.drift</programlisting> <para>This will also prevent access from the server to any servers listed in the local configuration. If there is a need to synchronise the NTP server with an external NTP - server, allow only that specific server. See the - &man.ntp.conf.5; manual for more information.</para> + server, allow only that specific server. Refer to + &man.ntp.conf.5; for more information.</para> </note> <para>To allow machines within the network to synchronize @@ -5935,8 +5439,8 @@ driftfile /var/db/ntp.drift</programlisting> <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting> <para>instead, where - <hostid role="ipaddr">192.168.1.0</hostid> is an IP address - on the network and + <hostid role="ipaddr">192.168.1.0</hostid> is an + <acronym>IP</acronym> address on the network and <hostid role="netmask">255.255.255.0</hostid> is the network's netmask.</para> @@ -6009,6 +5513,7 @@ driftfile /var/db/ntp.drift</programlisting> </sect1> <sect1 id="network-syslogd"> + <!-- <sect1info> <authorgroup> <author> @@ -6018,6 +5523,7 @@ driftfile /var/db/ntp.drift</programlisting> </author> </authorgroup> </sect1info> + --> <title>Remote Host Logging with <command>syslogd</command></title> @@ -6086,8 +5592,8 @@ driftfile /var/db/ntp.drift</programlisting> <note> <para>More information on various supported and available - <emphasis>facilities</emphasis> may be found in the - &man.syslog.conf.5; manual page.</para> + <emphasis>facilities</emphasis> may be found in + &man.syslog.conf.5;.</para> </note> <para>Once added, all <literal>facility</literal> messages will @@ -6111,8 +5617,8 @@ syslogd_flags="-a logclient.example.com -v -v"</programlisting> <para>Multiple <option>-a</option> options may be specified to allow logging from multiple clients. <acronym>IP</acronym> - addresses and whole netblocks may also be specified, see the - &man.syslog.3; manual page for a full list of possible + addresses and whole netblocks may also be specified. Refer to + &man.syslog.3; for a full list of possible options.</para> <para>Finally, the log file should be created. The method used @@ -6186,8 +5692,8 @@ syslogd_flags="-s -v -v"</programlisting> Facilities are accompanied with a priority or level, which is used to mark how important a log message is. The most common will be the <literal>warning</literal> and - <literal>info</literal>. Please refer to the &man.syslog.3; - manual page for a full list of available facilities and + <literal>info</literal>. Refer to &man.syslog.3; + for a full list of available facilities and priorities.</para> <para>The logging server must be defined in the client's @@ -6306,4 +5812,334 @@ Logging to FILE /var/log/messages</screen> by local users.</para> </sect2> </sect1> + + <sect1 id="network-iscsi"> + <!-- + <sect1info> + <authorgroup> + <author> + <firstname>Edward Tomasz</firstname> + <surname>Napierala</surname> + </author> + </authorgroup> + </sect1info> + --> + + <title><acronym>iSCSI</acronym> Initiator and Target Configuration</title> + + <para><acronym>iSCSI</acronym> is a way to share storage, to make + disk space at one machine (the server, in iSCSI nomenclature + known as the <emphasis>target</emphasis>) available to others (clients, called <emphasis>initiators</emphasis> + in <acronym>iSCSI</acronym>). The main difference when compared to <acronym>NFS</acronym> is + that <acronym>NFS</acronym> works at a filesystem level, while <acronym>iSCSI</acronym> works at the block + device level. To initiators, remote disks served via <acronym>iSCSI</acronym> + are just like physical disks. Their device + nodes appear in <filename>/dev/</filename>, and must be separately + mounted.</para> + + <sect2 id="network-iscsi-target"> + <title><acronym>iSCSI</acronym> Target</title> + + <para>Note: the native <acronym>iSCSI</acronym> target is supported starting with + &os; 10.0-RELEASE. To use <acronym>iSCSI</acronym> in older versions of &os;, install a + userspace target from the Ports Collection, such as + <filename role="package">net/istgt</filename>. + This chapter only describes the native target.</para> + + <sect3> + <title>Basic Operation</title> + + <para>Configuring an <acronym>iSCSI</acronym> target is straightforward: + create the <filename>/etc/ctl.conf</filename> + configuration file, add an appropriate line to + <filename>/etc/rc.conf</filename> to make sure the <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + daemon is automatically started at boot, and then start + the daemon.</para> + + <para>A simple <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink> + configuration file looks like this:</para> + + <programlisting>portal-group pg0 { + discovery-auth-group no-authentication + listen 0.0.0.0 + listen [::] +} + +target iqn.2012-06.com.example:target0 { + auth-group no-authentication + portal-group pg0 + + lun 0 { + path /data/target0-0 + size 4G + } +}</programlisting> + + <para>The first entry defines the <literal>pg0</literal> portal group. + Portal groups define network addresses the + <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + daemon will listen on. <literal>discovery-auth-group + no-authentication</literal> means that every initiator is allowed to + perform <acronym>iSCSI</acronym> SendTargets discovery without any + authentication. The following two lines make <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + listen on all <acronym>IPv4</acronym> (<literal>listen 0.0.0.0</literal>) and <acronym>IPv6</acronym> (<literal>listen + [::]</literal>) addresses on the + default port (3560). It is not necessary to define + a new portal group; there is a default one, called + <literal>default</literal>. The difference between <literal>default</literal> and <literal>pg0</literal> above is + that with <literal>default</literal>, the <acronym>iSCSI</acronym> SendTargets discovery is + always denied, while with <literal>pg0</literal> it is always + allowed.</para> + + <para>The second entry defines a single <emphasis>target</emphasis>. + <quote>Target</quote> has two + meanings: it is a machine serving <acronym>iSCSI</acronym>, but also + a named group of <acronym>LUNs</acronym>. In this example, we use the latter + meaning. + <literal>iqn.2012-06.com.example:target0</literal> is the + target name. For testing purposes it can be left as + is; otherwise, <literal>com.example</literal> + should be changed to the + real domain name, reversed; the <literal>2012-06</literal> + is the year and + month of acquiring control of that domain name, and + <literal>target0</literal> can be pretty much whatever. + Any + number of targets can be defined in the configuration file.</para> + + <para><literal>auth-group no-authentication</literal> + allows all initiators to connect to this target. + <literal>portal-group pg0</literal> + makes the target reachable through the <literal>pg0</literal> + portal group.</para> + + <para>After that come <acronym>LUNs</acronym>. To the initiator, each <acronym>LUN</acronym> will + be visible as a separate disk device, like + <filename>/dev/da0</filename>, <filename>/dev/da1</filename> + and so on. Multiple <acronym>LUNs</acronym> can be defined for each target. + <acronym>LUNs</acronym> are identified by numbers; <acronym>LUN</acronym> 0 is mandatory. The first + line of <acronym>LUN</acronym> configuration (<literal>path /data/target0-0</literal>) + defines the + full path to a file or ZVOL backing the <acronym>LUN</acronym>. The file must + exist before starting <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>. + The second line is optional and specifies the size.</para> + + <para>To make sure <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + daemon is started at boot, add this + line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ctld_enable="YES"</programlisting> + + <para>On a new server being configured as <acronym>iSCSI</acronym> target, + <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + can be started by running this command as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>service ctld start</userinput></screen> + + <para>The <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + daemon reads <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink> + file when started. To make configuration changes take + effect immediately, force <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + to reread it:</para> + + <screen>&prompt.root; <userinput>service ctld reload</userinput></screen> + </sect3> + + <sect3> + <title>Authentication</title> + + <para>The example above is inherently insecure: it uses no + authentication whatsoever, granting anyone full access to + all targets. To require username and password to access + targets, modify the configuration:</para> + + <programlisting>auth-group ag0 { + chap username1 secretsecret + chap username2 anothersecret +} + +portal-group pg0 { + discovery-auth-group no-authentication + listen 0.0.0.0 + listen [::] +} + +target iqn.2012-06.com.example:target0 { + auth-group ag0 + portal-group pg0 + lun 0 { + path /data/target0-0 + size 4G + } +}</programlisting> + + <para>The <literal>auth-group</literal> section defines username and password pairs. + An initiator trying to connect to + <literal>iqn.2012-06.com.example:target0</literal> must specify either of + those. The SendTargets discovery is still permitted without + any kind of authentication; to change it, set + <literal>discovery-auth-group</literal> to something else.</para> + + <para>A common case for <acronym>iSCSI</acronym> is to have a single exported + target for every initiator. As a shorthand for the syntax + above, the username and password can be specified directly in the + target entry:</para> + + <programlisting>target iqn.2012-06.com.example:target0 { + portal-group pg0 + chap username1 secretsecret + + lun 0 { + path /data/target0-0 + size 4G + } +}</programlisting> + </sect3> + </sect2> + + <sect2 id="network-iscsi-initiator"> + <title><acronym>iSCSI</acronym> Initiator</title> + + <note> + <para>The current <acronym>iSCSI</acronym> initiator is supported starting with + &os; 10.0-RELEASE. To use the <acronym>iSCSI</acronym> initiator available in + older versions, refer to <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</ulink>. + This chapter only applies to the new + initiator.</para> + </note> + + <para>The <acronym>iSCSI</acronym> initiator requires the <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink> + daemon to run. It does not use a configuration + file. To start it automatically at boot, add + this line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>iscsid_enable="YES"</programlisting> + + <para>On a new machine being configured as an <acronym>iSCSI</acronym> initiator, + <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink> + can be started by running this command as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>service iscsid start</userinput></screen> + + <para>Connecting to a target can be done with or without an + <ulink + url="http://www.freebsd.org/cgi/man.cgi?query=iscsi.conf&sektion=5&manpath=FreeBSD+10-current">iscsi.conf(8)</ulink> + configuration file.</para> + + <sect3> + <title>Connecting to a Target Without a Configuration + File</title> + + <para>To make the initiator connect to a single target, run + this command as <username>root</username>:</para> |