doc/manual/configuration.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="configuration">
   3   <title>Setting up Netatalk</title>
   4
   5   <sect1>
   6     <title>File Services<indexterm>
   7         <primary>File Services</primary>
   8
   9         <secondary>Netatalk's File Services</secondary>
  10       </indexterm></title>
  11
  12     <para>Netatalk supplies AFP<indexterm>
  13         <primary>AFP</primary>
  14
  15         <secondary>Apple Filing Protocol</secondary>
  16       </indexterm> services.</para>
  17
  18     <sect2>
  19       <title>Setting up the AFP file server</title>
  20
  21       <para>AFP (the Apple Filing Protocol) is the protocol Apple Macintoshes
  22       use for file services. The protocol has evolved over the years. The
  23       latest changes to the protocol, called "AFP 3.3", were added with the
  24       release of Snow Leopard<indexterm>
  25           <primary>Snow Leopard</primary>
  26
  27           <secondary>Mac OS X 10.6</secondary>
  28         </indexterm> (Mac OS X 10.6).</para>
  29
  30       <para>The afpd daemon offers the fileservices to Apple clients. The only
  31       configuration file is <filename>afp.conf</filename>. It uses a ini style
  32       configuration syntax.</para>
  33
  34       <para>Support for <link linkend="spotlight">Spotlight</link><indexterm>
  35           <primary>Spotlight</primary>
  36         </indexterm> has been added in Netatalk 3.1. See this <link
  37       linkend="spotlight-compile">section</link> for information on how to
  38       compile Netatalk with Spotlight support.</para>
  39
  40       <para>Mac OS X 10.5 (Leopard) added support for Time Machine backups
  41       over AFP. Two new functions ensure that backups are written to spinning
  42       disk, not just in the server's cache. Different host operating systems
  43       honour this cache flushing differently. To make a volume a Time Machine
  44       target use the volume option "<option>time machine =
  45       yes</option>".</para>
  46
  47       <para>Starting with Netatalk 2.1 UNIX symlinks<indexterm>
  48           <primary>symlink</primary>
  49
  50           <secondary>UNIX symlink</secondary>
  51         </indexterm> can be used on the server. Semantics are the same as for
  52       eg NFS, ie they are not resolved on the server side but instead it's
  53       completely up to the client to resolve them, resulting in links that
  54       point somewhere inside the clients filesystem view.</para>
  55
  56       <sect3>
  57         <title>afp.conf</title>
  58
  59         <para><filename>afp.conf</filename> is the configuration file used by
  60         afpd to determine the behaviour and configuration of the AFP file
  61         serverand the AFP volume that it provides.</para>
  62
  63         <para>The <filename>afp.conf</filename> is divided into several
  64         sections:<variablelist>
  65             <varlistentry>
  66               <term>[Global]</term>
  67
  68               <listitem>
  69                 <para>The global section defines general server options</para>
  70               </listitem>
  71             </varlistentry>
  72
  73             <varlistentry>
  74               <term>[Homes]</term>
  75
  76               <listitem>
  77                 <para>The homes section defines user home volumes</para>
  78               </listitem>
  79             </varlistentry>
  80           </variablelist>Any section not called <option>Global</option> or
  81         <option>Homes</option> is interpreted as an AFP volume.</para>
  82
  83         <para>For sharing user homes by defining a <option>Homes</option>
  84         section you must specify the option <option>basedir regex</option>
  85         which can be a simple string with the path to the parent directory of
  86         all user homes or a regular expression.</para>
  87
  88         <para>Example:</para>
  89
  90         <para><programlisting>[Homes]
  91 basedir regex = /home
  92 </programlisting></para>
  93
  94         <para>Now any user logging into the AFP server will have a user volume
  95         available whos path is <filename>/home/NAME</filename>.</para>
  96
  97         <para>A more complex setup would be a server with a large amount of
  98         user homes which are split across eg two different
  99         filesystems:<itemizedlist>
 100             <listitem>
 101               <para>/RAID1/homes</para>
 102             </listitem>
 103
 104             <listitem>
 105               <para>/RAID2/morehomes</para>
 106             </listitem>
 107           </itemizedlist>The following configuration is
 108         required:<programlisting>[Homes]
 109 basedir regex = /RAID./.*homes
 110 </programlisting></para>
 111
 112         <para>If <option>basedir regex</option> contains symlink, set the
 113         canonicalized absolute path. When <filename>/home</filename> links to
 114         <filename>/usr/home</filename>: <programlisting>[Homes]
 115 basedir regex = /usr/home</programlisting></para>
 116
 117         <para>For a more detailed explanation of the available options, please
 118         refer to the <citerefentry>
 119             <refentrytitle>afp.conf</refentrytitle>
 120
 121             <manvolnum>5</manvolnum>
 122           </citerefentry> man page.</para>
 123       </sect3>
 124     </sect2>
 125
 126     <sect2 id="CNID-backends">
 127       <title>CNID<indexterm>
 128           <primary>CNID</primary>
 129
 130           <secondary>Catalog Node ID</secondary>
 131         </indexterm> backends<indexterm>
 132           <primary>Backend</primary>
 133
 134           <secondary>CNID backend</secondary>
 135         </indexterm></title>
 136
 137       <para>Unlike other protocols like SMB or NFS, the AFP protocol mostly
 138       refers to files and directories by ID and not by a path (the IDs are
 139       also called CNID, that means Catalog Node ID). A typical AFP request
 140       uses a directory ID<indexterm>
 141           <primary>DID</primary>
 142
 143           <secondary>Directory ID</secondary>
 144         </indexterm> and a filename, something like <phrase>"server, please
 145       open the file named 'Test' in the directory with id 167"</phrase>. For
 146       example "Aliases" on the Mac basically work by ID (with a fallback to
 147       the absolute path in more recent AFP clients. But this applies only to
 148       Finder, not to applications).</para>
 149
 150       <para>Every file in an AFP volume has to have a unique file ID<indexterm>
 151           <primary>FID</primary>
 152
 153           <secondary>File ID</secondary>
 154         </indexterm>, IDs must, according to the specs, never be reused, and
 155       IDs are 32 bit numbers (Directory IDs use the same ID pool). So, after
 156       ~4 billion files/folders have been written to an AFP volume, the ID pool
 157       is depleted and no new file can be written to the volume. No whining
 158       please :-)</para>
 159
 160       <para>Netatalk needs to map IDs to files and folders in the host
 161       filesystem. To achieve this, several different CNID backends<indexterm>
 162           <primary>CNID backend</primary>
 163         </indexterm> are available and can be choosed by the <option>cnid
 164       scheme</option><indexterm>
 165           <primary>cnidscheme</primary>
 166
 167           <secondary>specifying a CNID backend</secondary>
 168         </indexterm> option in the <citerefentry>
 169           <refentrytitle>afp.conf</refentrytitle>
 170
 171           <manvolnum>5</manvolnum>
 172         </citerefentry> configuration file. A CNID backend is basically a
 173       database storing ID &lt;-&gt; name mappings.</para>
 174
 175       <para>The CNID Databases are by default located in
 176       <filename>/var/netatalk/CNID</filename>.</para>
 177
 178       <para>There is a command line utility called <command>dbd</command>
 179       available which can be used to verify, repair and rebuild the CNID
 180       database.</para>
 181
 182       <note>
 183         <para>There are some CNID related things you should keep in mind when
 184         working with netatalk:</para>
 185
 186         <itemizedlist>
 187           <listitem>
 188             <para>Don't nest volumes<indexterm>
 189                 <primary>Nested volumes</primary>
 190               </indexterm>.</para>
 191           </listitem>
 192
 193           <listitem>
 194             <para>CNID backends are databases, so they turn afpd into a file
 195             server/database mix.</para>
 196           </listitem>
 197
 198           <listitem>
 199             <para>If there's no more space on the filesystem left, the
 200             database will get corrupted. You can work around this by either
 201             using the <option>vol dbpath</option> option and put the database
 202             files into another location or, if you use quotas, make sure the
 203             CNID database folder is owned by a user/group without a
 204             quota<indexterm>
 205                 <primary>Quotas</primary>
 206
 207                 <secondary>Disk usage quotas</secondary>
 208               </indexterm>.</para>
 209           </listitem>
 210
 211           <listitem>
 212             <para>Be careful with CNID databases for volumes that are mounted
 213             via NFS. That is a pretty audacious decision to make anyway, but
 214             putting a database there as well is really asking for trouble,
 215             i.e. database corruption. Use the <option>vol dbpath</option>
 216             directive to put the databases onto a local disk if you must use
 217             NFS<indexterm>
 218                 <primary>NFS</primary>
 219
 220                 <secondary>Network File System</secondary>
 221               </indexterm> mounted volumes.</para>
 222           </listitem>
 223         </itemizedlist>
 224       </note>
 225
 226       <sect3>
 227         <title>cdb<indexterm>
 228             <primary>CDB</primary>
 229
 230             <secondary>"cdb" CNID backend</secondary>
 231           </indexterm></title>
 232
 233         <para>The "concurrent database" backend is based on Berkeley DB. With
 234         this backend, several afpd daemons access the CNID database directly.
 235         Berkeley DB locking is used to synchronize access, if more than one
 236         afpd process is active for a volume. The drawback is, that the crash
 237         of a single afpd process might corrupt the database. cdb should only
 238         be used when sharing home directories for a larger number of users
 239         <emphasis>and</emphasis> it has been determined that a large number of
 240         <command>cnid_dbd</command> processes is problematic.</para>
 241       </sect3>
 242
 243       <sect3>
 244         <title>dbd<indexterm>
 245             <primary>DBD</primary>
 246
 247             <secondary>"dbd" CNID backend</secondary>
 248           </indexterm></title>
 249
 250         <para>Access to the CNID database is restricted to the cnid_dbd daemon
 251         process. afpd processes communicate with the daemon for database reads
 252         and updates. The probability for database corruption is practically
 253         zero.</para>
 254
 255         <para>This is the default backend since Netatalk 2.1.</para>
 256       </sect3>
 257
 258       <sect3>
 259         <title>tdb<indexterm>
 260             <primary>tdb</primary>
 261
 262             <secondary>"tdb" CNID backend</secondary>
 263           </indexterm></title>
 264
 265         <para><abbrev>tdb</abbrev> is another persistent CNID database, it's
 266         Samba's <emphasis>Trivial Database</emphasis>. It could be used
 267         instead of <abbrev>cdb</abbrev> for user volumes.<important>
 268             <para>Only ever use it for volumes that are
 269             <emphasis>not</emphasis> shared and accessed by multiple clients
 270             at once !</para>
 271           </important>This backend is also used internally (as in-memory CNID
 272         database) as a fallback in case opening the primary database can't be
 273         opened, because <abbrev>tdb</abbrev> can work as in-memory database.
 274         This of course means upon restart the CNIDs are gone.</para>
 275       </sect3>
 276
 277       <sect3>
 278         <title>last<indexterm>
 279             <primary>Last</primary>
 280
 281             <secondary>"last" CNID backend</secondary>
 282           </indexterm></title>
 283
 284         <para>The last backend is a in-memory tdb database. It is not
 285         persistent. Starting with netatalk 3.0, it becomes the <emphasis> read
 286         only mode</emphasis> automatically. This is useful e.g. for
 287         CD-ROMs.</para>
 288       </sect3>
 289
 290       <sect3>
 291         <title>mysql<indexterm>
 292             <primary>MySQL</primary>
 293
 294             <secondary>"mysql" CNID backend</secondary>
 295           </indexterm></title>
 296
 297         <para>CNID backend using a MySQL server.</para>
 298       </sect3>
 299     </sect2>
 300
 301     <sect2 id="charsets">
 302       <title>Charsets<indexterm>
 303           <primary>Charset</primary>
 304
 305           <secondary>character set</secondary>
 306         </indexterm>/Unicode<indexterm>
 307           <primary>Unicode</primary>
 308         </indexterm></title>
 309
 310       <para></para>
 311
 312       <sect3>
 313         <title>Why Unicode?</title>
 314
 315         <para>Internally, computers don't know anything about characters and
 316         texts, they only know numbers. Therefore, each letter is assigned a
 317         number. A character set, often referred to as
 318         <emphasis>charset</emphasis> or
 319         <emphasis>codepage</emphasis><indexterm>
 320             <primary>Codepage</primary>
 321           </indexterm>, defines the mappings between numbers and
 322         letters.</para>
 323
 324         <para>If two or more computer systems need to communicate with each
 325         other, the have to use the same character set. In the 1960s the
 326         ASCII<indexterm>
 327             <primary>ASCII</primary>
 328
 329             <secondary>American Standard Code for Information
 330             Interchange</secondary>
 331           </indexterm> (American Standard Code for Information Interchange)
 332         character set was defined by the American Standards Association. The
 333         original form of ASCII represented 128 characters, more than enough to
 334         cover the English alphabet and numerals. Up to date, ASCII has been
 335         the normative character scheme used by computers.</para>
 336
 337         <para>Later versions defined 256 characters to produce a more
 338         international fluency and to include some slightly esoteric graphical
 339         characters. Using this mode of encoding each character takes exactly
 340         one byte. Obviously, 256 characters still wasn't enough to map all the
 341         characters used in the various languages into one character
 342         set.</para>
 343
 344         <para>As a result localized character sets were defined later, e.g the
 345         ISO-8859 character sets. Most operating system vendors introduced
 346         their own characters sets to satisfy their needs, e.g. IBM defined the
 347         <emphasis>codepage 437 (DOSLatinUS)</emphasis>, Apple introduced the
 348         <emphasis>MacRoman</emphasis><indexterm>
 349             <primary>MacRoman</primary>
 350
 351             <secondary>MacRoman charset</secondary>
 352           </indexterm> codepage and so on. The characters that were assigned
 353         number larger than 127 were referred to as
 354         <emphasis>extended</emphasis> characters. These character sets
 355         conflict with another, as they use the same number for different
 356         characters, or vice versa.</para>
 357
 358         <para>Almost all of those characters sets defined 256 characters,
 359         where the first 128 (0-127) character mappings are identical to ASCII.
 360         As a result, communication between systems using different codepages
 361         was effectively limited to the ASCII charset.</para>
 362
 363         <para>To solve this problem new, larger character sets were defined.
 364         To make room for more character mappings, these character sets use at
 365         least 2 bytes to store a character. They are therefore referred to as
 366         <emphasis>multibyte</emphasis> character sets.</para>
 367
 368         <para>One standardized multibyte charset encoding scheme is known as
 369         <ulink url="http://www.unicode.org/">unicode</ulink>. A big advantage
 370         of using a multibyte charset is that you only need one. There is no
 371         need to make sure two computers use the same charset when they are
 372         communicating.</para>
 373       </sect3>
 374
 375       <sect3>
 376         <title>character sets used by Apple</title>
 377
 378         <para>In the past, Apple clients used single-byte charsets to
 379         communicate over the network. Over the years Apple defined a number of
 380         codepages, western users will most likely be using the
 381         <emphasis>MacRoman</emphasis> codepage.</para>
 382
 383         <para>Codepages defined by Apple include:</para>
 384
 385         <itemizedlist>
 386           <listitem>
 387             <para>MacArabic, MacFarsi</para>
 388           </listitem>
 389
 390           <listitem>
 391             <para>MacCentralEurope</para>
 392           </listitem>
 393
 394           <listitem>
 395             <para>MacChineseSimple</para>
 396           </listitem>
 397
 398           <listitem>
 399             <para>MacChineseTraditional</para>
 400           </listitem>
 401
 402           <listitem>
 403             <para>MacCroation</para>
 404           </listitem>
 405
 406           <listitem>
 407             <para>MacCyrillic</para>
 408           </listitem>
 409
 410           <listitem>
 411             <para>MacDevanagari</para>
 412           </listitem>
 413
 414           <listitem>
 415             <para>MacGreek</para>
 416           </listitem>
 417
 418           <listitem>
 419             <para>MacHebrew</para>
 420           </listitem>
 421
 422           <listitem>
 423             <para>MacIcelandic</para>
 424           </listitem>
 425
 426           <listitem>
 427             <para>MacJapanese</para>
 428           </listitem>
 429
 430           <listitem>
 431             <para>MacKorean</para>
 432           </listitem>
 433
 434           <listitem>
 435             <para>MacRoman</para>
 436           </listitem>
 437
 438           <listitem>
 439             <para>MacRomanian</para>
 440           </listitem>
 441
 442           <listitem>
 443             <para>MacThai</para>
 444           </listitem>
 445
 446           <listitem>
 447             <para>MacTurkish</para>
 448           </listitem>
 449         </itemizedlist>
 450
 451         <para>Starting with Mac OS X and AFP3, <ulink
 452         url="http://www.utf-8.com/">UTF-8</ulink> is used. UTF-8 encodes
 453         Unicode characters in an ASCII compatible way, each Unicode character
 454         is encoded into 1-6 ASCII characters. UTF-8 is therefore not really a
 455         charset itself, it's an encoding of the Unicode charset.</para>
 456
 457         <para>To complicate things, Unicode defines several <emphasis> <ulink
 458         url="http://www.unicode.org/reports/tr15/index.html">normalization</ulink>
 459         </emphasis> forms. While <ulink
 460         url="http://www.samba.org">samba</ulink><indexterm>
 461             <primary>Samba</primary>
 462           </indexterm> uses <emphasis>precomposed</emphasis><indexterm>
 463             <primary>Precomposed</primary>
 464
 465             <secondary>Precomposed Unicode normalization</secondary>
 466           </indexterm> Unicode, which most Unix tools prefer as well, Apple
 467         decided to use the <emphasis>decomposed</emphasis><indexterm>
 468             <primary>Decomposed</primary>
 469
 470             <secondary>Decomposed Unicode normalization</secondary>
 471           </indexterm> normalization.</para>
 472
 473         <para>For example lets take the German character
 474         '<keycode>ä</keycode>'. Using the precomposed normalization, Unicode
 475         maps this character to 0xE4. In decomposed normalization, 'ä' is
 476         actually mapped to two characters, 0x61 and 0x308. 0x61 is the mapping
 477         for an 'a', 0x308 is the mapping for a <emphasis>COMBINING
 478         DIAERESIS</emphasis>.</para>
 479
 480         <para>Netatalk refers to precomposed UTF-8 as
 481         <emphasis>UTF8</emphasis><indexterm>
 482             <primary>UTF8</primary>
 483
 484             <secondary>Netatalk's precomposed UTF-8 encoding</secondary>
 485           </indexterm> and to decomposed UTF-8 as
 486         <emphasis>UTF8-MAC</emphasis><indexterm>
 487             <primary>UTF8-MAC</primary>
 488
 489             <secondary>Netatalk's decomposed UTF-8 encoding</secondary>
 490           </indexterm>.</para>
 491       </sect3>
 492
 493       <sect3>
 494         <title>afpd and character sets</title>
 495
 496         <para>To support new AFP 3.x and older AFP 2.x clients at the same
 497         time, afpd needs to be able to convert between the various charsets
 498         used. AFP 3.x clients always use UTF8-MAC, AFP 2.x clients use one of
 499         the Apple codepages.</para>
 500
 501         <para>At the time of this writing, netatalk supports the following
 502         Apple codepages:</para>
 503
 504         <itemizedlist>
 505           <listitem>
 506             <para>MAC_CENTRALEUROPE</para>
 507           </listitem>
 508
 509           <listitem>
 510             <para>MAC_CHINESE_SIMP</para>
 511           </listitem>
 512
 513           <listitem>
 514             <para>MAC_CHINESE_TRAD</para>
 515           </listitem>
 516
 517           <listitem>
 518             <para>MAC_CYRILLIC</para>
 519           </listitem>
 520
 521           <listitem>
 522             <para>MAC_GREEK</para>
 523           </listitem>
 524
 525           <listitem>
 526             <para>MAC_HEBREW</para>
 527           </listitem>
 528
 529           <listitem>
 530             <para>MAC_JAPANESE</para>
 531           </listitem>
 532
 533           <listitem>
 534             <para>MAC_KOREAN</para>
 535           </listitem>
 536
 537           <listitem>
 538             <para>MAC_ROMAN</para>
 539           </listitem>
 540
 541           <listitem>
 542             <para>MAC_TURKISH</para>
 543           </listitem>
 544         </itemizedlist>
 545
 546         <para>afpd handles three different character set options:</para>
 547
 548         <variablelist>
 549           <varlistentry>
 550             <term>unix charset<indexterm>
 551                 <primary>unix charset</primary>
 552
 553                 <secondary>afpd's unix charset setting</secondary>
 554               </indexterm></term>
 555
 556             <listitem>
 557               <para>This is the codepage used internally by your operating
 558               system. If not specified, it defaults to <option>UTF8</option>.
 559               If <option>LOCALE</option> is specified and your system support
 560               Unix locales, afpd tries to detect the codepage. afpd uses this
 561               codepage to read its configuration files, so you can use
 562               extended characters for volume names, login messages, etc. see
 563               <citerefentry>
 564                   <refentrytitle>afp.conf</refentrytitle>
 565
 566                   <manvolnum>5</manvolnum>
 567                 </citerefentry>.</para>
 568             </listitem>
 569           </varlistentry>
 570
 571           <varlistentry>
 572             <term>mac charset<indexterm>
 573                 <primary>mac charset</primary>
 574
 575                 <secondary>afpd's mac charset setting</secondary>
 576               </indexterm></term>
 577
 578             <listitem>
 579               <para>As already mentioned, older Mac OS clients (up to AFP 2.2)
 580               use codepages to communicate with afpd. However, there is no
 581               support for negotiating the codepage used by the client in the
 582               AFP protocol. If not specified otherwise, afpd assumes the
 583               <emphasis>MacRoman</emphasis> codepage is used. In case you're
 584               clients use another codepage, e.g.
 585               <emphasis>MacCyrillic</emphasis>, you'll <emphasis
 586               role="bold">have</emphasis> to explicitly configure this. see
 587               <citerefentry>
 588                   <refentrytitle>afp.conf</refentrytitle>
 589
 590                   <manvolnum>5</manvolnum>
 591                 </citerefentry>.</para>
 592             </listitem>
 593           </varlistentry>
 594
 595           <varlistentry>
 596             <term>vol charset<indexterm>
 597                 <primary>vol charset</primary>
 598
 599                 <secondary>afpd's vol charset setting</secondary>
 600               </indexterm></term>
 601
 602             <listitem>
 603               <para>This defines the charset afpd should use for filenames on
 604               disk. By default, it is the same as <option>unix
 605               charset</option>. If you have <ulink
 606               url="http://www.gnu.org/software/libiconv/">iconv</ulink><indexterm>
 607                   <primary>Iconv</primary>
 608
 609                   <secondary>iconv encoding conversion engine</secondary>
 610                 </indexterm> installed, you can use any iconv provided charset
 611               as well.</para>
 612
 613               <para>afpd needs a way to preserve extended macintosh
 614               characters, or characters illegal in unix filenames, when saving
 615               files on a unix filesystem. Earlier versions used the the so
 616               called CAP encoding<indexterm>
 617                   <primary>CAP encoding</primary>
 618
 619                   <secondary>CAP style character encoding</secondary>
 620                 </indexterm>. An extended character (&gt;0x7F) would be
 621               converted to a :xx hex sequence, e.g. the Apple Logo (MacRoman:
 622               0xF0) was saved as :f0. Some special characters will be
 623               converted as to :xx notation as well. '/' will be encoded to
 624               :2f, if <option>usedots</option> was not specified, a leading
 625               dot '.' will be encoded as :2e.</para>
 626
 627               <para>Even though this version now uses <option>UTF8</option> as
 628               the default encoding for filenames, '/' will be converted to
 629               ':'. For western users another useful setting could be
 630               <option>vol charset = ISO-8859-15</option>.</para>
 631
 632               <para>If a character cannot be converted from the <option>mac
 633               charset</option> to the selected <option>vol charset</option>,
 634               afpd will save it as a CAP encoded character. For AFP3 clients,
 635               afpd will convert the UTF8 character to <option>mac
 636               charset</option> first. If this conversion fails, you'll receive
 637               a -50 error on the mac. <emphasis>Note</emphasis>: Whenever you
 638               can, please stick with the default UTF8 volume format. see
 639               <citerefentry>
 640                   <refentrytitle>afp.conf</refentrytitle>
 641
 642                   <manvolnum>5</manvolnum>
 643                 </citerefentry>.</para>
 644             </listitem>
 645           </varlistentry>
 646         </variablelist>
 647       </sect3>
 648     </sect2>
 649
 650     <sect2 id="authentication">
 651       <title>Authentication<indexterm>
 652           <primary>Authentication</primary>
 653
 654           <secondary>between AFP client and server</secondary>
 655         </indexterm></title>
 656
 657       <sect3>
 658         <title>AFP authentication basics</title>
 659
 660         <para>Apple chose a flexible model called "User Authentication
 661         Modules"<indexterm>
 662             <primary>UAM</primary>
 663
 664             <secondary>User Authentication Module</secondary>
 665           </indexterm> (UAMs) for authentication purposes between AFP client
 666         and server. An AFP client initially connecting to an AFP server will
 667         ask for the list of UAMs which the server provides, and will choose
 668         the one with strongest encryption that the client supports.</para>
 669
 670         <para>Several UAMs have been developed by Apple over the time, some by
 671         3rd-party developers.</para>
 672       </sect3>
 673
 674       <sect3>
 675         <title>UAMs supported by Netatalk</title>
 676
 677         <para>Netatalk supports the following ones by default:</para>
 678
 679         <itemizedlist>
 680           <listitem>
 681             <para>"No User Authent"<indexterm>
 682                 <primary>No User Authent</primary>
 683
 684                 <secondary>"No User Authent" UAM (guest access)</secondary>
 685               </indexterm> UAM (guest access without authentication)</para>
 686           </listitem>
 687
 688           <listitem>
 689             <para>"Cleartxt Passwrd"<indexterm>
 690                 <primary>Cleartxt Passwrd</primary>
 691
 692                 <secondary>"Cleartxt Passwrd" UAM</secondary>
 693               </indexterm> UAM (no password encryption)</para>
 694           </listitem>
 695
 696           <listitem>
 697             <para>"Randnum exchange"<indexterm>
 698                 <primary>Randnum exchange</primary>
 699
 700                 <secondary>"Randnum exchange" UAM</secondary>
 701               </indexterm>/"2-Way Randnum exchange"<indexterm>
 702                 <primary>2-Way Randnum exchange</primary>
 703
 704                 <secondary>"2-Way Randnum exchange" UAM</secondary>
 705               </indexterm> UAMs (weak password encryption, separate password
 706             storage)</para>
 707           </listitem>
 708
 709           <listitem>
 710             <para>"DHCAST128"<indexterm>
 711                 <primary>DHCAST128</primary>
 712
 713                 <secondary>"DHCAST128" UAM</secondary>
 714               </indexterm> UAM (stronger password encryption)</para>
 715           </listitem>
 716
 717           <listitem>
 718             <para>"DHX2"<indexterm>
 719                 <primary>DHX2</primary>
 720
 721                 <secondary>"DHX2" UAM</secondary>
 722               </indexterm> UAM (successor of DHCAST128)</para>
 723           </listitem>
 724         </itemizedlist>
 725
 726         <para>There exist other optional UAMs as well:</para>
 727
 728         <itemizedlist>
 729           <listitem>
 730             <para>"PGPuam 1.0"<indexterm>
 731                 <primary>PGPuam 1.0</primary>
 732
 733                 <secondary>"PGPuam 1.0" UAM</secondary>
 734               </indexterm><indexterm>
 735                 <primary>uams_pgp.so</primary>
 736
 737                 <secondary>"PGPuam 1.0" UAM</secondary>
 738               </indexterm> UAM (PGP-based authentication for pre-Mac OS X
 739             clients. You'll also need the <ulink
 740             url="http://www.vmeng.com/vinnie/papers/pgpuam.html">PGPuam
 741             client</ulink> to let this work)</para>
 742
 743             <para>You'll have to add <filename>"--enable-pgp-uam"</filename>
 744             to your configure switches to have this UAM available.</para>
 745           </listitem>
 746
 747           <listitem>
 748             <para>"Kerberos IV"<indexterm>
 749                 <primary>Kerberos IV</primary>
 750
 751                 <secondary>"Kerberos IV" UAM</secondary>
 752               </indexterm><indexterm>
 753                 <primary>uams_krb4.so</primary>
 754
 755                 <secondary>"Kerberos IV" UAM</secondary>
 756               </indexterm>/"AFS Kerberos"<indexterm>
 757                 <primary>AFS Kerberos</primary>
 758
 759                 <secondary>"AFS Kerberos" UAM (Kerberos IV)</secondary>
 760               </indexterm> UAMs (suitable to use <ulink
 761             url="http://web.mit.edu/macdev/KfM/Common/Documentation/faq.html">Kerberos
 762             v4 based authentication</ulink> and AFS file servers)</para>
 763
 764             <para>Use <filename>"--enable-krb4-uam"</filename> at compile time
 765             to activate the build of this UAM.</para>
 766           </listitem>
 767
 768           <listitem>
 769             <para>"Client Krb v2"<indexterm>
 770                 <primary>Client Krb v2</primary>
 771
 772                 <secondary>"Client Krb v2" UAM (Kerberos V)</secondary>
 773               </indexterm> UAM (Kerberos V, suitable for "Single Sign On"
 774             Scenarios with OS X clients -- see below)</para>
 775
 776             <para><filename>"--enable-krbV-uam"</filename> will provide you
 777             with the ability to use this UAM.</para>
 778           </listitem>
 779         </itemizedlist>
 780
 781         <para>You can configure which UAMs should be activated by defining
 782         "<option>uam list</option>" in <option>Global</option> section.
 783         <command>afpd</command> will log which UAMs it's using and if problems
 784         occur while activating them in either
 785         <filename>netatalk.log</filename> or syslog at startup time.
 786         <citerefentry>
 787             <refentrytitle>asip-status.pl</refentrytitle>
 788
 789             <manvolnum>1</manvolnum>
 790           </citerefentry> can be used to query the available UAMs of AFP
 791         servers as well.</para>
 792
 793         <para>Having a specific UAM available at the server does not
 794         automatically mean that a client can use it. Client-side support is
 795         also necessary. For older Macintoshes running Mac OS &lt; X DHCAST128
 796         support exists since AppleShare client 3.8.x.</para>
 797
 798         <para>On OS X, there exist some client-side techniques to make the
 799         AFP-client more verbose, so one can have a look what's happening while
 800         negotiating the UAMs to use. Compare with this <ulink
 801         url="http://article.gmane.org/gmane.network.netatalk.devel/7383/">hint</ulink>.</para>
 802       </sect3>
 803
 804       <sect3>
 805         <title>Which UAMs to activate?</title>
 806
 807         <para>It depends primarily on your needs and on the kind of Mac OS
 808         versions you have to support. Basically one should try to use
 809         DHCAST128 and DHX2 where possible because of its strength of password
 810         encryption.</para>
 811
 812         <itemizedlist>
 813           <listitem>
 814             <para>Unless you really have to supply guest access to your
 815             server's volumes ensure that you disable "No User Authent" since
 816             it might lead accidentally to unauthorized access. In case you
 817             must enable guest access take care that you enforce this on a per
 818             volume base using the access controls.</para>
 819           </listitem>
 820
 821           <listitem>
 822             <para>The "ClearTxt Passwrd" UAM is as bad as it sounds since
 823             passwords go unencrypted over the wire. Try to avoid it at both
 824             the server's side as well as on the client's. Note: If you want to
 825             provide Mac OS 8/9 clients with NetBoot-services then you need
 826             uams_cleartext.so since the AFP-client integrated into the Mac's
 827             firmware can only deal with this basic form of
 828             authentication.</para>
 829           </listitem>
 830
 831           <listitem>
 832             <para>Since "Randnum exchange"/"2-Way Randnum exchange" uses only
 833             56 bit DES for encryption it should be avoided as well. Another
 834             disadvantage is the fact that the passwords have to be stored in
 835             cleartext on the server and that it doesn't integrate into both
 836             PAM scenarios or classic /etc/shadow (you have to administrate
 837             passwords separately by using the <citerefentry>
 838                 <refentrytitle>afppasswd</refentrytitle>
 839
 840                 <manvolnum>1</manvolnum>
 841               </citerefentry> utility, if clients should use these
 842             UAMs)</para>
 843           </listitem>
 844
 845           <listitem>
 846             <para>"DHCAST128" or "DHX2" should be a good compromise for most
 847             people since it combines stronger encryption with PAM
 848             integration.</para>
 849           </listitem>
 850
 851           <listitem>
 852             <para>Using the Kerberos V<indexterm>
 853                 <primary>Kerberos V</primary>
 854
 855                 <secondary>"Client Krb v2" UAM</secondary>
 856               </indexterm> ("Client Krb v2") UAM, it's possible to implement
 857             real single sign on scenarios using Kerberos tickets. The password
 858             is not sent over the network. Instead, the user password is used
 859             to decrypt a service ticket for the appleshare server. The service
 860             ticket contains an encryption key for the client and some
 861             encrypted data (which only the appleshare server can decrypt). The
 862             encrypted portion of the service ticket is sent to the server and
 863             used to authenticate the user. Because of the way that the afpd
 864             service principal detection is implemented, this authentication
 865             method is vulnerable to man-in-the-middle attacks.</para>
 866           </listitem>
 867         </itemizedlist>
 868
 869         <para>For a more detailed overview over the technical implications of
 870         the different UAMs, please have a look at Apple's <ulink
 871         url="http://developer.apple.com/library/mac/#documentation/Networking/Conceptual/AFP/AFPSecurity/AFPSecurity.html#//apple_ref/doc/uid/TP40000854-CH232-SW1">File
 872         Server Security</ulink> pages.</para>
 873       </sect3>
 874
 875       <sect3>
 876         <title>Using different authentication sources with specific
 877         UAMs</title>
 878
 879         <para>Some UAMs provide the ability to use different authentication
 880         "backends", namely <filename>uams_cleartext.so</filename>,
 881         <filename>uams_dhx.so</filename> and
 882         <filename>uams_dhx2.so</filename>. They can use either classic Unix
 883         passwords from <filename>/etc/passwd</filename>
 884         (<filename>/etc/shadow</filename>) or PAM if the system supports that.
 885         <filename>uams_cleartext.so</filename> can be symlinked to either
 886         <filename>uams_passwd.so</filename> or
 887         <filename>uams_pam.so</filename>, <filename>uams_dhx.so</filename> to
 888         <filename>uams_dhx_passwd.so</filename> or
 889         <filename>uams_dhx_pam.so</filename> and
 890         <filename>uams_dhx2.so</filename> to
 891         <filename>uams_dhx2_passwd.so</filename> or
 892         <filename>uams_dhx2_pam.so</filename>.</para>
 893
 894         <para>So, if it looks like this in Netatalk's UAMs folder (per default
 895         <filename>/etc/netatalk/uams/</filename>):<programlisting>uams_clrtxt.so -&gt; uams_pam.so
 896 uams_dhx.so -&gt; uams_dhx_pam.so
 897 uams_dhx2.so -&gt; uams_dhx2_pam.so</programlisting> then you're using PAM,
 898         otherwise classic Unix passwords. The main advantage of using PAM is
 899         that one can integrate Netatalk in centralized authentication
 900         scenarios, eg. via LDAP, NIS and the like. Please always keep in mind
 901         that the protection of your user's login credentials in such scenarios
 902         also depends on the strength of encryption that the UAM in question
 903         supplies. So think about eliminating weak UAMs like "ClearTxt Passwrd"
 904         and "Randnum exchange" completely from your network.</para>
 905       </sect3>
 906
 907       <sect3>
 908         <title>Netatalk UAM overview table</title>
 909
 910         <para>A small overview of the most common used UAMs.</para>
 911
 912         <table orient="land">
 913           <title>Netatalk UAM overview</title>
 914
 915           <tgroup align="center" cols="7">
 916             <colspec colname="col1" colnum="1" colwidth="0.5*" />
 917
 918             <colspec colname="uam_guest" colnum="2" colwidth="1*" />
 919
 920             <colspec colname="uam_clrtxt" colnum="3" colwidth="1*" />
 921
 922             <colspec colname="uam_randnum" colnum="4" colwidth="1*" />
 923
 924             <colspec colname="uam_dhx" colnum="5" colwidth="1*" />
 925
 926             <colspec colname="uam_dhx2" colnum="6" colwidth="1*" />
 927
 928             <colspec colname="uam_gss" colnum="7" colwidth="1*" />
 929
 930             <tbody>
 931               <row>
 932                 <entry align="center" rotate="0" valign="middle">UAM</entry>
 933
 934                 <entry>No User Authent<indexterm>
 935                     <primary>uams_guest.so</primary>
 936
 937                     <secondary>"No User Authent" UAM (guest
 938                     access)</secondary>
 939                   </indexterm></entry>
 940
 941                 <entry>Cleartxt Passwrd<indexterm>
 942                     <primary>uams_cleartxt.so</primary>
 943
 944                     <secondary>"Cleartxt Passwrd" UAM</secondary>
 945                   </indexterm></entry>
 946
 947                 <entry>(2-Way) Randnum exchange<indexterm>
 948                     <primary>uams_randnum.so</primary>
 949
 950                     <secondary>"(2-Way) Randnum exchange" UAM</secondary>
 951                   </indexterm></entry>
 952
 953                 <entry>DHCAST128<indexterm>
 954                     <primary>uams_dhx.so</primary>
 955
 956                     <secondary>"DHCAST128" UAM</secondary>
 957                   </indexterm></entry>
 958
 959                 <entry>DHX2<indexterm>
 960                     <primary>uams_dhx2.so</primary>
 961
 962                     <secondary>"DHX2" UAM</secondary>
 963                   </indexterm></entry>
 964
 965                 <entry>Client Krb v2<indexterm>
 966                     <primary>uams_gss.so</primary>
 967
 968                     <secondary>"Client Krb v2" UAM (Kerberos V)</secondary>
 969                   </indexterm></entry>
 970               </row>
 971
 972               <row>
 973                 <entry align="center" rotate="0" valign="middle">pssword
 974                 length</entry>
 975
 976                 <entry>guest access</entry>
 977
 978                 <entry>max. 8 characters</entry>
 979
 980                 <entry>max. 8 characters</entry>
 981
 982                 <entry>max. 64 characters</entry>
 983
 984                 <entry>max. 256 characters</entry>
 985
 986                 <entry>Kerberos tickets</entry>
 987               </row>
 988
 989               <row>
 990                 <entry align="center" rotate="0" valign="middle">Client
 991                 support</entry>
 992
 993                 <entry>built-in into all Mac OS versions</entry>
 994
 995                 <entry>built-in in all Mac OS versions except 10.0. Has to be
 996                 activated explicitly in recent Mac OS X versions</entry>
 997
 998                 <entry>built-in into almost all Mac OS versions</entry>
 999
1000                 <entry>built-in since AppleShare client 3.8.4, available as a
1001                 plug-in for 3.8.3, integrated in Mac OS X' AFP client</entry>
1002
1003                 <entry>built-in since Mac OS X 10.2</entry>
1004
1005                 <entry>built-in since Mac OS X 10.2</entry>
1006               </row>
1007
1008               <row>
1009                 <entry align="center" rotate="0"
1010                 valign="middle">Encryption</entry>
1011
1012                 <entry>Enables guest access without authentication between
1013                 client and server.</entry>
1014
1015                 <entry>Password will be sent in cleartext over the wire. Just
1016                 as bad as it sounds, therefore avoid at all if possible (note:
1017                 providing NetBoot services requires the ClearTxt UAM)</entry>
1018
1019                 <entry>8-byte random numbers are sent over the wire,
1020                 comparable with DES, 56 bits. Vulnerable to offline dictionary
1021                 attack. Requires passwords in clear on the server.</entry>
1022
1023                 <entry>Password will be encrypted with 128 bit SSL, user will
1024                 be authenticated against the server but not vice versa.
1025                 Therefor weak against man-in-the-middle attacks.</entry>
1026
1027                 <entry>Password will be encrypted using libgcrypt with CAST
1028                 128 in CBC mode. User will be authenticated against the server
1029                 but not vice versa. Therefor weak against man-in-the-middle
1030                 attacks.</entry>
1031
1032                 <entry>Password is not sent over the network. Due to the
1033                 service principal detection method, this authentication method
1034                 is vulnerable to man-in-the-middle attacks.</entry>
1035               </row>
1036
1037               <row>
1038                 <entry align="center" rotate="0" valign="middle">Server
1039                 support</entry>
1040
1041                 <entry align="center" valign="middle">uams_guest.so</entry>
1042
1043                 <entry align="center" valign="middle">uams_cleartxt.so</entry>
1044
1045                 <entry align="center" valign="middle">uams_randnum.so</entry>
1046
1047                 <entry align="center" valign="middle">uams_dhx.so</entry>
1048
1049                 <entry align="center" valign="middle">uams_dhx2.so</entry>
1050
1051                 <entry align="center" valign="middle">uams_gss.so</entry>
1052               </row>
1053
1054               <row>
1055                 <entry align="center" rotate="0" valign="middle">Password
1056                 storage method</entry>
1057
1058                 <entry align="center" valign="middle">None</entry>
1059
1060                 <entry align="center" valign="middle">Either /etc/passwd
1061                 (/etc/shadow) or PAM</entry>
1062
1063                 <entry align="center" valign="middle">Passwords stored in
1064                 clear text in a separate text file</entry>
1065
1066                 <entry align="center" valign="middle">Either /etc/passwd
1067                 (/etc/shadow) or PAM</entry>
1068
1069                 <entry align="center" valign="middle">Either /etc/passwd
1070                 (/etc/shadow) or PAM</entry>
1071
1072                 <entry align="center" valign="middle">At the Kerberos Key
1073                 Distribution Center*</entry>
1074               </row>
1075             </tbody>
1076           </tgroup>
1077         </table>
1078
1079         <para>* Have a look at this <ulink
1080         url="http://cryptnet.net/fdp/admin/kerby-infra/en/kerby-infra.html">Kerberos
1081         overview</ulink></para>
1082       </sect3>
1083
1084       <sect3 id="sshtunnel">
1085         <title>SSH tunneling</title>
1086
1087         <para>Tunneling and all sort of VPN stuff has nothing to do with AFP
1088         authentication and UAMs in general. But since Apple introduced an
1089         option called "Allow Secure Connections Using SSH" and many people
1090         tend to confuse both things, we'll speak about that here too.</para>
1091
1092         <sect4 id="manualsshtunnel">
1093           <title>Manually tunneling an AFP session</title>
1094
1095           <para>This works since the first AFP servers that spoke "AFP over
1096           TCP" appeared in networks. One simply tunnels the remote server's
1097           AFP port to a local port different than 548 and connects locally to
1098           this port afterwards. On OS X this can be done by</para>
1099
1100           <programlisting>ssh -l $USER $SERVER -L 10548:127.0.0.1:548 sleep 3000</programlisting>
1101
1102           <para>After establishing the tunnel one will use
1103           <filename>"afp://127.0.0.1:10548"</filename> in the "Connect to
1104           server" dialog. All AFP traffic including the initial connection
1105           attempts will be sent encrypted over the wire since the local AFP
1106           client will connect to the Mac's local port 10548 which will be
1107           forwarded to the remote server's AFP port (we used the default 548)
1108           over SSH.</para>
1109
1110           <para>These sorts of tunnels are an ideal solution if you've to
1111           access an AFP server providing weak authentications mechanisms
1112           through the Internet without having the ability to use a "real" VPN.
1113           Note that you can let <command>ssh</command> compress the data by
1114           using its "-C" switch and that the tunnel endpoints can be different
1115           from both AFP client and server (compare with the SSH documentation
1116           for details).</para>
1117         </sect4>
1118
1119         <sect4 id="autosshtunnel">
1120           <title>Automatically establishing a tunneled AFP connection</title>
1121
1122           <para>From Mac OS X 10.2 to 10.4, Apple added an "Allow Secure
1123           Connections Using SSH" checkbox to the "Connect to Server" dialog.
1124           The idea behind: When the server signals that it can be contacted by
1125           SSH then Mac OS X' AFP client tries to establish the tunnel and
1126           automagically sends all AFP traffic through it.</para>
1127
1128           <para>But it took until the release of Mac OS X 10.3 that this
1129           feature worked the first time... partly. In case, the SSH tunnel
1130           can't be established the AFP client <emphasis
1131           role="strong">silently</emphasis> fell back to an unencrypted AFP
1132           connection attempt.</para>
1133
1134           <para>Netatalk's afpd will report that it is capable of handling SSH
1135           tunneled AFP requests, when both "<option>advertise ssh</option>"
1136           and "<option>fqdn</option>" options are set in
1137           <option>Global</option> section (double check with <citerefentry>
1138               <refentrytitle>asip-status.pl</refentrytitle>
1139
1140               <manvolnum>1</manvolnum>
1141             </citerefentry> after you restarted afpd when you made changes to
1142           the settings). But there are a couple of reasons why you don't want
1143           to use this option at all:</para>
1144
1145           <itemizedlist>
1146             <listitem>
1147               <para>Tunneling TCP over TCP (as SSH does) is not the best idea.
1148               There exist better solutions like VPNs based on the IP
1149               layer.</para>
1150             </listitem>
1151
1152             <listitem>
1153               <para>Since this SSH kludge isn't a normal UAM that integrates
1154               directly into the AFP authentication mechanisms but instead uses
1155               a single flag signalling clients whether they can <emphasis
1156               role="strong">try</emphasis> to establish a tunnel or not, it
1157               makes life harder to see what's happening when things go
1158               wrong.</para>
1159             </listitem>
1160
1161             <listitem>
1162               <para>You cannot control which machines are logged on by
1163               Netatalk tools like a <command>macusers</command> since all
1164               connection attempts seem to be made from localhost.</para>
1165             </listitem>
1166
1167             <listitem>
1168               <para>On the other side you've to limit access to afpd to
1169               localhost only (TCP wrappers) when you want to ensure that all
1170               AFP sessions are SSH encrypted or...</para>
1171             </listitem>
1172
1173             <listitem>
1174               <para>...when you're using 10.2 - 10.3.3 then you get the
1175               opposite of what you'd expect: potentially unencrypted AFP
1176               communication (including logon credentials) on the network
1177               without a single notification that establishing the tunnel
1178               failed. Apple fixed that not until Mac OS X 10.3.4.</para>
1179             </listitem>
1180
1181             <listitem>
1182               <para>Encrypting all AFP sessions via SSH can lead to a
1183               significantly higher load on the Netatalk server</para>
1184             </listitem>
1185           </itemizedlist>
1186         </sect4>
1187       </sect3>
1188     </sect2>
1189
1190     <sect2 id="acls">
1191       <title>ACL Support<indexterm>
1192           <primary>ACLs</primary>
1193         </indexterm></title>
1194
1195       <para>ACL support for AFP is implemented for ZFS ACLs on Solaris and
1196       derived platforms and for POSIX 1e ACLs on Linux.</para>
1197
1198       <sect3>
1199         <title>Configuration</title>
1200
1201         <para>For a basic mode of operation there's nothing to configure.
1202         Netatalk reads ACLs on the fly and calculates effective permissions
1203         which are then send to the AFP client via the so called
1204         UARights<indexterm>
1205             <primary>UARights</primary>
1206           </indexterm> permission bits. On a Mac, the Finder uses these bits
1207         to adjust permission in Finder windows. For example folder whos UNIX
1208         mode would only result in in read-only permissions for a user will not
1209         be displayed with a read-only icon and the user will be able to write
1210         to the folder given the folder has an ACL giving the user write
1211         access.</para>
1212
1213         <para>By default, the effective permission of the authenticated user
1214         are only mapped to the mentioned UARights<indexterm>
1215             <primary>UARights</primary>
1216           </indexterm>permission structure, not the UNIX mode. You can adjust
1217         this behaviour with the configuration option <link
1218         linkend="map_acls">map acls</link>.</para>
1219
1220         <para>However, neither in Finder "Get Info" windows nor in Terminal
1221         will you be able to see the ACLs, that's a result of how ACLs in OS X
1222         are designed. If you want to be able to display ACLs on the client,
1223         things get more involved as you must then setup both client and server
1224         to be part on a authentication domain (directory service, eg LDAP,
1225         OpenDirectory). The reason is, that in OS X ACLs are bound to UUIDs,
1226         not just uid's or gid's. Therefor afpd must be able to map every
1227         filesystem uid and gid to a UUID so that it can return the server side
1228         ACLs which are bound to UNIX uid and gid mapped to OS X UUIDs.</para>
1229
1230         <para>Netatalk can query a directory server using LDAP queries. Either
1231         the directory server already provides an UUID attribute for user and
1232         groups (Active Directory, Open Directory) or you reuse an unused
1233         attribute (or add a new one) to you directory server (eg
1234         OpenLDAP).</para>
1235
1236         <para>In detail:</para>
1237
1238         <orderedlist>
1239           <listitem>
1240             <para>For Solaris/ZFS: ZFS Volumes</para>
1241
1242             <para>You should configure a ZFS ACL know for any volume you want
1243             to use with Netatalk:</para>
1244
1245             <screen>aclinherit = passthrough
1246 aclmode = passthrough</screen>
1247
1248             <para>For an explanation of what this knob does and how to apply
1249             it, check your hosts ZFS documentation (eg man zfs).</para>
1250           </listitem>
1251
1252           <listitem>
1253             <para>Authentication Domain</para>
1254
1255             <para>Your server and the clients must be part of a security
1256             association where identity data is coming from a common source.
1257             ACLs in Darwin are based on UUIDs and so is the ACL specification
1258             in AFP 3.2. Therefor your source of identity data has to provide
1259             an attribute for every user and group where a UUID is stored as a
1260             ASCII string. In other words:</para>
1261
1262             <itemizedlist>
1263               <listitem>
1264                 <para>you need an Open Directory Server or an LDAP server
1265                 where you store UUIDs in some attribute</para>
1266               </listitem>
1267
1268               <listitem>
1269                 <para>your clients must be configured to use this
1270                 server</para>
1271               </listitem>
1272
1273               <listitem>
1274                 <para>your server should be configured to use this server via
1275                 nsswitch and PAM</para>
1276               </listitem>
1277
1278               <listitem>
1279                 <para>configure Netatalk via the special <link
1280                 linkend="acl_options">LDAP options for ACLs</link> in <link
1281                 linkend="afp.conf.5">afp.conf</link> so that Netatalk is able
1282                 to retrieve the UUID for users and groups via LDAP search
1283                 queries</para>
1284               </listitem>
1285             </itemizedlist>
1286           </listitem>
1287         </orderedlist>
1288       </sect3>
1289
1290       <sect3>
1291         <title>OS X ACLs</title>
1292
1293         <para>With Access Control Lists (ACLs) Mac OS X offers a powerful
1294         extension of the traditional UNIX permissions model. An ACL is an
1295         ordered list of Access Control Entries (ACEs) explicitly granting or
1296         denying a set of permissions to a given user or group.</para>
1297
1298         <para>Unlike UNIX permissions, which are bound to user or group IDs,
1299         ACLs are tied to UUIDs. For this reason accessing an object's ACL
1300         requires server and client to use a common directory service which
1301         translates between UUIDs and user/group IDs.</para>
1302
1303         <para>ACLs and UNIX permissions interact in a rather simple way. As
1304         ACLs are optional UNIX permissions act as a default mechanism for
1305         access control. Changing an objects's UNIX permissions will leave it's
1306         ACL intact and modifying an ACL will never change the object's UNIX
1307         permissions. While doing access checks, OS X first examines an
1308         object's ACL evaluating ACEs in order until all requested rights have
1309         been granted, a requested right has been explicitly denied by an ACE
1310         or the end of the list has been reached. In case there is no ACL or
1311         the permissions granted by the ACL are not sufficient to fulfill the
1312         request, OS X next evaluates the object's UNIX permissions. Therefore
1313         ACLs always have precedence over UNIX permissions.</para>
1314       </sect3>
1315
1316       <sect3>
1317         <title>ZFS ACLs</title>
1318
1319         <para>ZFS ACLs closely match OS X ACLs. Both offer mostly identical
1320         fine grained permissions and inheritance settings.</para>
1321       </sect3>
1322
1323       <sect3>
1324         <title>POSIX ACLs</title>
1325
1326         <sect4>
1327           <title>Overview</title>
1328
1329           <para>Compared to OS X or NFSv4 ACLs, Posix ACLs represent a
1330           different, less versatile approach to overcome the limitations of
1331           the traditional UNIX permissions. Implementations are based on the
1332           withdrawn Posix 1003.1e standard.</para>
1333
1334           <para>The standard defines two types of ACLs. Files and directories
1335           can have access ACLs which are consulted for access checks.
1336           Directories can also have default ACLs irrelevant to access checks.
1337           When a new object is created inside a directory with a default ACL,
1338           the default ACL is applied to the new object as it's access ACL.
1339           Subdirectories inherit default ACLs from their parent. There are no
1340           further mechanisms of inheritance control.</para>
1341
1342           <para>Architectural differences between Posix ACLs and OS X ACLs
1343           especially involve:</para>
1344
1345           <para><itemizedlist>
1346               <listitem>
1347                 <para>No fine-granular permissions model. Like UNIX
1348                 permissions Posix ACLs only differentiate between read, write
1349                 and execute permissions.</para>
1350               </listitem>
1351
1352               <listitem>
1353                 <para>Entries within an ACL are unordered.</para>
1354               </listitem>
1355
1356               <listitem>
1357                 <para>Posix ACLs can only grant rights. There is no way to
1358                 explicitly deny rights by an entry.</para>
1359               </listitem>
1360
1361               <listitem>
1362                 <para>UNIX permissions are integrated into an ACL as special
1363                 entries.</para>
1364               </listitem>
1365             </itemizedlist></para>
1366
1367           <para>Posix 1003.1e defines 6 different types of ACL entries. The
1368           first three types are used to integrate standard UNIX permissions.
1369           They form a minimal ACL, their presence is mandatory and only one
1370           entry of each type is allowed within an ACL.</para>
1371
1372           <para><itemizedlist>
1373               <listitem>
1374                 <para>ACL_USER_OBJ: the owner's access rights.</para>
1375               </listitem>
1376
1377               <listitem>
1378                 <para>ACL_GROUP_OBJ: the owning group's access rights.</para>
1379               </listitem>
1380
1381               <listitem>
1382                 <para>ACL_OTHER: everybody's access rights.</para>
1383               </listitem>
1384             </itemizedlist></para>
1385
1386           <para>The remaining entry types expand the traditional permissions
1387           model:</para>
1388
1389           <para><itemizedlist>
1390               <listitem>
1391                 <para>ACL_USER: grants access rights to a certain user.</para>
1392               </listitem>
1393
1394               <listitem>
1395                 <para>ACL_GROUP: grants access rights to a certain
1396                 group.</para>
1397               </listitem>
1398
1399               <listitem>
1400                 <para>ACL_MASK: limits the maximum access rights which can be
1401                 granted by entries of type ACL_GROUP_OBJ, ACL_USER and
1402                 ACL_GROUP. As the name suggests, this entry acts as a mask.
1403                 Only one ACL_MASK entry is allowed per ACL. If an ACL contains
1404                 ACL_USER or ACL_GROUP entries, an ACL_MASK entry must be
1405                 present too, otherwise it is optional.</para>
1406               </listitem>
1407             </itemizedlist></para>
1408
1409           <para>In order to maintain compatibility with applications not aware
1410           of ACLs, Posix 1003.1e changes the semantics of system calls and
1411           utilities which retrieve or manipulate an objects UNIX permissions.
1412           In case an object only has a minimal ACL, the group permissions bits
1413           of the UNIX permissions correspond to the value of the ACL_GROUP_OBJ
1414           entry.</para>
1415
1416           <para>However, if the ACL also contains an ACL_MASK entry, the
1417           behavior of those system calls and utilities is different. The group
1418           permissions bits of the UNIX permissions correspond to the value of
1419           the ACL_MASK entry, i. e. calling "chmod g-w" will not only revoke
1420           write access for the group, but for all entities which have been
1421           granted write access by ACL_USER or ACL_GROUP entries.</para>
1422         </sect4>
1423
1424         <sect4>
1425           <title>Mapping POSIX ACLs to OS X ACLs</title>
1426
1427           <para>When a client wants to read an object's ACL, afpd maps it's
1428           Posix ACL onto an equivalent OS X ACL. Writing an object's ACL
1429           requires afpd to map an OS X ACL onto a Posix ACL. Due to
1430           architectural restrictions of Posix ACLs, it is usually impossible
1431           to find an exact mapping so that the result of the mapping process
1432           will be an approximation of the original ACL's semantic.</para>
1433
1434           <para><itemizedlist>
1435               <listitem>
1436                 <para>afpd silently discard entries which deny a set of
1437                 permissions because they they can't be represented within the
1438                 Posix architecture.</para>
1439               </listitem>
1440
1441               <listitem>
1442                 <para>As entries within Posix ACLs are unordered, it is
1443                 impossible to preserve order.</para>
1444               </listitem>
1445
1446               <listitem>
1447                 <para>Inheritance control is subject to severe limitations as
1448                 well:<itemizedlist>
1449                     <listitem>
1450                       <para>Entries with the only_inherit flag set will only
1451                       become part of the directory's default ACL.</para>
1452                     </listitem>
1453
1454                     <listitem>
1455                       <para>Entries with at least one of the flags
1456                       file_inherit, directory_inherit or limit_inherit set,
1457                       will become part of the directory's access and default
1458                       ACL, but the restrictions they impose on inheritance
1459                       will be ignored.</para>
1460                     </listitem>
1461                   </itemizedlist></para>
1462               </listitem>
1463
1464               <listitem>
1465                 <para>The lack of a fine-granular permission model on the
1466                 Posix side will normally result in an increase of granted
1467                 permissions.</para>
1468               </listitem>
1469             </itemizedlist></para>
1470
1471           <para>As OS X clients aren't aware of the Posix 1003.1e specific
1472           relationship between UNIX permissions and ACL_MASK, afpd does not
1473           expose this feature to the client to avoid compatibility issues and
1474           handles *unix permissions and ACLs the same way as Apple's reference
1475           implementation of AFP does. When an object's UNIX permissions are
1476           requested, afpd calculates proper group rights and returns the
1477           result together with the owner's and everybody's access rights to
1478           the caller via "permissions" and "ua_permissions" members of the
1479           FPUnixPrivs structure (see Apple Filing Protocol Reference, page
1480           181). Changing an object's permissions, afpd always updates
1481           ACL_USER_OBJ, ACL_GROUP_OBJ and ACL_OTHERS. If an ACL_MASK entry is
1482           present too, afpd recalculates it's value so that the new group
1483           rights become effective and existing entries of type ACL_USER or
1484           ACL_GROUP stay intact.</para>
1485         </sect4>
1486       </sect3>
1487     </sect2>
1488
1489     <sect2 id="fce">
1490       <title>Filesystem Change Events<indexterm>
1491           <primary>FCE</primary>
1492         </indexterm></title>
1493
1494       <para>Netatalk includes a nifty filesystem change event mechanism where
1495       afpd processes notfiy interested listeners about certain filesystem
1496       event by UDP network datagrams.</para>
1497
1498       <para>For the format of the UDP packets and for an example C application
1499       that demonstrates how to use these in a listener, take a look at the
1500       Netatalk sourcefile <filename>bin/misc/fce.c</filename>.</para>
1501
1502       <para>The currently supported FCE events are<itemizedlist>
1503           <listitem>
1504             <para>file modification (fmod)</para>
1505           </listitem>
1506
1507           <listitem>
1508             <para>file deletion (fdel)</para>
1509           </listitem>
1510
1511           <listitem>
1512             <para>directory deletion (ddel)</para>
1513           </listitem>
1514
1515           <listitem>
1516             <para>file creation (fcre)</para>
1517           </listitem>
1518
1519           <listitem>
1520             <para>directory deletion (ddel)</para>
1521           </listitem>
1522         </itemizedlist></para>
1523
1524       <para>For details on the available simple configuration options take a
1525       look at <filename><link
1526       linkend="fceconf">afp.conf</link></filename>.</para>
1527     </sect2>
1528   </sect1>
1529
1530   <sect1>
1531     <title id="spotlight">Spotlight<indexterm>
1532         <primary>Spotlight</primary>
1533       </indexterm></title>
1534
1535     <para>Starting with version 3.1 Netatalk supports Spotlight searching.
1536     Netatalk uses Gnome <ulink url="https://projects.gnome.org/tracker/">Tracker</ulink> as metadata store,
1537     indexer and search engine.</para>
1538
1539     <sect2>
1540       <title>Configuration</title>
1541
1542       <para>You can enable Spotlight and indexing either globally or on a per
1543       volume basis with the <option>spotlight</option> option.</para>
1544
1545       <warning>
1546         <para>Once Spotlight is enable for a single volume, all other volumes
1547         for which spotlight is disabled won't be searchable at all.</para>
1548       </warning>
1549
1550       <para>In case the <command>dbus-daemon</command> binary is not installed
1551       at the path <filename>/bin/dbus-daemon</filename>, you must use the
1552       global option <option>dbus daemon</option> to point to the path, eg for
1553       Solaris with Tracker from OpenCSW: <screen>dbus daemon = /opt/csw/bin/dbus-daemon</screen></para>
1554     </sect2>
1555
1556     <sect2>
1557       <title>Limitations and notes</title>
1558
1559       <itemizedlist>
1560         <listitem>
1561           <para>Large filesystems</para>
1562
1563           <para>Tracker on Linux uses the inotify Kernel filesystem change
1564           event API for tracking filesystem changes. On large filesystems this
1565           may be problematic since the inotify API doesn't offer recursive
1566           directory watches but instead requires that for every subdirectoy
1567           watches must be added individually.</para>
1568
1569           <para>On Solaris the FEN file event notification system is used. It
1570           is unkown which limitations and ressource consumption this Solaris
1571           subsystem may have.</para>
1572
1573           <para>We therefor recommend to disable live filesystem monitoring
1574           and let Tracker periodically scan filesystems for changes instead,
1575           see the Tracker configuration options <link
1576           linkend="enable-monitors">enable-monitors</link> and <link
1577           linkend="crawling-interval">crawling-interval</link> below.</para>
1578         </listitem>
1579       </itemizedlist>
1580     </sect2>
1581
1582     <sect2>
1583       <title>Using Tracker commandline tools on the server</title>
1584
1585       <para>Netatalk must be running, commands must be executed as root and
1586       some environent variables must be set up (adjust PREFIX to point to
1587       the base directory Netatalk in installed to):<screen>$ su
1588 # cat .tracker_profile
1589 PREFIX="/"
1590 export XDG_DATA_HOME="$PREFIX/var/netatalk/"
1591 export XDG_CACHE_HOME="$PREFIX/var/netatalk/"
1592 export DBUS_SESSION_BUS_ADDRESS="unix:path=$PREFIX/var/netatalk/spotlight.ipc"
1593 # . .tracker_profile
1594 #
1595 </screen></para>
1596
1597       <para>When using Tracker from OpenCSW you must also update your
1598       PATH:<screen># export PATH=/opt/csw/bin:$PATH</screen></para>
1599
1600       <sect3>
1601         <title>Starting and stopping Tracker</title>
1602
1603         <variablelist>
1604           <varlistentry>
1605             <term>Querying Tracker status</term>
1606
1607             <listitem>
1608               <screen># tracker-control -S</screen>
1609             </listitem>
1610           </varlistentry>
1611
1612           <varlistentry>
1613             <term>Stop Tracker</term>
1614
1615             <listitem>
1616               <screen># tracker-control -t</screen>
1617             </listitem>
1618           </varlistentry>
1619
1620           <varlistentry>
1621             <term>Start Tracker status</term>
1622
1623             <listitem>
1624               <screen># tracker-control -s</screen>
1625             </listitem>
1626           </varlistentry>
1627         </variablelist>
1628       </sect3>
1629
1630       <sect3>
1631         <title>Reindex directory</title>
1632
1633         <screen># tracker-control -f PATH</screen>
1634       </sect3>
1635
1636       <sect3>
1637         <title>Query Tracker for information about a file or directory</title>
1638
1639         <screen># tracker-info PATH</screen>
1640       </sect3>
1641
1642       <sect3>
1643         <title>Search Tracker</title>
1644
1645         <screen># tracker-search QUERY</screen>
1646       </sect3>
1647     </sect2>
1648
1649     <sect2>
1650       <title>Advanced Tracker command line configuration</title>
1651
1652       <para>Tracker stores its configuration via Gnome dconf backend which can
1653       be modified with the command <command>gsettings</command>.</para>
1654
1655       <para>Gnome dconf settings are per-user settings, so, as Netatalk runs
1656       the Tracker processes as root, the settings are stored in the root user
1657       context and reading or changing these settings must be perfomed as root
1658       and Netatalk must be running (and again the enviroment must be set up
1659       as shown above).</para>
1660
1661       <para><screen># gsettings list-recursively | grep Tracker
1662 org.freedesktop.Tracker.Writeback verbosity 'debug'
1663 ...</screen></para>
1664
1665       <para>The following list describes some important Tracker options and
1666       their default settings.</para>
1667
1668       <variablelist>
1669         <varlistentry>
1670           <term>org.freedesktop.Tracker.Miner.Files
1671           index-recursive-directories</term>
1672
1673           <listitem>
1674             <para>This option controls which directories Tracker will index.
1675             Don't change this option manually as it is automatically set by
1676             Netatalk reflecting the setting of the <option>Spotlight</option>
1677             option of Netatalk volumes.</para>
1678           </listitem>
1679         </varlistentry>
1680
1681         <varlistentry>
1682           <term id="enable-monitors">org.freedesktop.Tracker.Miner.Files
1683           enable-monitors <parameter> true</parameter></term>
1684
1685           <listitem>
1686             <para>The value controls whether Tracker watches all configured
1687             paths for modification. Depending on the filesystem modification
1688             backend (FAM on Linux, FEN on Solaris), this feature may not work
1689             as reliable as one might wish, so it may be safer to disable it
1690             and instead rely on periodic crawling of Tracker itself. See aslo
1691             the option <option>crawling-interval </option>.</para>
1692           </listitem>
1693         </varlistentry>
1694
1695         <varlistentry>
1696           <term id="crawling-interval">org.freedesktop.Tracker.Miner.Files
1697           crawling-interval <parameter>-1</parameter></term>
1698
1699           <listitem>
1700             <para>Interval in days to check the filesystem is up to date in
1701             the database, maximum is 365, default is -1. -2 = crawling is
1702             disabled entirely, -1 = crawling *may* occur on startup (if not
1703             cleanly shutdown), 0 = crawling is forced</para>
1704           </listitem>
1705         </varlistentry>
1706       </variablelist>
1707     </sect2>
1708
1709     <sect2>
1710       <title>Supported metadata attributes</title>
1711
1712       <para>The following table lists the supported Spotlight metadata
1713       attributes</para>
1714
1715       <table>
1716         <title>Supported Spotlight metadata attributes</title>
1717
1718         <tgroup cols="2">
1719           <thead>
1720             <row>
1721               <entry align="center">Description</entry>
1722
1723               <entry align="center">Spotlight Key</entry>
1724             </row>
1725           </thead>
1726
1727           <tbody>
1728             <row>
1729               <entry>Name</entry>
1730
1731               <entry>kMDItemDisplayName, kMDItemFSName</entry>
1732             </row>
1733
1734             <row>
1735               <entry>Document content (full text search)</entry>
1736
1737               <entry>kMDItemTextContent</entry>
1738             </row>
1739
1740             <row>
1741               <entry>File type</entry>
1742
1743               <entry>_kMDItemGroupId, kMDItemContentTypeTree</entry>
1744             </row>
1745
1746             <row>
1747               <entry>File modification date</entry>
1748
1749               <entry>kMDItemFSContentChangeDate,
1750               kMDItemContentModificationDate,
1751               kMDItemAttributeChangeDate</entry>
1752             </row>
1753
1754             <row>
1755               <entry>Content Creation date</entry>
1756
1757               <entry>kMDItemContentCreationDate</entry>
1758             </row>
1759
1760             <row>
1761               <entry>The author, or authors, of the contents of the
1762               file</entry>
1763
1764               <entry>kMDItemAuthors, kMDItemCreator</entry>
1765             </row>
1766
1767             <row>
1768               <entry>The name of the country where the item was
1769               created</entry>
1770
1771               <entry>kMDItemCountry</entry>
1772             </row>
1773
1774             <row>
1775               <entry>Duration</entry>
1776
1777               <entry>kMDItemDurationSeconds</entry>
1778             </row>
1779
1780             <row>
1781               <entry>Number of pages</entry>
1782
1783               <entry>kMDItemNumberOfPages</entry>
1784             </row>
1785
1786             <row>
1787               <entry>Document title</entry>
1788
1789               <entry>kMDItemTitle</entry>
1790             </row>
1791
1792             <row>
1793               <entry>The width, in pixels, of the contents. For example, the
1794               image width or the video frame width</entry>
1795
1796               <entry>kMDItemPixelWidth</entry>
1797             </row>
1798
1799             <row>
1800               <entry>The height, in pixels, of the contents. For example, the
1801               image height or the video frame height</entry>
1802
1803               <entry>kMDItemPixelHeight</entry>
1804             </row>
1805
1806             <row>
1807               <entry>The color space model used by the document
1808               contents</entry>
1809
1810               <entry>kMDItemColorSpace</entry>
1811             </row>
1812
1813             <row>
1814               <entry>The number of bits per sample</entry>
1815
1816               <entry>kMDItemBitsPerSample</entry>
1817             </row>
1818
1819             <row>
1820               <entry>Focal length of the lens, in millimeters</entry>
1821
1822               <entry>kMDItemFocalLength</entry>
1823             </row>
1824
1825             <row>
1826               <entry>ISO speed</entry>
1827
1828               <entry>kMDItemISOSpeed</entry>
1829             </row>
1830
1831             <row>
1832               <entry>Orientation of the document. Possible values are 0
1833               (landscape) and 1 (portrait)</entry>
1834
1835               <entry>kMDItemOrientation</entry>
1836             </row>
1837
1838             <row>
1839               <entry>Resolution width, in DPI</entry>
1840
1841               <entry>kMDItemResolutionWidthDPI</entry>
1842             </row>
1843
1844             <row>
1845               <entry>Resolution height, in DPI</entry>
1846
1847               <entry>kMDItemResolutionHeightDPI</entry>
1848             </row>
1849
1850             <row>
1851               <entry>Exposure time, in seconds</entry>
1852
1853               <entry>kMDItemExposureTimeSeconds</entry>
1854             </row>
1855
1856             <row>
1857               <entry>The composer of the music contained in the audio
1858               file</entry>
1859
1860               <entry>kMDItemComposer</entry>
1861             </row>
1862
1863             <row>
1864               <entry>The musical genre of the song or composition</entry>
1865
1866               <entry>kMDItemMusicalGenre</entry>
1867             </row>
1868           </tbody>
1869         </tgroup>
1870       </table>
1871
1872     </sect2>
1873
1874     <sect2>
1875       <title>References</title>
1876
1877       <orderedlist>
1878         <listitem>
1879           <para><ulink
1880           url="https://developer.apple.com/library/mac/#documentation/Carbon/Reference/MDItemRef/Reference/reference.html">MDItem</ulink></para>
1881         </listitem>
1882
1883         <listitem>
1884           <para><ulink
1885           url="https://live.gnome.org/Tracker/Documentation">Tracker</ulink></para>
1886         </listitem>
1887       </orderedlist>
1888     </sect2>
1889   </sect1>
1890
1891   <sect1>
1892     <title>Starting and stopping Netatalk</title>
1893
1894     <para>The Netatalk distribution comes with several operating system
1895     specific startup script templates that are tailored according to the
1896     options given to the "configure" script before compiling. Currently,
1897     templates are provided for RedHat (sysv style), RedHat (systemd style),
1898     SUSE (sysv style), SUSE (systemd style), Gentoo, NetBSD, Debian and
1899     Solaris. You can select to install the generated startup script(s)
1900     <indexterm>
1901         <primary>Startscript</primary>
1902
1903         <secondary>startup script</secondary>
1904       </indexterm> by specifying a system type to "configure". To
1905     automatically install startup scripts give one of the available
1906     <option>--with-init-style</option> option to "configure".</para>
1907
1908     <para>Since new releases of Linux distributions appear all the time and
1909     the startup procedure for the other systems mentioned above might change
1910     as well, it is probably a good idea to not blindly install a startup
1911     script but to look at it first to see if it will work on your system. If
1912     you use Netatalk as part of a fixed setup, like a Linux distribution, an
1913     RPM or a BSD package, things will probably have been arranged properly for
1914     you. The following therefore applies mostly for people who have compiled
1915     Netatalk themselves.</para>
1916
1917     <para>The following daemon need to be started by whatever startup script
1918     mechanism is used:</para>
1919
1920     <itemizedlist>
1921       <listitem>
1922         <para>netatalk<indexterm>
1923             <primary>netatalk</primary>
1924           </indexterm></para>
1925       </listitem>
1926     </itemizedlist>
1927
1928     <para>Additionally, make sure that the configuration file
1929     <filename>afp.conf</filename> is in the right place.</para>
1930   </sect1>
1931 </chapter>