1AFP.CONF(5) Netatalk AFP Fileserver Manual AFP.CONF(5)
2
3
4
6 afp.conf - Netatalk configuration file
7
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
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
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
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
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
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
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 e.g. "admin auth user = root" whenever a normal user
175 login fails, afpd will try to authenticate as the specified admin
176 auth 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 e.g. 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 or
394 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 i.e. 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 this
416 option to allow the parent directory's ACL inheritance full
417 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 steps
423
424 close vol = BOOLEAN (default: no) (G)
425 Whether to close volumes possibly opened by clients when they're
426 removed from the configuration and the configuration is reloaded.
427
428 cnid mysql host = MySQL server address (G)
429 name or address of a MySQL server for use with the mysql CNID
430 backend.
431
432 cnid mysql user = MySQL user (G)
433 MySQL user for authentication with the server.
434
435 cnid mysql pw = password (G)
436 Password for MySQL server.
437
438 cnid mysql db = database name (G)
439 Name of an existing database for which the specified user has full
440 privileges.
441
442 cnid server = ipaddress[:port] (G)/(V)
443 Specifies the IP address and port of a cnid_metad server, required
444 for CNID dbd backend. Defaults to localhost:4700. The network
445 address may be specified either in dotted-decimal format for IPv4
446 or in hexadecimal format for IPv6.-
447
448 dbus daemon = path (G)
449 Sets the path to dbus-daemon binary used by Spotlight feature. The
450 default value [/usr/bin/dbus-daemon] is determined when building
451 netatalk.
452
453 dircachesize = number (G)
454 Maximum possible entries in the directory cache. The cache stores
455 directories and files. It is used to cache the full path to
456 directories and CNIDs which considerably speeds up directory
457 enumeration.
458
459 Default size is 8192, maximum size is 131072. Given value is
460 rounded up to nearest power of 2. Each entry takes about 100 bytes,
461 which is not much, but remember that every afpd child process for
462 every connected user has its cache.
463
464 extmap file = path (G)
465 Sets the path to the file which defines file extension type/creator
466 mappings. (default is @pkgconfdir@/extmap.conf).
467
468 force xattr with sticky bit = BOOLEAN (default: no) (G/V)
469 Writing metadata xattr on directories with the sticky bit set may
470 fail even though we may have write access to a directory, because
471 if the sticky bit is set only the owner is allowed to write xattrs.
472
473 By enabling this option Netatalk will write the metadata xattr as
474 root.
475
476 guest account = name (G)
477 Specifies the user that guests should use (default is nobody). The
478 name must be a valid user on the host system.
479
480 home name = name (H)
481 AFP user home volume name. The default is $u's home. The name must
482 contain "$u".
483
484 ignored attributes = all | nowrite | nodelete | norename (G)/(V)
485 Specify 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. Extended characters are
496 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(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, e.g. LDAP, Open Directory, Active Directory). The reason is,
706 in OS X ACLs are bound to UUIDs, not just uid's or gid's. Therefore
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 e.g. 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
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. Therefore you MUST NOT use this volume to store other
825 content when using this option, because it would NOT be accounted
826 for. The calculation works by reading the band size from the
827 Info.plist XML file of the sparsebundle, reading the bands/
828 directory counting the number of band files, and then multiplying
829 one with the other.
830
831 valid users = user @group (V)
832 The allow option allows the users and groups that access a share to
833 be specified. Users and groups are specified, delimited by spaces
834 or commas. Groups are designated by a @ prefix. Example:
835
836 valid users = user @group
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 '/', e.g. "veto files = veto1/", "veto files =
942 veto1/veto2/".
943
944 Volume options
945 Boolean volume options.
946
947 acls = BOOLEAN (default: yes) (V)
948 Whether to flag volumes as supporting ACLs. If ACL support is
949 compiled in, this is yes by default.
950
951 case sensitive = BOOLEAN (default: yes) (V)
952 Whether to flag volumes as supporting case-sensitive filenames. If
953 the filesystem is case-insensitive, set to no. However, it is not
954 fully verified.
955
956 Note
957 In spite of being case sensitive as a matter of fact, netatalk
958 3.1.3 and earlier did not notify kCaseSensitive flag to the
959 client. Starting with 3.1.4, it is notified correctly by
960 default.
961
962 cnid dev = BOOLEAN (default: yes) (V)
963 Whether to use the device number in the CNID backends. Helps when
964 the device number is not constant across a reboot, e.g. cluster,
965 ...
966
967 convert appledouble = BOOLEAN (default: yes) (V)
968 Whether automatic conversion from appledouble = v2 to appledouble =
969 ea is performed when accessing filesystems from clients. This is
970 generally useful, but costs some performance. It's recommendable to
971 run dbd on volumes and do the conversion with that. Then this
972 option can be set to no.
973
974 delete veto files = BOOLEAN (default: no) (V)
975 This option is used when Netatalk is attempting to delete a
976 directory that contains one or more vetoed files or directories
977 (see the veto files option). If this option is set to no (the
978 default) then if a directory contains any non-vetoed files or
979 directories then the directory delete will fail. This is usually
980 what you want.
981
982 If this option is set to yes, then Netatalk will attempt to
983 recursively delete any files and directories within the vetoed
984 directory.
985
986 follow symlinks = BOOLEAN (default: no) (V)
987 The default setting is false thus symlinks are not followed on the
988 server. This is the same behaviour as OS X's AFP server. Setting
989 the option to true causes afpd to follow symlinks on the server.
990 symlinks may point outside of the AFP volume, currently afpd
991 doesn't do any checks for "wide symlinks".
992
993 Note
994 This option will subtly break when the symlinks point across
995 filesystem boundaries.
996
997 invisible dots = BOOLEAN (default: no) (V)
998 make dot files invisible. WARNING: enabling this option will lead
999 to unwanted sideeffects were OS X applications when saving files to
1000 a temporary file starting with a dot first, then renaming the temp
1001 file to its final name, result in the saved file being invisible.
1002 The only thing this option is useful for is making files that start
1003 with a dot invisible on Mac OS 9. It's completely useless on Mac OS
1004 X, as both in Finder and in Terminal files starting with a dot are
1005 hidden anyway.
1006
1007 network ids = BOOLEAN (default: yes) (V)
1008 Whether the server support network ids. Setting this to no will
1009 result in the client not using ACL AFP functions.
1010
1011 preexec close = BOOLEAN (default: no) (V)
1012 A non-zero return code from preexec close the volume being
1013 immediately, preventing clients to mount/see the volume in
1014 question.
1015
1016 read only = BOOLEAN (default: no) (V)
1017 Specifies the share as being read only for all users. Overwrites ea
1018 = auto with ea = none
1019
1020 root preexec close= BOOLEAN (default: no) (V)
1021 A non-zero return code from root_preexec closes the volume
1022 immediately, preventing clients to mount/see the volume in
1023 question.
1024
1025 search db = BOOLEAN (default: no) (V)
1026 Use fast CNID database namesearch instead of slow recursive
1027 filesystem search. Relies on a consistent CNID database, i.e. Samba
1028 or local filesystem access lead to inaccurate or wrong results.
1029 Works only for "dbd" CNID db volumes.
1030
1031 stat vol = BOOLEAN (default: yes) (V)
1032 Whether to stat volume path when enumerating volumes list, useful
1033 for automounting or volumes created by a preexec script.
1034
1035 time machine = BOOLEAN (default: no) (V)
1036 Whether to enable Time Machine support for this volume.
1037
1038 unix priv = BOOLEAN (default: yes) (V)
1039 Whether to use AFP3 UNIX privileges. This should be set for OS X
1040 clients. See also: file perm, directory perm and umask.
1041
1043 The AFP protocol mostly refers to files and directories by ID and not
1044 by name. Netatalk needs a way to store these ID's in a persistent way,
1045 to achieve this several different CNID backends are available. The CNID
1046 Databases are by default located in the
1047 /var/lib/netatalk/CNID/(volumename)/.AppleDB/ directory.
1048
1049 cdb
1050 "Concurrent database", backend is based on Oracle Berkeley DB. With
1051 this backend several afpd daemons access the CNID database
1052 directly. Berkeley DB locking is used to synchronize access, if
1053 more than one afpd process is active for a volume. The drawback is,
1054 that the crash of a single afpd process might corrupt the database.
1055
1056 dbd
1057 Access to the CNID database is restricted to the cnid_metad daemon
1058 process. afpd processes communicate with the daemon for database
1059 reads and updates. If built with Berkeley DB transactions the
1060 probability for database corruption is practically zero, but
1061 performance can be slower than with cdb
1062
1063 last
1064 This backend is an exception, in terms of ID persistency. ID's are
1065 only valid for the current session. This is basically what afpd did
1066 in the 1.5 (and 1.6) versions. This backend is still available, as
1067 it is useful for e.g. sharing cdroms. Starting with Netatalk 3.0,
1068 it becomes the read only mode automatically.
1069
1070 Warning: It is NOT recommended to use this backend for volumes
1071 anymore, as afpd now relies heavily on a persistent ID database.
1072 Aliases will likely not work and filename mangling is not
1073 supported.
1074
1075 Even though ./configure --help might show that there are other CNID
1076 backends available, be warned those are likely broken or mainly used
1077 for testing. Don't use them unless you know what you're doing, they may
1078 be removed without further notice from future versions.
1079
1081 With OS X Apple introduced the AFP3 protocol. One of the most important
1082 changes was that AFP3 uses unicode names encoded as UTF-8 decomposed.
1083 Previous AFP/OS versions used codepages, like MacRoman,
1084 MacCentralEurope, etc.
1085
1086 afpd needs a way to preserve extended Macintosh characters, or
1087 characters illegal in unix filenames, when saving files on a unix
1088 filesystem. This version now uses UTF-8 as the default encoding for
1089 names. '/' will be converted to ':'.
1090
1091 Earlier versions used the the so called CAP encoding. An extended
1092 character (>0x7F) would be converted to a :xx sequence, e.g. the Apple
1093 Logo (MacRoman: 0xF0) was saved as :f0. Some special characters would
1094 be converted as to :xx notation as well. '/' would be encoded to :2f, a
1095 leading dot '.' might be encoded as :2e.
1096
1097 The vol charset option will allow you to select another volume
1098 encoding. afpd will accept any iconv(1) provided charset. It is highly
1099 recommended to stick to the default UTF-8.
1100
1102 afpd(8), afppasswd(5), afp_signature.conf(5), extmap.conf(5),
1103 cnid_metad(8)
1104
1106 See CONTRIBUTORS[1]
1107
1109 1. CONTRIBUTORS
1110 https://github.com/Netatalk/netatalk/blob/main/CONTRIBUTORS
1111
1112
1113
1114Netatalk 3.1.18 11 Apr 2023 AFP.CONF(5)