man/man5/AppleVolumes.default.5.tmpl

   1 '\" t
   2 .\"     Title: AppleVolumes.default
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
   5 .\"      Date: 02 Octobre 2009
   6 .\"    Manual: Netatalk 2.1
   7 .\"    Source: Netatalk 2.1
   8 .\"  Language: English
   9 .\"
  10 .TH "APPLEVOLUMES\&.DEFAU" "5" "02 Octobre 2009" "Netatalk 2.1" "Netatalk 2.1"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 AppleVolumes.default \- Configuration file used by \fBafpd\fR(8) to determine the shares made available through Appletalk
  23 .SH "DESCRIPTION"
  24 .PP
  25 :ETCDIR:/AppleVolumes\&.default
  26 is the configuration file used by
  27 \fBafpd\fR
  28 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\&. Newline escaping is supported\&. The configuration lines are composed like:
  29 .PP
  30 path
  31 \fI[ volume name ] [ options ]\fR
  32 .PP
  33 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\&.
  34 .PP
  35 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
  36 \':\'
  37 character\&.
  38 .if n \{\
  39 .sp
  40 .\}
  41 .RS 4
  42 .it 1 an-trap
  43 .nr an-no-space-flag 1
  44 .nr an-break-flag 1
  45 .br
  46 .ps +1
  47 \fBNote\fR
  48 .ps -1
  49 .br
  50 .PP
  51 Each volume has to be configured on a
  52 \fBsingle\fR
  53 line\&. Though newline escaping is supported\&.
  54 .sp .5v
  55 .RE
  56 .PP
  57 The possible options and their meanings are:
  58 .PP
  59 adouble:\fI[v1|v2|osx]\fR
  60 .RS 4
  61 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
  62 .if n \{\
  63 .sp
  64 .\}
  65 .RS 4
  66 .it 1 an-trap
  67 .nr an-no-space-flag 1
  68 .nr an-break-flag 1
  69 .br
  70 .ps +1
  71 \fBNote\fR
  72 .ps -1
  73 .br
  74 Using
  75 \fBadouble:osx\fR
  76 is
  77 \fBnot\fR
  78 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
  79 .sp .5v
  80 .RE
  81 .RE
  82 .PP
  83 allow:\fI[users/groups]\fR
  84 .RS 4
  85 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
  86 .RE
  87 .PP
  88 deny:\fI[users/groups]\fR
  89 .RS 4
  90 The deny option specifies users and groups who are not allowed access to the share\&. It follows the same format as the allow option\&.
  91 .RE
  92 .PP
  93 allowed_hosts:\fI[IPv4 host address/IPv4 netmask bits[, \&.\&.\&. ]]\fR
  94 .RS 4
  95 Only listed hosts and networks are allowed, all others are rejected\&. Example: allowed_hosts:10\&.1\&.0\&.0/16,10\&.2\&.1\&.100
  96 .RE
  97 .PP
  98 denied_hosts:\fI[IPv4 host address/IPv4 netmask bits[, \&.\&.\&.]]\fR
  99 .RS 4
 100 Listed hosts and nets are rejected, all others are allowed\&. Example: denied_hosts: 192\&.168\&.100/24,10\&.1\&.1\&.1
 101 .RE
 102 .PP
 103 cnidscheme:\fI[backend]\fR
 104 .RS 4
 105 set the CNID backend to be used for the volume, default is [:DEFAULT_CNID_SCHEME:] available schemes: [:COMPILED_BACKENDS:]
 106 .RE
 107 .PP
 108 dbpath:\fI[path]\fR
 109 .RS 4
 110 Sets the database information to be stored in path\&. You have to specifiy a writable location, even if the volume is read only\&.
 111 .RE
 112 .PP
 113 ea:\fI[ad|solaris]\fR
 114 .RS 4
 115 Specify the format of the metadata files which are used for saving Extended Attributes\&.
 116 \fBad\fR
 117 is the default and stores the EAs inside the
 118 \&.AppleDouble
 119 directories\&.
 120 \fBsolaris\fR
 121 uses native
 122 \fI[Open]Solaris\fR
 123 EAs if available\&.
 124 .RE
 125 .PP
 126 maccharset:\fI[charset]\fR
 127 .RS 4
 128 specifies the mac client codepage for this Volume, e\&.g\&. "MAC_ROMAN", "MAC_CYRILLIC"\&. If not specified the setting from
 129 afpd\&.conf
 130 is inherited\&. This setting is only required if you need volumes, where the mac codepage differs from the one globally set in
 131 afpd\&.conf\&.
 132 .RE
 133 .PP
 134 options:\fI[option]\fR
 135 .RS 4
 136 This allows multiple options to be specified in a comma delimited format\&. The available options are:
 137 .PP
 138 acls
 139 .RS 4
 140 Enable ACLs on this volume\&. Requires a
 141 \fINFSv4 ACLs\fR
 142 compatible filesystem (e\&.g\&. ZFS) and an ACL API compatible to *Solaris\&. In other words: this requires Solaris, Opensolaris or a derived distribution\&.
 143 .RE
 144 .PP
 145 tm
 146 .RS 4
 147 Enable Time Machine suport for this volume\&.
 148 .RE
 149 .PP
 150 invisibledots
 151 .RS 4
 152 Use with
 153 \fBusedots\fR: make dot files invisible\&.
 154 .RE
 155 .PP
 156 limitsize
 157 .RS 4
 158 Limit disk size reporting to 2GB\&. This can be used for older Macintoshes using newer Appleshare clients\&.
 159 .RE
 160 .PP
 161 preexec_close
 162 .RS 4
 163 a non\-zero return code from preexec close the volume being immediately, preventing clients to mount/see the volume in question\&.
 164 .RE
 165 .PP
 166 ro
 167 .RS 4
 168 Specifies the share as being read only for all users\&. The \&.AppleDB directory has to be writeable, you can use the
 169 \fB\-dbpath\fR
 170 option to relocate it\&.
 171 .RE
 172 .PP
 173 root_preexec_close
 174 .RS 4
 175 a non\-zero return code from root_preexec closes the volume immediately, preventing clients to mount/see the volume in question\&.
 176 .RE
 177 .PP
 178 upriv
 179 .RS 4
 180 use AFP3 unix privileges\&. Become familiar with the new "unix privileges" AFP permissions concepts in MacOS X before using this option\&. See also:
 181 \fBperm|fperm|dperm\fR\&.
 182 .RE
 183 .PP
 184 usedots
 185 .RS 4
 186 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\&. See also
 187 \fBinvisibledots\fR\&.
 188 .RE
 189 .RE
 190 .PP
 191 password:\fI[password]\fR
 192 .RS 4
 193 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)\&.
 194 .RE
 195 .PP
 196 perm|fperm|dperm:[mode]
 197 .RS 4
 198 Add(or) with the client requested permissions:
 199 \fBperm\fR
 200 affects files and directories,
 201 \fBfperm\fR
 202 is for files only,
 203 \fBdperm\fR
 204 is for directories only\&. Use with
 205 \fBoptions:upriv\fR\&.
 206 .PP
 207 \fBExample.\ \&Volume for a collaborative workgroup\fR
 208 .sp
 209 .if n \{\
 210 .RS 4
 211 .\}
 212 .nf
 213 /path/to/volume "Workgroup" options:upriv dperm:0770 fperm:0660
 214 .fi
 215 .if n \{\
 216 .RE
 217 .\}
 218 .RE
 219 .PP
 220 preexec:\fI[command]\fR
 221 .RS 4
 222 command to be run when the volume is mounted, ignored for user defined volumes
 223 .RE
 224 .PP
 225 postexec:\fI[command]\fR
 226 .RS 4
 227 command to be run when the volume is closed, ignored for user defined volumes
 228 .RE
 229 .PP
 230 root_preexec:\fI[command]\fR
 231 .RS 4
 232 command to be run as root when the volume is mounted, ignored for user defined volumes
 233 .RE
 234 .PP
 235 root_postexec:\fI[command]\fR
 236 .RS 4
 237 command to be run as root when the volume is closed, ignored for user defined volumes
 238 .RE
 239 .PP
 240 rolist:[\fBusers/groups\fR]
 241 .RS 4
 242 Allows certain users and groups to have read\-only access to a share\&. This follows the allow option format\&.
 243 .RE
 244 .PP
 245 rwlist:\fI[users/groups]\fR
 246 .RS 4
 247 Allows certain users and groups to have read/write access to a share\&. This follows the allow option format\&.
 248 .RE
 249 .PP
 250 veto:\fI[vetoed name]\fR
 251 .RS 4
 252 hide files and directories,where the path matches one of the \'/\' delimited vetoed names\&. Matches are partial, e\&.g\&. path is
 253 /abc/def/file
 254 and veto:/abc/ will hide the file\&.
 255 .RE
 256 .PP
 257 volcharset:\fI[charset]\fR
 258 .RS 4
 259 specifies the volume codepage, e\&.g\&. "UTF8", "UTF8\-MAC", "ISO\-8859\-15"\&. Defaults to "UTF8"\&.
 260 .RE
 261 .SH "VARIABLE SUBSTITUTIONS"
 262 .PP
 263 You can use variables in both volume path and volume name\&.
 264 .sp
 265 .RS 4
 266 .ie n \{\
 267 \h'-04' 1.\h'+01'\c
 268 .\}
 269 .el \{\
 270 .sp -1
 271 .IP "  1." 4.2
 272 .\}
 273 if you specify an unknown variable, it will not get converted\&.
 274 .RE
 275 .sp
 276 .RS 4
 277 .ie n \{\
 278 \h'-04' 2.\h'+01'\c
 279 .\}
 280 .el \{\
 281 .sp -1
 282 .IP "  2." 4.2
 283 .\}
 284 if you specify a known variable, but that variable doesn\'t have a value, it will get ignored\&.
 285 .RE
 286 .PP
 287 The variables which can be used for substitutions are:
 288 .PP
 289 $b
 290 .RS 4
 291 basename
 292 .RE
 293 .PP
 294 $c
 295 .RS 4
 296 client\'s ip or appletalk address
 297 .RE
 298 .PP
 299 $d
 300 .RS 4
 301 volume pathname on server
 302 .RE
 303 .PP
 304 $f
 305 .RS 4
 306 full name (contents of the gecos field in the passwd file)
 307 .RE
 308 .PP
 309 $g
 310 .RS 4
 311 group name
 312 .RE
 313 .PP
 314 $h
 315 .RS 4
 316 hostname
 317 .RE
 318 .PP
 319 $i
 320 .RS 4
 321 client\'s ip, without port
 322 .RE
 323 .PP
 324 $s
 325 .RS 4
 326 server name (this can be the hostname)
 327 .RE
 328 .PP
 329 $u
 330 .RS 4
 331 user name (if guest, it is the user that guest is running as)
 332 .RE
 333 .PP
 334 $v
 335 .RS 4
 336 volume name (either ADEID_NAME or basename of path)
 337 .RE
 338 .PP
 339 $z
 340 .RS 4
 341 appletalk zone (may not exist)
 342 .RE
 343 .PP
 344 $$
 345 .RS 4
 346 prints dollar sign ($)
 347 .RE
 348 .PP
 349 When using variable substitution in the volume name, always keep in mind, not to exceed the 27 characters limit
 350 .PP
 351 \fBExample.\ \&Using variable substitution when defining volumes\fR
 352 .PP
 353 .if n \{\
 354 .RS 4
 355 .\}
 356 .nf
 357 /home/groups/$g "Groupdir for $g"
 358 ~ "$f is the best one"
 359 .fi
 360 .if n \{\
 361 .RE
 362 .\}
 363 .sp
 364 We define "groupdirs" for each primary group and use a personalized server name for homedir shares\&.
 365 .SH "CNID BACKENDS"
 366 .PP
 367 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
 368 \&.AppleDB
 369 folder in the volume root\&.
 370 .PP
 371 cdb
 372 .RS 4
 373 "Concurrent database", backend is based on Sleepycat\'s Berkely DB\&. With this backend several
 374 \fBafpd\fR
 375 deamons access the CNID database directly\&. Berkeley DB locking is used to synchronize access, if more than one
 376 \fBafpd\fR
 377 process is active for a volume\&. The drawback is, that the crash of a single
 378 \fBafpd\fR
 379 process might corrupt the database\&.
 380 .RE
 381 .PP
 382 dbd
 383 .RS 4
 384 Access to the CNID database is restricted to the
 385 \fBcnid_metad\fR
 386 daemon process\&.
 387 \fBafpd\fR
 388 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
 389 \fBcdb\fR
 390 .RE
 391 .PP
 392 last
 393 .RS 4
 394 This backend is an exception, in terms of ID persistency\&. ID\'s are only valid for the current session\&. This is basically what
 395 \fBafpd\fR
 396 did in the 1\&.5 (and 1\&.6) versions\&. This backend is still available, as it is useful for e\&.g\&. sharing cdroms\&.
 397 .sp
 398 \fBWarning\fR: It is
 399 \fINOT\fR
 400 recommended to use this backend for volumes anymore, as
 401 \fBafpd\fR
 402 now relies heavily on a persistent ID database\&. Aliases will likely not work and filename mangling is not supported\&.
 403 .RE
 404 .PP
 405 Even though
 406 \fB\&./configure \-\-help\fR
 407 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\&.
 408 .SH "CHARSET OPTIONS"
 409 .PP
 410 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\&.
 411 .PP
 412 \fBafpd\fR
 413 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
 414 :f0\&. Some special characters will be converted as to :xx notation as well\&. \'/\' will be encoded to
 415 :2f, if
 416 \fB\-usedots\fR
 417 is not specified, a leading dot \'\&.\' will be encoded as
 418 :2e\&.
 419 .PP
 420 This version now uses UTF\-8 as the default encoding for names\&. Special characters, like \'/\' and a leading \'\&.\' will still be CAP style encoded \&.
 421 .PP
 422 The
 423 \fB\-volcharset\fR
 424 option will allow you to select another volume encoding\&. E\&.g\&. for western users another useful setting could be \-volcharset ISO\-8859\-15\&.
 425 \fBapfd\fR
 426 will accept any
 427 \fBiconv\fR(1)
 428 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,
 429 \fBafpd\fR
 430 will convert the UTF\-8
 431 character to
 432 \fB\-maccharset\fR
 433 first\&. If this conversion fails, you\'ll receive a \-50 error on the mac\&.
 434 .PP
 435 \fINote\fR: Whenever you can, please stick with the default UTF\-8 volume format\&.
 436 .SH "COMPATIBILITY WITH EARLIER VERSIONS"
 437 .PP
 438 To use a volume created with an earlier
 439 \fBafpd\fR
 440 version, you\'ll have to specify the following options:
 441 .PP
 442 \fBExample.\ \&use a 1.x style volume\fR
 443 .sp
 444 .if n \{\
 445 .RS 4
 446 .\}
 447 .nf
 448 /path/to/volume "Volname" adouble:v1 volcharset:ASCII
 449 .fi
 450 .if n \{\
 451 .RE
 452 .\}
 453 .PP
 454 In case you used an NLS you could try using a compatible iconv charset for
 455 \fB\-volcharset\fR\&.
 456 .PP
 457 \fBExample.\ \&use a 1.x style volume, created with maccode.iso8859-1\fR
 458 .sp
 459 .if n \{\
 460 .RS 4
 461 .\}
 462 .nf
 463 /path/to/volume "Volname" adouble:v1 volcharset:ISO\-8859\-1
 464 .fi
 465 .if n \{\
 466 .RE
 467 .\}
 468 .PP
 469 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\&.
 470 .PP
 471 \fINote\fR: Using above example options will allow you to downgrade to 1\&.x netatalk again\&.
 472 .PP
 473 \fINote\fR: Some 1\&.x NLS files used non standard mappings, e\&.g\&.
 474 maccode\&.iso8859\-1\&.adapted\&. Three 1\&.x CAP double\-byte maccharsets are incompatible to netatalk 2\&.x; "MAC_CHINESE_TRAD", "MAC_JAPANESE" and "MAC_KOREAN"\&. These are 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\&.
 475 .SH "ADVANCED OPTIONS"
 476 .PP
 477 The following options should only be used after serious consideration\&. Be sure you fully understood the, sometimes complex, consequences, before using them\&.
 478 .PP
 479 casefold:\fB[option]\fR
 480 .RS 4
 481 The casefold option handles, if the case of filenames should be changed\&. The available options are:
 482 .sp
 483 \fBtolower\fR
 484 \- Lowercases names in both directions\&.
 485 .sp
 486 \fBtoupper\fR
 487 \- Uppercases names in both directions\&.
 488 .sp
 489 \fBxlatelower\fR
 490 \- Client sees lowercase, server sees uppercase\&.
 491 .sp
 492 \fBxlateupper\fR
 493 \- Client sees uppercase, server sees lowercase\&.
 494 .RE
 495 .PP
 496 options:[\fBoption\fR]
 497 .RS 4
 498 This allows multiple options to be specified in a comma delimited format\&. The available options are:
 499 .PP
 500 nocnidcache
 501 .RS 4
 502 If set
 503 \fBafpd\fR
 504 doesn\'t store the ID information in AppleDouble V2 header files\&. As these IDs are used for caching and as a database backup, this option normally shouldn\'t be set\&.
 505 .RE
 506 .PP
 507 crlf
 508 .RS 4
 509 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\&.
 510 \fBAfpd\fR
 511 will potentially destroy such files when "erroneously" changing bytes in order to do line break translation\&.
 512 .RE
 513 .PP
 514 dropbox
 515 .RS 4
 516 Allows a volume to be declared as being a "dropbox\&." Note that netatalk must be compiled with dropkludge support for this to function\&.
 517 \fIWarning\fR: This option is deprecated and might not work as expected\&.
 518 .RE
 519 .PP
 520 mswindows
 521 .RS 4
 522 Forces filename restrictions imposed by MS WinXX\&.
 523 \fIWarning\fR: This is
 524 \fINOT\fR
 525 recommened for volumes mainly used by Macs\&. Please make sure you fully understand this option before using it\&.
 526 .if n \{\
 527 .sp
 528 .\}
 529 .RS 4
 530 .it 1 an-trap
 531 .nr an-no-space-flag 1
 532 .nr an-break-flag 1
 533 .br
 534 .ps +1
 535 \fBWarning\fR
 536 .ps -1
 537 .br
 538 This option breaks direct saving to netatalk volumes from some applications, i\&.e\&. OfficeX\&.
 539 .sp .5v
 540 .RE
 541 .RE
 542 .PP
 543 noadouble
 544 .RS 4
 545 Forces
 546 \fBafpd\fR
 547 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
 548 \fBafpd\fR
 549 to not automatically create \&.AppleDouble subdirs containing AD header files in every directory it enters (which will it do by default)\&.
 550 .sp
 551 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\&.
 552 .sp
 553 Try to avoid
 554 \fBnoadouble\fR
 555 whenever possible\&.
 556 .RE
 557 .PP
 558 nodev
 559 .RS 4
 560 always use 0 for device number, helps when the device number is not constant across a reboot, cluster, \&.\&.\&.
 561 .RE
 562 .PP
 563 nofileid
 564 .RS 4
 565 don\'t advertise createfileid, resolveid, deleteid calls\&.
 566 .RE
 567 .PP
 568 nohex
 569 .RS 4
 570 Disables :hex translations for anything except dot files\&. This option makes the
 571 \'/\' character illegal\&.
 572 .RE
 573 .PP
 574 nostat
 575 .RS 4
 576 don\'t stat volume path when enumerating volumes list, useful for automounting or volumes created by a preexec script\&.
 577 .RE
 578 .PP
 579 prodos
 580 .RS 4
 581 Provides compatibility with Apple II clients\&.
 582 .RE
 583 .RE
 584 .SH "SEE ALSO"
 585 .PP
 586 \fBafpd.conf\fR(5),
 587 \fBafpd\fR(8)