'\" t .\" Title: AppleVolumes.default .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 22 Apr 2010 .\" Manual: Netatalk 2.2 .\" Source: Netatalk 2.2 .\" Language: English .\" .TH "APPLEVOLUMES\&.DEFAU" "5" "22 Apr 2010" "Netatalk 2.2" "Netatalk 2.2" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" AppleVolumes.default, AppleVolumes.system, AppleVolumes \- Configuration file used by \fBafpd\fR(8) to determine the shares made available through AFP and specify file name extension mappings\&. .SH "SYNOPSIS" .HP \w'\fB:ETCDIR:/AppleVolumes\&.default\fR\fB\fR\fB:ETCDIR:/AppleVolumes\&.system\fR\fB\fR\fB~/AppleVolumes\fR\fB\fR\fB~/\&.AppleVolumes\fR\fB\fR\fB~/applevolumes\fR\fB\fR\fB~/\&.applevolumes\fR\fB\fR\ 'u \fB:ETCDIR:/AppleVolumes\&.default\fR\fB\fR .br \fB:ETCDIR:/AppleVolumes\&.system\fR\fB\fR .br \fB~/AppleVolumes\fR\fB\fR .br \fB~/\&.AppleVolumes\fR\fB\fR .br \fB~/applevolumes\fR\fB\fR .br \fB~/\&.applevolumes\fR\fB\fR .SH "DESCRIPTION" .PP :ETCDIR:/AppleVolumes\&.system and one of :ETCDIR:/AppleVolumes\&.default, ~/AppleVolumes, ~/\&.AppleVolumes, ~/applevolumes, or ~/\&.applevolumes are the configuration files used by \fBafpd\fR to determine what portions of the file system will be shared via Apple Filing Protocol, as well as their behaviour\&. .PP Any line not prefixed with # is interpreted\&. Newline escaping is supported\&. The configuration lines are composed like: .PP path \fI[ volume name ] [ options ]\fR .PP \&.extension \fI[ type [ creator ] ]\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 volumename is unspecified, the last component of pathname is used\&. No two volumes may have the same name\&. If there are spaces in the name, it should be in quotes (i\&.e\&. "File Share")\&. The volume name cannot contain the \':\' character\&. The volume name is mangled if it is very long\&. Mac codepage volume name is limited to 27 characters\&. UTF8\-MAC volume name is limited to \-volnamelen parameter in afpd\&.conf .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP Each volume has to be configured on a \fBsingle\fR line\&. Though newline escaping is supported\&. .sp .5v .RE .PP The leading\-dot lines specify file name extension mappings\&. The extension \'\&.\' sets the default creator and type for otherwise untyped Unix files\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP File name extension mapping is useful for Mac OS 9 and earlier\&. But it should not use for Mac OS X\&. .sp .5v .RE .PP It is possible to specify default options for all volumes with a \fI:DEFAULT: \fRline preceeding these volume definitions: .PP \fBExample.\ \&:DEFAULT: configuration line\fR .sp .if n \{\ .RS 4 .\} .nf :DEFAULT: options:upriv,usedots dbpath:/var/dbd/AppleDB/$v dperm:0775 fperm:0664 .fi .if n \{\ .RE .\} .PP The possible options and their meanings are: .PP adouble:\fI[v1|v2|osx]\fR .RS 4 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 10\&.3\&.x uses, is also supported\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br \fBadouble:osx\fR \fBcannot\fR be treated normally any longer\&. Its only aim was 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\&. AppleDouble file of Mac OS X 10\&.6 is incompatible to V1 and V2\&. .sp .5v .RE .RE .PP volsizelimit:\fIsize in MiB\fR .RS 4 Useful for TimeMachine: limits the reported volume size, thus preventing TM from using the whole real disk space for backup\&. Example: "volsizelimit:1000" would limit the reported disk space to 1 GB\&. .RE .PP allow:\fI[users/groups]\fR .RS 4 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 .RE .PP deny:\fI[users/groups]\fR .RS 4 The deny option specifies users and groups who are not allowed access to the share\&. It follows the same format as the allow option\&. .RE .PP allowed_hosts:\fI[IP host address/IP netmask bits[, \&.\&.\&. ]]\fR .RS 4 Only listed hosts and networks are allowed, all others are rejected\&. The network address may be specified either in dotted\-decimal format for IPv4 or in hexadecimal format for IPv6\&. .sp Example: allowed_hosts:10\&.1\&.0\&.0/16,10\&.2\&.1\&.100,2001:0db8:1234::/48 .RE .PP denied_hosts:\fI[IP host address/IP netmask bits[, \&.\&.\&.]]\fR .RS 4 Listed hosts and nets are rejected, all others are allowed\&. .sp Example: denied_hosts: 192\&.168\&.100/24,10\&.1\&.1\&.1,2001:db8::1428:57ab .RE .PP cnidscheme:\fI[backend]\fR .RS 4 set the CNID backend to be used for the volume, default is [:DEFAULT_CNID_SCHEME:] available schemes: [:COMPILED_BACKENDS:] .RE .PP dbpath:\fI[path]\fR .RS 4 Sets the database information to be stored in path\&. You have to specifiy a writable location, even if the volume is read only\&. .RE .PP cnidserver:\fI[fqdn|IP[:port]]\fR .RS 4 Query this servername or IP address (default:\fIlocalhost\fR) and port (default: \fI4700\fR) for CNIDs\&. Only used with CNID backend "\fIdbd\fR"\&. This option here overrides any setting from afpd\&.conf:\fBcnidserver\fR\&. .RE .PP ea:\fI[none|auto|sys|ad]\fR .RS 4 Specify how Extended Attributes are stored\&. \fBauto\fR is the default\&. .PP auto .RS 4 Try \fBsys\fR (by setting an EA on the shared directory itself), fallback to \fBad\fR\&. Requires writeable volume for perfoming test\&. \fBoptions:ro\fR overwrites \fBauto\fR with \fBnone\fR\&. Use explicit \fBea:sys|ad\fR for read\-only volumes where appropiate\&. .RE .PP sys .RS 4 Use filesystem Extended Attributes\&. .RE .PP ad .RS 4 Use files in \fI\&.AppleDouble\fR directories\&. .RE .PP none .RS 4 No Extended Attributes support\&. .RE .RE .PP maccharset:\fI[charset]\fR .RS 4 specifies the mac client codepage for this Volume, e\&.g\&. "MAC_ROMAN", "MAC_CYRILLIC"\&. If not specified the setting from afpd\&.conf is inherited\&. This setting is only required if you need volumes, where the mac codepage differs from the one globally set in afpd\&.conf\&. .RE .PP options:\fI[option]\fR .RS 4 This allows multiple options to be specified in a comma delimited format\&. The available options are: .PP tm .RS 4 Enable Time Machine suport for this volume\&. .RE .PP invisibledots .RS 4 Use with \fBusedots\fR: make dot files invisible\&. .RE .PP limitsize .RS 4 Limit disk size reporting to 2GB\&. This can be used for older Macintoshes using newer Appleshare clients\&. .RE .PP preexec_close .RS 4 a non\-zero return code from preexec close the volume being immediately, preventing clients to mount/see the volume in question\&. .RE .PP ro .RS 4 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\&. Overwrites \fBea:auto\fR with \fBea:none\fR .RE .PP root_preexec_close .RS 4 a non\-zero return code from root_preexec closes the volume immediately, preventing clients to mount/see the volume in question\&. .RE .PP upriv .RS 4 use AFP3 unix privileges\&. Become familiar with the new "unix privileges" AFP permissions concepts in MacOS X before using this option\&. See also: \fBperm|fperm|dperm\fR\&. .RE .PP usedots .RS 4 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 \fBinvisibledots\fR\&. .RE .RE .PP password:\fI[password]\fR .RS 4 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)\&. .RE .PP perm|fperm|dperm:\fI[mode]\fR .RS 4 Add(or) with the client requested permissions: \fBperm\fR affects files and directories, \fBfperm\fR is for files only, \fBdperm\fR is for directories only\&. Use with \fBoptions:upriv\fR\&. .PP \fBExample.\ \&Volume for a collaborative workgroup\fR .sp .if n \{\ .RS 4 .\} .nf /path/to/volume "Workgroup" options:upriv dperm:0770 fperm:0660 .fi .if n \{\ .RE .\} .RE .PP umask:\fI[mode]\fR .RS 4 set perm mask\&. Use with \fBoptions:upriv\fR\&. .RE .PP preexec:\fI[command]\fR .RS 4 command to be run when the volume is mounted, ignored for user defined volumes .RE .PP postexec:\fI[command]\fR .RS 4 command to be run when the volume is closed, ignored for user defined volumes .RE .PP root_preexec:\fI[command]\fR .RS 4 command to be run as root when the volume is mounted, ignored for user defined volumes .RE .PP root_postexec:\fI[command]\fR .RS 4 command to be run as root when the volume is closed, ignored for user defined volumes .RE .PP rolist:[\fBusers/groups\fR] .RS 4 Allows certain users and groups to have read\-only access to a share\&. This follows the allow option format\&. .RE .PP rwlist:\fI[users/groups]\fR .RS 4 Allows certain users and groups to have read/write access to a share\&. This follows the allow option format\&. .RE .PP veto:\fI[vetoed name]\fR .RS 4 hide files and directories,where the path matches one of the \'/\' delimited vetoed names\&. Matches are partial, e\&.g\&. path is /abc/def/file and veto:/abc/ will hide the file\&. .RE .PP volcharset:\fI[charset]\fR .RS 4 specifies the volume codepage, e\&.g\&. "UTF8", "UTF8\-MAC", "ISO\-8859\-15"\&. Defaults to "UTF8"\&. .RE .SH "VARIABLE SUBSTITUTIONS" .PP You can use variables in both volume path and volume name\&. .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} if you specify an unknown variable, it will not get converted\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} if you specify a known variable, but that variable doesn\'t have a value, it will get ignored\&. .RE .PP The variables which can be used for substitutions are: .PP $b .RS 4 basename .RE .PP $c .RS 4 client\'s ip or appletalk address .RE .PP $d .RS 4 volume pathname on server .RE .PP $f .RS 4 full name (contents of the gecos field in the passwd file) .RE .PP $g .RS 4 group name .RE .PP $h .RS 4 hostname .RE .PP $i .RS 4 client\'s ip, without port .RE .PP $s .RS 4 server name (this can be the hostname) .RE .PP $u .RS 4 user name (if guest, it is the user that guest is running as) .RE .PP $v .RS 4 volume name (either ADEID_NAME or basename of path) .RE .PP $z .RS 4 appletalk zone (may not exist) .RE .PP $$ .RS 4 prints dollar sign ($) .RE .PP \fBExample.\ \&Using variable substitution when defining volumes\fR .PP .if n \{\ .RS 4 .\} .nf /home/groups/$g "Groupdir for $g" ~ "$f is the best one" .fi .if n \{\ .RE .\} .sp We define "groupdirs" for each primary group and use a personalized server name for homedir shares\&. .SH "CNID BACKENDS" .PP 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 \&.AppleDB folder in the volume root\&. .PP cdb .RS 4 "Concurrent database", backend is based on Sleepycat\'s Berkely DB\&. With this backend several \fBafpd\fR deamons access the CNID database directly\&. Berkeley DB locking is used to synchronize access, if more than one \fBafpd\fR process is active for a volume\&. The drawback is, that the crash of a single \fBafpd\fR process might corrupt the database\&. .RE .PP dbd .RS 4 Access to the CNID database is restricted to the \fBcnid_metad\fR daemon process\&. \fBafpd\fR 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 .RE .PP last .RS 4 This backend is an exception, in terms of ID persistency\&. ID\'s are only valid for the current session\&. This is basically what \fBafpd\fR did in the 1\&.5 (and 1\&.6) versions\&. This backend is still available, as it is useful for e\&.g\&. sharing cdroms\&. .sp \fBWarning\fR: It is \fINOT\fR recommended to use this backend for volumes anymore, as \fBafpd\fR now relies heavily on a persistent ID database\&. Aliases will likely not work and filename mangling is not supported\&. .RE .PP Even though \fB\&./configure \-\-help\fR 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" .PP 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 \fBafpd\fR 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 :f0\&. Some special characters will be converted as to :xx notation as well\&. \'/\' will be encoded to :2f, if \fB\-usedots\fR is not specified, a leading dot \'\&.\' will be encoded as :2e\&. .PP This version now uses UTF\-8 as the default encoding for names\&. Special characters, like \'/\' and a leading \'\&.\' 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\&. \fBapfd\fR 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, \fBafpd\fR 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" .PP To use a volume created with an earlier \fBafpd\fR version, you\'ll have to specify the following options: .PP \fBExample.\ \&use a 1.x style volume\fR .sp .if n \{\ .RS 4 .\} .nf /path/to/volume "Volname" adouble:v1 volcharset:ASCII .fi .if n \{\ .RE .\} .PP In case you used an NLS you could try using a compatible iconv charset for \fB\-volcharset\fR\&. .PP \fBExample.\ \&use a 1.x style volume, created with maccode.iso8859-1\fR .sp .if n \{\ .RS 4 .\} .nf /path/to/volume "Volname" adouble:v1 volcharset:ISO\-8859\-1 .fi .if n \{\ .RE .\} .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\&. 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\&. .SH "ADVANCED OPTIONS" .PP The following options should only be used after serious consideration\&. Be sure you fully understood the, sometimes complex, consequences, before using them\&. .PP casefold:\fB[option]\fR .RS 4 The casefold option handles, if the case of filenames should be changed\&. The available options are: .sp \fBtolower\fR \- Lowercases names in both directions\&. .sp \fBtoupper\fR \- Uppercases names in both directions\&. .sp \fBxlatelower\fR \- Client sees lowercase, server sees uppercase\&. .sp \fBxlateupper\fR \- Client sees uppercase, server sees lowercase\&. .RE .PP options:[\fBoption\fR] .RS 4 This allows multiple options to be specified in a comma delimited format\&. The available options are: .PP caseinsensitive .RS 4 The underlying filesystem is case insensitive (only tested with JFS in OS2 mode)\&. .RE .PP crlf .RS 4 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\&. \fBAfpd\fR will potentially destroy such files when "erroneously" changing bytes in order to do line break translation\&. .RE .PP dropbox .RS 4 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\&. .RE .PP dropkludge .RS 4 same as "dropbox"\&. .RE .PP mswindows .RS 4 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBWarning\fR .ps -1 .br This option breaks direct saving to netatalk volumes from some applications, i\&.e\&. OfficeX\&. .sp .5v .RE .RE .PP noadouble .RS 4 Forces \fBafpd\fR 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 \fBafpd\fR to not automatically create \&.AppleDouble subdirs containing AD header files in every directory it enters (which will it do by default)\&. .sp 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\&. .sp Try to avoid \fBnoadouble\fR whenever possible\&. .RE .PP nocnidcache .RS 4 If set \fBafpd\fR 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\&. .RE .PP nodev .RS 4 always use 0 for device number, helps when the device number is not constant across a reboot, cluster, \&.\&.\&. .RE .PP nofileid .RS 4 don\'t advertise createfileid, resolveid, deleteid calls\&. .RE .PP nohex .RS 4 Disables :hex translations for anything except dot files\&. This option makes the \'/\' character illegal\&. .RE .PP nostat .RS 4 don\'t stat volume path when enumerating volumes list, useful for automounting or volumes created by a preexec script\&. .RE .PP prodos .RS 4 Provides compatibility with Apple II clients\&. (legacy) .RE .RE .SH "FILE NAME EXTENSION MAPPINGS" .PP \fBExample.\ \&Extension is jpg. Type is "JPEG". Creator is "ogle".\fR .sp .if n \{\ .RS 4 .\} .nf \&.jpg "JPEG" "ogle" .fi .if n \{\ .RE .\} .PP \fBExample.\ \&Extension is lzh. Type is "LHA ". Creator is not defined.\fR .sp .if n \{\ .RS 4 .\} .nf \&.lzh "LHA " .fi .if n \{\ .RE .\} .SH "SEE ALSO" .PP \fBafpd.conf\fR(5), \fBafpd\fR(8), \fBafp_ldap.conf\fR(5), \fBafp_acls\fR(8)