1APPLEVOLUMES.DEFAU(5) Netatalk 2.1 APPLEVOLUMES.DEFAU(5)
2
6 AppleVolumes.default, AppleVolumes.system, AppleVolumes - Configuration
7 file used by afpd(8) to determine the shares made available through AFP
8 and specify file name extension mappings.
9
11 /etc/netatalk//AppleVolumes.default
12 /etc/netatalk//AppleVolumes.system
13 ~/AppleVolumes
14 ~/.AppleVolumes
15 ~/applevolumes
16 ~/.applevolumes
17
19 /etc/netatalk//AppleVolumes.system and one of
20 /etc/netatalk//AppleVolumes.default, ~/AppleVolumes, ~/.AppleVolumes,
21 ~/applevolumes, or ~/.applevolumes are the configuration files used by
22 afpd to determine what portions of the file system will be shared via
23 Apple Filing Protocol, as well as their behaviour.
24 Any line not prefixed with # is interpreted. Newline escaping is
26 supported. The configuration lines are composed like:
27 path [ volume name ] [ options ]
29 .extension [ type [ creator ] ]
31 The path name must be a fully qualified path name, or a path name using
33 either the ~ shell shorthand or any of the substitution variables,
34 which are listed below.
35 The volume name is the name that appears in the Chooser ot the "connect
37 to server" dialog on Macintoshes to represent the appropriate share. If
38 volumename is unspecified, the last component of pathname is used. No
39 two volumes may have the same name. If there are spaces in the name, it
40 should be in quotes (i.e. "File Share"). The volume name cannot contain
41 the ´:´ character. The volume name is mangled if it is very long. Mac
42 codepage volume name is limited to 27 characters. UTF8-MAC volume name
43 is limited to -volnamelen parameter in afpd.conf
44 Note
46 Each volume has to be configured on a single line. Though newline
47 escaping is supported.
48 The leading-dot lines specify file name extension mappings. The
50 extension ´.´ sets the default creator and type for otherwise untyped
51 Unix files.
52 Note
54 File name extension mapping is useful for Mac OS 9 and earlier. But
55 it should not use for Mac OS X.
56 It is possible to specify default options for all volumes with a
58 :DEFAULT: line preceeding these volume definitions:
59 Example. :DEFAULT: configuration line
61 :DEFAULT: options:upriv,usedots dbpath:/var/dbd/AppleDB/$v dperm:0775 fperm:0664
63 The possible options and their meanings are:
65 adouble:[v1|v2|osx]
67 Specify the format of the metadata files, which are used for saving
68 Mac resource fork as well. Earlier versions used AppleDouble V1,
69 the new default format is V2. Starting with Netatalk 2.0, the
70 scheme MacOS X 10.3.x uses, is also supported.
71 Note
73 adouble:osx cannot be treated normally any longer. Its only aim
74 was to temporarely share eg. FAT32 formatted FireWire
75 harddrives written on a Macintosh with afpd. Apple´s metadata
76 scheme lacks several essential features, so using it on the
77 server´s side will break both CNIDs and MacOS 9 compatibility.
78 AppleDouble file of Mac OS X 10.6 is incompatible to V1 and V2.
79 volsizelimit:size in MiB
81 Useful for TimeMachine: limits the reported volume size, thus
82 preventing TM from using the whole real disk space for backup.
83 Example: "volsizelimit:1000" would limit the reported disk space to
84 1 GB.
85 allow:[users/groups]
87 The allow option allows the users and groups that access a share to
88 be specified. Users and groups are specified, delimited by commas.
89 Groups are designated by a @ prefix. Example:
90 allow:user1,user2,@group
91 deny:[users/groups]
93 The deny option specifies users and groups who are not allowed
94 access to the share. It follows the same format as the allow
95 option.
96 allowed_hosts:[IP host address/IP netmask bits[, ... ]]
98 Only listed hosts and networks are allowed, all others are
99 rejected. The network address may be specified either in
100 dotted-decimal format for IPv4 or in hexadecimal format for IPv6.
101 Example: allowed_hosts:10.1.0.0/16,10.2.1.100,2001:0db8:1234::/48
103 denied_hosts:[IP host address/IP netmask bits[, ...]]
105 Listed hosts and nets are rejected, all others are allowed.
106 Example: denied_hosts: 192.168.100/24,10.1.1.1,2001:db8::1428:57ab
108 cnidscheme:[backend]
110 set the CNID backend to be used for the volume, default is [dbd]
111 available schemes: [dbd last tdb]
112 dbpath:[path]
114 Sets the database information to be stored in path. You have to
115 specifiy a writable location, even if the volume is read only.
116 cnidserver:[fqdn|IP[:port]]
118 Query this servername or IP address (default:localhost) and port
119 (default: 4700) for CNIDs. Only used with CNID backend "dbd". This
120 option here overrides any setting from afpd.conf:cnidserver.
121 ea:[none|auto|sys|ad]
123 Specify how Extended Attributes are stored. auto is the default.
124 auto
126 Try sys (by setting an EA on the shared directory itself),
127 fallback to ad. Requires writeable volume for perfoming test.
128 options:ro overwrites auto with none. Use explicit ea:sys|ad
129 for read-only volumes where appropiate.
130 sys
132 Use filesystem Extended Attributes.
133 ad
135 Use files in .AppleDouble directories.
136 none
138 No Extended Attributes support.
139 maccharset:[charset]
141 specifies the mac client codepage for this Volume, e.g.
142 "MAC_ROMAN", "MAC_CYRILLIC". If not specified the setting from
143 afpd.conf is inherited. This setting is only required if you need
144 volumes, where the mac codepage differs from the one globally set
145 in afpd.conf.
146 options:[option]
148 This allows multiple options to be specified in a comma delimited
149 format. The available options are:
150 acls
152 Enable ACLs on this volume. Requires a NFSv4 ACLs compatible
153 filesystem (e.g. ZFS) and an ACL API compatible to *Solaris. In
154 other words: this requires Solaris, Opensolaris or a derived
155 distribution.
156 tm
158 Enable Time Machine suport for this volume.
159 invisibledots
161 Use with usedots: make dot files invisible.
162 limitsize
164 Limit disk size reporting to 2GB. This can be used for older
165 Macintoshes using newer Appleshare clients.
166 preexec_close
168 a non-zero return code from preexec close the volume being
169 immediately, preventing clients to mount/see the volume in
170 question.
171 ro
173 Specifies the share as being read only for all users. The
174 .AppleDB directory has to be writeable, you can use the -dbpath
175 option to relocate it. Overwrites ea:auto with ea:none
176 root_preexec_close
178 a non-zero return code from root_preexec closes the volume
179 immediately, preventing clients to mount/see the volume in
180 question.
181 upriv
183 use AFP3 unix privileges. Become familiar with the new "unix
184 privileges" AFP permissions concepts in MacOS X before using
185 this option. See also: perm|fperm|dperm.
186 usedots
188 Don´t do :hex translation for dot files. note: when this option
189 gets set, certain file names become illegal. These are .Parent
190 and anything that starts with .Apple. See also invisibledots.
191 password:[password]
193 This option allows you to set a volume password, which can be a
194 maximum of 8 characters long (using ASCII strongly recommended at
195 the time of this writing).
196 perm|fperm|dperm:[mode]
198 Add(or) with the client requested permissions: perm affects files
199 and directories, fperm is for files only, dperm is for directories
200 only. Use with options:upriv.
201 Example. Volume for a collaborative workgroup
203 /path/to/volume "Workgroup" options:upriv dperm:0770 fperm:0660
205 umask:[mode]
207 set perm mask. Use with options:upriv.
208 preexec:[command]
210 command to be run when the volume is mounted, ignored for user
211 defined volumes
212 postexec:[command]
214 command to be run when the volume is closed, ignored for user
215 defined volumes
216 root_preexec:[command]
218 command to be run as root when the volume is mounted, ignored for
219 user defined volumes
220 root_postexec:[command]
222 command to be run as root when the volume is closed, ignored for
223 user defined volumes
224 rolist:[users/groups]
226 Allows certain users and groups to have read-only access to a
227 share. This follows the allow option format.
228 rwlist:[users/groups]
230 Allows certain users and groups to have read/write access to a
231 share. This follows the allow option format.
232 veto:[vetoed name]
234 hide files and directories,where the path matches one of the ´/´
235 delimited vetoed names. Matches are partial, e.g. path is
236 /abc/def/file and veto:/abc/ will hide the file.
237 volcharset:[charset]
239 specifies the volume codepage, e.g. "UTF8", "UTF8-MAC",
240 "ISO-8859-15". Defaults to "UTF8".
241
243 You can use variables in both volume path and volume name.
244 1. if you specify an unknown variable, it will not get converted.
246 2. if you specify a known variable, but that variable doesn´t have a
248 value, it will get ignored.
249 The variables which can be used for substitutions are:
251 $b
253 basename
254 $c
256 client´s ip or appletalk address
257 $d
259 volume pathname on server
260 $f
262 full name (contents of the gecos field in the passwd file)
263 $g
265 group name
266 $h
268 hostname
269 $i
271 client´s ip, without port
272 $s
274 server name (this can be the hostname)
275 $u
277 user name (if guest, it is the user that guest is running as)
278 $v
280 volume name (either ADEID_NAME or basename of path)
281 $z
283 appletalk zone (may not exist)
284 $$
286 prints dollar sign ($)
287 Example. Using variable substitution when defining volumes
289 /home/groups/$g "Groupdir for $g"
291 ~ "$f is the best one"
292 We define "groupdirs" for each primary group and use a personalized
294 server name for homedir shares.
295
297 The AFP protocol mostly refers to files and directories by ID and not
298 by name. Netatalk needs a way to store these ID´s in a persistent way,
299 to achieve this several different CNID backends are available. The CNID
300 Databases are by default located in the .AppleDB folder in the volume
301 root.
302 cdb
304 "Concurrent database", backend is based on Sleepycat´s Berkely DB.
305 With this backend several afpd deamons access the CNID database
306 directly. Berkeley DB locking is used to synchronize access, if
307 more than one afpd process is active for a volume. The drawback is,
308 that the crash of a single afpd process might corrupt the database.
309 dbd
311 Access to the CNID database is restricted to the cnid_metad daemon
312 process. afpd processes communicate with the daemon for database
313 reads and updates. If built with Berkeley DB transactions the
314 probability for database corruption is practically zero, but
315 performance can be slower than with cdb
316 last
318 This backend is an exception, in terms of ID persistency. ID´s are
319 only valid for the current session. This is basically what afpd did
320 in the 1.5 (and 1.6) versions. This backend is still available, as
321 it is useful for e.g. sharing cdroms.
322 Warning: It is NOT recommended to use this backend for volumes
324 anymore, as afpd now relies heavily on a persistent ID database.
325 Aliases will likely not work and filename mangling is not
326 supported.
327 Even though ./configure --help might show that there are other CNID
329 backends available, be warned those are likely broken or mainly used
330 for testing. Don´t use them unless you know what you´re doing, they may
331 be removed without further notice from future versions.
332
334 With OS X Apple introduced the AFP3 protocol. One of the most important
335 changes was that AFP3 uses unicode names encoded as UTF-8 decomposed.
336 Previous AFP/OS versions used codepages, like MacRoman,
337 MacCentralEurope, etc.
338 afpd needs a way to preserve extended macintosh characters, or
340 characters illegal in unix filenames, when saving files on a unix
341 filesystem. Earlier versions used the the so called CAP encoding. An
342 extended character (>0x7F) would be converted to a :xx sequence, e.g.
343 the Apple Logo (MacRoman: 0XF0) was saved as :f0. Some special
344 characters will be converted as to :xx notation as well. ´/´ will be
345 encoded to :2f, if -usedots is not specified, a leading dot ´.´ will be
346 encoded as :2e.
347 This version now uses UTF-8 as the default encoding for names. Special
349 characters, like ´/´ and a leading ´.´ will still be CAP style encoded
350 .
351 The -volcharset option will allow you to select another volume
353 encoding. E.g. for western users another useful setting could be
354 -volcharset ISO-8859-15. apfd will accept any iconv(1) provided
355 charset. If a character cannot be converted from the mac codepage to
356 the selected volcharset, afpd will save it as a CAP encoded character.
357 For AFP3 clients, afpd will convert the UTF-8 character to -maccharset
358 first. If this conversion fails, you´ll receive a -50 error on the mac.
359 Note: Whenever you can, please stick with the default UTF-8 volume
361 format.
362
364 To use a volume created with an earlier afpd version, you´ll have to
365 specify the following options:
366 Example. use a 1.x style volume
368 /path/to/volume "Volname" adouble:v1 volcharset:ASCII
370 In case you used an NLS you could try using a compatible iconv charset
372 for -volcharset.
373 Example. use a 1.x style volume, created with maccode.iso8859-1
375 /path/to/volume "Volname" adouble:v1 volcharset:ISO-8859-1
377 You should consider converting old style volumes to the new UTF-8/AD2
379 format. The safest way to do this, is to create a new volume with the
380 default options and copy the files between this volumes with a mac.
381 Note: Using above example options will allow you to downgrade to 1.x
383 netatalk again.
384 Note: Some 1.x NLS files used non standard mappings, e.g.
386 maccode.iso8859-1.adapted. Three 1.x CAP double-byte maccharsets are
387 incompatible to netatalk 2.x; "MAC_CHINESE_TRAD", "MAC_JAPANESE" and
388 "MAC_KOREAN". These are not supported anymore. You´ll have to copy the
389 contents of those volumes files to a Mac and then back to the netatalk
390 server, preferably to an UTF-8 volume.
391
393 The following options should only be used after serious consideration.
394 Be sure you fully understood the, sometimes complex, consequences,
395 before using them.
396 casefold:[option]
398 The casefold option handles, if the case of filenames should be
399 changed. The available options are:
400 tolower - Lowercases names in both directions.
402 toupper - Uppercases names in both directions.
404 xlatelower - Client sees lowercase, server sees uppercase.
406 xlateupper - Client sees uppercase, server sees lowercase.
408 options:[option]
410 This allows multiple options to be specified in a comma delimited
411 format. The available options are:
412 caseinsensitive
414 The underlying filesystem is case insensitive (only tested with
415 JFS in OS2 mode).
416 crlf
418 Enables crlf translation for TEXT files, automatically
419 converting macintosh line breaks into Unix ones. Use of this
420 option might be dangerous since some older programs store
421 binary data files as type "TEXT" when saving and switch the
422 filetype in a second step. Afpd will potentially destroy such
423 files when "erroneously" changing bytes in order to do line
424 break translation.
425 dropbox
427 Allows a volume to be declared as being a "dropbox." Note that
428 netatalk must be compiled with dropkludge support for this to
429 function. Warning: This option is deprecated and might not
430 work as expected.
431 dropkludge
433 same as "dropbox".
434 mswindows
436 Forces filename restrictions imposed by MS WinXX. Warning:
437 This is NOT recommened for volumes mainly used by Macs. Please
438 make sure you fully understand this option before using it.
439 Warning
441 This option breaks direct saving to netatalk volumes from
442 some applications, i.e. OfficeX.
443 noadouble
445 Forces afpd to not create .AppleDouble directories unless
446 macintosh metadata needs to be written. This option is only
447 useful if you want to share files mostly used NOT by macs,
448 causing afpd to not automatically create .AppleDouble subdirs
449 containing AD header files in every directory it enters (which
450 will it do by default).
451 In case, you save or change files from mac clients, AD metadata
453 files have to be written even in case you set this option. So
454 you can´t avoid the creation of .AppleDouble directories and
455 its contents when you give macs write access to a share and
456 they make use of it.
457 Try to avoid noadouble whenever possible.
459 nocnidcache
461 If set afpd doesn´t store the ID information in AppleDouble V2
462 header files. As these IDs are used for caching and as a
463 database backup, this option normally shouldn´t be set.
464 nodev
466 always use 0 for device number, helps when the device number is
467 not constant across a reboot, cluster, ...
468 nofileid
470 don´t advertise createfileid, resolveid, deleteid calls.
471 nohex
473 Disables :hex translations for anything except dot files. This
474 option makes the ´/´ character illegal.
475 nostat
477 don´t stat volume path when enumerating volumes list, useful
478 for automounting or volumes created by a preexec script.
479 prodos
481 Provides compatibility with Apple II clients. (legacy)
482
484 Example. Extension is jpg. Type is "JPEG". Creator is "ogle".
485 .jpg "JPEG" "ogle"
487 Example. Extension is lzh. Type is "LHA ". Creator is not defined.
489 .lzh "LHA "
491
493 afpd.conf(5), afpd(8), afp_ldap.conf(5), afp_acls(8)
494Netatalk 2.1 22 Apr 2010 APPLEVOLUMES.DEFAU(5)