1AppleVolumes.default(5) Netatalk AppleVolumes.default(5)
2
6 AppleVolumes.default - Configuration file used by afpd(8) to determine
7 the shares made available through Appletalk
8
10 /etc/atalk//AppleVolumes.default is the configuration file used by afpd
11 to determine what portions of the file system will be shared via Apple
12 Filing Protocol, as well as their behaviour. Any line not prefixed with
13 # is interpreted. The configuration lines are composed like:
14 path [ volume name ] [ options ]
16 The path name must be a fully qualified path name, or a path name using
18 either the ~ shell shorthand or any of the substitution variables,
19 which are listed below.
20 The volume name is the name that appears in the Chooser ot the "connect
22 to server" dialog on Macintoshes to represent the appropriate share. If
23 there are spaces in the name, it should be in quotes (i.e. "File
24 Share"). The volume name may not exceed 27 characters in length, and
25 cannot contain the ':' character.
26 Note
27 Each volume has to be configured on a single line.
29 The possible options and their meanings are:
31 adouble:[v1|v2|osx]
33 specify the format of the metadata files, which are used for
34 saving Mac resource fork as well. Earlier versions used Apple‐
35 Double V1, the new default format is V2. Starting with Netatalk
36 2.0, the scheme MacOS X uses currently (10.3.x), is also sup‐
37 ported
38 Note
39 Using adouble:osx is not recommended for production use. Its
41 only aim is to temporarely share eg. FAT32 formatted FireWire
42 harddrives written on a Macintosh with afpd. Apple's metadata
43 scheme lacks several essential features, so using it on the
44 server's side will break both CNIDs and MacOS 9 compatibility
45 allow:[users/groups]
47 The allow option allows the users and groups that access a share
48 to be specified. Users and groups are specified, delimited by
49 commas. Groups are designated by a @ prefix. Example:
50 allow:user1,user2,@group
51 deny:[users/groups]
53 The deny option specifies users and groups who are not allowed
54 access to the share. It follows the same format as the allow
55 option.
56 cnidscheme:[backend]
58 set the CNID backend to be used for the volume, default is
59 [:DEFAULT_CNID_SCHEME:] available schemes: [:COMPILED_BACKENDS:]
60 dbpath:[path]
62 Sets the database information to be stored in path. You have to
63 specifiy a writable location, even if the volume is read only.
64 maccharset:[charset]
66 specifies the mac client codepage for this Volume, e.g.
67 "MAC_ROMAN", "MAC_CYRILLIC". If not specified the setting from
68 afpd.conf is inherited. This setting is only required if you
69 need volumes, where the mac codepage differs from the one glob‐
70 ally set in afpd.conf.
71 options:[option]
73 This allows multiple options to be specified in a comma delim‐
74 ited format. The available options are:
75 limitsize
77 Limit disk size reporting to 2GB. This can be used for
78 older Macintoshes using newer Appleshare clients.
79 ro Specifies the share as being read only for all users.
81 The .AppleDB directory has to be writeable, you can use
82 the -dbpath option to relocate it.
83 usedots
85 Don't do :hex translation for dot files. note: when this
86 option gets set, certain file names become illegal. These
87 are .Parent and anything that starts with .Apple. Also,
88 dot files created on the unix side are marked invisible.
89 root_preexec_close
91 a non-zero return code from root_preexec closes the vol‐
92 ume immediately, preventing clients to mount/see the vol‐
93 ume in question.
94 preexec_close
96 a non-zero return code from preexec close the volume
97 being immediately, preventing clients to mount/see the
98 volume in question.
99 password:[password]
101 This option allows you to set a volume password, which can be a
102 maximum of 8 characters long (using ASCII strongly recommended
103 at the time of this writing).
104 preexec:[command]
106 command to be run when the volume is mounted, ignored for user
107 defined volumes
108 postexec:[command]
110 command to be run when the volume is closed, ignored for user
111 defined volumes
112 root_preexec:[command]
114 command to be run as root when the volume is mounted, ignored
115 for user defined volumes
116 root_postexec:[command]
118 command to be run as root when the volume is closed, ignored for
119 user defined volumes
120 rolist:[users/groups]
122 Allows certain users and groups to have read-only access to a
123 share. This follows the allow option format.
124 rwlist:[users/groups]
126 Allows certain users and groups to have read/write access to a
127 share. This follows the allow option format.
128 veto:[vetoed name]
130 hide files and directories,where the path matches one of the '/'
131 delimited vetoed names. Matches are partial, e.g. path is
132 /abc/def/file and veto:/abc/ will hide the file.
133 volcharset:[charset]
135 specifies the volume codepage, e.g. "UTF8", "UTF8-MAC",
136 "ISO-8859-15". Defaults to "UTF8".
137
139 You can use variables in both volume path and volume name.
140 1. if you specify an unknown variable, it will not get converted.
142 2. if you specify a known variable, but that variable doesn't have
144 a value, it will get ignored.
145 The variables which can be used for substitutions are:
147 $b basename
149 $c client's ip or appletalk address
151 $d volume pathname on server
153 $f full name (contents of the gecos field in the passwd file)
155 $g group name
157 $h hostname
159 $i client's ip, without port
161 $s server name (this can be the hostname)
163 $u user name (if guest, it is the user that guest is running as)
165 $v volume name (either ADEID_NAME or basename of path)
167 $z appletalk zone (may not exist)
169 $$ prints dollar sign ($)
171 When using variable substitution in the volume name, always keep in
173 mind, not to exceed the 27 characters limit
174 Using variable substitution when defining volumes
176 /home/groups/$g "Groupdir for $g"
178 ~ "$f is the best one"
179 We define "groupdirs" for each primary group and use a personalized
181 server name for homedir shares.
182
184 The AFP protocol mostly refers to files and directories by ID and not
185 by name. Netatalk needs a way to store these ID's in a persistent way,
186 to achieve this several different CNID backends are available. The CNID
187 Databases are by default located in the .AppleDB folder in the volume
188 root.
189 cdb "Concurrent database", backend is based on Sleepycat's Berkely
191 DB. With this backend several afpd deamons access the CNID data‐
192 base directly. Berkeley DB locking is used to synchronize
193 access, if more than one afpd process is active for a volume.
194 The drawback is, that the crash of a single afpd process might
195 corrupt the database.
196 dbd Access to the CNID database is restricted to the cnid_metad dae‐
198 mon process. afpd processes communicate with the daemon for
199 database reads and updates. If built with Berkeley DB transac‐
200 tions the probability for database corruption is practically
201 zero, but performance can be slower than with cdb
202 last This backend is an exception, in terms of ID persistency. ID's
204 are only valid for the current session. This is basically what
205 afpd did in the 1.5 (and 1.6) versions. This backend is still
206 available, as it is useful for e.g. sharing cdroms.
207 Warning: It is NOT recommended to use this backend for volumes
209 anymore, as afpd now relies heavily on a persistent ID database.
210 Aliases will likely not work and filename mangling is not sup‐
211 ported.
212 Even though ./configure --help might show that there are other CNID
214 backends available, be warned those are likely broken or mainly used
215 for testing. Don't use them unless you know what you're doing, they may
216 be removed without further notice from future versions.
217
219 With OS X Apple introduced the AFP3 protocol. One of the most important
220 changes was that AFP3 uses unicode names encoded as UTF-8 decomposed.
221 Previous AFP/OS versions used codepages, like MacRoman, MacCentralEu‐
222 rope, etc.
223 afpd needs a way to preserve extended macintosh characters, or charac‐
225 ters illegal in unix filenames, when saving files on a unix filesystem.
226 Earlier versions used the the so called CAP encoding. An extended
227 character (>0x7F) would be converted to a :xx sequence, e.g. the Apple
228 Logo (MacRoman: 0XF0) was saved as :f0. Some special characters will
229 be converted as to :xx notation as well. '/' will be encoded to :2f,
230 if -usedots is not specified, a leading dot '.' will be encoded as :2e.
231 This version now uses UTF-8 as the default encoding for names. Special
233 characters, like '/' and a leading '.' will still be CAP style encoded
234 .
235 The -volcharset option will allow you to select another volume encod‐
237 ing. E.g. for western users another useful setting could be -volcharset
238 ISO-8859-15. apfd will accept any iconv(1) provided charset. If a char‐
239 acter cannot be converted from the mac codepage to the selected
240 volcharset, afpd will save it as a CAP encoded character. For AFP3
241 clients, afpd will convert the UTF-8 character to -maccharset first. If
242 this conversion fails, you'll receive a -50 error on the mac.
243 Note: Whenever you can, please stick with the default UTF-8 volume for‐
245 mat.
246
248 To use a volume created with an earlier afpd version, you'll have to
249 specify the following options:
250 use a 1.x style volume
252 /path/to/volume "Volname" adouble:v1 volcharset:ASCII
254 In case you used an NLS you could try using a compatible iconv charset
256 for -volcharset.
257 use a 1.x style volume, created with maccode.iso8859-1
259 /path/to/volume "Volname" adouble:v1 volcharset:ISO-8859-1
261 You should consider converting old style volumes to the new UTF-8/AD2
263 format. The safest way to do this, is to create a new volume with the
264 default options and copy the files between this volumes with a mac.
265 Note: Using above example options will allow you to downgrade to 1.x
267 netatalk again.
268 Note: Some 1.x NLS files used non standard mappings, e.g. mac‐
270 code.iso8859-1.adapted. This is not supported anymore. You'll have to
271 copy the contents of those volumes files to a Mac and then back to the
272 netatalk server, preferably to an UTF-8 volume.
273
275 The following options should only be used after serious consideration.
276 Be sure you fully understood the, sometimes complex, consequences,
277 before using them.
278 casefold:[option]
280 The casefold option handles, if the case of filenames should be
281 changed. The available options are:
282 tolower - Lowercases names in both directions.
284 toupper - Uppercases names in both directions.
286 xlatelower - Client sees lowercase, server sees uppercase.
288 xlateupper - Client sees uppercase, server sees lowercase.
290 options:[option]
292 This allows multiple options to be specified in a comma delim‐
293 ited format. The available options are:
294 cachecnid
296 If set afpd uses the ID information stored in AppleDouble
297 V2 header files to reduce database load. Don't set this
298 option if the volume is modified by non AFP clients
299 (NFS/SMB/local). Defaults to off.
300 crlf Enables crlf translation for TEXT files, automatically
302 converting macintosh line breaks into Unix ones. Use of
303 this option might be dangerous since some older programs
304 store binary data files as type "TEXT" when saving and
305 switch the filetype in a second step. Afpd will poten‐
306 tially destroy such files when "erroneously" changing
307 bytes in order to do line break translation.
308 dropbox
310 Allows a volume to be declared as being a "dropbox."
311 Note that netatalk must be compiled with dropkludge sup‐
312 port for this to function. Warning: This option is depre‐
313 cated and might not work as expected.
314 mswindows
316 Forces filename restrictions imposed by MS WinXX. Warn‐
317 ing: This is NOT recommened for volumes mainly used by
318 Macs. Please make sure you fully understand this option
319 before using it.
320 Warning
321 This option breaks direct saving to netatalk volumes from
323 some applications, i.e. OfficeX.
324 noadouble
326 Forces afpd to not create .AppleDouble directories unless
327 macintosh metadata needs to be written. This option is
328 only useful if you want to share files mostly used NOT by
329 macs, causing afpd to not automatically create .AppleDou‐
330 ble subdirs containing AD header files in every directory
331 it enters (which will it do by default).
332 In case, you save or change files from mac clients, AD
334 metadata files have to be written even in case you set
335 this option. So you can't avoid the creation of .Apple‐
336 Double directories and its contents when you give macs
337 write access to a share and they make use of it.
338 Try to avoid noadouble whenever possible.
340 nodev always use 0 for device number, helps when the device
342 number is not constant across a reboot, cluster, ...
343 nofileid
345 don't advertise createfileid, resolveid, deleteid calls.
346 nohex Disables :hex translations for anything except dot files.
348 This option makes the '/' character illegal.
349 prodos Provides compatibility with Apple II clients.
351 nostat don't stat volume path when enumerating volumes list,
353 useful for automounting or volumes created by a preexec
354 script.
355 upriv use AFP3 unix privileges. Become familiar with the new
357 "unix privileges" AFP permissions concepts in MacOS X
358 before using this option.
359
361 afpd.conf(5), afpd(8)
3622.0.3 03 January 2005 AppleVolumes.default(5)