diff --git a/documentation/content/zh-tw/articles/contributing/_index.adoc b/documentation/content/zh-tw/articles/contributing/_index.adoc index 7c58c41366..36ddcf9aa7 100644 --- a/documentation/content/zh-tw/articles/contributing/_index.adoc +++ b/documentation/content/zh-tw/articles/contributing/_index.adoc @@ -1,235 +1,247 @@ --- title: 幫助 FreeBSD authors: - author: Jordan Hubbard releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "ieee", "general"] --- = 幫助 FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 無論是個人或是各種組織，如果希望為 FreeBSD 提供幫助，都可以在本文中找到合適的方法。 ''' toc::[] 你希望替 FreeBSD 做點什麼嗎？太好了，我們歡迎你。FreeBSD 正是有賴於廣大使用者的貢獻才得以發展壯大的。我們不僅非常感謝您所做的貢獻，而且，這些工作對於 FreeBSD 的持續發展也至關重要。 也許與您想像的不同，您既不必得是一名出色的 Programmer，也無須和 FreeBSD core team 成員有很好的私交，我們會一視同仁的對待您的工作。 FreeBSD 的開發人員遍布全球，大家技術專長各異，年齡分布也非常廣泛。 然而，每天我們都在面對持續增加的工作，而苦於沒有足夠的人手，因此我們隨時歡迎您的幫助。 FreeBSD 計劃所處理的是一個完整的作業系統環境，而不只是一個 kernel 或是一些零散的工具包。 因此，我們的 [.filename]#TODO# 待辦任務列表裡包含各式各樣的工作： 從文件、使用者測試、demo，到系統安裝程式和更專業的 kernel 開發。 因此無論您的技術水準如何，從事何種領域，都可以幫助這個計劃。 我們鼓勵從事和 FreeBSD 相關工作的企業和我們聯繫。 您需要一些特殊的擴展來使您的產品運轉起來嗎？ 您會發現我們很樂意答應您的請求，除非是特別稀奇古怪的。 您是否正從事相關的增值業務？ 讓我們來幫助您吧， 我們也許可以在某些方面相互合作。 自由軟體界正在努力打破舊有的框框(像是關於軟體開發、銷售和維護)， 我們希望懇請您至少能給它一次機會。 [[contrib-what]] == 我們的需求 下面列出了一些需要完成的任務和子計劃， 它們代表 [.filename]#TODO#(待辦任務列表) 列表的意思，以及使用者的要求。 [[non-programmer-tasks]] === 正在進行中的任務(非程式開發人員) 很多參加 FreeBSD 計劃的人不是 Programmer。 這個計劃裡有文件撰寫者、網頁設計師、以及技術支援人員。 對於這些義工來說，他們只需要貢獻一些時間，並且具有學習的意願。 . 您可以時常翻閱 FAQ 和手冊(Handbook) ，如果發現有解釋不清楚的地方，或是不合時宜的文件，甚至完全不正確的地方， 都請告訴我們。當然，若能順手把他們修正，並把勘誤寄給我們，那就更好了。:) (SGML 其實並不難學，但我們也不反對您直接提交一般 ASCII 的純文字版本)。 . 幫助我們把 FreeBSD 文件翻譯成你的母語。 如果你的母語版本已經存在了， 也可以翻譯一些額外的文件，或者檢查那些已有的文件是否為最新版。 您可以先簡單看看 FreeBSD 文件計劃中有關 link:{fdp-primer}#translations[翻譯時的常見問題]。 參加翻譯工作，並不是說您要孤軍奮戰翻譯所有 FreeBSD 文件。 身為義工，要做多少工作完全取決於您的意願。一旦某個人開始翻譯了， 之後幾乎一定會有其他人參與到這些工作中來。 如果時間有限，或者精力不夠去翻譯整份文件，那可以首先去翻譯安裝指南。 . 閱讀 {freebsd-questions} 並偶爾翻閱(甚至有規律地這樣做) link:news:comp.unix.bsd.freebsd.misc[comp.unix.bsd.freebsd.misc] 。與別人分享您的專業知識， 並幫助他們解決問題，是件令人愉悅的事情； 有時候，您甚至可以在這個過程中學到一些新東西！ 這些論壇有時也會為您激發出一些不錯的想法。 [[ongoing-programmer-tasks]] === 正在進行中的任務(程式開發人員) 列在這裡的大部分任務都需要您投入可觀的時間，或者需要您在 FreeBSD kernel 方面有豐富的知識，或者兩者都要。當然這裡也有很多重要的任務，適合像是 "weekend hackers" 這類只用週末就可以搞定的 Hacker。 . 如果您正在跑的是 FreeBSD -CURRENT 版本，並且網路速度還不錯， 那麼可以到 `current.FreeBSD.org`， 這台每天會有一個新版本 - 如果您有空， 您可以三不五時下載並安裝， 其間如果出了什麼問題，請告訴我們。 . 閱讀 {freebsd-bugs}。這些問題，或許您能提供有建設性意義的意見， 或者幫忙測試一些 patch 。此外，甚至可以嘗試修正其中的一些問題。 . 如果您知道有一些修正已經在 -CURRENT 上成功地使用， 但在經過一段時間(通常是 2 週左右)之後，仍未合併到 -STABLE (這步驟就是 MFC -- Merged From Current)，那麼可以給相關的 committer 人員發封禮貌的提醒信。 . 將第三方(3rd party)軟體加入到原始碼中的 [.filename]#src/contrib# 目錄。 . 確保 [.filename]#src/contrib# 中的原始碼是最新的。 . 編譯原始碼(或是部分原始碼)時，請改用更高的警告等級(warning level) 以便偵錯(debug)用，並在完成測試、確認正常完畢之後，清除這些編譯的警告等級。 . 更新那些在 ports 中使用過時的東西， 例如 `gets()` 或包含 [.filename]#malloc.h# 所產生的警告。 . 如果有為 ports 作了任何修正， 請記得將您的 patch 發給原作者 (這樣下次升級時，您的工作會變得輕鬆一些)。 . 先取得正式的標準，如 POSIX(R) 的副本。 在 link:https://www.FreeBSD.org/projects/c99/[FreeBSD C99 & POSIX 標準相容計劃] 網站上，可以得到相關鏈接。 請將 FreeBSD 的行為與上述的標準進行比較，若所得結果與 C99 & POSIX 標準不同的話， 特別是那些細節地方的微小差異，請發一個關於它的 PR (問題報告)。 如果可能，請指出如何修正它，並隨 PR 提交 patch 。 如果您認為標準有問題，請向這些規格標準的相關團體，請求對其進行重新的考慮。 . 為這份列表提供更多建議！ === 查閱整個 PR 資料庫 http://www.FreeBSD.org/cgi/query-pr-summary.cgi[FreeBSD PR 列表] 這裡會顯示目前所有 PR 的問題狀態，以及由 FreeBSD 使用者提交的改進建議。 PR 資料庫同時包括了開發人員和非開發人員的任務。 查看那些尚未解決的 PR，並看看是否有您感興趣的任務。 這其中可能有一些是非常簡單的問題，只需要看一看並確認 PR 是正確的。 另外一些可能會非常複雜，或者完全未附任何修正。 首先看一看那些還沒有人接手的 PR。 如果 PR 已經分配給了其它人，但看起來是您能夠處理的， 您可以寄信給那個人，並詢問您是否可以提供幫助 - 他們可能已經有可供測試的 patch ，或有一些可供討論的意見。 === 由 "Ideas" 中選一項 link:https://www.FreeBSD.org/projects/ideas/[FreeBSD list of projects and ideas for volunteers] 同樣地開放給有意願參與 FreeBSD 計劃的人。 這份清單將持續地更新，同時提供各個項目的資訊給所有人 （不論是否為程式設計人員）。 [[contrib-how]] == 如何提供幫助 基本上可以分為以下 5 種方式： [[contrib-general]] === 錯誤報告和意見發表 通常，__一般__ 的技術想法和建議應該發到 {freebsd-hackers}。 同樣地，對於這些東西有興趣的人 (當然， 他們同時還要能夠容忍 _大量的_ 郵件！) 可以考慮訂閱 {freebsd-hackers}。 請參閱 link:{handbook}#eresources-mail[FreeBSD 使用手冊] 以了解關於這個郵遞論壇， 以及其它郵遞論壇的詳細情況。 如果您發現了 bug 或者想要提交某些修改， 請透過 man:send-pr[1] 程式或使用 link:https://www.FreeBSD.org/send-pr/[網頁介面 的回報] 來提交。請試著填寫 PR 的每個項目。 一般來說，除非 patch 檔超過 65 KB，我們建議在 PR 中直接附上 patch 就可以了。 若可直接套用 patch 到原始碼的話，那麼建議在 PR 的 Synopsis 欄位註明 `[PATCH]`。 對了，在附上 patch 時，請 _不要_ 透過滑鼠的『複製、貼上』來進行，因為這樣做會把 Tab 變成空格， 會導致 patch 就不能用了。如果 patch 超過 20KB， 請考慮壓縮它並使用 man:uuencode[1] 來進行編碼。 在寫完 PR 之後，您會收到一封確認郵件以及事件追蹤編號。 請保留這個編號，因為事後可以用這編號發信到 {bugfollowup} 來回覆、提供關於該事件的後續資料。您需要做的是將編號放到郵件的標題中， 例如 `"Re: kern/3377"`。 若是同一問題的回覆方面，應該透過這種方式來進行。 如果您在一段時間 (超過 3 天甚至 1 週，這取決於您的郵件服務)之後仍然沒有收到確認信 或者由於一些原因無法使用 man:send-pr[1] 程式， 則可以發信到 {freebsd-bugs} 來請別人幫你代寄。 請參閱 link:{problem-reports}[這篇文章] 了解如何撰寫好的問題報告。 === 對於文件的修訂 文件的修改方面，是由 {freebsd-doc} 來審查。 請參閱 link:{fdp-primer}[FreeBSD Documentation Project Primer] 來獲得完整的教學細節。 請按照 <> 中介紹的方法使用 man:send-pr[1] 來提交新的文件，或者改善現有的文件 (哪怕是很小的改進也是歡迎的！)。 === 對於現有原始碼的修改 在現有原始碼上進行修改或增加功能，在某種程度上是需要更多技巧的事， 並且還跟您對於目前 FreeBSD 的開發現狀了解程度有關。 有多種方式可以得到被稱作 "FreeBSD-CURRENT" 的 FreeBSD 開發版本。 請參閱 FreeBSD 使用手冊的 link:{handbook}#current-stable[相關部份] ，來了解使用 FreeBSD-CURRENT 的詳情。 在舊的原始碼上進行修改，則通常可能原始碼已過時， 或與新的版本差異太大而無法被重新整合到 FreeBSD 中。 如果您有訂 {freebsd-announce} 以及 {freebsd-current} 的話， 則可以透過它們來大致了解目前的開發狀態。 若您能夠儘量以最新的原始碼來進行您的修改， 則下一步要做的事情就是產生您所修改的 diff 檔， 並將它發給 FreeBSD 的維護人員。這項工作可以透過 man:diff[1] 命令來完成。 提交 patch 時，建議 man:diff[1] 格式採用 unified diff (可以用 `diff -u` 來產生)。不過，如果您修改了大量的原始碼， 則使用 `diff -c` 來生成的 context diff 的 diff 可能更容易閱讀，因而推薦使用。一般而言，大都是採用 `diff -ruN` 即可。 例如： [source,shell] .... % diff -c oldfile newfile .... 或 [source,shell] .... % diff -c -r olddir newdir .... 將會對特定目錄，產生 context 的 diff 檔。 或者像是... [source,shell] .... % diff -u oldfile newfile .... 或 [source,shell] .... % diff -u -r olddir newdir .... 將產生一樣的 diff ，但是格式為 unified 。 更多的細節部份，請參閱 man:diff[1]。 一旦您使用 man:diff[1] 來產生 diff 檔 (可以使用 man:patch[1] 命令來測試一下)，就可以提交它們，以便被 FreeBSD 收錄。 透過使用 <> 中所介紹的 man:send-pr[1] 程式就可以完成這項工作。 請注意：不要只把 diff 檔發到 {freebsd-hackers}， 否則它們可能會被遺忘！ 我們會非常感激您提交的修改 (這是一個義工計劃！)； 因為我們都很忙， 因此有時不一定能夠立即修正問題，但 PR 資料庫將一直保持著這些記錄， 因此只要有人有了時間它們就能被改正了。 如果您的問題報告中包括 patch ，不要忘了在標題加上 `[PATCH]` 來強調一下。 如果您認為合適 (例如增、刪檔案或更改檔名)， 還可以考慮使用 `tar` 來將檔案打包，然後用 man:uuencode[1] 來編碼。此外，也可以用 man:shar[1] 產生的方式。 如果您的修改可能存在潛在的爭議，例如， 您不確定相關的版權問題，或者感覺需要經過更嚴格的復審才可以發佈它們， 則應直接發給 {core}，而不是透過 man:send-pr[1] 來發送。 {core} 這小組成員大多從事 FreeBSD 的日常工作。 需要注意的是，這個小組也因此十分忙碌， 因此只有在非常必要的時候，才應寫信給他們。 請參考 man:intro[9] 和 man:style[9] 以了解關於撰寫程式碼的風格偏好。 若能在送出相關程式碼之前，先了解這些，那對大家來說將是極大的幫助。 === 新原始碼或重要的加值軟體包 如果您打算提供規模較大的原始碼，或者為 FreeBSD 增加重要的新功能， 則可能必須將它們透過 uuencode 進行編碼，或傳到某個 Web 或 FTP 站點，以便更多的人能夠得到它。如果您沒有這樣的主機， 請到相關的 FreeBSD 郵遞論壇提出，看看是否有人願意幫您放置它們。 對於大量的原始碼而言，關於版權的問題肯定會被提出。 FreeBSD 基本系統中能夠使用的版權聲明包括： . BSD 版權。我們傾向於使用這類授權的原始碼， 因為它『不附加多餘的條件』，因而更能夠吸引商業企業使用。 FreeBSD 並不反對商業公司使用它的原始碼，相反， 我們積極地鼓勵商業公司使用我們的原始碼， 當然，如果它們若最終能把部分原始碼，重新捐贈給 FreeBSD 就更好了。 . GNU General Public License，或簡稱 "GPL"。 我們並不很歡迎使用這樣授權的原始碼， 因為商業公司使用它需要做更多的工作。不過，由於很多使用 GPL 授權的原始碼目前是無法避免的 (compiler, assembler, text formatter等等) ，拒絕使用所有採用這樣授權的軟體是很不明智的。 採用 GPL 授權的原始碼會被放到原始碼的一些特定的位置，例如 [.filename]#/sys/gnu# 或 [.filename]#/usr/src/gnu#，以便那些認為 GPL 可能會造成麻煩的人能夠作出適當的判斷。 使用其它授權的原始碼在進入 FreeBSD 之前必須經過慎重的復審和考慮。 採用包含嚴厲限制的商業授權的原始碼，一般來說會被拒絕， 但我們鼓勵這些原始碼的作者，透過自己的管道來發布它們。 若要在您的成果上加入 "BSD-based" 版權的話， 請把下列文字放到每份原始碼的最開始部分， 並用適當的文字替換 `%%` 之間的文字。 [.programlisting] .... Copyright (c) %%proper_years_here%% %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ .... 為了方便您的使用，在 [.filename]#/usr/shared/examples/etc/bsd-style-copyright# 也可以找到此授權的副本。 === 贊助資金、硬體或 Internet mirror 我們非常願意接受各種形式的捐贈，以進一步拓展 FreeBSD 計劃 ，因為有您的支持，像我們這樣的義工努力才能夠有更大的成就！ 捐贈硬體也非常重要，因為這樣能夠幫助我們增加可支援的硬體種類， 而我們中的很多人並沒有足夠的資金來購置這些硬體。 [[donations]] ==== 捐款 FreeBSD 基金會是一個非營利的、有課稅豁免權的基金會， 之所以會建立這個基金會，是為了讓 FreeBSD 計劃能夠可長可久。 因為該基金會屬 501(c)3 實體，一般而言捐款給基金會的話，可以免繳美國聯邦收入稅， 以及科羅拉多州收入稅。通常對於有課稅豁免權的實體進行捐贈的話， 可以折抵聯邦收入中應課稅部分的金額。 您可以把支票寄往： [.address] **** The FreeBSD Foundation + P.O. Box 20247, + Boulder, + CO 80308 + USA **** FreeBSD 基金會現在可以透過 PayPal 從網上接受捐款。 如果您想向基金會捐款，請參閱 http://www.freebsdfoundation.org[FreeBSD 基金會] 網站。 關於 FreeBSD 基金會的更多詳情，可以在 http://people.FreeBSD.org/~jdp/foundation/announcement.html[FreeBSD 基金會 -- 介紹] 找到。要聯絡基金會， 請發送電子郵件到 mailto:bod@FreeBSDFoundation.org[bod@FreeBSDFoundation.org]。 ==== 捐贈硬體 FreeBSD 計劃歡迎任何人捐贈可以使用的硬體。 如果您有興趣捐贈硬體，請聯繫 link:https://www.FreeBSD.org/donations/[捐贈聯絡人辦公室]。 ==== 成為 FreeBSD mirror 的網站 我們歡迎新的 FTP、WWW 或 `cvsup` mirror 站。如果您希望成為這樣的 mirror 站， 請參閱 link:{hubs}[如何架設 FreeBSD mirror] 一文，以了解進一步的情況。 diff --git a/documentation/content/zh-tw/articles/freebsd-questions/_index.adoc b/documentation/content/zh-tw/articles/freebsd-questions/_index.adoc index 91bb198fa1..c614749423 100644 --- a/documentation/content/zh-tw/articles/freebsd-questions/_index.adoc +++ b/documentation/content/zh-tw/articles/freebsd-questions/_index.adoc @@ -1,239 +1,251 @@ --- title: 如何在 FreeBSD-questions mailing list 上得到正解 authors: - author: Greg Lehey email: grog@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "microsoft", "opengroup", "qualcomm", "general"] --- = 如何在 FreeBSD-questions mailing list 上得到正解 :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 本文主要是給準備寫信到 FreeBSD-questions mailing list 的人提供一些參考。 我們會給你一些發問的技巧與建議，以便讓你的答案得到更有用的答覆。 本文會定期發到 FreeBSD-questions mailing list 上。 ''' toc::[] == 簡介 `FreeBSD-questions` is a mailing list maintained by the FreeBSD project to help people who have questions about the normal use of FreeBSD. Another group, `FreeBSD-hackers`, discusses more advanced questions such as future development work. [NOTE] ==== The term "hacker" has nothing to do with breaking into other people's computers. The correct term for the latter activity is "cracker", but the popular press has not found out yet. The FreeBSD hackers disapprove strongly of cracking security, and have nothing to do with it. For a longer description of hackers, see Eric Raymond's http://www.catb.org/~esr/faqs/hacker-howto.html[How To Become A Hacker] ==== This is a regular posting aimed to help both those seeking advice from FreeBSD-questions (the "newcomers"), and also those who answer the questions (the "hackers"). Inevitably there is some friction, which stems from the different viewpoints of the two groups. The newcomers accuse the hackers of being arrogant, stuck-up, and unhelpful, while the hackers accuse the newcomers of being stupid, unable to read plain English, and expecting everything to be handed to them on a silver platter. Of course, there is an element of truth in both these claims, but for the most part these viewpoints come from a sense of frustration. In this document, I would like to do something to relieve this frustration and help everybody get better results from FreeBSD-questions. In the following section, I recommend how to submit a question; after that, we will look at how to answer one. == How to subscribe to FreeBSD-questions FreeBSD-questions is a mailing list, so you need mail access. Point your WWW browser to the {freebsd-questions}. In the section titled "Subscribing to freebsd-questions" fill in the "Your email address" field; the other fields are optional. [NOTE] ==== The password fields in the subscription form provide only mild security, but should prevent others from messing with your subscription. _Do not use a valuable password_ as it will occasionally be emailed back to you in cleartext. ==== You will receive a confirmation message from mailman; follow the included instructions to complete your subscription. Finally, when you get the "Welcome" message from mailman telling you the details of the list and subscription area password, __please save it__. If you ever should want to leave the list, you will need the information there. See the next section for more details. == How to unsubscribe from FreeBSD-questions When you subscribed to FreeBSD-questions, you got a welcome message from mailman. In this message, amongst other things, it told you how to unsubscribe. Here is a typical message: .... Welcome to the freebsd-questions@freebsd.org mailing list! To post to this list, send your email to: freebsd-questions@freebsd.org General information about the mailing list is at: http://lists.freebsd.org/mailman/listinfo/freebsd-questions If you ever want to unsubscribe or change your options (e.g., switch to or from digest mode, change your password, etc.), visit your subscription page at: http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de You can also make such adjustments via email by sending a message to: freebsd-questions-request@freebsd.org with the word `help' in the subject or body (don't include the quotes), and you will get back a message with instructions. You must know your password to change your options (including changing the password, itself) or to unsubscribe. It is: 12345 Normally, Mailman will remind you of your freebsd.org mailing list passwords once every month, although you can disable this if you prefer. This reminder will also include instructions on how to unsubscribe or change your account options. There is also a button on your options page that will email your current password to you. .... From the URL specified in your "Welcome" message you may visit the "Account management page" and enter a request to "Unsubscribe" you from FreeBSD-questions mailing list. A confirmation message will be sent to you from mailman; follow the included instructions to finish unsubscribing. If you have done this, and you still can not figure out what is going on, send a message to mailto:freebsd-questions-request@FreeBSD.org[freebsd-questions-request@FreeBSD.org], and they will sort things out for you. _Do not_ send a message to FreeBSD-questions: they can not help you. == Should I ask `-questions` or `-hackers`? Two mailing lists handle general questions about FreeBSD, `FreeBSD-questions` and `FreeBSD-hackers`. In some cases, it is not really clear which group you should ask. The following criteria should help for 99% of all questions, however: . If the question is of a general nature, ask `FreeBSD-questions`. Examples might be questions about installing FreeBSD or the use of a particular UNIX(R) utility. . If you think the question relates to a bug, but you are not sure, or you do not know how to look for it, send the message to `FreeBSD-questions`. . If the question relates to a bug, and you are _sure_ that it is a bug (for example, you can pinpoint the place in the code where it happens, and you maybe have a fix), then send the message to `FreeBSD-hackers`. . If the question relates to enhancements to FreeBSD, and you can make suggestions about how to implement them, then send the message to `FreeBSD-hackers`. There are also a number of other specialized mailing lists, for example `FreeBSD-isp`, which caters to the interests of ISPs (Internet Service Providers) who run FreeBSD. If you happen to be an ISP, this does not mean you should automatically send your questions to `FreeBSD-isp`. The criteria above still apply, and it is in your interest to stick to them, since you are more likely to get good results that way. == Before submitting a question You can (and should) do some things yourself before asking a question on one of the mailing lists: * Try solving the problem on your own. If you post a question which shows that you have tried to solve the problem, your question will generally attract more positive attention from people reading it. Trying to solve the problem yourself will also enhance your understanding of FreeBSD, and will eventually let you use your knowledge to help others by answering questions posted to the mailing lists. * Read the manual pages, and the FreeBSD documentation (either installed in [.filename]#/usr/doc# or accessible via WWW at http://www.FreeBSD.org[http://www.FreeBSD.org]), especially the link:{handbook}[handbook] and the link:{faq}[FAQ]. * Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at http://www.FreeBSD.org/mail[http://www.FreeBSD.org/mail] and http://www.FreeBSD.org/search/#mailinglists[http://www.FreeBSD.org/search/#mailinglists] respectively. This can be done at other WWW sites as well, for example at http://marc.theaimsgroup.com[http://marc.theaimsgroup.com]. * Use a search engine such as http://www.google.com[Google] or http://www.yahoo.com[Yahoo] to find answers to your question. Google even has a http://www.google.com/bsd[BSD-specific search interface]. == How to submit a question When submitting a question to FreeBSD-questions, consider the following points: * Remember that nobody gets paid for answering a FreeBSD question. They do it of their own free will. You can influence this free will positively by submitting a well-formulated question supplying as much relevant information as possible. You can influence this free will negatively by submitting an incomplete, illegible, or rude question. It is perfectly possible to send a message to FreeBSD-questions and not get an answer even if you follow these rules. It is much more possible to not get an answer if you do not. In the rest of this document, we will look at how to get the most out of your question to FreeBSD-questions. * Not everybody who answers FreeBSD questions reads every message: they look at the subject line and decide whether it interests them. Clearly, it is in your interest to specify a subject. "FreeBSD problem" or "Help" are not enough. If you provide no subject at all, many people will not bother reading it. If your subject is not specific enough, the people who can answer it may not read it. * Format your message so that it is legible, and PLEASE DO NOT SHOUT!!!!!. We appreciate that a lot of people do not speak English as their first language, and we try to make allowances for that, but it is really painful to try to read a message written full of typos or without any line breaks. + Do not underestimate the effect that a poorly formatted mail message has, not just on the FreeBSD-questions mailing list. Your mail message is all people see of you, and if it is poorly formatted, one line per paragraph, badly spelt, or full of errors, it will give people a poor impression of you. + A lot of badly formatted messages come from http://www.lemis.com/email.html[bad mailers or badly configured mailers]. The following mailers are known to send out badly formatted messages without you finding out about them: ** cc:Mail ** Eudora(R) ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Internet Mail ** Microsoft(R) Outlook(R) ** Netscape(R) + As you can see, the mailers in the Microsoft world are frequent offenders. If at all possible, use a UNIX(R) mailer. If you must use a mailer under Microsoft environments, make sure it is set up correctly. Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. * Make sure your time and time zone are set correctly. This may seem a little silly, since your message still gets there, but many of the people you are trying to reach get several hundred messages a day. They frequently sort the incoming messages by subject and by date, and if your message does not come before the first answer, they may assume they missed it and not bother to look. * Do not include unrelated questions in the same message. Firstly, a long message tends to scare people off, and secondly, it is more difficult to get all the people who can answer all the questions to read the message. * Specify as much information as possible. This is a difficult area, and we need to expand on what information you need to submit, but here is a start: ** In nearly every case, it is important to know the version of FreeBSD you are running. This is particularly the case for FreeBSD-CURRENT, where you should also specify the date of the sources, though of course you should not be sending questions about -CURRENT to FreeBSD-questions. ** With any problem which _could_ be hardware related, tell us about your hardware. In case of doubt, assume it is possible that it is hardware. What kind of CPU are you using? How fast? What motherboard? How much memory? What peripherals? + There is a judgement call here, of course, but the output of the man:dmesg[8] command can frequently be very useful, since it tells not just what hardware you are running, but what version of FreeBSD as well. ** If you get error messages, do not say "I get error messages", say (for example) "I get the error message 'No route to host'". ** If your system panics, do not say "My system panicked", say (for example) "my system panicked with the message 'free vnode isn't'". ** If you have difficulty installing FreeBSD, please tell us what hardware you have. In particular, it is important to know the IRQs and I/O addresses of the boards installed in your machine. ** If you have difficulty getting PPP to run, describe the configuration. Which version of PPP do you use? What kind of authentication do you have? Do you have a static or dynamic IP address? What kind of messages do you get in the log file? * A lot of the information you need to supply is the output of programs, such as man:dmesg[8], or console messages, which usually appear in [.filename]#/var/log/messages#. Do not try to copy this information by typing it in again; it is a real pain, and you are bound to make a mistake. To send log file contents, either make a copy of the file and use an editor to trim the information to what is relevant, or cut and paste into your message. For the output of programs like man:dmesg[8], redirect the output to a file and include that. For example, + [source,shell] .... % dmesg > /tmp/dmesg.out .... + This redirects the information to the file [.filename]#/tmp/dmesg.out#. * If you do all this, and you still do not get an answer, there could be other reasons. For example, the problem is so complicated that nobody knows the answer, or the person who does know the answer was offline. If you do not get an answer after, say, a week, it might help to re-send the message. If you do not get an answer to your second message, though, you are probably not going to get one from this forum. Resending the same message again and again will only make you unpopular. To summarize, let's assume you know the answer to the following question (yes, it is the same one in each case). You choose which of these two questions you would be more prepared to answer: .範例 1 [example] ==== .... Subject: HELP!!?!?? I just can't get hits damn silly FereBSD system to workd, and Im really good at this tsuff, but I have never seen anythign sho difficult to install, it jst wont work whatever I try so why don't you guys tell me what I doing wrong. .... ==== .範例 2 [example] ==== .... Subject: Problems installing FreeBSD I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot of difficulty installing it. I have a 66 MHz 486 with 16 MB of memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball disk and a Toshiba 3501XA CDROM drive. The installation works just fine, but when I try to reboot the system, I get the message Missing Operating System. .... ==== == How to follow up to a question Often you will want to send in additional information to a question you have already sent. The best way to do this is to reply to your original message. This has three advantages: . You include the original message text, so people will know what you are talking about. Do not forget to trim unnecessary text out, though. . The text in the subject line stays the same (you did remember to put one in, did you not?). Many mailers will sort messages by subject. This helps group messages together. . The message reference numbers in the header will refer to the previous message. Some mailers, such as http://www.mutt.org/[mutt], can _thread_ messages, showing the exact relationships between the messages. == How to answer a question Before you answer a question to FreeBSD-questions, consider: . A lot of the points on submitting questions also apply to answering questions. Read them. . Has somebody already answered the question? The easiest way to check this is to sort your incoming mail by subject: then (hopefully) you will see the question followed by any answers, all together. + If somebody has already answered it, it does not automatically mean that you should not send another answer. But it makes sense to read all the other answers first. . Do you have something to contribute beyond what has already been said? In general, "Yeah, me too" answers do not help much, although there are exceptions, like when somebody is describing a problem he is having, and he does not know whether it is his fault or whether there is something wrong with the hardware or software. If you do send a "me too" answer, you should also include any further relevant information. . Are you sure you understand the question? Very frequently, the person who asks the question is confused or does not express himself very well. Even with the best understanding of the system, it is easy to send a reply which does not answer the question. This does not help: you will leave the person who submitted the question more frustrated or confused than ever. If nobody else answers, and you are not too sure either, you can always ask for more information. . Are you sure your answer is correct? If not, wait a day or so. If nobody else comes up with a better answer, you can still reply and say, for example, "I do not know if this is correct, but since nobody else has replied, why don't you try replacing your ATAPI CDROM with a frog?". . Unless there is a good reason to do otherwise, reply to the sender and to FreeBSD-questions. Many people on the FreeBSD-questions are "lurkers": they learn by reading messages sent and replied to by others. If you take a message which is of general interest off the list, you are depriving these people of their information. Be careful with group replies; lots of people send messages with hundreds of CCs. If this is the case, be sure to trim the Cc: lines appropriately. . Include relevant text from the original message. Trim it to the minimum, but do not overdo it. It should still be possible for somebody who did not read the original message to understand what you are talking about. . Use some technique to identify which text came from the original message, and which text you add. I personally find that prepending "`>`" to the original message works best. Leaving white space after the "`>`" and leave empty lines between your text and the original text both make the result more readable. . Put your response in the correct place (after the text to which it replies). It is very difficult to read a thread of responses where each reply comes before the text to which it replies. . Most mailers change the subject line on a reply by prepending a text such as "Re: ". If your mailer does not do it automatically, you should do it manually. . If the submitter did not abide by format conventions (lines too long, inappropriate subject line), _please_ fix it. In the case of an incorrect subject line (such as "HELP!!??"), change the subject line to (say) "Re: Difficulties with sync PPP (was: HELP!!??)". That way other people trying to follow the thread will have less difficulty following it. + In such cases, it is appropriate to say what you did and why you did it, but try not to be rude. If you find you can not answer without being rude, do not answer. + If you just want to reply to a message because of its bad format, just reply to the submitter, not to the list. You can just send him this message in reply, if you like. diff --git a/documentation/content/zh-tw/articles/hubs/_index.adoc b/documentation/content/zh-tw/articles/hubs/_index.adoc index c461be0051..fb74f127f5 100644 --- a/documentation/content/zh-tw/articles/hubs/_index.adoc +++ b/documentation/content/zh-tw/articles/hubs/_index.adoc @@ -1,294 +1,304 @@ --- title: Mirroring FreeBSD authors: - author: Jun Kuriyama email: kuriyama@FreeBSD.org - author: Valentino Vaschetto email: logo@FreeBSD.org - author: Daniel Lang email: dl@leo.org - author: Ken Smith email: kensmith@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Mirroring FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 這是份介紹如何 mirror FreeBSD,主要是針對網路中心管理者或託管於大型資料中心的管理者. ''' toc::[] [NOTE] ==== 我們目前不接受新Mirror站點的申請. ==== [[mirror-contact]] == 聯繫方式 The Mirror System Coordinators can be reached through email at mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org]. There is also a http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[FreeBSD mirror sites mailing lists]. [[mirror-requirements]] == FreeBSD mirrors 的需求 [[mirror-diskspace]] === 磁碟空間 磁碟空間是最為需要. 根據你想要 mirror 的發行版、CPU架構 ,可能會消耗大量的磁碟空間.另外請注意 _官方_ 鏡像站需要完整 mirror。網站內容亦需要完整鏡像。且這裡所述的數字是反應目前版本狀態 (如 10.4-RELEASE/11.1-RELEASE )。而不斷的開發與發行將會增加所需空間。並請務必保留一些 ( 約10-20% ) 額外空間。這裡大約估計如下： * 完整的作業系統套件 FTP 站所需：1.4 TB * CTM deltas： 10 GB * 網站： 1GB 目前 FTP Distribution 的磁碟使用可在 link:ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes[ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes] 找到。 [[mirror-bandwidth]] === 網路連線/頻寬 當然，你一定要能連上 Internet。 頻寬需求多少，這要看你所想要的 mirror 程度而定。 若只想要 mirror 一部份的 FreeBSD 檔案以作為網站或 intranet 的局部用途， 那麼頻寬需求會明顯比成為公共服務用途的小一些。 若想成為 official mirror 之一的話，那麼頻寬就勢必得增加才夠用。以下，我們僅列出一些估計值以做為參考： * 本地站台，沒有要公共存取： 基本上沒有最低需求，但是 < 2Mbps 同步將會非常緩慢 * 非官方公共站台: 34Mbps 是不錯的開始. * 官方站台: > 100Mbps 是建議值,並且你的主機必須盡可能連接靠近邊界路由器. [[mirror-system]] === 系統需求，CPU，RAM 這取決於預期的客戶端數量,這是由伺服器的策略決定的。也會受到您提供的服務類型而影響.普通的 FTP 或 HTTP 服務可能不需要大量的資源。注意如果您提供rsync. 這可能會對 CPU 和記憶體的需求產生巨大的影響，因為會消耗大量記憶體。 以下只是給你一個非常粗略的的例子。 針對一個較常被瀏覽的網站 rsync，您須考量處理器大約 800Mhz 至 1Ghz，並且安裝最少 512MB RAM，這或許是成為一個 _官方_ 站台的最小需求. 為了一個經常使用的網站你絕對需要更多 RAM (2GB是不錯的開始) 並且儘可能有更多 CPU ， 這也表示你需要一個 SMP 系統。 您也會需要考慮有一個較快的磁碟系統。在管理 SVN repository 需要一個快速的磁碟系統 ( 強烈建議 RAID)。有自己的快取記憶體的 SCSI 控制器也可以加快速度，因為大多數這些服務會對磁碟進行大量的小幅修改。 [[mirror-services]] === 提供的服務 每個鏡像站都需要一有一組可用的核心服務。除了這些所需的服務之外，還有許多伺服器管理員可以選擇提供的選用服務。本節將說明您可以提供哪些服務以及如何實作這些服務。 [[mirror-serv-ftp]] ==== FTP (需要提供給FTP檔案集) 這是最基本的服務之一。需要為每個鏡像站提供公共的 FTP distributions 。 FTP 存取必須是匿名的， 不允許上傳/下載比率 （這是一件荒謬的事），上傳功能不是必需的 （且__必須 __絕不允許 FreeBSD 檔案空間）。另外，FreeBSD archive 應該在路徑 [.filename]#/pub/FreeBSD# 下。 這裡有很多可用的軟體可以架設允許匿名的 FTP 服務 （按字母順序）。 * `/usr/libexec/ftpd`: FreeBSD 內建的 ftpd 可以使用。請您參閱 man:ftpd[8]。 * package:ftp/ncftpd[]。一個商業軟體套件，免費供教育使用。 * package:ftp/oftpd[]：一個以安全性作為主要考量的 ftpd。 * package:ftp/proftpd[]：一個模組化且非常有彈性的 ftpd。 * package:ftp/pure-ftpd[]: 另一個為安全所設計的 ftpd。 * package:ftp/twoftpd[]：如上。 * package:ftp/vsftpd[]："非常安全的" ftpd。 FreeBSD 的 ftpd、proftpd 和也許 ncftpd 是最常使用的 FTP 軟體。其他的在鏡像站並沒有大量用戶基礎。需要考慮的一件事情是,您可能需要性地來限制允許同時連線數，從而限制消耗多少網路頻寬和系統資源。 [[mirror-serv-rsync]] ==== Rsync (給FTP檔案集選用) rsync 通常是用在存取 FreeBSD 系統中的FTP內容，其他的鏡像站可以使用你的系統當作他們的來源。這個協定和 FTP 有很多不同，它比較不那麼消耗頻寬，只有當比對檔案間有變動才傳輸檔案，而不是整個檔案傳完。rsync 需要較多的記憶體。大小取決於檔案與目錄的數目及同步模組大小。rsync 可以使用 `rsh` 和 `ssh` （現在為預設）來傳輸， 或使用自己的協定單獨存取（這是公共rsync伺服器的首選方法）。可以用認證、連接限制和其他限制。只有一個軟體套件可以用： * package:net/rsync[] [[mirror-serv-http]] ==== HTTP（網頁需要，FTP 檔案集則是選用） 如果您想提供 FreeBSD 的網頁，您需要安裝一個網頁伺服器。您可以選擇利用 HTTP 提供 FTP 檔案集。網頁伺服器軟體的選擇留給鏡像站管理員選擇。一些最受歡迎的選擇是： * package:www/apache22[]：Apache 是網際網路上最廣泛使用的網頁伺服器。 它被 FreeBSD 計畫廣泛使用。 * package:www/thttpd[]：如果您要提供大量的靜態內容，您可能會發現使用諸如 thttpd 之類的應用程式會比 Apache 更有效率。它針對 FreeBSD 的優秀性能進行了最佳化。 * package:www/boa[]：Boa 是 thttpd 和 Apache 外的另一個選擇。對於純粹的靜態網頁，它應該會提供比 Apache 更好的性能。在寫這篇文章的時候，它並不包含像在 thttpd 中一樣針對FreeBSD 做最佳化。 * package:www/nginx[]：Nginx 是一款高性能的最新網頁服務器，具有低記憶體佔用量和關鍵特色，可以構建現代高效率網頁基礎架構，功能包括 HTTP 伺服器，HTTP 和郵件反向代理，快取，負載平衡，壓縮，請求限制(request throtting)，連接多工與再利用，SSL 卸載和 HTTP 媒體串流。 [[mirror-howto]] == 如何Mirror FreeBSD 站台 好，現在你知道硬體需求和如何提供服務，但不知道如何做。:-) 這節將解釋如何實際 mirror FreeBSD 的不同部分，使用哪些工具以及從哪裡 mirror。 [[mirror-ftp-rsync]] === 鏡像 FTP 站 FTP 部份有最大量的資料需要被 mirror。它包括網路安裝所需的__發布集__，實際上是原始碼樹快照的__分支__，可燒錄光碟供安裝系統的__ISO映像檔__ ，一個可 live 開機的檔案系統，以及一個 port tree 的快照。當然，全都有各種 FreeBSD 版本和各種CPU架構。 The best way to mirror the FTP area is rsync. You can install the port package:net/rsync[] and then use rsync to sync with your upstream host. rsync is already mentioned in <>. Since rsync access is not required, your preferred upstream site may not allow it. You may need to hunt around a little bit to find a site that allows rsync access. [NOTE] ==== 由於 rsync 客戶端的數量將對伺服器主機產生重大影響，因此大多數管理員會對伺服器負荷加以限制。對於 mirror 站台，您應該詢問您要 mirror 站台的管理人員他們的管理政策，也許需要對您的主機開放例外（因為您是一個 mirror 站）。 ==== 一個需要mirror FreeBSD官網的指令如下: [source,shell] .... % rsync -vaHz --delete rsync://ftp4.de.FreeBSD.org/FreeBSD/ /pub/FreeBSD/ .... Consult the documentation for rsync, which is also available at http://rsync.samba.org/[http://rsync.samba.org/], about the various options to be used with rsync. If you sync the whole module (unlike subdirectories), be aware that the module-directory (here "FreeBSD") will not be created, so you cannot omit the target directory. Also you might want to set up a script framework that calls such a command via man:cron[8]. [[mirror-www]] === Mirroring 網頁 FreeBSD 網站應只能透過 rsync 指令來mirror. 一個 mirror FreeBSD 網站的指令應該看起像這樣： [source,shell] .... % rsync -vaHz --delete rsync://bit0.us-west.freebsd.org/FreeBSD-www-data/ /usr/local/www/ .... [[mirror-pkgs]] === Mirroring 套件 由於對頻寬，儲存空間和管理的要求非常高，FreeBSD 計畫決定不允許公眾 mirror 套件. 對於擁有大量伺服主機的網站，建議為 man:pkg[8] 使用 HTTP proxy 快取可能會有所幫助。或者，您可以使用以下指令獲得套件與相依套件： [source,shell] .... % pkg fetch -d -o /usr/local/mirror vim .... 一旦這些套件包被下載，就必須執行以下命令來產生套件庫數據： [source,shell] .... % pkg repo /usr/local/mirror .... 一旦套件被下載並且已經生成了套件庫的數據，就可以透過 HTTP 協定將套件提供給客戶端機器。有關更多訊息，請參閱 man:pkg[8] 的 man pages，特別是 man:pkg-repo[8] 頁面。 [[mirror-how-often]] === 我多久應該mirror? Every mirror should be updated at a minimum of once per day. Certainly a script with locking to prevent multiple runs happening at the same time will be needed to run from man:cron[8]. Since nearly every admin does this in their own way, specific instructions cannot be provided. It could work something like this: [.procedure] . Put the command to run your mirroring application in a script. Use of a plain `/bin/sh` script is recommended. . Add some output redirections so diagnostic messages are logged to a file. . Test if your script works. Check the logs. . Use man:crontab[1] to add the script to the appropriate user's man:crontab[5]. This should be a different user than what your FTP daemon runs as so that if file permissions inside your FTP area are not world-readable those files can not be accessed by anonymous FTP. This is used to "stage" releases -- making sure all of the official mirror sites have all of the necessary release files on release day. Here are some recommended schedules: * FTP fileset: daily * WWW pages: daily [[mirror-where]] == Where to mirror from This is an important issue. So this section will spend some effort to explain the backgrounds. We will say this several times: under no circumstances should you mirror from `ftp.FreeBSD.org`. [[mirror-where-organization]] === A few words about the organization Mirrors are organized by country. All official mirrors have a DNS entry of the form `ftpN.CC.FreeBSD.org`. _CC_ (i.e. country code) is the _top level domain_ (TLD) of the country where this mirror is located. _N_ is a number, telling that the host would be the _Nth_ mirror in that country. (Same applies to `wwwN.CC.FreeBSD.org`, etc.) There are mirrors with no _CC_ part. These are the mirror sites that are very well connected and allow a large number of concurrent users. `ftp.FreeBSD.org` is actually two machines, one currently located in Denmark and the other in the United States. It is _NOT_ a master site and should never be used to mirror from. Lots of online documentation leads "interactive"users to `ftp.FreeBSD.org` so automated mirroring systems should find a different machine to mirror from. Additionally there exists a hierarchy of mirrors, which is described in terms of __tiers__. The master sites are not referred to but can be described as __Tier-0__. Mirrors that mirror from these sites can be considered __Tier-1__, mirrors of __Tier-1__-mirrors, are __Tier-2__, etc. Official sites are encouraged to be of a low __tier__, but the lower the tier the higher the requirements in terms as described in <>. Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted. The __tier__-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites. However, official mirrors with low numbers like 1-4, are usually _Tier-1_ (this is just a rough hint, and there is no rule). [[mirror-where-where]] === Ok, but where should I get the stuff now? Under no circumstances should you mirror from `ftp.FreeBSD.org`. The short answer is: from the site that is closest to you in Internet terms, or gives you the fastest access. [[mirror-where-simple]] ==== I just want to mirror from somewhere! If you have no special intentions or requirements, the statement in <> applies. This means: [.procedure] . Check for those which provide fastest access (number of hops, round-trip-times) and offer the services you intend to use (like rsync). . Contact the administrators of your chosen site stating your request, and asking about their terms and policies. . Set up your mirror as described above. [[mirror-where-official]] ==== I am an official mirror, what is the right site for me? In general the description in <> still applies. Of course you may want to put some weight on the fact that your upstream should be of a low tier. There are some other considerations about _official_ mirrors that are described in <>. [[mirror-where-master]] ==== I want to access the master sites! If you have good reasons and good prerequisites, you may want and get access to one of the master sites. Access to these sites is generally restricted, and there are special policies for access. If you are already an _official_ mirror, this certainly helps you getting access. In any other case make sure your country really needs another mirror. If it already has three or more, ask the "zone administrator" (mailto:hostmaster@CC.FreeBSD.org[hostmaster@CC.FreeBSD.org]) or http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[FreeBSD mirror sites mailing lists] first. Whoever helped you become, an _official_ should have helped you gain access to an appropriate upstream host, either one of the master sites or a suitable Tier-1 site. If not, you can send email to mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org] to request help with that. There is one master site for the FTP fileset. [[mirror-where-master-ftp]] ===== ftp-master.FreeBSD.org This is the master site for the FTP fileset. `ftp-master.FreeBSD.org` provides rsync access, in addition to FTP. Refer to <>. Mirrors are also encouraged to allow rsync access for the FTP contents, since they are __Tier-1__-mirrors. [[mirror-official]] == Official Mirrors Official mirrors are mirrors that * a) have a `FreeBSD.org` DNS entry (usually a CNAME). * b) are listed as an official mirror in the FreeBSD documentation (like handbook). So far to distinguish official mirrors. Official mirrors are not necessarily __Tier-1__-mirrors. However you probably will not find a __Tier-1__-mirror, that is not also official. [[mirror-official-requirements]] === Special Requirements for official (tier-1) mirrors It is not so easy to state requirements for all official mirrors, since the project is sort of tolerant here. It is more easy to say, what _official tier-1 mirrors_ are required to. All other official mirrors can consider this a big _should_. Tier-1 mirrors are required to: * carry the complete fileset * allow access to other mirror sites * provide ftp and rsync access Furthermore, admins should be subscribed to the http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[FreeBSD mirror sites mailing lists]. See link:{handbook}#eresources-mail[this link] for details, how to subscribe. [IMPORTANT] ==== It is _very_ important for a hub administrator, especially Tier-1 hub admins, to check the https://www.FreeBSD.org/releng/[release schedule] for the next FreeBSD release. This is important because it will tell you when the next release is scheduled to come out, and thus giving you time to prepare for the big spike of traffic which follows it. It is also important that hub administrators try to keep their mirrors as up-to-date as possible (again, even more crucial for Tier-1 mirrors). If Mirror1 does not update for a while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins a downward spiral... Keep your mirrors up to date! ==== [[mirror-official-become]] === How to become official then? We are not accepting any new mirrors at this time. [[mirror-statpages]] == Some statistics from mirror sites Here are links to the stat pages of your favorite mirrors (a.k.a. the only ones who feel like providing stats). [[mirror-statpagesftp]] === FTP site statistics * ftp.is.FreeBSD.org - mailto:hostmaster@is.FreeBSD.org[hostmaster@is.FreeBSD.org] - http://www.rhnet.is/status/draupnir/draupnir.html[ (Bandwidth)] http://www.rhnet.is/status/ftp/ftp-notendur.html[(FTP processes)] http://www.rhnet.is/status/ftp/http-notendur.html[(HTTP processes) ] * ftp2.ru.FreeBSD.org - mailto:mirror@macomnet.ru[mirror@macomnet.ru] - http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html[(Bandwidth)] http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html[(HTTP and FTP users)] diff --git a/documentation/content/zh-tw/articles/leap-seconds/_index.adoc b/documentation/content/zh-tw/articles/leap-seconds/_index.adoc index 7c06fbe94e..3ec5291688 100644 --- a/documentation/content/zh-tw/articles/leap-seconds/_index.adoc +++ b/documentation/content/zh-tw/articles/leap-seconds/_index.adoc @@ -1,79 +1,89 @@ --- title: FreeBSD 對潤秒的支援 releaseinfo: "$FreeBSD$" --- = FreeBSD 對潤秒的支援 :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] ''' toc::[] [[leapseconds-definition]] == 說明 __潤秒__是為了同步地球自轉，與原子鐘所做的特定一秒的修正。本文描述FreeBSD 如何處理潤秒。 本文寫作時，下一個潤秒會發生在2015年6月30日23:59:60 CST。下一次潤秒會發生在南北美洲和亞太地區的工作日。 潤秒是由 http://datacenter.iers.org/[IERS] 在 http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16[Bulletin C]所發表。 標準的潤秒行為描述在link:https://tools.ietf.org/html/rfc7164#section-3[RFC 7164].。也可見 man:time2posix[3]。 [[leapseconds-posix]] == FreeBSD預設的潤秒處理 最簡單的處理潤秒方法使用FreeBSD預設的 POSIX 時間規則，並使用 link:{handbook}#network-ntp[NTP]。如果 man:ntpd[8] 在執行，而且時間和上游正確處理潤秒的 NTP 伺服器同步，潤秒會使系統時間自動重複當天的最後一秒。不需要其他調整。 如果上游的 NTP 伺服器無法正確地處理潤秒，man:ntpd[8] 會在錯誤的上游伺服器發現錯誤並跳一秒後，跟著把時間跳一秒。 如果未使用 NTP ，將需要在潤秒過後，手動調整系統時鐘。 [[leapseconds-cautions]] == 警告 潤秒的插入在全世界是在同一個瞬間： UTC 午夜。在日本，是在上午九點，在太平洋，是正午，在美洲，是傍晚，在歐洲，是晚上。 我們相信和預期，如果提供正確和穩定的 NTP 服務，FreeBSD會如設計地在這次潤秒正確運作，就像在之前遇到潤秒時一樣。 然而我們要警告，實務上沒有應用程式曾經要求核心關於潤秒的事。我們的經驗是，如同設計，潤秒本質上是潤秒前一秒的重播，這對大部份應用程式設計師來說是意想不到的事。 其他作業系統或電腦可能會或可能不會像FreeBSD用同樣方法處理潤秒，沒有正確和穩定 NTP 服務的系統一點也不會知道潤秒的發生。 電腦因為潤秒而當機並不是沒有聽聞，經驗上也顯示，有大量公用的 NTP 伺服器沒有正確地處理和公告潤秒。 請試著確定不會因為潤秒而發生任何可怕的事情。 [[leapseconds-testing]] == 測試 測試是否有使用潤秒是有可能的。由於 NTP 的性質，測試可能要運作到潤秒前24小時。有些主要的參考時鐘來源只在潤秒前一個小時公告。詢問 NTP 行程： [source,shell] .... % ntpq -c 'rv 0 leap' .... 包含``leap_add_sec`` 的輸出指出對於潤秒的支援。潤秒前24小時，或是潤秒已經過了，會顯示``leap_none``。 [[leapseconds-conclusion]] == 結論 實務上，FreeBSD 的潤秒通常不是個問題。我們希望這篇概述能幫助釐清預期會遇到什麼狀況，如何使潤秒事件進行的更順利。 diff --git a/documentation/content/zh-tw/articles/mailing-list-faq/_index.adoc b/documentation/content/zh-tw/articles/mailing-list-faq/_index.adoc index dfe33f0c65..469ee37646 100644 --- a/documentation/content/zh-tw/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/zh-tw/articles/mailing-list-faq/_index.adoc @@ -1,169 +1,183 @@ --- title: FreeBSD Mailing Lists 常見問答集 authors: - author: The FreeBSD Documentation Project copyright: 2004-2006 FreeBSD 文件計畫 releaseinfo: "$FreeBSD$" --- = FreeBSD Mailing Lists 常見問答集 :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 這是有關 FreeBSD mailing lists 的 FAQ。如果您對協助本文件/翻譯計畫 的進行有興趣的話，請寄 e-mail 到 {freebsd-doc}。此外，隨時可從 link:.[FreeBSD 網站] 拿到這份文件的最新版本。 也可以利用 HTTP 來下載 link:.[HTML] 文件，或是經由 link:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/[FreeBSD FTP 站] 下載純文字、PostScript(R)、或 PDF 版本的檔案。 您也可以在這裡使用 link:https://www.FreeBSD.org/search/[搜尋 FAQ 資料] 的功能。 ''' toc::[] [[introduction]] == 前言 如同其他 FAQs 一樣，本文主要目的是希望涵蓋在 FreeBSD mailing lists 上面的常見問題(當然，包括答案)。 雖然，原本構想是希望能降低這些重複問題的網路流量，但如今已被公認 FAQs 也是相當好用的資源之一。 本文主要是描述社群之間所培養的一些禮儀(或默契)，但本文本身並非『聖旨』般的權威。 若發現本文內有任何技術瑕疵，或者是想建議可以增加哪些部分的話，請送 PR，或是 email 到 {freebsd-doc}。謝囉！ === FreeBSD mailing lists 的目的為何？ FreeBSD mailing lists 主要是提供 FreeBSD 社群間的溝通管道，這裡有各式專題領域的探討，以及興趣交流。 === FreeBSD mailing lists 的參與者有哪些? 這個問題，要看各個 list 的『版規(charter)』定位而有所不同。有些 lists 主要是 developers 在參與討論的； 而有些則主要是幾乎整體 FreeBSD 社群都可以隨意參與討論的。請看 http://lists.FreeBSD.org/mailman/listinfo[這份清單] 上面有目前所有 list 的摘要說明。 === FreeBSD mailing lists 對任何人都是開放參與的嗎？ 再重複一次，這要看各個 list 的『版規(charter)』定位而有所不同。 請在發文前，先注意閱讀該 list 的『版規(charter)』，並遵守相關原則。 如此一來，才會讓大家都能溝通更無礙。 如果看了上一個問答內的清單之後，還是不清楚要到哪個 list 去發問的話， 那麼可以試著把問題丟到 freebsd-questions 看看(但請先看下面講的補充)。 請注意：習慣上所有 mailing lists 都是開放發表討論的，也不必得先成為訂閱會員才行。 這是相當審慎的選擇，來讓參與 FreeBSD 社群更輕鬆容易，並鼓勵互相分享彼此的想法。 然而，由於過去有些人的濫用，有些 lists 現在開始限制參與討論的部分，以避免不必要的困擾。 === 要怎麼訂閱呢？ 可以用 http://lists.FreeBSD.org/mailman/listinfo[Mailman 網頁介面] 來訂閱任何公開的 lists。 === 要怎麼退訂？ 一樣請用剛上面說的網頁介面，或者 mailing list 上面每封信結尾處都會有相關 URL 連結的指示說明。 千萬請不要直接寫信到這些公開的 mailing lists 說你要退訂。 首先呢..因為本來就不是這樣退訂的，其次你會惹來眾怒而招來圍剿、筆戰。 這是很典型的退訂錯誤示範，請不要這樣做。 === 可以找到舊信的資料庫嗎？ 嗯，有！可以在 http://docs.FreeBSD.org/mail/[這邊] 找到相關的舊信資料庫(archive)。 === mailing lists 可有摘要版呢？ 當然也有，請看 http://lists.FreeBSD.org/mailman/listinfo[Mailman 網頁介面]。 [[etiquette]] == Mailing List 的參與禮儀 在 mailing lists 上參與討論，就像在其他社群一樣，我們都需要一些溝通上的共識。 發言請注重禮儀(或默契)，切勿無的放矢。 === 在發文之前，有什麼注意事項呢？ 最重要的是你已經看了這篇文章，然而，若您對 FreeBSD 不熟的話， 可能需要先廣泛閱讀 link:https://www.FreeBSD.org/docs/books/[相關書籍及文章] 來先熟悉這套作業系統和一些典故，尤其是其中的 link:{faq}[FreeBSD 常見問答集 (FAQ)] 文件，link:{handbook}[FreeBSD 使用手冊(Handbook)]，以及相關文章：link:{freebsd-questions-article}[How to get best results from the FreeBSD-questions mailing list]、link:{explaining-bsd}[Explaining BSD]、以及 link:{new-users}[FreeBSD First Steps]。 此外，對上述文件內已有解答的部份又提出來問的話，會被認為是相當不禮貌的。 這並不是因為這群志工是相當吝於回答的，而是一再被相同的問題不斷疲勞轟炸之後，所產生的挫折感很重。 尤其是現成答案明明就在眼前，卻仍同樣問題滿天飛，這實在是...。 請注意：這些 FreeBSD 相關文件幾乎都是由一群無薪志工的好心成果，而他們也是人。 === 如何避免不當發文呢？ * 發文時，請務必遵守該 mailing list 的遊戲規則。 * 不要作人身攻擊。好的網路公民，應該要有更高的言行標準。 * 請不要試圖作 Spam 行為(廣告、轉貼多處等不請自來行為)。 所有 mailing lists 都會積極禁止這些違規者，一旦有的話，那麼後果請自行負責。 === 發文時，有什麼該注意的嗎？ * 發文時，請保持一行約 75 個字元就自動斷行，因為並不是每個看的人都有很炫的圖形介面(GUI)看信軟體。 * 請注意：事實上，網路頻寬並不是無限的。 並非每個讀者的頻寬都很大，所以若想貼一些像是 [.filename]#config.log# 之類的設定檔內容，或是大量的 stack trace 紀錄，那麼請把它放在自己網站上，然後貼出該網址 URL 就行了。 還有一件事，請記住，這些信件都會被舊信資料庫保存下來，所以這樣作會造成保存的資料庫會很快被塞到很大， 甚至可能塞爆 Server 的硬碟空間。 * 文章是要讓人看得懂，所以請注意版面編排的可讀性，還有.. 千　萬　不　要　大　聲　嚷　叫!!!!! 這點可不只 FreeBSD mailing lists 才需如此注意， 請勿低估文章『基本編排』的重要性、連鎖效應。 信中的表達方式通常就代表著別人眼中的你，若文章讓人看了很吃力(霧煞煞)、拼字錯誤百出、 充滿語意或邏輯錯誤、或是文內充滿一堆驚嘆號，這會讓人對你印象觀感極差。 * 在一些特定的 list 場合，請用適當的語言來溝通。許多非英語系的mailing lists 可以到 link:https://www.FreeBSD.org/community/mailinglists/[ 這邊] 查看看。 + 對於許多母語不是英語的人，我們都能諒解他們的苦楚，並且試著儘量多多包涵。 英文非母語的人，我們會儘量不惡意批評拼字或文法錯誤之處。 FreeBSD 在這方面，一直有相當優秀的紀錄，請讓我們繼續保持這傳統吧。 * 寫信時，請用相容標準的 Mail User Agent (MUA)程式。 http://www.lemis.com/email.html[不良的(或設定錯誤的)寄信程式] 這裡列有許多信件格式的錯誤示範。以下是一些已知的寄信程式的不良示範： ** cc:Mail ** (舊版的)Eudora(R) ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Internet Mail ** Microsoft(R) Outlook(R) ** (舊版的) Netscape(R) + 如同上述所見，Microsoft 出的一堆寄信程式通常都是不相容標準格式的。 請儘量改用 UNIX(R) 上的寄信程式。若必須在 Microsoft 環境下使用寄信程式的話， 請記得確認設定是否正確。請儘量不要用 MIME 格式： 因為有一堆人都在濫用 MIME 信件格式。 * 請確認：時間與時區設定是否正確。 這問題看起來有點蠢，因為你寄出的信還是會到達 mailing list 上， 但是呢，每位 mailing lists 上的訂戶每天都會看數百封的信， 他們通常會把信件以標題跟時間作為排序依據。 若你的信沒有在第一篇正解之前就先出現的話，他們就會假設可能是漏收你這封信， 然後就沒再去看你那封信了。 * 請提供程式出現的相關訊息，像是 man:dmesg[8] 或者 console messages 也就是通常會出現在 [.filename]#/var/log/messages# 出現的。 請不要用手打，因為這不僅很苦，而且也可能打錯字或亂掉原有格式。請直接把相關的 log 檔丟出來， 或是用編輯器來剪裁、或是用滑鼠複製/貼上來完成。舉個例子，如果是要把像是 `dmesg` 的程式訊息倒入到某個檔案去的話，那麼作法如下： + [source,shell] .... % dmesg > /tmp/dmesg.out .... + 這樣子會把訊息送到 [.filename]#/tmp/dmesg.out# 檔內。 * 在用滑鼠剪貼時，請注意是否有犯一些細節的剪貼壞習慣。 尤其是像貼 [.filename]#Makefiles# 之類檔案時，由於 `tab` 鍵所打出來的分格，是屬於特殊字元。因此，在 link:https://www.FreeBSD.org/support/#gnats[GNATS PR 資料庫] 上很常看到這類很常見的惱人問題：[.filename]+Makefiles+ 內的 tab 經過剪貼後，變成『空白(white space)』 或是困擾的 `=3B` escape sequence，這些會讓 committers 們十分不爽。 === 在 mailing lists 上回文的話，有什麼要特別注意的嗎？ * 請適當調整文章引言長度。回文時，引言部份請引『有談到的』部分為主，但請不要過與不及。 應該保留涉及討論範圍的原文，這樣子才能讓沒看過前面文章的人知道是在講什麼，而非一頭霧水。 + 還有一點也很重要，原文若是幅度相當長的話，記得註明 "yes, I see this too"。 * 善用技巧來確認原文與自己寫的部份： 通常會在原文的每行前面加上 `">"` 以作記號。 請記得保留 `">"` 符號後面的空白，並且在原文以及你所寫的段落之間加上空行， 以便閱讀。 * 請不要斷章取義、穿鑿附會：通常對原始文章『斷章取義』、『穿鑿附會』會讓大家很不爽，因為他們原意並非如此，卻被曲解。 * 回文時，不要寫在原文上面(`top post`)。 這個意思是：若要回文時，請寫在原文下方，不要寫在原文上面，以免讓人有時空錯置的錯亂混淆。 + ** 答： Because it reverses the logical flow of conversation. ** 問： Why is top posting frowned upon? + (感謝 Randy Bush 提供笑話) [[recurring]] == Mailing Lists 上的重複性問題 在 mailing lists 上參與討論，就像在其他社群一樣，我們都需要一些溝通上的共識。 許多 mailing lists 都會假設參與討論者都大致知道 FreeBSD 計劃的一些歷史淵源。 尤其是社群的新手總是定期會不斷重複問類似問題。 每個發文的人，都有責任來避免掉入這樣的惡性循環輪迴內。 因此，應儘可能讓 mailing list 上能正常討論，而避免讓自己陷入筆戰泥沼。 要怎麼避免呢？最好的方法就是善用這些 http://docs.FreeBSD.org/mail/[mailing list 舊信資料庫(archives)]，來瞭解相關背景。 正由於這原因，所以 http://www.FreeBSD.org/search/#mailinglists[mailing list 搜尋介面] 就顯得非常好用。 (若這方法仍無法找到有用的答案，那麼請改用自己愛用的搜尋引擎吧) 透過這些舊信資料庫，不只可瞭解先前討論過哪些話題，也可以知道：是怎麼討論的、 哪些人參與討論過、主要看的人又是哪些人。 入境隨俗這些原則不只是 FreeBSD mailing list 上才這樣，一樣可以適合其他地方。 archives 的內容無疑地相當廣泛，而且會有些問題不斷反覆出現， 有時討論到後面總會離題。無論如何，在發問前的義務就是先做好功課， 以避免這類的月經文惡性循環，尤其是令人反感的 `bikeshed（打嘴砲)`。 [[bikeshed]] == 什麼是 "Bikeshed" 呀？ 單就字面上意思解釋的話，`bikeshed` 是指專門給腳踏車、機車之類的兩輪交通工具使用的遮雨棚， 然而呢，在 FreeBSD 這邊的說法卻有其他意思(帶有貶抑)指的是： 某些特定話題的重複討論，尤其是指在 FreeBSD 社群內絕不會有共識，且有爭議的話題。 (這字彙的起源在 link:{faq}#BIKESHED-PAINTING[這份文件] 內有更多說明)。你只要在發信到任一 FreeBSD mailing lists 之前，知道這個基本概念就行了。 一般來講，『bikeshed』是很容易產生許多波的筆戰與額外討論的爭議話題，如果事先不知道這些背景的話。 拜託，請幫個忙讓討論回歸正常，而不要只是到處打嘴砲而已。感恩！ [[acknowledgments]] == 致謝 `{grog}`:: link:{freebsd-questions-article}[How to get best results from the FreeBSD-questions mailing list] 一文的原作者， 我們從他這文內獲得許多 mailing list 上的禮儀(或默契)寫作題材。 `{linimon}`:: 本 FAQ 雛形的原作 diff --git a/documentation/content/zh-tw/articles/nanobsd/_index.adoc b/documentation/content/zh-tw/articles/nanobsd/_index.adoc index c8cabd72de..3315fa790b 100644 --- a/documentation/content/zh-tw/articles/nanobsd/_index.adoc +++ b/documentation/content/zh-tw/articles/nanobsd/_index.adoc @@ -1,288 +1,298 @@ --- title: NanoBSD 簡介 authors: - author: Daniel Gerzo copyright: 2006 The FreeBSD Documentation Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = NanoBSD 簡介 :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +endif::[] [.abstract-title] 摘要 這篇文件提供了關於 NanoBSD 工具的情報介紹， 這工具可用來建立用於嵌入式環境應用程式的 FreeBSD 系統映像檔， 以便存放到 Compact Flash 卡(或隨身碟)。 ''' toc::[] [[intro]] == NanoBSD 簡介 NanoBSD 是 {phk-name} 目前正在開發的一項工具。 它可用來建立用於嵌入式環境應用程式的 FreeBSD 系統映像檔， 以便存放到 Compact Flash 卡(或隨身碟，mass storage medium)。 這一工具也可以用來自製安裝映像檔， 以簡化俗稱為 "嵌入式系統(computer appliances)" 的系統安裝、維護工作。 通常，每個嵌入式系統產品都有限定硬體和軟體， 或者換言之，所有的應用程式都是預先裝好的。 這些設備可以直接放到現有的網路中，而且(幾乎是)立即使用。 NanoBSD 提供的功能包括： * 可以和 FreeBSD 一樣使用 Ports 和 Packages - 所有的應用程序都可以在 NanoBSD 中直接使用， 而方式與 FreeBSD 完全一樣。 * 功能絲毫未損 - 在 FreeBSD 做的任何工作，都可以在 NanoBSD 中使用， 除非您在建立 NanoBSD 映像檔時， 有指定要拿掉它們。 * 所有東西在運行時都是唯讀的 - 可以安全地拔掉電源插頭。 系統不正常關機的話，不用再跑 man:fsck[8] 了。 * 可輕鬆編譯、自行打造 - 只需使用一個 shell script 和一個設定檔， 您可以輕鬆依需求來量身訂做適用的映像檔。 [[howto]] == 如何使用 NanoBSD [[design]] === NanoBSD 的設計 一旦將映像檔存入嵌入式硬體，就可以用它來引導 NanoBSD 了。 預設情況下，隨身碟會劃分為三部分： * 兩個映像檔分割區： `code#1` 和 `code#2`。 * 一個設定檔分割區，在運行環境中， 可以將其掛載(mount)到 [.filename]#/cfg# 目錄下。 這些分割區，在預設情況下是以唯讀方式掛載。 [.filename]#/etc# 和 [.filename]#/var# 目錄均為 man:md[4](malloc)磁碟。 設定檔的分割區則是在 [.filename]#/cfg# 目錄。 它包含了用於 [.filename]#/etc# 目錄的檔案，在啟動之後暫時以唯讀方式掛載。 因此，若想要重開機保留新的設定， 那麼要記得從 [.filename]#/etc# 把改過的檔案複製回 [.filename]#/cfg# 目錄才行。 .把修改過 [.filename]#/etc/resolv.conf# 設定保存起來 [example] ==== [source,shell] .... # vi /etc/resolv.conf [...] # mount /cfg # cp /etc/resolv.conf /cfg # umount /cfg .... ==== [NOTE] ==== 只有在系統啟動過程中，以及需要修改設定檔的時候，才需要掛載含有 [.filename]#/cfg# 的那個分割區。 一直都掛載 [.filename]#/cfg# 不是一個好主意，特別是當您把 NanoBSD 放在不適合進行大量寫入動作的分割區時 (比如：由於檔案系統的同步化會定期在系統碟內寫入資料)。 ==== === 打造 NanoBSD 映像檔 NanoBSD 映像檔是透過使用非常簡單的 [.filename]#nanobsd.sh# shell script 來打造的，這個 script 可以在 [.filename]#/usr/src/tools/tools/nanobsd# 目錄中找到。 這個 script 建立的映像檔，可以用 man:dd[1] 工具來複製到隨身碟上。 打造 NanoBSD 映像檔所需的指令是： [source,shell] .... # cd /usr/src/tools/tools/nanobsd <.> # sh nanobsd.sh <.> # cd /usr/obj/nanobsd.full <.> # dd if=_.disk.full of=/dev/da0 bs=64k <.> .... <.> 進入 NanoBSD 打造 script 的主目錄。 <.> 開始打造過程。 <.> 進入打造好的映像檔所在的目錄。 <.> 在隨身碟上安裝 NanoBSD。 === 自行打造 NanoBSD 映像檔 這可能是 NanoBSD 最為重要， 同時也是您最感興趣的功能。 同時，在開發 NanoBSD 應用程式時，這也是相當耗時的過程。 執行下面的指令將會 [.filename]#nanobsd.sh# 讀取目前所在目錄的 [.filename]#myconf.nano# 檔的設定： [source,shell] .... # sh nanobsd.sh -c myconf.nano .... 自行打造的流程，只需兩個步驟： * 自訂選項 * 自訂功能 ==== 自訂選項 透過修改設定，可以設定用於 NanoBSD 打造過程中 `buildworld` 和 `installworld` 階段的編譯、安裝選項，以及 NanoBSD 主要打造過程中的選項。 透過使用這些選項可以削減系統的尺寸，使之能夠放入 64 MB 的隨身碟。 您還可以進一步透過這些選項來削減 FreeBSD， 直到它只包含 kernel 以及兩三個 userland 檔案為止。 設定檔案中包含用以代替預設值的設定選項。簡介最重要的幾項設定如下： * `NANO_NAME` - 本次打造的名稱(所建立工作目錄的名稱)。 * `NANO_SRC` - 用以編譯、打造映像檔的 source tree 的位置。 * `NANO_KERNEL` - 設定用來編譯的 kernel 設定檔檔名。 * `CONF_BUILD` - 用於 `buildworld` 打造階段的選項。 * `CONF_INSTALL` - 用於 `installworld` 打造階段的選項。 * `CONF_WORLD` - 用於 `buildworld` 和 `installworld` 這兩個打造階段的選項。 * `FlashDevice` - 定義所用的嵌入式硬體類型。 詳情請參考 [.filename]#FlashDevice.sub# 檔。 ==== 自訂功能 透過在設定檔案中使用 shell 函數，可以進一步微調 NanoBSD。 舉例說明一下自行打造函數的基本方式： [.programlisting] .... cust_foo()( echo "bar=topless" > \ ${NANO_WORLDDIR}/etc/foo ) customize_cmd cust_foo .... 下面舉更實際點的例子，它會把預設的 [.filename]#/etc# 目錄大小，從 5MB 調整為 30MB： [.programlisting] .... cust_etc_size()( cd ${NANO_WORLDDIR}/conf echo 30000 > default/etc/md_size ) customize_cmd cust_etc_size .... 除此之外，還有幾個預設的功能定義可以用來自訂： * `cust_comconsole` - 在預設 VGA 顯示卡上停用 man:getty[8] ([.filename]#/dev/ttyv*#)並啟用 serial port 的 COM1 以作為系統 console。 * `cust_allow_ssh_root` - 允許 man:sshd[8] 可以用 `root` 帳號登入。 * `cust_install_files` - 從 [.filename]#nanobsd/Files# 目錄中安裝檔案，這包含一些實用的系統管理 script 。 ==== 設定檔案舉例 下面是用於自行打造的 NanoBSD 映像檔的完整例子： [.programlisting] .... NANO_NAME=custom NANO_SRC=/usr/src NANO_KERNEL=MYKERNEL NANO_IMAGES=2 CONF_BUILD=' NO_KLDLOAD=YES NO_NETGRAPH=YES NO_PAM=YES ' CONF_INSTALL=' NO_ACPI=YES NO_BLUETOOTH=YES NO_CVS=YES NO_FORTRAN=YES NO_HTML=YES NO_LPR=YES NO_MAN=YES NO_SENDMAIL=YES NO_SHAREDOCS=YES NO_EXAMPLES=YES NO_INSTALLLIB=YES NO_CALENDAR=YES NO_MISC=YES NO_SHARE=YES ' CONF_WORLD=' NO_BIND=YES NO_MODULES=YES NO_KERBEROS=YES NO_GAMES=YES NO_RESCUE=YES NO_LOCALES=YES NO_SYSCONS=YES NO_INFO=YES ' FlashDevice SanDisk 1G cust_nobeastie()( touch ${NANO_WORLDDIR}/boot/loader.conf echo "beastie_disable=\"YES\"" >> ${NANO_WORLDDIR}/boot/loader.conf ) customize_cmd cust_comconsole customize_cmd cust_install_files customize_cmd cust_allow_ssh_root customize_cmd cust_nobeastie .... === 更新 NanoBSD 更新 NanoBSD 相對 FreeBSD 而言較為簡單： [.procedure] . 和之前一樣打造新的 NanoBSD 映像檔。 . 將新的映像檔放入正運行的 NanoBSD 中未用的分割區之一。 + 與之前最初安裝 NanoBSD 的步驟相比， 這一步驟最重要的區別在於：這次不用 [.filename]#\_.disk.full# 檔(它包含整個磁碟的映像檔)， 而應安裝 [.filename]#_.disk.image# 映像檔(這個檔案中，只包含一個系統分割區)。 . 重新啟動，並從新安裝的分割區中啟動系統。 . 如果一切順利的話，升級工作就完成了。 . 如果發生了任何問題，則可以從先前的分割區啟動 (其中包含了舊的、 可用的映像檔)，來盡快恢復系統功能。 接下來可以修正新編譯的版本中存在的問題，並重複前述步驟。 要在正在運行的 NanoBSD 系統中安裝新的映像檔，可以使用位於 [.filename]#/root# 目錄的 [.filename]#updatep1# 或 [.filename]#updatep2# script ， 實際上要用哪一個 script，則取決於正在運行的系統是位於哪個分割區而定。 隨時提供新 NanoBSD 映像檔所提供的服務， 以及採用的傳輸方法的不同，您可以參考並使用下列三種方式之一： ==== 使用 man:ftp[1] 如果傳輸速度是第一要求的話，請採用下面例子： [source,shell] .... # ftp myhost get _.disk.image "| sh updatep1" .... ==== 使用 man:ssh[1] 如果想更安全的話，應參考下面例子： [source,shell] .... # ssh myhost cat _.disk.image.gz | zcat | sh updatep1 .... ==== 使用 man:nc[1] 如果遠程主機既不提供 man:ftp[1] 服務，也不提供 man:sshd[8] 服務的話： [.procedure] . 首先，在提供映像檔的主機上開啟 TCP listen，並讓它把映像檔傳給 client： + [source,shell] .... myhost# nc -l 2222 < _.disk.image .... + [NOTE] ==== 請確認您所使用的 port 沒有被防火牆阻止來自 NanoBSD client 的連線請求。 ==== . 連到提供新映像檔服務的主機，並執行 [.filename]#updatep1# 這支 script： + [source,shell] .... # nc myhost 2222 | sh updatep1 .... diff --git a/documentation/content/zh-tw/articles/pr-guidelines/_index.adoc b/documentation/content/zh-tw/articles/pr-guidelines/_index.adoc index a29acf5349..203fa06a0e 100644 --- a/documentation/content/zh-tw/articles/pr-guidelines/_index.adoc +++ b/documentation/content/zh-tw/articles/pr-guidelines/_index.adoc @@ -1,455 +1,467 @@ --- title: 問題回報(PR)的處理原則 authors: - author: Dag-Erling Smørgrav - author: Hiten Pandya releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "opengroup", "general"] --- = 問題回報(PR)的處理原則 :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 這篇文章主要在講：由 FreeBSD PR 維護小組所提出的一些 FreeBSD 問題回報(PR) 建議，希望大家在弄 PR 時都能遵守。 ''' toc::[] [[intro]] == 前言 GNATS 是 FReeBSD 計劃所採用的一套專門管理錯誤(回報bug) 系統。 由於對 FreeBSD 品質保證而言，是否能準確掌握各項錯誤回報與進度是十分重要的， 因此，如何正確有效使用 GNATS 也就必須注意。 Access to GNATS is available to FreeBSD developers, as well as to the wider community. 為了讓 GNATS 資料庫使用上儘量一致，於是就產生了怎麼處理像是：followup(回文)、關閉PR等的參考原則。 [[pr-lifecycle]] == 問題回報(PR)的生命週期 * 首先，回報者(originator)以 man:send-pr[1] 送出 PR，然後會收到一封確認信。 * 然後，committer 們就會有人(假設叫做 Joe)發掘有興趣的 PR 並將該 PR 指派給自己來處理。 或者 bugbuster 會有人(假設叫做 Jane) 就會下決定：她覺得 Joe 比較適合處理，就將該 PR 指派(assign)給他 * Joe 會先與有問題的回報者作些意見交流(以確定這問題有進入 audit 追蹤流程內) 以及判斷問題點。 然後再確定問題點有寫入 audit 追蹤流程之後，然後把該 PR 狀態設為 "analyzed(已分析)"。 * Joe 開始徹夜找出問題解法，然後將 patch 送到 follow-up(回文用)，並請回報者協助測試是否正常。 然後，他就會將 PR 狀態設為 "feedback" 囉。 * 如此重複 analyzed、feedback 幾趟之後，直到 Joe 與回報者雙方都相當滿意 patch 結果， 於是就會將 patch 給 commits 進入 `-CURRENT` (或者若 `-CURRENT` 上面沒這問題的話，就直接送到 `-STABLE`)，在 commit log 內要把相關 PR 寫上去 (同時回報者若有送完整或部分 patch 的話，就順便記載)，然後，若沒什麼事的話，就開始準備 MFC 哩。 (譯註：MFC意指 Merged From CURRENT ，也就是把 `-CURRENT` 上的東西併入 `-STABLE`。 * 若該 patch 不需要 MFC 的話，Joe 就會關掉(close)該 PR 了。 * 若該 patch 需要 MFC 的話，Joe 會把 PR 狀態改為 "patched(已修正)"， 直到已經 MFC 完畢，才會 close(關掉)。 [NOTE] ==== 很多送出來的 PR 都很少附上問題的相關訊息，而有些則是相當複雜難搞， 或只是提到部分表面問題而已； 遇到這種情況時，是非常需要得到所有相關訊息以便解決問題。 若遇到這種無解的問題或再次發生的話，就必須要 re-open(重新開啟) 該 PR，以待解決。 ==== [NOTE] ==== PR 上所附的 "email address" 可能因某些原因而無法收信時，遇到這種狀況，通常就是 followup 該 PR ，並(在 followup 時)請回報者重新提供可正常收信的 email address。 當系統上的 mail 系統關閉或沒裝的時候，這通常是在使用 man:send-pr[1] 的替代方案。 ==== [[pr-states]] == 問題回報(PR)的狀態 若 PR 有任何變化的話，請務必記得更新 PR 的『狀態(state)』。 『狀態』應該要能正確反映該 PR 的目前進度才是。 .以下是更改 PR 狀態的小例子： [example] ==== 當有可以修正問題的 PR 出現，而相關負責的 developer(s) 也覺得這樣的修正可以接受，他們會 followup 該 PR，並將其狀態改為 "feedback"。同時，回報者應重新評估最終的修正結果，並回應：所回報的錯誤是否已成功修正。 ==== 每份 PR 通常會有下面這幾種狀態之一： [.glosslist] open:: PR 最初的狀態：這個問題被提出來，並在等待處理中。 analyzed:: 已經開始處理這問題，並且有找到疑似解決的方法。 feedback:: 需要回報者提供更詳細的相關資料，正如教學要因材施教，治病也要因人下藥，越多相關訊息，才能有最佳效果。 patched:: 已經送相關 patch 了，但仍因某些原因(MFC，或來自回報者的確認結果異常)因此尚未完畢。 suspended(暫緩):: 因為沒附上相關訊息或參考資料，所以還沒辦法處理這問題。 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 suspended for wish-list items that entail a significant amount of work which no one currently has time for. closed:: A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned. [NOTE] ==== The "patched" state is directly related to feedback, so you may go directly to "closed" state if the originator cannot test the patch, and it works in your own testing. ==== [[pr-types]] == 問題回報(PR)的種類 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. * <> * <> * <> * <> * <> 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. [[pr-unassigned]] == Unassigned PRs When PRs arrive, they are initially assigned to a generic (placeholder) assignee. These are always prepended with `freebsd-`. The exact value for this default depends on the category; in most cases, it corresponds to a specific FreeBSD mailing list. Here is the current list, with the most common ones listed first: [[default-assignees-common]] .Default Assignees - most common [cols="1,1,1", options="header"] |=== | Type | Categories | Default Assignee |base system |bin, conf, gnu, kern, misc |freebsd-bugs |architecture-specific |alpha, i386, ia64, powerpc, sparc64 |freebsd-_arch_ |ports collection |ports |freebsd-ports-bugs |documentation shipped with the system |docs |freebsd-doc |FreeBSD web pages (not including docs) |www |freebsd-www |=== [[default-assignees-other]] .Default Assignees - other [cols="1,1,1", options="header"] |=== | Type | Categories | Default Assignee |advocacy efforts |advocacy |freebsd-advocacy |Java Virtual Machine(TM) problems |java |freebsd-java |standards compliance |standards |freebsd-standards |threading libraries |threads |freebsd-threads |man:usb[4] subsystem |usb |freebsd-usb |=== 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 FreeBSD, and thus be more appropriate for `kern`. The converse is also true, of course.) 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., `freebsd-foo` instead of `foo`); this will avoid duplicate emails sent to the mailing list. [NOTE] ==== Here is a sample list of such entities; it is probably not complete. In some cases, entries that have the short form are __aliases__, not mailing lists. ==== [[common-assignees-base]] .Common Assignees - base system [cols="1,1,1", options="header"] |=== | Type | Suggested Category | Suggested Assignee |problem specific to the ARM(R) architecture |kern |freebsd-arm |problem specific to the MIPS(R) architecture |kern |freebsd-mips |problem specific to the PowerPC(R) architecture |kern |freebsd-ppc |problem with Advanced Configuration and Power Management (man:acpi[4]) |kern |freebsd-acpi |problem with Asynchronous Transfer Mode (ATM) drivers |kern |freebsd-atm |problem with FireWire(R) drivers |kern |freebsd-firewire |problem with the filesystem code |kern |freebsd-fs |problem with the man:geom[4] subsystem |kern |freebsd-geom |problem with the man:ipfw[4] subsystem |kern |freebsd-ipfw |problem with Integrated Services Digital Network (ISDN) drivers |kern |freebsd-isdn |problem with Linux(R) or SVR4 emulation |kern |freebsd-emulation |problem with the networking stack |kern |freebsd-net |problem with PicoBSD |kern |freebsd-small |problem with the man:pf[4] subsystem |kern |freebsd-pf |problem with the man:scsi[4] subsystem |kern |freebsd-scsi |problem with the man:sound[4] subsystem |kern |freebsd-multimedia |problem with man:sysinstall[8] |bin |freebsd-qa |problem with the system startup scripts (man:rc[8]) |kern |freebsd-rc |=== [[common-assignees-ports]] .Common Assignees - Ports Collection [cols="1,1,1", options="header"] |=== | Type | Suggested Category | Suggested Assignee |problem with the ports framework (__not__ with an individual port!) |ports |portmgr |port which is maintained by apache@FreeBSD.org |ports |apache |port which is maintained by eclipse@FreeBSD.org |ports |freebsd-eclipse |port which is maintained by gnome@FreeBSD.org |ports |gnome |port which is maintained by haskell@FreeBSD.org |ports |haskell |port which is maintained by java@FreeBSD.org |ports |freebsd-java |port which is maintained by kde@FreeBSD.org |ports |kde |port which is maintained by openoffice@FreeBSD.org |ports |freebsd-openoffice |port which is maintained by perl@FreeBSD.org |ports |perl |port which is maintained by python@FreeBSD.org |ports |freebsd-python |port which is maintained by x11@FreeBSD.org |ports |freebsd-x11 |=== Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.) 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. [[pr-assigned]] == Assigned PRs If a PR has the `responsible` 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. 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. [[pr-dups]] == 重複的 PR 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). [[pr-stale]] == Stale PRs 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: * If the PR contains sufficient detail, try to reproduce the problem in `-CURRENT` and `-STABLE`. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to "analyzed" if appropriate. * 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 "User error" or "Configuration error". * If the PR describes an error which you know has been corrected in both `-CURRENT` and `-STABLE`, close it with a message stating when it was fixed in each branch. * If the PR describes an error which you know has been corrected in `-CURRENT`, but not in `-STABLE`, 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 "feedback" and assign it to whomever will do the MFC. * 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 "Feedback timeout". [[pr-misfiled]] == Misfiled PRs GNATS is picky about the format of a submitted bug report. This is why a lot of PRs end up being "misfiled" 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. When GNATS cannot deduce what to do with a problem report that reaches the database, it sets the responsible of the PR to `gnats-admin` and files it under the `pending` category. This is now a "misfiled" 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 `query-pr` to view a listing of PRs that have been misfiled: [source,shell] .... % query-pr -x -q -r gnats-admin 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 .... Commonly PRs like the ones shown above are misfiled for one of the following reasons: * A followup to an existing PR, sent through email, has the wrong format on its `Subject:` header. * 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.) * When completing the man:send-pr[1] template, the submitter forgot to set the category or class of the PR to a proper value. * When completing the man:send-pr[1] template, the submitter set Confidential to `yes`. (Since we allow anyone to mirror GNATS via CVSup, our PRs are public information. Security alerts should therefore not be sent via GNATS but instead via email to the Security Team.) * It is not a real PR, but some random message sent to mailto:bug-followup@FreeBSD.org[bug-followup@FreeBSD.org] or mailto:freebsd-gnats-submit@FreeBSD.org[freebsd-gnats-submit@FreeBSD.org]. [[pr-misfiled-followups]] == Followups misfiled as new PRs 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 "listens" to for incoming messages, the subject of the reply should always be of the form: [.programlisting] .... Subject: Re: category/number: old synopsis text .... Most mailers will add the "`Re:`" part when you reply to the original mail message of a PR. The "`category/number:`" part is a GNATS-specific convention that you have to manually insert to the subject of your followup reports. 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 {bugfollowup}). Then the misfiled PR can be closed with a message similar to: [.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 .... Searching with `query-pr` for the original PR, of which a misfiled followup is a reply, is as easy as running: [source,shell] .... % query-pr -q -y "some text" .... After you locate the original PR and the misfiled followups, use the `-F` option of `query-pr` to save the full text of all the relevant PRs in a UNIX(R) mailbox file, i.e.: [source,shell] .... % query-pr -F 52458 52474 > mbox .... Now you can use any mail user agent to view all the PRs you saved in [.filename]#mbox#. Copy the text of all the misfiled PRs in a followup to the original PR and make sure you include the proper `Subject:` 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 "closed". Make sure you provide enough details in the log about the reason of this state change. Typically something like the following is ok: [.programlisting] .... Followup to ports/45364 misfiled as a new PR. This was misfiled because the subject did not have the format: Re: ports/45364: ... .... This way the submitter of the misfiled PR will know what to avoid the next time a followup to an existing PR is sent. [[pr-misfiled-format]] == PRs misfiled because of missing fields 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. Missing or bogus "category" or "class" 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. Another common cause of misfiled PRs because of formatting issues is quoting, changes or removal of the `send-pr` 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 `edit-pr` 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. [[pr-misfiled-notpr]] == Misfiled PRs that are not really problem reports 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 mailto:freebsd-gnats-submit@FreeBSD.org[freebsd-gnats-submit@FreeBSD.org] have to follow the template of `send-pr`, but email reports can be sent to {freebsd-bugs}. Developers that come across PRs that look like they should have been posted to {freebsd-bugs} 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. 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 "pending" 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. Currently, with the installation of some antispam filters that check all submissions to the GNATS database, the amount of spam that reaches the "pending" state is very small. 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: * Set Category to `junk`. * Set Confidential to `no`. * Set Responsible to yourself (and not, e.g., `freebsd-bugs`, which merely sends more mail). * Set State to `closed`. 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 CVSup. [[references]] == 延伸閱讀 下面這是在寫、處理 PR 時，可以參考的資料。當然很明顯，這份清單仍須補充。 * link:{problem-reports}[How to Write FreeBSD Problem Reports]-給 PR 回報者用的參考原則。 diff --git a/documentation/content/zh-tw/articles/problem-reports/_index.adoc b/documentation/content/zh-tw/articles/problem-reports/_index.adoc index e559de5456..e3f264be10 100644 --- a/documentation/content/zh-tw/articles/problem-reports/_index.adoc +++ b/documentation/content/zh-tw/articles/problem-reports/_index.adoc @@ -1,326 +1,340 @@ --- title: Writing FreeBSD Problem Reports authors: - author: Dag-Erling Smørgrav - author: Mark Linimon releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "cvsup", "ibm", "intel", "sparc", "sun", "general"] --- = Writing FreeBSD Problem Reports :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/en/teams.adoc[] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/zh-tw/mailing-lists.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 This article describes how to best formulate and submit a problem report to the FreeBSD Project. ''' toc::[] [[pr-intro]] == Introduction One of the most frustrating experiences one can have as a software user is to submit a problem report only to have it summarily closed with a terse and unhelpful explanation like "not a bug" or "bogus PR". Similarly, one of the most frustrating experiences as a software developer is to be flooded with problem reports that are not really problem reports but requests for support, or that contain little or no information about what the problem is and how to reproduce it. This document attempts to describe how to write good problem reports. What, you ask, is a good problem report? Well, to go straight to the bottom line, a good problem report is one that can be analyzed and dealt with swiftly, to the mutual satisfaction of both user and developer. Although the primary focus of this article is on FreeBSD problem reports, most of it should apply quite well to other software projects. Note that this article is organized thematically, not chronologically, so you should read through the entire document before submitting a problem report, rather than treat it as a step-by-step tutorial. [[pr-when]] == When to submit a problem report There are many types of problems, and not all of them should engender a problem report. Of course, nobody is perfect, and there will be times when you are convinced you have found a bug in a program when in fact you have misunderstood the syntax for a command or made a typographical error in a configuration file (though that in itself may sometimes be indicative of poor documentation or poor error handling in the application). There are still many cases where submitting a problem report is clearly _not_ the right course of action, and will only serve to frustrate you and the developers. Conversely, there are cases where it might be appropriate to submit a problem report about something else than a bug-an enhancement or a feature request, for instance. So how do you determine what is a bug and what is not? As a simple rule of thumb your problem is _not_ a bug if it can be expressed as a question (usually of the form "How do I do X?" or "Where can I find Y?"). It is not always quite so black and white, but the question rule covers a large majority of cases. If you are looking for an answer, consider posing your question to the {freebsd-questions}. Some cases where it may be appropriate to submit a problem report about something that is not a bug are: * Requests for feature enhancements. It is generally a good idea to air these on the mailing lists before submitting a problem report. * Notification of updates to externally maintained software (mainly ports, but also externally maintained base system components such as BIND or various GNU utilities). + For unmaintained ports (`MAINTAINER` contains `ports@FreeBSD.org`), such update notifications might get picked up by an interested committer, or you might be asked to provide a patch to update the port; providing it upfront will greatly improve your chances that the port will get updated in a timely manner. + If the port is maintained, PRs announcing new upstream releases are usually not very useful since they generate supplementary work for the committers, and the maintainer likely knows already there is a new version, they have probably worked with the developers on it, they are probably testing to see there is no regression, etc. + In either case, following the process described in link:{porters-handbook}#port-upgrading[Porter's Handbook] will yield the best results. A bug that can not be reproduced can rarely be fixed. If the bug only occurred once and you can not reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. That does not mean it did not happen, but it does mean that the chances of your problem report ever leading to a bug fix are very slim. To make matters worse, often these kinds of bugs are actually caused by failing hard drives or overheating processors - you should always try to rule out these causes, whenever possible, before submitting a PR. Next, to decide to whom you should file your problem report, you need to understand that the software that makes up FreeBSD is composed of several different elements: * Code in the base system that is written and maintained by FreeBSD contributors, such as the kernel, the C library, and the device drivers (categorized as `kern`); the binary utilities (`bin`); the manual pages and documentation (`docs`); and the web pages (`www`). All bugs in these areas should be reported to the FreeBSD developers. * Code in the base system that is written and maintained by others, and imported into FreeBSD and adapted. Examples include bind, man:gcc[1], and man:sendmail[8]. Most bugs in these areas should be reported to the FreeBSD developers; but in some cases they may need to be reported to the original authors instead if the problems are not FreeBSD-specific. Usually these bugs will fall under either the `bin` or `gnu` categories. * Individual applications that are not in the base system but are instead part of the FreeBSD Ports Collection (category `ports`). Most of these applications are not written by FreeBSD developers; what FreeBSD provides is merely a framework for installing the application. Therefore, you should only report a problem to the FreeBSD developers when you believe the problem is FreeBSD-specific; otherwise, you should report it to the authors of the software. Then you should ascertain whether or not the problem is timely. There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed. If the problem is in the base system, you should first read the FAQ section on link:{faq}#LATEST-VERSION[FreeBSD versions], if you are not already familiar with the topic. It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs. The Security Officer team maintains the http://www.freebsd.org/security/[list of supported versions]. If the problem is in a port, note that you must first upgrade to the latest version of the Ports Collection and see if the problem still applies. Due to the rapid pace of changes in these applications, it is infeasible for FreeBSD to support anything other than the absolute latest versions, and problems with older version of applications simply cannot be fixed. [[pr-prep]] == Preparations A good rule to follow is to always do a background search before submitting a problem report. Maybe your problem has already been reported; maybe it is being discussed on the mailing lists, or recently was; it may even already be fixed in a newer version than what you are running. You should therefore check all the obvious places before submitting your problem report. For FreeBSD, this means: * The FreeBSD link:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning link:{faq}#hardware[hardware compatibility], link:{faq}#applications[user applications], and link:{faq}#kernelconfig[kernel configuration]. * The link:{handbook}#eresources-mail[mailing lists]-if you are not subscribed, use http://www.FreeBSD.org/search/#mailinglists[the searchable archives] on the FreeBSD web site. If your problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something you have overlooked. * Optionally, the entire web-use your favorite search engine to locate any references to your problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through. * Next, the searchable http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[FreeBSD PR database] (GNATS). Unless your problem is recent or obscure, there is a fair chance it has already been reported. * Most importantly, you should attempt to see if existing documentation in the source base addresses your problem. + For the base FreeBSD code, you should carefully study the contents of the [.filename]#/usr/src/UPDATING# file on your system or its latest version at http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING[http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING]. (This is vital information if you are upgrading from one version to another-especially if you are upgrading to the FreeBSD-CURRENT branch). + However, if the problem is in something that was installed as a part of the FreeBSD Ports Collection, you should refer to [.filename]#/usr/ports/UPDATING# (for individual ports) or [.filename]#/usr/ports/CHANGES# (for changes that affect the entire Ports Collection). http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING[http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING] and http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES[http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES] are also available via CVSweb. [[pr-writing]] == Writing the problem report Now that you have decided that your issue merits a problem report, and that it is a FreeBSD problem, it is time to write the actual problem report. Before we get into the mechanics of the program used to generate and submit PRs, here are some tips and tricks to help make sure that your PR will be most effective. == Tips and tricks for writing a good problem report * _Do not leave the "Synopsis" line empty._ The PRs go both onto a mailing list that goes all over the world (where the "Synopsis" is used for the `Subject:` line), but also into a database. Anyone who comes along later and browses the database by synopsis, and finds a PR with a blank subject line, tends just to skip over it. Remember that PRs stay in this database until they are closed by someone; an anonymous one will usually just disappear in the noise. * _Avoid using a weak "Synopsis" line._ You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of `Synopsis: portupgrade is broken`, see how much more informative this seems: `Synopsis: port sysutils/portupgrade coredumps on -current`. (In the case of ports, it is especially helpful to have both the category and portname in the "Synopsis" line.) * _If you have a patch, say so._ A PR with a patch included is much more likely to be looked at than one without. If you are including one, put the string `[patch]` at the beginning of the "Synopsis". (Although it is not mandatory to use that exact string, by convention, that is the one that is used.) * _If you are a maintainer, say so._ If you are maintaining a part of the source code (for instance, a port), you might consider adding the string `[maintainer update]` at the beginning of your synopsis line, and you definitely should set the "Class" of your PR to `maintainer-update`. This way any committer that handles your PR will not have to check. * _Be specific._ The more information you supply about what problem you are having, the better your chance of getting a response. ** Include the version of FreeBSD you are running (there is a place to put that, see below) and on which architecture. You should include whether you are running from a release (e.g. from a CDROM or download), or from a system maintained by man:cvsup[1] (and, if so, how recently you updated). If you are tracking the FreeBSD-CURRENT branch, that is the very first thing someone will ask, because fixes (especially for high-profile problems) tend to get committed very quickly, and FreeBSD-CURRENT users are expected to keep up. ** Include which global options you have specified in your [.filename]#make.conf#. Note: specifying `-O2` and above to man:gcc[1] is known to be buggy in many situations. While the FreeBSD developers will accept patches, they are generally unwilling to investigate such issues due to simple lack of time and volunteers, and may instead respond that this just is not supported. ** If this is a kernel problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): *** your kernel configuration (including which hardware devices you have installed) *** whether or not you have debugging options enabled (such as `WITNESS`), and if so, whether the problem persists when you change the sense of that option *** a backtrace, if one was generated *** the fact that you have read [.filename]#src/UPDATING# and that your problem is not listed there (someone is guaranteed to ask) *** whether or not you can run any other kernel as a fallback (this is to rule out hardware-related issues such as failing disks and overheating CPUs, which can masquerade as kernel problems) ** If this is a ports problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): *** which ports you have installed *** any environment variables that override the defaults in [.filename]#bsd.port.mk#, such as `PORTSDIR` *** the fact that you have read [.filename]#ports/UPDATING# and that your problem is not listed there (someone is guaranteed to ask) * _Avoid vague requests for features._ PRs of the form "someone should really implement something that does so-and-so" are less likely to get results than very specific requests. Remember, the source is available to everyone, so if you want a feature, the best way to ensure it being included is to get to work! Also consider the fact that many things like this would make a better topic for discussion on `freebsd-questions` than an entry in the PR database, as discussed above. * _Make sure no one else has already submitted a similar PR._ Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the web-based search engine at http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query]. (Of course, everyone is guilty of forgetting to do this now and then.) * _Avoid controversial requests._ If your PR addresses an area that has been controversial in the past, you should probably be prepared to not only offer patches, but also justification for why the patches are "The Right Thing To Do". As noted above, a careful search of the mailing lists using the archives at http://www.FreeBSD.org/search/#mailinglists[http://www.FreeBSD.org/search/#mailinglists] is always good preparation. * _Be polite._ Almost anyone who would potentially work on your PR is a volunteer. No one likes to be told that they have to do something when they are already doing it for some motivation other than monetary gain. This is a good thing to keep in mind at all times on Open Source projects. == Before you begin If you are using the man:send-pr[1] program, make sure your `VISUAL` (or `EDITOR` if `VISUAL` is not set) environment variable is set to something sensible. You should also make sure that mail delivery works fine. man:send-pr[1] uses mail messages for the submission and tracking of problem reports. If you cannot post mail messages from the machine you are running man:send-pr[1] on, your problem report will not reach the GNATS database. For details on the setup of mail on FreeBSD, see the "Electronic Mail" chapter of the FreeBSD Handbook at link:{handbook}#mail[Electronic Mail]. Make sure that your mailer will not mangle the message on its way to GNATS. In particular, if your mailer automatically breaks lines, changes tabs to spaces, or escapes newline characters, any patch that you submit will be rendered unusable. For the text sections, however, we request that you insert manual linebreaks somewhere around 70 characters, so that the web display of the PR will be readable. Similar considerations apply if you are using the web-based PR submittal form instead of man:send-pr[1]. Note that cut-and-paste operations can have their own side-effects on text formatting. In certain cases it may be necessary to use man:uuencode[1] to ensure that patches arrive unmodified. Finally, if your submission will be lengthy, you should to prepare your work offline so that nothing will be lost in case there is a problem submitting it. This can be an especial problem with the web form. == Attaching patches or files The following applies to submitting PRs via email: The man:send-pr[1] program has provisions for attaching files to a problem report. You can attach as many files as you want provided that each has a unique base name (i.e. the name of the file proper, without the path). Just use the `-a` command-line option to specify the names of the files you wish to attach: [source,shell] .... % send-pr -a /var/run/dmesg -a /tmp/errors .... Do not worry about binary files, they will be automatically encoded so as not to upset your mail agent. If you attach a patch, make sure you use the `-c` or `-u` option to man:diff[1] to create a context or unified diff (unified is preferred), and make sure to specify the exact CVS revision numbers of the files you modified so the developers who read your report will be able to apply them easily. For problems with the kernel or the base utilities, a patch against FreeBSD-CURRENT (the HEAD CVS branch) is preferred since all new code should be applied and tested there first. After appropriate or substantial testing has been done, the code will be merged/migrated to the FreeBSD-STABLE branch. If you attach a patch inline, instead of as an attachment, note that the most common problem by far is the tendency of some email programs to render tabs as spaces, which will completely ruin anything intended to be part of a Makefile. Do not send patches as attachments using `Content-Transfer-Encoding: quoted-printable`. These will perform character escaping and the entire patch will be useless. Also note that while including small patches in a PR is generally all right-particularly when they fix the problem described in the PR-large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the PR instead of the patch. Patches in email tend to get mangled, especially when GNATS is involved, and the larger the patch, the harder it will be for interested parties to unmangle it. Also, posting a patch on the web allows you to modify it without having to resubmit the entire patch in a followup to the original PR. Finally, large patches simply increase the size of the database, since closed PRs are not actually deleted but instead kept and simply marked as `closed`. You should also take note that unless you explicitly specify otherwise in your PR or in the patch itself, any patches you submit will be assumed to be licensed under the same terms as the original file you modified. == Filling out the template The next section applies to the email method only: When you run man:send-pr[1], you are presented with a template. The template consists of a list of fields, some of which are pre-filled, and some of which have comments explaining their purpose or listing acceptable values. Do not worry about the comments; they will be removed automatically if you do not modify them or remove them yourself. At the top of the template, below the `SEND-PR:` lines, are the email headers. You do not normally need to modify these, unless you are sending the problem report from a machine or account that can send but not receive mail, in which case you will want to set the `From:` and `Reply-To:` to your real email address. You may also want to send yourself (or someone else) a carbon copy of the problem report by adding one or more email addresses to the `Cc:` header. In the email template you will find the following two single-line fields: * _Submitter-Id:_ Do not change this. The default value of `current-users` is correct, even if you run FreeBSD-STABLE. * _Confidential:_ This is prefilled to `no`. Changing it makes no sense as there is no such thing as a confidential FreeBSD problem report-the PR database is distributed worldwide by CVSup. The next section describes fields that are common to both the email interface and the web interface: * _Originator:_ Please specify your real name, optionally followed by your email address in angle brackets. In the email interface, this is normally prefilled with the `gecos` field of the currently logged-in user. + [NOTE] ==== The email address you use will become public information and may become available to spammers. You should either have spam handling procedures in place, or use a temporary email account. However, please note that if you do not use a valid email account at all, we will not be able to ask you questions about your PR. ==== * _Organization:_ Whatever you feel like. This field is not used for anything significant. * _Synopsis:_ Fill this out with a short and accurate description of the problem. The synopsis is used as the subject of the problem report email, and is used in problem report listings and summaries; problem reports with obscure synopses tend to get ignored. + As noted above, if your problem report includes a patch, please have the synopsis start with `[patch]`; if this is a ports PR and you are the maintainer, you may consider adding `[maintainer update]` and set the "Class" of your PR to `maintainer-update`. * _Severity:_ One of `non-critical`, `serious` or `critical`. Do not overreact; refrain from labeling your problem `critical` unless it really is (e.g. data corruption issues, serious regression from previous functionality in -CURRENT) or `serious` unless it is something that will affect many users (kernel panics or freezes; problems with particular device drivers or system utilities). FreeBSD developers will not necessarily work on your problem faster if you inflate its importance since there are so many other people who have done exactly that - in fact, some developers pay little attention to this field because of this. + [NOTE] ==== Major security problems should _not_ be filed in GNATS, because all GNATS information is public knowledge. Please send such problems in private email to `{security-officer}`. ==== * _Priority:_ One of `low`, `medium` or `high`. `high` should be reserved for problems that will affect practically every user of FreeBSD and `medium` for something that will affect many users. + [NOTE] ==== This field has become so widely abused that it is almost completely meaningless. ==== * _Category:_ Choose an appropriate category. + [NOTE] ==== There are a number of "platform" categories into which bugs in the base system that are specific to one particular hardware architecture should be filed. Problems that are generic all across versions of FreeBSD should probably be filed as `kern` or `bin`; see discussion of those categories below. Example: you have a common PC-based machine, and think you have encountered a problem specific to a particular chipset or a particular motherboard: `i386` is the right category. Example: You are having a problem with an add-in peripheral card on a commonly seen bus, or a problem with a particular type of hard disk drive: in this case, it probably applies to more than one architecture, and `kern` is the right category. ==== + Here is the current list of categories (taken from http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories[http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories]): ** `advocacy:` problems relating to FreeBSD's public image. Rarely used. ** `alpha:` problems specific to the Alpha platform. ** `amd64:` problems specific to the AMD64 platform. ** `bin:` problems with userland programs in the base system. If running man:whereis[1] shows `/bin`, `/usr/sbin`, or something similar, then this is probably the right category. (A few contributed programs might instead need to be in `gnu`; see below.) ** `conf:` problems with configuration files, default values, and so forth. Things that affect `/usr/share` or `/etc/rc*` belong here. ** `docs:` problems with manual pages or on-line documentation. ** `gnu:` problems with imported GNU software such as man:gcc[1] or man:grep[1]. ** `i386:` problems specific to the i386(TM) platform. ** `ia64:` problems specific to the ia64 platform. ** `java:` problems related to the Java(TM) Virtual Machine. (Ports that merely depend on Java(TM) to run should be filed under `ports`.) ** `kern:` problems with the kernel, (non-platform-specific) device drivers, or the base libraries. ** `misc:` anything that does not fit in any of the other categories. (Note that there is almost nothing that truly belongs in this category, except for problems with the release and build infrastructure. Temporary build failures on `HEAD` do not belong here. Also note that it is easy for things to get lost in this category). ** `ports:` problems relating to the ports tree. ** `powerpc:` problems specific to the PowerPC(R) platform. ** `sparc64:` problems specific to the Sparc64(R) platform. ** `standards:` Standards conformance issues. ** `threads:` problems related to the FreeBSD threads implementation (especially on FreeBSD-CURRENT). ** `usb:` problems related to the FreeBSD USB implementation. ** `www:` Changes or enhancements to the FreeBSD website. Problems with code found in `/usr/ports/www` do _not_ belong here, they belong in `ports` instead. * _Class:_ Choose one of the following: ** `sw-bug:` software bugs. ** `doc-bug:` errors in documentation. ** `change-request:` requests for additional features or changes in existing features. ** `update:` updates to ports or other contributed software. ** `maintainer-update:` updates to ports for which you are the maintainer. * _Release:_ The version of FreeBSD that you are running. This is filled out automatically if you are using man:send-pr[1] and need only be changed if you are sending a problem report from a different system than the one that exhibits the problem. Finally, there is a series of multi-line fields: * _Environment:_ This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.-quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs. * _Description:_ A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. * _How-To-Repeat:_ A summary of the actions you need to take to reproduce the problem. * _Fix:_ Preferably a patch, or at least a workaround (which not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem), but if you do not have any firm ideas for either, it is better to leave this field blank than to speculate. == Sending off the problem report If you are using man:send-pr[1]: Once you are done filling out the template, have saved it, and exit your editor, man:send-pr[1] will prompt you with [.prompt]#s)end, e)dit or a)bort?#. You can then hit `s` to go ahead and submit the problem report, `e` to restart the editor and make further modifications, or `a` to abort. If you choose the latter, your problem report will remain on disk (man:send-pr[1] will tell you the filename before it terminates), so you can edit it at your leisure, or maybe transfer it to a system with better net connectivity, before sending it with the `-F` to man:send-pr[1]: [source,shell] .... % send-pr -f ~/my-problem-report .... This will read the specified file, validate the contents, strip comments and send it off. If you are using the web form: Before you hit `submit`, you will need to fill in a field containing text that is represented in image form on the page. This unfortunate measure has had to be adopted due to misuse by automated systems and a few misguided individuals. It is a necessary evil that no one likes; please do not ask us to remove it. Note that you are `strongly advised` to save your work somewhere before hitting `submit`. A common problem for users is to have their web browser displaying a stale image from its cache. If this happens to you, your submission will be rejected and you may lose your work. If you are unable to view images for any reason, and are also unable to use man:send-pr[1], please accept our apologies for the inconvenience and email your problem report to the bugbuster team at mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org]. [[pr-followup]] == Follow-up Once your problem report has been filed, you will receive a confirmation by email which will include the tracking number that was assigned to your problem report and a URL you can use to check its status. With a little luck, someone will take an interest in your problem and try to address it, or, as the case may be, explain why it is not a problem. You will be automatically notified of any change of status, and you will receive copies of any comments or patches someone may attach to your problem report's audit trail. If someone requests additional information from you, or you remember or discover something you did not mention in the initial report, please use one of two methods to submit your followup: * The easiest way is to use the followup link on the individual PR's web page, which you can reach from the http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[PR search page]. Clicking on this link will bring up an an email window with the correct To: and Subject: lines filled in (if your browser is configured to do this). * Alternatively, you can just mail it to {bugfollowup}, making sure that the tracking number is included in the subject so the bug tracking system will know what problem report to attach it to. + [NOTE] ==== If you do _not_ include the tracking number, GNATS will become confused and create an entirely new PR which it then assigns to the GNATS administrator, and then your followup will become lost until someone comes in to clean up the mess, which could be days or weeks afterwards. Wrong way: [.programlisting] .... Subject: that PR I sent .... Right way: [.programlisting] .... Subject: Re: ports/12345: compilation problem with foo/bar .... ==== If the problem report remains open after the problem has gone away, just send a follow-up (in the manner prescribed above) saying that the problem report can be closed, and, if possible, explaining how or when the problem was fixed. [[pr-problems]] == If you are having problems Most PRs go through the system and are accepted quickly; however, at times GNATS runs behind and you may not get your email confirmation for 10 minutes or even longer. Please try to be patient. In addition, because GNATS receives all its input via email, it is absolutely vital that FreeBSD runs all its submissions through spam filters. If you do not get a response within an hour or two, you may have fallen afoul of them; if so, please contact the GNATS administrators at mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org] and ask for help. [NOTE] ==== Among the anti-spam measures is one that weighs against many common abuses seen HTML-based email (although not necessarily the mere inclusion of HTML in a PR). We strongly recommend against the use of HTML-based email when sending PRs: not only is it more likely to fall afoul of the filters, it also tends to merely clutter up the database. Plain old email is strongly preferred. ==== On rare occasions you will encounter a GNATS bug where a PR is accepted and assigned a tracking number but it does not show up on the list of PRs on any of the web query pages. What may have happened is that the database index has gotten out of synchronization with the database itself. The way that you can test whether this has happened is to pull up the http://www.FreeBSD.org/cgi/query-pr.cgi[view a single PR] page and see whether the PR shows up. If it does, please notify the GNATS administrators at mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org]. Note that there is a `cron` job that periodically rebuilds the database, so unless you are in a hurry, no action needs to be taken. [[pr-further]] == Further Reading This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. * http://www.chiark.greenend.org.uk/~sgtatham/bugs.html[How to Report Bugs Effectively]-an excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports. * link:{pr-guidelines}[Problem Report Handling Guidelines]-valuable insight into how problem reports are handled by the FreeBSD developers. diff --git a/documentation/content/zh-tw/articles/remote-install/_index.adoc b/documentation/content/zh-tw/articles/remote-install/_index.adoc index 69622b2544..e8b75cca4e 100644 --- a/documentation/content/zh-tw/articles/remote-install/_index.adoc +++ b/documentation/content/zh-tw/articles/remote-install/_index.adoc @@ -1,324 +1,336 @@ --- title: 遠端安裝 FreeBSD 作業系統而不必接 Remote Console authors: - author: Daniel Gerzo email: danger@FreeBSD.org copyright: 2008 The FreeBSD Documentation Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = 遠端安裝 FreeBSD 作業系統而不必接 Remote Console :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] include::shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/zh-tw/urls.adoc[] +endif::[] [.abstract-title] 摘要 本文介紹如何在沒辦法連到遠端 console 的機器做 FreeBSD 遠端安裝。 本文構想來自於作者與 `{mm}` 的合作成果， 以及 `{pjd}` 所投注的諸多心血。 ''' toc::[] [[background]] == 緣起 世上有許多 server hosting provider，但其中有官方支援 FreeBSD 則不是相當多。 他們通常會在所提供的機器上有 Linux(R) distribution 的安裝支援。 有些會讓您可選擇喜好的 Linux(R) distribution 來裝， 像這種情況就可以試著安裝 FreeBSD。 而有些則是會提供救急用的系統， 這種也可以用來安裝 FreeBSD。 本文介紹這些遠端基本安裝 FreeBSD 的方式，以及 RAID-1 與 ZFS 設定步驟。 [[intro]] == 介紹 茲摘錄一下本文的目的以及闡述這邊所涵蓋的東西。 對於無官方支援 FreeBSD 的代管服務(colocation)用戶而言， 本文中所介紹到的指令會相當有用。 [.procedure] . 正如先前 <> 所提到的，許多名聲還不賴的 server hosting 公司會提供一些救急用系統，可以透過 LAN 方式開機，也可以透過 SSH 方式進行管理。 通常會有該加值服務， 以讓他們的客戶可以連進來修復有問題的作業系統。 本節之後將介紹如何透過救急系統來安裝 FreeBSD。 + . 下一節會介紹如何在本機設定以及打造最小巧的 FreeBSD ---- 該版最後會在遠端機器上透過 ramdisk 方式啟動，並以 Sysinstall 從 FTP mirror 站來安裝完整的 FreeBSD 作業系統。 . 本文其餘部分將介紹安裝程序，以及 ZFS 檔案系統的設定。 [[requirements]] === 需求 為了成功完成遠端安裝，必須要有： * 要有可以上網的作業系統，並且 SSH 可以連線。 * 瞭解 FreeBSD 的安裝程序 * 熟悉如何使用 man:sysinstall[8] * 有 FreeBSD 安裝光碟片或者 ISO image 檔 [[preparation]] == 準備 - mfsBSD 在裝 FreeBSD 之前，要先打造最小化的 FreeBSD 作業系統 image 檔， 以便可以從硬碟上開機。 如此一來，新的系統就可以透過網路來操作， 而剩下來的安裝部分即可不必透過 console。 而 mfsBSD 這套工具就是用來打造小型的 FreeBSD image 檔。 mfsBSD (名字其中 "mfs" 就是 "memory file system")所建造出來的 整套系統會透過 ramdisk 方式來運作。 由於此一特色，硬碟的部分就不受限， 因此可以用來安裝完整的 FreeBSD 作業系統。 mfsBSD 的首頁位於 http://people.freebsd.org/\~mm/mfsbsd/[http://people.freebsd.org/~mm/mfsbsd/]， 其中連結有該工具的最新 release 部分。 請注意：mfsBSD 內部運作方式的細節，不 在本文介紹範圍之內。 若對這方面有興趣的讀者，可至 mfsBSD 官網查閱相關文件。 首先下載最新的 mfsBSD 並解壓縮之， 然後切到解壓縮後的工作目錄，也就是 mfsBSD script 檔所在處： [source,shell] .... # fetch http://people.freebsd.org/~mm/mfsbsd/mfsbsd-latest.tar.gz # tar xvzf mfsbsd-1.0-beta1.tar.gz # cd mfsbsd-1.0-beta1/ .... [[mfsbsd-config]] === 設定 mfsBSD 在將 mfsBSD 開機之前， 有幾個重要設定要先設妥。 此時最重要的設定，很明顯就是網路設定。 到底網路怎麼設最好，則取決於所處的網路環境， 以及該網路卡會以哪一種驅動程式載入而定。 我們將會看到 mfsBSD 如何在任何網路情況下進行設定。 另一件重要事就是設定 `root` 密碼。 這點可以透過 [.filename]#conf/rootpw.conf# 來完成。 請切記：該檔密碼是以明文方式存放，因此不建議放真正平常有在用的密碼。 然而這密碼只是臨時密碼而已，可以在之後開機時再做更換。 ==== 設定網路([.filename]#conf/interfaces.conf# 方式) 若對要裝的機器網卡為何還不知道是哪一款，但可以善加利用 mfsBSD 的自動偵測功能。 mfsBSD 的開機 script 會根據網卡的 MAC 位址範圍來偵測正確的驅動程式，像是下列的 [.filename]#conf/interfaces.conf# 設定內容： [.programlisting] .... initconf_interfaces="ext1" initconf_mac_ext1="00:00:00:00:00:00" initconf_ip_ext1="192.168.0.2" initconf_netmask_ext1="255.255.255.0" .... 別忘了在 [.filename]#conf/rc.conf# 內要加上 `defaultrouter` 的相關設定： [.programlisting] .... defaultrouter="192.168.0.1" .... ==== 設定網路([.filename]#conf/rc.conf# 方式) 若已經知道網卡是哪一種，那麼要設定網路的話直接改 [.filename]#conf/rc.conf# 會比較方便。 該檔設定語法與 FreeBSD 標準的 man:rc.conf[5] 是一致的。 舉個例子，若知道該機器網卡是用 man:re[4]，那麼就在 [.filename]#conf/rc.conf# 做下列類似設定： [.programlisting] .... defaultrouter="192.168.0.1" ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0" .... [[mfsbsd-build]] === 打造 mfsBSD image 打造 mfsBSD image 檔的過程相當簡單。 首先是把 FreeBSD 安裝光碟或者安裝用的 ISO image 檔丟到 [.filename]#/cdrom#。 為維持所有例子的一致，本文假設都是用 FreeBSD 7.0-RELEASE ISO。 而把 ISO image 檔掛載到 [.filename]#/cdrom# 目錄相當簡單， 就是用 man:mdconfig[8]： [source,shell] .... # mdconfig -a -t vnode -u 10 -f 7.0-RELEASE-amd64-disc1.iso # mount_cd9660 /dev/md10 /cdrom .... 接著就開始打造可開機的 mfsBSD image： [source,shell] .... # make BASE=/cdrom/7.0-RELEASE .... [NOTE] ==== 上述的 make 指令要在 mfsBSD 的最上層目錄執行，比方說 [.filename]#~/mfsbsd-1.0-beta1/#。 ==== === mfsBSD 開動 現在 mfsBSD image 已經備妥， 要上傳到遠端機器的救急系統或者預先安裝的 Linux(R) distribution。 要完成這工作最適合的工具就是 scp： [source,shell] .... # scp disk.img root@192.168.0.2:. .... 為了能順利啟動 mfsBSD image， 要把檔案放在欲安裝機器的第一顆(可開機)硬碟上。 假設例子的第一顆開機硬碟代號為 [.filename]#sda#， 那麼作法就類似下面這樣： [source,shell] .... # dd if=/root/disk.img of=/dev/sda bs=1m .... 若一切順利，該 image 檔現在應該會在第一顆硬碟的 MBR 磁區並可以開始進行重開機了。 可以用 man:ping[8] 工具來檢測該機器開機完畢與否。 一旦 ping 到之後， 就可以透過 man:ssh[1] 連進去，並且用 `root` 以及剛設定的密碼登入。 [[installation]] == FreeBSD 作業系統的安裝 現在 mfsBSD 已順利啟動，並且應該可以透過 man:ssh[1] 方式來連。 本節將介紹如何建立 slice 分割、設定 gmirror 以作 RAID-1、如何以 Sysinstall 來安裝 FreeBSD 作業系統的最小化安裝。 === 準備硬碟 首先要作的是配置硬碟空間給 FreeBSD，像是建立 slice 跟分割區。 很明顯地，目前在跑的作業系統是載入到系統記憶體內執行， 因此要對硬碟配置並無任何問題。 這些工作可以用 Sysinstall 或者以 man:fdisk[8] 搭配 man:bsdlabel[8] 來完成。 首先先把各硬碟都先清空。 請對各硬碟作下列指令： [source,shell] .... # dd if=/dev/zero of=/dev/ad0 count=2 .... 接著，以您慣用的工具來建立 slice 以及設定 label。 通常會建議以 的 Sysinstall 工具來作會比較輕鬆， 或者是強而又不太會出槌的文字介面 UNIX(R) 標準工具(像是 man:fdisk[8], man:bsdlabel[8])，這部分稍後也會一併介紹。 前者部分在 FreeBSD Handbook 的 link:{handbook}#install-steps[安裝 FreeBSD] 章節有相當詳盡的介紹，所以這邊主要要介紹的是如何建立 RAID-1 系統以及 ZFS。 這邊會介紹建立以 man:gmirror[8] 做成的小型 mirrored 檔案系統： [.filename]#/# (根目錄), [.filename]#/usr# 以及 [.filename]#/var#，而硬碟的其餘剩餘空間則通通以 man:zpool[8] 做成 ZFS 的 mirrored 檔案系統 。 請注意：必須要先把 FreeBSD 作業系統裝好並開完機後，才能進行設定 ZFS 檔案系統。 下面的例子會介紹如何建立 slice 以及 label、在每個分割區上啟用 man:gmirror[8]、如何在每個 mirrored 分割區上建立 UFS2 檔案系統： [source,shell] .... # fdisk -BI /dev/ad0 <.> # fdisk -BI /dev/ad1 # bsdlabel -wB /dev/ad0s1 <.> # bsdlabel -wB /dev/ad1s1 # bsdlabel -e /dev/ad0s1 <.> # bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt && bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt <.> # gmirror label root /dev/ad[01]s1a <.> # gmirror label var /dev/ad[01]s1d # gmirror label usr /dev/ad[01]s1e # gmirror label -F swap /dev/ad[01]s1b <.> # newfs /dev/mirror/root <.> # newfs /dev/mirror/var # newfs /dev/mirror/usr .... <.> 對該硬碟建立 slice 並且在第零軌處將開機表作初始。 請對該機器所有硬碟都作此一動作。 <.> 對各硬碟寫入 label 以及 bootstrap 碼。 <.> 現在手動修改該硬碟的 label，至於如何建立分割區(partitions) 請參閱 man:bsdlabel[8] 說明。 分割區分別建立：`a` 是給 [.filename]#/# (根目錄)， `b` 給 swap， `d` 給 [.filename]#/var#， `e` 給 [.filename]#/usr#， 最後，會在稍後步驟把 `f` 給 ZFS 使用。 <.> 把剛剛的 label 設定先匯出，再匯入到第二顆硬碟上， 如此一來兩邊的硬碟 label 設定就會同樣。 <.> 在各分割區上啟用 man:gmirror[8] <.> 請注意：`-F` 選項是用在 swap 上。 這參數會讓 man:gmirror[8] 認為該硬體是處於可靠狀態， 即使發生電源故障或系統當掉，也不會去同步。 <.> 在各個有做 mirror 的分割區上建立 UFS2 檔案系統 === 系統安裝 這裡是最重要的一環， 本節介紹實際上如何在先前一節所做好的硬碟安裝最小化的 FreeBSD， 為了完成此一目標，所有檔案系統都必須掛載妥當，才能讓 Sysinstall 可以把 FreeBSD 裝到硬碟內： [source,shell] .... # mount /dev/mirror/root /mnt # mkdir /mnt/var /mnt/usr # mount /dev/mirror/var /mnt/var # mount /dev/mirror/usr /mnt/usr .... 做完上述動作之後，請執行 man:sysinstall[8]。 請從主選單中選擇 [.guimenuitem]#Custom# 安裝，選 [.guimenuitem]#Options# 按 kbd:[Enter]。 然後以方向鍵移動到 `Install Root` 處，按 kbd:[Space] 鍵然後改為 [.filename]#/mnt#，再按 kbd:[Enter] 鍵以將修改值存起來，然後按 kbd:[q] 鍵即可離開這個 [.guimenuitem]#Options# 畫面。 [WARNING] ==== 請注意：本步驟極為重要，若忽略的話那麼 Sysinstall 就沒辦法安裝 FreeBSD。 ==== 接著選 [.guimenuitem]#Distributions#，然後移動游標到 `Minimal` 處，按 kbd:[Space] 鍵。 本文之所以介紹最小化安裝是為了要節省網路流量，因為系統安裝是透過 ftp 方式來進行。 要離開本畫面，請選 `Exit` 即可。 [NOTE] ==== 至於 [.guimenuitem]#Partition# 及 [.guimenuitem]#Label# 步驟則可略過， 因為這些目前已經都設定完畢了。 ==== 在 [.guimenuitem]#Media# 選單中請選 `FTP`。 請選最近的 mirror 站，並且讓 Sysinstall 假設網路已經設妥。 接下來就會回到 [.guimenuitem]#Custom# 選單。 最後，按下 [.guimenuitem]#Commit# 即可開始進行安裝。 完成安裝後，即可離開 Sysinstall。 === 後續安裝步驟 此時 FreeBSD 作業系統應該已經裝完，然而還有些後續流程要做。 必須要做一些後續設定，才能讓 FreeBSD 可以開機跟登入。 現在必須要用 man:chroot[8] 以切到剛剛新裝好的系統內。 指令如下： [source,shell] .... # chroot /mnt .... 然後再打下列指令以繼續完成： * 把 `GENERIC` kernel 複製到 [.filename]#/boot/kernel# 目錄： + [source,shell] .... # cp -Rp /boot/GENERIC/* /boot/kernel .... * 建立 [.filename]#/etc/rc.conf#, [.filename]#/etc/resolv.conf# 及 [.filename]#/etc/fstab# 檔案。 別忘了，要記得在 [.filename]#/etc/rc.conf# 檔設相關網路設定，以及把 sshd 啟用。 此外， [.filename]#/etc/fstab# 檔應該會長像下面這樣： + [.programlisting] .... # Device Mountpoint FStype Options Dump Pass# /dev/mirror/swap none swap sw 0 0 /dev/mirror/root / ufs rw 1 1 /dev/mirror/usr /usr ufs rw 2 2 /dev/mirror/var /var ufs rw 2 2 /dev/cd0 /cdrom cd9660 ro,noauto 0 0 .... * 新增 [.filename]#/boot/loader.conf# 檔， 並且內容填入下列： + [.programlisting] .... geom_mirror_load="YES" zfs_load="YES" .... * 執行下列指令，以在下次開機時啟用 ZFS ： + [source,shell] .... # echo 'zfs_enable="YES"' >> /etc/rc.conf .... * 使用 man:adduser[8] 工具來新增其他使用者帳號。 別忘了， 至少要有一個帳號得加入 `wheel` 群組， 才能在重開機後以該帳號切換為 root。 * 再次檢查上述相關的設定，是否有遺漏或打錯。 現在該系統終於可以重開機了，請用 man:reboot[8] 指令以重開機。 [[zfs]] == ZFS 系統重開機完畢之後，應該就可以登入了。 歡迎使用全新的 FreeBSD 安裝方式， 完全透過遠端而不必接上 remote console！ 接下來只剩要調整 man:zpool[8] 以及建立 man:zfs[8] 檔案系統而已。 ZFS 的建立及管理是相當淺顯易懂。 首先， 建立 mirrored pool： [source,shell] .... # zpool create tank mirror /dev/ad[01]s1f .... 接著，建立檔案系統： [source,shell] .... # zfs create tank/ports # zfs create tank/src # zfs set compression=gzip tank/ports # zfs set compression=on tank/src # zfs set mountpoint=/usr/ports tank/ports # zfs set mountpoint=/usr/src tank/src .... 一切就是這樣簡單。 若對 FreeBSD 上的 ZFS 細節部分有興趣，請參閱 FreeBSD Wiki 上的 http://wiki.freebsd.org/ZFS[ZFS] 一節說明。 diff --git a/documentation/content/zh-tw/books/developers-handbook/_index.adoc b/documentation/content/zh-tw/books/developers-handbook/_index.adoc index d74adf6ea3..4f2d623cd0 100644 --- a/documentation/content/zh-tw/books/developers-handbook/_index.adoc +++ b/documentation/content/zh-tw/books/developers-handbook/_index.adoc @@ -1,103 +1,103 @@ --- title: FreeBSD Developers' Handbook authors: - author: FreeBSD 文件計畫 copyright: 1995-2020 The FreeBSD Documentation Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "ibm", "ieee", "apple", "intel", "linux", "microsoft", "opengroup", "sun", "general"] --- = FreeBSD Developers' Handbook :doctype: book :toc: macro :toclevels: 2 :icons: font :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: :skip-front-matter: :toc-title: 目录 :part-signifier: 部分 :chapter-signifier: 第 :appendix-caption: 附录 :table-caption: 表 :figure-caption: 图 :example-caption: 例 ifeval::["{backend}" == "html5"] include::shared/mirrors.adoc[] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/zh-tw/mailing-lists.adoc[] include::shared/zh-tw/urls.adoc[] :imagesdir: ../../../../images/books/developers-handbook/ :chapters-path: content/zh-tw/books/developers-handbook/ endif::[] ifeval::["{backend}" == "pdf"] include::../../../../shared/mirrors.adoc[] include::../../../../shared/authors.adoc[] include::../../../../shared/releases.adoc[] include::../../../../shared/zh-tw/mailing-lists.adoc[] include::../../../../shared/zh-tw/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ +:imagesdir: ../../../../static/images/books/developers-handbook/ :chapters-path: endif::[] ifeval::["{backend}" == "epub3"] include::../../../../shared/mirrors.adoc[] include::../../../../shared/authors.adoc[] include::../../../../shared/releases.adoc[] include::../../../../shared/zh-tw/mailing-lists.adoc[] include::../../../../shared/zh-tw/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ +:imagesdir: ../../../../static/images/books/developers-handbook/ :chapters-path: endif::[] [.abstract-title] [abstract] 摘要 歡迎使用 Developers' Handbook！ 這份文件是由許多人 _不斷撰寫_ 而成的， 而且許多章節仍需更新或者內容還是一片空白， 如果你想幫忙 FreeBSD 文件計劃， 請寄信到 {freebsd-doc}。 最新版的文件都在 link:https://www.FreeBSD.org[FreeBSD 官網] 上面， 也可從 link:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/[FreeBSD FTP server] 下載不同格式的資料。 當然也可以在其他的 link:{handbook}#mirrors-ftp/[mirror站]下載。 ''' toc::[] // Section one [[basics]] = 基本概念 include::{chapters-path}introduction/chapter.adoc[leveloffset=+1, lines=10..30;40..-1] include::{chapters-path}tools/chapter.adoc[leveloffset=+1, lines=10..35;45..-1] include::{chapters-path}secure/chapter.adoc[leveloffset=+1, lines=9..29;39..-1] include::{chapters-path}l10n/chapter.adoc[leveloffset=+1, lines=7..27;37..-1] include::{chapters-path}policies/chapter.adoc[leveloffset=+1, lines=10..30;40..-1] include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=7..27;37..-1] // Section two [[ipc]] = Interprocess Communication(IPC) include::{chapters-path}sockets/chapter.adoc[leveloffset=+1, lines=9..29;40..-1] include::{chapters-path}ipv6/chapter.adoc[leveloffset=+1, lines=9..29;39..-1] // Section three [[kernel]] = Kernel(核心) include::{chapters-path}kernelbuild/chapter.adoc[leveloffset=+1, lines=7..27;37..-1] include::{chapters-path}kerneldebug/chapter.adoc[leveloffset=+1, lines=11..31;41..-1] // Section four [[architectures]] = Architectures(電腦架構) include::{chapters-path}x86/chapter.adoc[leveloffset=+1, lines=7..27;37..-1] // Appendices include::{chapters-path}bibliography/chapter.adoc[leveloffset=+1, lines=6..20;28..-1]