man/man5/AppleVolumes.default.5.tmpl

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