File: AppleVolumes.default.5.tmpl

package info (click to toggle)
netatalk 2.0.3-11%2Blenny1
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 9,428 kB
  • ctags: 6,161
  • sloc: ansic: 67,633; sh: 8,393; perl: 1,187; makefile: 1,060
file content (416 lines) | stat: -rw-r--r-- 13,631 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
.TH AppleVolumes.default 5 "03 January 2005" 2.0.3 Netatalk 
.SH NAME
AppleVolumes.default \- Configuration file used by afpd(8) to determine the shares made available through Appletalk
.SH DESCRIPTION
\fB:ETCDIR:/AppleVolumes.default\fR is the
configuration file used by afpd to determine what
portions of the file system will be shared via Apple Filing Protocol, as
well as their behaviour. Any line not prefixed with # is interpreted. The
configuration lines are composed like:
.PP
\fBpath\fR \fI[ volume name ] [ options
]\fR
.PP
The path name must be a fully qualified path name, or a path name
using either the ~ shell shorthand or any of the substitution variables,
which are listed below.
.PP
The volume name is the name that appears in the Chooser ot the
"connect to server" dialog on Macintoshes to represent the appropriate
share. If there are spaces in the name, it should be in quotes (i.e. "File
Share"). The volume name may not exceed 27 characters in length, and
cannot contain the \fB':'\fR character.
.RS 
\fBNote\fR
.PP
Each volume has to be configured on a \fBsingle\fR line.
.RE
.PP
The possible options and their meanings are:
.TP 
adouble:\fI[v1|v2|osx]\fR
specify the format of the metadata files, which are used for
saving Mac resource fork as well. Earlier versions used AppleDouble
V1, the new default format is V2. Starting with Netatalk 2.0, the
scheme MacOS X uses currently (10.3.x), is also supported
.RS 
\fBNote\fR

Using \fBadouble:osx\fR is \fBnot\fR recommended for production use. Its
only aim is to temporarely share eg. FAT32 formatted FireWire
harddrives written on a Macintosh with afpd. Apple's metadata
scheme lacks several essential features, so using it on the
server's side will break both CNIDs and MacOS 9
compatibility
.RE
.TP 
allow:\fI[users/groups]\fR
The allow option allows the users and groups that access a
share to be specified. Users and groups are specified, delimited by
commas. Groups are designated by a @ prefix. Example:
allow:user1,user2,@group
.TP 
deny:\fI[users/groups]\fR
The deny option specifies users and groups who are not allowed
access to the share. It follows the same format as the allow
option.
.TP 
cnidscheme:\fI[backend]\fR
set the CNID backend to be used for the volume, default is
[:DEFAULT_CNID_SCHEME:] available schemes:
[:COMPILED_BACKENDS:]
.TP 
dbpath:\fI[path]\fR
Sets the database information to be stored in path. You have
to specifiy a writable location, even if the volume is read
only.
.TP 
maccharset:\fI[charset]\fR
specifies the mac client codepage for this Volume, e.g.
"MAC_ROMAN", "MAC_CYRILLIC". If not specified the setting from
\fBafpd.conf\fR is inherited. This setting is only
required if you need volumes, where the mac codepage differs from
the one globally set in \fBafpd.conf\fR.
.TP 
options:\fI[option]\fR
This allows multiple options to be specified in a comma
delimited format. The available options are:
.RS 
.TP 
limitsize
Limit disk size reporting to 2GB. This can be used for
older Macintoshes using newer Appleshare clients.
.TP 
ro
Specifies the share as being read only for all users.
The .AppleDB directory has to be writeable, you can use the
\fB\-dbpath\fR option to relocate it.
.TP 
usedots
Don't do :hex translation for dot files. note: when this
option gets set, certain file names become illegal. These are
\&.Parent and anything that starts with .Apple. Also, dot files
created on the unix side are marked invisible.
.TP 
root_preexec_close
a non\-zero return code from root_preexec closes the
volume immediately, preventing clients to mount/see the volume
in question.
.TP 
preexec_close
a non\-zero return code from preexec close the volume
being immediately, preventing clients to mount/see the volume
in question.
.RE
.TP 
password:\fI[password]\fR
This option allows you to set a volume password, which can be
a maximum of 8 characters long (using ASCII strongly recommended at
the time of this writing).
.TP 
preexec:\fI[command]\fR
command to be run when the volume is mounted, ignored for user
defined volumes
.TP 
postexec:\fI[command]\fR
command to be run when the volume is closed, ignored for user
defined volumes
.TP 
root_preexec:\fI[command]\fR
command to be run as root when the volume is mounted, ignored
for user defined volumes
.TP 
root_postexec:\fI[command]\fR
command to be run as root when the volume is closed, ignored
for user defined volumes
.TP 
rolist:[\fBusers/groups\fR]
Allows certain users and groups to have read\-only access to a
share. This follows the allow option format.
.TP 
rwlist:\fI[users/groups]\fR
Allows certain users and groups to have read/write access to a
share. This follows the allow option format.
.TP 
veto:\fI[vetoed name]\fR
hide files and directories,where the path matches one of the
\&'/' delimited vetoed names. Matches are partial, e.g. path is
\fB/abc/def/file\fR and veto:/abc/ will hide the
file.
.TP 
volcharset:\fI[charset]\fR
specifies the volume codepage, e.g. "UTF8", "UTF8\-MAC",
"ISO\-8859\-15". Defaults to "UTF8".
.SH "VARIABLE SUBSTITUTIONS"
You can use variables in both volume path and volume name.
.TP 
1.
if you specify an unknown variable, it will not get
converted.
.TP 
2.
if you specify a known variable, but that variable doesn't have
a value, it will get ignored.
.PP
The variables which can be used for substitutions are:
.TP 
$b
basename
.TP 
$c
client's ip or appletalk address
.TP 
$d
volume pathname on server
.TP 
$f
full name (contents of the gecos field in the passwd
file)
.TP 
$g
group name
.TP 
$h
hostname
.TP 
$i
client's ip, without port
.TP 
$s
server name (this can be the hostname)
.TP 
$u
user name (if guest, it is the user that guest is running
as)
.TP 
$v
volume name (either ADEID_NAME or basename of path)
.TP 
$z
appletalk zone (may not exist)
.TP 
$$
prints dollar sign ($)
.PP
When using variable substitution in the volume name, always keep in
mind, not to exceed the 27 characters limit
.PP
\fBUsing variable substitution when defining volumes\fR
.PP
.nf
/home/groups/$g "Groupdir for $g"
~ "$f is the best one"
.fi

We define "groupdirs" for each primary
group and use a personalized server name for homedir shares.
.SH "CNID BACKENDS"
The AFP protocol mostly refers to files and directories by ID and
not by name. Netatalk needs a way to store these ID's in a persistent way,
to achieve this several different CNID backends are available. The CNID
Databases are by default located in the \fB.AppleDB\fR
folder in the volume root.
.TP 
cdb
"Concurrent database", backend is based on Sleepycat's Berkely
DB. With this backend several afpd deamons access
the CNID database directly. Berkeley DB locking is used to
synchronize access, if more than one afpd process
is active for a volume. The drawback is, that the crash of a single
afpd process might corrupt the database.
.TP 
dbd
Access to the CNID database is restricted to the
cnid_metad daemon process.
afpd processes communicate with the daemon for
database reads and updates. If built with Berkeley DB transactions
the probability for database corruption is practically zero, but
performance can be slower than with \fBcdb\fR
.TP 
last
This backend is an exception, in terms of ID persistency. ID's
are only valid for the current session. This is basically what
afpd did in the 1.5 (and 1.6) versions. This
backend is still available, as it is useful for e.g. sharing
cdroms.

\fBWarning\fR: It is
\fINOT\fR recommended to use this backend for volumes
anymore, as afpd now relies heavily on a
persistent ID database. Aliases will likely not work and filename
mangling is not supported.
.PP
Even though ./configure \-\-help might show that
there are other CNID backends available, be warned those are likely broken
or mainly used for testing. Don't use them unless you know what you're
doing, they may be removed without further notice from future
versions.
.SH "CHARSET OPTIONS"
With OS X Apple introduced the AFP3 protocol. One of the most
important changes was that AFP3 uses unicode names encoded as UTF\-8
decomposed. Previous AFP/OS versions used codepages, like MacRoman,
MacCentralEurope, etc.
.PP
afpd needs a way to preserve extended macintosh
characters, or characters illegal in unix filenames, when saving files on
a unix filesystem. Earlier versions used the the so called CAP encoding.
An extended character (>0x7F) would be converted to a :xx sequence,
e.g. the Apple Logo (MacRoman: 0XF0) was saved as \fB:f0\fR.
Some special characters will be converted as to :xx notation as well.
\&'\fB/\fR' will be encoded to \fB:2f\fR, if
\fB\-usedots\fR is not specified, a leading dot
\&'\fB.\fR' will be encoded as \fB:2e\fR.
.PP
This version now uses UTF\-8 as the default encoding for names.
Special characters, like '\fB/\fR' and a leading
\&'\fB.\fR' will still be CAP style encoded .
.PP
The \fB\-volcharset\fR option will allow you to select
another volume encoding. E.g. for western users another useful setting
could be \-volcharset ISO\-8859\-15. apfd will accept any
\fBiconv\fR(1) provided charset. If a character cannot be converted
from the mac codepage to the selected volcharset, afpd will save it as a
CAP encoded character. For AFP3 clients, afpd will
convert the UTF\-8 character to \fB\-maccharset\fR first. If this
conversion fails, you'll receive a \-50 error on the mac.
.PP
\fINote\fR: Whenever you can, please stick with the
default UTF\-8 volume format.
.SH "COMPATIBILITY WITH EARLIER VERSIONS"
To use a volume created with an earlier afpd
version, you'll have to specify the following options:
.PP
\fBuse a 1.x style volume\fR
.PP
.nf
/path/to/volume "Volname" adouble:v1 volcharset:ASCII
.fi
.PP
In case you used an NLS you could try using a compatible iconv
charset for \fB\-volcharset\fR.
.PP
\fBuse a 1.x style volume, created with maccode.iso8859\-1\fR
.PP
.nf
/path/to/volume "Volname" adouble:v1 volcharset:ISO\-8859\-1
.fi
.PP
You should consider converting old style volumes to the new
UTF\-8/AD2 format. The safest way to do this, is to create a new volume
with the default options and copy the files between this volumes with a
mac.
.PP
\fINote\fR: Using above example options will allow
you to downgrade to 1.x netatalk again.
.PP
\fINote\fR: Some 1.x NLS files used non standard
mappings, e.g. \fBmaccode.iso8859\-1.adapted\fR. This is not
supported anymore. You'll have to copy the contents of those volumes files
to a Mac and then back to the netatalk server, preferably to an UTF\-8
volume.
.SH "ADVANCED OPTIONS"
The following options should only be used after serious
consideration. Be sure you fully understood the, sometimes complex,
consequences, before using them.
.TP 
casefold:\fB[option]\fR
The casefold option handles, if the case of filenames should
be changed. The available options are:

\fBtolower\fR \- Lowercases names in both
directions.

\fBtoupper\fR \- Uppercases names in both
directions.

\fBxlatelower\fR \- Client sees lowercase, server
sees uppercase.

\fBxlateupper\fR \- Client sees uppercase, server
sees lowercase.
.TP 
options:[\fBoption\fR]
This allows multiple options to be specified in a comma
delimited format. The available options are:
.RS 
.TP 
cachecnid
If set afpd uses the ID information
stored in AppleDouble V2 header files to reduce database 
load. Don't set this option if the volume is modified by non
AFP clients (NFS/SMB/local). Defaults to off.
.TP 
crlf
Enables crlf translation for TEXT files, automatically
converting macintosh line breaks into Unix ones. Use of this
option might be dangerous since some older programs store
binary data files as type "TEXT" when saving and switch the
filetype in a second step. Afpd will
potentially destroy such files when "erroneously" changing
bytes in order to do line break translation.
.TP 
dropbox
Allows a volume to be declared as being a "dropbox."
Note that netatalk must be compiled with dropkludge support
for this to function. \fIWarning\fR: This
option is deprecated and might not work as expected.
.TP 
mswindows
Forces filename restrictions imposed by MS WinXX.
\fIWarning\fR: This is \fINOT\fR
recommened for volumes mainly used by Macs. Please make sure
you fully understand this option before using it.
.RS 
\fBWarning\fR

This option breaks direct saving to netatalk volumes from
some applications, i.e. OfficeX.
.RE
.TP 
noadouble
Forces afpd to not create
\&.AppleDouble directories unless macintosh metadata needs to be
written. This option is only useful if you want to share files
mostly used NOT by macs, causing afpd to
not automatically create .AppleDouble subdirs containing AD
header files in every directory it enters (which will it do by
default).

In case, you save or change files from mac clients, AD
metadata files have to be written even in case you set this
option. So you can't avoid the creation of .AppleDouble
directories and its contents when you give macs write access
to a share and they make use of it.

Try to avoid \fBnoadouble\fR whenever
possible.
.TP 
nodev
always use 0 for device number, helps when the device
number is not constant across a reboot, cluster, ...
.TP 
nofileid
don't advertise createfileid, resolveid, deleteid
calls.
.TP 
nohex
Disables :hex translations for anything except dot
files. This option makes the \fB'/\fR' character
illegal.
.TP 
prodos
Provides compatibility with Apple II clients.
.TP 
nostat
don't stat volume path when enumerating volumes list,
useful for automounting or volumes created by a preexec
script.
.TP 
upriv
use AFP3 unix privileges. Become familiar with the new
"unix privileges" AFP permissions concepts in MacOS X before
using this option.
.RE
.SH "SEE ALSO"
\fBafpd.conf\fR(5), \fBafpd\fR(8)