man/man5/AppleVolumes.default.5.tmpl

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