1AFP.CONF(5)                         3.1.14                         AFP.CONF(5)
2
3
4

NAME

6       afp.conf - Netatalk configuration file
7

SYNOPSIS

9       The afp.conf file is the configuration file for the Netatalk AFP file
10       server.
11
12       All AFP specific configuration and AFP volume definitions are done via
13       this file.
14

FILE FORMAT

16       The file consists of sections and parameters. A section begins with the
17       name of the section in square brackets and continues until the next
18       section begins. Sections contain parameters of the form:
19
20               name = value
21
22
23       The file is line-based - that is, each newline-terminated line
24       represents either a comment, a section name or a parameter.
25
26       Section and parameter names are case sensitive.
27
28       Only the first equals sign in a parameter is significant. Whitespace
29       before or after the first equals sign is discarded. Leading, trailing
30       and internal whitespace in section and parameter names is irrelevant.
31       Leading and trailing whitespace in a parameter value is discarded.
32       Internal whitespace within a parameter value is retained verbatim.
33
34       Any line beginning with a semicolon (“;”) or a hash (“#”) character is
35       ignored, as are lines containing only whitespace.
36
37       Any line ending in a “ \ ” is continued on the next line in the
38       customary UNIX fashion.
39
40       The values following the equals sign in parameters are all either a
41       string (no quotes needed) or a boolean, which may be given as yes/no,
42       1/0 or true/false. Case is not significant in boolean values, but is
43       preserved in string values. Some items such as "file perm"s are
44       numeric.
45
46       The parameter include = path allows you to include one config file
47       inside another. The file is included literally, as though typed in
48       place. Nested includes are not supported.
49

SECTION DESCRIPTIONS

51       Each section in the configuration file (except for the [Global]
52       section) describes a shared resource (known as a “volume”). The section
53       name is the name of the volume and the parameters within the section
54       define the volume attributes and options.
55
56       There are two special sections, [Global] and [Homes], which are
57       described under special sections. The following notes apply to ordinary
58       section descriptions.
59
60       A volume consists of a directory to which access is being given plus a
61       description of the access rights which are granted to the user of the
62       service. For volumes the path option must specify the directory to
63       share.
64
65       Any volume section without path option is considered a vol preset which
66       can be selected in other volume sections via the vol preset option and
67       constitutes defaults for the volume. For any option specified both in a
68       preset and in a volume section the volume section setting completely
69       substitutes the preset option.
70
71       The access rights granted by the server are masked by the access rights
72       granted to the specified or guest UNIX user by the host system. The
73       server does not grant more access than the host system grants.
74
75       The following sample section defines an AFP volume. The user has full
76       access to the path /foo/bar. The share is accessed via the share name
77       baz:
78
79            [baz]
80               path = /foo/bar
81

SPECIAL SECTIONS

83   The [Global] section
84       Parameters in this section apply to the server as a whole. Parameters
85       denoted by a (G) below are must be set in this section.
86
87   The [Homes] section
88       This section enable sharing of the UNIX server user home directories.
89       Specifying an optional path parameter means that not the whole user
90       home will be shared but the subdirectory path. It is necessary to
91       define the basedir regex option. It should be a regex which matches the
92       parent directory of the user homes. Parameters denoted by a (H) belong
93       to volume sections. The optional parameter home name can be used to
94       change the AFP volume name which $u's home by default. See below under
95       VARIABLE SUBSTITUTIONS.
96
97       The following example illustrates this. Given all user home directories
98       are stored under /home:
99
100            [Homes]
101                 path = afp-data
102                 basedir regex = /home
103
104       For a user john this results in an AFP home volume with a path of
105       /home/john/afp-data.
106
107       If basedir regex contains symlink, set the canonicalized absolute path.
108       When /home links to /usr/home:
109
110            [Homes]
111                 basedir regex = /usr/home
112

PARAMETERS

114       Parameters define the specific attributes of sections.
115
116       Some parameters are specific to the [Global] section (e.g., log type).
117       All others are permissible only in volume sections. The letter G in
118       parentheses indicates that a parameter is specific to the [Global]
119       section. The letter V indicates that a parameter can be specified in a
120       volume specific section.
121

VARIABLE SUBSTITUTIONS

123       You can use variables in volume names. The use of variables in paths is
124       limited to $u.
125
126        1. if you specify an unknown variable, it will not get converted.
127
128        2. if you specify a known variable, but that variable doesn't have a
129           value, it will get ignored.
130
131       The variables which can be used for substitutions are:
132
133       $b
134           basename
135
136       $c
137           client's ip address
138
139       $d
140           volume pathname on server
141
142       $f
143           full name (contents of the gecos field in the passwd file)
144
145       $g
146           group name
147
148       $h
149           hostname
150
151       $i
152           client's ip, without port
153
154       $s
155           server name (this can be the hostname)
156
157       $u
158           user name (if guest, it is the user that guest is running as)
159
160       $v
161           volume name
162
163       $$
164           prints dollar sign ($)
165

EXPLANATION OF GLOBAL PARAMETERS

167   Authentication Options
168       ad domain = DOMAIN (G)
169           Append @DOMAIN to username when authenticating. Useful in Active
170           Directory environments that otherwise would require the user to
171           enter the full user@domain string.
172
173       admin auth user = user (G)
174           Specifying eg "admin auth user = root" whenever a normal user login
175           fails, afpd will try to authenticate as the specified admin auth
176           user. If this succeeds, a normal session is created for the
177           original connecting user. Said differently: if you know the
178           password of admin auth user, you can authenticate as any other
179           user.
180
181       admin group = group (G)
182           Allows users of a certain group to be seen as the superuser when
183           they log in. This option is disabled by default.
184
185       force user = USER (G)
186           This specifies a UNIX user name that will be assigned as the
187           default user for all users connecting to this server. This is
188           useful for sharing files. You should also use it carefully as using
189           it incorrectly can cause security problems.
190
191       force group = GROUP (G)
192           This specifies a UNIX group name that will be assigned as the
193           default primary group for all users connecting to this server.
194
195       k5 keytab = path (G), k5 service = service (G), k5 realm = realm (G)
196           These are required if the server supports the Kerberos 5
197           authentication UAM.
198
199       nt domain = DOMAIN (G), nt separator = SEPARATOR (G)
200           Use for eg. winbind authentication, prepends both strings before
201           the username from login and then tries to authenticate with the
202           result through the available and active UAM authentication modules.
203
204       save password = BOOLEAN (default: yes) (G)
205           Enables or disables the ability of clients to save passwords
206           locally.
207
208       set password = BOOLEAN (default: no) (G)
209           Enables or disables the ability of clients to change their
210           passwords via chooser or the "connect to server" dialog.
211
212       uam list = uam list (G)
213           Space or comma separated list of UAMs. (The default is "uams_dhx.so
214           uams_dhx2.so").
215
216           The most commonly used UAMs are:
217
218           uams_guest.so
219               allows guest logins
220
221           uams_clrtxt.so
222               (uams_pam.so or uams_passwd.so) Allow logins with passwords
223               transmitted in the clear. (legacy)
224
225           uams_randnum.so
226               allows Random Number and Two-Way Random Number Exchange for
227               authentication (requires a separate file containing the
228               passwords, either @pkgconfdir@/afppasswd file or the one
229               specified via "passwd file"). See afppasswd(1) for details.
230               (legacy)
231
232           uams_dhx.so
233               (uams_dhx_pam.so or uams_dhx_passwd.so) Allow Diffie-Hellman
234               eXchange (DHX) for authentication.
235
236           uams_dhx2.so
237               (uams_dhx2_pam.so or uams_dhx2_passwd.so) Allow Diffie-Hellman
238               eXchange 2 (DHX2) for authentication.
239
240           uam_gss.so
241               Allow Kerberos V for authentication (optional)
242
243       uam path = path (G)
244           Sets the default path for UAMs for this server (default is
245           /usr/lib64/netatalk).
246
247   Charset Options
248       With OS X Apple introduced the AFP3 protocol. One of the big changes
249       was, that AFP3 uses Unicode names encoded as Decomposed UTF-8
250       (UTF8-MAC). Previous AFP/OS versions used charsets like MacRoman,
251       MacCentralEurope, etc.
252
253       To be able to serve AFP3 and older clients at the same time, afpd needs
254       to be able to convert between UTF-8 and Mac charsets. Even OS X clients
255       partly still rely on the mac charset. As there's no way, afpd can
256       detect the codepage a pre AFP3 client uses, you have to specify it
257       using the mac charset option. The default is MacRoman, which should be
258       fine for most western users.
259
260       As afpd needs to interact with UNIX operating system as well, it needs
261       to be able to convert from UTF8-MAC / Mac charset to the UNIX charset.
262       By default afpd uses UTF8. You can set the UNIX charset using the unix
263       charset option. If you're using extended characters in the
264       configuration files for afpd, make sure your terminal matches the unix
265       charset.
266
267       mac charset = CHARSET (G)/(V)
268           Specifies the Mac clients charset, e.g.  MAC_ROMAN. This is used to
269           convert strings and filenames to the clients codepage for OS9 and
270           Classic, i.e. for authentication and AFP messages (SIGUSR2
271           messaging). This will also be the default for the volumes mac
272           charset. Defaults to MAC_ROMAN.
273
274       unix charset = CHARSET (G)
275           Specifies the servers unix charset, e.g.  ISO-8859-15 or EUC-JP.
276           This is used to convert strings to/from the systems locale, e.g.
277           for authentication, server messages and volume names. If LOCALE is
278           set, the systems locale is used. Defaults to UTF8.
279
280       vol charset = CHARSET (G)/(V)
281           Specifies the encoding of the volumes filesystem. By default, it is
282           the same as unix charset.
283
284   Password Options
285       passwd file = path (G)
286           Sets the path to the Randnum UAM passwd file for this server
287           (default is @pkgconfdir@/afppasswd).
288
289       passwd minlen = number (G)
290           Sets the minimum password length, if supported by the UAM
291
292   Network Options
293       advertise ssh = BOOLEAN (default: no) (G)
294           Allows old Mac OS X clients (10.3.3-10.4) to automagically
295           establish a tunneled AFP connection through SSH. If this option is
296           set, the server's answers to client's FPGetSrvrInfo requests
297           contain an additional entry. It depends on both client's settings
298           and a correctly configured and running sshd(8) on the server to let
299           things work.
300
301               Note
302               Setting this option is not recommended since globally
303               encrypting AFP connections via SSH will increase the server's
304               load significantly. On the other hand, Apple's client side
305               implementation of this feature in MacOS X versions prior to
306               10.3.4 contained a security flaw.
307
308       afp interfaces = name [name ...] (G)
309           Specifies the network interfaces that the server should listens on.
310           The default is advertise the first IP address of the system, but to
311           listen for any incoming request.
312
313       afp listen = ip address[:port] [ip address[:port] ...] (G)
314           Specifies the IP address that the server should advertise and
315           listens to. The default is advertise the first IP address of the
316           system, but to listen for any incoming request. The network address
317           may be specified either in dotted-decimal format for IPv4 or in
318           hexadecimal format for IPv6.
319
320           IPv6 address + port combination must use URL the format using
321           square brackets [IPv6]:port
322
323       afp port = port number (G)
324           Allows a different TCP port to be used for AFP. The default is 548.
325           Also sets the default port applied when none specified in an afp
326           listen option.
327
328       cnid listen = ip address[:port] [ip address[:port] ...] (G)
329           Specifies the IP address that the CNID server should listen on. The
330           default is localhost:4700.
331
332       disconnect time = number (G)
333           Keep disconnected AFP sessions for number hours before dropping
334           them. Default is 24 hours.
335
336       dsireadbuf = number (G)
337           Scale factor that determines the size of the DSI/TCP readahead
338           buffer, default is 12. This is multiplies with the DSI server
339           quantum (default 1MiB) to give the size of the buffer. Increasing
340           this value might increase throughput in fast local networks for
341           volume to volume copies.  Note: This buffer is allocated per afpd
342           child process, so specifying large values will eat up large amount
343           of memory (buffer size * number of clients).
344
345       fqdn = name[:port] (G)
346           Specifies a fully-qualified domain name, with an optional port.
347           This is discarded if the server cannot resolve it. This option is
348           not honored by AppleShare clients <= 3.8.3. This option is disabled
349           by default. Use with caution as this will involve a second name
350           resolution step on the client side. Also note that afpd will
351           advertise this name:port combination but not automatically listen
352           to it.
353
354       hostname = name (G)
355           Use this instead of the result from calling hostname for
356           determining which IP address to advertise, therefore the hostname
357           is resolved to an IP which is the advertised. This is NOT used for
358           listening and it is also overwritten by afp listen.
359
360       max connections = number (G)
361           Sets the maximum number of clients that can simultaneously connect
362           to the server (default is 200).
363
364       server quantum = number (G)
365           This specifies the DSI server quantum. The default value is
366           0x100000 (1 MiB). The maximum value is 0xFFFFFFFFF, the minimum is
367           32000. If you specify a value that is out of range, the default
368           value will be set. Do not change this value unless you're
369           absolutely sure, what you're doing
370
371       sleep time = number (G)
372           Keep sleeping AFP sessions for number hours before disconnecting
373           clients in sleep mode. Default is 10 hours.
374
375       tcprcvbuf = number (G)
376           Try to set TCP receive buffer using setsockopt(). Often OSes impose
377           restrictions on the applications ability to set this value.
378
379       tcpsndbuf = number (G)
380           Try to set TCP send buffer using setsockopt(). Often OSes impose
381           restrictions on the applications ability to set this value.
382
383       recvfile = BOOLEAN (default: no) (G)
384           Whether to use splice() on Linux for receiving data.
385
386       splice size = number (default: 64k) (G)
387           Maximum number of bytes spliced.
388
389       use sendfile = BOOLEAN (default: yes) (G)
390           Whether to use sendfile.  syscall for sending file data to clients.
391
392       zeroconf = BOOLEAN (default: yes) (G)
393           Whether to use automatic Zeroconf.  service registration if Avahi
394           or mDNSResponder were compiled in.
395
396   Miscellaneous Options
397       afp read locks = BOOLEAN (default: no) (G)
398           Whether to apply locks to the byte region read in FPRead calls. The
399           AFP spec mandates this, but it's not really in line with UNIX
400           semantics and is a performance hug.
401
402       afpstats = BOOLEAN (default: no) (G)
403           Whether to provide AFP runtime statistics (connected users, open
404           volumes) via dbus.
405
406       basedir regex = regex (H)
407           Regular expression which matches the parent directory of the user
408           homes. If basedir regex contains symlink, you must set the
409           canonicalized absolute path. In the simple case this is just a path
410           ie basedir regex = /home
411
412       chmod request = preserve (default) | ignore | simple (G)/(V)
413           Advanced permission control that deals with ACLs.
414
415ignore - UNIX chmod() requests are completely ignored, use
416               this option to allow the parent directory's ACL inheritance
417               full control over new items.
418
419preserve - preserve ZFS ACEs for named users and groups or
420               POSIX ACL group mask
421
422simple - just to a chmod() as requested without any extra
423               steps
424
425       close vol = BOOLEAN (default: no) (G)
426           Whether to close volumes possibly opened by clients when they're
427           removed from the configuration and the configuration is reloaded.
428
429       cnid mysql host = MySQL server address (G)
430           name or address of a MySQL server for use with the mysql CNID
431           backend.
432
433       cnid mysql user = MySQL user (G)
434           MySQL user for authentication with the server.
435
436       cnid mysql pw = password (G)
437           Password for MySQL server.
438
439       cnid mysql db = database name (G)
440           Name of an existing database for which the specified user has full
441           privileges.
442
443       cnid server = ipaddress[:port] (G)/(V)
444           Specifies the IP address and port of a cnid_metad server, required
445           for CNID dbd backend. Defaults to localhost:4700. The network
446           address may be specified either in dotted-decimal format for IPv4
447           or in hexadecimal format for IPv6.-
448
449       dbus daemon = path (G)
450           Sets the path to dbus-daemon binary used by Spotlight feature. The
451           default value [/usr/bin/dbus-daemon] is determined when building
452           netatalk.
453
454       dircachesize = number (G)
455           Maximum possible entries in the directory cache. The cache stores
456           directories and files. It is used to cache the full path to
457           directories and CNIDs which considerably speeds up directory
458           enumeration.
459
460           Default size is 8192, maximum size is 131072. Given value is
461           rounded up to nearest power of 2. Each entry takes about 100 bytes,
462           which is not much, but remember that every afpd child process for
463           every connected user has its cache.
464
465       extmap file = path (G)
466           Sets the path to the file which defines file extension type/creator
467           mappings. (default is @pkgconfdir@/extmap.conf).
468
469       force xattr with sticky bit = BOOLEAN (default: no) (G/V)
470           Writing metadata xattr on directories with the sticky bit set may
471           fail even though we may have write access to a directory, because
472           if the sticky bit is set only the owner is allowed to write xattrs.
473
474           By enabling this option Netatalk will write the metadata xattr as
475           root.
476
477       guest account = name (G)
478           Specifies the user that guests should use (default is "nobody").
479           The name should be quoted.
480
481       home name = name (H)
482           AFP user home volume name. The default is $u's home.
483
484       ignored attributes = all | nowrite | nodelete | norename (G)/(V)
485           Speficy a set of file and directory attributes that shall be
486           ignored by the server, all includes all the other options.
487
488           In OS X when the Finder sets a lock on a file/directory or you set
489           the BSD uchg flag in the Terminal, all three attributes are used.
490           Thus in order to ignore the Finder lock/BSD uchg flag, add set
491           ignored attributes = all.
492
493       login message = message (G)/(V)
494           Sets a message to be displayed when clients logon to the server.
495           The message should be in unix charset and should be quoted.
496           Extended characters are allowed.
497
498       mimic model = model (G)
499           Specifies the icon model that appears on clients. Defaults to off.
500           Note that netatalk must support Zeroconf. Examples: RackMac (same
501           as Xserve), PowerBook, PowerMac, Macmini, iMac, MacBook,
502           MacBookPro, MacBookAir, MacPro, AppleTV1,1, AirPort.
503
504       signature = <text> (G)
505           Specify a server signature. The maximum length is 16 characters.
506           This option is useful for clustered environments, to provide fault
507           isolation etc. By default, afpd generate signature and saving it to
508           /var/lib/netatalk/afp_signature.conf automatically (based on random
509           number). See also asip-status.pl(1).
510
511       solaris share reservations = BOOLEAN (default: yes) (G)
512           Use share reservations on Solaris. Solaris CIFS server uses this
513           too, so this makes a lock coherent multi protocol server.
514
515       sparql results limit = NUMBER (default: UNLIMITED) (G)
516           Impose a limit on the number of results queried from Tracker via
517           SPARQL queries.
518
519       spotlight = BOOLEAN (default: no) (G)/(V)
520           Whether to enable Spotlight searches. Note: once the global option
521           is enabled, any volume that is not enabled won't be searchable at
522           all. See also dbus daemon option.
523
524       spotlight attributes = COMMA SEPARATED STRING (default: EMPTY) (G)
525           A list of attributes that are allowed to be used in Spotlight
526           searches. By default all attributes can be searched, passing a
527           string limits attributes to elements of the string. Example:
528
529               spotlight attributes = *,kMDItemTextContent
530
531       spotlight expr = BOOLEAN (default: yes) (G)
532           Whether to allow the use of logic expression in searches.
533
534       start dbus = BOOLEAN (default: yes) (G)
535           Whether to start a dbus instance for use with Tracker.
536
537       start tracker = BOOLEAN (default: yes) (G)
538           Whether to start Tracker with "tracker daemon -s". In case of old
539           Tracker, "tracker-control -s" is used instead.
540
541       veto message = BOOLEAN (default: no) (G)
542           Send optional AFP messages for vetoed files. Then whenever a client
543           tries to access any file or directory with a vetoed name, it will
544           be sent an AFP message indicating the name and the directory.
545
546       vol dbpath = path (G)/(V)
547           Sets the database information to be stored in path. You have to
548           specify a writable location, even if the volume is read only. The
549           default is /var/lib/netatalk/CNID/$v/.
550
551       vol dbnest = BOOLEAN (default: no) (G)
552           Setting this option to true brings back Netatalk 2 behaviour of
553           storing the CNID database in a folder called .AppleDB inside the
554           volume root of each share.
555
556       volnamelen = number (G)
557           Max length of UTF8-MAC volume name for Mac OS X. Note that Hangul
558           is especially sensitive to this.
559
560               73: limit of Mac OS X 10.1
561               80: limit of Mac OS X 10.4/10.5 (default)
562               255: limit of recent Mac OS X
563
564           Mac OS 9 and earlier are not influenced by this, because Maccharset
565           volume name is always limited to 27 bytes.
566
567       vol preset = name (G)/(V)
568           Use section name as option preset for all volumes (when set in the
569           [Global] section) or for one volume (when set in that volume's
570           section).
571
572       zeroconf name = name (G)
573           Specifies a human-readable name that uniquely describes registered
574           services. The zeroconf name is advertised as UTF-8, up to 63 octets
575           (bytes) in length. Defaults to hostname. Note that netatalk must
576           support Zeroconf.
577
578   Logging Options
579       log file = logfile (G)
580           If not specified Netatalk logs to syslogs daemon facility.
581           Otherwise it logs to logfile.
582
583       log level = type:level [type:level ...] (G), log level =
584       type:level,[type:level, ...] (G)
585           Specify that any message of a loglevel up to the given log level
586           should be logged.
587
588           By default afpd logs to syslog with a default logging setup
589           equivalent to default:note
590
591           logtypes: default, afpdaemon, logger, uamsdaemon
592
593           loglevels: severe, error, warn, note, info, debug, debug6, debug7,
594           debug8, debug9, maxdebug
595
596               Note
597               Both logtype and loglevels are case insensitive.
598
599   Filesystem Change Events (FCE.
600       Netatalk includes a nifty filesystem change event mechanism where afpd
601       processes notify interested listeners about certain filesystem event by
602       UDP network datagrams.
603
604       The following FCE events are defined:
605
606       •   file modification (fmod)
607
608       •   file deletion (fdel)
609
610       •   directory deletion (ddel)
611
612       •   file creation (fcre)
613
614       •   directory creation (dcre)
615
616       •   file move or rename (fmov)
617
618       •   directory move or rename (dmov)
619
620       •   login (login)
621
622       •   logout (logout)
623
624       fce listener = host[:port] (G)
625           Enables sending FCE events to the specified host, default port is
626           12250 if not specified. Specifying multiple listeners is done by
627           having this option once for each of them.
628
629       fce version = 1|2 (G)
630           FCE protocol version, default is 1. You need version 2 for the
631           fmov, dmov, login or logout events.
632
633       fce events = fmod,fdel,ddel,fcre,dcre,fmov,dmov,login,logout (G)
634           Specifies which FCE events are active, default is
635           fmod,fdel,ddel,fcre,dcre.
636
637       fce coalesce = all|delete|create (G)
638           Coalesce FCE events.
639
640       fce holdfmod = seconds (G)
641           This determines the time delay in seconds which is always waited if
642           another file modification for the same file is done by a client
643           before sending an FCE file modification event (fmod). For example
644           saving a file in Photoshop would generate multiple events by itself
645           because the application is opening, modifying and closing a file
646           multiple times for every "save". Default: 60 seconds.
647
648       fce ignore names = NAME[/NAME2/...] (G)
649           Slash delimited list of filenames for which FCE events shall not be
650           generated. Default: .DS_Store.
651
652       fce ignore directories = NAME[,NAME2,...] (G)
653           Comma delimited list of directories for which FCE events shall not
654           be generated. Default: empty.
655
656       fce notify script = PATH (G)
657           Script which will be executed for every FCE event, see
658           contrib/shell_utils/fce_ev_script.sh from the Netatalk sources for
659           an example script.
660
661   Debug Parameters
662       These options are useful for debugging only.
663
664       tickleval = number (G)
665           Sets the tickle timeout interval (in seconds). Defaults to 30.
666
667       timeout = number (G)
668           Specify the number of tickles to send before timing out a
669           connection. The default is 4, therefore a connection will timeout
670           after 2 minutes.
671
672       client polling = BOOLEAN (default: no) (G)
673           With this option enabled, afpd won't advertise that it is capable
674           of server notifications, so that connected clients poll the server
675           every 10 seconds to detect changes in opened server windows.  Note:
676           Depending on the number of simultaneously connected clients and the
677           network's speed, this can lead to a significant higher load on your
678           network!
679
680           Do not use this option any longer as present Netatalk correctly
681           supports server notifications, allowing connected clients to update
682           folder listings in case another client changed the contents.
683
684   Options for ACL handling
685       By default, the effective permission of the authenticated user are only
686       mapped to the mentioned UARights permission structure, not the UNIX
687       mode. You can adjust this behaviour with the configuration option map
688       acls:
689
690       map acls = none|rights|mode (G)
691
692           none
693               no mapping of ACLs
694
695           rights
696               effective permissions are mapped to UARights structure. This is
697               the default.
698
699           mode
700               ACLs are additionally mapped to the UNIX mode of the filesystem
701               object.
702
703       If you want to be able to display ACLs on the client, you must setup
704       both client and server as part on a authentication domain (directory
705       service, eg LDAP, Open Directory, Active Directory). The reason is, in
706       OS X ACLs are bound to UUIDs, not just uid's or gid's. Therefor
707       Netatalk must be able to map every filesystem uid and gid to a UUID so
708       that it can return the server side ACLs which are bound to UNIX uid and
709       gid mapped to OS X UUIDs.
710
711       Netatalk can query a directory server using LDAP queries. Either the
712       directory server already provides an UUID attribute for user and groups
713       (Active Directory, Open Directory) or you reuse an unused attribute (or
714       add a new one) to you directory server (eg OpenLDAP).
715
716       The following LDAP options must be configured for Netatalk:
717
718       ldap auth method = none|simple|sasl (G)
719           Authentication method: none | simple | sasl
720
721           none
722               anonymous LDAP bind
723
724           simple
725               simple LDAP bind
726
727           sasl
728               SASL. Not yet supported !
729
730       ldap auth dn = dn (G)
731           Distinguished Name of the user for simple bind.
732
733       ldap auth pw = password (G)
734           Password for simple bind.
735
736       ldap server = host (G)
737           Name or IP address of your LDAP Server. This is only needed for
738           explicit ACL support in order to be able to query LDAP for UUIDs.
739
740           You can use afpldaptest(1) to syntactically check your config.
741
742       ldap userbase = base dn (G)
743           DN of the user container in LDAP.
744
745       ldap userscope = scope (G)
746           Search scope for user search: base | one | sub
747
748       ldap groupbase = base dn (G)
749           DN of the group container in LDAP.
750
751       ldap groupscope = scope (G)
752           Search scope for group search: base | one | sub
753
754       ldap uuid attr = dn (G)
755           Name of the LDAP attribute with the UUIDs.
756
757           Note: this is used both for users and groups.
758
759       ldap name attr = dn (G)
760           Name of the LDAP attribute with the users short name.
761
762       ldap group attr = dn (G)
763           Name of the LDAP attribute with the groups short name.
764
765       ldap uuid string = STRING (G)
766           Format of the uuid string in the directory. A series of x and -,
767           where every x denotes a value 0-9a-f and every - is a separator.
768
769           Default: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
770
771       ldap uuid encoding = string | ms-guid (default: string) (G)
772           Format of the UUID of the LDAP attribute, allows usage of the
773           binary objectGUID fields from Active Directory. If left
774           unspecified, string is the default, which passes through the ASCII
775           UUID returned by most other LDAP stores. If set to ms-guid, the
776           internal UUID representation is converted to and from the binary
777           format used in the objectGUID attribute found on objects in Active
778           Directory when interacting with the server.
779
780           See also the options ldap user filter and ldap group filter.
781
782           string
783               UUID is a string, use with eg OpenDirectory.
784
785           ms-guid
786               Binary objectGUID from Active Directory
787
788       ldap user filter = STRING (default: unused) (G)
789           Optional LDAP filter that matches user objects. This is necessary
790           for Active Directory environments where users and groups are stored
791           in the same directory subtree.
792
793           Recommended setting for Active Directory: objectClass=user.
794
795       ldap group filter = STRING (default: unused) (G)
796           Optional LDAP filter that matches group objects. This is necessary
797           for Active Directory environments where users and groups are stored
798           in the same directory subtree.
799
800           Recommended setting for Active Directory: objectClass=group.
801

EXPLANATION OF VOLUME PARAMETERS

803   Parameters
804       The section name defines the volume name. No two volumes may have the
805       same name. The volume name cannot contain the ':' character. The volume
806       name is mangled if it is very long. Mac charset volume name is limited
807       to 27 characters. UTF8-MAC volume name is limited to volnamelen
808       parameter.
809
810       path = PATH (V)
811           The path name must be a fully qualified path name.
812
813       appledouble = ea|v2 (V)
814           Specify the format of the metadata files, which are used for saving
815           Mac resource fork as well. Earlier versions used AppleDouble v2,
816           the new default format is ea.
817
818       vol size limit = size in MiB (V)
819           Useful for Time Machine: limits the reported volume size, thus
820           preventing Time Machine from using the whole real disk space for
821           backup. Example: "vol size limit = 1000" would limit the reported
822           disk space to 1 GB.  IMPORTANT: This is an approximated calculation
823           taking into account the contents of Time Machine sparsebundle
824           images. Therefor you MUST NOT use this volume to store other
825           content when using this option, because it would NOT be accounted.
826           The calculation works by reading the band size from the Info.plist
827           XML file of the sparsebundle, reading the bands/ directory counting
828           the number of band files, and then multiplying one with the other.
829
830       valid users = user @group (V)
831           The allow option allows the users and groups that access a share to
832           be specified. Users and groups are specified, delimited by spaces
833           or commas. Groups are designated by a @ prefix. Names may be quoted
834           in order to allow for spaces in names. Example:
835
836               valid users = user "user 2" @group “@group 2"
837
838       invalid users = users/groups (V)
839           The deny option specifies users and groups who are not allowed
840           access to the share. It follows the same format as the "valid
841           users" option.
842
843       hosts allow = IP host address/IP netmask bits [ ... ] (V)
844           Only listed hosts and networks are allowed, all others are
845           rejected. The network address may be specified either in
846           dotted-decimal format for IPv4 or in hexadecimal format for IPv6.
847
848           Example: hosts allow = 10.1.0.0/16 10.2.1.100 2001:0db8:1234::/48
849
850       hosts deny = IP host address/IP netmask bits [ ... ] (V)
851           Listed hosts and nets are rejected, all others are allowed.
852
853           Example: hosts deny = 192.168.100/24 10.1.1.1 2001:db8::1428:57ab
854
855       cnid scheme = backend (V)
856           set the CNID backend to be used for the volume, default is [dbd]
857           available schemes: [ dbd last tdb mysql]
858
859       ea = none|auto|sys|ad|samba (V)
860           Specify how Extended Attributes.  are stored.  auto is the default.
861
862           auto
863               Try sys (by setting an EA on the shared directory itself),
864               fallback to ad. Requires writable volume for performing test.
865               "read only = yes" overwrites auto with none. Use explicit "ea =
866               sys|ad" for read-only volumes where appropriate.
867
868           sys
869               Use filesystem Extended Attributes.
870
871           samba
872               Use filesystem Extended Attributes, but append a 0 byte to each
873               xattr in order to be compatible with Samba's vfs_streams_xattr.
874
875           ad
876               Use files in .AppleDouble directories.
877
878           none
879               No Extended Attributes support.
880
881       mac charset = CHARSET (V)
882           specifies the Mac client charset for this Volume, e.g.  MAC_ROMAN,
883           MAC_CYRILLIC. If not specified the global setting is applied. This
884           setting is only required if you need volumes, where the Mac charset
885           differs from the one globally set in the [Global] section.
886
887       casefold = option (V)
888           The casefold option handles, if the case of filenames should be
889           changed. The available options are:
890
891           tolower - Lowercases names in both directions.
892
893           toupper - Uppercases names in both directions.
894
895           xlatelower - Client sees lowercase, server sees uppercase.
896
897           xlateupper - Client sees uppercase, server sees lowercase.
898
899       password = password (V)
900           This option allows you to set a volume password, which can be a
901           maximum of 8 characters long (using ASCII strongly recommended at
902           the time of this writing).
903
904       file perm = mode (V), directory perm = mode (V)
905           Add(or) with the client requested permissions: file perm is for
906           files only, directory perm is for directories only. Don't use with
907           "unix priv = no".
908
909           Example. Volume for a collaborative workgroup
910
911               file perm = 0660 directory perm =
912                             0770
913
914
915       umask = mode (V)
916           set perm mask. Don't use with "unix priv = no".
917
918       preexec = command (V)
919           command to be run when the volume is mounted
920
921       postexec = command (V)
922           command to be run when the volume is closed
923
924       root preexec = command (V)
925           command to be run as root when the volume is mounted
926
927       root postexec = command (V)
928           command to be run as root when the volume is closed
929
930       rolist = users/groups (V)
931           Allows certain users and groups to have read-only access to a
932           share. This follows the allow option format.
933
934       rwlist = users/groups (V)
935           Allows certain users and groups to have read/write access to a
936           share. This follows the allow option format.
937
938       veto files = vetoed names (V)
939           hide files and directories,where the path matches one of the '/'
940           delimited vetoed names. The veto string must always be terminated
941           with a '/', eg. "veto files = veto1/", "veto files = veto1/veto2/".
942
943   Volume options
944       Boolean volume options.
945
946       acls = BOOLEAN (default: yes) (V)
947           Whether to flag volumes as supporting ACLs. If ACL support is
948           compiled in, this is yes by default.
949
950       case sensitive = BOOLEAN (default: yes) (V)
951           Whether to flag volumes as supporting case-sensitive filenames. If
952           the filesystem is case-insensitive, set to no. However, it is not
953           fully verified.
954
955               Note
956               In spite of being case sensitive as a matter of fact, netatalk
957               3.1.3 and earlier did not notify kCaseSensitive flag to the
958               client. Starting with 3.1.4, it is notified correctly by
959               default.
960
961       cnid dev = BOOLEAN (default: yes) (V)
962           Whether to use the device number in the CNID backends. Helps when
963           the device number is not constant across a reboot, eg cluster, ...
964
965       convert appledouble = BOOLEAN (default: yes) (V)
966           Whether automatic conversion from appledouble = v2 to appledouble =
967           ea is performed when accessing filesystems from clients. This is
968           generally useful, but costs some performance. It's recommendable to
969           run dbd on volumes and do the conversion with that. Then this
970           option can be set to no.
971
972       delete veto files = BOOLEAN (default: no) (V)
973           This option is used when Netatalk is attempting to delete a
974           directory that contains one or more vetoed files or directories
975           (see the veto files option). If this option is set to no (the
976           default) then if a directory contains any non-vetoed files or
977           directories then the directory delete will fail. This is usually
978           what you want.
979
980           If this option is set to yes, then Netatalk will attempt to
981           recursively delete any files and directories within the vetoed
982           directory.
983
984       follow symlinks = BOOLEAN (default: no) (V)
985           The default setting is false thus symlinks are not followed on the
986           server. This is the same behaviour as OS X's AFP server. Setting
987           the option to true causes afpd to follow symlinks on the server.
988           symlinks may point outside of the AFP volume, currently afpd
989           doesn't do any checks for "wide symlinks".
990
991               Note
992               This option will subtly break when the symlinks point across
993               filesystem boundaries.
994
995       invisible dots = BOOLEAN (default: no) (V)
996           make dot files invisible. WARNING: enabling this option will lead
997           to unwanted sideeffects were OS X applications when saving files to
998           a temporary file starting with a dot first, then renaming the temp
999           file to its final name, result in the saved file being invisible.
1000           The only thing this option is useful for is making files that start
1001           with a dot invisible on Mac OS 9. It's completely useless on Mac OS
1002           X, as both in Finder and in Terminal files starting with a dot are
1003           hidden anyway.
1004
1005       network ids = BOOLEAN (default: yes) (V)
1006           Whether the server support network ids. Setting this to no will
1007           result in the client not using ACL AFP functions.
1008
1009       preexec close = BOOLEAN (default: no) (V)
1010           A non-zero return code from preexec close the volume being
1011           immediately, preventing clients to mount/see the volume in
1012           question.
1013
1014       read only = BOOLEAN (default: no) (V)
1015           Specifies the share as being read only for all users. Overwrites ea
1016           = auto with ea = none
1017
1018       root preexec close= BOOLEAN (default: no) (V)
1019           A non-zero return code from root_preexec closes the volume
1020           immediately, preventing clients to mount/see the volume in
1021           question.
1022
1023       search db = BOOLEAN (default: no) (V)
1024           Use fast CNID database namesearch instead of slow recursive
1025           filesystem search. Relies on a consistent CNID database, ie Samba
1026           or local filesystem access lead to inaccurate or wrong results.
1027           Works only for "dbd" CNID db volumes.
1028
1029       stat vol = BOOLEAN (default: yes) (V)
1030           Whether to stat volume path when enumerating volumes list, useful
1031           for automounting or volumes created by a preexec script.
1032
1033       time machine = BOOLEAN (default: no) (V)
1034           Whether to enable Time Machine support for this volume.
1035
1036       unix priv = BOOLEAN (default: yes) (V)
1037           Whether to use AFP3 UNIX privileges. This should be set for OS X
1038           clients. See also: file perm, directory perm and umask.
1039

CNID BACKENDS

1041       The AFP protocol mostly refers to files and directories by ID and not
1042       by name. Netatalk needs a way to store these ID's in a persistent way,
1043       to achieve this several different CNID backends are available. The CNID
1044       Databases are by default located in the
1045       /var/lib/netatalk/CNID/(volumename)/.AppleDB/ directory.
1046
1047       cdb
1048           "Concurrent database", backend is based on Oracle Berkley DB. With
1049           this backend several afpd daemons access the CNID database
1050           directly. Berkeley DB locking is used to synchronize access, if
1051           more than one afpd process is active for a volume. The drawback is,
1052           that the crash of a single afpd process might corrupt the database.
1053
1054       dbd
1055           Access to the CNID database is restricted to the cnid_metad daemon
1056           process.  afpd processes communicate with the daemon for database
1057           reads and updates. If built with Berkeley DB transactions the
1058           probability for database corruption is practically zero, but
1059           performance can be slower than with cdb
1060
1061       last
1062           This backend is an exception, in terms of ID persistency. ID's are
1063           only valid for the current session. This is basically what afpd did
1064           in the 1.5 (and 1.6) versions. This backend is still available, as
1065           it is useful for e.g. sharing cdroms. Starting with Netatalk 3.0,
1066           it becomes the read only mode automatically.
1067
1068           Warning: It is NOT recommended to use this backend for volumes
1069           anymore, as afpd now relies heavily on a persistent ID database.
1070           Aliases will likely not work and filename mangling is not
1071           supported.
1072
1073       Even though ./configure --help might show that there are other CNID
1074       backends available, be warned those are likely broken or mainly used
1075       for testing. Don't use them unless you know what you're doing, they may
1076       be removed without further notice from future versions.
1077

CHARSET OPTIONS

1079       With OS X Apple introduced the AFP3 protocol. One of the most important
1080       changes was that AFP3 uses unicode names encoded as UTF-8 decomposed.
1081       Previous AFP/OS versions used codepages, like MacRoman,
1082       MacCentralEurope, etc.
1083
1084       afpd needs a way to preserve extended Macintosh characters, or
1085       characters illegal in unix filenames, when saving files on a unix
1086       filesystem. This version now uses UTF-8 as the default encoding for
1087       names. '/' will be converted to ':'.
1088
1089       Earlier versions used the the so called CAP encoding. An extended
1090       character (>0x7F) would be converted to a :xx sequence, e.g. the Apple
1091       Logo (MacRoman: 0xF0) was saved as :f0. Some special characters would
1092       be converted as to :xx notation as well. '/' would be encoded to :2f, a
1093       leading dot '.' might be encoded as :2e.
1094
1095       The vol charset option will allow you to select another volume
1096       encoding.  afpd will accept any iconv(1) provided charset. It is highly
1097       recommended to stick to the default UTF-8.
1098

SEE ALSO

1100       afpd(8), afppasswd(5), afp_signature.conf(5), extmap.conf(5),
1101       cnid_metad(8)
1102
1103
1104
11053.1.14                            27 Dec 2016                      AFP.CONF(5)
Impressum