Merge master

[netatalk.git] / man / man5 / AppleVolumes.default.5.tmpl

'\" t
.\"     Title: AppleVolumes.default
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 30 Mar 2011
.\"    Manual: Netatalk 2.2
.\"    Source: Netatalk 2.2
.\"  Language: English
.\"
.TH "APPLEVOLUMES\&.DEFAU" "5" "30 Mar 2011" "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
searchdb
.RS 4
Use fast CNID database namesearch instead of slow recursive filesystem search\&. Relies on a consistent CNID database, ie Samba or local filesystem access lead to inaccurate or wrong results\&. Works only for "dbd" CNID db volumes\&.
.RE
.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
nonetids
.RS 4
Try to force ACL unawareness on the client\&.
.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\&. This should be set for OS X clients\&. Starting with Netatalk 2\&.1 it\'s part of the default config :DEFAULT: line\&. 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 names]\fR
.RS 4
hide files and directories,where the path matches one of the \'/\' delimited vetoed names\&. The veto string must always be terminated with a \'/\', eg\&. "veto1/", "veto1/veto2/"\&.
.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),
\fBcnid_metad\fR(8)