1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="configuration">
3 <title>Setting up Netatalk</title>
6 <title>File Services<indexterm>
7 <primary>File Services</primary>
9 <secondary>Netatalk's File Services</secondary>
12 <para>Netatalk supplies AFP<indexterm>
13 <primary>AFP</primary>
15 <secondary>Apple Filing Protocol</secondary>
16 </indexterm> services.</para>
19 <title>Setting up the AFP file server</title>
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>
27 <secondary>Mac OS X 10.6</secondary>
28 </indexterm> (Mac OS X 10.6).</para>
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>
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>
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 =
47 <para>Starting with Netatalk 2.1 UNIX symlinks<indexterm>
48 <primary>symlink</primary>
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>
57 <title>afp.conf</title>
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>
63 <para>The <filename>afp.conf</filename> is divided into several
64 sections:<variablelist>
69 <para>The global section defines general server options</para>
77 <para>The homes section defines user home volumes</para>
80 </variablelist>Any section not called <option>Global</option> or
81 <option>Homes</option> is interpreted as an AFP volume.</para>
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>
90 <para><programlisting>[Homes]
92 </programlisting></para>
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>
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>
101 <para>/RAID1/homes</para>
105 <para>/RAID2/morehomes</para>
107 </itemizedlist>The following configuration is
108 required:<programlisting>[Homes]
109 basedir regex = /RAID./.*homes
110 </programlisting></para>
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>
117 <para>For a more detailed explanation of the available options, please
118 refer to the <citerefentry>
119 <refentrytitle>afp.conf</refentrytitle>
121 <manvolnum>5</manvolnum>
122 </citerefentry> man page.</para>
126 <sect2 id="CNID-backends">
127 <title>CNID<indexterm>
128 <primary>CNID</primary>
130 <secondary>Catalog Node ID</secondary>
131 </indexterm> backends<indexterm>
132 <primary>Backend</primary>
134 <secondary>CNID backend</secondary>
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>
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>
150 <para>Every file in an AFP volume has to have a unique file ID<indexterm>
151 <primary>FID</primary>
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
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>
167 <secondary>specifying a CNID backend</secondary>
168 </indexterm> option in the <citerefentry>
169 <refentrytitle>afp.conf</refentrytitle>
171 <manvolnum>5</manvolnum>
172 </citerefentry> configuration file. A CNID backend is basically a
173 database storing ID <-> name mappings.</para>
175 <para>The CNID Databases are by default located in
176 <filename>/var/netatalk/CNID</filename>.</para>
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
183 <para>There are some CNID related things you should keep in mind when
184 working with netatalk:</para>
188 <para>Don't nest volumes<indexterm>
189 <primary>Nested volumes</primary>
194 <para>CNID backends are databases, so they turn afpd into a file
195 server/database mix.</para>
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
205 <primary>Quotas</primary>
207 <secondary>Disk usage quotas</secondary>
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
218 <primary>NFS</primary>
220 <secondary>Network File System</secondary>
221 </indexterm> mounted volumes.</para>
227 <title>cdb<indexterm>
228 <primary>CDB</primary>
230 <secondary>"cdb" CNID backend</secondary>
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>
244 <title>dbd<indexterm>
245 <primary>DBD</primary>
247 <secondary>"dbd" CNID backend</secondary>
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
255 <para>This is the default backend since Netatalk 2.1.</para>
259 <title>tdb<indexterm>
260 <primary>tdb</primary>
262 <secondary>"tdb" CNID backend</secondary>
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
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>
278 <title>last<indexterm>
279 <primary>Last</primary>
281 <secondary>"last" CNID backend</secondary>
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
291 <sect2 id="charsets">
292 <title>Charsets<indexterm>
293 <primary>Charset</primary>
295 <secondary>character set</secondary>
296 </indexterm>/Unicode<indexterm>
297 <primary>Unicode</primary>
303 <title>Why Unicode?</title>
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
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
317 <primary>ASCII</primary>
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>
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
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>
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>
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>
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>
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>
366 <title>character sets used by Apple</title>
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>
373 <para>Codepages defined by Apple include:</para>
377 <para>MacArabic, MacFarsi</para>
381 <para>MacCentralEurope</para>
385 <para>MacChineseSimple</para>
389 <para>MacChineseTraditional</para>
393 <para>MacCroation</para>
397 <para>MacCyrillic</para>
401 <para>MacDevanagari</para>
405 <para>MacGreek</para>
409 <para>MacHebrew</para>
413 <para>MacIcelandic</para>
417 <para>MacJapanese</para>
421 <para>MacKorean</para>
425 <para>MacRoman</para>
429 <para>MacRomanian</para>
437 <para>MacTurkish</para>
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>
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>
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>
460 <secondary>Decomposed Unicode normalization</secondary>
461 </indexterm> normalization.</para>
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>
470 <para>Netatalk refers to precomposed UTF-8 as
471 <emphasis>UTF8</emphasis><indexterm>
472 <primary>UTF8</primary>
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>
479 <secondary>Netatalk's decomposed UTF-8 encoding</secondary>
484 <title>afpd and character sets</title>
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>
491 <para>At the time of this writing, netatalk supports the following
492 Apple codepages:</para>
496 <para>MAC_CENTRALEUROPE</para>
500 <para>MAC_CHINESE_SIMP</para>
504 <para>MAC_CHINESE_TRAD</para>
508 <para>MAC_CYRILLIC</para>
512 <para>MAC_GREEK</para>
516 <para>MAC_HEBREW</para>
520 <para>MAC_JAPANESE</para>
524 <para>MAC_KOREAN</para>
528 <para>MAC_ROMAN</para>
532 <para>MAC_TURKISH</para>
536 <para>afpd handles three different character set options:</para>
540 <term>unix charset<indexterm>
541 <primary>unix charset</primary>
543 <secondary>afpd's unix charset setting</secondary>
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
554 <refentrytitle>afp.conf</refentrytitle>
556 <manvolnum>5</manvolnum>
557 </citerefentry>.</para>
562 <term>mac charset<indexterm>
563 <primary>mac charset</primary>
565 <secondary>afpd's mac charset setting</secondary>
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
578 <refentrytitle>afp.conf</refentrytitle>
580 <manvolnum>5</manvolnum>
581 </citerefentry>.</para>
586 <term>vol charset<indexterm>
587 <primary>vol charset</primary>
589 <secondary>afpd's vol charset setting</secondary>
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>
599 <secondary>iconv encoding conversion engine</secondary>
600 </indexterm> installed, you can use any iconv provided charset
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>
609 <secondary>CAP style character encoding</secondary>
610 </indexterm>. An extended character (>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>
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>
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
630 <refentrytitle>afp.conf</refentrytitle>
632 <manvolnum>5</manvolnum>
633 </citerefentry>.</para>
640 <sect2 id="authentication">
641 <title>Authentication<indexterm>
642 <primary>Authentication</primary>
644 <secondary>between AFP client and server</secondary>
648 <title>AFP authentication basics</title>
650 <para>Apple chose a flexible model called "User Authentication
652 <primary>UAM</primary>
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>
660 <para>Several UAMs have been developed by Apple over the time, some by
661 3rd-party developers.</para>
665 <title>UAMs supported by Netatalk</title>
667 <para>Netatalk supports the following ones by default:</para>
671 <para>"No User Authent"<indexterm>
672 <primary>No User Authent</primary>
674 <secondary>"No User Authent" UAM (guest access)</secondary>
675 </indexterm> UAM (guest access without authentication)</para>
679 <para>"Cleartxt Passwrd"<indexterm>
680 <primary>Cleartxt Passwrd</primary>
682 <secondary>"Cleartxt Passwrd" UAM</secondary>
683 </indexterm> UAM (no password encryption)</para>
687 <para>"Randnum exchange"<indexterm>
688 <primary>Randnum exchange</primary>
690 <secondary>"Randnum exchange" UAM</secondary>
691 </indexterm>/"2-Way Randnum exchange"<indexterm>
692 <primary>2-Way Randnum exchange</primary>
694 <secondary>"2-Way Randnum exchange" UAM</secondary>
695 </indexterm> UAMs (weak password encryption, separate password
700 <para>"DHCAST128"<indexterm>
701 <primary>DHCAST128</primary>
703 <secondary>"DHCAST128" UAM</secondary>
704 </indexterm> UAM (stronger password encryption)</para>
708 <para>"DHX2"<indexterm>
709 <primary>DHX2</primary>
711 <secondary>"DHX2" UAM</secondary>
712 </indexterm> UAM (successor of DHCAST128)</para>
716 <para>There exist other optional UAMs as well:</para>
720 <para>"PGPuam 1.0"<indexterm>
721 <primary>PGPuam 1.0</primary>
723 <secondary>"PGPuam 1.0" UAM</secondary>
724 </indexterm><indexterm>
725 <primary>uams_pgp.so</primary>
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>
733 <para>You'll have to add <filename>"--enable-pgp-uam"</filename>
734 to your configure switches to have this UAM available.</para>
738 <para>"Kerberos IV"<indexterm>
739 <primary>Kerberos IV</primary>
741 <secondary>"Kerberos IV" UAM</secondary>
742 </indexterm><indexterm>
743 <primary>uams_krb4.so</primary>
745 <secondary>"Kerberos IV" UAM</secondary>
746 </indexterm>/"AFS Kerberos"<indexterm>
747 <primary>AFS Kerberos</primary>
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>
754 <para>Use <filename>"--enable-krb4-uam"</filename> at compile time
755 to activate the build of this UAM.</para>
759 <para>"Client Krb v2"<indexterm>
760 <primary>Client Krb v2</primary>
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>
766 <para><filename>"--enable-krbV-uam"</filename> will provide you
767 with the ability to use this UAM.</para>
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.
777 <refentrytitle>asip-status.pl</refentrytitle>
779 <manvolnum>1</manvolnum>
780 </citerefentry> can be used to query the available UAMs of AFP
781 servers as well.</para>
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 < X DHCAST128
786 support exists since AppleShare client 3.8.x.</para>
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>
795 <title>Which UAMs to activate?</title>
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
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>
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>
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>
830 <manvolnum>1</manvolnum>
831 </citerefentry> utility, if clients should use these
836 <para>"DHCAST128" or "DHX2" should be a good compromise for most
837 people since it combines stronger encryption with PAM
842 <para>Using the Kerberos V<indexterm>
843 <primary>Kerberos V</primary>
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>
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>
866 <title>Using different authentication sources with specific
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>
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 -> uams_pam.so
886 uams_dhx.so -> uams_dhx_pam.so
887 uams_dhx2.so -> 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>
898 <title>Netatalk UAM overview table</title>
900 <para>A small overview of the most common used UAMs.</para>
902 <table orient="land">
903 <title>Netatalk UAM overview</title>
905 <tgroup align="center" cols="7">
906 <colspec colname="col1" colnum="1" colwidth="0.5*" />
908 <colspec colname="uam_guest" colnum="2" colwidth="1*" />
910 <colspec colname="uam_clrtxt" colnum="3" colwidth="1*" />
912 <colspec colname="uam_randnum" colnum="4" colwidth="1*" />
914 <colspec colname="uam_dhx" colnum="5" colwidth="1*" />
916 <colspec colname="uam_dhx2" colnum="6" colwidth="1*" />
918 <colspec colname="uam_gss" colnum="7" colwidth="1*" />
922 <entry align="center" rotate="0" valign="middle">UAM</entry>
924 <entry>No User Authent<indexterm>
925 <primary>uams_guest.so</primary>
927 <secondary>"No User Authent" UAM (guest
931 <entry>Cleartxt Passwrd<indexterm>
932 <primary>uams_cleartxt.so</primary>
934 <secondary>"Cleartxt Passwrd" UAM</secondary>
937 <entry>(2-Way) Randnum exchange<indexterm>
938 <primary>uams_randnum.so</primary>
940 <secondary>"(2-Way) Randnum exchange" UAM</secondary>
943 <entry>DHCAST128<indexterm>
944 <primary>uams_dhx.so</primary>
946 <secondary>"DHCAST128" UAM</secondary>
949 <entry>DHX2<indexterm>
950 <primary>uams_dhx2.so</primary>
952 <secondary>"DHX2" UAM</secondary>
955 <entry>Client Krb v2<indexterm>
956 <primary>uams_gss.so</primary>
958 <secondary>"Client Krb v2" UAM (Kerberos V)</secondary>
963 <entry align="center" rotate="0" valign="middle">pssword
966 <entry>guest access</entry>
968 <entry>max. 8 characters</entry>
970 <entry>max. 8 characters</entry>
972 <entry>max. 64 characters</entry>
974 <entry>max. 256 characters</entry>
976 <entry>Kerberos tickets</entry>
980 <entry align="center" rotate="0" valign="middle">Client
983 <entry>built-in into all Mac OS versions</entry>
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>
988 <entry>built-in into almost all Mac OS versions</entry>
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>
993 <entry>built-in since Mac OS X 10.2</entry>
995 <entry>built-in since Mac OS X 10.2</entry>
999 <entry align="center" rotate="0"
1000 valign="middle">Encryption</entry>
1002 <entry>Enables guest access without authentication between
1003 client and server.</entry>
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>
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>
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>
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
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>
1028 <entry align="center" rotate="0" valign="middle">Server
1031 <entry align="center" valign="middle">uams_guest.so</entry>
1033 <entry align="center" valign="middle">uams_cleartxt.so</entry>
1035 <entry align="center" valign="middle">uams_randnum.so</entry>
1037 <entry align="center" valign="middle">uams_dhx.so</entry>
1039 <entry align="center" valign="middle">uams_dhx2.so</entry>
1041 <entry align="center" valign="middle">uams_gss.so</entry>
1045 <entry align="center" rotate="0" valign="middle">Password
1046 storage method</entry>
1048 <entry align="center" valign="middle">None</entry>
1050 <entry align="center" valign="middle">Either /etc/passwd
1051 (/etc/shadow) or PAM</entry>
1053 <entry align="center" valign="middle">Passwords stored in
1054 clear text in a separate text file</entry>
1056 <entry align="center" valign="middle">Either /etc/passwd
1057 (/etc/shadow) or PAM</entry>
1059 <entry align="center" valign="middle">Either /etc/passwd
1060 (/etc/shadow) or PAM</entry>
1062 <entry align="center" valign="middle">At the Kerberos Key
1063 Distribution Center*</entry>
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>
1074 <sect3 id="sshtunnel">
1075 <title>SSH tunneling</title>
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>
1082 <sect4 id="manualsshtunnel">
1083 <title>Manually tunneling an AFP session</title>
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>
1090 <programlisting>ssh -l $USER $SERVER -L 10548:127.0.0.1:548 sleep 3000</programlisting>
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)
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>
1109 <sect4 id="autosshtunnel">
1110 <title>Automatically establishing a tunneled AFP connection</title>
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>
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>
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>
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>
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
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
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>
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>
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>
1172 <para>Encrypting all AFP sessions via SSH can lead to a
1173 significantly higher load on the Netatalk server</para>
1181 <title>ACL Support<indexterm>
1182 <primary>ACLs</primary>
1183 </indexterm></title>
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>
1189 <title>Configuration</title>
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
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
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>
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>
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
1226 <para>In detail:</para>
1230 <para>For Solaris/ZFS: ZFS Volumes</para>
1232 <para>You should configure a ZFS ACL know for any volume you want
1233 to use with Netatalk:</para>
1235 <screen>aclinherit = passthrough
1236 aclmode = passthrough</screen>
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>
1243 <para>Authentication Domain</para>
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>
1254 <para>you need an Open Directory Server or an LDAP server
1255 where you store UUIDs in some attribute</para>
1259 <para>your clients must be configured to use this
1264 <para>your server should be configured to use this server via
1265 nsswitch and PAM</para>
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
1281 <title>OS X ACLs</title>
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>
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>
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>
1307 <title>ZFS ACLs</title>
1309 <para>ZFS ACLs closely match OS X ACLs. Both offer mostly identical
1310 fine grained permissions and inheritance settings.</para>
1314 <title>POSIX ACLs</title>
1317 <title>Overview</title>
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>
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>
1332 <para>Architectural differences between Posix ACLs and OS X ACLs
1333 especially involve:</para>
1335 <para><itemizedlist>
1337 <para>No fine-granular permissions model. Like UNIX
1338 permissions Posix ACLs only differentiate between read, write
1339 and execute permissions.</para>
1343 <para>Entries within an ACL are unordered.</para>
1347 <para>Posix ACLs can only grant rights. There is no way to
1348 explicitly deny rights by an entry.</para>
1352 <para>UNIX permissions are integrated into an ACL as special
1355 </itemizedlist></para>
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>
1362 <para><itemizedlist>
1364 <para>ACL_USER_OBJ: the owner's access rights.</para>
1368 <para>ACL_GROUP_OBJ: the owning group's access rights.</para>
1372 <para>ACL_OTHER: everybody's access rights.</para>
1374 </itemizedlist></para>
1376 <para>The remaining entry types expand the traditional permissions
1379 <para><itemizedlist>
1381 <para>ACL_USER: grants access rights to a certain user.</para>
1385 <para>ACL_GROUP: grants access rights to a certain
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>
1397 </itemizedlist></para>
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
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>
1415 <title>Mapping POSIX ACLs to OS X ACLs</title>
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>
1424 <para><itemizedlist>
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>
1432 <para>As entries within Posix ACLs are unordered, it is
1433 impossible to preserve order.</para>
1437 <para>Inheritance control is subject to severe limitations as
1440 <para>Entries with the only_inherit flag set will only
1441 become part of the directory's default ACL.</para>
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>
1451 </itemizedlist></para>
1455 <para>The lack of a fine-granular permission model on the
1456 Posix side will normally result in an increase of granted
1459 </itemizedlist></para>
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>
1480 <title>Filesystem Change Events<indexterm>
1481 <primary>FCE</primary>
1482 </indexterm></title>
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>
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>
1492 <para>The currently supported FCE events are<itemizedlist>
1494 <para>file modification (fmod)</para>
1498 <para>file deletion (fdel)</para>
1502 <para>directory deletion (ddel)</para>
1506 <para>file creation (fcre)</para>
1510 <para>directory deletion (ddel)</para>
1512 </itemizedlist></para>
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>
1521 <title id="spotlight">Spotlight<indexterm>
1522 <primary>Spotlight</primary>
1523 </indexterm></title>
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>
1530 <title>Configuration</title>
1532 <para>You can enable Spotlight and indexing either globally or on a per
1533 volume basis with the <option>spotlight</option> option.</para>
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>
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>
1547 <title>Limitations and notes</title>
1551 <para>Large filesystems</para>
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>
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>
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>
1573 <title>Using Tracker commandline tools on the server</title>
1575 <para>Netatalk must be running and the commands must be executed as
1577 # export DBUS_SESSION_BUS_ADDRESS="unix:path=/tmp/spotlight.ipc"</screen></para>
1579 <para>When using Tracker from OpenCSW you must also update your
1580 PATH:<screen># export PATH=/opt/csw/bin:$PATH</screen></para>
1583 <title>Starting and stopping Tracker</title>
1587 <term>Querying Tracker status</term>
1590 <screen># tracker-control -S</screen>
1595 <term>Stop Tracker</term>
1598 <screen># tracker-control -t</screen>
1603 <term>Start Tracker status</term>
1606 <screen># tracker-control -s</screen>
1613 <title>Reindex directory</title>
1615 <screen># tracker-control -f PATH</screen>
1619 <title>Query Tracker for information about a file or directory</title>
1621 <screen># tracker-info PATH</screen>
1625 <title>Search Tracker</title>
1627 <screen># tracker-search QUERY</screen>
1632 <title>Advanced Tracker command line configuration</title>
1634 <para>Tracker stores its configuration via Gnome dconf backend which can
1635 be modified with the command <command>gsettings</command>.</para>
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>
1643 <para>When using Tracker from OpenCSW you must also update your
1644 PATH:<screen># export PATH=/opt/csw/bin:$PATH</screen></para>
1646 <para><screen># gsettings list-recursively | grep Tracker
1647 org.freedesktop.Tracker.Writeback verbosity 'debug'
1650 <para>The following list describes some important Tracker options and
1651 their default settings.</para>
1655 <term>org.freedesktop.Tracker.Miner.Files
1656 index-recursive-directories</term>
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>
1667 <term id="enable-monitors">org.freedesktop.Tracker.Miner.Files
1668 enable-monitors <parameter> true</parameter></term>
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>
1681 <term id="crawling-interval">org.freedesktop.Tracker.Miner.Files
1682 crawling-interval <parameter>-1</parameter></term>
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>
1695 <title>Supported metadata attributes</title>
1697 <para>The following list is the complete set of supported metadata
1698 attributes in Tracker SPARQL search queries</para>
1701 <title>Tracker SPARQL</title>
1706 <entry align="center">Description</entry>
1708 <entry align="center">Spotlight Key</entry>
1716 <entry>kMDItemDisplayName, kMDItemFSName</entry>
1720 <entry>Document content (full text search)</entry>
1722 <entry>kMDItemTextContent</entry>
1726 <entry>File type</entry>
1728 <entry>_kMDItemGroupId, kMDItemContentTypeTree</entry>
1732 <entry>File modification date</entry>
1734 <entry>kMDItemFSContentChangeDate,
1735 kMDItemContentModificationDate,
1736 kMDItemAttributeChangeDate</entry>
1740 <entry>Content Creation date</entry>
1742 <entry>kMDItemContentCreationDate</entry>
1746 <entry>The author, or authors, of the contents of the
1749 <entry>kMDItemAuthors, kMDItemCreator</entry>
1753 <entry>The name of the country where the item was
1756 <entry>kMDItemCountry</entry>
1760 <entry>Duration</entry>
1762 <entry>kMDItemDurationSeconds</entry>
1766 <entry>Number of pages</entry>
1768 <entry>kMDItemNumberOfPages</entry>
1772 <entry>Document title</entry>
1774 <entry>kMDItemTitle</entry>
1778 <entry>The width, in pixels, of the contents. For example, the
1779 image width or the video frame width</entry>
1781 <entry>kMDItemPixelWidth</entry>
1785 <entry>The height, in pixels, of the contents. For example, the
1786 image height or the video frame height</entry>
1788 <entry>kMDItemPixelHeight</entry>
1792 <entry>The color space model used by the document
1795 <entry>kMDItemColorSpace</entry>
1799 <entry>The number of bits per sample</entry>
1801 <entry>kMDItemBitsPerSample</entry>
1805 <entry>Focal length of the lens, in millimeters</entry>
1807 <entry>kMDItemFocalLength</entry>
1811 <entry>ISO speed</entry>
1813 <entry>kMDItemISOSpeed</entry>
1817 <entry>Orientation of the document. Possible values are 0
1818 (landscape) and 1 (portrait)</entry>
1820 <entry>kMDItemOrientation</entry>
1824 <entry>Resolution width, in DPI</entry>
1826 <entry>kMDItemResolutionWidthDPI</entry>
1830 <entry>Resolution height, in DPI</entry>
1832 <entry>kMDItemResolutionHeightDPI</entry>
1836 <entry>Exposure time, in seconds</entry>
1838 <entry>kMDItemExposureTimeSeconds</entry>
1842 <entry>The composer of the music contained in the audio
1845 <entry>kMDItemComposer</entry>
1849 <entry>The musical genre of the song or composition</entry>
1851 <entry>kMDItemMusicalGenre</entry>
1857 <para>The following list is the complete set of supported metadata
1858 attributes in Tracker RDF search queries:<table>
1859 <title>Tracker RDF</title>
1864 <entry align="center">Description</entry>
1866 <entry align="center">Spotlight Key</entry>
1874 <entry>kMDItemDisplayName, kMDItemFSName</entry>
1878 <entry>Document content (full text search)</entry>
1880 <entry>kMDItemTextContent</entry>
1884 <entry>File type</entry>
1886 <entry>_kMDItemGroupId, kMDItemContentTypeTree</entry>
1890 <entry>File modification date</entry>
1892 <entry>kMDItemFSContentChangeDate,
1893 kMDItemContentModificationDate,
1894 kMDItemAttributeChangeDate</entry>
1898 <entry>Content Creation date</entry>
1900 <entry>kMDItemContentCreationDate</entry>
1904 <entry>The author, or authors, of the contents of the
1907 <entry>kMDItemAuthors, kMDItemCreator</entry>
1911 <entry>The name of the country where the item was
1914 <entry>kMDItemCountry</entry>
1918 <entry>Duration</entry>
1920 <entry>kMDItemDurationSeconds</entry>
1924 <entry>Number of pages</entry>
1926 <entry>kMDItemNumberOfPages</entry>
1930 <entry>Document title</entry>
1932 <entry>kMDItemTitle</entry>
1936 <entry>The width, in pixels, of the contents. For example, the
1937 image width or the video frame width</entry>
1939 <entry>kMDItemPixelWidth</entry>
1943 <entry>The height, in pixels, of the contents. For example,
1944 the image height or the video frame height</entry>
1946 <entry>kMDItemPixelHeight</entry>
1950 <entry>Focal length of the lens, in millimeters</entry>
1952 <entry>kMDItemFocalLength</entry>
1956 <entry>ISO speed</entry>
1958 <entry>kMDItemISOSpeed</entry>
1962 <entry>Orientation of the document. Possible values are 0
1963 (landscape) and 1 (portrait)</entry>
1965 <entry>kMDItemOrientation</entry>
1969 <entry>Exposure time, in seconds</entry>
1971 <entry>kMDItemExposureTimeSeconds</entry>
1975 <entry>The musical genre of the song or composition</entry>
1977 <entry>kMDItemMusicalGenre</entry>
1985 <title>References</title>
1990 url="https://developer.apple.com/library/mac/#documentation/Carbon/Reference/MDItemRef/Reference/reference.html">MDItem</ulink></para>
1995 url="https://live.gnome.org/Tracker/Documentation">Tracker</ulink></para>
2002 <title>Starting and stopping Netatalk</title>
2004 <para>The Netatalk distribution comes with several operating system
2005 specific startup script templates that are tailored according to the
2006 options given to the "configure" script before compiling. Currently,
2007 templates are provided for RedHat (sysv style), RedHat (systemd style),
2008 SUSE (sysv style), SUSE (systemd style), Gentoo, NetBSD, Debian and
2009 Solaris. You can select to install the generated startup script(s)
2011 <primary>Startscript</primary>
2013 <secondary>startup script</secondary>
2014 </indexterm> by specifying a system type to "configure". To
2015 automatically install startup scripts give one of the available
2016 <option>--with-init-style</option> option to "configure".</para>
2018 <para>Since new releases of Linux distributions appear all the time and
2019 the startup procedure for the other systems mentioned above might change
2020 as well, it is probably a good idea to not blindly install a startup
2021 script but to look at it first to see if it will work on your system. If
2022 you use Netatalk as part of a fixed setup, like a Linux distribution, an
2023 RPM or a BSD package, things will probably have been arranged properly for
2024 you. The following therefore applies mostly for people who have compiled
2025 Netatalk themselves.</para>
2027 <para>The following daemon need to be started by whatever startup script
2028 mechanism is used:</para>
2032 <para>netatalk<indexterm>
2033 <primary>netatalk</primary>
2038 <para>Additionally, make sure that the configuration file
2039 <filename>afp.conf</filename> is in the right place.</para>