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

- Update to 200606170-SVN (http://OpenSVN.csie.org/freebsddoc)

Browse source 
- Generated by chinsan, psilotum, tzhuan, whsyu

PR:		ports/99074
Submitted by:	chinsan <chinsan.tw@gmail.dot.com>
This commit is contained in:
Vanilla I. Shu 2006-06-17 10:22:46 +00:00
parent d5140b068d
commit 507ebf0702
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=28109
49 changed files with 21855 additions and 1746 deletions

4
zh_TW.Big5/articles/Makefile
View file

@ -3,6 +3,10 @@
SUBDIR =
SUBDIR+= contributing
SUBDIR+= cvs-freebsd
SUBDIR+= hubs
SUBDIR+= mailing-list-faq
SUBDIR+= pr-guidelines
SUBDIR+= problem-reports
DOC_PREFIX?= ${.CURDIR}/../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

17
zh_TW.Big5/articles/hubs/Makefile Normal file
View file

@ -0,0 +1,17 @@
#
# $FreeBSD$
#
# Article: Mirroring FreeBSD
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

1081
zh_TW.Big5/articles/hubs/article.sgml Normal file
View file

File diff suppressed because it is too large Load diff

26
zh_TW.Big5/articles/mailing-list-faq/Makefile Normal file
View file

@ -0,0 +1,26 @@
#
# $FreeBSD$
#
# Article: Frequently Asked Questions About The FreeBSD Mailing Lists
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
WITH_ARTICLE_TOC?=YES
#
# SRCS lists the individual SGML files that make up the document. Changes
# to any of these files will force a rebuild
#
# SGML content
SRCS= article.sgml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

430
zh_TW.Big5/articles/mailing-list-faq/article.sgml Normal file
View file

@ -0,0 +1,430 @@
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<!-- FreeBSD Mailing Lists 常見問答集 -->
<!-- Translate into Chinese by chinsan.tw@gmail.com -->
<!-- English Version: 1.7 -->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
]>
<article>
<articleinfo>
<title>&os; Mailing Lists 常見問答集</title>
<authorgroup>
<author>
<surname>The &os; Documentation Project</surname>
</author>
</authorgroup>
<pubdate>$FreeBSD$</pubdate>
<copyright>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<holder>&os; 文件計畫</holder>
</copyright>
<abstract>
<para>這是有關 &os; mailing lists 的 FAQ。如果您對協助本文件/翻譯計畫
的進行有興趣的話，請寄 e-mail 到
&a.doc;。此外，隨時可從 <ulink URL="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/index.html">
FreeBSD 網站</ulink> 拿到這份文件的最新版本。
也可以利用 HTTP 來下載 <ulink URL="article.html">HTML</ulink>
文件，或是經由 <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">
FreeBSD FTP 站</ulink> 下載純文字、&postscript;、或 PDF 版本的檔案。
您也可以在這裡使用
<ulink URL="&url.base;/search/search.html">搜尋 FAQ 資料</ulink>
的功能。</para>
</abstract>
</articleinfo>
<sect1 id="introduction">
<title>前言</title>
<para>如同其他 FAQs 一樣，本文主要目的是希望涵蓋在 &os; mailing
lists 上面的常見問題(當然，包括答案)。
雖然，原本構想是希望能降低這些重複問題的網路流量，但如今已被公認 FAQs 也是相當好用的資源之一。</para>
<para>本文主要是描述社群之間所培養的一些禮儀(或默契)，但本文本身並非『聖旨』般的權威。
若發現本文內有任何技術瑕疵，或者是想建議可以增加哪些部分的話，請送 PR，或是 email 到 &a.doc;。謝囉！</para>
<qandaset>
<qandaentry>
<question id="purpose">
<para>&os; mailing lists 的目的為何？</para>
</question>
<answer>
<para>&os; mailing lists 主要是提供 &os; 社群間的溝通管道，這裡有各式專題領域的探討，以及興趣交流。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="audience">
<para>&os; mailing lists 的參與者有哪些?</para>
</question>
<answer>
<para>這個問題，要看各個 list 的『版規(charter)』定位而有所不同。有些 lists 主要是 developers 在參與討論的；
而有些則主要是幾乎整體 &os; 社群都可以隨意參與討論的。請看 <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">這份清單</ulink> 上面有目前所有 list 的摘要說明。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="participation-who">
<para>&os; mailing lists 對任何人都是開放參與的嗎？</para>
</question>
<answer>
<para>再重複一次，這要看各個 list 的『版規(charter)』定位而有所不同。
請在發文前，先注意閱讀該 list 的『版規(charter)』，並遵守相關原則。
如此一來，才會讓大家都能溝通更無礙。</para>
<para>如果看了上一個問答內的清單之後，還是不清楚要到哪個 list 去發問的話，
那麼可以試著把問題丟到 freebsd-questions 看看(但請先看下面講的補充)。</para>
<para>請注意：習慣上所有 mailing lists 都是開放發表討論的，也不必得先成為訂閱會員才行。
這是相當審慎的選擇，來讓參與 &os; 社群更輕鬆容易，並鼓勵互相分享彼此的想法。
然而，由於過去有些人的濫用，有些 lists 現在開始限制參與討論的部分，以避免不必要的困擾。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="subscribe">
<para>要怎麼訂閱呢？</para>
</question>
<answer>
<para>可以用 <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">
Mailman 網頁介面</ulink> 來訂閱任何公開的 lists。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="unsubscribe">
<para>要怎麼退訂？</para>
</question>
<answer>
<para>一樣請用剛上面說的網頁介面，或者 mailing list 上面每封信結尾處都會有相關 URL 連結的指示說明。</para>
<para>千萬請不要直接寫信到這些公開的 mailing lists 說你要退訂。
首先呢..因為本來就不是這樣退訂的，其次你會惹來眾怒而招來圍剿、筆戰。
這是很典型的退訂錯誤示範，請不要這樣做。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="archives">
<para>可以找到舊信的資料庫嗎？</para>
</question>
<answer>
<para>嗯，有！可以在 <ulink url="http://docs.FreeBSD.org/mail/">這邊</ulink>
找到相關的舊信資料庫(archive)。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="digest">
<para>mailing lists 可有摘要版呢？</para>
</question>
<answer>
<para>當然也有，請看 <ulink
url="http://lists.FreeBSD.org/mailman/listinfo">
Mailman 網頁介面</ulink>。</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="etiquette">
<title>Mailing List 的參與禮儀</title>
<para>在 mailing lists 上參與討論，就像在其他社群一樣，我們都需要一些溝通上的共識。
發言請注重禮儀(或默契)，切勿無的放矢。</para>
<qandaset>
<qandaentry>
<question id="before-posting">
<para>在發文之前，有什麼注意事項呢？</para>
</question>
<answer>
<para>最重要的是你已經看了這篇文章，然而，若您對 &os; 不熟的話，
可能需要先廣泛閱讀
<ulink url="&url.base;/docs/books.html">相關書籍及文章</ulink>
來先熟悉這套作業系統和一些典故，尤其是其中的 <ulink
url="&url.books.faq;/index.html">
&os; 常見問答集 (FAQ)</ulink> 文件，
<ulink
url="&url.books.handbook;/index.html">
&os; 使用手冊(Handbook)</ulink>，
以及相關文章：<ulink
url="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</ulink>、
<ulink
url="&url.articles.explaining-bsd;/article.html">
Explaining BSD</ulink>、以及 <ulink
url="&url.articles.new-users;/article.html">
&os; First Steps</ulink>。</para>
<para>此外，對上述文件內已有解答的部份又提出來問的話，會被認為是相當不禮貌的。
這並不是因為這群志工是相當吝於回答的，而是一再被相同的問題不斷疲勞轟炸之後，所產生的挫折感很重。
尤其是現成答案明明就在眼前，卻仍同樣問題滿天飛，這實在是...。
請注意：這些 &os; 相關文件幾乎都是由一群無薪志工的好心成果，而他們也是人。</para>
</answer>
</qandaentry>
<qandaentry>
<question id="inappropriate">
<para>如何避免不當發文呢？</para>
</question>
<answer>
<itemizedlist>
<listitem>
<para>發文時，請務必遵守該 mailing list 的遊戲規則。</para>
</listitem>
<listitem>
<para>不要作人身攻擊。好的網路公民，應該要有更高的言行標準。</para>
</listitem>
<listitem>
<para>請不要試圖作 Spam 行為(廣告、轉貼多處等不請自來行為)。
所有 mailing lists 都會積極禁止這些違規者，一旦有的話，那麼後果請自行負責。</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question id="etiquette-posting">
<para>發文時，有什麼該注意的嗎？</para>
</question>
<answer>
<itemizedlist>
<listitem>
<para>發文時，請保持一行約 75 個字元就自動斷行，因為並不是每個看的人都有很炫的圖形介面(GUI)看信軟體。</para>
</listitem>
<listitem>
<para>請注意：事實上，網路頻寬並不是無限的。
並非每個讀者的頻寬都很大，所以若想貼一些像是 <filename>config.log</filename>
之類的設定檔內容，或是大量的 stack trace 紀錄，那麼請把它放在自己網站上，然後貼出該網址 URL 就行了。
還有一件事，請記住，這些信件都會被舊信資料庫保存下來，所以這樣作會造成保存的資料庫會很快被塞到很大，
甚至可能塞爆 Server 的硬碟空間。</para>
</listitem>
<listitem>
<para>文章是要讓人看得懂，所以請注意版面編排的可讀性，還有..
千　萬　不　要　大　聲　嚷　叫!!!!! 這點可不只 &os; mailing lists 才需如此注意，
請勿低估文章『基本編排』的重要性、連鎖效應。
信中的表達方式通常就代表著別人眼中的你，若文章讓人看了很吃力(霧煞煞)、拼字錯誤百出、
充滿語意或邏輯錯誤、或是文內充滿一堆驚嘆號，這會讓人對你印象觀感極差。</para>
</listitem>
<listitem>
<para>在一些特定的 list 場合，請用適當的語言來溝通。許多非英語系的mailing
lists 可以到
<ulink url="&url.base;/community/mailinglists.html">
這邊</ulink> 查看看。</para>
<para>對於許多母語不是英語的人，我們都能諒解他們的苦楚，並且試著儘量多多包涵。
英文非母語的人，我們會儘量不惡意批評拼字或文法錯誤之處。
&os; 在這方面，一直有相當優秀的紀錄，請讓我們繼續保持這傳統吧。</para>
</listitem>
<listitem>
<para>寫信時，請用相容標準的 Mail User Agent (MUA)程式。
<ulink url="http://www.lemis.com/email.html">不良的(或設定錯誤的)寄信程式</ulink>
這裡列有許多信件格式的錯誤示範。以下是一些已知的寄信程式的不良示範：</para>
<itemizedlist>
<listitem>
<para>cc:Mail</para>
</listitem>
<listitem>
<para>(舊版的)&eudora;</para>
</listitem>
<listitem>
<para>exmh</para>
</listitem>
<listitem>
<para>&microsoft; Exchange</para>
</listitem>
<listitem>
<para>&microsoft; Internet Mail</para>
</listitem>
<listitem>
<para>&microsoft; &outlook;</para>
</listitem>
<listitem>
<para>(舊版的)&netscape;</para>
</listitem>
</itemizedlist>
<para>如同上述所見，Microsoft 出的一堆寄信程式通常都是不相容標準格式的。
請儘量改用 &unix; 上的寄信程式。若必須在 Microsoft 環境下使用寄信程式的話，
請記得確認設定是否正確。請儘量不要用 <acronym>MIME</acronym> 格式：
因為有一堆人都在濫用 <acronym>MIME</acronym> 信件格式。</para>
</listitem>
<listitem>
<para>請確認：時間與時區設定是否正確。
這問題看起來有點蠢，因為你寄出的信還是會到達 mailing list 上，
但是呢，每位 mailing lists 上的訂戶每天都會看數百封的信，
他們通常會把信件以標題跟時間作為排序依據。
若你的信沒有在第一篇正解之前就先出現的話，他們就會假設可能是漏收你這封信，
然後就沒再去看你那封信了。</para>
</listitem>
<listitem>
<para>請提供程式出現的相關訊息，像是 &man.dmesg.8; 或者 console
messages 也就是通常會出現在 <filename>/var/log/messages</filename> 出現的。
請不要用手打，因為這不僅很苦，而且也可能打錯字或亂掉原有格式。請直接把相關的 log 檔丟出來，
或是用編輯器來剪裁、或是用滑鼠複製/貼上來完成。舉個例子，如果是要把像是 <command>dmesg</command>
的程式訊息倒入到某個檔案去的話，那麼作法如下：</para>
<screen>&prompt.user; <userinput>dmesg &gt; /tmp/dmesg.out</userinput></screen>
<para>這樣子會把訊息送到 <filename>/tmp/dmesg.out</filename> 檔內。</para>
</listitem>
<listitem>
<para>在用滑鼠剪貼時，請注意是否有犯一些細節的剪貼壞習慣。
尤其是像貼 <filename>Makefiles</filename> 之類檔案時，由於 <literal>tab</literal>
鍵所打出來的分格，是屬於特殊字元。因此，在 <ulink url="&url.base;/support.html#gnats">
GNATS PR 資料庫</ulink> 上很常看到這類很常見的惱人問題：
<filename>Makefiles</filename> 內的 tab 經過剪貼後，變成『空白(white space)』
或是困擾的 <literal>=3B</literal> escape sequence，這些會讓 committers 們十分不爽。</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question id="etiquette-replying">
<para>在 mailing lists 上回文的話，有什麼要特別注意的嗎？</para>
</question>
<answer>
<itemizedlist>
<listitem>
<para>請適當調整文章引言長度。回文時，引言部份請引『有談到的』部分為主，但請不要過與不及。
應該保留涉及討論範圍的原文，這樣子才能讓沒看過前面文章的人知道是在講什麼，而非一頭霧水。</para>
<para>還有一點也很重要，原文若是幅度相當長的話，記得註明 "yes, I see this too"。</para>
</listitem>
<listitem>
<para>善用技巧來確認原文與自己寫的部份：
通常會在原文的每行前面加上 <quote><literal>&gt; </literal></quote> 以作記號。
請記得保留 <quote><literal>&gt; </literal></quote> 符號後面的空白，並且在原文以及你所寫的段落之間加上空行，
以便閱讀。</para>
</listitem>
<listitem>
<para>請不要斷章取義、穿鑿附會：通常對原始文章『斷章取義』、『穿鑿附會』會讓大家很不爽，因為他們原意並非如此，卻被曲解。</para>
</listitem>
<listitem>
<para>回文時，不要寫在原文上面(<literal>top post</literal>)。
這個意思是：若要回文時，請寫在原文下方，不要寫在原文上面，以免讓人有時空錯置的錯亂混淆。</para>
<!-- 注意：下面這是故意幽默效果的問答 -->
<itemizedlist>
<listitem>
<para>答： Because it reverses the logical flow of
conversation.</para>
</listitem>
<listitem>
<para>問： Why is top posting frowned upon?</para>
</listitem>
</itemizedlist>
<para>(感謝 Randy Bush 提供笑話)</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="recurring">
<title>Mailing Lists 上的重複性問題</title>
<para>在 mailing lists 上參與討論，就像在其他社群一樣，我們都需要一些溝通上的共識。
許多 mailing lists 都會假設參與討論者都大致知道 FreeBSD 計劃的一些歷史淵源。
尤其是社群的新手總是定期會不斷重複問類似問題。
每個發文的人，都有責任來避免掉入這樣的惡性循環輪迴內。
因此，應儘可能讓 mailing list 上能正常討論，而避免讓自己陷入筆戰泥沼。</para>
<para>要怎麼避免呢？最好的方法就是善用這些 <ulink url="http://docs.FreeBSD.org/mail/">
mailing list 舊信資料庫(archives)</ulink>，來瞭解相關背景。
正由於這原因，所以 <ulink
url="http://www.FreeBSD.org/search/search.html#mailinglists">
mailing list 搜尋介面</ulink> 就顯得非常好用。
(若這方法仍無法找到有用的答案，那麼請改用自己愛用的搜尋引擎吧)</para>
<para>透過這些舊信資料庫，不只可瞭解先前討論過哪些話題，也可以知道：是怎麼討論的、
哪些人參與討論過、主要看的人又是哪些人。
入境隨俗這些原則不只是 &os; mailing list 上才這樣，一樣可以適合其他地方。</para>
<para>archives 的內容無疑地相當廣泛，而且會有些問題不斷反覆出現，
有時討論到後面總會離題。無論如何，在發問前的義務就是先做好功課，
以避免這類的月經文惡性循環，尤其是令人反感的 <literal>bikeshed（打嘴砲)</literal>。</para>
</sect1>
<sect1 id="bikeshed">
<title>什麼是 "Bikeshed" 呀？</title>
<para>單就字面上意思解釋的話，<literal>bikeshed</literal> 是指專門給腳踏車、機車之類的兩輪交通工具使用的遮雨棚，
然而呢，在 &os; 這邊的說法卻有其他意思(帶有貶抑)指的是：
某些特定話題的重複討論，尤其是指在 &os; 社群內絕不會有共識，且有爭議的話題。
(這字彙的起源在 <ulink
url="&url.books.faq;/misc.html#BIKESHED-PAINTING">
這份文件</ulink> 內有更多說明)。你只要在發信到任一 &os; mailing lists 之前，知道這個基本概念就行了。</para>
<para>一般來講，『bikeshed』是很容易產生許多波的筆戰與額外討論的爭議話題，如果事先不知道這些背景的話。</para>
<para>拜託，請幫個忙讓討論回歸正常，而不要只是到處打嘴砲而已。感恩！</para>
</sect1>
<sect1 id="acknowledgments">
<title>致謝</title>
<variablelist>
<varlistentry>
<term>&a.grog;</term>
<listitem>
<para><ulink
url="&url.articles.freebsd-questions;/article.html">
How to get best results from the FreeBSD-questions mailing list</ulink> 一文的原作者，
我們從他這文內獲得許多 mailing list 上的禮儀(或默契)寫作題材。</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.linimon;</term>
<listitem>
<para>本 FAQ 雛形的原作</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</article>

19
zh_TW.Big5/articles/pr-guidelines/Makefile Normal file
View file

@ -0,0 +1,19 @@
#
# $FreeBSD$
#
# Article: Problem Report Handling Guidelines
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

881
zh_TW.Big5/articles/pr-guidelines/article.sgml Normal file
View file

@ -0,0 +1,881 @@
<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<!-- Translate into Chinese by chinsan.tw@gmail.com -->
<!-- English Version: 1.24 -->
<!--
問題回報(PR)的處理原則
The FreeBSD Project - http://www.FreeBSD.org
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
]>
<article>
<!-- :START of Article Metadata -->
<articleinfo>
<title>問題回報(PR)的處理原則</title>
<pubdate>$FreeBSD$</pubdate>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.opengroup;
&tm-attrib.general;
</legalnotice>
<abstract>
<para>這篇文章主要在講：由 FreeBSD PR 維護小組所提出的一些 FreeBSD 問題回報(PR)
建議，希望大家在弄 PR 時都能遵守。</para>
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
</author>
<author>
<firstname>Hiten</firstname>
<surname>Pandya</surname>
</author>
</authorgroup>
</articleinfo>
<!-- :END of Article Metadata-->
<section id="intro">
<title>前言</title>
<para>GNATS 是 FReeBSD 計劃所採用的一套專門管理錯誤(回報bug) 系統。
由於對 FreeBSD 品質保證而言，是否能準確掌握各項錯誤回報與進度是十分重要的，
因此，如何正確有效使用 GNATS 也就必須注意。</para>
<para>Access to GNATS is available to FreeBSD developers, as well as
to the wider community. 為了讓 GNATS 資料庫使用上儘量一致，於是就產生了怎麼處理像是：followup(回文)、關閉PR等的參考原則。</para>
</section>
<section id="pr-lifecycle">
<title>問題回報(PR)的生命週期</title>
<itemizedlist>
<listitem>
<para>首先，回報者(originator)以 &man.send-pr.1; 送出 PR，然後會收到一封確認信。</para>
</listitem>
<listitem>
<para>然後，committer 們就會有人(假設叫做 Joe)發掘有興趣的 PR 並將該 PR 指派給自己來處理。
或者 bugbuster 會有人(假設叫做 Jane) 就會下決定：她覺得 Joe 比較適合處理，就將該 PR 指派(assign)給他</para>
</listitem>
<listitem>
<para>Joe 會先與有問題的回報者作些意見交流(以確定這問題有進入 audit 追蹤流程內)
以及判斷問題點。
然後再確定問題點有寫入 audit 追蹤流程之後，然後把該 PR 狀態設為
<quote>analyzed(已分析)</quote>。</para>
</listitem>
<listitem>
<para>Joe 開始徹夜找出問題解法，然後將 patch 送到 follow-up(回文用)，並請回報者協助測試是否正常。
然後，他就會將 PR 狀態設為 <quote>feedback</quote> 囉。</para>
</listitem>
<listitem>
<para>如此重複 analyzed、feedback 幾趟之後，直到 Joe 與回報者雙方都相當滿意 patch 結果，
於是就會將 patch 給 commits 進入 <literal>-CURRENT</literal> (或者若 <literal>-CURRENT</literal>
上面沒這問題的話，就直接送到 <literal>-STABLE</literal>)，在 commit log 內要把相關 PR 寫上去
(同時回報者若有送完整或部分 patch 的話，就順便記載)，然後，若沒什麼事的話，就開始準備 MFC 哩。
(譯註：MFC意指 Merged From CURRENT ，也就是把 <literal>-CURRENT</literal> 上的東西併入 <literal>-STABLE</literal>。</para>
</listitem>
<listitem>
<para>若該 patch 不需要 MFC 的話，Joe 就會關掉(close)該 PR 了。</para>
</listitem>
<listitem>
<para>若該 patch 需要 MFC 的話，Joe 會把 PR 狀態改為 <quote>patched(已修正)</quote>，
直到已經 MFC 完畢，才會 close(關掉)。</para>
</listitem>
</itemizedlist>
<note>
<para>很多送出來的 PR 都很少附上問題的相關訊息，而有些則是相當複雜難搞，
或只是提到部分表面問題而已；
遇到這種情況時，是非常需要得到所有相關訊息以便解決問題。
若遇到這種無解的問題或再次發生的話，就必須要 re-open(重新開啟) 該 PR，以待解決。</para>
</note>
<note>
<para>PR 上所附的 <quote>email address</quote> 可能因某些原因而無法收信時，遇到這種狀況，通常就是
followup 該 PR ，並(在 followup 時)請回報者重新提供可正常收信的 email address。
當系統上的 mail 系統關閉或沒裝的時候，這通常是在使用 &man.send-pr.1; 的替代方案。</para>
</note>
</section>
<section id="pr-states">
<title>問題回報(PR)的狀態</title>
<para>若 PR 有任何變化的話，請務必記得更新 PR 的『狀態(state)』。
『狀態』應該要能正確反映該 PR 的目前進度才是。</para>
<example>
<title>以下是更改 PR 狀態的小例子：</title>
<para>當有可以修正問題的 PR 出現，而相關負責的 developer(s)
也覺得這樣的修正可以接受，他們會 followup 該 PR，並將其狀態改為
<quote>feedback</quote>。同時，回報者應重新評估最終的修正結果，並回應：所回報的錯誤是否已成功修正。</para>
</example>
<para>每份 PR 通常會有下面這幾種狀態之一：</para>
<glosslist>
<glossentry>
<glossterm>open</glossterm>
<glossdef>
<para>PR 最初的狀態：這個問題被提出來，並在等待處理中。</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>analyzed</glossterm>
<glossdef>
<para>已經開始處理這問題，並且有找到疑似解決的方法。</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>feedback</glossterm>
<glossdef>
<para>需要回報者提供更詳細的相關資料，正如教學要因材施教，治病也要因人下藥，越多相關訊息，才能有最佳效果。</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>patched</glossterm>
<glossdef>
<para>已經送相關 patch 了，但仍因某些原因(MFC，或來自回報者的確認結果異常)因此尚未完畢。</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>suspended(暫緩)</glossterm>
<glossdef>
<para>因為沒附上相關訊息或參考資料，所以還沒辦法處理這問題。
This is a prime candidate for
somebody who is looking for a project to take on. If the
problem cannot be solved at all, it will be closed, rather
than suspended. The documentation project uses
<quote>suspended</quote> for <quote>wish-list</quote>
items that entail a significant amount of work which no one
currently has time for.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>closed</glossterm>
<glossdef>
<para>A problem report is closed when any changes have been
integrated, documented, and tested, or when fixing the
problem is abandoned.</para>
</glossdef>
</glossentry>
</glosslist>
<note>
<para>The <quote>patched</quote> state is directly related to
feedback, so you may go directly to <quote>closed</quote> state if
the originator cannot test the patch, and it works in your own testing.</para>
</note>
</section>
<section id="pr-types">
<title>問題回報(PR)的種類</title>
<para>While handling problem reports, either as a developer who has
direct access to the GNATS database or as a contributor who
browses the database and submits followups with patches, comments,
suggestions or change requests, you will come across several
different types of PRs.</para>
<itemizedlist>
<listitem>
<para><link linkend="pr-unassigned">PRs not yet assigned to anyone.</link></para>
</listitem>
<listitem>
<para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
</listitem>
<listitem>
<para><link linkend="pr-dups">重複的 PR</link></para>
</listitem>
<listitem>
<para><link linkend="pr-stale">Stale PRs</link></para>
</listitem>
<listitem>
<para><link linkend="pr-misfiled">Misfiled PRs</link></para>
</listitem>
</itemizedlist>
<para>The following sections describe what each different type of
PRs is used for, when a PR belongs to one of these types, and what
treatment each different type receives.</para>
<section id="pr-unassigned">
<title>Unassigned PRs</title>
<para>When PRs arrive, they are initially assigned to a generic
(placeholder) assignee. These are always prepended with
<literal>freebsd-</literal>. The exact value for this default
depends on the category; in most cases, it corresponds to a
specific &os; mailing list. Here is the current list, with
the most common ones listed first:</para>
<table id=default-assignees-common>
<title>Default Assignees &mdash; most common</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Categories</entry>
<entry>Default Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>base system</entry>
<entry>bin, conf, gnu, kern, misc</entry>
<entry>freebsd-bugs</entry>
</row>
<row>
<entry>architecture-specific</entry>
<entry>alpha, i386, ia64, powerpc, sparc64</entry>
<entry>freebsd-<replaceable>arch</replaceable></entry>
</row>
<row>
<entry>ports collection</entry>
<entry>ports</entry>
<entry>freebsd-ports-bugs</entry>
</row>
<row>
<entry>documentation shipped with the system</entry>
<entry>docs</entry>
<entry>freebsd-doc</entry>
</row>
<row>
<entry>&os; web pages (not including docs)</entry>
<entry>www</entry>
<entry>freebsd-www</entry>
</row>
</tbody>
</table>
<table id=default-assignees-other>
<title>Default Assignees &mdash; other</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Categories</entry>
<entry>Default Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>advocacy efforts</entry>
<entry>advocacy</entry>
<entry>freebsd-advocacy</entry>
</row>
<row>
<entry>&java.virtual.machine; problems</entry>
<entry>java</entry>
<entry>freebsd-java</entry>
</row>
<row>
<entry>standards compliance</entry>
<entry>standards</entry>
<entry>freebsd-standards</entry>
</row>
<row>
<entry>threading libraries</entry>
<entry>threads</entry>
<entry>freebsd-threads</entry>
</row>
<row>
<entry>&man.usb.4; subsystem</entry>
<entry>usb</entry>
<entry>freebsd-usb</entry>
</row>
</tbody>
</table>
<para>Do not be surprised to find that the submitter of the
PR has assigned it to the wrong category. If you fix the
category, do not forget to fix the assignment as well.
(In particular, our submitters seem to have a hard time
understanding that just because their problem manifested
on an i386 system, that it might be generic to all of &os;,
and thus be more appropriate for <literal>kern</literal>.
The converse is also true, of course.)</para>
<para>Certain PRs may be reassigned away from these generic
assignees by anyone. For assignees which are mailing lists,
please use the long form when making the assignment (e.g.,
<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
this will avoid duplicate emails sent to the mailing list.</para>
<note>
<para>Here is a sample list of such entities; it is probably
not complete. In some cases, entries that have the short form are
<emphasis>aliases</emphasis>, not mailing lists.</para>
</note>
<table id=common-assignees-base>
<title>Common Assignees &mdash; base system</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Suggested Category</entry>
<entry>Suggested Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>problem specific to the &arm; architecture</entry>
<entry>kern</entry>
<entry>freebsd-arm</entry>
</row>
<row>
<entry>problem specific to the &mips; architecture</entry>
<entry>kern</entry>
<entry>freebsd-mips</entry>
</row>
<row>
<entry>problem specific to the &powerpc; architecture</entry>
<entry>kern</entry>
<entry>freebsd-ppc</entry>
</row>
<row>
<entry>problem with Advanced Configuration and Power
Management (&man.acpi.4;)</entry>
<entry>kern</entry>
<entry>freebsd-acpi</entry>
</row>
<row>
<entry>problem with Asynchronous Transfer Mode (ATM)
drivers</entry>
<entry>kern</entry>
<entry>freebsd-atm</entry>
</row>
<row>
<entry>problem with &firewire; drivers</entry>
<entry>kern</entry>
<entry>freebsd-firewire</entry>
</row>
<row>
<entry>problem with the filesystem code</entry>
<entry>kern</entry>
<entry>freebsd-fs</entry>
</row>
<row>
<entry>problem with the &man.geom.4; subsystem</entry>
<entry>kern</entry>
<entry>freebsd-geom</entry>
</row>
<row>
<entry>problem with the &man.ipfw.4; subsystem</entry>
<entry>kern</entry>
<entry>freebsd-ipfw</entry>
</row>
<row>
<entry>problem with Integrated Services Digital Network
(ISDN) drivers</entry>
<entry>kern</entry>
<entry>freebsd-isdn</entry>
</row>
<row>
<entry>problem with &linux; or SVR4 emulation</entry>
<entry>kern</entry>
<entry>freebsd-emulation</entry>
</row>
<row>
<entry>problem with the networking stack</entry>
<entry>kern</entry>
<entry>freebsd-net</entry>
</row>
<row>
<entry>problem with PicoBSD</entry>
<entry>kern</entry>
<entry>freebsd-small</entry>
</row>
<row>
<entry>problem with the &man.pf.4; subsystem</entry>
<entry>kern</entry>
<entry>freebsd-pf</entry>
</row>
<row>
<entry>problem with the &man.scsi.4; subsystem</entry>
<entry>kern</entry>
<entry>freebsd-scsi</entry>
</row>
<row>
<entry>problem with the &man.sound.4; subsystem</entry>
<entry>kern</entry>
<entry>freebsd-multimedia</entry>
</row>
<row>
<entry>problem with &man.sysinstall.8;</entry>
<entry>bin</entry>
<entry>freebsd-qa</entry>
</row>
<row>
<entry>problem with the system startup scripts
(&man.rc.8;)</entry>
<entry>kern</entry>
<entry>freebsd-rc</entry>
</row>
</tbody>
</table>
<table id=common-assignees-ports>
<title>Common Assignees &mdash; Ports Collection</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Suggested Category</entry>
<entry>Suggested Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>problem with the ports framework
(<emphasis>not</emphasis> with an individual port!)</entry>
<entry>ports</entry>
<entry>portmgr</entry>
</row>
<row>
<entry>port which is maintained by apache@FreeBSD.org</entry>
<entry>ports</entry>
<entry>apache</entry>
</row>
<row>
<entry>port which is maintained by eclipse@FreeBSD.org</entry>
<entry>ports</entry>
<entry>freebsd-eclipse</entry>
</row>
<row>
<entry>port which is maintained by gnome@FreeBSD.org</entry>
<entry>ports</entry>
<entry>gnome</entry>
</row>
<row>
<entry>port which is maintained by haskell@FreeBSD.org</entry>
<entry>ports</entry>
<entry>haskell</entry>
</row>
<row>
<entry>port which is maintained by java@FreeBSD.org</entry>
<entry>ports</entry>
<entry>freebsd-java</entry>
</row>
<row>
<entry>port which is maintained by kde@FreeBSD.org</entry>
<entry>ports</entry>
<entry>kde</entry>
</row>
<row>
<entry>port which is maintained by
openoffice@FreeBSD.org</entry>
<entry>ports</entry>
<entry>freebsd-openoffice</entry>
</row>
<row>
<entry>port which is maintained by perl@FreeBSD.org</entry>
<entry>ports</entry>
<entry>perl</entry>
</row>
<row>
<entry>port which is maintained by python@FreeBSD.org</entry>
<entry>ports</entry>
<entry>freebsd-python</entry>
</row>
<row>
<entry>port which is maintained by x11@FreeBSD.org</entry>
<entry>ports</entry>
<entry>freebsd-x11</entry>
</row>
</tbody>
</table>
<para>Ports PRs which have a maintainer who is a ports committer
may be reassigned by anyone (but note that not every &os;
committer is necessarily a ports committer, so you cannot
simply go by the email address alone.)
</para>
<para>For other PRs, please do not reassign them to individuals
(other than yourself) unless you are certain that the assignee
really wants to track the PR. This will help to avoid the
case where no one looks at fixing a particular problem
because everyone assumes that the assignee is already working
on it.</para>
</section>
<section id="pr-assigned">
<title>Assigned PRs</title>
<para>If a PR has the <literal>responsible</literal> field set
to the username of a FreeBSD developer, it means that the PR
has been handed over to that particular person for further
work.</para>
<para>Assigned PRs should not be touched by anyone but the
assignee. If you have comments, submit a followup. If for
some reason you think the PR should change state or be
reassigned, send a message to the assignee. If the assignee
does not respond within two weeks, unassign the PR and do as
you please.</para>
</section>
<section id="pr-dups">
<title>重複的 PR</title>
<para>If you find more than one PR that describe the same issue,
choose the one that contains the largest amount of useful
information and close the others, stating clearly the number
of the superseding PR. If several PRs contain non-overlapping
useful information, submit all the missing information to one
in a followup, including references to the others; then close
the other PRs (which are now completely superseded).</para>
</section>
<section id="pr-stale">
<title>Stale PRs</title>
<para>A PR is considered stale if it has not been modified in more
than six months. Apply the following procedure to deal with
stale PRs:</para>
<itemizedlist>
<listitem>
<para>If the PR contains sufficient detail, try to reproduce
the problem in <literal>-CURRENT</literal> and
<literal>-STABLE</literal>. If you succeed, submit a
followup detailing your findings and try to find someone
to assign it to. Set the state to <quote>analyzed</quote>
if appropriate.</para>
</listitem>
<listitem>
<para>If the PR describes an issue which you know is the
result of a usage error (incorrect configuration or
otherwise), submit a followup explaining what the
originator did wrong, then close the PR with the reason
<quote>User error</quote> or <quote>Configuration
error</quote>.</para>
</listitem>
<listitem>
<para>If the PR describes an error which you know has been
corrected in both <literal>-CURRENT</literal> and
<literal>-STABLE</literal>, close it with a message
stating when it was fixed in each branch.</para>
</listitem>
<listitem>
<para>If the PR describes an error which you know has been
corrected in <literal>-CURRENT</literal>, but not in
<literal>-STABLE</literal>, try to find out when the person
who corrected it is planning to MFC it, or try to find
someone else (maybe yourself?) to do it. Set the state to
<quote>feedback</quote> and assign it to whomever will do
the MFC.</para>
</listitem>
<listitem>
<para>In other cases, ask the originator to confirm if
the problem still exists in newer versions. If the
originator does not reply within a month, close the PR
with the notation <quote>Feedback timeout</quote>.</para>
</listitem>
</itemizedlist>
</section>
<section id="pr-misfiled">
<title>Misfiled PRs</title>
<para>GNATS is picky about the format of a submitted bug report.
This is why a lot of PRs end up being <quote>misfiled</quote> if
the submitter forgets to fill in a field or puts the wrong sort of
data in some of the PR fields. This section aims to provide most
of the necessary details for FreeBSD developers that can help them to
close or refile these PRs.</para>
<para>When GNATS cannot deduce what to do with a problem report
that reaches the database, it sets the responsible of the PR to
<literal>gnats-admin</literal> and files it under the
<literal>pending</literal> category. This is now a
<quote>misfiled</quote> PR and will not appear in bug report
listings, unless someone explicitly asks for a list of all the
misfiled PRs. If you have access to the FreeBSD cluster
machines, you can use <command>query-pr</command> to view a
listing of PRs that have been misfiled:</para>
<screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput>
52458 gnats-ad open serious medium Re: declaration clash f
52510 gnats-ad open serious medium Re: lots of sockets in
52557 gnats-ad open serious medium
52570 gnats-ad open serious medium Jigdo maintainer update</screen>
<para>Commonly PRs like the ones shown above are misfiled for one
of the following reasons:</para>
<itemizedlist>
<listitem>
<para>A followup to an existing PR, sent through email, has
the wrong format on its <literal>Subject:</literal>
header.</para>
</listitem>
<listitem>
<para>A submitter sent a Cc: to a mailing list and someone
followed up to that post instead of the email issued by
GNATS after processing. The email to the list will not
have the category/PRnumber tracking tag. (This is why we
discourage submitters from doing this exact thing.)</para>
</listitem>
<listitem>
<para>When completing the &man.send-pr.1; template, the submitter
forgot to set the category or class of the PR to a proper
value.</para>
</listitem>
<listitem>
<para>When completing the &man.send-pr.1; template, the submitter
set Confidential to <literal>yes</literal>. (Since we allow
anyone to mirror GNATS via <application>cvsup</application>,
our PRs are public information. Security alerts should
therefore not be sent via GNATS but instead via email to
the Security Team.)</para>
</listitem>
<listitem>
<para>It is not a real PR, but some random message sent to
<email>bug-followup@FreeBSD.org</email> or
<email>freebsd-gnats-submit@FreeBSD.org</email>.</para>
</listitem>
</itemizedlist>
<section id="pr-misfiled-followups">
<title>Followups misfiled as new PRs</title>
<para>The first category of misfiled PRs, the one with the wrong
subject header, is actually the one that requires the greatest
amount of work from developers. These are not real PRs,
describing separate problem reports. When a reply is received
for an existing PR at one of the addresses that GNATS
<quote>listens</quote> to for incoming messages, the subject
of the reply should always be of the form:</para>
<programlisting>Subject: Re: category/number: old synopsis text</programlisting>
<para>Most mailers will add the
<quote><literal>Re:&nbsp;</literal></quote> part when you
reply to the original mail message of a PR. The
<quote><literal>category/number:&nbsp;</literal></quote> part
is a GNATS-specific convention that you have to manually
insert to the subject of your followup reports.</para>
<para>Any FreeBSD developer, who has direct access to the GNATS
database, can periodically check for PRs of this sort and move
interesting bits of the misfiled PR into the audit trail of
the original PR (by posting a proper followup to a bug report
to the address &a.bugfollowup;). Then
the misfiled PR can be closed with a message similar
to:</para>
<programlisting>Your problem report was misfiled. Please use the format
"Subject: category/number: original text" when following
up to older, existing PRs. I've added the relevant bits
from the body of this PR to kern/12345</programlisting>
<para>Searching with <command>query-pr</command> for the
original PR, of which a misfiled followup is a reply, is as
easy as running:</para>
<screen>&prompt.user; query-pr -q -y "some text"</screen>
<para>After you locate the original PR and the misfiled
followups, use the <option>-F</option> option of
<command>query-pr</command> to save the full text of all the
relevant PRs in a &unix; mailbox file, i.e.:</para>
<screen>&prompt.user; <userinput>query-pr -F 52458 52474 &gt; mbox</userinput></screen>
<para>Now you can use any mail user agent to view all the PRs
you saved in <filename>mbox</filename>. Copy the text of all
the misfiled PRs in a followup to the original PR and make
sure you include the proper <literal>Subject:</literal>
header. Then close the misfiled PRs. When you close the misfiled
PRs remember that the submitter receives a mail notification that
his PR changed state to <quote>closed</quote>. Make sure you
provide enough details in the log about the reason of this state
change. Typically something like the following is ok:</para>
<programlisting>Followup to ports/45364 misfiled as a new PR.
This was misfiled because the subject did not have the format:
Re: ports/45364: ...</programlisting>
<para>This way the submitter of the misfiled PR will know what to
avoid the next time a followup to an existing PR is sent.</para>
</section>
<section id="pr-misfiled-format">
<title>PRs misfiled because of missing fields</title>
<para>The second type of misfiled PRs is usually the result of a
submitter forgetting to fill all the necessary fields when
writing the original PR.</para>
<para>Missing or bogus <quote>category</quote> or
<quote>class</quote> fields can result in a misfiled report.
Developers can use &man.edit-pr.1; to change the category or
class of these misfiled PRs to a more appropriate value and
save the PR.</para>
<para>Another common cause of misfiled PRs because of formatting
issues is quoting, changes or removal of the
<command>send-pr</command> template, either by the user who
edits the template or by mailers which do strange things to
plain text messages. This does not happen a lot of the time,
but it can be fixed with <command>edit-pr</command> too; it
does require a bit of work from the developer who refiles the
PR, but it is relatively easy to do most of the time.</para>
</section>
<section id="pr-misfiled-notpr">
<title>Misfiled PRs that are not really problem reports</title>
<para>Sometimes a user wants to submit a report for a problem
and sends a simple email message to GNATS. The GNATS scripts
will recognize bug reports that are formatted using the
&man.send-pr.1; template. They cannot parse any sort of email
though. This is why submissions of bug reports that are sent
to <email>freebsd-gnats-submit@FreeBSD.org</email> have to
follow the template of <command>send-pr</command>, but email
reports can be sent to &a.bugs;.</para>
<para>Developers that come across PRs that look like they should have
been posted to &a.bugs.name; or some other list should close the
PR, informing the submitter in their state-change log why this
is not really a PR and where the message should be posted.</para>
<para>The email addresses that GNATS listens to for incoming PRs
have been published as part of the FreeBSD documentation, have
been announced and listed on the web-site. This means that
spammers found them. Spam messages
that reach GNATS are promptly filed
under the <quote>pending</quote> category until someone looks
at them. Closing one of these with &man.edit-pr.1; is very
annoying though, because GNATS replies to the submitter and
the sender's address of spam mail is never valid these days.
Bounces will come back for each PR that is closed.</para>
<para>Currently, with the installation of some antispam filters
that check all submissions to the GNATS database, the amount
of spam that reaches the <quote>pending</quote> state is very
small.</para>
<para>All developers who have access to the FreeBSD.org cluster
machines are encouraged to check for misfiled PRs and immediately
close those that are spam mail. Whenever you close one of
these PRs, please do the following:
<itemizedlist>
<listitem>
<para>Set Category to <literal>junk</literal>.</para>
</listitem>
<listitem>
<para>Set Confidential to <literal>no</literal>.</para>
</listitem>
<listitem>
<para>Set Responsible to yourself (and not, e.g.,
<literal>freebsd-bugs</literal>, which merely
sends more mail).</para>
</listitem>
<listitem>
<para>Set State to <literal>closed</literal>.</para>
</listitem>
</itemizedlist>
<para>Junk PRs are not
backed up, so filing spam mail under this category makes it
obvious that we do not care to keep it around or waste disk
space for it. If you merely close them without changing the
category, they remain both in the master database and in
any copies of the database mirrored through
<application>cvsup</application>.</para>
</section>
</section>
</section>
<section id="references">
<title>延伸閱讀</title>
<para>下面這是在寫、處理 PR 時，可以參考的資料。當然很明顯，這份清單仍須補充。</para>
<itemizedlist>
<listitem>
<para><ulink
url="&url.articles.problem-reports;/article.html">How to
Write FreeBSD Problem Reports</ulink>&mdash;給 PR 回報者用的參考原則。</para>
</listitem>
</itemizedlist>
</section>
</article>

19
zh_TW.Big5/articles/problem-reports/Makefile Normal file
View file

@ -0,0 +1,19 @@
#
# $FreeBSD$
#
# Article: Writing FreeBSD Problem Reports
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

1113
zh_TW.Big5/articles/problem-reports/article.sgml Normal file
View file

File diff suppressed because it is too large Load diff

5
zh_TW.Big5/books/Makefile
View file

@ -1,12 +1,13 @@
# $FreeBSD$
SUBDIR = faq
SUBDIR = developers-handbook
SUBDIR+= faq
SUBDIR+= fdp-primer
SUBDIR+= handbook
SUBDIR+= porters-handbook
#SUBDIR+= zh-tut
ROOT_SYMLINKS = faq
ROOT_SYMLINKS = faq fdp-primer handbook porters-handbook
DOC_PREFIX?= ${.CURDIR}/../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

45
zh_TW.Big5/books/developers-handbook/Makefile Normal file
View file

@ -0,0 +1,45 @@
#
# $FreeBSD$
#
# Build the FreeBSD Developers' Handbook.
#
MAINTAINER=doc@FreeBSD.org
DOC?= book
FORMATS?= html-split
HAS_INDEX= true
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
# Images
IMAGES_EN= sockets/layers.eps sockets/sain.eps sockets/sainfill.eps sockets/sainlsb.eps sockets/sainmsb.eps sockets/sainserv.eps sockets/serv.eps sockets/serv2.eps sockets/slayers.eps
#
# SRCS lists the individual SGML files that make up the document. Changes
# to any of these files will force a rebuild
#
# SGML content
SRCS= book.sgml
SRCS+= dma/chapter.sgml
SRCS+= introduction/chapter.sgml
SRCS+= ipv6/chapter.sgml
SRCS+= kerneldebug/chapter.sgml
SRCS+= l10n/chapter.sgml
SRCS+= policies/chapter.sgml
SRCS+= secure/chapter.sgml
SRCS+= sockets/chapter.sgml
SRCS+= testing/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= x86/chapter.sgml
# Entities
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

228
zh_TW.Big5/books/developers-handbook/book.sgml Normal file
View file

@ -0,0 +1,228 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % books.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN">
%books.ent;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
<!ENTITY % chap.index "IGNORE">
]>
<book>
<bookinfo>
<title>FreeBSD Developers' Handbook</title>
<corpauthor>The FreeBSD Documentation Project</corpauthor>
<pubdate>August 2000</pubdate>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
&bookinfo.legalnotice;
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.apple;
&tm-attrib.ibm;
&tm-attrib.ieee;
&tm-attrib.intel;
&tm-attrib.linux;
&tm-attrib.microsoft;
&tm-attrib.opengroup;
&tm-attrib.sun;
&tm-attrib.general;
</legalnotice>
<abstract>
<para>Welcome to the Developers' Handbook. This manual is a
<emphasis>work in progress</emphasis> and is the work of many
individuals. Many sections do not yet exist and some of those
that do exist need to be updated. If you are interested in
helping with this project, send email to the &a.doc;.</para>
<para>The latest version of this document is always available
from the <ulink url="&url.base;/index.html">FreeBSD World
Wide Web server</ulink>. It may also be downloaded in a
variety of formats and compression options from the <ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP
server</ulink> or one of the numerous <ulink
url="&url.books.handbook;/mirrors-ftp.html">mirror
sites</ulink>.</para>
</abstract>
</bookinfo>
<part id="Basics">
<title>Basics</title>
&chap.introduction;
&chap.tools;
&chap.secure;
&chap.l10n;
&chap.policies;
&chap.testing;
</part>
<part id="ipc">
<title>Interprocess Communication</title>
&chap.sockets;
&chap.ipv6;
</part>
<part id="kernel">
<title>Kernel</title>
&chap.dma;
&chap.kerneldebug;
</part>
<part id="architectures">
<title>Architectures</title>
&chap.x86;
</part>
<part id="appendices">
<title>Appendices</title>
<bibliography>
<biblioentry id="COD" xreflabel="1">
<authorgroup>
<author>
<firstname>Dave</firstname>
<othername role="MI">A</othername>
<surname>Patterson</surname>
</author>
<author>
<firstname>John</firstname>
<othername role="MI">L</othername>
<surname>Hennessy</surname>
</author>
</authorgroup>
<copyright><year>1998</year><holder>Morgan Kaufmann Publishers,
Inc.</holder></copyright>
<isbn>1-55860-428-6</isbn>
<publisher>
<publishername>Morgan Kaufmann Publishers, Inc.</publishername>
</publisher>
<title>Computer Organization and Design</title>
<subtitle>The Hardware / Software Interface</subtitle>
<pagenums>1-2</pagenums>
</biblioentry>
<biblioentry xreflabel="2">
<authorgroup>
<author>
<firstname>W.</firstname>
<othername role="Middle">Richard</othername>
<surname>Stevens</surname>
</author>
</authorgroup>
<copyright><year>1993</year><holder>Addison Wesley Longman,
Inc.</holder></copyright>
<isbn>0-201-56317-7</isbn>
<publisher>
<publishername>Addison Wesley Longman, Inc.</publishername>
</publisher>
<title>Advanced Programming in the Unix Environment</title>
<pagenums>1-2</pagenums>
</biblioentry>
<biblioentry xreflabel="3">
<authorgroup>
<author>
<firstname>Marshall</firstname>
<othername role="Middle">Kirk</othername>
<surname>McKusick</surname>
</author>
<author>
<firstname>Keith</firstname>
<surname>Bostic</surname>
</author>
<author>
<firstname>Michael</firstname>
<othername role="MI">J</othername>
<surname>Karels</surname>
</author>
<author>
<firstname>John</firstname>
<othername role="MI">S</othername>
<surname>Quarterman</surname>
</author>
</authorgroup>
<copyright><year>1996</year><holder>Addison-Wesley Publishing Company,
Inc.</holder></copyright>
<isbn>0-201-54979-4</isbn>
<publisher>
<publishername>Addison-Wesley Publishing Company, Inc.</publishername>
</publisher>
<title>The Design and Implementation of the 4.4 BSD Operating System</title>
<pagenums>1-2</pagenums>
</biblioentry>
<biblioentry id="Phrack" xreflabel="4">
<authorgroup>
<author>
<firstname>Aleph</firstname>
<surname>One</surname>
</author>
</authorgroup>
<title>Phrack 49; "Smashing the Stack for Fun and Profit"</title>
</biblioentry>
<biblioentry id="StackGuard" xreflabel="5">
<authorgroup>
<author>
<firstname>Chrispin</firstname>
<surname>Cowan</surname>
</author>
<author>
<firstname>Calton</firstname>
<surname>Pu</surname>
</author>
<author>
<firstname>Dave</firstname>
<surname>Maier</surname>
</author>
</authorgroup>
<title>StackGuard; Automatic Adaptive Detection and Prevention of
Buffer-Overflow Attacks</title>
</biblioentry>
<biblioentry id="OpenBSD" xreflabel="6">
<authorgroup>
<author>
<firstname>Todd</firstname>
<surname>Miller</surname>
</author>
<author>
<firstname>Theo</firstname>
<surname>de Raadt</surname>
</author>
</authorgroup>
<title>strlcpy and strlcat -- consistent, safe string copy and
concatenation.</title>
</biblioentry>
</bibliography>
<![ %chap.index; [ &chap.index; ]]>
</part>
</book>

32
zh_TW.Big5/books/developers-handbook/chapters.ent Normal file
View file

@ -0,0 +1,32 @@
<!--
Creates entities for each chapter in the FreeBSD Developer's
Handbook. Each entity is named chap.foo, where foo is the value
of the id attribute on that chapter, and corresponds to the name of
the directory in which that chapter's .sgml file is stored.
Chapters should be listed in the order in which they are referenced.
$FreeBSD$
-->
<!-- Part one -->
<!ENTITY chap.introduction SYSTEM "introduction/chapter.sgml">
<!ENTITY chap.tools SYSTEM "tools/chapter.sgml">
<!ENTITY chap.secure SYSTEM "secure/chapter.sgml">
<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml">
<!ENTITY chap.policies SYSTEM "policies/chapter.sgml">
<!ENTITY chap.testing SYSTEM "testing/chapter.sgml">
<!-- Part two - IPC -->
<!ENTITY chap.sockets SYSTEM "sockets/chapter.sgml">
<!ENTITY chap.ipv6 SYSTEM "ipv6/chapter.sgml">
<!-- Part three - Kernel -->
<!ENTITY chap.dma SYSTEM "dma/chapter.sgml">
<!ENTITY chap.kerneldebug SYSTEM "kerneldebug/chapter.sgml">
<!-- Part five - Architectures -->
<!ENTITY chap.x86 SYSTEM "x86/chapter.sgml">
<!-- Part six - Appendices -->
<!ENTITY chap.index SYSTEM "index.sgml">

1326
zh_TW.Big5/books/developers-handbook/dma/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

225
zh_TW.Big5/books/developers-handbook/introduction/chapter.sgml Normal file
View file

@ -0,0 +1,225 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="introduction">
<chapterinfo>
<authorgroup>
<author>
<firstname>Murray</firstname>
<surname>Stokely</surname>
<contrib>Contributed by </contrib>
</author>
<author>
<firstname>Jeroen</firstname>
<surname>Ruigrok van der Werven</surname>
</author>
</authorgroup>
</chapterinfo>
<title>Introduction</title>
<sect1 id="introduction-devel">
<title>Developing on FreeBSD</title>
<para>So here we are. System all installed and you are ready to
start programming. But where to start? What does FreeBSD
provide? What can it do for me, as a programmer?</para>
<para>These are some questions which this chapter tries to answer.
Of course, programming has different levels of proficiency like
any other trade. For some it is a hobby, for others it is their
profession. The information in this chapter might be aimed
toward the beginning programmer; indeed, it could serve useful
for the programmer unfamiliar with the &os; platform.</para>
</sect1>
<sect1 id="introduction-bsdvision">
<title>The BSD Vision</title>
<para>To produce the best &unix; like operating system package
possible, with due respect to the original software tools
ideology as well as usability, performance and
stability.</para>
</sect1>
<sect1 id="introduction-archguide">
<title>Architectural Guidelines</title>
<para>Our ideology can be described by the following
guidelines</para>
<itemizedlist>
<listitem><para>Do not add new functionality unless an
implementor cannot complete a real application without
it.</para></listitem>
<listitem><para>It is as important to decide what a system is
not as to decide what it is. Do not serve all the world's
needs; rather, make the system extensible so that additional
needs can be met in an upwardly compatible
fashion.</para></listitem>
<listitem><para>The only thing worse than generalizing from one
example is generalizing from no examples at
all. </para></listitem>
<listitem><para>If a problem is not completely understood, it is
probably best to provide no solution at all.</para></listitem>
<listitem><para>If you can get 90 percent of the desired effect
for 10 percent of the work, use the simpler
solution.</para></listitem>
<listitem><para>Isolate complexity as much as
possible.</para></listitem>
<listitem><para>Provide mechanism, rather than policy. In
particular, place user interface policy in the client's
hands.</para></listitem>
</itemizedlist>
<para>From Scheifler & Gettys: "X Window System"</para>
</sect1>
<sect1 id="introduction-layout">
<title>The Layout of
<filename class="directory">/usr/src</filename></title>
<para>The complete source code to FreeBSD is available from our
public CVS repository. The source code is normally installed in
<filename class="directory">/usr/src</filename> which contains the
following subdirectories:</para>
<para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<thead>
<row>
<entry>Directory</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><filename class="directory">bin/</filename></entry>
<entry>Source for files in
<filename>/bin</filename></entry>
</row>
<row>
<entry><filename class="directory">contrib/</filename></entry>
<entry>Source for files from contributed software.</entry>
</row>
<row>
<entry><filename class="directory">crypto/</filename></entry>
<entry>Cryptographical sources</entry>
</row>
<row>
<entry><filename class="directory">etc/</filename></entry>
<entry>Source for files in <filename
class="directory">/etc</filename></entry>
</row>
<row>
<entry><filename class="directory">games/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/games</filename></entry>
</row>
<row>
<entry><filename class="directory">gnu/</filename></entry>
<entry>Utilities covered by the GNU Public License</entry>
</row>
<row>
<entry><filename class="directory">include/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/include</filename></entry>
</row>
<row>
<entry><filename
class="directory">kerberos5/</filename></entry>
<entry>Source for Kerberos version 5</entry>
</row>
<row>
<entry><filename class="directory">lib/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/lib</filename></entry>
</row>
<row>
<entry><filename class="directory">libexec/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/libexec</filename></entry>
</row>
<row>
<entry><filename
class="directory">release/</filename></entry>
<entry>Files required to produce a FreeBSD release</entry>
</row>
<row>
<entry><filename class="directory">rescue/</filename></entry>
<entry>Build system for the
<filename class="directory">/rescue</filename> utilities</entry>
</row>
<row>
<entry><filename class="directory">sbin/</filename></entry>
<entry>Source for files in <filename
class="directory">/sbin</filename></entry>
</row>
<row>
<entry><filename class="directory">secure/</filename></entry>
<entry>FreeSec sources</entry>
</row>
<row>
<entry><filename class="directory">share/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/share</filename></entry>
</row>
<row>
<entry><filename class="directory">sys/</filename></entry>
<entry>Kernel source files</entry>
</row>
<row>
<entry><filename class="directory">tools/</filename></entry>
<entry>Tools used for maintenance and testing of
FreeBSD</entry>
</row>
<row>
<entry><filename
class="directory">usr.bin/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/bin</filename></entry>
</row>
<row>
<entry><filename
class="directory">usr.sbin/</filename></entry>
<entry>Source for files in <filename
class="directory">/usr/sbin</filename></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</sect1>
</chapter>

1593
zh_TW.Big5/books/developers-handbook/ipv6/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

15
zh_TW.Big5/books/developers-handbook/kerneldebug/Makefile Normal file
View file

@ -0,0 +1,15 @@
#
# Build the Handbook with just the content from this chapter.
#
# $FreeBSD$
#
CHAPTERS= kerneldebug/chapter.sgml
VPATH= ..
MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
DOC_PREFIX?= ${.CURDIR}/../../../..
.include "../Makefile"

868
zh_TW.Big5/books/developers-handbook/kerneldebug/chapter.sgml Normal file
View file

@ -0,0 +1,868 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="kerneldebug">
<chapterinfo>
<authorgroup>
<author>
<firstname>Paul</firstname>
<surname>Richards</surname>
<contrib>Contributed by </contrib>
</author>
<author>
<firstname>J&ouml;rg</firstname>
<surname>Wunsch</surname>
</author>
</authorgroup>
</chapterinfo>
<title>Kernel Debugging</title>
<sect1 id="kerneldebug-obtain">
<title>Obtaining a Kernel Crash Dump</title>
<para>When running a development kernel (eg: &os.current;), such as a
kernel under extreme conditions (eg: very high load averages,
tens of thousands of connections, exceedingly high number of
concurrent users, hundreds of &man.jail.8;s, etc.), or using a
new feature or device driver on &os.stable; (eg:
<acronym>PAE</acronym>), sometimes a kernel will panic. In the
event that it does, this chapter will demonstrate how to extract
useful information out of a crash.</para>
<para>A system reboot is inevitable once a kernel panics. Once a
system is rebooted, the contents of a system's physical memory
(<acronym>RAM</acronym>) is lost, as well as any bits that are
on the swap device before the panic. To preserve the bits in
physical memory, the kernel makes use of the swap device as a
temporary place to store the bits that are in RAM across a
reboot after a crash. In doing this, when &os; boots after a
crash, a kernel image can now be extracted and debugging can
take place.</para>
<note><para>A swap device that has been configured as a dump
device still acts as a swap device. Dumps to non-swap devices
(such as tapes or CDRWs, for example) are not supported at this time. A
<quote>swap device</quote> is synonymous with a <quote>swap
partition.</quote></para></note>
<para>To be able to extract a usable core, it is required that at
least one swap partition be large enough to hold all of the bits
in physical memory. When a kernel panics, before the system
reboots, the kernel is smart enough to check to see if a swap
device has been configured as a dump device. If there is a
valid dump device, the kernel dumps the contents of what is in
physical memory to the swap device.</para>
<sect2 id="config-dumpdev">
<title>Configuring the Dump Device</title>
<para>Before the kernel will dump the contents of its physical
memory to a dump device, a dump device must be configured. A
dump device is specified by using the &man.dumpon.8; command
to tell the kernel where to save kernel crash dumps. The
&man.dumpon.8; program must be called after the swap partition
has been configured with &man.swapon.8;. This is normally
handled by setting the <varname>dumpdev</varname> variable in
&man.rc.conf.5; to the path of the swap device (the
recommended way to extract a kernel dump).</para>
<para>Alternatively, the dump device can be hard-coded via the
<literal>dump</literal> clause in the &man.config.5; line of
a kernel configuration file. This approach is deprecated and should
be used only if a kernel is crashing before &man.dumpon.8; can be executed.</para>
<tip><para>Check <filename>/etc/fstab</filename> or
&man.swapinfo.8; for a list of swap devices.</para></tip>
<important><para>Make sure the <varname>dumpdir</varname>
specified in &man.rc.conf.5; exists before a kernel
crash!</para>
<screen>&prompt.root; <userinput>mkdir /var/crash</userinput>
&prompt.root; <userinput>chmod 700 /var/crash</userinput></screen>
<para>Also, remember that the contents of
<filename>/var/crash</filename> is sensitive and very likely
contains confidential information such as passwords.</para>
</important>
</sect2>
<sect2 id="extract-dump">
<title>Extracting a Kernel Dump</title>
<para>Once a dump has been written to a dump device, the dump
must be extracted before the swap device is mounted.
To extract a dump
from a dump device, use the &man.savecore.8; program. If
<varname>dumpdev</varname> has been set in &man.rc.conf.5;,
&man.savecore.8; will be called automatically on the first
multi-user boot after the crash and before the swap device
is mounted. The location of the extracted core is placed in
the &man.rc.conf.5; value <varname>dumpdir</varname>, by
default <filename>/var/crash</filename> and will be named
<filename>vmcore.0</filename>.</para>
<para>In the event that there is already a file called
<filename>vmcore.0</filename> in
<filename>/var/crash</filename> (or whatever
<varname>dumpdir</varname> is set to), the kernel will
increment the trailing number for every crash to avoid
overwriting an existing <filename>vmcore</filename> (eg:
<filename>vmcore.1</filename>). While debugging, it is
highly likely that you will want to use the highest version
<filename>vmcore</filename> in
<filename>/var/crash</filename> when searching for the right
<filename>vmcore</filename>.</para>
<tip>
<para>If you are testing a new kernel but need to boot a different one in
order to get your system up and running again, boot it only into single
user mode using the <option>-s</option> flag at the boot prompt, and
then perform the following steps:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput> # make sure /var/crash is writable
&prompt.root; <userinput>savecore /var/crash /dev/ad0s1b</userinput>
&prompt.root; <userinput>exit</userinput> # exit to multi-user</screen>
<para>This instructs &man.savecore.8; to extract a kernel dump
from <filename>/dev/ad0s1b</filename> and place the contents in
<filename>/var/crash</filename>. Do not forget to make sure the
destination directory <filename>/var/crash</filename> has enough
space for the dump. Also, do not forget to specify the correct path to your swap
device as it is likely different than
<filename>/dev/ad0s1b</filename>!</para></tip>
<para>The recommended, and certainly the easiest way to automate
obtaining crash dumps is to use the <varname>dumpdev</varname>
variable in &man.rc.conf.5;.</para>
</sect2>
</sect1>
<sect1 id="kerneldebug-gdb">
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<note>
<para>This section covers &man.kgdb.1; as found in &os;&nbsp;5.3
and later. In previous versions, one must use
<command>gdb -k</command> to read a core dump file.</para>
</note>
<para>Once a dump has been obtained, getting useful information
out of the dump is relatively easy for simple problems. Before
launching into the internals of &man.kgdb.1; to debug
the crash dump, locate the debug version of your kernel
(normally called <filename>kernel.debug</filename>) and the path
to the source files used to build your kernel (normally
<filename>/usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></filename>,
where <filename><replaceable>KERNCONF</replaceable></filename>
is the <varname>ident</varname> specified in a kernel
&man.config.5;). With those two pieces of info, let the
debugging commence!</para>
<para>To enter into the debugger and begin getting information
from the dump, the following steps are required at a minimum:</para>
<screen>&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput>
&prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput></screen>
<para>You can debug the crash dump using the kernel sources just like
you can for any other program.</para>
<para>This first dump is from a 5.2-BETA kernel and the crash
comes from deep within the kernel. The output below has been
modified to include line numbers on the left. This first trace
inspects the instruction pointer and obtains a back trace. The
address that is used on line 41 for the <command>list</command>
command is the instruction pointer and can be found on line
17. Most developers will request having at least this
information sent to them if you are unable to debug the problem
yourself. If, however, you do solve the problem, make sure that
your patch winds its way into the source tree via a problem
report, mailing lists, or by being able to commit it!</para>
<screen> 1:&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput>
2:&prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput>
3:GNU gdb 5.2.1 (FreeBSD)
4:Copyright 2002 Free Software Foundation, Inc.
5:GDB is free software, covered by the GNU General Public License, and you are
6:welcome to change it and/or distribute copies of it under certain conditions.
7:Type "show copying" to see the conditions.
8:There is absolutely no warranty for GDB. Type "show warranty" for details.
9:This GDB was configured as "i386-undermydesk-freebsd"...
10:panic: page fault
11:panic messages:
12:---
13:Fatal trap 12: page fault while in kernel mode
14:cpuid = 0; apic id = 00
15:fault virtual address = 0x300
16:fault code: = supervisor read, page not present
17:instruction pointer = 0x8:0xc0713860
18:stack pointer = 0x10:0xdc1d0b70
19:frame pointer = 0x10:0xdc1d0b7c
20:code segment = base 0x0, limit 0xfffff, type 0x1b
21: = DPL 0, pres 1, def32 1, gran 1
22:processor eflags = resume, IOPL = 0
23:current process = 14394 (uname)
24:trap number = 12
25:panic: page fault
26 cpuid = 0;
27:Stack backtrace:
28
29:syncing disks, buffers remaining... 2199 2199 panic: mi_switch: switch in a critical section
30:cpuid = 0;
31:Uptime: 2h43m19s
32:Dumping 255 MB
33: 16 32 48 64 80 96 112 128 144 160 176 192 208 224 240
34:---
35:Reading symbols from /boot/kernel/snd_maestro3.ko...done.
36:Loaded symbols for /boot/kernel/snd_maestro3.ko
37:Reading symbols from /boot/kernel/snd_pcm.ko...done.
38:Loaded symbols for /boot/kernel/snd_pcm.ko
39:#0 doadump () at /usr/src/sys/kern/kern_shutdown.c:240
40:240 dumping++;
41:<prompt>(kgdb)</prompt> <userinput>list *0xc0713860</userinput>
42:0xc0713860 is in lapic_ipi_wait (/usr/src/sys/i386/i386/local_apic.c:663).
43:658 incr = 0;
44:659 delay = 1;
45:660 } else
46:661 incr = 1;
47:662 for (x = 0; x &lt; delay; x += incr) {
48:663 if ((lapic-&gt;icr_lo &amp; APIC_DELSTAT_MASK) == APIC_DELSTAT_IDLE)
49:664 return (1);
50:665 ia32_pause();
51:666 }
52:667 return (0);
53:<prompt>(kgdb)</prompt> <userinput>backtrace</userinput>
54:#0 doadump () at /usr/src/sys/kern/kern_shutdown.c:240
55:#1 0xc055fd9b in boot (howto=260) at /usr/src/sys/kern/kern_shutdown.c:372
56:#2 0xc056019d in panic () at /usr/src/sys/kern/kern_shutdown.c:550
57:#3 0xc0567ef5 in mi_switch () at /usr/src/sys/kern/kern_synch.c:470
58:#4 0xc055fa87 in boot (howto=256) at /usr/src/sys/kern/kern_shutdown.c:312
59:#5 0xc056019d in panic () at /usr/src/sys/kern/kern_shutdown.c:550
60:#6 0xc0720c66 in trap_fatal (frame=0xdc1d0b30, eva=0)
61: at /usr/src/sys/i386/i386/trap.c:821
62:#7 0xc07202b3 in trap (frame=
63: {tf_fs = -1065484264, tf_es = -1065484272, tf_ds = -1065484272, tf_edi = 1, tf_esi = 0, tf_ebp = -602076292, tf_isp = -602076324, tf_ebx = 0, tf_edx = 0, tf_ecx = 1000000, tf_eax = 243, tf_trapno = 12, tf_err = 0, tf_eip = -1066321824, tf_cs = 8, tf_eflags = 65671, tf_esp = 243, tf_ss = 0})
64: at /usr/src/sys/i386/i386/trap.c:250
65:#8 0xc070c9f8 in calltrap () at {standard input}:94
66:#9 0xc07139f3 in lapic_ipi_vectored (vector=0, dest=0)
67: at /usr/src/sys/i386/i386/local_apic.c:733
68:#10 0xc0718b23 in ipi_selected (cpus=1, ipi=1)
69: at /usr/src/sys/i386/i386/mp_machdep.c:1115
70:#11 0xc057473e in kseq_notify (ke=0xcc05e360, cpu=0)
71: at /usr/src/sys/kern/sched_ule.c:520
72:#12 0xc0575cad in sched_add (td=0xcbcf5c80)
73: at /usr/src/sys/kern/sched_ule.c:1366
74:#13 0xc05666c6 in setrunqueue (td=0xcc05e360)
75: at /usr/src/sys/kern/kern_switch.c:422
76:#14 0xc05752f4 in sched_wakeup (td=0xcbcf5c80)
77: at /usr/src/sys/kern/sched_ule.c:999
78:#15 0xc056816c in setrunnable (td=0xcbcf5c80)
79: at /usr/src/sys/kern/kern_synch.c:570
80:#16 0xc0567d53 in wakeup (ident=0xcbcf5c80)
81: at /usr/src/sys/kern/kern_synch.c:411
82:#17 0xc05490a8 in exit1 (td=0xcbcf5b40, rv=0)
83: at /usr/src/sys/kern/kern_exit.c:509
84:#18 0xc0548011 in sys_exit () at /usr/src/sys/kern/kern_exit.c:102
85:#19 0xc0720fd0 in syscall (frame=
86: {tf_fs = 47, tf_es = 47, tf_ds = 47, tf_edi = 0, tf_esi = -1, tf_ebp = -1077940712, tf_isp = -602075788, tf_ebx = 672411944, tf_edx = 10, tf_ecx = 672411600, tf_eax = 1, tf_trapno = 12, tf_err = 2, tf_eip = 671899563, tf_cs = 31, tf_eflags = 642, tf_esp = -1077940740, tf_ss = 47})
87: at /usr/src/sys/i386/i386/trap.c:1010
88:#20 0xc070ca4d in Xint0x80_syscall () at {standard input}:136
89:---Can't read userspace from dump, or kernel process---
90:<prompt>(kgdb)</prompt> <userinput>quit</userinput></screen>
<para>This next trace is an older dump from the FreeBSD 2 time
frame, but is more involved and demonstrates more of the
features of <command>gdb</command>. Long lines have been folded
to improve readability, and the lines are numbered for
reference. Despite this, it is a real-world error trace taken
during the development of the pcvt console driver.</para>
<screen> 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
3:&prompt.root; <userinput>gdb -k kernel /var/crash/vmcore.1</userinput>
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:<prompt>(kgdb)</prompt> <userinput>backtrace</userinput>
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput>
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&amp;frame, FALSE);
36:<prompt>(kgdb)</prompt> <userinput>frame frame-&gt;tf_ebp frame-&gt;tf_eip</userinput>
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
41:<prompt>(kgdb)</prompt> <userinput>list</userinput>
42:398
43:399 tp-&gt;t_state |= TS_CARR_ON;
44:400 tp-&gt;t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD &gt;= 200)
47:403 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp-&gt;t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD &gt;= 200) */
51:407 }
52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput>
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:<prompt>(kgdb)</prompt> <userinput>print tp-&gt;t_line</userinput>
56:$2 = 1767990816
57:<prompt>(kgdb)</prompt> <userinput>up</userinput>
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:<prompt>(kgdb)</prompt> <userinput>up</userinput>
62:#2 0xf0132c34 in spec_open ()
63:<prompt>(kgdb)</prompt> <userinput>up</userinput>
64:#3 0xf012d014 in vn_open ()
65:<prompt>(kgdb)</prompt> <userinput>up</userinput>
66:#4 0xf012a183 in open ()
67:<prompt>(kgdb)</prompt> <userinput>up</userinput>
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp-&gt;sy_call)(p, args, rval);
74:<prompt>(kgdb)</prompt> <userinput>up</userinput>
75:Initial frame selected; you cannot go up.
76:<prompt>(kgdb)</prompt> <userinput>quit</userinput></screen>
<para>Comments to the above script:</para>
<variablelist>
<varlistentry>
<term>line 6:</term>
<listitem>
<para>This is a dump taken from within DDB (see below), hence the
panic comment <quote>because you said to!</quote>, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>line 20:</term>
<listitem>
<para>This is the location of function <function>trap()</function>
in the stack trace.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>line 36:</term>
<listitem>
<para>Force usage of a new stack frame; this is no longer necessary.
The stack frames are supposed to point to the right
locations now, even in case of a trap.
From looking at the code in source line 403, there is a
high probability that either the pointer access for
<quote>tp</quote> was messed up, or the array access was out of
bounds.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>line 52:</term>
<listitem>
<para>The pointer looks suspicious, but happens to be a valid
address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>line 56:</term>
<listitem>
<para>However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
<literal>tp-&gt;t_line</literal> refers to the line discipline of
the console device here, which must be a rather small integer
number.)</para>
</listitem>
</varlistentry>
</variablelist>
<tip><para>If your system is crashing regularly and you are running
out of disk space, deleting old <filename>vmcore</filename>
files in <filename>/var/crash</filename> could save a
considerable amount of disk space!</para></tip>
</sect1>
<sect1 id="kerneldebug-ddd">
<title>Debugging a Crash Dump with DDD</title>
<para>Examining a kernel crash dump with a graphical debugger like
<command>ddd</command> is also possible (you will need to install
the <filename role="package">devel/ddd</filename> port in order to use the
<command>ddd</command> debugger). Add the <option>-k</option>
option to the <command>ddd</command> command line you would use
normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
<para>You should then be able to go about looking at the crash dump using
<command>ddd</command>'s graphical interface.</para>
</sect1>
<sect1 id="kerneldebug-post-mortem">
<title>Post-Mortem Analysis of a Dump</title>
<para>What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
<para>Of course, you still need to enable crash dumps. See above for the
options you have to specify in order to do this.</para>
<para>Go to your kernel config directory
(<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following line:</para>
<programlisting>makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting>
<para>Rebuild the kernel. Due to the time stamp change on the Makefile,
some other object files will be rebuilt, for example
<filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but with some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.</para>
<para>Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files, recompile the kernel again and repeat the
<command>gdb <option>-k</option></command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
cases.</para>
</sect1>
<sect1 id="kerneldebug-online-ddb">
<title>On-Line Kernel Debugging Using DDB</title>
<para>While <command>gdb <option>-k</option></command> as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.</para>
<para>If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows setting of
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like <command>gdb</command> does.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>options DDB</programlisting>
to your config file, and rebuild. (See <ulink
url="&url.books.handbook;/index.html">The FreeBSD Handbook</ulink> for details on
configuring the FreeBSD kernel).</para>
<note>
<para>If you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automatically.</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
<option>-d</option> right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.</para>
<para>The second scenario is to drop to the debugger once the
system has booted. There are two simple ways to accomplish
this. If you would like to break to the debugger from the
command prompt, simply type the command:</para>
<screen>&prompt.root; <userinput>sysctl debug.enter_debugger=ddb</userinput></screen>
<para>Alternatively, if you are at the system console, you may use
a hot-key on the keyboard. The default break-to-debugger
sequence is <keycombo action="simul"><keycap>Ctrl</keycap>
<keycap>Alt</keycap><keycap>ESC</keycap></keycombo>. For
syscons, this sequence can be remapped and some of the
distributed maps out there do this, so check to make sure you
know the right sequence to use. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
in the kernel config file). It is not the default since there are a lot
of serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.</para>
<para>The DDB commands roughly resemble some <command>gdb</command>
commands. The first thing you probably need to do is to set a
breakpoint:</para>
<screen><userinput>b function-name</userinput>
<userinput>b address</userinput></screen>
<para>Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
<literal>a-f</literal> need to be preceded with <literal>0x</literal>
(this is optional for other numbers). Simple expressions are allowed,
for example: <literal>function-name + 0x103</literal>.</para>
<para>To continue the operation of an interrupted kernel, simply
type:</para>
<screen><userinput>c</userinput></screen>
<para>To get a stack trace, use:</para>
<screen><userinput>trace</userinput></screen>
<note>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
to you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
<screen><userinput>del</userinput>
<userinput>del address-expression</userinput></screen>
<para>The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:</para>
<screen><userinput>show b</userinput></screen>
<para>To single-step the kernel, try:</para>
<screen><userinput>s</userinput></screen>
<para>This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:</para>
<screen><userinput>n</userinput></screen>
<note>
<para>This is different from <command>gdb</command>'s
<command>next</command> statement; it is like <command>gdb</command>'s
<command>finish</command>.</para>
</note>
<para>To examine data from memory, use (for example):
<screen><userinput>x/wx 0xf0133fe0,40</userinput>
<userinput>x/hd db_symtab_space</userinput>
<userinput>x/bc termbuf,10</userinput>
<userinput>x/s stringbuf</userinput></screen>
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:</para>
<screen><userinput>x ,10</userinput></screen>
<para>Similarly, use
<screen><userinput>x/ia foofunc,10</userinput></screen>
to disassemble the first 0x10 instructions of
<function>foofunc</function>, and display them along with their offset
from the beginning of <function>foofunc</function>.</para>
<para>To modify memory, use the write command:</para>
<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
<userinput>w/w 0xf0010030 0 0</userinput></screen>
<para>The command modifier
(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.</para>
<para>If you need to know the current registers, use:</para>
<screen><userinput>show reg</userinput></screen>
<para>Alternatively, you can display a single register value by e.g.
<screen><userinput>p $eax</userinput></screen>
and modify it by:</para>
<screen><userinput>set $eax new-value</userinput></screen>
<para>Should you need to call some kernel functions from DDB, simply
say:</para>
<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
<para>The return value will be printed.</para>
<para>For a &man.ps.1; style summary of all running processes, use:</para>
<screen><userinput>ps</userinput></screen>
<para>Now you have examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:</para>
<screen><userinput>panic</userinput></screen>
<para>This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with <command>gdb</command>. This command
usually must be followed by another <command>continue</command>
statement.</para>
<screen><userinput>call boot(0)</userinput></screen>
<para>Which might be a good way to cleanly shut down the running system,
<function>sync()</function> all disks, and finally reboot. As long as
the disk and filesystem interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.</para>
<screen><userinput>call cpu_reset()</userinput></screen>
<para>This is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
<screen><userinput>help</userinput></screen>
<para>However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.</para>
</sect1>
<sect1 id="kerneldebug-online-gdb">
<title>On-Line Kernel Debugging Using Remote GDB</title>
<para>This feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis> for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).</para>
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the configuration, and
compile it as usual. This gives a large binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with <command>strip -x</command>, and boot it
using the <option>-d</option> boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start <command>gdb</command>:</para>
<screen>&prompt.user; <userinput>gdb -k kernel</userinput>
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
<prompt>(kgdb)</prompt> </screen>
<para>Initialize the remote debugging session (assuming the first serial
port is being used) by:</para>
<screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
<para>Now, on the target host (the one that entered DDB right before even
starting the device probe), type:</para>
<screen>Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
<prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
<para>DDB will respond with:</para>
<screen>Next trap will enter GDB remote protocol mode</screen>
<para>Every time you type <command>gdb</command>, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type <command>s</command> (step). Your hosting GDB
will now gain control over the target kernel:</para>
<screen>Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
<prompt>(kgdb)</prompt></screen>
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window), etc.</para>
</sect1>
<sect1 id="kerneldebug-kld">
<title>Debugging Loadable Modules Using GDB</title>
<para>When debugging a panic that occurred within a module, or
using remote GDB against a machine that uses dynamic modules,
you need to tell GDB how to obtain symbol information for those
modules.</para>
<para>First, you need to build the module(s) with debugging
information:</para>
<screen>&prompt.root; <userinput>cd /sys/modules/linux</userinput>
&prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
<para>If you are using remote GDB, you can run
<command>kldstat</command> on the target machine to find out
where the module was loaded:</para>
<screen>&prompt.root; <userinput>kldstat</userinput>
Id Refs Address Size Name
1 4 0xc0100000 1c1678 kernel
2 1 0xc0a9e000 6000 linprocfs.ko
3 1 0xc0ad7000 2000 warp_saver.ko
4 1 0xc0adc000 11000 linux.ko</screen>
<para>If you are debugging a crash dump, you will need to walk the
<literal>linker_files</literal> list, starting at
<literal>linker_files-&gt;tqh_first</literal> and following the
<literal>link.tqe_next</literal> pointers until you find the
entry with the <literal>filename</literal> you are looking for.
The <literal>address</literal> member of that entry is the load
address of the module.</para>
<para>Next, you need to find out the offset of the text section
within the module:</para>
<screen>&prompt.root; <userinput>objdump --section-headers /sys/modules/linux/linux.ko | grep text</userinput>
3 .rel.text 000016e0 000038e0 000038e0 000038e0 2**2
10 .text 00007f34 000062d0 000062d0 000062d0 2**2</screen>
<para>The one you want is the <literal>.text</literal> section,
section 10 in the above example. The fourth hexadecimal field
(sixth field overall) is the offset of the text section within
the file. Add this offset to the load address of the module to
obtain the relocation address for the module's code. In our
example, we get 0xc0adc000 + 0x62d0 = 0xc0ae22d0. Use the
<command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
<screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0</userinput>
add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0?
(y or n) <userinput>y</userinput>
Reading symbols from /sys/modules/linux/linux.ko...done.
<prompt>(kgdb)</prompt></screen>
<para>You should now have access to all the symbols in the
module.</para>
</sect1>
<sect1 id="kerneldebug-console">
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, including a serial
console.</para>
</sect1>
<sect1 id="kerneldebug-deadlocks">
<title>Debugging the Deadlocks</title>
<para>You may experience so called deadlocks, the situation where
system stops doing useful work. To provide the helpful bug report
in this situation, you shall use ddb as described above. Please,
include the output of <command>ps</command> and
<command>trace</command> for suspected processes in the
report.</para>
<para>If possible, consider doing further investigation. Receipt
below is especially useful if you suspect deadlock occurs in the
VFS layer. Add the options
<programlisting>makeoptions DEBUG=-g
options INVARIANTS
options INVARIANT_SUPPORT
options WITNESS
options DEBUG_LOCKS
options DEBUG_VFS_LOCKS
options DIAGNOSTIC</programlisting>
to the kernel config. When deadlock occurs, in addition to the
output of the <command>ps</command> command, provide information
from the <command>show allpcpu</command>, <command>show
alllocks</command>, <command>show lockedvnods</command> and
<command>show alltrace</command>.</para>
<para>For threaded processes, to obtain meaningful backtraces, use
<command>thread thread-id</command> to switch to the thread
stack, and do backtrace with <command>where</command>.</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

81
zh_TW.Big5/books/developers-handbook/l10n/chapter.sgml Normal file
View file

@ -0,0 +1,81 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="l10n">
<title>Localization and Internationalization - L10N and I18N</title>
<sect1 id="l10n-programming">
<title>Programming I18N Compliant Applications</title>
<indexterm><primary>Qt</primary></indexterm>
<indexterm><primary>GTK</primary></indexterm>
<para>To make your application more useful for speakers of other
languages, we hope that you will program I18N compliant. The GNU
gcc compiler and GUI libraries like QT and GTK support I18N through
special handling of strings. Making a program I18N compliant is
very easy. It allows contributors to port your application to
other languages quickly. Refer to the library specific I18N
documentation for more details.</para>
<para>In contrast with common perception, I18N compliant code is
easy to write. Usually, it only involves wrapping your strings
with library specific functions. In addition, please be sure to
allow for wide or multibyte character support.</para>
<sect2>
<title>A Call to Unify the I18N Effort</title>
<para>It has come to our attention that the individual I18N/L10N
efforts for each country has been repeating each others'
efforts. Many of us have been reinventing the wheel repeatedly
and inefficiently. We hope that the various major groups in
I18N could congregate into a group effort similar to the Core
Team's responsibility.</para>
<para>Currently, we hope that, when you write or port I18N
programs, you would send it out to each country's related
FreeBSD mailing list for testing. In the future, we hope to
create applications that work in all the languages
out-of-the-box without dirty hacks.</para>
<para>The &a.i18n; has been established. If you are an I18N/L10N
developer, please send your comments, ideas, questions, and
anything you deem related to it.</para>
<para>Michael C. Wu will be maintaining an I18N works in progress
homepage at <ulink url="http://www.FreeBSD.org/~keichii/i18n/index.html"></ulink>.
Please also read the BSDCon2000 I18N paper and presentations
by Clive Lin, Chia-Liang Kao, and Michael C. Wu at <ulink
url="http://www.FreeBSD.org/~keichii/papers/"></ulink></para>
</sect2>
<sect2>
<title>Perl and Python</title>
<indexterm>
<primary>Perl</primary>
</indexterm>
<indexterm>
<primary>Python</primary>
</indexterm>
<para>Perl and Python have I18N and wide character handling
libraries. Please use them for I18N compliance.</para>
<para>In older FreeBSD versions,
Perl may give warnings about not having a wide character locale
installed on your system. You can set the
environment variable <envar>LD_PRELOAD</envar> to
<filename>/usr/lib/libxpg4.so</filename> in your shell.</para>
<para>In <literal>sh</literal>-based shells:</para>
<programlisting><envar>LD_PRELOAD=/usr/lib/libxpg4.so</envar></programlisting>
<para>In <literal>C</literal>-based shells:</para>
<programlisting><envar>setenv LD_PRELOAD /usr/lib/libxpg4.so</envar></programlisting>
</sect2>
</sect1>
</chapter>

15
zh_TW.Big5/books/developers-handbook/policies/Makefile Normal file
View file

@ -0,0 +1,15 @@
#
# Build the Handbook with just the content from this chapter.
#
# $FreeBSD$
#
CHAPTERS= policies/chapter.sgml
VPATH= ..
MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
DOC_PREFIX?= ${.CURDIR}/../../../..
.include "../Makefile"

434
zh_TW.Big5/books/developers-handbook/policies/chapter.sgml Normal file
View file

@ -0,0 +1,434 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="policies">
<chapterinfo>
<authorgroup>
<author>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
<!-- June 1996 -->
</chapterinfo>
<title>Source Tree Guidelines and Policies</title>
<para>This chapter documents various guidelines and policies in force for
the FreeBSD source tree.</para>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
<indexterm><primary>ports maintainer</primary></indexterm>
<para>If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
<programlisting>MAINTAINER= email-addresses</programlisting>
line to the <filename>Makefile</filename>s covering this portion of the
source tree.</para>
<para>The semantics of this are as follows:</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answering problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.</para>
<para>Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try to have the
changes reviewed by someone else if at all possible.</para>
<para>It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand it
does not have to be a committer and it can easily be a group of
people.</para>
</sect1>
<sect1 id="policies-contributed">
<sect1info>
<authorgroup>
<author>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
<contrib>Contributed by </contrib>
</author>
<author>
<firstname>David</firstname>
<surname>O'Brien</surname>
</author>
</authorgroup>
<!-- June 1996 -->
</sect1info>
<title>Contributed Software</title>
<indexterm><primary>contributed software</primary></indexterm>
<para>Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this <emphasis>contributed</emphasis> software. Some
examples are <application>sendmail</application>, <application>gcc</application> and <application>patch</application>.</para>
<para>Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.</para>
<para>Since this is the case, after some debate one of these methods has
been selected as the <quote>official</quote> method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
<quote>official</quote> versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.</para>
<para>Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.</para>
<note>
<para>Because of some unfortunate design limitations with the RCS file
format and CVS's use of vendor branches, minor, trivial and/or
cosmetic changes are <emphasis>strongly discouraged</emphasis> on
files that are still tracking the vendor branch. <quote>Spelling
fixes</quote> are explicitly included here under the
<quote>cosmetic</quote> category and are to be avoided for files with
revision 1.1.x.x. The repository bloat impact from a single character
change can be rather dramatic.</para>
</note>
<para>The <application>Tcl</application> embedded programming
language will be used as example of how this model works:</para>
<para><filename>src/contrib/tcl</filename> contains the source as
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
<filename>mac</filename>, <filename>win</filename> and
<filename>compat</filename> subdirectories were eliminated before the
import.</para>
<para><filename>src/lib/libtcl</filename> contains only a <application>bmake</application> style
<filename>Makefile</filename> that uses the standard
<filename>bsd.lib.mk</filename> makefile rules to produce the library
and install the documentation.</para>
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
<filename>Makefile</filename> which will produce and install the
<command>tclsh</command> program and its associated man-pages using the
standard <filename>bsd.prog.mk</filename> rules.</para>
<para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
shell-scripts that can be of help when the tcl software needs updating.
These are not part of the built or installed software.</para>
<para>The important thing here is that the
<filename>src/contrib/tcl</filename> directory is created according to
the rules: it is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
<hostid>freefall</hostid> will assist in doing the import, but if there are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it <quote>works out</quote>. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.</para>
<para>Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that <quote>official</quote> patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and <quote>committed</quote>, as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.</para>
<para>Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall <emphasis>not</emphasis> be removed.</para>
<para>If it seems easier, the <command>bmake</command>
<filename>Makefile</filename>s can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
<filename>src/tools</filename> directory along with the port itself so
that it is available to future maintainers.</para>
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should state things like:</para>
<itemizedlist>
<listitem>
<para>Which files have been left out.</para>
</listitem>
<listitem>
<para>Where the original distribution was obtained from and/or the
official master site.</para>
</listitem>
<listitem>
<para>Where to send patches back to the original authors.</para>
</listitem>
<listitem>
<para>Perhaps an overview of the FreeBSD-specific changes that have
been made.</para>
</listitem>
</itemizedlist>
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
with the contributed source. Rather you should <command>cvs add
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
wording from <filename>src/contrib/cpio</filename> is below:</para>
<programlisting>This directory contains virgin sources of the original distribution files
on a "vendor" branch. Do not, under any circumstances, attempt to upgrade
the files in this directory via patches and a cvs commit. New versions or
official-patch versions must be imported. Please remember to import with
"-ko" to prevent CVS from corrupting any vendor RCS Ids.
For the import of GNU cpio 2.4.2, the following files were removed:
INSTALL cpio.info mkdir.c
Makefile.in cpio.texi mkinstalldirs
To upgrade to a newer version of cpio, when it is available:
1. Unpack the new version into an empty directory.
[Do not make ANY changes to the files.]
2. Remove the files listed above and any others that don't apply to
FreeBSD.
3. Use the command:
cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
src/contrib/cpio GNU cpio_&lt;version&gt;
For example, to do the import of version 2.4.2, I typed:
cvs import -ko -m 'Virgin import of GNU v2.4.2' \
src/contrib/cpio GNU cpio_2_4_2
4. Follow the instructions printed out in step 3 to resolve any
conflicts between local FreeBSD changes and the newer version.
Do not, under any circumstances, deviate from this procedure.
To make local changes to cpio, simply patch and commit to the main
branch (aka HEAD). Never make local changes on the GNU branch.
All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@FreeBSD.org - 30 March 1997</programlisting>
</sect1>
<sect1 id="policies-encumbered">
<title>Encumbered Files</title>
<para>It might occasionally be necessary to include an encumbered file in
the FreeBSD source tree. For example, if a device requires a small
piece of binary code to be loaded to it before the device will operate,
and we do not have the source to that code, then the binary file is said
to be encumbered. The following policies apply to including encumbered
files in the FreeBSD source tree.</para>
<orderedlist>
<listitem>
<para>Any file which is interpreted or executed by the system CPU(s)
and not in source format is encumbered.</para>
</listitem>
<listitem>
<para>Any file with a license more restrictive than BSD or GNU is
encumbered.</para>
</listitem>
<listitem>
<para>A file which contains downloadable binary data for use by the
hardware is not encumbered, unless (1) or (2) apply to it. It must
be stored in an architecture neutral ASCII format (file2c or
uuencoding is recommended).</para>
</listitem>
<listitem>
<para>Any encumbered file requires specific approval from the
<ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> before it is added to the
CVS repository.</para>
</listitem>
<listitem>
<para>Encumbered files go in <filename>src/contrib</filename> or
<filename>src/sys/contrib</filename>.</para>
</listitem>
<listitem>
<para>The entire module should be kept together. There is no point in
splitting it, unless there is code-sharing with non-encumbered
code.</para>
</listitem>
<listitem>
<para>Object files are named
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
</listitem>
<listitem>
<para>Kernel files:</para>
<orderedlist>
<listitem>
<para>Should always be referenced in
<filename>conf/files.*</filename> (for build simplicity).</para>
</listitem>
<listitem>
<para>Should always be in <filename>LINT</filename>, but the
<ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> decides per case if it
should be commented out or not. The
<ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> can, of course, change
their minds later on.</para>
</listitem>
<listitem>
<para>The <firstterm>Release Engineer</firstterm>
decides whether or not it goes into the release.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>User-land files:</para>
<orderedlist>
<listitem>
<indexterm><primary>core team</primary></indexterm>
<para>The <ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> decides if
the code should be part of <command>make world</command>.</para>
</listitem>
<listitem>
<indexterm><primary>release engineer</primary></indexterm>
<para>The <ulink url="&url.articles.contributors;/staff-who.html">Release Engineer</ulink>
decides if it goes into the release.</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</sect1>
<sect1 id="policies-shlib">
<sect1info>
<authorgroup>
<author>
<firstname>Satoshi</firstname>
<surname>Asami</surname>
<contrib>Contributed by </contrib>
</author>
<author>
<firstname>Peter</firstname>
<surname>Wemm</surname>
</author>
<author>
<firstname>David</firstname>
<surname>O'Brien</surname>
</author>
</authorgroup>
<!-- 9 Dec 1996 -->
</sect1info>
<title>Shared Libraries</title>
<para>If you are adding shared library support to a port or other piece of
software that does not have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.</para>
<para>The three principles of shared library building are:</para>
<itemizedlist>
<listitem>
<para>Start from <literal>1.0</literal></para>
</listitem>
<listitem>
<para>If there is a change that is backwards compatible, bump minor
number (note that ELF systems ignore the minor number)</para>
</listitem>
<listitem>
<para>If there is an incompatible change, bump major number</para>
</listitem>
</itemizedlist>
<para>For instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed function
call syntax, etc. will force the major version number to change.</para>
<para>Stick to version numbers of the form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out
dynamic linker does not handle version numbers of the form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
well. Any version number after the <replaceable>y</replaceable>
(i.e. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the <quote>micro</quote> revision,
<command>ld.so</command> will link with the higher one. That is, if you link
with <filename>libfoo.so.3.3.3</filename>, the linker only records
<literal>3.3</literal> in the headers, and will link with anything
starting with
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
3)</replaceable>.<replaceable>(highest
available)</replaceable>.</para>
<note>
<para><command>ld.so</command> will always use the highest
<quote>minor</quote> revision. For instance, it will use
<filename>libc.so.2.2</filename> in preference to
<filename>libc.so.2.0</filename>, even if the program was initially
linked with <filename>libc.so.2.0</filename>.</para>
</note>
<para>In addition, our ELF dynamic linker does not handle minor version
numbers at all. However, one should still specify a major and minor
version number as our <filename>Makefile</filename>s <quote>do the right thing</quote>
based on the type of system.</para>
<para>For non-port libraries, it is also our policy to change the shared
library version number only once between releases. In addition, it is
our policy to change the major shared library version number only once
between major OS releases (i.e. from 3.0 to 4.0). When you make a
change to a system library that requires the version number to be
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the <filename>Makefile</filename> to be updated, and any subsequent
changes will not.</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

525
zh_TW.Big5/books/developers-handbook/secure/chapter.sgml Normal file
View file

@ -0,0 +1,525 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="secure">
<chapterinfo>
<authorgroup>
<author>
<firstname>Murray</firstname>
<surname>Stokely</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</chapterinfo>
<title>Secure Programming</title>
<sect1 id="secure-synopsis"><title>Synopsis</title>
<para>This chapter describes some of the security issues that
have plagued &unix; programmers for decades and some of the new
tools available to help programmers avoid writing exploitable
code.</para>
</sect1>
<sect1 id="secure-philosophy"><title>Secure Design
Methodology</title>
<para>Writing secure applications takes a very scrutinous and
pessimistic outlook on life. Applications should be run with
the principle of <quote>least privilege</quote> so that no
process is ever running with more than the bare minimum access
that it needs to accomplish its function. Previously tested
code should be reused whenever possible to avoid common
mistakes that others may have already fixed.</para>
<para>One of the pitfalls of the &unix; environment is how easy it
is to make assumptions about the sanity of the environment.
Applications should never trust user input (in all its forms),
system resources, inter-process communication, or the timing of
events. &unix; processes do not execute synchronously so logical
operations are rarely atomic.</para>
</sect1>
<sect1 id="secure-bufferov"><title>Buffer Overflows</title>
<para>Buffer Overflows have been around since the very
beginnings of the Von-Neuman <xref linkend="COD"> architecture.
<indexterm><primary>buffer overflow</primary></indexterm>
<indexterm><primary>Von-Neuman</primary></indexterm>
They first gained widespread notoriety in 1988 with the Morris
Internet worm. Unfortunately, the same basic attack remains
<indexterm><primary>Morris Internet worm</primary></indexterm>
effective today. Of the 17 CERT security advisories of 1999, 10
<indexterm>
<primary>CERT</primary><secondary>security advisories</secondary>
</indexterm>
of them were directly caused by buffer-overflow software bugs.
By far the most common type of buffer overflow attack is based
on corrupting the stack.</para>
<indexterm><primary>stack</primary></indexterm>
<indexterm><primary>arguments</primary></indexterm>
<para>Most modern computer systems use a stack to pass arguments
to procedures and to store local variables. A stack is a last
in first out (LIFO) buffer in the high memory area of a process
image. When a program invokes a function a new "stack frame" is
<indexterm><primary>LIFO</primary></indexterm>
<indexterm>
<primary>process image</primary>
<secondary>stack pointer</secondary>
</indexterm>
created. This stack frame consists of the arguments passed to
the function as well as a dynamic amount of local variable
space. The "stack pointer" is a register that holds the current
<indexterm><primary>stack frame</primary></indexterm>
<indexterm><primary>stack pointer</primary></indexterm>
location of the top of the stack. Since this value is
constantly changing as new values are pushed onto the top of the
stack, many implementations also provide a "frame pointer" that
is located near the beginning of a stack frame so that local
variables can more easily be addressed relative to this
value. <xref linkend="COD"> The return address for function
<indexterm><primary>frame pointer</primary></indexterm>
<indexterm>
<primary>process image</primary>
<secondary>frame pointer</secondary>
</indexterm>
<indexterm><primary>return address</primary></indexterm>
<indexterm><primary>stack-overflow</primary></indexterm>
calls is also stored on the stack, and this is the cause of
stack-overflow exploits since overflowing a local variable in a
function can overwrite the return address of that function,
potentially allowing a malicious user to execute any code he or
she wants.</para>
<para>Although stack-based attacks are by far the most common,
it would also be possible to overrun the stack with a heap-based
(malloc/free) attack.</para>
<para>The C programming language does not perform automatic
bounds checking on arrays or pointers as many other languages
do. In addition, the standard C library is filled with a
handful of very dangerous functions.</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<tbody>
<row><entry><function>strcpy</function>(char *dest, const char
*src)</entry>
<entry><simpara>May overflow the dest buffer</simpara></entry>
</row>
<row><entry><function>strcat</function>(char *dest, const char
*src)</entry>
<entry><simpara>May overflow the dest buffer</simpara></entry>
</row>
<row><entry><function>getwd</function>(char *buf)</entry>
<entry><simpara>May overflow the buf buffer</simpara></entry>
</row>
<row><entry><function>gets</function>(char *s)</entry>
<entry><simpara>May overflow the s buffer</simpara></entry>
</row>
<row><entry><function>[vf]scanf</function>(const char *format,
...)</entry>
<entry><simpara>May overflow its arguments.</simpara></entry>
</row>
<row><entry><function>realpath</function>(char *path, char
resolved_path[])</entry>
<entry><simpara>May overflow the path buffer</simpara></entry>
</row>
<row><entry><function>[v]sprintf</function>(char *str, const char
*format, ...)</entry>
<entry><simpara>May overflow the str buffer.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2><title>Example Buffer Overflow</title>
<para>The following example code contains a buffer overflow
designed to overwrite the return address and skip the
instruction immediately following the function call. (Inspired
by <xref linkend="Phrack">)</para>
<programlisting>#include <sgmltag>stdio.h</sgmltag>
void manipulate(char *buffer) {
char newbuffer[80];
strcpy(newbuffer,buffer);
}
int main() {
char ch,buffer[4096];
int i=0;
while ((buffer[i++] = getchar()) != '\n') {};
i=1;
manipulate(buffer);
i=2;
printf("The value of i is : %d\n",i);
return 0;
}</programlisting>
<para>Let us examine what the memory image of this process would
look like if we were to input 160 spaces into our little program
before hitting return.</para>
<para>[XXX figure here!]</para>
<para>Obviously more malicious input can be devised to execute
actual compiled instructions (such as exec(/bin/sh)).</para>
</sect2>
<sect2><title>Avoiding Buffer Overflows</title>
<para>The most straightforward solution to the problem of
stack-overflows is to always use length restricted memory and
string copy functions. <function>strncpy</function> and
<function>strncat</function> are part of the standard C library.
<indexterm>
<primary>string copy functions</primary>
<secondary>strncpy</secondary>
</indexterm>
<indexterm>
<primary>string copy functions</primary>
<secondary>strncat</secondary>
</indexterm>
These functions accept a length value as a parameter which
should be no larger than the size of the destination buffer.
These functions will then copy up to `length' bytes from the
source to the destination. However there are a number of
problems with these functions. Neither function guarantees NUL
termination if the size of the input buffer is as large as the
<indexterm><primary>NUL termination</primary></indexterm>
destination. The length parameter is also used inconsistently
between strncpy and strncat so it is easy for programmers to get
confused as to their proper usage. There is also a significant
performance loss compared to <function>strcpy</function> when
copying a short string into a large buffer since
<function>strncpy</function> NUL fills up the size
specified.</para>
<para>In OpenBSD, another memory copy implementation has been
<indexterm><primary>OpenBSD</primary></indexterm>
created to get around these problem. The
<function>strlcpy</function> and <function>strlcat</function>
functions guarantee that they will always null terminate the
destination string when given a non-zero length argument. For
more information about these functions see <xref
linkend="OpenBSD">. The OpenBSD <function>strlcpy</function> and
<function>strlcat</function> instructions have been in FreeBSD
since 3.3.</para>
<indexterm>
<primary>string copy functions</primary>
<secondary>strlcpy</secondary>
</indexterm>
<indexterm>
<primary>string copy functions</primary>
<secondary>strlcat</secondary>
</indexterm>
<sect3><title>Compiler based run-time bounds checking</title>
<indexterm><primary>bounds checking</primary>
<secondary>compiler-based</secondary></indexterm>
<para>Unfortunately there is still a very large assortment of
code in public use which blindly copies memory around without
using any of the bounded copy routines we just discussed.
Fortunately, there is another solution. Several compiler
add-ons and libraries exist to do Run-time bounds checking in
C/C++.</para>
<indexterm><primary>StackGuard</primary></indexterm>
<indexterm><primary>gcc</primary></indexterm>
<para>StackGuard is one such add-on that is implemented as a
small patch to the gcc code generator. From the <ulink
url="http://immunix.org/stackguard.html">StackGuard
website</ulink>:
<blockquote><para>"StackGuard detects and defeats stack
smashing attacks by protecting the return address on the stack
from being altered. StackGuard places a "canary" word next to
the return address when a function is called. If the canary
word has been altered when the function returns, then a stack
smashing attack has been attempted, and the program responds
by emitting an intruder alert into syslog, and then
halts."</para></blockquote>
<blockquote><para>"StackGuard is implemented as a small patch
to the gcc code generator, specifically the function_prolog()
and function_epilog() routines. function_prolog() has been
enhanced to lay down canaries on the stack when functions
start, and function_epilog() checks canary integrity when the
function exits. Any attempt at corrupting the return address
is thus detected before the function
returns."</para></blockquote>
</para>
<indexterm><primary>buffer overflow</primary></indexterm>
<para>Recompiling your application with StackGuard is an
effective means of stopping most buffer-overflow attacks, but
it can still be compromised.</para>
</sect3>
<sect3><title>Library based run-time bounds checking</title>
<indexterm>
<primary>bounds checking</primary>
<secondary>library-based</secondary>
</indexterm>
<para>Compiler-based mechanisms are completely useless for
binary-only software for which you cannot recompile. For
these situations there are a number of libraries which
re-implement the unsafe functions of the C-library
(<function>strcpy</function>, <function>fscanf</function>,
<function>getwd</function>, etc..) and ensure that these
functions can never write past the stack pointer.</para>
<itemizedlist>
<listitem><simpara>libsafe</simpara></listitem>
<listitem><simpara>libverify</simpara></listitem>
<listitem><simpara>libparanoia</simpara></listitem>
</itemizedlist>
<para>Unfortunately these library-based defenses have a number
of shortcomings. These libraries only protect against a very
small set of security related issues and they neglect to fix
the actual problem. These defenses may fail if the
application was compiled with -fomit-frame-pointer. Also, the
LD_PRELOAD and LD_LIBRARY_PATH environment variables can be
overwritten/unset by the user.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="secure-setuid"><title>SetUID issues</title>
<indexterm><primary>seteuid</primary></indexterm>
<para>There are at least 6 different IDs associated with any
given process. Because of this you have to be very careful with
the access that your process has at any given time. In
particular, all seteuid applications should give up their
privileges as soon as it is no longer required.</para>
<indexterm>
<primary>user IDs</primary>
<secondary>real user ID</secondary>
</indexterm>
<indexterm>
<primary>user IDs</primary>
<secondary>effective user ID</secondary>
</indexterm>
<para>The real user ID can only be changed by a superuser
process. The <application>login</application> program sets this
when a user initially logs in and it is seldom changed.</para>
<para>The effective user ID is set by the
<function>exec()</function> functions if a program has its
seteuid bit set. An application can call
<function>seteuid()</function> at any time to set the effective
user ID to either the real user ID or the saved set-user-ID.
When the effective user ID is set by <function>exec()</function>
functions, the previous value is saved in the saved set-user-ID.</para>
</sect1>
<sect1 id="secure-chroot"><title>Limiting your program's environment</title>
<indexterm><primary>chroot()</primary></indexterm>
<para>The traditional method of restricting a process
is with the <function>chroot()</function> system call. This
system call changes the root directory from which all other
paths are referenced for a process and any child processes. For
this call to succeed the process must have execute (search)
permission on the directory being referenced. The new
environment does not actually take effect until you
<function>chdir()</function> into your new environment. It
should also be noted that a process can easily break out of a
chroot environment if it has root privilege. This could be
accomplished by creating device nodes to read kernel memory,
attaching a debugger to a process outside of the jail, or in
many other creative ways.</para>
<para>The behavior of the <function>chroot()</function> system
call can be controlled somewhat with the
kern.chroot_allow_open_directories <command>sysctl</command>
variable. When this value is set to 0,
<function>chroot()</function> will fail with EPERM if there are
any directories open. If set to the default value of 1, then
<function>chroot()</function> will fail with EPERM if there are
any directories open and the process is already subject to a
<function>chroot()</function> call. For any other value, the
check for open directories will be bypassed completely.</para>
<sect2><title>FreeBSD's jail functionality</title>
<indexterm><primary>jail</primary></indexterm>
<para>The concept of a Jail extends upon the
<function>chroot()</function> by limiting the powers of the
superuser to create a true `virtual server'. Once a prison is
set up all network communication must take place through the
specified IP address, and the power of "root privilege" in this
jail is severely constrained.</para>
<para>While in a prison, any tests of superuser power within the
kernel using the <function>suser()</function> call will fail.
However, some calls to <function>suser()</function> have been
changed to a new interface <function>suser_xxx()</function>.
This function is responsible for recognizing or denying access
to superuser power for imprisoned processes.</para>
<para>A superuser process within a jailed environment has the
power to:</para>
<itemizedlist>
<listitem><simpara>Manipulate credential with
<function>setuid</function>, <function>seteuid</function>,
<function>setgid</function>, <function>setegid</function>,
<function>setgroups</function>, <function>setreuid</function>,
<function>setregid</function>, <function>setlogin</function></simpara></listitem>
<listitem><simpara>Set resource limits with <function>setrlimit</function></simpara></listitem>
<listitem><simpara>Modify some sysctl nodes
(kern.hostname)</simpara></listitem>
<listitem><simpara><function>chroot()</function></simpara></listitem>
<listitem><simpara>Set flags on a vnode:
<function>chflags</function>,
<function>fchflags</function></simpara></listitem>
<listitem><simpara>Set attributes of a vnode such as file
permission, owner, group, size, access time, and modification
time.</simpara></listitem>
<listitem><simpara>Bind to privileged ports in the Internet
domain (ports &lt; 1024)</simpara></listitem>
</itemizedlist>
<para><function>Jail</function> is a very useful tool for
running applications in a secure environment but it does have
some shortcomings. Currently, the IPC mechanisms have not been
converted to the <function>suser_xxx</function> so applications
such as MySQL cannot be run within a jail. Superuser access
may have a very limited meaning within a jail, but there is
no way to specify exactly what "very limited" means.</para>
</sect2>
<sect2><title>&posix;.1e Process Capabilities</title>
<indexterm><primary>POSIX.1e Process Capabilities</primary></indexterm>
<indexterm><primary>TrustedBSD</primary></indexterm>
<para>&posix; has released a working draft that adds event
auditing, access control lists, fine grained privileges,
information labeling, and mandatory access control.</para>
<para>This is a work in progress and is the focus of the <ulink
url="http://www.trustedbsd.org/">TrustedBSD</ulink> project. Some
of the initial work has been committed to &os.current;
(cap_set_proc(3)).</para>
</sect2>
</sect1>
<sect1 id="secure-trust"><title>Trust</title>
<para>An application should never assume that anything about the
users environment is sane. This includes (but is certainly not
limited to): user input, signals, environment variables,
resources, IPC, mmaps, the filesystem working directory, file
descriptors, the # of open files, etc.</para>
<indexterm><primary>positive filtering</primary></indexterm>
<indexterm><primary>data validation</primary></indexterm>
<para>You should never assume that you can catch all forms of
invalid input that a user might supply. Instead, your
application should use positive filtering to only allow a
specific subset of inputs that you deem safe. Improper data
validation has been the cause of many exploits, especially with
CGI scripts on the world wide web. For filenames you need to be
extra careful about paths ("../", "/"), symbolic links, and
shell escape characters.</para>
<indexterm><primary>Perl Taint mode</primary></indexterm>
<para>Perl has a really cool feature called "Taint" mode which
can be used to prevent scripts from using data derived outside
the program in an unsafe way. This mode will check command line
arguments, environment variables, locale information, the
results of certain syscalls (<function>readdir()</function>,
<function>readlink()</function>,
<function>getpwxxx()</function>, and all file input.</para>
</sect1>
<sect1 id="secure-race-conditions">
<title>Race Conditions</title>
<para>A race condition is anomalous behavior caused by the
unexpected dependence on the relative timing of events. In
other words, a programmer incorrectly assumed that a particular
event would always happen before another.</para>
<indexterm><primary>race conditions</primary>
<secondary>signals</secondary></indexterm>
<indexterm><primary>race conditions</primary>
<secondary>access checks</secondary></indexterm>
<indexterm><primary>race conditions</primary>
<secondary>file opens</secondary></indexterm>
<para>Some of the common causes of race conditions are signals,
access checks, and file opens. Signals are asynchronous events
by nature so special care must be taken in dealing with them.
Checking access with <function>access(2)</function> then
<function>open(2)</function> is clearly non-atomic. Users can
move files in between the two calls. Instead, privileged
applications should <function>seteuid()</function> and then call
<function>open()</function> directly. Along the same lines, an
application should always set a proper umask before
<function>open()</function> to obviate the need for spurious
<function>chmod()</function> calls.</para>
</sect1>
</chapter>

1790
zh_TW.Big5/books/developers-handbook/sockets/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

226
zh_TW.Big5/books/developers-handbook/testing/chapter.sgml Normal file
View file

@ -0,0 +1,226 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="testing">
<title>Regression and Performance Testing</title>
<para>Regression tests are used to exercise a particular bit of the
system to check that it works as expected, and to make sure that
old bugs are not reintroduced.</para>
<para>The &os; regression testing tools can be found in the &os;
source tree in the directory <filename
class="directory">src/tools/regression</filename>.</para>
<section id="testing-micro-benchmark">
<title>Micro Benchmark Checklist</title>
<para>This section contains hints for doing proper
micro-benchmarking on &os; or of &os; itself.</para>
<para>It is not possible to use all of the suggestions below every
single time, but the more used, the better the benchmark's
ability to test small differences will be.</para>
<itemizedlist>
<listitem>
<para>Disable <acronym>APM</acronym> and any other kind of
clock fiddling (<acronym>ACPI</acronym> ?).</para>
</listitem>
<listitem>
<para>Run in single user mode. E.g. &man.cron.8;, and and
other daemons only add noise. The &man.sshd.8; daemon can
also cause problems. If ssh access is required during test
either disable the SSHv1 key regeneration, or kill the
parent <command>sshd</command> daemon during the tests.</para>
</listitem>
<listitem>
<para>Do not run &man.ntpd.8;.</para>
</listitem>
<listitem>
<para>If &man.syslog.3; events are generated, run
&man.syslogd.8; with an empty
<filename>/etc/syslogd.conf</filename>, otherwise, do not
run it.</para>
</listitem>
<listitem>
<para>Minimize disk-I/O, avoid it entirely if possible.</para>
</listitem>
<listitem>
<para>Do not mount file systems that are not needed.</para>
</listitem>
<listitem>
<para>Mount <filename class="directory">/</filename>,
<filename class="directory">/usr</filename>, and any other
file system as read-only if possible. This removes atime
updates to disk (etc.) from the I/O picture.</para>
</listitem>
<listitem>
<para>Reinitialize the read/write test file system with
&man.newfs.8; and populate it from a &man.tar.1; or
&man.dump.8; file before every run. Unmount and mount it
before starting the test. This results in a consistent file
system layout. For a worldstone test this would apply to
<filename class="directory">/usr/obj</filename> (just
reinitialize with <command>newfs</command> and mount). To
get 100% reproducibility, populate the file system from a
&man.dd.1; file (i.e.: <command>dd
if=<filename>myimage</filename> of=<filename
class="devicefile">/dev/ad0s1h</filename>
bs=1m</command>)</para>
</listitem>
<listitem>
<para>Use malloc backed or preloaded &man.md.4;
partitions.</para>
</listitem>
<listitem>
<para>Reboot between individual iterations of the test, this
gives a more consistent state.</para>
</listitem>
<listitem>
<para>Remove all non-essential device drivers from the kernel.
For instance if USB is not needed for the test, do not put
USB in the kernel. Drivers which attach often have timeouts
ticking away.</para>
</listitem>
<listitem>
<para>Unconfigure hardware that are not in use. Detach disks
with &man.atacontrol.8; and &man.camcontrol.8; if the disks
are not used for the test.</para>
</listitem>
<listitem>
<para>Do not configure the network unless it is being tested,
or wait until after the test has been performed to ship the
results off to another computer.</para>
<para>If the system must be connected to a public network,
watch out for spikes of broadcast traffic. Even though it
is hardly noticeable, it will take up CPU cycles. Multicast
has similar caveats.</para>
</listitem>
<listitem>
<para>Put each file system on its own disk. This minimizes
jitter from head-seek optimizations.</para>
</listitem>
<listitem>
<para>Minimize output to serial or VGA consoles. Running
output into files gives less jitter. (Serial consoles
easily become a bottleneck.) Do not touch keyboard while
the test is running, even <keycap>space</keycap> or
<keycap>back-space</keycap> shows up in the numbers.</para>
</listitem>
<listitem>
<para>Make sure the test is long enough, but not too long. If
the test is too short, timestamping is a problem. If it is
too long temperature changes and drift will affect the
frequency of the quartz crystals in the computer. Rule of
thumb: more than a minute, less than an hour.</para>
</listitem>
<listitem>
<para>Try to keep the temperature as stable as possible around
the machine. This affects both quartz crystals and disk
drive algorithms. To get real stable clock, consider
stabilized clock injection. E.g. get a OCXO + PLL, inject
output into clock circuits instead of motherboard xtal.
Contact &a.phk; for more information about this.</para>
</listitem>
<listitem>
<para>Run the test at least 3 times but it is better to run
more than 20 times both for <quote>before</quote> and
<quote>after</quote> code. Try to interleave if possible
(i.e.: do not run 20 times before then 20 times after), this
makes it possible to spot environmental effects. Do not
interleave 1:1, but 3:3, this makes it possible to spot
interaction effects.</para>
<para>A good pattern is: <literal>bababa{bbbaaa}*</literal>.
This gives hint after the first 1+1 runs (so it is possible
to stop the test if it goes entirely the wrong way), a
standard deviation after the first 3+3 (gives a good
indication if it is going to be worth a long run) and
trending and interaction numbers later on.</para>
</listitem>
<listitem>
<para>Use <filename
class="directory">usr/src/tools/tools/ministat</filename>
to see if the numbers are significant. Consider buying
<quote>Cartoon guide to statistics</quote> ISBN:
0062731025, highly recommended, if you have forgotten or
never learned about standard deviation and Student's
T.</para>
</listitem>
<listitem>
<para>Do not use background &man.fsck.8; unless the test is a
benchmark of background <command>fsck</command>. Also,
disable <varname>background_fsck</varname> in
<filename>/etc/rc.conf</filename> unless the benchmark is
not started at least 60+<quote><command>fsck</command>
runtime</quote> seconds after the boot, as &man.rc.8; wakes
up and checks if <command>fsck</command> needs to run on any
file systems when background <command>fsck</command> is
enabled. Likewise, make sure there are no snapshots lying
around unless the benchmark is a test with snapshots.</para>
</listitem>
<listitem>
<para>If the benchmark show unexpected bad performance, check
for things like high interrupt volume from an unexpected
source. Some versions of <acronym>ACPI</acronym> have been
reported to <quote>misbehave</quote> and generate excess
interrupts. To help diagnose odd test results, take a few
snapshots of <command>vmstat -i</command> and look for
anything unusual.</para>
</listitem>
<listitem>
<para>Make sure to be careful about optimization parameters
for kernel and userspace, likewise debugging. It is easy to
let something slip through and realize later the test was
not comparing the same thing.</para>
</listitem>
<listitem>
<para>Do not ever benchmark with the
<literal>WITNESS</literal> and <literal>INVARIANTS</literal>
kernel options enabled unless the test is interested to
benchmarking those features. <literal>WITNESS</literal> can
cause 400%+ drops in performance. Likewise, userspace
&man.malloc.3; parameters default differently in -CURRENT
from the way they ship in production releases.</para>
</listitem>
</itemizedlist>
</section>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->

2366
zh_TW.Big5/books/developers-handbook/tools/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

6486
zh_TW.Big5/books/developers-handbook/x86/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

936
zh_TW.Big5/books/faq/book.sgml
View file

File diff suppressed because it is too large Load diff

2
zh_TW.Big5/books/fdp-primer/see-also/chapter.sgml
View file

@ -32,7 +32,7 @@
-->
<chapter id="see-also">
<title>See Also</title>
<title>他山之石</title>
<para>This document is deliberately not an exhaustive discussion of SGML,
the DTDs listed, and the FreeBSD Documentation Project. For more

10
zh_TW.Big5/books/fdp-primer/translations/chapter.sgml
View file

@ -46,14 +46,12 @@
<qandaset>
<qandaentry>
<question>
<para>Why a FAQ?</para>
<para>FAQ 的目的是?</para>
</question>
<answer>
<para>More and more people are approaching the freebsd-doc mailing
list and volunteering to translate FreeBSD documentation to other
languages. This FAQ aims to answer their questions so they can start
translating documentation as quickly as possible.</para>
<para>隨著越來越多人參與 freebsd-doc 郵遞論壇，而且希望將 FreeBSD 文件翻譯為各種語言版本。
我們希望這份 FAQ 能儘可能為這些參與翻譯者提供快速的解惑。</para>
</answer>
</qandaentry>
@ -319,7 +317,7 @@
<para>There is no real reason why that information should not be in the
English (or German, or Spanish, or Japanese, or &hellip;) versions
as well. It is feasible that an English speaker in Korea might try
and pick up a copy of FreeBSD whilst over there. It also helps
to pick up a copy of FreeBSD whilst over there. It also helps
increase FreeBSD's perceived presence around the globe, which is not
a bad thing.</para>

2
zh_TW.Big5/books/handbook/Makefile
View file

@ -1,5 +1,5 @@
#
# $FreeBSD$
# $FreeBSD$
# Original revision: 1.97
#
# Build the FreeBSD Handbook.

212
zh_TW.Big5/books/handbook/audit/chapter.sgml
View file

@ -1,18 +1,10 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
Original revision: 1.5
Original revision: 1.13
-->
<!--
This version of the document assumes that the Audit system needs to be
installed as part of the trustedbsd/audit project. When/if audit becomes
part of FreeBSD proper, then these sections should be removed, or at least
reworded. The sections in question are marked with 'PROTOTYPE' labels in
commentary.
-->
<!-- Need more documenation on praudit, audtreduce, etc. Plus more info
<!-- Need more documentation on praudit, auditreduce, etc. Plus more info
on the triggers from the kernel (log rotation, out of space, etc).
And the /dev/audit special file if we choose to support that. Could use
some coverage of integrating MAC with Event auditing and perhaps discussion
@ -30,23 +22,31 @@ requirements. -->
</authorgroup>
</chapterinfo>
<title>Kernel Event Auditing</title>
<title>Security Event Auditing</title>
<sect1 id="audit-synopsis">
<title>Synopsis</title>
<indexterm><primary>AUDIT</primary></indexterm>
<indexterm>
<primary>Kernel Event Auditing</primary>
<primary>Security Event Auditing</primary>
<see>MAC</see>
</indexterm>
<para>The &os;&nbsp;6.0 operating system release has included
<para>The &os;&nbsp;7-CURRENT development branch includes
support for Event Auditing based on the &posix;.1e draft and
the &sun; <acronym>BSM</acronym> implementation. Event auditing
permits the selective logging of security-relevant system events
for the purposes of system analysis, system monitoring, and
security evaluation.</para>
Sun's published <acronym>BSM</acronym> API and file format.
Event auditing permits the selective logging of security-relevant
system events for the purposes of post-mortem analysis, system
monitoring, and intrusion detection. After some settling time in
&os;&nbsp;7-CURRENT, this support will be merged to &os;&nbsp;6-STABLE
and appear in subsequent releases.</para>
<warning>
<para>The audit facility in FreeBSD is considered experimental, and
production deployment should occur only after careful consideration
of the risks of deploying experimental software.</para>
</warning>
<para>This chapter will focus mainly on the installation and
configuration of Event Auditing. Explanation of audit policies,
@ -88,16 +88,17 @@ requirements. -->
<warning>
<para>Event auditing can generate a great deal of log file
data, exceeding gigabytes a week in some configurations. An administrator
should read this chapter in its entirety to avoid possible
self inflicted <acronym>DoS</acronym> attacks due to improper
configuration.</para>
data, exceeding gigabytes a week in some configurations. An
administrator should read this chapter in its entirety to avoid
possible self-inflicted <acronym>DoS</acronym> attacks due to
improper configuration.</para>
</warning>
<para>The implementation of Event Auditing in &os; is similar to
that of the &sun; Basic Security Module, or <acronym>BSM</acronym>
library. Thus, the configuration is almost completely
interchangeable with &solaris; and Darwin operating systems.</para>
interchangeable with &solaris; and Mac OS X/Darwin operating
systems.</para>
</sect1>
<sect1 id="audit-inline-glossary">
@ -110,22 +111,47 @@ requirements. -->
<itemizedlist>
<listitem>
<para><emphasis>class</emphasis>: A class specifies the category
different actions the system are placed in. For example,
use of &man.login.1; could be placed in a class.</para>
<para><emphasis>event</emphasis>: An auditable event is
an event that can be logged using the audit subsystem. The
administrator can configure which events will be audited.
Examples of security-relevant events include the creation of
a file, the building of a network connection, or the logging
in of a user. Events are either <quote>attributable</quote>,
meaning that they can be traced back to a user
authentication, or <quote>non-attributable</quote>. Examples
of non-attributable events are any events that occur before
authentication has succeeded in the login process, such as
failed authentication attempts.</para>
</listitem>
<listitem>
<para><emphasis>event</emphasis>: An event could be considered
an action taken on the system. Creating a file would be
an event.</para>
<para><emphasis>class</emphasis>: Events may be assigned to
one or more classes, usually based on the general category
of the events, such as <quote>file creation</quote>,
<quote>file access</quote>, or <quote>network</quote>. Login
and logout events are assigned to the <literal>lo</literal>
class. The use of classes allows the administrator to
specify high level auditing rules without having to specify
whether each individual auditable operation will be logged.</para>
</listitem>
<listitem>
<para><emphasis>record</emphasis>: A record is a log or a note
about a specific action.</para>
<para><emphasis>record</emphasis>: A record is a log entry
describing a security event. Records typically have a
record event type, information on the subject (user) associated
with the event, time information, information on any objects,
such as files, and information on whether the event corresponded
to a successful operation.</para>
</listitem>
<listitem>
<para><emphasis>trail</emphasis>: An audit trail, or log file,
consists of a series of audit records describing security
events. Typically, trails are in roughly chronological
order with respect to the time events completed. Only
authorized processes are allowed to commit records to the
audit trail.</para>
<listitem>
<para><emphasis>prefix</emphasis>: A prefix is considered to
be the configuration element used to toggle auditing for
@ -137,7 +163,7 @@ requirements. -->
<sect1 id="audit-install">
<title>Installing Audit Support</title>
<para>Support for Event Auditing should have been installed with
<para>Support for Event Auditing is installed with
the normal <maketarget>installworld</maketarget> process. An
administrator may confirm this by viewing the contents
of <filename role="directory">/etc/security</filename>. Files
@ -166,10 +192,9 @@ requirements. -->
<sect1 id="audit-config">
<title>Audit Configuration</title>
<para>By default, all configuration is done within the realm of
<filename role="directory">/etc/security</filename> and the
files contained within. The following files must be present
before the audit daemon is started:</para>
<para>All configuration files for security audit are found in
<filename role="directory">/etc/security</filename>. The following
files must be present before the audit daemon is started:</para>
<itemizedlist>
<listitem>
@ -191,21 +216,19 @@ requirements. -->
<listitem>
<para><filename>audit_user</filename> - The events to audit
for individual users. A user name does not need to appear
in here.</para>
for individual users. Users not appearing here will be
subject to the default configuration in the control
configuration file.</para>
</listitem>
<listitem>
<para><filename>audit_warn</filename> - A shell script
used by auditd to form warning messages.</para>
used by auditd to generate warning messages in
exceptional situations, such as when space for audit
records is running low.</para>
</listitem>
</itemizedlist>
<para>If these files do not exist, for whatever reason, they can
be installed easily by issuing the following commands:</para>
<screen>&prompt.root; <userinput>cd /usr/src/contrib/bsm/etc &amp;&amp; make install</userinput></screen>
<sect2>
<title>Audit File Syntax</title>
@ -291,7 +314,8 @@ requirements. -->
<listitem>
<para><option>ip</option> - <literal>ipc</literal> - Audit
System V <acronym>IPC</acronym> operations.</para>
various forms of Inter-Process Communication, including POSIX
pipes and System V <acronym>IPC</acronym> operations.</para>
</listitem>
<listitem>
@ -326,11 +350,6 @@ requirements. -->
Audit process operations, such as &man.exec.3; and
&man.exit.3;.</para>
</listitem>
<listitem>
<para><option>tf</option> - <literal>tfm</literal> -
I HAVE NO CLUE!</para>
</listitem>
</itemizedlist>
<para>Following is a list of all supported audit prefixes:</para>
@ -382,34 +401,40 @@ requirements. -->
<sect2>
<title>Configuration Files</title>
<para>Configuration is set in only two files, the first being
<filename>audit_control</filename> and
<filename>audit_user</filename> being the second. The first
is system-wide, controlling every aspect of event auditing
in the system. The latter may be used for fine grained user
auditing.</para>
<para>In most cases, administrators will need to modify only two files
when configuring the audit system: <filename>audit_control</filename>
and <filename>audit_user</filename>. The first controls system-wide
audit paramaters and defaults for both attributable and
non-attributable events. The second may be used to tune the level
and nature of auditing for individual users.</para>
<sect3 id="audit-auditcontrol">
<title>The <filename>audit_control</filename> File</title>
<para>The <filename>audit_control</filename> contains some basic
<para>The <filename>audit_control</filename> file contains some basic
defaults that the administrator may wish to modify. Perhaps
even set some new ones. Viewing the contents of this file,
we see the following:</para>
<programlisting>dir:/var/audit
flags:lo,ad,-all,^-fa,^-fc,^-cl
flags:lo
minfree:20
naflags:lo</programlisting>
<para>The <option>dir</option> is used to set the default
directory where audit logs are stored.</para>
<para>The <option>dir</option> option is used to set the default
directory where audit logs are stored. Audit is frequently
configured so that audit logs are stored on a dedicated file
system, so as to prevent interference between the audit
subsystem and other subsystems when file systems become full.
</para>
<para>The <option>flags</option> is used to set the system-wide
defaults. The current setting,
<para>The <option>flags</option> option is used to set the
system-wide defaults. The current setting, <option>lo</option>
configures the auditing of all &man.login.1; and &man.logout.1;
actions. A more complex example,
<option>lo,ad,-all,^-fa,^-fc,^-cl</option> audits all system
&man.login.1; and &man.logout.1; actions, all administrator
actions, all failed events in the system, and finally disable
actions, all failed events in the system, and finally disables
auditing of failed attempts for <option>fa</option>,
<option>fc</option>, and <option>cl</option>. Even though
the <option>-all</option> turned on the auditing of all
@ -432,19 +457,17 @@ naflags:lo</programlisting>
to eighty (80) percent full.</para>
<para>The <option>naflags</option> option specifies audit
flags to be considered non attributable; i.e.: classes of
events which cannot be attributed to a specific user
on the system. This can be overridden with the
<filename>audit_user</filename> configuration file.</para>
classes to be audited for non-attributed events &mdash;
that is, events for which there is no authenticated user.
</para>
</sect3>
<sect3 id="audit-audituser">
<title>The <filename>audit_user</filename> File</title>
<para>The <filename>audit_user</filename> permits the
administrator to map audit specific events to directly
to users. This adds a finer-grained control mechanism
for all system users.</para>
<para>The <filename>audit_user</filename> file permits the
administrator to determine which classes of audit events
should be logged for which system users.</para>
<para>The following is the defaults currently placed in
the <filename>audit_user</filename> file:</para>
@ -460,7 +483,7 @@ audit:fc:no</programlisting>
other auditing for the <username>audit</username>
user. While event auditing does not require a special
user exist, some configurations, specifically environments
making use of <acronym>MAC</acronym> may require it.</para>
making use of <acronym>MAC</acronym>, may require it.</para>
</sect3>
</sect2>
</sect1>
@ -468,16 +491,17 @@ audit:fc:no</programlisting>
<sect1 id="audit-administration">
<title>Event Audit Administration</title>
<para>Events from the <command>auditd</command> daemon cannot
<para>Events written by the kernel audit subsystem cannot
be altered or read in plain text. Data is stored and accessed
in a method similar to that of &man.ktrace.1; and &man.kdump.1,
in a method similar to that of &man.ktrace.1; and &man.kdump.1;,
that is, they may only be viewed by dumping them using the
<command>praudit</command> or <command>auditreduce</command>
utilities.</para>
<command>praudit</command> command; audit trails may be reduced
using the <command>auditreduce</command> command, which selects
records from an audit trail based on properties of interest, such
as the user, time of the event, and type of operation.</para>
<para>There are two utilities because of different requirements.
For example, the <command>praudit</command> will dump the entire
contents of a specified audit log in plain text. To dump an
<para>For example, the <command>praudit</command> utility will dump the
entire contents of a specified audit log in plain text. To dump an
audit log in its entirety, use:</para>
<screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen>
@ -489,7 +513,7 @@ audit:fc:no</programlisting>
command, where <username>trhodes</username> is the user of
choice:</para>
<screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE</userinput></screen>
<screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE | praudit</userinput></screen>
<para>This will select all audit records produced by the user
<username>trhodes</username> stored in the
@ -502,13 +526,17 @@ audit:fc:no</programlisting>
<sect2>
<title>Rotating Audit Log Files</title>
<para>Manually rotating audit log files will cause great
havoc within the system. Therefore, adding a line to
&man.newsyslog.conf.5; will provide no usefulness. So how
are the logs to be rotated? Sending the appropriate flag
to the <command>audit</command> utility will shut down
event auditing and safely rotate. The following command
should handle everything for an administrator:</para>
<para>Due to log reliability requirements, audit trails
are written to only by the kernel, and managed only by
<command>auditd</command>. Administrators should not
attempt to use &man.newsyslog.conf.5; or other tools to
directly rotate audit logs. Instead, the <command>audit</command>
management tool should be used to shut down auditing,
reconfigure the audit system, and perform log rotation.
The following command causes the audit daemon to create a
new audit log and signal the kernel to switch to using the
new log. The old log will be terminated and renamed, at
which point it may then be manipulated by the administrator.</para>
<screen>&prompt.root; <userinput>audit -n</userinput></screen>
@ -527,5 +555,17 @@ audit:fc:no</programlisting>
<para>The change will take effect once you have saved the
new <filename>/etc/crontab</filename>.</para>
</sect2>
<sect2>
<title>Delegating Audit Review Rights</title>
<para>By default, only the root user has the right to read system audit
logs. However, that right may be delegated to members of the
<literal>audit</literal> group, as the audit directory and audit
trail files are assigned to that group, and made group-readable. As
the ability to track audit log contents provides significant insight
into the behavior of users and processes, it is recommended that the
delegation of audit review rights be performed with caution.</para>
</sect2>
</sect1>
</chapter>

63
zh_TW.Big5/books/handbook/basics/chapter.sgml
View file

@ -72,7 +72,7 @@
<indexterm><primary>virtual consoles</primary></indexterm>
<indexterm><primary>terminals</primary></indexterm>
<para> FreeBSD 的使用方式有很多種，其中一種就是在文字終端機上打字。
<para> 有很多方法可以操作 FreeBSD ，其中一種就是在文字終端機上打字。
如此使用 FreeBSD 即可輕易的體會到 &unix; 作業系統的威力和彈性。
這一節描述什麼是<quote>終端機</quote>和<quote>console</quote>，及以您在 FreeBSD 中可以怎麼使用它們。
@ -151,43 +151,34 @@ Password:</screen>
</sect2>
<sect2 id="consoles-virtual">
<title>Multiple Consoles</title>
<title>多重 Console</title>
<para>Running &unix; commands in one console is fine, but FreeBSD can
run many programs at once. Having one console where commands can be
typed would be a bit of a waste when an operating system like FreeBSD
can run dozens of programs at the same time. This is where
<quote>virtual consoles</quote> can be very helpful.</para>
<para>在一個 Console 下執行 &unix; 當然是沒有問題，然而FreeBSD是可以同時執行很多程式的。
像 FreeBSD 這樣可以同時執行一大堆程式的作業系統，只有一個 console 可以輸入指令是有點浪費。
在此<quote>virtual consoles</quote>就很有用了。
</para>
<para>FreeBSD can be configured to present you with many different
virtual consoles. You can switch from one of them to any other
virtual console by pressing a couple of keys on your keyboard. Each
console has its own different output channel, and FreeBSD takes care
of properly redirecting keyboard input and monitor output as you
switch from one virtual console to the next.</para>
<para>Special key combinations have been reserved by FreeBSD for
switching consoles<footnote>
<para>A fairly technical and accurate description of all the details
of the FreeBSD console and keyboard drivers can be found in the
manual pages of &man.syscons.4;, &man.atkbd.4;, &man.vidcontrol.1;
and &man.kbdcontrol.1;. We will not expand on the details here,
but the interested reader can always consult the manual pages for
a more detailed and thorough explanation of how things
work.</para>
</footnote>. You can use
<keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>,
<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, through
<keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> to switch
to a different virtual console in FreeBSD.</para>
<para>As you are switching from one console to the next, FreeBSD 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 you can use to type commands for
FreeBSD to run. The programs that you launch on one virtual console
do not stop running when that console is not visible. They continue
running when you have switched to a different virtual console.</para>
<para> FreeBSD 可以被設定成同時有很多 virtual console ，用幾個按鍵的組合就可以從一個 virtual console 跳到別的 virtual console 去。 每一個 console 都有自已不同的輸出頻道， 當從某一個 virtual console 切換到下一個的時候，FreeBSD 會適當的處理鍵盤輸入及螢幕輸出。</para>
<para>FreeBSD 保留了特別的按鍵組合來切換 console
<footnote>
<para>在 &man.syscons.4;、 &man.atkbd.4;、 &man.vidcontrol.1;、以及
&man.kbdcontrol.1;等 manual page 中，對於 FreeBSD 的 console
及鍵盤驅動程式有十分技術性且詳細的描述。
我們在這裡不討論細節，有興趣的讀者隨時可以在 manual page
中查到關於運作方式的更詳細且完整的解釋</para>
</footnote>。 您可以用
<keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>、
<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>、到
<keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo>來切換 FreeBSD
的不同 console。 </para>
<para>
當您從一個 console 切換到下一個的時候， FreeBSD 會處理螢幕輸出的儲存及回復。
這就<quote>好像</quote>有很多<quote>虛擬</quote>的螢幕和鍵盤可以讓您輸入指令給
FreeBSD 執行。 在某一個 console 上執行的程式並不會因為切到別的 console
而停止執行，當您切換到另一個 console 的時候，他們會繼續執行。
</para>
</sect2>
<sect2 id="consoles-ttys">

2
zh_TW.Big5/books/handbook/book.sgml
View file

@ -47,6 +47,7 @@
<!ENTITY % chap.index "IGNORE">
<!ENTITY % chap.freebsd-glossary "IGNORE">
<!ENTITY % chap.mac "IGNORE">
<!ENTITY % chap.audit "IGNORE">
<!ENTITY % pgpkeys SYSTEM "../../../share/pgpkeys/pgpkeys.ent"> %pgpkeys;
]>
@ -242,6 +243,7 @@
<![ %chap.users; [ &chap.users; ]]>
<![ %chap.security; [ &chap.security; ]]>
<![ %chap.mac; [ &chap.mac; ]]>
<![ %chap.audit; [ &chap.audit; ]]>
<![ %chap.disks; [ &chap.disks; ]]>
<![ %chap.geom; [ &chap.geom; ]]>
<![ %chap.vinum; [ &chap.vinum; ]]>

3
zh_TW.Big5/books/handbook/chapters.ent
View file

@ -7,7 +7,7 @@
Chapters should be listed in the order in which they are referenced.
$FreeBSD$
Original revision: 1.32
Original revision: 1.33
-->
<!ENTITY chap.preface SYSTEM "preface/preface.sgml">
@ -32,6 +32,7 @@
<!ENTITY chap.users SYSTEM "users/chapter.sgml">
<!ENTITY chap.security SYSTEM "security/chapter.sgml">
<!ENTITY chap.mac SYSTEM "mac/chapter.sgml">
<!ENTITY chap.audit SYSTEM "audit/chapter.sgml">
<!ENTITY chap.disks SYSTEM "disks/chapter.sgml">
<!ENTITY chap.geom SYSTEM "geom/chapter.sgml">
<!ENTITY chap.vinum SYSTEM "vinum/chapter.sgml">

965
zh_TW.Big5/books/handbook/desktop/chapter.sgml
View file

File diff suppressed because it is too large Load diff

265
zh_TW.Big5/books/handbook/disks/chapter.sgml
View file

@ -12,8 +12,11 @@
<title>概述</title>
<para>本章涵蓋如何在 FreeBSD 下使用碟片裝置，包含
memory-backed disk (用記憶體作為硬碟使用)、跨網路使用的硬碟、
<para>本章涵蓋如何在 FreeBSD 下使用碟片裝置
<footnote><para>譯註：雖然有些設備沒有『碟片』，例如 USB 隨身碟，
不過在此仍把 Disk 譯為『碟片裝置』。此外，為方便起見，
後文所有的 Disk 都譯為『硬碟』。</para></footnote>
包含 memory-backed disk (用記憶體作為硬碟使用)、跨網路使用的硬碟、
標準 SCSI/IDE 硬碟、USB 介面的設備等。</para>
<para>閱讀本章後，您裝學會：</para>
@ -178,7 +181,9 @@
<emphasis>dedicated</emphasis> 模式，
不然的話 FreeBSD 必須置身於其中一個 PC BIOS partition 中。
在 FreeBSD 裡，PC BIOS partition 稱為 <emphasis>slice</emphasis>，
這是為了不要和傳統的 BSD partition 搞混了。
這是為了不要和傳統的 BSD partition 搞混了
<footnote><para>譯註：基於相同的理由，
現在 BSD partition 常稱為 BSD label，或簡稱 label。</para></footnote>
不論是完全由 FreeBSD 使用的硬碟，還是安裝了其它作業系統的硬碟，
您都可以使用 slice。這樣的好處是，其它非 FreeBSD 作業系統的
<command>fdisk</command> 工具可以順利操作。</para>
@ -198,156 +203,150 @@
因此最大是 16TB。如果要使用更大的硬碟，請使用 &man.gpt.8;。</para>
<sect2>
<title>Using &man.sysinstall.8;</title>
<title>使用 &man.sysinstall.8;</title>
<indexterm>
<primary><application>sysinstall</application></primary>
<secondary>adding disks</secondary>
<secondary>新增硬碟</secondary>
</indexterm>
<indexterm>
<primary>su</primary>
</indexterm>
<procedure>
<step>
<title>Navigating <application>Sysinstall</application></title>
<title>操作 <application>Sysinstall</application></title>
<para>You may use <command>sysinstall</command>
<para>透過 <command>sysinstall</command>
(<command>/stand/sysinstall</command> in &os; versions older
than 5.2) to
partition and label a new disk using its easy to use menus.
Either login as user <username>root</username> or use the
<command>su</command> command. Run
<command>sysinstall</command> and enter the
<literal>Configure</literal> menu. Within the
<literal>FreeBSD Configuration Menu</literal>, scroll down and
select the <literal>Fdisk</literal> option.</para>
than 5.2) 的選單介面，您可以輕易為硬碟分割 BIOS partition(slice)
和 BSD patition。您必須以 root 身份使用 <command>sysinstall</command>，
要嘛用 root 登入，要嘛用 <command>su</command> 切換到 root。
執行 <command>sysinstall</command> 後，選 <Literal>Configure</literal>
，在 <literal>FreeBSD Configuration Menu</literal> 裡移到
<literal>Fdisk</literal> 選項，
</step>
<step>
<title><application>fdisk</application> Partition Editor</title>
<para>Once inside <application>fdisk</application>, typing <userinput>A</userinput> will
use the entire disk for FreeBSD. When asked if you want to
<quote>remain cooperative with any future possible operating
systems</quote>, answer <literal>YES</literal>. Write the
changes to the disk using <userinput>W</userinput>. Now exit the
FDISK editor by typing <userinput>q</userinput>. Next you will be
asked about the <quote>Master Boot Record</quote>. Since you are adding a
disk to an already running system, choose
<literal>None</literal>.</para>
<title><application>fdisk</application> Partition 編輯器</title>
<para>在 <application>fdisk</application> 裡，按下
<userinput>A</userinput> 表示整個硬碟都給 FreeBSD 使用。
接著會提示您『是否要相容其它的作業系統』，回答 <literal>YES</literal>。
按 <userinput>W</userinput> 會將這些改變立即寫入硬碟，
再按 <userinput>q</userinput> 可以離開 FDISK 編輯器。
接下來會問您要將 <quote>Master Boot Record</quote> 安裝於何處，
由於現在是新增硬碟，表示作業系統已經裝在別的硬碟上了，所以可以
<literal>None</literal> 就行了。</para>
</step>
<step>
<title>Disk Label Editor</title>
<title>Disk Label Editor(硬碟 Label 編輯器)</title>
<indexterm><primary>BSD partitions</primary></indexterm>
<para>Next, you need to exit <application>sysinstall</application>
and start it again. Follow the directions above, although this
time choose the <literal>Label</literal> option. This will
enter the <literal>Disk Label Editor</literal>. This
is where you will create the traditional BSD partitions. A
disk can have up to eight partitions, labeled
<literal>a-h</literal>.
A few of the partition labels have special uses. The
<literal>a</literal> partition is used for the root partition
(<filename>/</filename>). Thus only your system disk (e.g,
the disk you boot from) should have an <literal>a</literal>
partition. The <literal>b</literal> partition is used for
swap partitions, and you may have many disks with swap
partitions. The <literal>c</literal> partition addresses the
entire disk in dedicated mode, or the entire FreeBSD slice in
slice mode. The other partitions are for general use.</para>
<para>接著請關閉 <application>sysinstall</application>，
再重開一次。照著上一節的指示，不過這次改選 <literal>Label</literal>
進入 <literal>Disk Label Editor</literal>，在此您可以編輯傳統的
BSD partition。一個硬碟(或著一個 slice) 最多可切分成 8 個 BSD partition，
依序用 <literal>a-h</literal> 來表示。
有些字母有特別的意義，<literal>a</literal> partition 表示這是
root partition(根分割區，<filename>/</filename>)，
因此只有安裝系統的硬碟(例如用來開機的硬碟) 有
<literal>a</literal> partition。<literal>b</literal> partition
表示這是 swap partitions(交換分割區)，每個硬碟上都可以有交換分割區。
<literal>c</literal> partition
用來表示整個硬碟(如果使用 dedicated mode 的話)
或整個 slice。其它的字母則用來表示普通的 BSD partition。</para>
<para><application>sysinstall</application>'s Label editor
favors the <literal>e</literal>
partition for non-root, non-swap partitions. Within the
Label editor, create a single file system by typing
<userinput>C</userinput>. When prompted if this will be a FS
(file system) or swap, choose <literal>FS</literal> and type in a
mount point (e.g, <filename>/mnt</filename>). When adding a
disk in post-install mode, <application>sysinstall</application>
will not create entries
in <filename>/etc/fstab</filename> for you, so the mount point
you specify is not important.</para>
<para><application>sysinstall</application> 的
Label editor(硬碟 Label 編輯器) 偏好用 <literal>e</literal>
來表示非 root、也非 swap 的分割區
<footnote><para>譯註：老實說我看不懂這句指的是什麼？原文是
<application>sysinstall</application> Label editor
favors the <literal>e</literal> partition for non-root,
non-swap partitions. </para></footnote> 在 Label editor 裡，
按 <userinput>C</userinput> 可以新增一個檔案系統(BSD label)，
它會問您這是一個 FS(file system，檔案系統) 或是 swap(交換分割區)，
選擇 <literal>FS</literal> 接著輸入要掛載的位置
(例如 <filename>/mnt</filename>)。如果系統安裝完後才新增硬碟，
<application>sysinstall</application> 不會幫您把這筆掛載資料加入
<filename>/etc/fstab</filename>，所以掛載的位置不太重要。</para>
<para>You are now ready to write the new label to the disk and
create a file system on it. Do this by typing
<userinput>W</userinput>. Ignore any errors from
<application>sysinstall</application> that
it could not mount the new partition. Exit the Label Editor
and <application>sysinstall</application> completely.</para>
<para>當您準備好將新的 label 寫入硬碟、建立檔案系統，
按 <userinput>W</userinput> 即可。如果出現在什麼錯誤，
<application>sysinstall</application> 可能無法幫您掛載這個新分割區。
結束 Label Editor、結束 <application>sysinstall</application> 就行了。
</step>
<step>
<title>Finish</title>
<title>完成</title>
<para>The last step is to edit <filename>/etc/fstab</filename>
to add an entry for your new disk.</para>
<para>最後要做的是編輯 <filename>/etc/fstab</filename>，
加入您新增的分割區資訊。</para>
</step>
</procedure>
</sect2>
<sect2>
<title>Using Command Line Utilities</title>
<title>使用命令列工具</title>
<sect3>
<title>Using Slices</title>
<para>This setup will allow your disk to work correctly with
other operating systems that might be installed on your
computer and will not confuse other operating systems'
<command>fdisk</command> utilities. It is recommended
to use this method for new disk installs. Only use
<literal>dedicated</literal> mode if you have a good reason
to do so!</para>
<title>使用 Slices(BIOS partitions)</title>
<para>這種模式能讓您的硬碟分割區與其它作業系統的
<command>fdisk</command> 工具和平共處，因此我們建議您使用 slice 模式。
如果您一定要使用 <literal>dedicated</literal> 模式，
您得有個好理由！
<footnote><para>譯註：如果您自始至終都不打算將這個硬碟用於 FreeBSD
之外的作業系統，那可以算是個好理由。不過就算如此，
用 slice 模式也沒什麼壞處就是了:-)。</para></footnote></para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
&prompt.root; <userinput>fdisk -BI da1</userinput> #Initialize your new disk
&prompt.root; <userinput>disklabel -B -w -r da1s1 auto</userinput> #Label it.
&prompt.root; <userinput>disklabel -e da1s1</userinput> # Edit the disklabel just created and add any partitions.
&prompt.root; <userinput>fdisk -BI da1</userinput> # 初始您的硬碟。
&prompt.root; <userinput>disklabel -B -w -r da1s1 auto</userinput> # 建立 disklabel。
&prompt.root; <userinput>disklabel -e da1s1</userinput> # 編輯 disklabel 以新增 label。
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # Repeat this for every partition you created.
&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # Mount the partition(s)
&prompt.root; <userinput>vi /etc/fstab</userinput> # Add the appropriate entry/entries to your <filename>/etc/fstab</filename>.</screen>
&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # 如果您新增了多個 label，對每個 label 重覆這個步驟。
&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # 掛載這些新 label。
&prompt.root; <userinput>vi /etc/fstab</userinput> # 在 <filename>/etc/fstab</filename> 加入適當的資訊。</screen>
<para>If you have an IDE disk, substitute <filename>ad</filename>
for <filename>da</filename>. On pre-4.X systems use
<filename>wd</filename>.</para>
<para>如果您新增的是 IDE 硬碟，將 <filename>da</filename>
改成 <filename>da</filename> 即可
<footnote><para>譯註：da 是 direct access，ad 則是 ata disk。</para></footnote>。
而如果是 4.X 之前的系統，用 <filename>wd</filename>。</para>
</sect3>
<sect3>
<title>Dedicated</title>
<indexterm><primary>OS/2</primary></indexterm>
<para>If you will not be sharing the new drive with another operating
system, you may use the <literal>dedicated</literal> mode. Remember
this mode can confuse Microsoft operating systems; however, no damage
will be done by them. IBM's &os2; however, will
<quote>appropriate</quote> any partition it finds which it does not
understand.</para>
<para>如果您不打算將新硬碟用於其它的作業系統，
您可以使用 <literal>dedicated</literal> 模式。注意：
Microsoft 的作業系統認不得這個模式，不過也不會去破壞它；
然而 IBM 的 &os2; 就沒那麼好心了，它會去調整所有它不認得的分割區
<footnote><para>譯註：我對這句的意思沒什麼信心，原文是 IBM's &os2; however,
will <quote>appropriate</quote> any partition it finds which it does
not understand.</para></footnote>。</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
&prompt.root; <userinput>disklabel -Brw da1 auto</userinput>
&prompt.root; <userinput>disklabel -e da1</userinput> # create the `e' partition
&prompt.root; <userinput>disklabel -e da1</userinput> # 建立 `e' partition。
&prompt.root; <userinput>newfs -d0 /dev/da1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
&prompt.root; <userinput>vi /etc/fstab</userinput> # 新增一筆 /dev/da1e 的資訊。
&prompt.root; <userinput>mount /1</userinput></screen>
<para>An alternate method is:</para>
<para>另一種方法：</para>
<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 count=2</userinput>
&prompt.root; <userinput>disklabel /dev/da1 | disklabel -BrR da1 /dev/stdin</userinput>
&prompt.root; <userinput>newfs /dev/da1e</userinput>
&prompt.root; <userinput>mkdir -p /1</userinput>
&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
&prompt.root; <userinput>vi /etc/fstab</userinput> # 新增一筆 /dev/da1e 的資訊。
&prompt.root; <userinput>mount /1</userinput></screen>
<note><para>Since &os;&nbsp;5.1-RELEASE, the &man.bsdlabel.8;
utility replaces the old &man.disklabel.8; program. With
&man.bsdlabel.8; a number of obsolete options and parameters
have been retired; in the examples above the option
<option>-r</option> should be removed with &man.bsdlabel.8;.
For more information, please refer to the &man.bsdlabel.8;
manual page.</para></note>
<note><para>從 &os;&nbsp;5.1-RELEASE 開始，&man.bsdlabel.8; 取代原本的
&man.disklabel.8; 程式，某些指令參數已經廢棄不用。
上面範例裡，如果用的是 &man.bsdlabel.8;，<option>-r</option>
參數應該拿掉。更多的資訊請參考 &man.bsdlabel.8; manual page。
</para></note>
</sect3>
</sect2>
</sect1>
@ -356,7 +355,7 @@
<title>RAID</title>
<sect2 id="raid-soft">
<title>Software RAID</title>
<title>軟體 RAID</title>
<sect3 id="ccd">
<sect3info>
@ -381,59 +380,43 @@
<primary>RAID</primary><secondary>CCD</secondary>
</indexterm>
<title>Concatenated Disk Driver (CCD) Configuration</title>
<para>When choosing a mass storage solution the most important
factors to consider are speed, reliability, and cost. It is
rare to have all three in balance; normally a fast, reliable mass
storage device is expensive, and to cut back on cost either speed
or reliability must be sacrificed.</para>
<para>In designing the system described below, cost was chosen
as the most important factor, followed by speed, then reliability.
Data transfer speed for this system is ultimately
constrained by the network. And while reliability is very important,
the CCD drive described below serves online data that is already
fully backed up on CD-R's and can easily be replaced.</para>
<para>Defining your own requirements is the first step
in choosing a mass storage solution. If your requirements prefer
speed or reliability over cost, your solution will differ from
the system described in this section.</para>
<title>連接式磁碟裝置驅動程式(CCD, Concatenated Disk Driver) 設定</title>
<para>對大容量儲存設備而言，最關鍵的要素乃是速度、可靠性及價格。
然而這三者往往難以兼顧：快速可靠的設備通常很貴；
而降低成本通常也犧牲了速度或可靠性。</para>
<para>接下來要介紹的系統，價格是最重要的考量，接下來是速度，最後才是可靠性。
順序如此是因為資料傳輸的速度最終取決於網路，而儘管可靠性十分重要，
卻有簡單的取代方案：將資料完整備份於 CD-R 中。</para>
<para>選擇大容量儲存設備方案時，首先要定義您的需求。如果您重視速度或可靠性
甚於價格，接下來的介紹恐非您所需。</para>
<sect4 id="ccd-installhw">
<title>Installing the Hardware</title>
<title>安裝硬體</title>
<para>In addition to the IDE system disk, three Western
Digital 30GB, 5400 RPM IDE disks form the core
of the CCD disk described below providing approximately
90GB of online storage. Ideally,
each IDE disk would have its own IDE controller
and cable, but to minimize cost, additional
IDE controllers were not used. Instead the disks were
configured with jumpers so that each IDE controller has
one master, and one slave.</para>
<para>除了系統磁碟外，下面介紹的 CCD 磁碟陣列將使用到三顆 30GB、
5400 RPM 的 Western Digital IDE 磁碟，以提供約 90GB 的儲存空間。
最理想的情況是每個磁碟由獨立使用的排線連接獨立使用的 IDE 控制器，
不過為了降低成本，利用 jumper 設定磁碟，使每個 IDE 控制器可連接
一個主磁碟加一個副磁碟，如此可不必加裝額外的 IDE 控制器。</para>
<para>Upon reboot, the system BIOS was configured to
automatically detect the disks attached. More importantly,
FreeBSD detected them on reboot:</para>
<para>開機後，BIOS 應該設定成自重偵測磁碟。更重要的是 FreeBSD 應該
要偵測到它們：</para>
<programlisting>ad0: 19574MB &lt;WDC WD205BA&gt; [39770/16/63] at ata0-master UDMA33
ad1: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata0-slave UDMA33
ad2: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-master UDMA33
ad3: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-slave UDMA33</programlisting>
<note><para>If FreeBSD does not detect all the disks, ensure
that you have jumpered them correctly. Most IDE drives
also have a <quote>Cable Select</quote> jumper. This is
<emphasis>not</emphasis> the jumper for the master/slave
relationship. Consult the drive documentation for help in
identifying the correct jumper.</para></note>
<note><para>如果 FreeBSD 沒有偵測到所有磁碟，請確認 jumper 都設定正確。
許多 IDE 磁碟可以設定成 <quote>Cable Select</quote>(根據排線位置決定)，
這<emphasis>並非</emphasis> master(主磁碟) 或 slave(副磁碟)。請參閱磁
碟的說明文件以正確設定 jumper。</para></note>
<para>Next, consider how to attach them as part of the file
system. You should research both &man.vinum.8; (<xref
linkend="vinum-vinum">) and &man.ccd.4;. In this
particular configuration, &man.ccd.4; was chosen.</para>
<para>接下來，考慮如何將它們變成檔案系統的一部份。您可以參考
&man.vinum.8;(<xref linkend="vinum-vinum">) 及 &man.ccd.4。
在此我們選擇 &man.ccd.4; 。</para>
</sect4>
<sect4 id="ccd-setup">

545
zh_TW.Big5/books/handbook/firewalls/chapter.sgml
View file

@ -2,7 +2,7 @@
The FreeBSD Documentation Project
$FreeBSD$
Original revision: 1.64
Original revision: 1.66
-->
<chapter id="firewalls">
@ -23,358 +23,293 @@
</authorgroup>
</chapterinfo>
<title>Firewalls</title>
<title>防火牆</title>
<indexterm><primary>firewall</primary></indexterm>
<indexterm><primary>防火牆</primary></indexterm>
<indexterm>
<primary>security</primary>
<primary>安全</primary>
<secondary>firewalls</secondary>
<secondary>防火牆</secondary>
</indexterm>
<sect1 id="firewalls-intro">
<title>Introduction</title>
<para>Firewalls make it possible to filter
incoming and outgoing traffic that flows through your system.
A firewall can use one or more sets of <quote>rules</quote> to
inspect the network packets as they come in or go out of your
network connections and either allows the traffic through or
blocks it. The rules of a firewall can inspect one or more
characteristics of the packets, including but not limited to the
protocol type, the source or destination host address, and the
source or destination port.</para>
<para>Firewalls can greatly enhance the security of a host or a
network. They can be used to do one or more of
the following things:</para>
<title>介紹</title>
<para>防火牆能夠過濾你的系統中進出的流量。
防火牆也能藉由設置一或多組「規則 (rules)」
來檢查你的網路連結中進出的網路封包 (network packets)，
並且能允許或阻擋其通過。
這些防火牆的規則可以檢查封包中的特徵，
這些特徵涵蓋，但不限於某些通訊協定類型、主機位址的來源或目的，
以及連接埠 (port) 的來源及目的。</para>
<para>防火牆能夠大幅地增強主機或是網路的安全性。
它也能夠用來執行下列事項：</para>
<itemizedlist>
<listitem>
<para>To protect and insulate the applications, services and
machines of your internal network from unwanted traffic
coming in from the public Internet.</para>
<para>保護或隔離你內部網路的應用程式、
服務以及機器，免於被來自 Internet 中你不想要的傳輸所影響
</para>
</listitem>
<listitem>
<para>To limit or disable access from hosts of the internal
network to services of the public Internet.</para>
<para>限制或禁止內部網路對 Internet 的存取服務</para>
</listitem>
<listitem>
<para>To support network address translation
(<acronym>NAT</acronym>), which allows your internal network
to use private <acronym>IP</acronym> addresses and share a
single connection to the public Internet (either with a
single <acronym>IP</acronym> address or by a shared pool of
automatically assigned public addresses).</para>
<para>支援「網路位址轉換」(network address translation
, <acronym>NAT</acronym>)，
它可以允許你的內部網路使用私有<acronym>IP</acronym>
位址並可以共同分享一個單一連線到網際網路上
(可同時用單一<acronym>IP</acronym>位址或是一組公共網址)
</para>
</listitem>
</itemizedlist>
<para>After reading this chapter, you will know:</para>
<para>讀完這章之後，你將會知道：</para>
<itemizedlist>
<listitem>
<para>How to properly define packet filtering rules.</para>
<para>如何適當地訂出封包過濾的規則。</para>
</listitem>
<listitem>
<para>The differences between the firewalls
built into &os;.</para>
<para>&os; 中內建的防火牆之間的差異。</para>
</listitem>
<listitem>
<para>How to use and configure the OpenBSD
<application>PF</application> firewall.</para>
<para>如何使用及設定 OpenBSD 的
<application>PF</application> 防火牆。
</listitem>
<listitem>
<para>How to use and configure
<application>IPFILTER</application>.</para>
<para>如何使用及設定
<application>IPFILTER</application>。</para>
</listitem>
<listitem>
<para>How to use and configure
<application>IPFW</application>.</para>
<para>如何使用及設定
<application>IPFW</application>。</para>
</listitem>
</itemizedlist>
<para>Before reading this chapter, you should:</para>
<para>在閱讀這章之前，你必須：</para>
<itemizedlist>
<listitem>
<para>Understand basic &os; and Internet concepts.</para>
<para>了解基本的 &os; 和 Internet 觀念</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="firewalls-concepts">
<title>Firewall Concepts</title>
<title>防火牆概念</title>
<indexterm>
<primary>firewall</primary>
<primary>防火牆</primary>
<secondary>rulesets</secondary>
<secondary>規則</secondary>
</indexterm>
<para>There are two basic ways to create firewall rulesets:
<quote>inclusive</quote> or <quote>exclusive</quote>. An
exclusive firewall allows all traffic through except for the
traffic matching the ruleset. An inclusive firewall does the
reverse. It only allows traffic matching the rules through and
blocks everything else.</para>
<para>
有兩種基本的方式可以建立防火牆規則：
「先容式(exclusive)」或是「後容式(inclusive)」。
<!--inclusive/exclusive 參考 Mattlinuxer 的意見
因為 exclusive 防火牆是先容許所有封包通過，再透過規則阻擋
不想讓其通過的封包。而 inclusive 則是檔掉所有，後來再容許
符合規則的封包通過。
-->
「先容式(exclusive)」類似「黑名單」，它先允許所有封包通過，
然後違反規則的封包則禁止通過防火牆。
相反的，「後容式(inclusive)」類似「白名單」，它先擋住所有封包通過，
然後只允許有符合規則的才可通過防火牆。</para>
<para>Inclusive firewalls are generally safer than exclusive
firewalls because they significantly reduce the risk of allowing
unwanted traffic to pass through the firewall.</para>
<para>
整體來說，「後容式(inclusive)」的防火牆會比「先容式(exclusive)」的防火牆安全些。
因為後容式明顯降低了不必要的風險。</para>
<para>Security can be tightened further using a <quote>stateful
firewall</quote>. With a stateful firewall the firewall keeps
track of which connections are opened through the firewall and
will only allow traffic through which either matches an existing
connection or opens a new one. The disadvantage of a stateful
firewall is that it can be vulnerable to Denial of Service
(<acronym>DoS</acronym>) attacks if a lot of new connections are
opened very fast. With most firewalls it is possible to use a
combination of stateful and non-stateful behavior to make an
optimal firewall for the site.</para>
<para>此外，使用「狀態防火牆(stateful firewall)」可讓安全性更嚴密。
它會持續記錄通過防火牆開放的連線，
並且只允許符合現存或開啟新的連線才能通過防火牆。
狀態防火牆的缺點是如果在非常快的速度下開啟許多新連線，就可能會受到阻絕式服務攻擊
(<acronym>DoS</acronym>, Denial of Service)。
在大多數的防火牆方案中，也可以交互運用「狀態」及「非狀態」防火牆的組合，
使該站的防火牆達到最佳化。
</para>
</sect1>
<sect1 id="firewalls-apps">
<title>Firewall Packages</title>
<title>防火牆軟體套件</title>
<para>&os; has three different firewall packages built
into the base system. They are: <emphasis>IPFILTER</emphasis>
(also known as <acronym>IPF</acronym>),
<emphasis>IPFIREWALL</emphasis> (also known as <acronym>IPFW</acronym>),
and <emphasis>OpenBSD's PacketFilter</emphasis> (also known as
<acronym>PF</acronym>). &os; also has two built in packages for
traffic shaping (basically controlling bandwidth usage):
&man.altq.4; and &man.dummynet.4;. Dummynet has traditionally been
closely tied with <acronym>IPFW</acronym>, and
<acronym>ALTQ</acronym> with
<acronym>IPF</acronym>/<acronym>PF</acronym>. IPF,
IPFW, and PF all use rules to control the access of packets to and
from your system, although they go about it different ways and
have different rule syntaxes.</para>
<para>The reason that &os; has multiple built in firewall packages
is that different people have different requirements and
preferences. No single firewall package is the best.</para>
<para>在 &os; 基本系統中內建有三種不同的防火牆軟體套件。
它們分別是 <emphasis>IPFILTER</emphasis>
(也就是 <acronym>IPF</acronym>)、
<emphasis>IPFIREWALL</emphasis> (也就是 <acronym>IPFW</acronym>)，
以及<emphasis> OpenBSD 的 PacketFilter</emphasis> (即有名的 <acronym>PF</acronym>)。
&os; 也有兩個內建的流量控管套件(基本上是控制頻寬的使用)：
&man.altq.4; 以及 &man.dummynet.4;。
通常我們習慣把 Dummynet 與 <acronym>IPFW</acronym> 一併運用，
而 <acronym>ALTQ</acronym> 則是搭配
<acronym>IPF</acronym>/<acronym>PF</acronym> 一同使用。
雖然 IPF、IPFW 以及 PF 是使用不同的實做方式及規則語法，
但是它們都使用規則來控制是否允許資料封包進出你的系統。</para>
<para>&os; 為何會內建許多不同的防火牆軟體套件，
這是因為不同人會有不同的需求、偏好，很難說哪一個防火牆軟體套件是最好的。</para>
<para>The author prefers IPFILTER because its stateful rules are
much less complicated to use in a <acronym>NAT</acronym>
environment and it has a built in ftp proxy that simplifies the
rules to allow secure outbound FTP usage.</para>
<para>而筆者偏好 IPFILTER 的原因，是因為運用在 <acronym>NAT</acronym>
環境的時候，它的狀態規則是相對簡單許多的。
而且它內建的 FTP 代理，也簡化了如何設定安全的對外 FTP 服務規則。</para>
<para>Since all firewalls are based on inspecting the values of
selected packet control fields, the creator of the firewall
rulesets must have an understanding of how
<acronym>TCP</acronym>/IP works, what the different values in
the packet control fields are and how these values are used in a
normal session conversation. For a good explanation go to:
<!-- psilotum: 20060309: 這段實在翻的有點怪，參考 zh_CN 翻譯 -->
<para>正由於所有的防火牆都是以「檢查、控制所選定之封包」的實作，所以，
制定防火牆規則的人就更必須了解 <acronym>TCP</acronym>/IP 如何運作，
以及如何控制封包在正常 session 的各種作用。
更詳盡的說明，請參閱：
<ulink
url="http://www.ipprimer.com/overview.cfm"></ulink>.</para>
url="http://www.ipprimer.com/overview.cfm"></ulink>。</para>
</sect1>
<sect1 id="firewalls-pf">
<title>The OpenBSD Packet Filter (PF) and
<title>OpenBSD 封包過濾器 (Packet Filter, PF)及
<acronym>ALTQ</acronym></title>
<indexterm>
<primary>firewall</primary>
<primary>防火牆</primary>
<secondary>PF</secondary>
</indexterm>
<para>As of July 2003 the OpenBSD firewall software application
known as <acronym>PF</acronym> was ported to &os; and was made
available in the &os; Ports Collection; the first release that
contained <acronym>PF</acronym> as an integrated part of the
base system was &os;&nbsp;5.3 in November 2004.
<acronym>PF</acronym> is a complete, fully featured firewall
that has optional support for <acronym>ALTQ</acronym> (Alternate
Queuing). <acronym>ALTQ</acronym> provides Quality of Service
(<acronym>QoS</acronym>) bandwidth shaping that allows
guaranteeing bandwidth to different services based on filtering
rules. The OpenBSD Project does an outstanding job of
maintaining the PF User's Guide that it will not be made part of
this handbook firewall section as that would just be duplicated
effort.</para>
<para>在 2003 年 6 月份，OpenBSD 的防火牆軟體 <acronym>PF</acronym>
被移植到 &os; 中，並且收錄於 Ports Collection 內。
而 2004 年 11 月份所發行的 &os;&nbsp;5.3 版也是第一次將 <acronym>PF</acronym>
整合為基礎系統的一部分。
<acronym>PF</acronym>是個完備、全功能的防火牆，
並且具有選擇性 <acronym>ALTQ</acronym>(交錯佇列，Alternate Queuing)
<!--psilotum: 20060309 alternative queuing 參考 zh_CN 的翻譯 -->
的功能。
<acronym>ALTQ</acronym>提供了「服務品質」(<acronym>QoS</acronym>，
Quality of Service)的頻寬管理功能，
這提供了以過濾規則的方式來保障各種不同服務的頻寬。
OpenBSD 計劃中已經對 PF 的使用指南提供了詳盡的解說，
因此在這本手冊中我們不會作重複的贅述，而只介紹概要。</para>
<!--20060309 psilotum：怎麼翻譯都覺得有點怪，所以最後一句重寫-->
<para>The availability of PF for the various &os; releases and
versions is summarized below:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<thead>
<row>
<entry>&os; Version</entry>
<entry>PF Availability</entry>
</row>
</thead>
<tbody>
<row>
<entry>Pre-4.X versions</entry>
<entry>PF is not available for any release of &os; older
than the 4.X branch.</entry>
</row>
<row>
<entry>All versions of the 4.X branch</entry>
<entry>PF is available as part of KAME.</entry>
</row>
<row>
<entry>5.X releases before 5.3-RELEASE</entry>
<entry>The <filename role="package">security/pf</filename>
port can be used to install PF on these versions of &os;.
These releases were targeted to developers and people who
wanted a preview of early 5.X versions. Upgrading to
5.3-RELEASE or newer versions of &os; is strongly
recommended.</entry>
</row>
<row>
<entry>5.3-RELEASE and later versions</entry>
<entry>PF is part of the base system. Do
<emphasis>not</emphasis> use the <filename
role="package">security/pf</filename> port on these
versions of &os;. It will not work. Use the &man.pf.4;
support of the base system instead.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>More info can be found at the PF for &os; web site: <ulink
<para>更多關於 PF 的資訊可於下列網址查詢: <ulink
url="http://pf4freebsd.love2party.net/"></ulink>.</para>
<sect2>
<title>Enabling PF</title>
<title>啟用 PF</title>
<para>PF is included in the basic &os; install for versions newer
than 5.3 as a separate run time loadable module. The system
will dynamically load the PF kernel loadable module when the
rc.conf statement <literal>pf_enable="YES"</literal> is used.
The loadable module was created with &man.pflog.4; logging
enabled.</para>
<para>PF 在 &os; 5.3 之後的系統中，可以輕鬆使用動態模組來載入。
在 rc.conf 中加入 <literal>pf_enable="YES"</literal> 後，
系統將會動態地載入 PF 核心動態模組。這個模組會在建立時也啟用
&man.pflog.4; 記錄功能。</para>
<note>
<para>The module assumes the presence of <literal>options
INET</literal> and <literal>device bpf</literal>. Unless
<literal>NOINET6</literal> (for example in &man.make.conf.5;)
was defined during the build, it also requires <literal>options
INET6</literal>.</para>
<para>這個模組會假設核心內已有 <literal>options INET</literal> 和
<literal>device bpf</literal>。
除非編譯時在核心中有事先(像是在 &man.make.conf.5; 中)加入 <literal>NOINET6</literal>，
&os; 6.0 以後的版本則是 <literal>NO_INET6</literal>
這樣才會避免不打開 IPv6 支援，否則 pf 模組同時也需要 <literal>options INET6</literal>，
也就是 IPv6 支援。</para>
</note>
<para>一旦載入 PF 核心模組或靜態地編譯入核心中，
就可以使用 <command>pfctl</command> 來啟動或關閉
<application>pf</application>。</para>
<para>Once the kernel module is loaded or the kernel is statically
built with PF support, it is possible to enable or disable
<application>pf</application> with the <command>pfctl</command>
command.</para>
<para>This example demonstrates how to enable
<para>這個例子示範了如何啟動
<application>pf</application>:</para>
<screen>&prompt.root; <userinput>pfctl -e</userinput></screen>
<para>The <command>pfctl</command> command provides a way to work
with the <application>pf</application> firewall. It is a good
idea to check the &man.pfctl.8; manual page to find out more
information about using it.</para>
<para><command>pfctl</command>指令提供了一個使用<application>pf</application>
防火牆的方式。
要了解更多使用 <command>pfctl</command> 的資訊，
查閱 &man.pfctl.8; 的線上手冊會是個好方式。</para>
</sect2>
<sect2>
<title>Kernel options</title>
<title>kernel 選項</title>
<indexterm>
<primary>kernel options</primary>
<primary>kernel 選項</primary>
<secondary>device pf</secondary>
</indexterm>
<indexterm>
<primary>kernel options</primary>
<primary>kernel 選項</primary>
<secondary>device pflog</secondary>
</indexterm>
<indexterm>
<primary>kernel options</primary>
<primary>kernel 選項</primary>
<secondary>device pfsync</secondary>
</indexterm>
<para>It is not a mandatory requirement that you enable PF by
compiling the following options into the &os; kernel. It is
only presented here as background information. Compiling PF
into the kernel causes the loadable module to never be
used.</para>
<para>Sample kernel config PF option statements are in the
<filename>/usr/src/sys/conf/NOTES</filename> kernel source and
are reproduced here:</para>
<para>在編譯 &os; kernel 時，並不必完全加入下列的選項來啟用 PF。
在這裡只是要列出給你參考的一些資訊而已。
將 PF 編譯入 kernel 中，會導致無法使用 kernel 的動態載入模組。</para>
<para>設定 PF 的核心選項範例在 kernel 原始碼中的
<filename>/usr/src/sys/conf/NOTES</filename>，轉貼內容如下：</para>
<programlisting>device pf
device pflog
device pfsync</programlisting>
<para><literal>device pf</literal> enables support for the
<quote>Packet Filter</quote> firewall.</para>
<para><literal>device pf</literal> 啟用了
「封包過濾(packet filter)」 的防火牆支援.</para>
<para><literal>device pflog</literal> enables the optional
&man.pflog.4; pseudo network device which can be used to log
traffic to a &man.bpf.4; descriptor. The &man.pflogd.8; daemon
can be used to store the logging information to disk.</para>
<para><literal>device pflog</literal> 啟動了選擇性的 &man.pflog.4;
虛擬網路設備 pseudo network device)，它可以透過 &man.bpf.4;
的描述符號來記錄流量。
&man.pflogd.8; 服務可以用來儲存訊息，並可以用日誌的形式記錄在硬碟上。</para>
<!-- psilotum:20060311 參考 zh_CN 翻譯 -->
<para><literal>device pfsync</literal> 啟動了選擇性 的&man.pfsync.4;
虛擬網路設備，它可以用來監控「狀態的改變」。
<literal>device pfsync</literal>並不是可載入模組，
要使用的話，必須要編入自訂的核心中才行。</para>
<para><literal>device pfsync</literal> enables the optional
&man.pfsync.4; pseudo network device that is used to monitor
<quote>state changes</quote>. As this is not part of the
loadable module one has to build a custom kernel to use
it.</para>
<para>These settings will take effect only after you have built
and installed a kernel with them set.</para>
<para>這些設定將會在你編譯及安裝好新核心後才會生效。</para>
</sect2>
<sect2>
<title>Available rc.conf Options</title>
<title>rc.conf 可用的選項</title>
<para>You need the following statements in
<filename>/etc/rc.conf</filename> to activate PF at boot
time:</para>
<para>你需要在 <filename>/etc/rc.conf</filename>
中加入下列的設定以便在啟動系統時同時啟用 PF：</para>
<programlisting>pf_enable="YES" # Enable PF (load module if required)
pf_rules="/etc/pf.conf" # rules definition file for pf
pf_flags="" # additional flags for pfctl startup
pflog_enable="YES" # start pflogd(8)
pflog_logfile="/var/log/pflog" # where pflogd should store the logfile
pflog_flags="" # additional flags for pflogd startup</programlisting>
<programlisting>pf_enable="YES" # 啟用 PF (如果需要的話載入模組)
pf_rules="/etc/pf.conf" # PF 的規則定義檔案
pf_flags="" # pfctl 啟動時附加的選項
pflog_enable="YES" # 啟動 pflogd(8)
pflog_logfile="/var/log/pflog" # pflogd 儲存記錄檔案的地方
pflog_flags="" # pflogd 啟動時附加的選項</programlisting>
<para>If you have a LAN behind this firewall and have to forward
packets for the computers in the LAN or want to do NAT, you
have to enable the following option as well:</para>
<para>如果在這個防火牆後方你有個區域網路，並透過它來轉送封包，
你就必須要設定下列選項：</para>
<programlisting>gateway_enable="YES" # Enable as LAN gateway</programlisting>
<programlisting>gateway_enable="YES" # 啟用作為區域網路閘道器</programlisting>
</sect2>
<sect2>
<title>Enabling <acronym>ALTQ</acronym></title>
<title>啟用 <acronym>ALTQ</acronym></title>
<para><acronym>ALTQ</acronym> is only available by compiling the
options into the &os; Kernel. <acronym>ALTQ</acronym> is not
supported by all of the available network card drivers. Please
see the &man.altq.4; manual page for a list of drivers that are
supported in your release of &os;. The following options will
enable <acronym>ALTQ</acronym> and add additional
functionality.</para>
<para><acronym>ALTQ</acronym>的選項只有在編入 &os; 核心中才能生效。
不是所有的網路卡驅動程式都支援 <acronym>ALTQ</acronym>。
請看 &man.altq.4; 線上手冊來了解你使用的 &os; 版本中支援驅動程式的清單。
下面列出的選項將會啟用 <acronym>ALTQ</acronym> 及加入其他附加的功能。</para>
<programlisting>options ALTQ
options ALTQ_CBQ # Class Bases Queuing (CBQ)
@ -384,11 +319,12 @@ options ALTQ_HFSC # Hierarchical Packet Scheduler (HFSC)
options ALTQ_PRIQ # Priority Queuing (PRIQ)
options ALTQ_NOPCC # Required for SMP build</programlisting>
<para><literal>options ALTQ</literal> enables the
<acronym>ALTQ</acronym> framework.</para>
<para><literal>options ALTQ</literal> 啟用了
<acronym>ALTQ</acronym> 主架構。</para>
<para><literal>options ALTQ_CBQ</literal> enables Class Based
Queuing (<acronym>CBQ</acronym>). <acronym>CBQ</acronym>
<para><literal>options ALTQ_CBQ</literal> 啟用「基於分類的佇列」
(Class Based Queuing, <acronym>CBQ</acronym>)支援。
<acronym>CBQ</acronym> 允許你
allows you to divide a connection's bandwidth into different
classes or queues to prioritize traffic based on filter
rules.</para>
@ -453,25 +389,22 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
</sect1>
<sect1 id="firewalls-ipf">
<title>The IPFILTER (IPF) Firewall</title>
<title>IPFILTER (IPF) 防火牆</title>
<indexterm>
<primary>firewall</primary>
<primary>防火牆</primary>
<secondary>IPFILTER</secondary>
</indexterm>
<note>
<para>This section is work in progress. The contents might
not be accurate at all times.</para>
<para>此小節的說明仍待陸續補充、更新，所以本內容可能並非完全符合現況。</para>
</note>
<para>The author of IPFILTER is Darren Reed. IPFILTER is not
operating system dependent: it is an open source application and
has been ported to &os;, NetBSD, OpenBSD, &sunos;, HP/UX, and
&solaris; operating systems. IPFILTER is actively being
supported and maintained, with updated versions being released
regularly.</para>
<para>IPFILTER 的作者為 Darren Reed。IPFILTER 並非
operating system dependent：它是個 open source 應用程式，且已被移植到
&os;、NetBSD、OpenBSD、&sunos;、HP/UX 以及
&solaris; 這些作業系統上。此外，IPFILTER 的支援以及維護也相當積極，也有定期釋出的更新版。</para>
<para>IPFILTER is based on a kernel-side firewall and
<acronym>NAT</acronym> mechanism that can be controlled and
@ -484,10 +417,10 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
files.</para>
<para>IPF was originally written using a rule processing logic of
<quote>the last matching rule wins</quote> and used only
「the last matching rule wins」 and used only
stateless type of rules. Over time IPF has been enhanced to
include a <quote>quick</quote> option and a stateful <quote>keep
state</quote> option which drastically modernized the rules
include a 「quick」 option and a stateful 「keep
state」 option which drastically modernized the rules
processing logic. IPF's official documentation covers the legacy
rule coding parameters and the legacy rule file processing
logic. The modernized functions are only included as additional
@ -495,8 +428,8 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
far superior secure firewall.</para>
<para>The instructions contained in this section are based on
using rules that contain the <quote>quick</quote> option and the
stateful <quote>keep state</quote> option. This is the basic
using rules that contain the 「quick」 option and the
stateful 「keep state」 option. This is the basic
framework for coding an inclusive firewall rule set.</para>
<!-- XXX: something like this already in
@ -518,16 +451,16 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
and <ulink
url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>.</para>
<para>The IPF FAQ is at <ulink
<para>IPF 的 FAQ 位於 <ulink
url="http://www.phildev.net/ipf/index.html"></ulink>.</para>
<sect2>
<title>Enabling IPF</title>
<title>啟用 IPF</title>
<indexterm>
<primary>IPFILTER</primary>
<secondary>enabling</secondary>
<secondary>啟用</secondary>
</indexterm>
<para>IPF is included in the basic &os; install as a separate run
@ -542,7 +475,7 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
</sect2>
<sect2>
<title>Kernel options</title>
<title>kernel 選項</title>
<indexterm>
<primary>kernel options</primary>
@ -568,11 +501,9 @@ options ALTQ_NOPCC # Required for SMP build</programlisting>
<secondary>kernel options</secondary>
</indexterm>
<para>It is not a mandatory requirement that you enable IPF by
compiling the following options into the &os; kernel. It is
only presented here as background information. Compiling IPF
into the kernel causes the loadable module to never be
used.</para>
<para>在編譯 &os; kernel 時，並不必完全加入下列的選項來啟用 IPF。
在這裡只是要列出給你參考的一些資訊而已。
將 IPF 編譯入 kernel 中，會導致無法使用 kernel 的動態載入模組。</para>
<para>Sample kernel config IPF option statements are in the
<filename>/usr/src/sys/conf/NOTES</filename> kernel source
@ -584,7 +515,7 @@ options IPFILTER_LOG
options IPFILTER_DEFAULT_BLOCK</programlisting>
<para><literal>options IPFILTER</literal> enables support for the
<quote>IPFILTER</quote> firewall.</para>
「IPFILTER」 firewall.</para>
<para><literal>options IPFILTER_LOG</literal> enables the option
to have IPF log traffic by writing to the
@ -601,26 +532,24 @@ options IPFILTER_DEFAULT_BLOCK</programlisting>
</sect2>
<sect2>
<title>Available rc.conf Options</title>
<title>可用的 rc.conf 選項</title>
<para>You need the following statements in
<filename>/etc/rc.conf</filename> to activate IPF at boot
time:</para>
<para>須在 <filename>/etc/rc.conf</filename> 內加入下列內容，以便在開機時就會啟用 IPF：</para>
<programlisting>ipfilter_enable="YES" # Start ipf firewall
ipfilter_rules="/etc/ipf.rules" # loads rules definition text file
ipmon_enable="YES" # Start IP monitor log
ipmon_flags="-Ds" # D = start as daemon
# s = log to syslog
# v = log tcp window, ack, seq
# n = map IP &amp; port to names</programlisting>
ipfilter_rules="/etc/ipf.rules" # 載入定義規則的文字檔案
ipmon_enable="YES" # 啟用 IP 監控記錄
ipmon_flags="-Ds" # D = 使用服務程序 (daemon) 啟動
# s = 使用 syslog 記錄
# v = 記錄於 tcp window, ack, seq
# n = 將 IP 及 port 對應至名稱中</programlisting>
<para>If you have a LAN behind this firewall that uses the
reserved private IP address ranges, then you need to add the
following to enable <acronym>NAT</acronym>
functionality:</para>
<programlisting>gateway_enable="YES" # Enable as LAN gateway
<programlisting>gateway_enable="YES" # 啟用為區域網路閘道器
ipnat_enable="YES" # Start ipnat function
ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat</programlisting>
</sect2>
@ -801,9 +730,9 @@ ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat</programlist
<para><application>Syslogd</application> uses its own special
method for segregation of log data. It uses special groupings
called <quote>facility</quote> and <quote>level</quote>. IPMON
called 「facility」 and <quote>level</quote>. IPMON
in <option>-Ds</option> mode uses <literal>security</literal>
(<literal>local0</literal> in 4.X) as the <quote>facility</quote>
(<literal>local0</literal> in 4.X) as the 「facility」
name. All IPMON logged data goes to <literal>security</literal>
(<literal>local0</literal> in 4.X). The following levels can be
used to further segregate the logged data if desired:</para>
@ -919,7 +848,7 @@ LOG_ERR - packets which have been logged and which can be considered short</scre
flags.</para>
<para>If the packet is an ICMP packet, there will be two fields
at the end, the first always being <quote>ICMP</quote>, and the
at the end, the first always being 「ICMP」, and the
next being the ICMP message and sub-message type, separated by
a slash, e.g. ICMP 3/3 for a port unreachable message.</para>
</sect2>
@ -951,11 +880,11 @@ LOG_ERR - packets which have been logged and which can be considered short</scre
<para>Start your rule file with something like this:</para>
<programlisting>############# Start of IPF rules script ########################
<programlisting>############# IPF 規則命令稿的開始 ########################
oif="dc0" # name of the outbound interface
odns="192.0.2.11" # ISP's DNS server IP address
myip="192.0.2.7" # my static IP address from ISP
oif="dc0" # 對外網路裝置的名稱
odns="192.0.2.11" # ISP 的 DNS 伺服器 IP 位址
myip="192.0.2.7" # 從我的 ISP 提供的靜態 IP
ks="keep state"
fks="flags S keep state"
@ -1028,12 +957,12 @@ sh /etc/ipf.rules.script</programlisting>
</listitem>
</itemizedlist>
<para>Now, when your system boots, your IPF rules will be
loaded.</para>
<para>從現在起，當你的系統開機時，
你的 IPF 規則將會被載入</para>
</sect2>
<sect2>
<title>IPF Rule Sets</title>
<title>IPF 規則</title>
<!-- XXX: looks incorrect (and duplicated 2 times in this chapter):
1. Packet can be processed two times depend of firewall
@ -1062,15 +991,15 @@ sh /etc/ipf.rules.script</programlisting>
</indexterm>
<para>IPF was originally written using a rules processing logic
of <quote>the last matching rule wins</quote> and used only
of 「the last matching rule wins」 and used only
stateless rules. Over time IPF has been enhanced to include a
<quote>quick</quote> option and a stateful <quote>keep
state</quote> option which drastically modernized the rule
「quick」 option and a stateful 「keep
state」 option which drastically modernized the rule
processing logic.</para>
<para>The instructions contained in this section are based on
using rules that contain the <quote>quick</quote> option and
the stateful <quote>keep state</quote> option. This is the
using rules that contain the 「quick」 option and
the stateful 「keep state」 option. This is the
basic framework for coding an inclusive firewall rule
set.</para>
@ -1108,8 +1037,8 @@ sh /etc/ipf.rules.script</programlisting>
</indexterm>
<para>The rule syntax presented here has been simplified to only
address the modern stateful rule context and <quote>first
matching rule wins</quote> logic. For the complete legacy rule
address the modern stateful rule context and 「first
matching rule wins」 logic. For the complete legacy rule
syntax description see the &man.ipf.8; manual page.</para>
<para>A <literal>#</literal> character is used to mark the start
@ -1209,7 +1138,7 @@ sh /etc/ipf.rules.script</programlisting>
<para><literal>quick</literal> indicates that if the selection
parameters match the packet, this rule will be the last rule
checked, allowing a <quote>short-circuit</quote> path to avoid processing
checked, allowing a 「short-circuit」 path to avoid processing
any following rules for this packet. This option is a
mandatory requirement for the modernized rules processing
logic.</para>
@ -1232,11 +1161,11 @@ sh /etc/ipf.rules.script</programlisting>
headers.</para>
<para><literal>first</literal> If the <literal>log</literal>
keyword is being used in conjunction with a <quote>keep
state</quote> option, it is recommended that this option is
keyword is being used in conjunction with a 「keep
state」 option, it is recommended that this option is
also applied so that only the triggering packet is logged and
not every packet which thereafter matches the <quote>keep
state</quote> information.</para>
not every packet which thereafter matches the 「keep
state」 information.</para>
</sect3>
<sect3>
@ -1273,17 +1202,17 @@ sh /etc/ipf.rules.script</programlisting>
<title>SRC_ADDR/DST_ADDR</title>
<para>The <literal>all</literal> keyword is essentially a
synonym for <quote>from any to any</quote> with no other
synonym for 「from any to any」 with no other
match parameters.</para>
<para><literal>from src to dst</literal>: the from and to
keywords are used to match against IP addresses. Rules must
specify BOTH source and destination parameters.
<literal>any</literal> is a special keyword that matches any
IP address. Examples of use: <quote>from any to any</quote>
or <quote>from 0.0.0.0/0 to any</quote> or <quote>from any to
0.0.0.0/0</quote> or <quote>from 0.0.0.0 to any</quote> or
<quote>from any to 0.0.0.0</quote>.</para>
IP address. Examples of use: 「from any to any」
or 「from 0.0.0.0/0 to any」 or <quote>from any to
0.0.0.0/0」 or 「from 0.0.0.0 to any</quote> or
「from any to 0.0.0.0」.</para>
<!-- XXX: Needs rewording -->
@ -1311,7 +1240,7 @@ sh /etc/ipf.rules.script</programlisting>
number. The use of the port option with the
<literal>to</literal> object is a mandatory requirement for
the modernized rules processing logic. Example of use:
<quote>from any to any port = 80</quote></para>
「from any to any port = 80」</para>
<!-- XXX: Needs rewriting -->
@ -2404,7 +2333,7 @@ options IPV6FIREWALL_DEFAULT_TO_ACCEPT</programlisting>
sequence order. When the packet matches a rule selection
parameters, the rules action field value is executed and the
search of the rule set terminates for that packet. This is
referred to as <quote>the first match wins</quote> search
referred to as 「the first match wins」 search
method. If the packet does not match any of the rules, it gets
caught by the mandatory ipfw default rule, number 65535 which
denies all packets and discards them without any reply back to
@ -3309,18 +3238,18 @@ pif="rl0" # public interface name of NIC
&dollar;cmd 307 deny all from 204.152.64.0/23 to any in via &dollar;pif #Sun cluster
&dollar;cmd 308 deny all from 224.0.0.0/3 to any in via &dollar;pif #Class D &amp; E multicast
# Deny ident
# 拒絕 ident
&dollar;cmd 315 deny tcp from any to any 113 in via &dollar;pif
# Deny all Netbios service. 137=name, 138=datagram, 139=session
# Netbios is MS/Windows sharing services.
# Block MS/Windows hosts2 name server requests 81
# 拒絕所有的 Netbios 服務. 137=name, 138=datagram, 139=session
# Netbios 是 MS/Windows 網路分享服務
# 阻擋所有的 MS/Windows 主機名稱伺服器hosts2 name server requests 81
&dollar;cmd 320 deny tcp from any to any 137 in via &dollar;pif
&dollar;cmd 321 deny tcp from any to any 138 in via &dollar;pif
&dollar;cmd 322 deny tcp from any to any 139 in via &dollar;pif
&dollar;cmd 323 deny tcp from any to any 81 in via &dollar;pif
# Deny any late arriving packets
# 拒絕任何的延遲到達之封包
&dollar;cmd 330 deny all from any to any frag in via &dollar;pif
# Deny ACK packets that did not match the dynamic rule table

121
zh_TW.Big5/books/handbook/install/chapter.sgml
View file

@ -603,7 +603,7 @@ We can take no responsibility for lost disk contents!</literallayout>
</step>
<step>
<para>用磁片安裝，請把在
<para>若要用磁片安裝，請把在
<xref linkend="install-floppies">一節中製作好的 <filename>kern.flp</filename> 那張安裝磁片放到第一台軟碟機中。</para>
<para>如果是從光碟安裝，那麼開機後請將 FreeBSD 光碟放入光碟機中。</para>
@ -672,7 +672,7 @@ Please insert MFS root floppy and press enter:</screen>
</step>
<step>
<para>不論從軟碟或光碟開機，您都會看到下面這段訊息：</para>
<para>無論從軟碟或光碟開機，您都會看到下面這段訊息：</para>
<screen>Hit [Enter] to boot immediately, or any other key for command prompt.
Booting [kernel] in 9 seconds... _</screen>
@ -690,54 +690,41 @@ Booting [kernel] in 9 seconds... _</screen>
<procedure>
<step>
<para>Start with your computer turned off.</para>
<para>在一開始，電腦電源開關是關閉的。</para>
</step>
<step>
<para>Turn on the computer and wait for a boot monitor
prompt.</para>
<para>打開電腦電源開關，然後等開機畫面出現。</para>
</step>
<step>
<para>If you needed to prepare boot floppies, as described in
<xref linkend="install-floppies"> then one of them will be the
first boot disc, probably the one containing
<filename>kern.flp</filename>. Put this disc in your floppy
drive and type the following command to boot the disk
(substituting the name of your floppy drive if
necessary):</para>
<para>若要用磁片安裝，請把在
<xref linkend="install-floppies">一節中製作好的 <filename>kern.flp</filename> 那張安裝磁片放到第一台軟碟機中。
然後，打下列指令來從磁片開機(請把下列軟碟機代號改為你電腦的軟碟機代號)：</para>
<screen>&gt;&gt;&gt;<userinput>BOOT DVA0 -FLAGS '' -FILE ''</userinput></screen>
<para>If you are booting from CDROM, insert the CDROM into
the drive and type the following command to start the
installation (substituting the name of the appropriate
CDROM drive if necessary):</para>
<para>若要用光碟安裝，請把做好的安裝片放入光碟機，然後打下列指令來從光碟開機(請把下列光碟機代號改為你電腦的光碟機代號)：</para>
<screen>&gt;&gt;&gt;<userinput>BOOT DKA0 -FLAGS '' -FILE ''</userinput></screen>
</step>
<step>
<para>FreeBSD will start to boot. If you are booting from a
floppy disc, at some point you will see the message:</para>
<para>接著 FreeBSD 開機片就會開始了。若是由軟碟開機的話，這時會看到以下訊息：</para>
<screen>Please insert MFS root floppy and press enter:</screen>
<para>Follow these instructions by removing the
<filename>kern.flp</filename> disc, insert the
<filename>mfsroot.flp</filename> disc, and press
<keycap>Enter</keycap>.</para>
<para>請照指示，拿走 <filename>kern.flp</filename> 片，改放
<filename>mfsroot.flp</filename> 片，然後按 <keycap>Enter</keycap>。</para>
</step>
<step>
<para>Whether you booted from floppy or CDROM, the
boot process will then get to this point:</para>
<para>無論從軟碟或光碟開機，您都會看到下面這段訊息：</para>
<screen>Hit [Enter] to boot immediately, or any other key for command prompt.
Booting [kernel] in 9 seconds... _</screen>
<para>Either wait ten seconds, or press <keycap>Enter</keycap>. This
will then launch the kernel configuration menu.</para>
<para>您可以等待 10 秒，或是按 <keycap>Enter</keycap> 鍵。接下來就會進入kernel configuration 選單。</para>
</step>
</procedure>
@ -751,26 +738,18 @@ Booting [kernel] in 9 seconds... _</screen>
<note><para>從 FreeBSD 5.0 版開始，改用新的 &man.device.hints.5; 方式，而淘汰舊的 userconfig 方式。
關於 &man.device.hints.5; 機制的細節介紹，請參閱 <xref linkend="device-hints">。</para></note>
<para>The <firstterm>kernel</firstterm> is the core of the operating
system. It is responsible for many things, including access to all
the devices you may have on your system, such as hard disks, network
cards, sound cards, and so on. Each piece of hardware supported by
the FreeBSD kernel has a driver associated with it. Each driver has a
two or three letter name, such as <devicename>sa</devicename> for the
SCSI sequential access driver, or <devicename>sio</devicename> for the
Serial I/O driver (which manages COM ports).</para>
<para><firstterm>kernel</firstterm> 乃是作業系統中的核心，負責許多事情，像是：控制系統上所有設備，比如硬碟、網路卡、音效卡等。
每項 FreeBSD 所支援的硬體都有相對應的驅動程式。
每個驅動程式名稱都有 2 到 3 個字母所組成，像是 <devicename>sa</devicename> 代表 SCSI 驅動程式，而
<devicename>sio</devicename> 代表 Serial I/O 驅動程式(管 COM ports 用的)。</para>
<para>When the kernel starts, each driver checks the system to see
whether or not the hardware it supports exists on your system. If it
does, then the driver configures the hardware and makes it available
to the rest of the kernel.</para>
<para>當 kernel 開始啟動時，每個驅動程式就會去檢查系統上是否有支援的硬體存在，
若有的話，驅動程式就會作相關硬體設定，以便讓 kernel 使用該硬體。</para>
<para>This checking is commonly referred to as <firstterm>device
probing</firstterm>. Unfortunately, it is not always possible to do
this in a safe way. Some hardware drivers do not co-exist well,
and probing for one piece of hardware can sometimes leave
another in an inconsistent state. This is a basic
limitation of the <acronym>PC</acronym> design.</para>
<para>上述的檢查動作，我們稱為 <firstterm>device probing(偵測硬體)</firstterm>。
但是，這樣子的方式並不是永遠都那麼順利。
有些硬體驅動程式無法同時共存，而有時候偵測某硬體時，又會造成另一硬體不穩出槌。
這問題，乃是由於 <acronym>PC</acronym> 本身設計上天生的限制所致。</para>
<para>Many older devices are called ISA devices&mdash;as opposed
to PCI devices. The ISA specification requires each device to have
@ -2162,17 +2141,13 @@ Mounting root from ufs:/dev/md0c
<sect1 id="install-media">
<title>選擇安裝來源</title>
<para>If Installing from a CDROM or DVD, use the arrow keys to highlight
<guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>. Ensure
that &gui.ok; is highlighted, then press
<keycap>Enter</keycap> to proceed with the installation.</para>
<para>若要從 CDROM 或 DVD 安裝，用方向鍵將游標移到 <guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>，並確定
選 &gui.ok; 後按下 <keycap>Enter</keycap> 就會開始裝了。</para>
<para>For other methods of installation, select the appropriate
option and follow the instructions.</para>
<para>若是要用其他的方式安裝的話，請選擇適當的安裝來源，然後遵照螢幕指示進行安裝即可。</para>
<para>Press <keycap>F1</keycap> to display the Online Help for
installation media. Press <keycap>Enter</keycap> to return
to the media selection menu.</para>
<para>按 <keycap>F1</keycap> 可以顯示針對此部分(安裝來源)的線上說明。按一下 <keycap>Enter</keycap>
就會回到『選擇安裝來源』的畫面了。</para>
<figure id="choose-media">
<title>選擇安裝來源</title>
@ -2193,8 +2168,7 @@ Mounting root from ufs:/dev/md0c
<tertiary>FTP</tertiary>
</indexterm>
<para>There are three FTP installation modes you can choose from:
active FTP, passive FTP, or via a HTTP proxy.</para>
<para>使用 FTP 安裝的話，有分三種模式︰主動式(active)FTP、被動式(passive)FTP 或是透過 HTTP proxy server。</para>
<variablelist>
<varlistentry>
@ -2314,13 +2288,11 @@ do so by typing: /stand/sysinstall .
[ Press enter to continue ]</screen>
<para>Press <keycap>Enter</keycap> to proceed with post-installation
configurations.</para>
<para>請按 <keycap>Enter</keycap> 鍵來進行相關的後續設定。</para>
<para>Selecting &gui.no; and pressing
<keycap>Enter</keycap> will abort
the installation so no changes will be made to your system. The
following message will appear:</para>
<para>如果剛選的是 &gui.no; 並按下
<keycap>Enter</keycap> 鍵，那麼會中斷安裝(就不會動到你的原有系統)。
接著，會出現以下訊息：</para>
<screen> Message
Installation complete with some errors. You may wish to scroll
@ -2330,9 +2302,7 @@ installation menus to retry whichever operations have failed.
[ OK ]</screen>
<para>This message is generated because nothing was installed.
Pressing <keycap>Enter</keycap> will return to the
Main Installation Menu to exit the installation.</para>
<para>這段訊息乃是因為都沒裝任何東西之故，請按 <keycap>Enter</keycap> 以跳回主畫面。</para>
</sect1>
<sect1 id="install-post">
@ -2344,28 +2314,24 @@ installation menus to retry whichever operations have failed.
<guimenuitem>Configure</guimenuitem> 選項以進行後續設定。</para>
<sect2 id="inst-network-dev">
<title>Network Device Configuration</title>
<title>設定網路</title>
<para>If you previously configured PPP for an FTP install, this screen
will not display and can be configured later as described
above.</para>
<para>如果您之前有設定用 PPP 連線透過 FTP 安裝，那麼這個畫面將不會出現；
正如上面剛所說的，您可以稍後再做更改。</para>
<para>For detailed information on Local Area Networks and
configuring FreeBSD as a gateway/router refer to the
<link linkend="advanced-networking">Advanced Networking</link>
chapter.</para>
<para>有關 LAN 或把 FreeBSD 設定為 gateway 或 router 請參閱使用手冊中有關
<link linkend="advanced-networking">網路進階運用</link> 的章節。</para>
<screen> User Confirmation Requested
Would you like to configure any Ethernet or SLIP/PPP network devices?
[ Yes ] No</screen>
<para>To configure a network device, select
&gui.yes; and press <keycap>Enter</keycap>.
Otherwise, select &gui.no; to continue.</para>
<para>如果要設定網路卡，請選擇 &gui.yes; 然後按 <keycap>Enter</keycap>。
否則請選 &gui.no; 以繼續。</para>
<figure id="ed-config1">
<title>Selecting an Ethernet Device</title>
<title>選擇網路卡</title>
<mediaobject>
<imageobject>
@ -2374,8 +2340,7 @@ installation menus to retry whichever operations have failed.
</mediaobject>
</figure>
<para>Select the interface to be configured with the arrow keys and press
<keycap>Enter</keycap>.</para>
<para>用方向鍵選擇您要設定的網路卡，然後按 <keycap>Enter</keycap>。</para>
<screen> User Confirmation Requested
Do you want to try IPv6 configuration of the interface?

19
zh_TW.Big5/books/handbook/introduction/chapter.sgml
View file

@ -32,7 +32,7 @@
<para>FreeBSD 與其他 OS 之間的關係；</para>
</listitem>
<listitem>
<para>FreeBSD 計劃的歷史淵源；</para>
<para>FreeBSD 計劃的歷史源流；</para>
</listitem>
<listitem>
<para>FreeBSD 計劃的目標；</para>
@ -54,7 +54,7 @@
<para>FreeBSD 是一個從 4.4BSD-Lite 衍生出而能在以 Intel (x86 and &itanium;),
AMD64, <trademark>Alpha</trademark>, Sun &ultrasparc;
為基礎的電腦上執行的作業系統。同時，移植到其他平台的工作也在進行中。
對於本計劃歷史的介紹，請看 <link linkend="history">FreeBSD 歷史淵源</link>，
對於本計劃歷史的介紹，請看 <link linkend="history">FreeBSD 歷史源流</link>，
對於 FreeBSD 的最新版本介紹，請看 <link linkend="relnotes">current release
</link>。若打算對於 FreeBSD 計劃有所貢獻的話(像是程式碼硬體設備，資金)，
請看 <ulink url="&url.articles.contributing;/index.html">如何對 FreeBSD
@ -177,8 +177,8 @@
<secondary>FORTRAN</secondary>
</indexterm>
<listitem>
<para>完全相容的 <emphasis>C</emphasis>、<emphasis>C++</emphasis>、
<emphasis>Fortran</emphasis> 和 <emphasis>Perl</emphasis> 開發工具及環境。
<para>完全相容的 <emphasis>C</emphasis>、<emphasis>C++</emphasis> 以及
<emphasis>Fortran</emphasis> 的環境和其他開發工具。
以及其他許多可供進階研發的程式語言也收集在 ports 和 packages。
</para>
</listitem>
@ -415,7 +415,7 @@
<sect1 id="history">
<title>關於 FreeBSD 計劃</title>
<para>接下來講的是 FreeBSD 計劃的背景，包含歷史淵源的簡介、計劃的目標，以及開發的模式。</para>
<para>接下來講的是 FreeBSD 計劃的背景，包含歷史源流的簡介、計劃的目標，以及開發的模式。</para>
<sect2 id="intro-history">
<sect2info role="firstperson">
@ -428,7 +428,7 @@
</authorgroup>
</sect2info>
<title>FreeBSD 歷史淵源的簡介</title>
<title>FreeBSD 歷史源流的簡介</title>
<indexterm><primary>386BSD Patchkit</primary></indexterm>
<indexterm><primary>Hubbard, Jordan</primary></indexterm>
@ -532,10 +532,11 @@
系列進入 -STABLE (RELENG_5分支)之後，-CURRENT 就轉移為 6.X 系列。</para>
<para>RELENG_5 分支於 2004 年 8 月正式開跑，之後是 5.3-RELEASE
，它是 5-STABLE 分支的第一個發行版本。5-STABLE 的最新發表是在 &rel2.current.date; 發行的 &rel2.current;-RELEASE，當然囉，RELENG_5 分支還將有後續的發行版。</para>
，它是 5-STABLE 分支的第一個發行版本。&rel2.current;-RELEASE 的最新發表是在 &rel2.current.date; 發行的 &rel2.current;-RELEASE，照往例 RELENG_5 分支還將有後續的發行版。</para>
<!-- chinsan: 6.X 的特色介紹部份等 Offical Handbook 出來新版再翻譯吧 XD -->
<para>RELENG_6 分支於 2005 年 11 月開跑，最新的 &rel.current;-RELEASE 是在 &rel.current.date; 發行。</para>
<para>RELENG_6 分支於 2005 年 7 月開跑，而 6.X 分支的第一個 release(6.0-RELEASE) 是在 2005 年 11 月出的。
最新的 &rel.current;-RELEASE 是在 &rel.current.date; 發行。當然囉，RELENG_6 分支還將有後續的發行版。</para>
<para>目前，長期的開發計畫繼續在 7.X-CURRENT (trunk) 分支中進行，而 7.X 的 CDROM
(當然，也可以用網路抓) snapshot 版本可以在 <ulink
@ -622,7 +623,7 @@
</indexterm>
<listitem>
<para>The central source tree for FreeBSD is maintained by
<ulink url="http://www.cvshome.org/">CVS</ulink>
<ulink url="http://ximbiot.com/cvs/wiki/">CVS</ulink>
(Concurrent Versions System), a freely available source code
control tool that comes bundled with FreeBSD. The primary
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVS

101
zh_TW.Big5/books/handbook/kernelconfig/chapter.sgml
View file

@ -2,7 +2,7 @@
The FreeBSD Documentation Project
$FreeBSD$
Original revision: 1.160
Original revision: 1.163
-->
<chapter id="kernelconfig">
@ -11,7 +11,7 @@
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Updated and restructured by </contrib>
<contrib>更新、重排：</contrib>
<!-- Mar 2000 -->
</author>
</authorgroup>
@ -19,122 +19,97 @@
<author>
<firstname>Jake</firstname>
<surname>Hamby</surname>
<contrib>Originally contributed by </contrib>
<contrib> 原作為：</contrib>
<!-- 6 Oct 1995 -->
</author>
</authorgroup>
</chapterinfo>
<title>Configuring the FreeBSD Kernel</title>
<title>設定 FreeBSD Kernel</title>
<sect1 id="kernelconfig-synopsis">
<title>Synopsis</title>
<title>概述</title>
<indexterm>
<primary>kernel</primary>
<secondary>building a custom kernel</secondary>
</indexterm>
<para>The kernel is the core of the &os; operating system. It is
responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While more and more of &os;
becomes dynamically configurable it is still occasionally necessary to
reconfigure and recompile your kernel.</para>
<para>kernel 是整個 &os; 作業系統的核心。
它控制了系統的整體運作，包含和記憶體管理、安全控管、網路、硬碟存取等等。
儘管目前 &os; 大多可以用動態 module 來載入、卸載所需功能，但有時候仍有必要學會重新調配 kernel。</para>
<para>After reading this chapter, you will know:</para>
<para>讀完這章，您將了解︰</para>
<itemizedlist>
<listitem>
<para>Why you might need to build a custom kernel.</para>
<para>為何需要重新調配、編譯 kernel？</para>
</listitem>
<listitem>
<para>How to write a kernel configuration file, or alter an existing
configuration file.</para>
<para>要怎麼修改 kernel 設定檔？</para>
</listitem>
<listitem>
<para>How to use the kernel configuration file to create and build a
new kernel.</para>
<para>如何以 kernel 設定檔來建立、編譯新的 kernel 呢？</para>
</listitem>
<listitem>
<para>How to install the new kernel.</para>
<para>如何安裝新的 kernel。</para>
</listitem>
<listitem>
<para>How to create any entries in <filename>/dev</filename> that may
be required.</para>
<para>如何在 <filename>/dev</filename> 下來安裝新的硬體。</para>
</listitem>
<listitem>
<para>How to troubleshoot if things go wrong.</para>
<para>如何處理 kernel 錯誤無法開機的情形。</para>
</listitem>
</itemizedlist>
<para>All of the commands listed within this chapter by way of example
should be executed as <username>root</username> in order to
succeed.</para>
<para>本章所舉例的相關指令都是以 <username>root</username> 權限來進行。</para>
</sect1>
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
<title>為何需要重新調配、編譯 kernel？</title>
<para>Traditionally, &os; has had what is called a
<quote>monolithic</quote> kernel. This means that the kernel was one
large program, supported a fixed list of devices, and if you wanted to
change the kernel's behavior then you had to compile a new kernel, and
then reboot your computer with the new kernel.</para>
<para>早期的 &os; 的 kernel 被戲稱為 <quote>monolithic</quote> kernel。
這意思是說當時的 kernel 是個大塊頭程式，且只支援固定的硬體而已。
如果您想改變 kernel 的設定，那麼必須編譯一個新的並重新開機，才能啟用。</para>
<para>Today, &os; is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be
dynamically loaded and unloaded from the kernel as necessary.
This allows the kernel to adapt to new hardware suddenly
becoming available (such as PCMCIA cards in a laptop), or for
new functionality to be brought into the kernel that was not
necessary when the kernel was originally compiled. This is
known as a modular kernel.</para>
<para>現在的 &os; 已快速成長到新型態的管理模式，其重要特色是：
kernel 功能可以隨時依據需求，而以動態載入或卸載相關的 kernel module。
這使得 kernel 能夠快速因應新的環境而作調整(有點像是：筆記型電腦上的 PCMCIA 卡一樣即插即用)
，或是增加其他原本的預設 kernel(<filename>GENERIC</filename>) 所沒有的功能。
這種模式，就叫做 modular kernel(核心模組)。</para>
<para>Despite this, it is still necessary to carry out some static kernel
configuration. In some cases this is because the functionality is so
tied to the kernel that it can not be made dynamically loadable. In
others it may simply be because no one has yet taken the time to write a
dynamic loadable kernel module for that functionality.</para>
<para>儘管如此，還是有一些功能仍須編譯在 kernel 內才行。因為有時候是因為這些功能與 kernel
結合的相當複雜緊密，而無法將它們弄成可動態載入的 module
；而有時候，則是因為沒有人有空來弄那些 kernel module 的實作。</para>
<para>Building a custom kernel is one of the most important rites of
passage nearly every BSD user must endure. This process, while
time consuming, will provide many benefits to your &os; system.
Unlike the <filename>GENERIC</filename> kernel, which must support a
wide range of hardware, a custom kernel only contains support for
<emphasis>your</emphasis> PC's hardware. This has a number of
benefits, such as:</para>
<para>重新調配、編譯 kernel 幾乎是每位 BSD 使用者所必須經歷的過程。
儘管這項工作可能比較耗時，但在 &os; 的使用上會有許多好處。
跟必須支援大多數各式硬體的 <filename>GENERIC</filename> kernel 相比的話，自行調配 kernel 不同處在於：可以更『體貼』，只支援『自己硬體』的部分就好。
好處在於，譬如︰</para>
<itemizedlist>
<listitem>
<para>Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot can decrease dramatically.</para>
<para>開機速度更快：因為自行調配的 kernel 只需要偵測您系統上的硬體，所以讓啟動所花的過程更流暢快速。</para>
</listitem>
<listitem>
<para>Lower memory usage. A custom kernel often uses less memory
than the <filename>GENERIC</filename> kernel, which is important
because the kernel must always be present in real
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.</para>
<para>佔用的記憶體更少：自行調配的 kernel 通常會比 <filename>GENERIC</filename> 核心使用更少的記憶體，
由於 kernel 必須一直存放在記憶體內，因此這就顯得更加重要。因此，對於記憶體較小的系統來說，自行調配的 kernel 就可發揮更多的作用、揮灑空間。</para>
</listitem>
<listitem>
<para>Additional hardware support. A custom kernel allows you to
add in support for devices which are not
present in the <filename>GENERIC</filename> kernel, such as
sound cards.</para>
<para>可支援更多硬體：您可在自行調配的 kernel 增加一些原本 <filename>GENERIC</filename> 核心沒有提供的硬體支援，像是音效卡之類的。</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="kernelconfig-building">
<title>Building and Installing a Custom Kernel</title>
<title>重新調配、編譯 kernel</title>
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
@ -377,7 +352,7 @@
<tip>
<para>By default, when you build a custom kernel,
<emphasis>all</emphasis> kernel modules also will be rebuilded.
<emphasis>all</emphasis> kernel modules will be rebuilt as well.
If you want to update a kernel faster or to build only custom
modules, you should edit <filename>/etc/make.conf</filename>
before starting to build the kernel:</para>

6
zh_TW.Big5/books/handbook/l10n/chapter.sgml
View file

@ -24,10 +24,10 @@
</authorgroup>
</chapterinfo>
<title>Localization - I18N/L10N Usage and Setup</title>
<title>地區、語系 - I18N/L10N 用法與設定</title>
<sect1 id="l10n-synopsis">
<title>Synopsis</title>
<title>概述</title>
<para>FreeBSD is a very distributed project with users and
contributors located all over the world. This chapter discusses
@ -63,7 +63,7 @@
<title>The Basics</title>
<sect2>
<title>What Is I18N/L10N?</title>
<title>啥是 I18N/L10N？</title>
<indexterm>
<primary>internationalization</primary>
<see>localization</see>

32
zh_TW.Big5/books/handbook/mirrors/chapter.sgml
View file

@ -2,7 +2,7 @@
The FreeBSD Documentation Project
$FreeBSD$
Original revision: 1.406
Original revision: 1.407
-->
<appendix id="mirrors">
@ -388,7 +388,6 @@
(Use <command>cvs login</command> and enter the password
<quote>anoncvs</quote> when prompted.)</para>
</listitem>
<!-- anoncvs.FreeBSD.org is sufferring hardware troubles at the moment ...
<listitem>
<para><emphasis>USA</emphasis>:
freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs
@ -398,14 +397,13 @@
SSH2 HostKey: 1024 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65 ssh_host_dsa_key.pub</programlisting>
</listitem>
-->
<listitem>
<para><emphasis>USA</emphasis>:
anoncvs@anoncvs1.FreeBSD.org:/home/ncvs (ssh only - no
password)</para>
<programlisting>SSH HostKey: 1024 4b:83:b6:c5:70:75:6c:5b:18:8e:3a:7a:88:a0:43:bb root@ender.liquidneon.com
SSH2 HostKey: 1024 80:a7:87:fa:61:d9:25:5c:33:d5:48:51:aa:8f:b6:12 ssh_host_dsa_key.pub</programlisting>
<programlisting>SSH HostKey: 1024 8b:c4:6f:9a:7e:65:8a:eb:50:50:29:7c:a1:47:03:bc root@ender.liquidneon.com
SSH2 HostKey: 2048 4d:59:19:7b:ea:9b:76:0b:ca:ee:da:26:e2:3a:83:b8 ssh_host_dsa_key.pub</programlisting>
</listitem>
</itemizedlist>
@ -512,7 +510,7 @@ Warning: Permanently added 'anoncvs.freebsd.org' (DSA) to the list of known host
</listitem>
<listitem>
<para><ulink url="http://www.cvshome.org/">CVS Home</ulink>,
<para><ulink url="http://ximbiot.com/cvs/wiki/">CVS Home</ulink>,
the CVS development and support community.</para>
</listitem>
@ -2414,7 +2412,7 @@ doc/zh_*</screen>
ports tree into <filename>/var/db/portsnap/</filename> (or
<filename>/usr/local/portsnap/</filename> if
<application>Portsnap</application> was installed from the
Ports Collection). This is approximately a 38&nbsp;MB
Ports Collection). For the beginning of 2006 this is approximately a 41&nbsp;MB
download.</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
@ -2433,8 +2431,11 @@ doc/zh_*</screen>
<note>
<para>In the default installation
<filename role="directory">/usr/ports</filename> is not
created. It should be created before
<command>portsnap</command> is used.</para>
created. If you run &os;&nbsp;6.0-RELEASE, it should be created before
<command>portsnap</command> is used. On more recent
versions of &os; or <application>Portsnap</application>,
this operation will be done automatically at first use
of the <command>portsnap</command> command.<para>
</note>
</sect2>
@ -2477,7 +2478,7 @@ doc/zh_*</screen>
<command>cron</command> job, since it is liable to cause
major problems if it happens to run at the same time as a port
is being built or installed. However, it is safe to update
the ports INDEX files, and this can be done by passing the
the ports' <filename>INDEX</filename> files, and this can be done by passing the
<option>-I</option> flag to
<command>portsnap</command>. (Obviously, if
<command>portsnap -I update</command> is run from
@ -2487,7 +2488,7 @@ doc/zh_*</screen>
<para>Adding the following line to <filename>/etc/crontab</filename>
will cause <command>portsnap</command> to update its
compressed snapshot and the INDEX files in
compressed snapshot and the <filename>INDEX</filename> files in
<filename>/usr/ports/</filename>, and will send an email if any
installed ports are out of date:</para>
@ -2556,6 +2557,15 @@ doc/zh_*</screen>
<listitem>
<para>The line of development for FreeBSD-6.X, also known
as FreeBSD 6-STABLE</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RELENG_6_1</term>
<listitem>
<para>The release branch for FreeBSD-6.1, used only for
security advisories and other critical fixes.</para>
</listitem>
</varlistentry>

39
zh_TW.Big5/books/handbook/multimedia/chapter.sgml
View file

@ -1526,35 +1526,26 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
<sect2>
<title>¤¶²Ð</title>
<para>&os;, like any modern operating system, allows the use of
image scanners. Standardized access to scanners is provided
by the <application>SANE</application> (Scanner Access Now
Easy) <acronym role="Application Programming
Interface">API</acronym> available through the &os; Ports
Collection. <application>SANE</application> will also use
some &os; devices drivers to access to the scanner
hardware.</para>
<para>&os; 就像任何現代作業系統一樣，都可以使用掃描器。
在 &os; 是透過 Ports Collection 內的 <application>SANE</application>(Scanner Access Now Easy)
所提供的 <acronym role="Application Programming Interface">API</acronym> 來操作掃描器。
<application>SANE</application> 也會使用一些 &os; 的驅動程式來控制掃描器硬體。</para>
<para>&os; supports both SCSI and USB scanners. Be sure your
scanner is supported by <application>SANE</application> prior
to performing any configuration.
<application>SANE</application> has a <ulink
url="http://sane-project.org/sane-supported-devices.html">supported
devices</ulink> list that can provide you with information
about the support for a scanner and its status. The
&man.uscanner.4; manual page also provides a list of supported
USB scanners.</para>
<para>&os; 同時支援 SCSI 和 USB 兩種介面的掃描器。在做任何設定之前，請確保
<application>SANE</application> 有支援您的掃描器。
<application>SANE</application> 有張 <ulink
url="http://sane-project.org/sane-supported-devices.html">支援硬體</ulink>
的清單，這裡有介紹掃描器的支援情況和狀態訊息。
在 &man.uscanner.4; 內也有提供一份 USB 掃描器的支援列表。</para>
</sect2>
<sect2>
<title>Kernel Configuration</title>
<title>Kernel 的設定</title>
<para>As mentioned above both SCSI and USB interfaces are
supported. According to your scanner interface, different
device drivers are required.</para>
<para>如同上述所提的 SCSI 和 USB 界面都有支援。這要取決於您的掃描器界面，而需要不同的設備驅動程式。</para>
<sect3 id="scanners-kernel-usb">
<title>USB Interface</title>
<title>USB 介面</title>
<para>The <filename>GENERIC</filename> kernel by default
includes the device drivers needed to support USB scanners.
@ -1605,7 +1596,7 @@ device uscanner</programlisting>
</sect3>
<sect3>
<title>SCSI Interface</title>
<title>SCSI 介面</title>
<para>If your scanner comes with a SCSI interface, it is
important to know which SCSI controller board you will use.
@ -1655,7 +1646,7 @@ Re-scan of bus 3 was successful</screen>
</sect2>
<sect2>
<title>SANE Configuration</title>
<title>設定 SANE</title>
<para>The <application>SANE</application> system has been
splitted in two parts: the backends (<filename

70
zh_TW.Big5/books/handbook/ports/chapter.sgml
View file

@ -79,19 +79,13 @@
FreeBSD 提供了兩種省事的軟體管理機制： packages 和 ports。就在寫這篇文章的時候，
已經有超過 &os.numports; 個 port 軟體可以使用。</para>
<para>For any given application, the FreeBSD package for that
application is a single file which you must download. The
package contains pre-compiled copies of all the commands for the
application, as well as any configuration files or
documentation. A downloaded package file can be manipulated
with FreeBSD package management commands, such as
&man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so
on. Installing a new application can be carried out with a
single command.</para>
<para>所謂的 FreeBSD package 就是別人把該應用程式編譯、打包完畢。
該 package 會包括該應用程式的所有執行檔、設定檔、文件等。
而下載到硬碟上的 package 都可透過 FreeBSD 套件管理指令來進行管理，比如：
&man.pkg.add.1;、&man.pkg.delete.1;、&man.pkg.info.1;等指令。
所以，只需簡單打個指令就可輕鬆安裝新的應用程式了。</para>
<para>A FreeBSD port for an application is a collection of files
designed to automate the process of compiling an application
from source code.</para>
<para>而 FreeBSD port 則是用一些檔案，來自動處理應用程式的安裝流程。</para>
<para>Remember that there are a number of steps you would normally
carry out if you compiled a program yourself (downloading,
@ -102,10 +96,8 @@
automatically downloaded, extracted, patched, compiled, and
installed for you.</para>
<para>In fact, the ports system can also be used to generate packages
which can later be manipulated with <command>pkg_add</command>
and the other package management commands that will be introduced
shortly.</para>
<para>事實上，ports 機制還可以用來產生 packages，以便他人可以用
<command>pkg_add</command> 來安裝，或是稍後會介紹到的其他套件管理指令。</para>
<para>Both packages and ports understand
<emphasis>dependencies</emphasis>. Suppose you want to install
@ -203,17 +195,15 @@
&a.ports; and the &a.ports-bugs;.</para>
<warning>
<para>Before installing any application, you should check <ulink
url="http://vuxml.freebsd.org/"></ulink> for security issues
related to your application.</para>
<para>在安裝軟體前，最好先看 <ulink
url="http://vuxml.freebsd.org/"></ulink> 內是否有該軟體的安全漏洞通報。
</para>
<para>You can also install <filename
role="package">security/portaudit</filename> which will
automatically check all installed applications for known
vulnerabilities; a check will be also performed before any port
build. Meanwhile, you can use the command <command>portaudit
-F -a</command> after you have installed some
packages.</para>
<para>此外，也可以裝 <filename
role="package">security/portaudit</filename>，它會自動檢查所有已裝的
的軟體是否有已知的安全漏洞，另外，它還會在裝軟體的編譯過程前先行檢查。
也可以在裝了某些軟體之後，用 <command>portaudit -F -a</command>
來作全面強制安檢。</para>
</warning>
<para>The remainder of this chapter will explain how to use
@ -224,19 +214,17 @@
<sect1 id="ports-finding-applications">
<title>尋找想裝的軟體</title>
<para>Before you can install any applications you need to know what you
want, and what the application is called.</para>
<para>在安裝任何軟體之前，你必須先了解你想要什麼的軟體，以及該軟體叫做什麼名稱。</para>
<para>FreeBSD's list of available applications is growing all the
time. Fortunately, there are a number of ways to find what you
want:</para>
<para>FreeBSD 上可裝的軟體清單不斷在增加中，
不過，我們很慶幸有幾種方式可以來找你想裝的軟體：</para>
<itemizedlist>
<listitem>
<para>The FreeBSD web site maintains an up-to-date searchable
list of all the available applications, at <ulink
url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
The ports are divided into categories, and you may either
<para>FreeBSD 網站上有更新頻繁的軟體清單，在
<ulink
url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>。
各 ports 皆依其性質而分門別類，and you may either
search for an application by name (if you know it), or see
all the applications available in a category.</para>
</listitem>
@ -244,8 +232,8 @@
<indexterm><primary>FreshPorts</primary></indexterm>
<listitem>
<para>Dan Langille maintains FreshPorts, at <ulink
url="http://www.FreshPorts.org/"></ulink>. FreshPorts
<para>Dan Langille 維護 FreshPorts 網站，網址在 <ulink
url="http://www.FreshPorts.org/"></ulink>。 FreshPorts
tracks changes to the applications in the ports tree as they
happen, allows you to <quote>watch</quote> one or more
ports, and can send you email when they are updated.</para>
@ -1313,12 +1301,10 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
email address。記得寄信給 maintainer 時，要附註該 port 的名稱、版本(或是把 <filename>Makefile</filename> 內的 <literal>&dollar;FreeBSD:</literal> 那一整行附上) 以及相關錯誤訊息。</para>
<note>
<para>Some ports are not maintained by an individual but
instead by a <ulink
<para>有些 port 不是由專門的單一 maintainer 負責，而是透過 <ulink
url="&url.articles.mailing-list-faq;/article.html">mailing
list</ulink>. Many, but not all, of these addresses look like
<email role="nolink">freebsd-listname@FreeBSD.org</email>. Please
take this into account when phrasing your questions.</para>
list</ulink> 的專題討論。許多(但非全部)的聯絡 email 格式通常是
<email role="nolink">freebsd-list名稱@FreeBSD.org</email>。發問時，請記得把『freebsd-list名稱』改為相關討論的 mailing list 名稱。</para>
<para>尤其當 port 的 maintainer 欄位是
<email role="nolink">freebsd-ports@FreeBSD.org</email>

284
zh_TW.Big5/books/porters-handbook/book.sgml
View file

@ -66,18 +66,14 @@
此外，若有其他特定 port 的問題，也可以到 &a.ports; 來獲得答案。</para>
<note>
<para>Only a fraction of the variables
(<makevar><replaceable>VAR</replaceable></makevar>) that can be
overridden are mentioned in this document. Most (if not all)
are documented at the start of <filename>/usr/ports/Mk/bsd.port.mk</filename>;
the others probably ought to be.
Note that this file uses a non-standard tab setting:
<application>Emacs</application> and
<application>Vim</application> should recognize the setting on
loading the file. Both &man.vi.1; and
&man.ex.1; can be set to use the correct value by
typing <command>:set tabstop=4</command> once the file has been
loaded.</para>
<para>本文內所提及的環境變數(<makevar><replaceable>VAR</replaceable></makevar>)部份，
只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在
<filename>/usr/ports/Mk/bsd.port.mk</filename> 內，其他的也是差不多。
請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 space：
<application>Emacs</application> 與
<application>Vim</application> 應該都會在載入該檔時順便讀取相關設定值。
&man.vi.1; 及
&man.ex.1; 這兩個程式也都可以打 <command>:set tabstop=4</command> 以修改設定值。</para>
</note>
</chapter>
@ -193,14 +189,12 @@ lib/X11/oneko/mouse.xpm
linkend="plist-autoplist">自動產生 packing list</link> 會比較省時省力唷。</para>
</note>
<para>只有在一 種情況下可以省略不用生 <filename>pkg-plist</filename> 檔。 If the port installs just a handful
of files, and perhaps directories, the files and directories may
be listed in the variables <makevar>PLIST_FILES</makevar> and
<makevar>PLIST_DIRS</makevar>, respectively, within the port's
<filename>Makefile</filename>. For instance, we could get along
without <filename>pkg-plist</filename> in the above
<filename>oneko</filename> port by adding the
following lines to the <filename>Makefile</filename>:</para>
<para>只有在一種情況下可以省略不用生 <filename>pkg-plist</filename> 檔：
若安裝的 port 相當單純，只有裝一些檔案，以及都在同一目錄下的話，
那麼可以在 <filename>Makefile</filename> 內改用 <makevar>PLIST_FILES</makevar> 及
<makevar>PLIST_DIRS</makevar> 來取代。
比如，可以在上述的 <filename>oneko</filename> port 內不必附上
<filename>pkg-plist</filename> ，而只需在 <filename>Makefile</filename> 內加入下列幾行：</para>
<programlisting>PLIST_FILES= bin/oneko \
lib/X11/app-defaults/Oneko \
@ -209,21 +203,16 @@ lib/X11/oneko/mouse.xpm
lib/X11/oneko/mouse.xpm
PLIST_DIRS= lib/X11/oneko</programlisting>
<para>Of course, <makevar>PLIST_DIRS</makevar> should be left
unset if a port installs no directories of its own.</para>
<para>當然，若該 port 並無安裝自屬的目錄的話，就不必設 <makevar>PLIST_DIRS</makevar> 囉。</para>
<para>The price for this way of listing port's files and
directories is that you cannot use command sequences
described in &man.pkg.create.1;. Therefore, it is suitable
only for simple ports and makes them even simpler. At the
same time, it has the advantage of reducing the number of files
in the ports collection. Please consider using this technique
before you resort to <filename>pkg-plist</filename>.</para>
<para>然而，使用 <makevar>PLIST_FILES</makevar> 、<makevar>PLIST_DIRS</makevar> 是必須付出代價：
不能使用 &man.pkg.create.1; 內所說的 command sequences。
因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。
此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。
所以，在考慮是否一定要用 <filename>pkg-plist</filename> 之前，可以先斟酌這個替代方案看看。</para>
<para>Later we will see how <filename>pkg-plist</filename>
and <makevar>PLIST_FILES</makevar> can be used to fulfil
<link linkend="plist">more sophisticated
tasks</link>.</para>
<para>後面會介紹到如何運用 <filename>pkg-plist</filename>、<makevar>PLIST_FILES</makevar>
這些技巧以因應 <link linkend="plist">更複雜的狀況</link>。</para>
</sect2>
</sect1>
@ -231,48 +220,40 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<title>產生 checksum 用途的 distinfo 檔</title>
<para>只要打『<command>make makesum</command>』就好了，接下來就會自動產生相對應的
<filename>distinfo</filename> 檔哩。</para>
<filename>distinfo</filename> 檔了唷。</para>
<para>If a file fetched has its checksum changed regularly and you are
certain the source is trusted (i.e. it comes from manufacturer CDs
or documentation generated daily), you should specify these files in
the <makevar>IGNOREFILES</makevar> variable.
Then the checksum is not calculated for that file when you run
<command>make makesum</command>, but set to
<literal>IGNORE</literal>.</para>
<para>若抓下來的檔案，它的 checksum 會經常變更，而你也很確信所抓的來源是正確無誤的話，
(比如：來源是光碟或是每天自動產生的文件)，那麼可以設定那些檔案為 <makevar>IGNOREFILES</makevar> 。
如此一來，在打 <command>make makesum</command> 的時候就不會計算那些檔案的 checksum，而自動改為
<literal>IGNORE</literal> 囉。</para>
</sect1>
<sect1 id="porting-testing">
<title>檢驗 port 是否完整、可行</title>
<para>You should make sure that the port rules do exactly what you
want them to do, including packaging up the port. These are the
important points you need to verify.</para>
<para>接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port 為 package。
以下有幾個需要確認的重要地方：</para>
<itemizedlist>
<listitem>
<para><filename>pkg-plist</filename> does not contain anything not
installed by your port</para>
<para>若該 port 沒裝的東西，不要列在 <filename>pkg-plist</filename> 內。</para>
</listitem>
<listitem>
<para><filename>pkg-plist</filename> contains everything that is
installed by your port</para>
<para>若該 port 有裝的東西，請務必列在 <filename>pkg-plist</filename> 內。</para>
</listitem>
<listitem>
<para>Your port can be installed multiple times using the
<maketarget>reinstall</maketarget> target</para>
<para>該 port 可以用 <command>reinstall</command> 來重新安裝。</para>
</listitem>
<listitem>
<para>Your port <link linkend="plist-cleaning">cleans up</link>
after itself upon deinstall</para>
<para>該 port 在移除之後，確定都可 <link linkend="plist-cleaning">cleans up</link>。</para>
</listitem>
</itemizedlist>
<procedure>
<title>建議採行的測試順序：</title>
<title>建議的測試步驟順序：</title>
<step>
<para><command>make install</command></para>
@ -304,23 +285,19 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
</step>
</procedure>
<para>Make sure that there are not any warnings issued in any of the
<maketarget>package</maketarget> and
<maketarget>deinstall</maketarget> stages. After step 3, check to
see if all the new directories are correctly deleted. Also, try
using the software after step 4, to ensure that it works correctly
when installed from a package.</para>
<para>確認在 <maketarget>package</maketarget> 和 <maketarget>deinstall</maketarget>
這兩個階段都沒有任何錯誤訊息出現。
完成第三步驟之後，檢查一下是否所裝的檔案、目錄都有移除完畢。此外，第四步驟完成後，也檢查一下以 package
裝的該軟體，是否都能正常運作。</para>
</sect1>
<sect1 id="porting-portlint">
<title>以 <command>portlint</command> 來作檢驗</title>
<para>請用 <command>portlint</command> 來檢查該 port 是否有遵循上述規則。 The <filename role="package">
devel/portlint</filename> program is part of the ports collection.
In particular, you may want to check if the
<link linkend="porting-samplem">Makefile</link> is in the right
shape and the <link linkend="porting-pkgname">package</link> is named
appropriately.</para>
<para>請用 <command>portlint</command> 來檢查該 port 是否有遵循上述遊戲規則。 說到這 <filename role="package">
devel/portlint</filename> 它是 ports collection 的其中一個套件。
它主要可以用來檢驗 <link linkend="porting-samplem">Makefile</link> 內容是否正確以及
<link linkend="porting-pkgname">package</link> 是否有正確命名。</para>
</sect1>
<sect1 id="porting-submitting">
@ -334,38 +311,34 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<filename>pkgname.tgz</filename> 的 package 可以砍掉。接著，只要用 <command>shar `find
port_dir`</command> 來產生 shar 格式，並配合 &man.send-pr.1; 程式以提交出去。
(&man.send-pr.1; 的部分可以參閱 <ulink url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">
錯誤報告和意見發表</ulink>) 記得在填寫 PR 時『分類(Category)』選
<literal>ports</literal> 還有『種類(Class)』填 <literal>change-request</literal>
錯誤報告和意見發表</ulink>) </para>
<para>記得在填寫 PR 時『分類(Category)』選 <literal>ports</literal>，還有『種類(Class)』填 <literal>change-request</literal>
(千萬別傻傻地把該 PR 的『Confidential(機密)』設為 yes！)，此外在『描述(<quote>Description</quote>)』
那邊寫上該程式的簡潔說明，而 shar 檔則附在『修正(<quote>Fix</quote>)』欄位內。</para>
<note>
<para>You can make our work a lot easier, if you use a good
description in the synopsis of the problem report.
We prefer something like
<para>若 Synopsis 欄清楚描述該 PR 重點的話，那麼會讓整個流程更為順暢。
new ports 的話，我們習慣用：
<quote>New port: &lt;category&gt;/&lt;portname&gt;
&lt;short description of the port&gt;</quote> for new ports and
&lt;該 port 的簡介&gt;</quote> ，而更新 port 的話，則是
<quote>Update port: &lt;category&gt;/&lt;portname&gt;
&lt;short description of the update&gt;</quote> for port updates.
If you stick to this scheme, the chance that someone will take a
look at your PR soon is much better.</para>
&lt;本次 update 的簡介&gt;</quote>。
若你也採用這樣的格式的話，那麼會被受理的機會就會越高囉。</para>
</note>
<para>One more time, <emphasis>do not include the original source
distfile, the <filename>work</filename> directory, or the package
you built with <command>make package</command></emphasis>.</para>
<para>再次強調一點：<emphasis>不必附上原始 source 的 distfile，也就是 <filename>work</filename> 目錄。
同時，也不必附上 <command>make package</command> 時產生的 package。</emphasis>.</para>
<para>After you have submitted your port, please be patient.
Sometimes it can take a few months before a port is included
in FreeBSD, although it might only take a few days. You can
view the list of <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports
waiting to be committed to FreeBSD</ulink>.</para>
<para>送出 port 之後，請耐心等候佳音。有時候可能需要等個幾天或幾個月時間，才會在 FreeBSD ports tree 上正式出現。
此外，隨時可以查閱 <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">
等待 committed to FreeBSD 的 port</ulink> 列表。</para>
<para>Once we have looked at your port, we will get back to you if necessary, and put
it in the tree. Your name will also appear in the list of
<ulink url="&url.articles.contributors;/contrib-additional.html">Additional FreeBSD Contributors</ulink>
and other files. Isn't that great?!? <!-- smiley
<para>一旦我們開始處理你送來的 port 之後，如果有一些意見需要溝通的話，那麼會先 feedback 給你，
之後確定都沒問題，就會放到 port tree 內囉！
你的大名會被記在 <ulink url="&url.articles.contributors;/contrib-additional.html">Additional FreeBSD Contributors</ulink>
列表上，以及其他檔案。聽起來，挺不賴的不是嗎！？ <!-- smiley
-->:-)</para>
</sect1>
</chapter>
@ -373,16 +346,14 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<chapter id="slow">
<title>Slow Porting</title>
<para>Ok...事實上並不太可能這麼簡單，port方面可能需要作些修改才能正常使用。
<para>Ok...事實上並不太可能這麼簡單，port 方面可能需要作些修改才能正常使用。
因此，本節將一步一步來介紹如何修改上一章的樣本以正常使用。</para>
<sect1 id="slow-work">
<title>How things work</title>
<para>First, this is the sequence of events which occurs when the user
first types <command>make</command> in your port's directory.
You may find that having <filename>bsd.port.mk</filename> in another
window while you read this really helps to understand it.</para>
<para>首先，先介紹一下在你所作的 port 目錄內打 <command>make</command> 時，所會作哪些事情的順序吧。
你可以另開一窗來看 <filename>bsd.port.mk</filename> 內容，以便瞭解我們下面在講什麼。</para>
<para>但別太擔心是否完全看懂
<filename>bsd.port.mk</filename> 在做啥，很多人都還沒完全看完...
@ -391,102 +362,78 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
<procedure>
<step>
<para>The <maketarget>fetch</maketarget> target is run. The
<maketarget>fetch</maketarget> target is responsible for making
sure that the tarball exists locally in
<makevar>DISTDIR</makevar>. If <maketarget>fetch</maketarget>
cannot find the required files in <makevar>DISTDIR</makevar> it
will look up the URL <makevar>MASTER_SITES</makevar>, which is
set in the Makefile, as well as our main FTP site at <ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/"></ulink>,
where we put sanctioned distfiles as backup. It will then
attempt to fetch the named distribution file with
<makevar>FETCH</makevar>, assuming that the requesting site has
direct access to the Internet. If that succeeds, it will save
the file in <makevar>DISTDIR</makevar> for future use and
proceed.</para>
<para>首先，進行 <maketarget>fetch</maketarget> 階段。
<maketarget>fetch</maketarget> 是確認 tarball 檔有沒有已在
<makevar>DISTDIR</makevar> 內了？若 <maketarget>fetch</maketarget>
在 <makevar>DISTDIR</makevar> 找不到的話，它會搜尋 Makefile 內的 <makevar>MASTER_SITES</makevar> URL
，或者是主 FTP 站專門放備份 distfiles 的目錄 <ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/"></ulink>。
假設都找不到的話，但是網路有接上 Internet 的話，它會試著用 <makevar>FETCH</makevar> 來抓所指定的檔案。
抓到之後，它會把檔案存到 <makevar>DISTDIR</makevar> 以便開始使用或日後運用。</para>
</step>
<step>
<para>The <maketarget>extract</maketarget> target is run. It
looks for your port's distribution file (typically a gzip'd
tarball) in <makevar>DISTDIR</makevar> and unpacks it into a
temporary subdirectory specified by <makevar>WRKDIR</makevar>
(defaults to <filename>work</filename>).</para>
<para>其次，進行 <maketarget>extract</maketarget> 階段，它會從 <makevar>DISTDIR</makevar> 內找出該 port
所需的檔案(通常是 gzip 格式的 tarball)，然後解壓縮到 <makevar>WRKDIR</makevar> 所設定的臨時目錄名稱
(預設是 <filename>work</filename> 目錄)內。</para>
</step>
<step>
<para>The <maketarget>patch</maketarget> target is run. First,
any patches defined in <makevar>PATCHFILES</makevar> are
applied. Second, if any patch files named
<filename>patch-<replaceable>*</replaceable></filename> are found in
<makevar>PATCHDIR</makevar> (defaults to the
<filename>files</filename> subdirectory), they are applied at
this time in alphabetical order.</para>
<para>之後，進行 <maketarget>patch</maketarget> 階段，一開始會先套用 <makevar>PATCHFILES</makevar>
指定的任何 patch 檔。
接著，是 <makevar>PATCHDIR</makevar>(預設是 <filename>files</filename> 子目錄) 內的檔名為
<filename>patch-<replaceable>*</replaceable></filename> 之類的檔案，會以字母順序而逐一套用 patch。</para>
</step>
<step>
<para>The <maketarget>configure</maketarget> target is run. This
can do any one of many different things.</para>
<para>接著是 <maketarget>configure</maketarget> 階段，可以照 port 的類型來作各種不同設定以調整，比如：</para>
<orderedlist>
<listitem>
<para>If it exists, <filename>scripts/configure</filename> is
run.</para>
<para>若有放 <filename>scripts/configure</filename> 的話，那麼就會跑裡面的設定。</para>
</listitem>
<listitem>
<para>If <makevar>HAS_CONFIGURE</makevar> or
<makevar>GNU_CONFIGURE</makevar> is set,
<filename><makevar>WRKSRC</makevar>/configure</filename> is
run.</para>
<para>若有設 <makevar>HAS_CONFIGURE</makevar> 或是
<makevar>GNU_CONFIGURE</makevar> 的話，那麼就會跑
<filename><makevar>WRKSRC</makevar>/configure</filename></para>
</listitem>
<listitem>
<para>If <makevar>USE_IMAKE</makevar> is set,
<makevar>XMKMF</makevar> (default: <command>xmkmf
-a</command>) is run.</para>
<para>若有設 <makevar>USE_IMAKE</makevar> 的話，那麼就會跑
<makevar>XMKMF</makevar> (預設是 <command>xmkmf
-a</command>) 。</para>
</listitem>
</orderedlist>
</step>
<step>
<para>The <maketarget>build</maketarget> target is run. This is
responsible for descending into the port's private working
directory (<makevar>WRKSRC</makevar>) and building it. If
<makevar>USE_GMAKE</makevar> is set, GNU <command>make</command>
will be used, otherwise the system <command>make</command> will
be used.</para>
<para>最後是 <maketarget>build</maketarget> 階段，它會在該
port 的 working directory(由 <makevar>WRKSRC</makevar> 所設定) 內開始編譯。
若有設 <makevar>USE_GMAKE</makevar> 的話，那麼就會改用 GNU <command>make</command>
來編譯，否則就用系統本身的 <command>make</command> 來編譯。</para>
</step>
</procedure>
<para>The above are the default actions. In addition, you can define
targets
<maketarget>pre-<replaceable>something</replaceable></maketarget> or
<maketarget>post-<replaceable>something</replaceable></maketarget>,
or put scripts with those names, in the <filename>scripts</filename>
subdirectory, and they will be run before or after the default
actions are done.</para>
<para>上面講的都是打 <command>make</command> 時的預設階段。
此外，還可以設定各階段之前、之後要作的事情：透過定義
<maketarget>pre-<replaceable>something</replaceable></maketarget> 或
<maketarget>post-<replaceable>something</replaceable></maketarget>，
或者把這些檔名的 script 丟到 <filename>scripts</filename> 子目錄去，
這樣子它們就會在各預設階段的之前、之後進行囉。</para>
<para>For example, if you have a <maketarget>post-extract</maketarget>
target defined in your <filename>Makefile</filename>, and a file
<filename>pre-build</filename> in the <filename>scripts</filename>
subdirectory, the <maketarget>post-extract</maketarget> target will
be called after the regular extraction actions, and the
<filename>pre-build</filename> script will be executed before the
default build rules are done. It is recommended that you use
<filename>Makefile</filename> targets if the actions are simple
enough, because it will be easier for someone to figure out what
kind of non-default action the port requires.</para>
<para>舉例來說，若在 <filename>Makefile</filename> 內設定 <maketarget>post-extract</maketarget>
，而且在 <filename>scripts</filename> 子目錄內又有 <filename>pre-build</filename> 檔的話，
那麼在作解壓縮之後，就會開始 <maketarget>post-extract</maketarget> 階段以進行解壓縮後的後續動作，
而在跑 build 階段之前，就會先執行 <filename>pre-build</filename> 這隻 script 作先期準備。
通常較簡單的修改動作，建議直接放在 <filename>Makefile</filename>
內就好了，因為這樣會比較方便加上這些原本沒有的階段，同時也方便他人協助除錯。</para>
<para>The default actions are done by the
<filename>bsd.port.mk</filename> targets
<maketarget>do-<replaceable>something</replaceable></maketarget>.
For example, the commands to extract a port are in the target
<maketarget>do-extract</maketarget>. If you are not happy with the
default target, you can fix it by redefining the
<maketarget>do-<replaceable>something</replaceable></maketarget>
target in your <filename>Makefile</filename>.</para>
<para>預設的各階段動作都是照
<filename>bsd.port.mk</filename> 內的
<maketarget>do-<replaceable>something</replaceable></maketarget> 之類所定義的。
舉例：<maketarget>do-extract</maketarget> 就是定義怎麼把檔案解壓縮的。
若對預設方式覺得不妥的話，都可以在該 port 的 <filename>Makefile</filename> 重新定義。</para>
<note>
<para>The <quote>main</quote> targets (e.g.,
@ -499,20 +446,17 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
the way <maketarget>extract</maketarget> operates!</para>
</note>
<para>Now that you understand what goes on when the user types
<command>make</command>, let us go through the recommended steps to
create the perfect port.</para>
<para>現在，你已經知道打 <command>make</command> 到底會作些什麼事囉，接下來會教你如何作更完美的
port。</para>
</sect1>
<sect1 id="slow-sources">
<title>Getting the original sources</title>
<title>取得原始的 source 檔</title>
<para>Get the original sources (normally) as a compressed tarball
(<filename><replaceable>foo</replaceable>.tar.gz</filename> or
<filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy
it into <makevar>DISTDIR</makevar>. Always use
<emphasis>mainstream</emphasis> sources when and where you
can.</para>
<para>取得原始的 source 檔(通常檔名是 <filename><replaceable>foo</replaceable>.tar.gz</filename>
或 <filename><replaceable>foo</replaceable>.tar.Z</filename> 之類的壓縮檔)，
然後會把抓下來的檔案放在 <makevar>DISTDIR</makevar> 內。
記得：抓的時候，儘量使用『主流站』上面的來源檔，以確保檔案有效、可信。</para>
<para>You will need to set the variable <makevar>MASTER_SITES</makevar>
to reflect where the original tarball resides. You will find

19
zh_TW.Big5/books/zh-tut/chapters/compose.sgml
View file

@ -87,17 +87,16 @@ fetch ftp://freebsd.sinica.edu.tw/pub/statue/OpenOffice/Writer.xml</screen>-->
</sect1>
<sect1 id="eioffice">
<title>eioffice - 永中Office 2003</title>
<para>eioffice 目前只有 Windows 和 GNU/Linux 的版本.
<para>FreeBSD 做法其實很簡單, 因為我本來以為他的 GNU/Linux
版用了特殊的壓縮來包裝, 結果抓去看了一下, 發現 fonts.data
和 source.data 這兩個最大的檔竟然是用 zip 壓縮的, 解開當然發現
fonts.data 裡面包的是字型, source.data 裡面就是主要的程式囉,
拷貝到相對應的地方後就可以執行了.</para>
<para>要注意的是, unzip 一定要用 chinese/unzip, 因為我有弄中文的 patch 在上面, 不然可能會有錯.</para>
<para>jdk 我只有測試 1.4.1, 不知道 1.4.2 有沒有差別.</para>
<title>eioffice - 永中Office 2004</title>
<para>eioffice 目前只有 Windows 和 GNU/Linux 的版本。
<para>FreeBSD 做法其實很簡單，因為我本來以為他的 GNU/Linux
版用了特殊的壓縮來包裝，結果抓去看了一下，發現 fonts.data
和 source.data 這兩個最大的檔竟然是用 zip 壓縮的。解開當然發現
fonts.data 裡面包的是字型，而 source.data 裡面就是主要的程式囉，拷貝到相對應的地方後就可以執行了。</para>
<para>要注意的是，unzip 一定要用 chinese/unzip 裝的，因為我有弄中文的 patch 在上面，不然可能會有錯。</para>
<para>jdk 我只有測試 1.4.1，不知道 1.4.2 有沒有差別。</para>
<para>我也弄了兩個版本, 簡體(eioffice-zh_CN)和繁體(eioffice-zh_TW), 更新 outta-port 後就會看到囉.</para>
<para>WWW: <ulink url="http://www.resii.com.tw/">台灣永中</ulink></para>
<para>WWW: <ulink url="http://www.evermoresw.com/webtr/index.jsp">台灣永中</ulink></para>
<para>WWW: <ulink url="http://www.evermoresw.com.cn/">大陸永中</ulink></para>
</sect1>

24
zh_TW.Big5/books/zh-tut/chapters/fonts.sgml
View file

@ -188,7 +188,7 @@ gugod22 -gugod-clean-medium-r-normal--22-220-75-75-c-110-iso8859-1 </programlist
<para><command>gs --help</command> 會有更多的選項</para>
<para>以此套件搭配 arphicttf 就可以讓大部分的軟體可以透過
gs 讀取 ttf 來產生正確的 gs 檔。</para>
<para>以下是利用 <application>ttfm</application> 來將 <application>arphicttf</application> 的字型加入 gs-cjk 的列表：</para>
<para>以下是利用 <filename role="package">chinese/ttfm</filename> 來將 <application>arphicttf</application> 的字型加入 gs-cjk 的列表：</para>
<screen>
&prompt.root; <userinput>ttfm.sh --add gs-cjk bkai00mp.ttf</userinput>
&prompt.root; <userinput>ttfm.sh --add gs-cjk bsmi00lp.ttf</userinput></screen>
@ -246,7 +246,7 @@ quit
</imageobject>
</mediaobject>
</figure>
<para>目前已經可以由 <application>ttfm</application> 搭配
<para>目前已經可以由 <filename role="package">chinese/ttfm</filename> 搭配
<application>gs-cjk</application>
的方式來取代，而且效果更好。</para>
<para>以下是以 MOESung-Regular 為例子，來增加粗體、斜體、粗斜體支援，
@ -449,12 +449,16 @@ endobj</programlisting>
<para>目前有許多程式都會要求使用 TTF 字型，所以我們最好還是幫 X 加
上中文的 TTF 字型支援。目前安裝字型所需的
<filename>fonts.dir</filename> 已經不需要
使用暴力的方法產生，使用 <application>ttfm</application>
使用暴力的方法產生，使用 <filename role="package">chinese/ttfm</filename>
就可以很順利的管理所有的中文字
型了。而現在在 ports 中的 TrueType 字型有三套，
型了。而現在在 ports 中的 TrueType 字型有七套，
<application>arnettf</application>、
<application>arphicttf</application>、
<application>dfsongsd</application>、
<application>fireflyttf</application>、
<application>mingunittf</application>、
<application>moettf</application>、
<application>wangttf</application>。</para>
<application>wqy</application>。</para>
<para>安裝 <filename role="package">chinese/ttfm</filename>。</para>
<para>安裝後包含了：</para>
<para><command>ttfinfo：</command>一個可以用來讀取 ttf
@ -521,12 +525,12 @@ Usage: /usr/local/bin/ttfm.sh [option]
</programlisting>
</listitem>
</itemizedlist>
<para><application>ttfm</application> 採用模組化的設計。
<para><filename role="package">chinese/ttfm</filename> 採用模組化的設計。
每一個需要使用到 ttf 字型的
程式都可以提供 <application>ttfm</application> 的模組，
程式都可以提供 <filename role="package">chinese/ttfm</filename> 的模組，
然後便可透過 <command>ttfm.sh</command> 來做到
字型的安裝，移除，列表，設定預設字型等管理的動作。
目前已有的 <application>ttfm</application> 模組有：</para>
目前已有的 <filename role="package">chinese/ttfm</filename> 模組有：</para>
<programlisting>
abiword 給 AbiWord 0.7.12 或是以上的版本使用。
chitex 安裝 ChiTeX 字型 (by cwhuang)
@ -559,11 +563,11 @@ xttfm
<screen>
&prompt.root; <userinput>ttfm.sh --setdefault xttfm bkai00mp.ttf</userinput></screen>
<para>將 xttfm 模組的預設字型更改為
bkai00mp.ttf 這或許是 <application>ttfm</application>
bkai00mp.ttf 這或許是 <filename role="package">chinese/ttfm</filename>
最 powerful 的功能之一了。
您可發現 X Window 預設的中文字型通通變成楷體的。</para>
<para>注意預設字型是跟 encoding 有關的。您可以對不同的
encoding 分別給定預設字型。<application>ttfm</application>
encoding 分別給定預設字型。<filename role="package">chinese/ttfm</filename>
會自動根據所給定
ttf 自動判斷應設定那種 encoding 的預設字型。
例如 <command>ttfm.sh --setdefault xttfm gkai00mp.ttf</command>

29
zh_TW.Big5/books/zh-tut/chapters/stepbystep.sgml
View file

@ -255,7 +255,7 @@ EndSection</programlisting>
<sect1 id="cvsup">
<title>保持最新的 Ports Tree</title>
<para>Last Update: 2003年 1月27日 周一 04時50分10秒 CST</para>
<para>Last Update: 2006年 3月13日 周一 01時47分34秒 CST</para>
<para>Contributed by &a.gslin;</para>
<para>在安裝軟體前，最好先更新 Ports Tree，
建議先由安裝光碟中選擇 Ports Collection 先安裝好後，
@ -268,32 +268,27 @@ SUP= /usr/local/bin/cvsup
SUPFLAGS= -g -L 2
#
# SUPHOST 代表要到哪台 CVSup，請改成離您比較近的 Server。
# cvsup[1-9].tw.FreeBSD.org
# cvsup[1-13].tw.FreeBSD.org
SUPHOST= cvsup.tw.FreeBSD.org
#
# 如果您是用 -stable，請用 stable-supfile (目前的 -stable 是 4.3)
# 如果您是用 -current，請用 standard-supfile (目前的 -current 是 5.0)
# 如果您是用 -STABLE，請用 stable-supfile (目前的 4.X -STABLE 是 4.11，5.X -STABLE 是 5.4，6.X -STABLE 是 6.0)
# 如果您是用 -CURRENT，請用 standard-supfile (目前的 -CURRENT 是 7.0)
SUPFILE= /usr/share/examples/cvsup/stable-supfile
PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile
DOCSUPFILE= /usr/share/examples/cvsup/doc-supfile
# 國內主要的 FreeBSD distfiles mirror 站台
MASTER_SITE_BACKUP?= \
ftp://ftp.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp2.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp3.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp4.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp5.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp7.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp8.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://ftp9.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
ftp://cvsup.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://cvsup10.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://cvsup13.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/\
ftp://cvsup2.tw.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
MASTER_SITE_OVERRIDE?= ${MASTER_SITE_BACKUP}</programlisting>
<note>
<para>可以安裝 <filename role="package">sysutils/fastest_cvsup</filename>
來檢察那一個 cvsup 最適合您，安裝完後修改
<filename>/usr/local/bin/fastest_cvsup</filename>，
把台灣的個數 <option>'tw' => 3, # Taiwan</option> 改成
<option>'tw' => 13, # Taiwan</option>，
然後執行 <command>fastest_cvsup -c tw</command>。</para></note>
來檢察那一個 cvsup 最適合您，安裝完後執行 <command>fastest_cvsup -c tw</command>。
</para></note>
<para>安裝好基本的 Ports Tree 後，安裝
<filename role="package">net/cvsup-without-gui</filename>。</para>
<para>接著就可以進行更新了：</para>

2
zh_TW.Big5/books/zh-tut/freebsd.dsl
View file

@ -4,7 +4,7 @@
-->
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY freebsd.dsl SYSTEM "/usr/doc/share/sgml/freebsd.dsl" CDATA DSSSL>
<!ENTITY freebsd.dsl SYSTEM "../../share/sgml/freebsd.dsl" CDATA DSSSL>
<!ENTITY % lang.zh.dsssl "IGNORE">
]>