Skip to content

Commit

Permalink
docs: Consolidate redundant CNID and encoding info
Browse files Browse the repository at this point in the history
  • Loading branch information
@rdmark
rdmark committed Jan 14, 2025
1 parent a411bb5 commit bbd5fb4
Show file tree
Hide file tree
Showing 4 changed files with 63 additions and 179 deletions.
97 changes: 18 additions & 79 deletions doc/ja/manpages/man5/afp.conf.5.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,10 @@
<listitem>
<para>ボリュームのファイルシステムのエンコーディングを指定する。デフォルトでは<option>unix
charset</option>と同じである。</para>

<note>
<para>デフォルトのUTF-8エンコーディングを使うことをを強く推奨する。</para>
</note>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -908,9 +912,8 @@
<type>(G)</type></term>

<listitem>
<para>Classic Mac OS の Finder に表示される共有ボリューム アイコンを設定する。
参考に、ある Classic Mac OS バージョンでは、このアイコン設定が無視される。
有効なアイコン名の例は以下になる。</para>
<para>Classic Mac OS の Finder に表示される共有ボリューム アイコンを設定する。 参考に、ある
Classic Mac OS バージョンでは、このアイコン設定が無視される。 有効なアイコン名の例は以下になる。</para>

<itemizedlist>
<listitem>
Expand Down Expand Up @@ -1692,6 +1695,16 @@
<para>そのボリュームに使う CNID バックエンドをセットする。デフォルトのバックエンドは
[@DEFAULT_CNID_SCHEME@] で、有効なバックエンドは [@compiled_backends@]
である。</para>

<note>
<para>「mysql」バックエンドでは、システム管理者が netatalk で使用するために MySQL データベース
インスタンスを構成する必要がある。</para>
</note>

<warning>
<para><command>afpd</command> が持続性のある ID
データベースに重く依存しているので、このバックエンドをボリュームに使用するのは推奨<emphasis>されていない</emphasis>。エイリアスはおそらく機能しないだろうし、ファイル名のマングリングもサポートされていない。</para>
</warning>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -2076,81 +2089,6 @@ directory perm = 0770</programlisting></para>
</refsect2>
</refsect1>

<refsect1>
<title>CNID バックエンド</title>

<para>AFP プロトコルはたいていはファイルとディレクトリを名前ではなく ID で参照する。Netatalk はこの ID
を永続的な方法で保管する方法を必要とする。これを達成するためにいくつかの異なる CNID バックエンドが用意されている。CNID
データベースはデフォルトで localstatedir の下に置かれている。</para>

<variablelist>
<varlistentry>
<term>cdb</term>

<listitem>
<para>"Concurrent database" バックエンドは Oracle Berkeley DB
を基礎としている。このバックエンドだと、いくつかの <command>afpd</command> デーモンが直接 CNID
データベースにアクセスする。もし一つのボリュームあたり、一つ以上の <command>afpd</command>
プロセスがアクティブならば、Berkeley DB ロッキングがアクセスを同期するために用いられる。欠点は単一の
<command>afpd</command> プロセスのクラッシュがデータベースを壊すかもしれないということである。</para>
</listitem>
</varlistentry>

<varlistentry>
<term>dbd</term>

<listitem>
<para>CNID データベースへのアクセスは <command>cnid_metad</command>
デーモンプロセスによって制限されている。<command>afpd</command>
プロセスはこのデーモンとデータベースの読み込みと更新のために通信する。もし Berkeley DB
トランザクションとでビルドすれば、データベースの壊れる可能性は経験的にはゼロである。しかし、パフォーマンスは
<option>cdb</option> とによるものより遅いかもしれない。</para>
</listitem>
</varlistentry>

<varlistentry>
<term>last</term>

<listitem>
<para>このバックエンドは、ID の持続性の点では、例外である。ID はカレントセッションでしか有効ではない。これは基本的には
<command>afpd</command> がバージョン 1.5（と1.6）で行ったことである。このバックエンドは、例えば共有
CD-ROM などで有用なので未だに有効である。Netatalk 3.0
からは、これは自動的に<emphasis>読み込み専用モード</emphasis>になる。</para>

<para><emphasis role="bold">警告</emphasis>: 今や
<command>afpd</command> が持続性のある ID
データベースに重く依存しているので、このバックエンドをボリュームに使用するのはもはや推奨<emphasis>されていない</emphasis>。エイリアスはおそらく機能しないだろうし、ファイル名のマングリングもサポートされていない。</para>
</listitem>
</varlistentry>
</variablelist>

<para><command>./configure --help</command>
で他の有効なバックエンドがあると表示するかもしれない。にも関わらずそれらは壊れていることもありえるし、あるいは主にテストのために使われていることを注意すべきである。
あなたが何をしているのかわかっている場合以外はそれらを使用してはならない。それらは将来のバージョンでそれ以上の通告なく除去されるかもしれない。</para>
</refsect1>

<refsect1>
<title>文字セットオプション</title>

<para>OS XでAppleはAFP3プロトコルを導入した。最も重要な変更の一つは、AFP3は分解済UTF-8
としてエンコードされたUnicode名を用いることである。以前のAFP及びOSバージョンはMacRomanやMacCentralEuropeといったコードページを用いた。</para>

<para><command>afpd</command>がunixファイルシステム上にファイルを保存するとき、拡張されたMacintosh文字やunixファイル名としては不正な文字を維持する方法が必要である。現在のバージョンは今、名前のためのデフォルトエンコーディングとしてUTF-8を用いる。「<keycode>/</keycode>」は「<keycode>:</keycode>」に変換される。</para>

<para>初期のバージョンはいわゆるCAPエンコーディングを用いた。一つの拡張文字(&gt;0x7F)は一つの :xx
シーケンスに変換された。例えば、Appleロゴ (MacRoman:
0xF0)は<literal>:f0</literal>として保存された。幾つかの特殊な文字も
:xx表記として変換された。「<keycode>/</keycode>」は<literal>:2f</literal>にエンコードされ、先頭のドット「<keycode>.</keycode>」は<literal>:2e</literal>にエンコードされた。</para>

<para><option>vol
charset</option>オプションは他のボリュームエンコーディングを選べるようにする。<command>afpd</command>は
<citerefentry>
<refentrytitle><command>iconv</command></refentrytitle>

<manvolnum>1</manvolnum>
</citerefentry> が提供する如何なる文字セットも受け入れる。デフォルトのUTF-8を使うことをを強く推奨する。</para>
</refsect1>

<refsect1>
<title>参照</title>

Expand Down Expand Up @@ -2180,6 +2118,7 @@ directory perm = 0770</programlisting></para>
<refsect1>
<title>著作者</title>

<para><ulink url='https://netatalk.io/contributors'>CONTRIBUTORS</ulink> を参照</para>
<para><ulink url="https://netatalk.io/contributors">CONTRIBUTORS</ulink>
を参照</para>
</refsect1>
</refentry>
8 changes: 6 additions & 2 deletions doc/ja/manual/configuration.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,9 +243,13 @@ basedir regex = /usr/home</programlisting></para>
<secondary>"last" CNID バックエンド</secondary>
</indexterm></title>

<para>last バックエンドはメモリーにデータを保持する tdb データベースである。それ故永続性がない。netatalk 3.0
からは、それは自動的に<emphasis>読み込み専用モード</emphasis>になる。このバックエンドは例えば CD-ROM
<para>last バックエンドはメモリーにデータを保持する tdb データベースである。故永続性がなく、ID
はカレントセッションでしか有効ではない。netatalk 3.0
からは、それは<emphasis>読み込み専用モード</emphasis>になっている。このバックエンドは例えば CD-ROM や自動化テスト
などに有用である。</para>

<para>これは基本的には <command>afpd</command> が netatalk バージョン 1.5以前で CNID
データの保存方法に一致している。</para>
</sect2>

<sect2>
Expand Down
111 changes: 24 additions & 87 deletions doc/manpages/man5/afp.conf.5.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -528,6 +528,11 @@
<listitem>
<para>Specifies the encoding of the volumes filesystem. By
default, it is the same as <option>unix charset</option>.</para>

<note>
<para>It is highly recommended to stick to the default UTF-8
encoding.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -970,8 +975,8 @@

<listitem>
<para>Sets the path to dbus-daemon binary used by the Spotlight
feature. Can be used when the compile-time default path
does not match the runtime environment.</para>
feature. Can be used when the compile-time default path does not
match the runtime environment.</para>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -1061,8 +1066,8 @@

<listitem>
<para>Sets the shared volume icon displayed in the Finder in
Classic Mac OS. Note that some versions of Classic Mac OS
ignores this icon. Examples of valid icon styles:</para>
Classic Mac OS. Note that some versions of Classic Mac OS ignores
this icon. Examples of valid icon styles:</para>

<itemizedlist>
<listitem>
Expand Down Expand Up @@ -1919,6 +1924,19 @@
<para>set the CNID backend to be used for the volume, default is
[@DEFAULT_CNID_SCHEME@] available schemes:
[@compiled_backends@]</para>

<note>
<para>The "mysql" backend requires the system administrator to
configure a MySQL database instance for use with
netatalk.</para>
</note>

<warning>
<para>Do <emphasis>NOT</emphasis> use the "last" backend for
volumes, because <command>afpd</command> relies heavily on a
persistent ID database. Aliases will likely not work and
filename mangling is not supported.</para>
</warning>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -2333,88 +2351,6 @@
</refsect2>
</refsect1>

<refsect1>
<title>CNID backends</title>

<para>The AFP protocol primarily refers to files and directories by ID and
not by name. Netatalk needs a way to store these IDs in a persistent way.
To achieve this, Netatalk provides multiple CNID backends with different
capabilities. The CNID databases are by default located under
localstatedir.</para>

<variablelist>
<varlistentry>
<term>dbd</term>

<listitem>
<para>Access to the CNID database is restricted to the
<command>cnid_metad</command> daemon process.
<command>afpd</command> processes communicate with the daemon for
database reads and updates. If built with Berkeley DB transactions
the probability for database corruption is practically zero, but
performance can be slower than with <option>cdb</option></para>
</listitem>
</varlistentry>

<varlistentry>
<term>last</term>

<listitem>
<para>This backend is an exception, in terms of ID persistency. ID's
are only valid for the current session. This is basically what
<command>afpd</command> did in the 1.5 (and 1.6) versions. This
backend is still available, as it is useful for e.g. sharing CD-ROMs.
Starting with Netatalk 3.0, it becomes the <emphasis>read only
mode</emphasis> automatically.</para>

<para><emphasis role="bold">Warning</emphasis>: It is
<emphasis>NOT</emphasis> recommended to use this backend for volumes
anymore, as <command>afpd</command> now relies heavily on a
persistent ID database. Aliases will likely not work and filename
mangling is not supported.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Even though <command>./configure --help</command> might show that
there are other CNID backends available, be warned those are likely broken
or mainly used for testing. Don't use them unless you know what you're
doing, they may be removed without further notice from future
versions.</para>
</refsect1>

<refsect1>
<title>Charset options</title>

<para>With OS X Apple introduced the AFP3 protocol. One of the most
important changes was that AFP3 uses unicode names encoded as UTF-8
decomposed. Previous AFP/OS versions used codepages, like MacRoman,
MacCentralEurope, etc.</para>

<para><command>afpd</command> needs a way to preserve extended Macintosh
characters, or characters illegal in unix filenames, when saving files on
a unix filesystem. This version now uses UTF-8 as the default encoding for
names. '<keycode>/</keycode>' will be converted to
'<keycode>:</keycode>'.</para>

<para>Earlier versions used the the so called CAP encoding. An extended
character (&gt;0x7F) would be converted to a :xx sequence, e.g. the Apple
Logo (MacRoman: 0xF0) was saved as <literal>:f0</literal>. Some special
characters would be converted as to :xx notation as well.
'<keycode>/</keycode>' would be encoded to <literal>:2f</literal>, a
leading dot '<keycode>.</keycode>' might be encoded as
<literal>:2e</literal>.</para>

<para>The <option>vol charset</option> option will allow you to select
another volume encoding. <command>afpd</command> will accept any
<citerefentry>
<refentrytitle><command>iconv</command></refentrytitle>

<manvolnum>1</manvolnum>
</citerefentry> provided charset. It is highly recommended to stick to
the default UTF-8.</para>
</refsect1>

<refsect1>
<title>See Also</title>

Expand Down Expand Up @@ -2444,6 +2380,7 @@
<refsect1>
<title>Author</title>

<para>See <ulink url='https://netatalk.io/contributors'>CONTRIBUTORS</ulink></para>
<para>See <ulink
url="https://netatalk.io/contributors">CONTRIBUTORS</ulink></para>
</refsect1>
</refentry>
26 changes: 15 additions & 11 deletions doc/manual/configuration.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,9 +234,13 @@ basedir regex = /usr/home</programlisting></para>
</indexterm></title>

<para>The last backend is an in-memory tdb database. It is not
persistent. Starting with netatalk 3.0, it operates in <emphasis>read
only mode</emphasis> automatically. This is useful e.g. for mounting
CD-ROMs.</para>
persistent, with IDs valid only for the current session. Starting with
netatalk 3.0, it operates in <emphasis>read only mode</emphasis>. This
backend is useful e.g. for mounting CD-ROMs, or for automated
testing.</para>

<para>This is basically equivalent to how <command>afpd</command> stored
CNID data in netatalk 1.5 and earlier.</para>
</sect2>

<sect2>
Expand Down Expand Up @@ -696,8 +700,8 @@ basedir regex = /usr/home</programlisting></para>
support exists since AppleShare client 3.8.x.</para>

<para>On macOS, there exist some client-side techniques to make the
AFP-client more verbose, so one can have a look at what's happening while
negotiating the UAMs to use. Compare with this <ulink
AFP-client more verbose, so one can have a look at what's happening
while negotiating the UAMs to use. Compare with this <ulink
url="https://web.archive.org/web/20080312054723/http://article.gmane.org/gmane.network.netatalk.devel/7383/">hint</ulink>.</para>
</sect2>

Expand Down Expand Up @@ -1341,12 +1345,12 @@ aclmode = passthrough</screen>
<sect3>
<title>Mapping POSIX ACLs to macOS ACLs</title>

<para>When a client wants to read an object's ACL, afpd maps its
POSIX ACL onto an equivalent macOS ACL. Writing an object's ACL
requires afpd to map an macOS ACL onto a POSIX ACL. Due to
architectural restrictions of POSIX ACLs, it is usually impossible to
find an exact mapping so that the result of the mapping process will
be an approximation of the original ACL's semantic.</para>
<para>When a client wants to read an object's ACL, afpd maps its POSIX
ACL onto an equivalent macOS ACL. Writing an object's ACL requires
afpd to map an macOS ACL onto a POSIX ACL. Due to architectural
restrictions of POSIX ACLs, it is usually impossible to find an exact
mapping so that the result of the mapping process will be an
approximation of the original ACL's semantic.</para>

<para><itemizedlist>
<listitem>
Expand Down

0 comments on commit bbd5fb4

Please sign in to comment.