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