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

Migrate doc to Hugo/AsciiDoctor

Browse source 
I'm very pleased to announce the release of
our new website and documentation using
the new toolchain with Hugo and AsciiDoctor.

To get more information about the new toolchain
please read the FreeBSD Documentation Project Primer[1],
Hugo docs[2] and AsciiDoctor docs[3].

Acknowledgment:
Benedict Reuschling <bcr@>
Glen Barber <gjb@>
Hiroki Sato <hrs@>
Li-Wen Hsu <lwhsu@>
Sean Chittenden <seanc@>
The FreeBSD Foundation

[1] https://docs.FreeBSD.org/en/books/fdp-primer/
[2] https://gohugo.io/documentation/
[3] https://docs.asciidoctor.org/home/

Approved by:    doceng, core
This commit is contained in:
Sergio Carlavilla Delgado 2021-01-26 00:31:29 +01:00
parent 0cff342f42
commit 989d921f5d
14375 changed files with 1277937 additions and 3448703 deletions
Download patch file Download diff file Expand all files Collapse all files

7
documentation/content/ja/articles/_index.adoc Normal file
View file

@ -0,0 +1,7 @@
---
title: Articles
---
= Articles
{{< list-articles-directories >}}

181
documentation/content/ja/articles/contributing/_index.adoc Normal file
View file

@ -0,0 +1,181 @@
---
title: FreeBSD への貢献
authors:
- author: Hubbard Jordan [FAMILY Given]
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: 例
include::shared/ja/mailing-lists.adoc[]
include::shared/ja/urls.adoc[]
[.abstract-title]
概要
この文書は、個人や団体が FreeBSD プロジェクトに貢献するためのいくつかの方法について説明しています。
'''
toc::[]
あなたも FreeBSD のために貢献したくなりましたか? 素晴らしい! FreeBSD は生き残るためにユーザベースの貢献に__頼っています__。 あなたの貢献は感謝されるだけではなく、FreeBSD が成長し続けるために極めて重要なものなのです!
一部の人達が発言しているのとは反対に、 貢献を受け付けてもらうために腕利きのプログラマーになるとか FreeBSD コアチームの人と親友になる必要はありません。 多くのそして益々増加する世界中の貢献者達が FreeBSD を開発しており、 彼らの年齢、専門技術分野は多岐に渡っています。 手の空いている人よりも成すべき仕事の方が多く、 お手伝いはいつでも歓迎されています。
FreeBSD プロジェクトはカーネルや散在しているユーティリティよりも、 オペレーティングシステム環境に対して責任を持っています。 私たちの [.filename]#TODO# リストには文書整備、ベータテスト、 インストーラや専門化されたタイプのカーネル開発の好例を紹介するなど非常に広い範囲の作業があります。 あなたの技能レベルや分野に関わらず、 プロジェクトを支援できることが必ず何かあります!
FreeBSD 関連の事業に携わる商業団体が私たちにコンタクトすることも歓迎しています。 あなたの製品を (FreeBSD 上で) 動作させるには、 特別な拡張が必要ではありませんか? あまりにも風変わりな要求でなければ、 それを受け入れる用意が私たちにあるとわかるはずです。 付加価値のある製品ですか? 私たちに知らせてください! 多分私たちは、 ある面において共同して作業をすることができるでしょう。 フリーソフトウェア界は、 ソフトウェアがどのように開発され、 販売され、保守されていくかについて、既存の仮説に挑戦しています。 少なくとももう一度考慮してみることを私たちは強くお奨めします。
[[contrib-what]]
== 何が必要?
次の課題とサブプロジェクトの一覧は、色々な [.filename]#TODO# リストとユーザからの要求を合わせたものです。
[[non-programmer-tasks]]
=== 進行中の非プログラマ向けの課題
FreeBSD に関わっている中には、プログラマではない人がたくさんいます。 プロジェクトには、文書を書く人、Web デザイナ、サポートを行う人がいます。 貢献するのに必要なのは、時間の投資と学ぶ意欲です。
. 定期的に FAQ とハンドブックを通して読んでみてください。 もしまずい説明や古い事柄や完全に間違っていることなどがあれば私達に教えてください。 さらに良いのは我々に修正案を送ることです (Docbook は学ぶのにそれほど難しくありませんが、 プレインテキストでも問題はありません)。
. FreeBSD の文書を自分の母国語に翻訳するのを手伝ってください。 文書がすでに存在すれば、もっと文書を翻訳したり、 その翻訳が最新の状態かどうか確認するのを手伝うことができます。 まず FreeBSD ドキュメンテーションプロジェクト入門の link:{fdp-primer}#translations[翻訳に関する FAQ (よくある質問とその答え)] を一読してください。 とはいっても、 そうすることによってあなたがすべての FreeBSD 文書の翻訳に携わるようになるわけではないですからね。 - ボランティアとして、 多少に関わらず、自分がやろうと思うだけやってください。 いったん誰かが翻訳を始めたら、 たくさんの人達がいつだって協力してくれますから。 もし翻訳に費す時間やエネルギーが限られているなら、 まずインストール方法の翻訳からお願いします (訳注: なぜなら、 もっとも必要とされている文書がそれだからです)。
. たまに (もしくは定期的に) {freebsd-questions} を読んでください。 これは、あなたの持っている専門知識を共有したり、 誰かが抱えている問題を解決するのに非常に有効なものになり得ることです。 時にはあなた自身で新しいことを学ぶことさえできるかもしれません。 これらのフォーラムはやるべきことのアイディアの源にもなり得るのです。
[[ongoing-programmer-tasks]]
=== 進行中のプログラマ向けの課題
このセクションで挙げる課題は膨大な時間の投資または FreeBSD のカーネルに関する深い知識、もしくは両方を必要とします。 しかしながら、"週末ハッカー" に適した立派な課題も数多くあります。
. FreeBSD-CURRENT を運用しており、 状態の良いインターネット接続があるならば、 `current.FreeBSD.org` という一日に一回フルリリースを行っているマシンがあります - 時おり最新のリリースをそこからインストールし、 その過程で何か問題があるなら報告してください。
. {freebsd-bugs} を読んでください。 そこではあなたが建設的なコメントを付けたりテストできるパッチが提供されているような問題があるかもしれません。 もしくはそれらの問題の一つをあなた自身で修正することさえできるかもしれません。
. -CURRENT に正しく当てられるがしばらく経っても (通常は 2, 3 週間) -STABLE に取り込まれてないようなバグフィックスがあるならばコミッターに丁寧に思い出させてください。
. 寄贈ソフトウェアをソースツリーの [.filename]#src/contrib# に移動させてください。
. [.filename]#src/contrib# 以下のコードが最新のものであるか確認してください。
. 警告を詳細に報告するようにしてソースツリー全体 (もしくはその一部) を構築してみてください。 そして警告が出ないようにしてください。
. ports で、`gets()` を使っているとか [.filename]#malloc.h# をインクルードしているなどといった警告が出ないようにしてください。
. もしなんらかの ports に関わっていて、 FreeBSD に固有の変更が必要であれば、 あなたのパッチを作者にフィードバックしてください (次のバージョンが出た時にあなたが楽になります)。
. POSIX(R) のような公式標準の写しを入手してください。 FreeBSD の挙動を標準が要求するものと比較してください。 挙動が異なる場合、 特にそれが仕様の取るに足らなかったり分かりにくい細かい部分なら、 障害報告を提出してください。できればどう修正すべきか明らかにして、 障害報告にパッチをつけてください。標準が間違っていると感じたら、 標準化団体にその疑問を糺してください。
. この一覧に追加する課題を提案してください!
=== 障害報告 (PR; Problem Report) データベースにおける作業
https://bugs.FreeBSD.org/search/[FreeBSD 障害報告一覧]では、現在問題となっている障害報告と、 FreeBSD の利用者によって提出された改良の要望すべての一覧を公開しています。 障害報告データベースには、 プログラマ向けと非プログラマ向けの課題が共に含まれています。 open 状態の障害報告を見て、興味を引くものがあるか確かめてください。 なかには、障害報告に対する修正が適切なものであるかどうか単にチェックするだけのとても簡単な作業もあるでしょうし、 ずっと複雑なものや、修正が含まれてすらいないものもあるでしょう。
まず、まだ誰にも割り当てられていない障害報告から作業を始めてください。 もし、誰か他の人に割り当てが決まっているけれども自分が作業可能だ、 という障害報告があれば、作業ができるかどうか、 割り当てられている人に電子メールで問い合わせてください。- 既にテスト用パッチが用意されているかもしれませんし、 より進んだ考えに関して議論ができるかもしれません。
=== "アイディア"ページの項目
FreeBSD プロジェクトに貢献したい人のために http://wiki.freebsd.org/IdeasPage[ボランティアのための FreeBSD のプロジェクトとアイディア一覧] も用意されています。 この一覧は常に更新され続けており、それぞれのプロジェクトについて、 プログラマと非プログラマ両方に向けた項目があります。
[[contrib-how]]
== 貢献の仕方
一般的に、システムへの貢献は次の 5 つのカテゴリの 1 つ以上に分類されます:
[[contrib-general]]
=== バグ報告と一般的な論評
__一般的な__技術的関心事に関するアイデアや提案は {freebsd-hackers} へメールしてください。同様に、このような事柄に興味のある (そして__膨大な__メール! に耐えられる) 人は、 {freebsd-hackers} に参加すると良いでしょう。 このメーリングリストや他のメーリングリストに関する詳しい情報については link:{handbook}#eresources-mail[FreeBSD ハンドブック] を参照してください。
バグを発見したり変更を送付しようとしている場合は https://bugs.FreeBSD.org/submit/[障害報告提出フォーム] を使用して報告してください。 バグレポートの各項目を埋めるようにしてください。65KB を超えるのでなければ、 レポート中に直接パッチを入れてくださって結構です。 パッチがソースツリーにすぐ適用できるものならば、 報告の概要に `[PATCH]` と書いておいてください。 パッチを入れる場合、カット&ペーストは__しないで__ ください。 カット&ペーストではタブがスペースに展開されてパッチが使い物にならなくなってしまいます。 パッチが 20KB を超える場合は、アップロードをする前に、 それらを (man:gzip[1] や man:bzip2[1] で) 圧縮することを検討してください。
レポートがファイリングされれば、 バグ報告の確認とトラッキング番号をメールで受け取るはずです。 このトラッキング番号を覚えておき、 問題に関する詳細情報を更新できるようにしてください。
良い障害報告を書く方法については link:{problem-reports}[この文書] をご覧ください。
=== 文書の変更
文書の変更は {freebsd-doc} が監督しています。 完全な説明は、link:{fdp-primer}[ドキュメンテーションプロジェクト入門] をご覧ください。 他の障害報告と同様の方法で、提案や変更 (どんな些細なものでも歓迎します!) を送ってください。
=== 現存のソースコードの変更
現存のソースコードへの追加または変更は、 いくらかトリッキーな仕事であり、FreeBSD 開発の現状にあなたがどれだけ通じているかに大きく依存します。 "FreeBSD-CURRENT" として知られる FreeBSD の特別な継続的リリースがあります。FreeBSD-CURRENT は開発者の積極的な活動の便宜のために、 色々な方法で利用可能になっています。FreeBSD-CURRENT の入手と使用方法についての詳しい情報については link:{handbook}#current-stable[FreeBSD ハンドブック] を参照してください。
古いソースをもとに作業すると、 残念ながらあなたの変更が時として時代遅れもしくは大きく異なるものになってしまって、 FreeBSD に再統合するのは困難になる恐れがあります。 システムの現状に関する議論がおこなわれている {freebsd-announce} と {freebsd-current} へ参加すれば、この可能性を最小限にできます。
十分新しいソースを変更のベースにできることが確実になったと仮定して、 次のステップは FreeBSD の保守担当者へ送る差分ファイルの生成です。これは man:diff[1] コマンドを使用しておこないます。
差分ファイルの提出において好ましい man:diff[1] の形式は、 `diff -u` により生成される unified diff 形式です。
[source,bash]
....
% diff -u oldfile newfile
....
または、
[source,bash]
....
% diff -u -r -N olddir newdir
....
で、指定されたソースファイルまたはディレクトリ階層に対する unified diff 形式の差分が生成されます。
詳しい説明は man:diff[1] を参照してください。
差分ファイル (man:patch[1] コマンドでテストできます) を作ったら、それらを FreeBSD に含めてもらうよう障害報告として提出してください。 差分ファイルだけを {freebsd-hackers} へ __送ってはいけません__。 見過ごされてしまうでしょう。 あなたの提案は大歓迎です (これはボランティアのプロジェクトです!)。 私たちは多忙なのですぐに取りかかれないかもしれませんが、 それまで PR データベースに残っているでしょう。 報告の概要に `[PATCH]` と書いてあなたの提案を表明してください。
あなたがそうした方がいいと思う場合 (たとえば、 ファイルの追加、削除または名称変更など)、変更を `tar` ファイルにまとめてください。man:shar[1] アーカイブも歓迎します。
たとえば、再配布に適用される著作権の問題に自信がないといった、 あなたの変更が微妙な性質のものである可能性があれば、 障害報告で提出するよりむしろ直接 {core} へ送ってください。{core} 宛のメールは、 日々の仕事のかなりの割合を FreeBSD に割いている人たちの、 より小さなグループに届きます。 このグループもまた__とても忙しい__ことに注意して、 本当に必要な場合だけコアチームにメールを送るようにしてください。
コーディングスタイルに関して man:intro[9] および man:style[9] を参照してください。コードを提出する前には、 少なくともこの情報を意識しておいてくださるようお願いします。
=== 新たなコードやきわめて付加価値の高いパッケージ
大きな分量の作業成果の貢献や、重要な新しい機能を FreeBSD に追加する場合には、大抵、変更点を tar ファイルにまとめて送るか、ウェブサイトや FTP サイトへアップロードしてアクセスできるようにしなければなりません。 web や FTP サイトが利用できなければ、適切な FreeBSD のメーリングリストで誰かその変更をおくサイトを提供してくれるよう頼んでください。
大量のコードを扱っている時は、 常に著作権に関する微妙な問題が出てきます。 FreeBSD では、BSD または ISC といったフリーソフトウェアライセンスが好まれます。 GPLv2 のようなコピーレフトライセンスも、場合によっては許可されます。 完全なリストが、link:https://www.FreeBSD.org/jp/internal/software-license/[コアチームライセンスポリシ] ページにあります。
=== 金銭、ハードウェア
私たちは FreeBSD プロジェクトの目的を進めるための寄付を常に喜んで受け入れています。 私たちのようなボランティア活動では、 ちょっとしたことが大いに役立つのです! また一般的に、私たちは自前で周辺機器を買う資金が不足しているため、 周辺機器のサポートを充実させるのにハードウェアの寄付はとても重要です。
[[donations]]
==== 資金の寄付
The FreeBSD Foundation は、 FreeBSD プロジェクトの目標を推進するために設立された、 非営利の、税金を免除された財団です。501(c)3 に適合する団体として、 Foundation はアメリカ合衆国連邦所得税ならびに コロラド州所得税を一般に免除されています。免税団体への寄付は、 多くの場合連邦政府の課税対象所得から控除できます。
寄付は小切手で以下に送ってください。
[.address]
****
The FreeBSD Foundation +
P.O. Box 20247, +
Boulder, +
CO 80308 +
USA
****
また、寄付の受け付けを PayPal を通じて web 経由でできるようになりました。 寄付をするには、The FreeBSD Foundation の https://www.freebsdfoundation.org[web サイト]をぜひご覧ください。
The FreeBSD Foundation に関するこれ以上の情報は https://people.FreeBSD.org/~jdp/foundation/announcement.html[The FreeBSD Foundation -- an Introduction] を見てください。 Foundation への email での連絡は mailto:bod@FreeBSDFoundation.org[bod@FreeBSDFoundation.org] へどうぞ。
==== ハードウェアの寄贈
FreeBSD プロジェクトは適切な使い道のあるハードウェアの寄付を喜んで受け入れています。 ハードウェアを寄贈しようとしているなら、 link:https://www.FreeBSD.org/donations/[寄贈品受付事務局]に連絡してください。
[[ideas-contributing]]
== 他の分野で貢献するには？
この文書で説明されていないような他の別な興味のあることを探していますか？ FreeBSD プロジェクトの wiki ページには、 新しい貢献者がどのように始めたらよいかについてのアイディアが書かれています。
https://wiki.freebsd.org/JuniorJobs[Junior Jobs] ページには、FreeBSD を使はじめたばかりの人々や、 興味のあることから手始めにやってみたいと考えている方が興味を持ちそうなプロジェクトの一覧があります。
https://wiki.freebsd.org/IdeasPage[アイディアページ] には、プロジェクトに "あると便利" だったり、 "面白い" 作業の一覧があります。

529
documentation/content/ja/articles/fonts/_index.adoc Normal file
View file

@ -0,0 +1,529 @@
---
title: フォントと FreeBSD
subtitle: A Tutorial
authors:
- author: Bodenstab Dave [FAMILY Given]
email: imdave@synet.net
releaseinfo: "$FreeBSD$"
trademarks: ["freebsd", "adobe", "apple", "linux", "microsoft", "opengroup", "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: 例
include::shared/ja/urls.adoc[]
[.abstract-title]
概要
ここでは FreeBSD の syscons ドライバや X11, Ghostscript, Groff で利用することができるさまざまなフォントファイルについて説明しています。 また、syscons ディスプレイを 80x60 行モードに切り替える方法や、 上述のアプリケーションでタイプ 1 フォントを利用する方法を例示します。
'''
toc::[]
[[intro]]
== はじめに
数多くのフォントのソースを入手することができますが、これらを FreeBSD でどのようにして使うかはあまりよく知られていないかもしれません。 その答えは、使いたいと思う構成要素の説明書を注意深く探すことによって見つけることができます。 しかし、これはとても時間がかかる作業です。本チュートリアルは、 フォントに関して興味がある向きに、 その近道を教えようと試みるものであります。
[[terminology]]
== 基本用語
フォント形式の種類やそれに関連したフォントファイルの拡張子は多数存在します。 その内でここで解説するものは以下の通りです。
[.filename]#.pfa#、[.filename]#.pfb#::
PostScript(R) タイプ 1 フォント。拡張子 [.filename]#.pfa# は __A__scii 形式のそして拡張子 [.filename]#.pfb# は __B__inary 形式を意味する。
[.filename]#.afm#::
タイプ 1 フォントに関連するフォントメトリック情報。
[.filename]#.pfm#::
タイプ 1 フォントに関連するプリンタ用フォントメトリック情報。
[.filename]#.ttf#::
TrueType(R) フォント。
[.filename]#.fot#::
TrueType フォントへの間接的な参照ファイル (実際にはフォントファイルではない)。
[.filename]#.fon#、[.filename]#.fnt#::
スクリーン表示用ビットマップフォント。
[.filename]#.fot# ファイルは、Windows(R) で用いられ、 実際の TrueType(R) フォント ([.filename]#.ttf#) ファイルへのシンボリックリンクに類する役割を果たします。 [.filename]#.fon# フォントも Windows で用いられていますが、 FreeBSD でこの形式のフォントを利用する方法を筆者は知りません。
[[font-formats]]
== どのフォント形式を利用できますか?
どのフォントファイル形式が有用であるかは、 利用するアプリケーションに依ります。 FreeBSD 自身はフォントファイルは利用しません。 アプリケーションプログラムやドライバ (あるいはその両方) によっては、 あるフォントファイルを利用するようにできるかもしれません。 以下は、アプリケーション、及び、 ドライバとそれが利用できるフォントタイプの拡張子の対応表を簡単に示します。
ドライバ::
syscons:::
[.filename]#.fnt#
アプリケーション::
Ghostscript:::
[.filename]#.pfa#、 [.filename]#.pfb#、 [.filename]#.ttf#
X11:::
[.filename]#.pfa#、 [.filename]#.pfb#
Groff:::
[.filename]#.pfa#、 [.filename]#.afm#
Povray:::
[.filename]#.ttf#
拡張子 [.filename]#.fnt# は極めて頻繁に使われています。 (訳注: この拡張子がフォント (font) という名前から連想しやすいので) あるアプリケーションに特化したフォントを作成しようとした際にはいつでも、 この拡張子が選択される方がそうでないときよりもかなり多いのではないかと著者は疑っています。 このため、この拡張子を持つファイル全てが同じ形式にはなっていないようです。 特に、[.filename]#.fnt# ファイルは FreeBSD 上では syscons によって利用されていますが、これと MS-DOS(R) や Windows(R) 環境で出会った [.filename]#.fnt# とは同じ形式ではないかもしれません。 筆者は FreeBSD で提供されている以外の [.filename]#.fnt# ファイルを利用する試みは一切行っていません。
[[virtual-console]]
== 仮想コンソールを 80x60 行モードに設定する
まず、8x8 サイズのフォントがロードされていなくてはなりません。 そのためには、[.filename]#/etc/rc.conf# に以下の行が含まれているべきです (フォントの名称をあなたの locale に対応するものに書き換えてください)。
[.programlisting]
....
font8x8="iso-8x8" # font 8x8 from /usr/shared/syscons/fonts/* (or NO).
....
実際にモードを切り替えるコマンドは man:vidcontrol[1] です。
[source,bash]
....
% vidcontrol VGA_80x60
....
man:vi[1] のような、さまざまなスクリーン指向のプログラムに対して、 現在の画面サイズが分かるようにしておかなくてはなりません。これは `ioctl` を通じて (man:syscons[4] などの) コンソールドライバに呼び掛けることで行われ、
これらを一度に済ませるために、 これらのコマンドを起動用のスクリプトに書いておき、 これをシステム起動時に実行するかもしれません。 この方法では [.filename]#/etc/rc.conf# に以下の行を追加します
[.programlisting]
....
allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens
....
参考文献: man:rc.conf[5]、man:vidcontrol[1]
[[type1-fonts-x11]]
== タイプ 1 フォントを X11 で利用する
X11 では、 [.filename]#.pfa# 形式、もしくは、 [.filename]#.pfb# 形式のフォントのどちらでも利用できます。 X11 では、フォントは [.filename]#/usr/X11R6/lib/X11/fonts# 以下のさまざまなサブディレクトリに置かれています。 それぞれのディレクトリにある [.filename]#fonts.dir# ファイルの内容によって、 それぞれのフォントのファイルと X11 上でのフォント名が関連付けられています。
[.filename]#Type1# という名前のディレクトリが既に存在しています。 新しいフォントを追加する最も簡単な方法は、 このディレクトリのそのフォントファイルを置くことです。 新しいフォントは別なディレクトリに置いておき、[.filename]#Type1# ディレクトリに追加フォントへのシンボリックリンクを張る方がより優れています。 なぜなら、この方法をとることでオリジナルで供給されているフォントと混乱することなく、 これらのフォントを追加した跡を残すことがより簡単にできるからです。 この方法は、例えば、次のように行います。
[source,bash]
....
フォントファイルを入れるディレクトリを作成します。
% mkdir -p /usr/local/shared/fonts/type1
% cd /usr/local/shared/fonts/type1
ここに .pfa または .pfb ファイルと .afm ファイルを置きます。
フォントの readme ファイルやその他のドキュメントをこのディ
レクトリに置いても構いません。
% cp /cdrom/fonts/atm/showboat/showboat.pfb .
% cp /cdrom/fonts/atm/showboat/showboat.afm .
フォントのクロスリファレンスのためにインデックスを変更します。
% echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX
....
さて、新しいフォントを X11 で利用するためには、 そのフォントファイルを利用できるようにして、 フォント名のファイルを更新する必要があります。 X11 のフォント名は次のようになっています。
[source,bash]
....
-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1
| | | | | | | | | | | | \ \
| | | | | \ \ \ \ \ \ \ +----+- character set
| | | | \ \ \ \ \ \ \ +- average width
| | | | \ \ \ \ \ \ +- spacing
| | | \ \ \ \ \ \ +- vertical res.
| | | \ \ \ \ \ +- horizontal res.
| | | \ \ \ \ +- points
| | | \ \ \ +- pixels
| | | \ \ \
foundry family weight slant width additional style
....
新しいフォントそれぞれに対して、新しい名前を付ける必要があります。 フォント付属のドキュメントにフォントに関する情報があれば、 名前を作る際の基になるかもしれません。そのような情報がない場合は、 フォントに対して man:strings[1] を使うと何らかのアイデアが得ることができます。例えば、
[source,bash]
....
% strings showboat.pfb | more
%!FontType1-1.0: Showboat 001.001
%%CreationDate: 1/15/91 5:16:03 PM
%%VMusage: 1024 45747
% Generated by Fontographer 3.1
% Showboat
1991 by David Rakowski. Alle Rechte Vorbehalten.
FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup
/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse
{save true}{false}ifelse}{false}ifelse
12 dict begin
/FontInfo 9 dict dup begin
/version (001.001) readonly def
/FullName (Showboat) readonly def
/FamilyName (Showboat) readonly def
/Weight (Medium) readonly def
/ItalicAngle 0 def
/isFixedPitch false def
/UnderlinePosition -106 def
/UnderlineThickness 16 def
/Notice (Showboat
1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def
end readonly def
/FontName /Showboat def
--stdin--
....
この情報から、次のような名前が考えられます:
[source,bash]
....
-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
....
この名前の構成は次の通りです。
型 (foundry)::
新フォントは `type1` と名付けることにしましょう。
族 (family)::
フォントの名前です。
重み (weight)::
normal (普通)、bold (太い)、medium (中間)、 semibold (やや太め) などがあります。上記の man:strings[1] の出力より、 フォントの重みは _medium_ であると考えられます。
傾斜 (slant)::
__r__oman (ローマン体)、__i__talic (イタリック体)、__o__blique (斜字体) などがあります。 _ItalicAngle_ が0になっていることにより、 _roman_ を使っています。
幅::
normal (普通)、wide (幅広)、condensed (圧縮)、extended(拡張) などがあります。上記で調べた結果から、 _normal_ を仮定します。
追加スタイル::
通常は省略されますが、フォントに装飾用 (decorative) 英大文字が含まれていることをここで示します。
スペーシング::
proportional (プロポーショナル (訳注: 字形に応じて幅が変化するフォント)) または monospaced (単一幅フォント) があります。ここでは _Proportional_ としてありますが、これは _isFixedPitch_ が false (偽) になっているためです。
これらの名前は全て任意なのですが、 既存の慣習と互換性を保つよう努力すべきでしょう。 X11 プログラムでは、 フォントはワイルドカードを含んだ名前で参照されます。ですから、 フォント名は何らかの意味づけを持って選択されるべきでしょう。 (訳注 : 適当なフォントを探すとき、) ある人は単純に以下の名前を使うことから始めるかもしれません。
[source,bash]
....
...-normal-r-normal-...-p-...
....
そして、man:xfontsel[1] で該当するフォントを調べてみて、そのフォントの形を見ながら、 名前を調節するかもしれません。
それでは、ここまでの例を完結させることにしましょう。
[source,bash]
....
X11 に対してフォントをアクセスできるようにします。
% cd /usr/X11R6/lib/X11/fonts/Type1
% ln -s /usr/local/shared/fonts/type1/showboat.pfb .
fonts.dir と fonts.scale を編集して、フォントを記述する行を追加し、最初の行にある総フォント数を増やします。
% ex fonts.dir
:1p
25
:1c
26
.
:$a
showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
.
:wq
fonts.scale は fonts.dirと同一内容のようですので...
% cp fonts.dir fonts.scale
X11 に内容が変更されたことを伝えます。
% xset fp rehash
新しいフォントを試してみます。
% xfontsel -pattern -type1-*
....
参考文献: man:xfontsel[1]、man:xset[1]、The X Windows System in a Nutshell、link:http://www.ora.com/[O'Reilly & Associates]
[[type1-fonts-ghostscript]]
== タイプ 1 フォントを Ghostscript で利用する
Ghostscript では、 [.filename]#Fontmap# ファイルに従ってフォントを参照して います。このファイルを X11 の [.filename]#fonts.dir# ファイルと同様な方法で変更しなくてはなりません。 Ghostscript では、 [.filename]#.pfa# 形式または [.filename]#.pfb# 形式のフォントのいずれか一方を使用することができます。 前章の例で登場したフォントを使って、ここではこのフォントを Ghostscript で使用する方法について述べます。
[source,bash]
....
フォントを Ghostscript のフォントディレクトリに置きます。
% cd /usr/local/shared/ghostscript/fonts
% ln -s /usr/local/shared/fonts/type1/showboat.pfb .
Ghostscript にフォントを認識させるために Fontmap を編集します。
% cd /usr/local/shared/ghostscript/4.01
% ex Fontmap
:$a
/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat
.
:wq
Ghostscript を用いてフォントを試してみます。
% gs prfont.ps
Aladdin Ghostscript 4.01 (1996-7-10)
Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights
reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Loading Times-Roman font from /usr/local/shared/ghostscript/fonts/tir_____.pfb...
/1899520 581354 1300084 13826 0 done.
GS>Showboat DoFont
Loading Showboat font from /usr/local/shared/ghostscript/fonts/showboat.pfb...
1939688 565415 1300084 16901 0 done.
>>showpage, press <return> to continue<<
>>showpage, press <return> to continue<<
>>showpage, press <return> to continue<<
GS>quit
....
参考文献: Ghostscript バージョン 4.01 で配布されている [.filename]#fonts.txt#
[[type1-fonts-groff]]
== タイプ 1 フォントを Groff で利用する
ここまでで新しいフォントを X11 と Ghostscript の両方で用いることができるようになりましたが、 この新しいフォントをどのようにすれば Groff で使うことができるでしょうか? まず第一に、PostScript(R) のタイプ 1 フォントを扱っていますから、 これを適用できる Groff デバイスは _ps_ デバイスです。次に、各々のフォントを Groff で使用できるようにフォントファ イルを作らなくてはなりません。 Groff でのフォント名は [.filename]#/usr/shared/groff_font/devps# の中のファイル名になります。上述の例では、フォントファイルは [.filename]#/usr/shared/groff_font/devps/SHOWBOAT# とすることができるでしょう。このファイルは Groff によって提供されているツールを用いて生成しなくてはなりません。
最初に `afmtodit` というツールを使います。 このコマンドは通常ではインストールされませんので、 ソースプログラム群から該当プログラムを取り出さなくてはなりません。 このファイルの最初の一行を変更しなくてはならないことが分かっています。 著者は次のようにしました。
[source,bash]
....
% cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp
% ex /tmp/afmtodit.pl
:1c
#!/usr/bin/perl -P-
.
:wq
....
このツールはメトリックファイル ([.filename]#.afm# 拡張子) から Groff フォントファイルを生成してくれます。 フォント使用方法例を続けることにしましょう。
[source,bash]
....
.afm ファイルの多くは Mac 形式... すなわち行が ^M で区切られています。
これを行を ^J で区切る UNIX(R) スタイルに変換する必要があります。
% cd /tmp
% cat /usr/local/shared/fonts/type1/showboat.afm |
tr '\015' '\012' >showboat.afm
そして、groff フォントファイルを生成します。
% cd /usr/shared/groff_font/devps
% /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT
....
これでフォントを SHOWBOAT という名前で参照することができました。
システムでプリンタを扱うために Ghostscript を使用しているならば、 これで作業は完了しました。しかしながら、本物の PostScript(R) プリンタを使っている場合は、フォントを使用可能にする為に、 当該フォントをプリンタにダウンロードする必要があります (showboat フォントがプリンタに偶然にも最初から組み込まれている場合、 もしくはプリンタからアクセスされるフォントディスクの中に入ってい る場合はこの限りではありません)。 フォント利用の最終段階として、 ダウンロード可能な形式のフォントを生成します。 ツール `pfbtops` は (訳注 : [.filename]#.pfb# 形式から) [.filename]#.pfa# 形式のフォントを生成するために、そして、 [.filename]#download# というファイルを編集し、 フォントの内部名を参照するように変更しなくてはなりません。 この内部名は以下で示すように groff フォントファイルから容易に調べることができます。
[source,bash]
....
.pfa フォントファイルを生成する。
% pfbtops /usr/local/shared/fonts/type1/showboat.pfb >showboat.pfa
....
もちろん、[.filename]#.pfa# が既に利用可能であれば、 参照できるようにシンボリックリンクを張って下さい。
[source,bash]
....
内部フォント名を得る。
% fgrep internalname SHOWBOAT
internalname Showboat
該当フォントをダウンロードしなくてはならないことを groff に通知する。
% ex download
:$a
Showboat showboat.pfa
.
:wq
....
フォントを試用する。
[source,bash]
....
% cd /tmp
% cat >example.t <<EOF
.sp 5
.ps 16
This is an example of the Showboat font:
.br
.ps 48
.vs (\n(.s+2)p
.sp
.ft SHOWBOAT
ABCDEFGHI
.br
JKLMNOPQR
.br
STUVWXYZ
.sp
.ps 16
.vs (\n(.s+2)p
.fp 5 SHOWBOAT
.ft R
To use it for the first letter of a paragraph, it will look like:
.sp 50p
\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the
showboat font as its first letter.
Additional vertical space must be used to allow room for the larger
letter.
EOF
% groff -Tps example.t >example.ps
ghostscript/ghostviewを使って表示する。
% ghostview example.ps
印刷する (訳注 : プリンタ名は適宜変更して下さい)。
% lpr -Ppostscript example.ps
....
参考文献: [.filename]#/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man#、 man:groff_font[5]、man:groff_char[7]、man:pfbtops[1]
[[convert-truetype]]
== TrueType フォントを groff 用に groff/PostScript フォーマットに変換する
これにはいくつかユーティリティが必要ですが、 ベースシステムの一部としてインストールされてはいないので若干の作業が必要となります。 インストールするものは:
`ttf2pf`::
TrueType から PostScript への変換ユーティリティです。 これは TrueType フォントからアスキーフォントメトリック ([.filename]#.afm#) ファイルへの変換を行います。
+
現時点では http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/[http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/] から入手できます。 注意: これらのファイルは PostScript によるプログラムなので、 kbd:[Shift] キーを押しながらリンクをクリックして ディスクにダウンロードしてください。 さもないとあなたのブラウザは ghostview を立ちあげます。
+
重要なファイルは:
** [.filename]#GS_TTF.PS#
** [.filename]#PF2AFM.PS#
** [.filename]#ttf2pf.ps#
+
大文字と小文字が奇妙に混在しているのは、 DOS シェルのことも考慮しているためです。 [.filename]#ttf2pf.ps# はそれ以外のファイルを 大文字として扱いますので、 ファイル名の変更はそれに対応させてください (実際には [.filename]#GS_TTF.PS# と [.filename]#PFS2AFM.PS# は、一応 Ghostscript の配布物の一部ですが、 個別のユーティリティとしても問題なく利用できます。 FreeBSD には後者が入っていないようです)。 [.filename]#/usr/local/shared/groff_font/devps# にインストールするとよいかもしれません。
`afmtodit`::
はアスキーフォントメトリックファイルから Groff とともに使うフォントファイルを作ります。 これは通常、 [.filename]#/usr/src/contrib/groff/afmtodit# ディレクトリに存在していて、 使えるようにするには作業が必要です。
+
[NOTE]
====
もしも [.filename]#/usr/src# ツリーで作業をすることを躊躇うなら、 このディレクトリの内容を作業用の場所にコピーすればいいです。
====
+
作業エリアで以下のようにしてこのユーティリティします。
+
[source,bash]
....
# make -f Makefile.sub afmtodit
....
+
もし、まだ存在していなければ [.filename]#/usr/contrib/groff/devps/generate/textmap# を [.filename]#/usr/shared/groff_font/devps/generate# にコピーします。
これらのユーティリティが所定の場所に収まったら いつでも開始できます。
. [.filename]#.afm# ファイルを以下のようにして作ります。
+
[source,bash]
....
% gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name
....
+
ここで、_TTF_name_ はあなたの TrueType フォントの名前で、_PS_font_name_ は [.filename]#.pfa# ファイルのためのファイル名で、 _AFM_name_ は [.filename]#.afm# ファイルに望む名前です. [.filename]#.pfa# や [.filename]#.afm# 用の出力ファイル名を明示しなければ、 デフォルト名は TrueType フォントファイル名から作成されます。
+
この時、アスキー PostScript フォントメトリックファイルである [.filename]#.pfa# ファイルも同時に作られます ([.filename]#.pfb# はバイナリ形式です)。 これは不要となるでしょうが、(私が考えるに) フォントサーバには役立つでしょう。
+
例として、30f9 バーコードフォントをデフォルトのファイル名で変換するには以下のようにします。
+
[source,bash]
....
% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf
Aladdin Ghostscript 5.10 (1997-11-23)
Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Converting 3of9.ttf to 3of9.pfa and 3of9.afm.
....
+
変換後のフォントを [.filename]#A.pfa# と [.filename]#B.afm# にするなら以下のようにします。
+
[source,bash]
....
% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B
Aladdin Ghostscript 5.10 (1997-11-23)
Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Converting 3of9.ttf to A.pfa and B.afm.
....
. Groff PostScript ファイルを作ります。
+
以下のコマンドの実行が用意なように [.filename]#/usr/shared/groff_font/devps# に ディレクトリを変更します。 恐らく root 特権が必要になるでしょう (そこでの作業が気にいらないなら、このディレクトリの [.filename]#DESC#、 [.filename]#text.enc#、 [.filename]#generate/textmap# ファイルが参照されるということに注意してください)。
+
[source,bash]
....
% afmtodit -d DESC -e text.enc file.afm \
generate/textmap PS_font_name
....
+
ここで、[.filename]#file.afm# は _AFM_name_ で、上で `ttf2pf.ps` で作ったものです。 _PS_font_name_ はコマンドから使われるフォント名で、 man:groff[1] がこのフォントを参照するために使うものです。 たとえば、最初の `tiff2pf.ps` コマンドを上述のように行っていたとすると、 3of9 バーコードフォントは以下のコマンドで作成できます。
+
[source,bash]
....
% afmtodit -d DESC -e text.enc 3of9.afm \
generate/textmap 3of9
....
+
得られる _PS_font_name_ ファイル (この例では [.filename]#3of9#) はディレクトリ [.filename]#/usr/shared/groff_font/devps# に、コピーするなり移動するなりして置かれることに気をつけてください。
+
[.filename]#ttf2pf.ps# がわりつけるフォント名は TrueType フォントファイル中に見つかったものになります。 それとは異なる名前を使いたかったら、 [.filename]#.afm# ファイルを編集してから `afmtodit` を実行する必要があります。 man:groff[1] から man:gs[1] へパイプするつもりならば、 その名前は同時にフォントマップファイルで使われているものである必要があります。
[[truetype-for-other-programs]]
== TrueType フォントを他のプログラムで使うことができますか?
TrueType フォント形式は Windows、Windows 95、Mac で用いられます。この形式は極めて有名であり、 非常にたくさんのフォントが利用できます。
残念ながら、この形式を (訳注: FreeBSD で) この形式を利用でき るアプリケーションは、筆者が知る限りほとんどなく、 Ghostscript と Povray しか思いつきません。 ドキュメントによれば、Ghostscript の 対応は不十分であり、タイプ 1 フォントより粗悪な結果になるようです。 Povray バージョン 3 もまた TrueType フォントを利用可能ですが、筆者は、ドキュメントを一連のレイトレー スしたページとして作成する人が多いのではないかと疑っています :-)。
このなんとも悲惨な状況は変わりつつあります。 http://www.freetype.org/[FreeType プロジェクト] では FreeType の便利なツールを開発しています。
* XFree86 4.x に含まれている freetype モジュール。 詳細は link:{handbook}#x-fonts[FreeBSD ハンドブック] か http://www.xfree86.org/4.0.2/fonts.html[XFree86 4.0.2 Fonts] ページを見てください。
* X11 用の xfsft フォントサーバは 一般のフォントに加えて TrueType フォントを提供します。 現在ベータ版であるにもかかわらずたいへん評判がいいものです。 詳しくは http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/[Juliusz Chroboczek's page] をごらんください。 FreeBSD への移植についての情報は http://math.missouri.edu/~stephen/software/[Stephen Montgomery's software page] にあります。
* xfstt は X11 用のもうひとつのフォントサーバで、 link: ftp://sunsite.unc.edu/pub/Linux/X11/fonts/[ftp://sunsite.unc.edu/pub/Linux/X11/fonts/] から入手できます。
* `ttf2bdf` というプログラムは、 X の環境下で TrueType フォントのセットから BDF 形式のファイルを作るものです。 Linux 用のバイナリが link:ftp://crl.nmsu.edu/CLR/multiling/General/[ftp://crl.nmsu.edu/CLR/multiling/General/] から 入手できます。
* そしてその他 ...
[[obtaining-additional-fonts]]
== どこでフォントを入手できますか?
インターネット上でたくさんのフォントを利用することができます。 これらは完全に無料であるか、シェアウェアです。加えて、 たくさんのフォントが収録されたあまり高価ではない CDROM がたくさんあります。インターネットでのアクセスポイント (1996年8月現在)を以下に示します。
* http://www.simtel.net/[http://www.simtel.net/]
* http://www.freshmeat.net/[http://www.freshmeat.net/]
* Ports Collection の [.filename]#x11-fonts/#
[[additional-questions]]
== その他の質問
* [.filename]#.pfm# ファイルを利用するものはあるのか?
* [.filename]#.afm# ファイルを [.filename]#.pfa# もしくは [.filename]#.pfb# から作成できるか?
* 非標準キャラクタ名がある PostScript フォントを Groff キャラクタにマッピングする ファイルをどのように作成するか?
* xditview と devX?? デバイスで新たなファイル全てにアクセスするためのセットアップをすることができるか?
* Povray と Ghostscript で TrueType フォントを利用する例があるといいだろう。

264
documentation/content/ja/articles/ipsec-must/_index.adoc Normal file
View file

@ -0,0 +1,264 @@
---
title: FreeBSD の IPsec 機能を独立検証するには
authors:
- author: Honig David [FAMILY Given]
email: honig@sprynet.com
releaseinfo: "$FreeBSD$"
trademarks: ["freebsd", "opengroup", "general"]
---
= FreeBSD の IPsec 機能を独立検証するには
:doctype: article
:toc: macro
:toclevels: 1
:sectnumlevels: 6
:icons: font
:sectnums:
:source-highlighter: rouge
:experimental:
:toc-title: 目次
:part-signifier: パート
:chapter-signifier: 第
:appendix-caption: 付録
:table-caption: 表
:figure-caption: 図
:example-caption: 例
include::shared/ja/urls.adoc[]
[.abstract-title]
概要
IPsec をインストールした時、 それがきちんと動作しているかどうか調べるにはどうしたら良いでしょう? ここでは、IPsec の動作を検証する実験的な方法を紹介します。
'''
toc::[]
[[problem]]
== 問題
まず、<<ipsec-install>>を前提に話を進めます。 IPsec が<<caveat>>かどうか知るにはどうしたら良いでしょう? もちろん設定が間違っていればネットワーク接続が行なえないでしょうし、 接続できたということは設定が合っているからだ、という認識は間違っていません。 接続状態は man:netstat[1] コマンドで確かめることができます。 しかし、それを独立して検証することは可能なのでしょうか?
[[solution]]
== 解決方法
最初に、暗号に使われている情報理論について考えます。
. 暗号化されたデータは、一様に分布している。つまり、 各情報源シンボルは最大のエントロピーを持っている。
. 通常、未処理のデータや圧縮されていないデータは冗長である。 つまり、各情報源シンボルのエントロピーは最大ではない。
ネットワークインターフェイスを入出力するデータのエントロピーを測定できると仮定すると、 「暗号化されていないデータ」と「暗号化されたデータ」の両者に、 違いを見ることができるはずです。 このことは、パケットのルーティングが行なわれる場合の一番外側の IP ヘッダなど、 データの一部が "暗号化モード" で暗号化されなかったとしても成立します。
[[MUST]]
=== MUST
Ueli Maurer 氏の "Universal Statistical Test for Random Bit Generators" (http://www.geocities.com/SiliconValley/Code/4704/universal.pdf[MUST]) は、サンプルデータのエントロピーを高速に測定します。 これには圧縮と良く似たアルゴリズムが使われています。 <<code>>、 一つのファイル中で連続するデータ (最大 0.25 メガバイト) を測定するコードです。
[[tcpdump]]
=== Tcpdump
さて次に、上記に加えてネットワーク上の生データを捕捉するための手段も必要になります。 それを実現するプログラムに、man:tcpdump[1] と呼ばれるものがあります。 ただし、tcpdump を使うには、 <<kernel>>において _Berkeley Packet Filter_ インターフェイスが有効化されていなければなりません。
次のコマンド:
[source,bash]
....
tcpdump -c 4000 -s 10000 -w dumpfile.bin
....
は、4000 個の生パケットを捕捉し、_dumpfile.bin_ に記録します。 この例のでは 10,000 バイト以下のパケットのみ記録されます。
[[experiment]]
== 実験
では、実験してみましょう。
[.procedure]
====
. IPsec ホストと IPsec を使っていないホストの両方にネットワーク接続してください。
. そして <<tcpdump>>を開始します。
. 次に、"IPsec を使っている" 接続で man:yes[1] という UNIX(R) コマンドを実行します。 これは、`y` という文字の連続データを出力するものです。 しばらくしたらコマンドを停止させ、IPsec を使っていない接続に対して同じコマンドを実行します。 こちらも、しばらくしたらコマンドを停止させてください。
. ここで、<<code>> を捕捉したパケットに実行すると、次のような出力が得られるはずです。 この中で重要なのは、期待値 (7.18) に対して、 IPsec を使った接続が 93% (6.7)、 "通常の"接続が 29% (2.1) という結果になっていることです。
+
[source,bash]
....
% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin
% uliscan ipsecdemo.bin
Uliscan 21 Dec 98
L=8 256 258560
Measuring file ipsecdemo.bin
Init done
Expected value for L=8 is 7.1836656
6.9396 --------------------------------------------------------
6.6177 -----------------------------------------------------
6.4100 ---------------------------------------------------
2.1101 -----------------
2.0838 -----------------
2.0983 -----------------
....
====
[[caveat]]
== 注意
この実験は暗号化の理論が示すとおり、IPsec を使った通信では__確かに__ペイロード中のデータに含まれるシンボルの生起確率が__一様に__分布する、 ということを示しています。 しかし、ここで示した実験ではシステム上の欠陥 (あるのかどうか知りませんが) を検出することは__できません__。 ここで言う「欠陥」とは、たとえば暗号鍵生成や交換の不備や、 データや暗号鍵が他人に見られていないかどうかといった問題、 あるいはアルゴリズムの強度はどうか、 カーネルのバージョンは合っているかといったことです。 これらはソースを調べれば確かめることができます。
[[IPsec]]
== IPsec の定義
インターネットプロトコル セキュリティ拡張 (Internet Protocol security extensions) は IP v4 と IP v6 に適用され、IP v6 への実装は必須となっています。 このプロトコルは IP (ホスト間) レベルで暗号化と認証を実現するためのものです。 たとえば SSL は一つのアプリケーションソケット、SSH はログイン、 PGP は特定のファイルやメッセージのみに対してそれぞれ安全性を提供しますが、 IPsec は 2 ホスト間のすべての通信を暗号化します。
[[ipsec-install]]
== IPsec のインストール
FreeBSD の最近のバージョンでは IPsec のサポートが基本のソースコードに含まれています。 それ故、あなたはおそらく `IPSEC` オプションをカーネルコンフィグファイルに追加し、 カーネルを再構築/再インストールして man:setkey[8] コマンドで IPsec 接続を設定すればよいはずです。
FreeBSD で IPsec を実行する包括的なガイドは link:{handbook}#ipsec[FreeBSD ハンドブック] で提供されています。
[[kernel]]
== src/sys/i386/conf/KERNELNAME
ネットワークデータを man:tcpdump[1] で補足するためにはカーネルコンフィグファイルには以下の行が必要です。 追加後 man:config[8] を実行しカーネルの再構築/再インストールを 行なってください。
[.programlisting]
....
device bpf
....
[[code]]
== Maurer's Universal Statistical Test (ブロックサイズ = 8 ビット)
同一のコードを http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt[ このリンク]から入手することができます。
[.programlisting]
....
/*
ULISCAN.c ---blocksize of 8
1 Oct 98
1 Dec 98
21 Dec 98 uliscan.c derived from ueli8.c
This version has // comments removed for Sun cc
This implements Ueli M Maurer's "Universal Statistical Test for Random
Bit Generators" using L=8
Accepts a filename on the command line; writes its results, with other
info, to stdout.
Handles input file exhaustion gracefully.
Ref: J. Cryptology v 5 no 2, 1992 pp 89-105
also on the web somewhere, which is where I found it.
-David Honig
honig@sprynet.com
Usage:
ULISCAN filename
outputs to stdout
*/
#define L 8
#define V (1<<L)
#define Q (10*V)
#define K (100 *Q)
#define MAXSAMP (Q + K)
#include <stdio.h>
#include <math.h>
int main(argc, argv)
int argc;
char **argv;
{
FILE *fptr;
int i,j;
int b, c;
int table[V];
double sum = 0.0;
int iproduct = 1;
int run;
extern double log(/* double x */);
printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP);
if (argc < 2) {
printf("Usage: Uliscan filename\n");
exit(-1);
} else {
printf("Measuring file %s\n", argv[1]);
}
fptr = fopen(argv[1],"rb");
if (fptr == NULL) {
printf("Can't find %s\n", argv[1]);
exit(-1);
}
for (i = 0; i < V; i++) {
table[i] = 0;
}
for (i = 0; i < Q; i++) {
b = fgetc(fptr);
table[b] = i;
}
printf("Init done\n");
printf("Expected value for L=8 is 7.1836656\n");
run = 1;
while (run) {
sum = 0.0;
iproduct = 1;
if (run)
for (i = Q; run && i < Q + K; i++) {
j = i;
b = fgetc(fptr);
if (b < 0)
run = 0;
if (run) {
if (table[b] > j)
j += K;
sum += log((double)(j-table[b]));
table[b] = i;
}
}
if (!run)
printf("Premature end of file; read %d blocks.\n", i - Q);
sum = (sum/((double)(i - Q))) / log(2.0);
printf("%4.4f ", sum);
for (i = 0; i < (int)(sum*8.0 + 0.50); i++)
printf("-");
printf("\n");
/* refill initial table */
if (0) {
for (i = 0; i < Q; i++) {
b = fgetc(fptr);
if (b < 0) {
run = 0;
} else {
table[b] = i;
}
}
}
}
}
....

79
documentation/content/ja/articles/leap-seconds/_index.adoc Normal file
View file

@ -0,0 +1,79 @@
---
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: 例
include::shared/ja/urls.adoc[]
'''
toc::[]
[[leapseconds-definition]]
== イントロダクション
__leap second__(閏秒)は地球の自転と時刻を同期させるために使用される特別な秒のことです。この記事はFreeBSDがどのように閏秒を扱っているかを解説します。
執筆段階ですと、次に閏秒を挿入するのは協定世界時で2015年6月30日 23時59分60秒になります。この閏秒は北アメリカ、南アメリカ、アジア太平洋地域の営業日に実施されます。
閏秒はlink:http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16[Bulletin C]におけるlink:http://datacenter.iers.org/[IERS]において発表されています。
閏秒の一般的な動作に関しては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 (協定世界時)での真夜中に世界中で同時に挿入されます。日本では午前の半ば、太平洋地域では日中、米国では午後の遅いタイミング、欧州は夜です。
FreeBSDでは適切で安定した NTP サービスが提供されていれば先ほど説明したように閏秒のタイミングで設計通りに処理が行われることになると思います。
しかしながら、実際のところカーネルに対して閏秒について尋ねてくるアプリケーションは存在しないことに注意してください。我々の経験からしますと、想定されているように、閏秒の処理は閏秒のタイミングで1秒を1度繰り返すというもので、これはほとんどのアプリケーションプログラマにとっては想定していないものだと思います。
FreeBSDと同じ方法で閏秒を処理しているしていないに関わらずほかのオペレーティングシステムやほかのコンピュータと、適切で安定した NTP サービスを使用していないシステムは閏秒に関してはまったく関知してくれません。
コンピュータが閏秒が原因でクラッシュするという話は聞いたことがありませんが、経験からしますとパブリックに利用されている NTP サーバの一部は不適切に閏秒を処理して報告をおこなっています。
閏秒が原因でなにか問題が発生しないことを確認するようにしてください。
[[leapseconds-testing]]
== テスト方法
閏秒が使われるかどうかをテストする方法があります。NTP の特性から、テストは閏秒が発生する24時間前から行います。いくつかの有名な時刻の参照ソースは閏秒発生の1時間前にアナウンスを行います。NTP デーモンに次のクエリを発行します:
[source,bash]
....
% ntpq -c 'rv 0 leap'
....
``leap_add_sec``インディケータを含んだ出力は閏秒を適切にサポートしていることを意味しています。閏秒が発生するよりも24時間前、または閏秒が発生した後には``leap_none``が表示されます。
[[leapseconds-conclusion]]
== 結論
実際のところ、閏秒がFreeBSDで問題になることはありません。この要約がどのように閏秒の処理で何が行われるのか、どうやって閏秒の処理を問題なく済ませればよいのかという考えを明確にする手助けになればと思います。

247
documentation/content/ja/articles/problem-reports/_index.adoc Normal file
View file

@ -0,0 +1,247 @@
---
title: FreeBSD 障害報告の書き方
authors:
- author: Smørgrav Dag-Erling [FAMILY Given]
- author: Linimon Mark [FAMILY Given]
releaseinfo: "$FreeBSD$"
trademarks: ["freebsd", "ibm", "intel", "sun", "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: 例
include::shared/ja/mailing-lists.adoc[]
include::shared/ja/urls.adoc[]
[.abstract-title]
概要
この記事では、明瞭な障害報告 (Problem Report: PR) を FreeBSD プロジェクトに提出する方法を解説します。
'''
toc::[]
[[pr-intro]]
== はじめに
ソフトウェアの利用者として経験するもっともいらただしいことの一つは、 "それはバグじゃない"、"ひどい障害報告だ" などのようなそっけなく理解の役に立たない説明によって、 障害報告があっさり片付けられてしまうことです。 同様に、ソフトウェア開発者が経験するもっともいらだたしいことの一つは、 実際は障害報告ではない単なるサポート要求や、 何が問題でどのように再現するかについての情報が乏しい、 または欠落している障害報告が殺到することです。
この記事のねらいは、上手な障害報告の書き方について説明することです。 上手な障害報告とはどういうものでしょうか? そうですね、単刀直入に要点を言えば、 上手な障害報告とは、迅速に解析を進め処理を行うことができ、 利用者と開発者がお互いに満足できるものです。
この記事では主として FreeBSD の障害報告に焦点を絞っていますが、 他のソフトウェアプロジェクトでも多くの部分が当てはまるでしょう。
この記事はテーマ別に整理されており、 順番に読めるようにはなっていません。 段階を踏んだチュートリアルとして利用するのではなく、 障害報告を提出する前に全体を通して読むべきです。
[[pr-when]]
== いつ障害報告を提出すればよいのか
問題にはさまざまな種類がありますが、 それらすべてが障害報告に値するわけではありません。 もちろん、誰しもが完璧ではありませんので、 実際はコマンドの構文を勘違いしていたり、 設定ファイルを書き間違えているのに、 プログラムにバグを見つけた! と思い込んでしまうことがあるでしょう (とは言っても、それ自身、文書が適切に記述されていなかったり、 アプリケーションのエラー処理が甘いことを暗示している可能性があります)。 それ以外にも、 障害報告を提出することが正しい行動では__なく__、 あなたと開発者両方に不満を抱かせるだけという場合があります (訳注: はっきりと把握していないことを報告すべきではありません。 要領を得ない障害報告は扱いにくいものです)。 逆に、バグではありませんが障害報告を提出するのにふさわしい場合もあります - たとえば、既存機能の拡張や新しい機能の搭載のようなものです。
では、何がバグで何がバグでないのか、 どのようにして決めれば良いでしょうか? 簡単な経験則では、それを質問として (よくあるのは "どうすれば X できますか?" や "Y はどこで見つけることができますか?" のような形式で) 表現できるなら、問題はバグでは__ありません__。 いつも白黒がつけられるわけではありませんが、 この質問規則は大半の場合にあてはまります。 もし、このような質問に対する答えを求めているのなら、 {freebsd-questions} で質問してみてください。
[NOTE]
====
{freebsd-questions} へのメールは英語でお願いします。 日本語での質問は、{users-jp} や http://www.flathill.gr.jp/~flathill/FreeBSD/FreeBSD-beginners-jp.html[FreeBSD-beginners-jp メーリングリスト] などに送ってください。
====
ports または FreeBSD の一部ではない他のソフトウェアに関する障害報告を提出する際には、 以下に注意してください。
* あるアプリケーションの新しいバージョンが利用可能という情報を知らせるだけの障害報告は提出しないでください。 ports のメンテナは、新しいバージョンが利用になった際には、 自動的に portscout から連絡を受けています。 もちろん port を最新版へアップデートするためのパッチの提出は歓迎されます。
* メンテナンスされていない ports (`MAINTAINER` が `ports@FreeBSD.org` の ports) に対するパッチが添付されていない障害報告は、 コミッタからは取り上げられにくいものです。 メンテナンスされていない port のメンテナになるには、 リクエストの障害報告を提出してください (パッチがあることは好ましいですが、必須ではありません)。
* いずれの場合も、link:{porters-handbook}#port-upgrading[Port 作成者のためのハンドブック] で説明されている手順がもっともよい結果をもたらします (link:{contributing}#ports-contributing[Contributing to the FreeBSD Ports Collection] という文書も読んでみたいと思われるかもしれませんね)。
再現することができないバグは、めったに直すことができません。 もし、バグが一度だけ発生してそれが再現できないもので、 なおかつ他の人のシステムでも起こらないようであれば、 開発者がそれを再現できる可能性も、 何が悪いのかわかる可能性もありません。 これはバグが起こらなかったことを意味するわけではありません。 しかし、このような状況では、 あなたの障害報告がバグの修正につながる見込みは非常に薄いものです。 おまけに、この手のバグは実際は故障したハードディスクや過熱した CPU が原因で起きていることが多いのです (障害報告を提出する前には必ず、可能なら、 こうした原因を排除するよう努めるべきです)。
次に、誰に障害報告を提出するか決めます。 そのためには、FreeBSD を構成するソフトウェアがさまざまな要素で構成されていることを知っておく必要があります。
* ベースシステムのコードで、FreeBSD への貢献者によって書かれ、維持されているもの。 たとえば、カーネル、C ライブラリやデバイスドライバ (`kern` に分類されているもの)、 バイナリユーティリティ (`bin`)、 マニュアルページや文書 (`docs`) やウェブページ (`www`) があります。 この領域のバグは全て FreeBSD 開発者に報告してください。
* それ以外の人によって書かれ、維持されているベースシステムのコードで、 FreeBSD に取り込まれ、FreeBSD に合わせて変更されているもの。 たとえば、man:clang[1] や man:sendmail[8] があります。 この領域のバグのほとんどは FreeBSD 開発者に報告すべきですが、 問題が FreeBSD 特有でない場合には、 おおもとの作者に報告してください。
* ベースシステムではなく FreeBSD Ports Collection (`ports` カテゴリ) の一部である個別のアプリケーション。 そのほとんどは FreeBSD が書いたものではありません。 FreeBSD が提供しているのは、 単なるアプリケーションをインストールする枠組みです。 したがって、問題が FreeBSD 特有であると考えられる場合にだけ FreeBSD 開発者に報告してください。 それ以外は、そのソフトウェアの開発者に連絡してください。
それから、問題が時宜を得たものかを確認してください。 既に修正したバグに関する障害報告を受けとることほど開発者を悩ませるものはまずありません。
ベースシステムの問題で、FreeBSD のバージョンについてよく分かっていないなら、まず FAQ の link:{faq}#LATEST-VERSION[FreeBSD バージョン] に関する節を読んでください。 FreeBSD では、 ベースシステムのいくつかの最新ブランチ以外は修正できません。 そのため、古いバージョンについて障害報告を提出しても、 開発者からは、問題がまだ起きるかどうかを確認するために、 サポートされているバージョンにアップグレードするように勧められるだけかもしれません。 セキュリティオフィサチームが、 link:https://www.FreeBSD.org/security/[ サポートされているバージョンの一覧] を管理しています。
ある port に問題がある場合、 開発元にバグを報告することを考えて見てください。 すべてのソフトウェアのすべてのバグに対し、FreeBSD プロジェクトが修正することは不可能です。
[[pr-prep]]
== 準備
従うべき良い規則は、 障害報告を提出する前に常に問題の背景を調べることです。 あなたの問題はすでに報告されているかもしれません。 また、メーリングリストで議論されている最中か、 最近議論されていたかもしれません。 あなたが動かしているものより新しいバージョンで、 既に修正済みということすらありえます。 ですから、障害報告を提出する前に自明な場をすべて確認すべきです。 FreeBSD では、以下になります。
* FreeBSD の link:{faq}[よくある質問とその答え] (FAQ) 一覧。FAQ は、link:{faq}#hardware[ハードウェア互換性]、link:{faq}#applications[ユーザアプリケーション] や link:{faq}#kernelconfig[カーネルコンフィグレーション] といったことに関する広い範囲の質問に対して答を示そうとしています。
* link:{handbook}#eresources-mail[メーリングリスト]。 - メーリングリストを購読していなければ、 FreeBSD のウェブサイトにある https://www.FreeBSD.org/ja/search/search/#mailinglists[アーカイブ検索]を使ってください。 もし、メーリングリストで議論がされていなければ、 自分の問題についてのメッセージを送ってみて、 見落とした点を誰かが見つけてくれるかどうか、 数日間待ってみると良いでしょう。
* ウェブ全体を検索する (任意)。- あなたの問題に関係する話題がないかどうかを、 お気に入りの検索エンジンを使って探してください。 あなたが知りもしなかったか、 検索しようと考えなかったメーリングリストやニュースグループのアーカイブにあたることもあるかもしれません。
* 次に、検索可能な https://bugs.freebsd.org/bugzilla/query.cgi[FreeBSD 障害報告データベース] (Bugzilla) があります。 あなたの問題が新しいものでも不明瞭でもなければ、 既に報告されている可能性がかなり高いです。
* 何よりもまず、 元となるソースコード内のドキュメントで、 あなたの問題が触れられていないどうかを調べてみてください。
+
FreeBSD の基本部分のコードについては、 システムの [.filename]#/usr/src/UPDATING# の内容か、link:https://svnweb.freebsd.org/base/head/UPDATING?view=log[https://svnweb.freebsd.org/base/head/UPDATING?view=log] にある最新版をよく調べるべきです (あるバージョンから別のバージョンにアップグレードしようとしているのであれば -特に `-current` ブランチに上げようとしているなら、 これは非常に重要な情報です)。
+
しかし、問題が FreeBSD Ports Collection からインストールされたものにあるのであれば、 [.filename]#/usr/ports/UPDATING# (個別の ports) または [.filename]#/usr/ports/CHANGES# (Ports Collection 全体に影響する変更) を参照すべきです。link:https://svnweb.freebsd.org/ports/head/UPDATING?view=log[https://svnweb.freebsd.org/ports/head/UPDATING?view=log] と https://svnweb.freebsd.org/ports/head/CHANGES?view=log[https://svnweb.freebsd.org/ports/head/CHANGES?view=log] は svnweb からも参照できます。
[[pr-writing]]
== 障害報告の書き方
問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したら、 実際に障害報告を執筆する時です。 障害報告を作成して送信するプログラムの仕組みに入る前に、 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。
[[pr-writing-tips]]
== よい障害報告を書くこつ
* _"Summary"(概要) 行を空のままにしないでください。_ 障害報告は、世界中に配布されるメーリングリストに送られる (そこでは、"Summary" (概要) は `Subject:` 行に使われます) と共に、 データベースにも登録されます。後でデータベースを synopsis (概要) で参照する人は、 題がついていない障害報告は単に無視することでしょう。 このデータベースに登録された障害報告は、 誰かが対応済にするまでは残っていることを忘れないでください。 内容不明のものは大抵雑音に埋もれてしまいます。
* _わかりにくい "Summary" (概要) 行は避けましょう。_ あなたが提出した障害報告を読む人がどういう状況か分かっていると仮定すべきではありません。 できるだけ詳しく書きましょう。 たとえば、その問題はシステムのどの部分にあてはまるのでしょうか。 インストール中にしか問題に当たらないのか、それとも稼働中に当たるのか。 具体的な例でいうなら、 `Summary: portupgrade is broken` (概要: portupgrade がおかしい) ではなく、 次のように書いたらどれだけ伝わりやすいか考えてみてください。 `Summary: port ports-mgmt/portupgrade coredumps on -current` (概要: sysutils/portupgrade port が -current でコアダンプします)。(ports の場合は、 "Summary" (概要) 行に分類と名前を入れると、 とても助かります)。
* _パッチがあるなら、そう書いてください。_ パッチがついている障害報告は、 ついていないものよりも見てもらえる可能性が高いです。 Bugzilla の Keyword で `patch` を選択してください。
* _あなたがメンテナなら、そう書いてください。_ ソースコードの一部 (たとえば、ある port) をメンテナンスしているなら、障害報告の "Class" を必ず `maintainer-update` にしてください。こうすれば、committer がその障害報告を扱う際に、いちいち確認する必要がありません。
* _具体的に書いてください。_ あなたが抱えている問題について多くの情報を出すほど、 回答してもらえる可能性は高くなります。
** FreeBSD のバージョン (これを記載する場所があります。後述します) と、どのアーキテクチャで動かしているのかを書いてください。 動かしているのが (CDROM から、 またはダウンロードして入れた) リリースでなのか、それとも Subversion でメンテナンスしているシステムでなのか (そうだとしたら、最後に更新したのはいつか) も書いてください。あなたが FreeBSD-CURRENT ブランチを追いかけていたら、それを真っ先に聞かれるでしょう。 なぜなら、FreeBSD-CURRENT では (注目を浴びる問題は特に) 修正がすぐに入る傾向があり、FreeBSD-CURRENT のユーザはそれについて行くことが求められているからです。
** [.filename]#make.conf#, [.filename]#src.conf#, および [.filename]#src-env.conf# に、指定したグローバルオプションの情報を記述してください。 数多くのオプションを設定できるため、 すべての組み合わせについて、 完全に対応しているわけではありません。
** 問題が容易に再現できるようであれば、 開発者が自身で再現できるように情報を含めてください。 もし、特別な入力が行われた時に問題が起きるようであれば、 可能であれば、その入力例を入れてください。また、 実際の出力や予想される出力も含めてください。 もし、データが大きかったり、公開できないものであれば、 同じ問題を表わすような最小限のファイルを作成し、 障害報告に含めてください。
** カーネルの問題なら、 次の情報を渡せるようにしておいてください (はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、 関係があると思う部分の抜粋は入れるべきです)。
*** カーネルコンフィグレーション (どのハードウェアデバイスがインストールされているかも含む)
*** (`WITNESS` などの) デバッグオプションを有効にしているか、 しているなら、 そのオプションを変更しても問題は変わらないか
*** もし生成しているなら、バックトレース、 パニックや他のコンソールの出力、または、 [.filename]#/var/log/messages# のすべてのテキスト
*** 問題がハードウェアのある部分に関連するのであれば、 `pciconf -l` および `dmesg` 出力の関連する部分
*** [.filename]#src/UPDATING# は読んだか、そこにあなたの問題が挙がっていないか (間違いなく聞かれます)
*** 代替として動かせるカーネルが他にないか (これは、故障したディスクや過熱した CPU などのハードウェアに関連した問題で、 カーネルの問題に見えるものを除外するためです)
** Ports の問題であれば、 次の情報を渡せるようにしておいてください (はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、 関係があると思う部分の抜粋は入れるべきです)。
*** どの ports をインストールしたのか
*** `PORTSDIR` など、[.filename]#bsd.port.mk# のデフォルトを上書きする環境変数すべて
*** [.filename]#ports/UPDATING# は読んだか、そこにあなたの問題が挙がっていないか (間違いなく聞かれます)
* _漠然と機能を要求するのはやめましょう。_"誰かこういうことするものを実装すべきだ" という形の障害報告は、詳細な要望に比べて成果を得にくいものです。 ソースコードは誰でも利用できるのですから、何か機能が欲しければ、 それをいれる最善の手段は作業にとりかかることです。 また上述したように、こういうことは多くの場合、 障害報告データベースに登録するよりも `freebsd-questions` で議論した方がよいでしょう。
* _誰かが既に似たような障害報告を提出していないか確認してください。_ これは、既に述べたことではありますが、ここで繰り返しておくに値するでしょう。 Web ベースの検索エンジン https://bugs.freebsd.org/bugzilla/query.cgi[https://bugs.freebsd.org/bugzilla/query.cgi] で調べるのは 1, 2 分程度しかかかりません (もちろん、 誰もがときどきこれを忘れてしまうという罪を犯しています)。
* _ひとつの障害報告にはひとつの問題を報告してください。_ 2 つ以上の問題は、関係がなければ同じ障害報告に含めないでください。 パッチを提出する際には、一つの障害報告に複数の機能や複数のバグを、 それらが極めて関係してなければ、含めることは避けてください。 そのような障害報告は、解決するのにより多くの時間がかかります。
* _異論のある要望は出さないようにしましょう。_ あなたの障害報告がかつて論争になった分野に関するものであったら、 パッチを提出するだけでなく、そのパッチが "正当なものである" 根拠も提出したほうがよいかもしれません。 どの場合でも上述のように https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。
* _礼儀正しくしましょう。_ あなたの障害報告について作業する人は、 ほとんど全員がボランティアです。 金銭的収入以外の動機から行なっていることを、 やれと命令されるのは誰も好きではありません。 オープンソースプロジェクトに関しては、 これを常に念頭においておくとよいでしょう。
[[pr-writing-before-beginning]]
== 始める前に
https://bugs.freebsd.org/bugzilla/enter_bug.cgi[web ベースの障害報告提出フォーム] を利用する場合も、同様の配慮が必要です。 カットアンドペーストを行う場合には、 ホワイトスペースやその他のテキストフォーマットを変えてしまう可能性があるので、気をつけてください。
最後に、提出物が長くなってしまうなら、 提出時に問題が起きて失われてしまうことのないように、 オフラインで準備しておきましょう。
[[pr-writing-attaching-patches]]
== パッチやファイルを添付する
パッチを添付する場合、 unified 形式の差分を `svn diff` または man:diff[1] の `-u` オプションを使って作成してください。 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルに対するリポジトリの SVN のリビジョン番号が特定できることを確認してください。 カーネルやベースのユーティリティに関しては、新しいコードはすべて FreeBSD-CURRENT (SVN の HEAD ブランチ) でテストするべきなので、それに対するパッチが望ましいです。 適切か十分なテストが行なわれたら、そのコードは FreeBSD-STABLE ブランチにマージまたは移植されます。
パッチを添付するのではなく本文中に含める場合、 もっともありがちな問題は、 電子メールプログラムによってはタブをスペースに変更してしまい、 Makefile に含めるつもりだったものを台無しにしてしまうことです。
パッチを `Content-Transfer-Encoding: quoted-printable` を利用した添付ファイルとして送らないようにしてください。 これは文字をエスケープしてしまい、 パッチ全体が使い物にならなくなります。
また、障害報告の中に小さなパッチを含めるのは (とりわけ説明されている障害を修正する場合は) 大抵問題ないのですが、 大規模なパッチや新しいコードの場合は十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、 その URL を障害報告に書くようにしてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり、 パッチが大きいほど興味をもった人がつなぎ直すのが面倒になります。 また、Web にパッチをおけば、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくても変更できます。 最後に、大きなパッチはデータベースのサイズをとにかく増やしてしまいます。 閉じられた障害報告は実際に消されることはなく、 完了の状態で保持されたままになるだけだからです。
また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件のライセンス下にあるものと仮定されることに留意しておくべきです。
[[pr-writing-filling-template]]
== フォームを記入する
[NOTE]
====
指定した電子メールアドレスは公開情報となり、 スパマーに利用されるかもしれません。 スパム対策を使えるようにしておくか、 一時的なメールアカウントを利用してください。 有効な電子メールアドレスを書いていただかないと、 わたしたちは障害報告に対する質問をあなたに対してできないので、 ご留意ください。
====
バグの申請には、以下のフィールドを使ってください。
* _Summary (概要):_ 問題についての簡にして要を得た説明を書き込んでください。 概要は障害報告メールのサブジェクトとして利用されており、 一覧や要旨にも使われています。 概要が不明瞭な障害報告は無視される傾向があります。
* _Severity (重要度):_`Affects only me`, `Affects some people` および `Affects many people` のどれかを選択してください。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的でない場合は、 `Affects many people` に分類するのを控えてください。 まったく同じことをやる人があまりに多いため、 問題の重要性を水増ししても、必ずしも FreeBSD 開発者がその問題に早くとりかかるわけではありません。
* _Category (分類):_ 適切な分類を選んでください。
+
まず最初に行わなければならないのは、 あなたの問題がシステムのどの部分に関連しているかを決めることです。 FreeBSD は完全なオペレーティングシステムなので、 カーネル、標準ライブラリの両方、および、 周辺ドライバ、多くのユーティリティ ("ベースシステム") をインストールします。 さらに、Ports Collection には数多くの追加のアプリケーションが用意されています。 そのため、最初に判断しなくてならないのは、 問題がベースシステムに関連しているのか、 それとも Ports Collection からインストールされた何かに関係しているのか、 ということになります。
+
以下はメジャーなカテゴリについての説明です。
** もし、問題がカーネル、(標準 C ライブラリ `libc`) ライブラリ、またはベースシステムの周辺ドライバで起こるのであれば、 通常は `kern` カテゴリを使うとよいでしょう (下記に説明するようにいくつかの例外があります)。 一般的に、マニュアルページのセクション 2, 3 もしくは 4 に書かれているようなものがここに分類されます。
** 問題が man:sh[1] や man:mount[8] のようなバイナリプログラムで起きるのであれば、 まず最初に、それらのプログラムがベースシステムのものか、 もしくは Ports Collection から追加されたものなのかを判断してください。 よくわかならければ、 `whereis _programname_` と実行してください。 FreeBSD の Ports Collection の慣例では、 (システム管理者は、この設定を変更することができますが) すべてのものは [.filename]#/usr/local# 以下にインストールされます。 このような場合は、 `ports` カテゴリを使うことになります (もし、その port のカテゴリが `www` であっても当てはまります。説明が下にあります)。 もし、コマンドの場所が [.filename]#/bin#, [.filename]#/usr/bin#, [.filename]#/sbin#, もしくは [.filename]#/usr/sbin# であれば、 それはベースシステムの一部ですので、 `bin` カテゴリを使ってください。 このカテゴリには、マニュアルページのセクション 1 または 8 に記述されているすべてが分類されます。
** もし、エラーがスタートアップ `(rc)` スクリプトで起きている、 または他の非実行形式の設定ファイルに関連したようなものあれば、 `conf` (configuration) が適切なカテゴリでしょう。 マニュアルページのセクション 5 に書かれている内容がここに分類されます。
** 問題がドキュメント (article, book もしくはマニュアルページ) またはウェブサイトに関連したものであれば、 `docs` が適切なカテゴリです。
+
[NOTE]
====
もし、問題が `www/_someportname_` という名前の port に関連したものである場合には、 `ports` カテゴリを選択してください。
====
+
さらにいくつかの特別なカテゴリがあります。
** 問題が `kern` に分類されるようなものでも、 USB サブシステムに関連したものであれば、`usb` が適切なカテゴリです。
** 問題が `kern` に分類されるようなものでも、 スレッドのライブラリに関連したものであれば、`threads` が適切なカテゴリです。
** 問題がベースシステムに分類されるようなものでも、 POSIX(R) のような標準への準拠に関連したものであれば、 `standards` が適切なカテゴリです。
+
その他の問題については、以下のカテゴリを使用してください。
** 問題が、あなたの使っているプロセッサアーキテクチャでのみ起こると確信できるのであれば、 アーキテクチャ固有のカテゴリから選んでください。 良く使われている 32-bit モードの Intel 互換コンピュータは `i386`, 64-bit モードで動作する AMD マシンの場合は `amd64` (この分類には、EMT64 モードで動作する Intel 互換のコンピュータも含まれます) を選択してください。 通常はあまりよく使われないアーキテクチャには、 `arm` および `powerpc` があります。
+
[NOTE]
====
これらのカテゴリは、"よくわからない" 問題に対して間違ってよく使われます。 とりあえず推測で選んでしまうのではなく、そのような場合には `misc` を選んでください。
====
+
.アーキテクチャカテゴリの正しい使い方
[example]
====
あなたは一般的な PC アーキテクチャのマシンを持っていて、 特定のチップセットや特定のマザーボードの問題にぶつかったようです。 この場合は、`i386` がふさわしい分類になります。
====
+
.アーキテクチャカテゴリの正しくない使い方
[example]
====
例: 一般的なバス用の追加の周辺カードや、 特定の種類のハードディスクドライブで問題があります。 この場合は、複数のアーキテクチャに影響する可能性があり、 `kern` がふさわしい分類になります。
====
** もし、問題をどの分類に分ければよいのかわからなければ (上で説明したものに当てはまらなければ)、 `misc` カテゴリを選んでください。 このカテゴリを選択する前に、まず最初に {freebsd-questions} で、 助けを求めてみてください。 存在するカテゴリの中から本当に選択すべきものをアドバイスされるかもしれません。
* _Environment (環境):_ 問題が発生した環境を可能な限り正確に記述すべきです。 ここには、オペレーティングシステムのバージョン、 特定のプログラムのバージョンまたは問題があるファイル、 そしてシステムの設定などのような関係する項目、 問題に影響を及ぼすインストールしたその他のソフトウェアなどが含まれます。 - 手短にいうなら、その問題が生じる環境を再構築するために、 開発者が知らなければならないことすべてです。
* _Description:_ あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り、 推測は避けるようにしてください。 ここには、問題を再現する方法を記述してください。 回避方法をご存知でしたら、それについても記述してください。 この情報は、同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません。
[[pr-followup]]
== フォローアップ
障害報告を提出すると、 障害報告に割り当てられた追跡用の番号と状況を確認するために利用する URL を含む、確認のための電子メールが送られてくるでしょう。 ちょっぴり運がよければ、 誰かがあなたの問題に興味を持ってそれに取り組もうとするでしょうし、 場合によってはなぜそれが問題でないか説明してくれるでしょう。 状況に何かの変更があると、 誰かがあなたの障害報告を審査追跡状態にして、 何らかのコメントかパッチの通知を自動的に受けとるでしょう。
誰かがあなたに追加情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 フォローアップを提出してください。 バグが修正されない一番の理由は、 提出者とのコミュニケーション不足が原因です。 一番楽なのは、link:https://bugs.freebsd.org/bugzilla/query.cgi[障害報告検索ページ] から行ける、それぞれの障害報告の web ページのコメントオプションを利用することです。
問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 この障害報告は議論を終了することができます、 とコメントを送ってください。
時々、提出した障害報告が誰にも割り当てられなかったり、 コメントのない状態が 1, 2 週間続くことがあります。 障害報告のバックログが増えているときや、 休暇シーズンに起こり得ます。 提出した障害報告に注意が引かれない状況が何週間も続くようであれば、 その分野に興味を持っているコミッタを見つけると良いでしょう。
これには、幾つかの方法がありますが、以下の順番が好ましいでしょう。 それぞれのコミュニケーションチャネルへのコンタクトには数日開けてください。
* 提出した障害報告に関連する FreeBSD のメーリングリストを link:{handbook}#eresources-mail[ハンドブックのメーリングリスト] で探し、 そのメーリングリストに手助けやコメントをお願いするメールを送ってください。
* 関連する IRC チャネルに参加してください。 不完全ですが一覧が https://wiki.freebsd.org/IrcChannels[] にあります。 チャネルにいるメンバーに提出した障害報告のことを伝えて、 助けを求めてください。 助けを求めた後は、 世界中の異なるタイムゾーンの人々がそれを取り上げることができるように、 我慢強くそのチャネルに留まってください。
* 報告した障害報告に興味を持つコミッタを探してください。 問題が、特定のツール、バイナリ、port、 文書もしくはソースファイルに関するものであれば、link:http://svnweb.FreeBSD.org[SVN リポジトリ] を確認してください。 ファイルに最近変更を加えたコミッタを突き止め、 IRC もしくは電子メールで連絡をとってください。 コミッタとメールアドレスの一覧は、link:{contributors}[FreeBSD への貢献者] 文書にあります。
メンテナやユーザ同様、これらの人々もボランティアであるため、 すぐには障害報告に対応出来ないかもしれません。 フォローアップには、 我慢強くそして一貫性を持って対応することが推奨されます。 また、そのように対応すると協力を得やすいでしょう。 十分な配慮や努力をもってフォローアップに臨めば、 提出した障害報告に対応してくれるコミッタが見つかるのも時間の問題です。
[[pr-problems]]
== 問題が起きたら
バグシステムに関する問題を見つけたら、 バグとして提出してください。 まさにこの目的のためのカテゴリが用意されています。 もし障害報告の提出が難しいようであれば、バグマイスター (mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org]) に連絡をしてください。
[[pr-further]]
== さらなる読みもの
完全なものとはいえませんが、 適切な障害報告の書き方と手順について関連する資料を示します。
* http://www.chiark.greenend.org.uk/~sgtatham/bugs.html[How to Report Bugs Effectively] (http://www.chiark.greenend.org.uk/~sgtatham/bugs-jp.html[日本語訳]) - Simon G. Tatham 氏による、(FreeBSD に限らない) 役に立つ障害報告の作成についてのすぐれたエッセイ。
* link:{pr-guidelines}[Problem Report Handling Guidelines] - 障害報告が FreeBSD の開発者によってどのように扱われるかについて 有益な見識をまとめた記事。