1AFP.CONF(5)                         3.1.12                         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
415           ·    ignore - 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
419           ·    preserve - preserve ZFS ACEs for named users and groups or
420               POSIX ACL group mask
421
422           ·    simple - 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 notify script = PATH (G)
653           Script which will be executed for every FCE event, see
654           contrib/shell_utils/fce_ev_script.sh from the Netatalk sources for
655           an example script.
656
657   Debug Parameters
658       These options are useful for debugging only.
659
660       tickleval = number (G)
661           Sets the tickle timeout interval (in seconds). Defaults to 30.
662
663       timeout = number (G)
664           Specify the number of tickles to send before timing out a
665           connection. The default is 4, therefore a connection will timeout
666           after 2 minutes.
667
668       client polling = BOOLEAN (default: no) (G)
669           With this option enabled, afpd won't advertise that it is capable
670           of server notifications, so that connected clients poll the server
671           every 10 seconds to detect changes in opened server windows.  Note:
672           Depending on the number of simultaneously connected clients and the
673           network's speed, this can lead to a significant higher load on your
674           network!
675
676           Do not use this option any longer as present Netatalk correctly
677           supports server notifications, allowing connected clients to update
678           folder listings in case another client changed the contents.
679
680   Options for ACL handling
681       By default, the effective permission of the authenticated user are only
682       mapped to the mentioned UARights permission structure, not the UNIX
683       mode. You can adjust this behaviour with the configuration option map
684       acls:
685
686       map acls = none|rights|mode (G)
687
688           none
689               no mapping of ACLs
690
691           rights
692               effective permissions are mapped to UARights structure. This is
693               the default.
694
695           mode
696               ACLs are additionally mapped to the UNIX mode of the filesystem
697               object.
698
699       If you want to be able to display ACLs on the client, you must setup
700       both client and server as part on a authentication domain (directory
701       service, eg LDAP, Open Directory, Active Directory). The reason is, in
702       OS X ACLs are bound to UUIDs, not just uid's or gid's. Therefor
703       Netatalk must be able to map every filesystem uid and gid to a UUID so
704       that it can return the server side ACLs which are bound to UNIX uid and
705       gid mapped to OS X UUIDs.
706
707       Netatalk can query a directory server using LDAP queries. Either the
708       directory server already provides an UUID attribute for user and groups
709       (Active Directory, Open Directory) or you reuse an unused attribute (or
710       add a new one) to you directory server (eg OpenLDAP).
711
712       The following LDAP options must be configured for Netatalk:
713
714       ldap auth method = none|simple|sasl (G)
715           Authentication method: none | simple | sasl
716
717           none
718               anonymous LDAP bind
719
720           simple
721               simple LDAP bind
722
723           sasl
724               SASL. Not yet supported !
725
726       ldap auth dn = dn (G)
727           Distinguished Name of the user for simple bind.
728
729       ldap auth pw = password (G)
730           Password for simple bind.
731
732       ldap server = host (G)
733           Name or IP address of your LDAP Server. This is only needed for
734           explicit ACL support in order to be able to query LDAP for UUIDs.
735
736           You can use afpldaptest(1) to syntactically check your config.
737
738       ldap userbase = base dn (G)
739           DN of the user container in LDAP.
740
741       ldap userscope = scope (G)
742           Search scope for user search: base | one | sub
743
744       ldap groupbase = base dn (G)
745           DN of the group container in LDAP.
746
747       ldap groupscope = scope (G)
748           Search scope for group search: base | one | sub
749
750       ldap uuid attr = dn (G)
751           Name of the LDAP attribute with the UUIDs.
752
753           Note: this is used both for users and groups.
754
755       ldap name attr = dn (G)
756           Name of the LDAP attribute with the users short name.
757
758       ldap group attr = dn (G)
759           Name of the LDAP attribute with the groups short name.
760
761       ldap uuid string = STRING (G)
762           Format of the uuid string in the directory. A series of x and -,
763           where every x denotes a value 0-9a-f and every - is a separator.
764
765           Default: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
766
767       ldap uuid encoding = string | ms-guid (default: string) (G)
768           Format of the UUID of the LDAP attribute, allows usage of the
769           binary objectGUID fields from Active Directory. If left
770           unspecified, string is the default, which passes through the ASCII
771           UUID returned by most other LDAP stores. If set to ms-guid, the
772           internal UUID representation is converted to and from the binary
773           format used in the objectGUID attribute found on objects in Active
774           Directory when interacting with the server.
775
776           See also the options ldap user filter and ldap group filter.
777
778           string
779               UUID is a string, use with eg OpenDirectory.
780
781           ms-guid
782               Binary objectGUID from Active Directory
783
784       ldap user filter = STRING (default: unused) (G)
785           Optional LDAP filter that matches user objects. This is necessary
786           for Active Directory environments where users and groups are stored
787           in the same directory subtree.
788
789           Recommended setting for Active Directory: objectClass=user.
790
791       ldap group filter = STRING (default: unused) (G)
792           Optional LDAP filter that matches group objects. This is necessary
793           for Active Directory environments where users and groups are stored
794           in the same directory subtree.
795
796           Recommended setting for Active Directory: objectClass=group.
797

EXPLANATION OF VOLUME PARAMETERS

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

CNID BACKENDS

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

CHARSET OPTIONS

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

SEE ALSO

1096       afpd(8), afppasswd(5), afp_signature.conf(5), extmap.conf(5),
1097       cnid_metad(8)
1098
1099
1100
11013.1.12                            27 Dec 2016                      AFP.CONF(5)
Impressum