man/man5/AppleVolumes.default.5.tmpl

   1 .TH AppleVolumes.default 5 "06 September 2004" 2.0.0 Netatalk
   2 .SH NAME
   3 AppleVolumes.default \- Configuration file used by afpd(8) to determine the shares made available through Appletalk
   4 .SH DESCRIPTION
   5 \fB:ETCDIR:/AppleVolumes.default\fR is the
   6 configuration file used by afpd to determine what
   7 portions of the file system will be shared via Apple Filing Protocol, as
   8 well as their behaviour. Any line not prefixed with # is interpreted. The
   9 configuration lines are composed like:
  10 .PP
  11 \fBpath\fR \fI[ volume name ] [ options
  12 ]\fR
  13 .PP
  14 The path name must be a fully qualified path name, or a path name
  15 using either the ~ shell shorthand or any of the substitution variables,
  16 which are listed below.
  17 .PP
  18 The volume name is the name that appears in the Chooser ot the
  19 "connect to server" dialog on Macintoshes to represent the appropriate
  20 share. If there are spaces in the name, it should be in quotes (i.e. "File
  21 Share"). The volume name may not exceed 27 characters in length, and
  22 cannot contain the \fB':'\fR character.
  23 .RS
  24 \fBNote\fR
  25 .PP
  26 Each volume has to be configured on a \fBsingle\fR line.
  27 .RE
  28 .PP
  29 The possible options and their meanings are:
  30 .TP
  31 adouble:\fI[v1|v2|osx]\fR
  32 specify the format of the metadata files, which are used for
  33 saving Mac resource fork as well. Earlier versions used AppleDouble
  34 V1, the new default format is V2. Starting with Netatalk 2.0, the
  35 scheme MacOS X uses currently (10.3.x), is also supported
  36 .RS
  37 \fBNote\fR
  38
  39 Using \fBadouble:osx\fR is \fBnot\fR recommended for production use. Its
  40 only aim is to temporarely share eg. FAT32 formatted FireWire
  41 harddrives written on a Macintosh with afpd. Apple's metadata
  42 scheme lacks several essential features, so using it on the
  43 server's side will break both CNIDs and MacOS 9
  44 compatibility
  45 .RE
  46 .TP
  47 allow:\fI[users/groups]\fR
  48 The allow option allows the users and groups that access a
  49 share to be specified. Users and groups are specified, delimited by
  50 commas. Groups are designated by a @ prefix. Example:
  51 allow:user1,user2,@group
  52 .TP
  53 deny:\fI[users/groups]\fR
  54 The deny option specifies users and groups who are not allowed
  55 access to the share. It follows the same format as the allow
  56 option.
  57 .TP
  58 cnidscheme:\fI[backend]\fR
  59 set the CNID backend to be used for the volume, default is
  60 [:DEFAULT_CNID_SCHEME:] available schemes:
  61 [:COMPILED_BACKENDS:]
  62 .TP
  63 dbpath:\fI[path]\fR
  64 Sets the database information to be stored in path. You have
  65 to specifiy a writable location, even if the volume is read
  66 only.
  67 .TP
  68 maccharset:\fI[charset]\fR
  69 specifies the mac client codepage for this Volume, e.g.
  70 "MAC_ROMAN", "MAC_CYRILLIC". If not specified the setting from
  71 \fBafpd.conf\fR is inherited. This setting is only
  72 required if you need volumes, where the mac codepage differs from
  73 the one globally set in \fBafpd.conf\fR.
  74 .TP
  75 options:\fI[option]\fR
  76 This allows multiple options to be specified in a comma
  77 delimited format. The available options are:
  78 .RS
  79 .TP
  80 limitsize
  81 Limit disk size reporting to 2GB. This can be used for
  82 older Macintoshes using newer Appleshare clients.
  83 .TP
  84 ro
  85 Specifies the share as being read only for all users.
  86 The .AppleDB directory has to be writeable, you can use the
  87 \fB\-dbpath\fR option to relocate it.
  88 .TP
  89 usedots
  90 Don't do :hex translation for dot files. note: when this
  91 option gets set, certain file names become illegal. These are
  92 \&.Parent and anything that starts with .Apple. Also, dot files
  93 created on the unix side are marked invisible.
  94 .TP
  95 root_preexec_close
  96 a non\-zero return code from root_preexec closes the
  97 volume immediately, preventing clients to mount/see the volume
  98 in question.
  99 .TP
 100 preexec_close
 101 a non\-zero return code from preexec close the volume
 102 being immediately, preventing clients to mount/see the volume
 103 in question.
 104 .RE
 105 .TP
 106 password:\fI[password]\fR
 107 This option allows you to set a volume password, which can be
 108 a maximum of 8 characters long (using ASCII strongly recommended at
 109 the time of this writing).
 110 .TP
 111 preexec:\fI[command]\fR
 112 command to be run when the volume is mounted, ignored for user
 113 defined volumes
 114 .TP
 115 postexec:\fI[command]\fR
 116 command to be run when the volume is closed, ignored for user
 117 defined volumes
 118 .TP
 119 root_preexec:\fI[command]\fR
 120 command to be run as root when the volume is mounted, ignored
 121 for user defined volumes
 122 .TP
 123 root_postexec:\fI[command]\fR
 124 command to be run as root when the volume is closed, ignored
 125 for user defined volumes
 126 .TP
 127 rolist:[\fBusers/groups\fR]
 128 Allows certain users and groups to have read\-only access to a
 129 share. This follows the allow option format.
 130 .TP
 131 rwlist:\fI[users/groups]\fR
 132 Allows certain users and groups to have read/write access to a
 133 share. This follows the allow option format.
 134 .TP
 135 veto:\fI[vetoed name]\fR
 136 hide files and directories,where the path matches one of the
 137 \&'/' delimited vetoed names. Matches are partial, e.g. path is
 138 \fB/abc/def/file\fR and veto:/abc/ will hide the
 139 file.
 140 .TP
 141 volcharset:\fI[charset]\fR
 142 specifies the volume codepage, e.g. "UTF8", "UTF8\-MAC",
 143 "ISO\-8859\-15". Defaults to "UTF8".
 144 .SH "VARIABLE SUBSTITUTIONS"
 145 You can use variables in both volume path and volume name.
 146 .TP
 147 1.
 148 if you specify an unknown variable, it will not get
 149 converted.
 150 .TP
 151 2.
 152 if you specify a known variable, but that variable doesn't have
 153 a value, it will get ignored.
 154 .PP
 155 The variables which can be used for substitutions are:
 156 .TP
 157 $b
 158 basename
 159 .TP
 160 $c
 161 client's ip or appletalk address
 162 .TP
 163 $d
 164 volume pathname on server
 165 .TP
 166 $f
 167 full name (contents of the gecos field in the passwd
 168 file)
 169 .TP
 170 $g
 171 group name
 172 .TP
 173 $h
 174 hostname
 175 .TP
 176 $i
 177 client's ip, without port
 178 .TP
 179 $s
 180 server name (this can be the hostname)
 181 .TP
 182 $u
 183 user name (if guest, it is the user that guest is running
 184 as)
 185 .TP
 186 $v
 187 volume name (either ADEID_NAME or basename of path)
 188 .TP
 189 $z
 190 appletalk zone (may not exist)
 191 .TP
 192 $$
 193 prints dollar sign ($)
 194 .PP
 195 When using variable substitution in the volume name, always keep in
 196 mind, not to exceed the 27 characters limit
 197 .PP
 198 \fBUsing variable substitution when defining volumes\fR
 199 .PP
 200 .nf
 201 /home/groups/$g "Groupdir for $g"
 202 ~ "$f is the best one"
 203 .fi
 204
 205 We define "groupdirs" for each primary
 206 group and use a personalized server name for homedir shares.
 207 .SH "CNID BACKENDS"
 208 The AFP protocol mostly refers to files and directories by ID and
 209 not by name. Netatalk needs a way to store these ID's in a persistent way,
 210 to achieve this several different CNID backends are available. The CNID
 211 Databases are by default located in the \fB.AppleDB\fR
 212 folder in the volume root.
 213 .TP
 214 cdb
 215 "Concurrent database", backend is based on Sleepycat's Berkely
 216 DB. With this backend several afpd deamons access
 217 the CNID database directly. Berkeley DB locking is used to
 218 synchronize access, if more than one afpd process
 219 is active for a volume. The drawback is, that the crash of a single
 220 afpd process might corrupt the database.
 221 .TP
 222 dbd
 223 Access to the CNID database is restricted to the
 224 cnid_metad daemon process.
 225 afpd processes communicate with the daemon for
 226 database reads and updates. If built with Berkeley DB transactions
 227 the probability for database corruption is practically zero, but
 228 performance can be slower than with \fBcdb\fR
 229 .TP
 230 last
 231 This backend is an exception, in terms of ID persistency. ID's
 232 are only valid for the current session. This is basically what
 233 afpd did in the 1.5 (and 1.6) versions. This
 234 backend is still available, as it is useful for e.g. sharing
 235 cdroms.
 236
 237 \fBWarning\fR: It is
 238 \fINOT\fR recommended to use this backend for volumes
 239 anymore, as afpd now relies heavily on a
 240 persistent ID database. Aliases will likely not work and filename
 241 mangling is not supported.
 242 .PP
 243 Even though ./configure \-\-help might show that
 244 there are other CNID backends available, be warned those are likely broken
 245 or mainly used for testing. Don't use them unless you know what you're
 246 doing, they may be removed without further notice from future
 247 versions.
 248 .SH "CHARSET OPTIONS"
 249 With OS X Apple introduced the AFP3 protocol. One of the most
 250 important changes was that AFP3 uses unicode names encoded as UTF\-8
 251 decomposed. Previous AFP/OS versions used codepages, like MacRoman,
 252 MacCentralEurope, etc.
 253 .PP
 254 afpd needs a way to preserve extended macintosh
 255 characters, or characters illegal in unix filenames, when saving files on
 256 a unix filesystem. Earlier versions used the the so called CAP encoding.
 257 An extended character (>0x7F) would be converted to a :xx sequence,
 258 e.g. the Apple Logo (MacRoman: 0XF0) was saved as \fB:f0\fR.
 259 Some special characters will be converted as to :xx notation as well.
 260 \&'\fB/\fR' will be encoded to \fB:2f\fR, if
 261 \fB\-usedots\fR is not specified, a leading dot
 262 \&'\fB.\fR' will be encoded as \fB:2e\fR.
 263 .PP
 264 This version now uses UTF\-8 as the default encoding for names.
 265 Special characters, like '\fB/\fR' and a leading
 266 \&'\fB.\fR' will still be CAP style encoded .
 267 .PP
 268 The \fB\-volcharset\fR option will allow you to select
 269 another volume encoding. E.g. for western users another useful setting
 270 could be \-volcharset ISO\-8859\-15. apfd will accept any
 271 \fBiconv\fR(1) provided charset. If a character cannot be converted
 272 from the mac codepage to the selected volcharset, afpd will save it as a
 273 CAP encoded character. For AFP3 clients, afpd will
 274 convert the UTF\-8 character to \fB\-maccharset\fR first. If this
 275 conversion fails, you'll receive a \-50 error on the mac.
 276 .PP
 277 \fINote\fR: Whenever you can, please stick with the
 278 default UTF\-8 volume format.
 279 .SH "COMPATIBILITY WITH EARLIER VERSIONS"
 280 To use a volume created with an earlier afpd
 281 version, you'll have to specify the following options:
 282 .PP
 283 \fBuse a 1.x style volume\fR
 284 .PP
 285 .nf
 286 /path/to/volume "Volname" adouble:v1 volcharset:ASCII
 287 .fi
 288 .PP
 289 In case you used an NLS you could try using a compatible iconv
 290 charset for \fB\-volcharset\fR.
 291 .PP
 292 \fBuse a 1.x style volume, created with maccode.iso8859\-1\fR
 293 .PP
 294 .nf
 295 /path/to/volume "Volname" adouble:v1 volcharset:ISO\-8859\-1
 296 .fi
 297 .PP
 298 You should consider converting old style volumes to the new
 299 UTF\-8/AD2 format. The safest way to do this, is to create a new volume
 300 with the default options and copy the files between this volumes with a
 301 mac.
 302 .PP
 303 \fINote\fR: Using above example options will allow
 304 you to downgrade to 1.x netatalk again.
 305 .PP
 306 \fINote\fR: Some 1.x NLS files used non standard
 307 mappings, e.g. \fBmaccode.iso8859\-1.adapted\fR. This is not
 308 supported anymore. You'll have to copy the contents of those volumes files
 309 to a Mac and then back to the netatalk server, preferably to an UTF\-8
 310 volume.
 311 .SH "ADVANCED OPTIONS"
 312 The following options should only be used after serious
 313 consideration. Be sure you fully understood the, sometimes complex,
 314 consequences, before using them.
 315 .TP
 316 casefold:\fB[option]\fR
 317 The casefold option handles, if the case of filenames should
 318 be changed. The available options are:
 319
 320 \fBtolower\fR \- Lowercases names in both
 321 directions.
 322
 323 \fBtoupper\fR \- Uppercases names in both
 324 directions.
 325
 326 \fBxlatelower\fR \- Client sees lowercase, server
 327 sees uppercase.
 328
 329 \fBxlateupper\fR \- Client sees uppercase, server
 330 sees lowercase.
 331 .TP
 332 options:[\fBoption\fR]
 333 This allows multiple options to be specified in a comma
 334 delimited format. The available options are:
 335 .RS
 336 .TP
 337 crlf
 338 Enables crlf translation for TEXT files, automatically
 339 converting macintosh line breaks into Unix ones. Use of this
 340 option might be dangerous since some older programs store
 341 binary data files as type "TEXT" when saving and switch the
 342 filetype in a second step. Afpd will
 343 potentially destroy such files when "erroneously" changing
 344 bytes in order to do line break translation.
 345 .TP
 346 dropbox
 347 Allows a volume to be declared as being a "dropbox."
 348 Note that netatalk must be compiled with dropkludge support
 349 for this to function. \fIWarning\fR: This
 350 option is deprecated and might not work as expected.
 351 .TP
 352 mswindows
 353 Forces filename restrictions imposed by MS WinXX.
 354 \fIWarning\fR: This is \fINOT\fR
 355 recommened for volumes mainly used by Macs. Please make sure
 356 you fully understand this option before using it.
 357 .TP
 358 noadouble
 359 Forces afpd to not create
 360 \&.AppleDouble directories unless macintosh metadata needs to be
 361 written. This option is only useful if you want to share files
 362 mostly used NOT by macs, causing afpd to
 363 not automatically create .AppleDouble subdirs containing AD
 364 header files in every directory it enters (which will it do by
 365 default).
 366
 367 In case, you save or change files from mac clients, AD
 368 metadata files have to be written even in case you set this
 369 option. So you can't avoid the creation of .AppleDouble
 370 directories and its contents when you give macs write access
 371 to a share and they make use of it.
 372
 373 Try to avoid \fBnoadouble\fR whenever
 374 possible.
 375 .TP
 376 nodev
 377 always use 0 for device number, helps when the device
 378 number is not constant across a reboot, cluster, ...
 379 .TP
 380 nofileid
 381 don't advertise createfileid, resolveid, deleteid
 382 calls.
 383 .TP
 384 nohex
 385 Disables :hex translations for anything except dot
 386 files. This option makes the \fB'/\fR' character
 387 illegal.
 388 .TP
 389 prodos
 390 Provides compatibility with Apple II clients.
 391 .TP
 392 nostat
 393 don't stat volume path when enumerating volumes list,
 394 useful for automounting or volumes created by a preexec
 395 script.
 396 .TP
 397 upriv
 398 use AFP3 unix privileges. Become familiar with the new
 399 "unix privileges" AFP permissions concepts in MacOS X before
 400 using this option.
 401 .RE
 402 .SH "SEE ALSO"
 403 \fBafpd.conf\fR(5), \fBafpd\fR(8)
 404