X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=man%2Fman5%2FAppleVolumes.default.5.tmpl;h=f9b0699584e65e90309fdd3d742c4397bfa14c31;hb=2cc69f27dd1782914303f8dfb3225558cf94277a;hp=8d116b438afbba4ac29d1b6971fbd58f024815b2;hpb=e770493d599b7da22b36536dc432293f96ed394e;p=netatalk.git diff --git a/man/man5/AppleVolumes.default.5.tmpl b/man/man5/AppleVolumes.default.5.tmpl index 8d116b43..f9b06995 100644 --- a/man/man5/AppleVolumes.default.5.tmpl +++ b/man/man5/AppleVolumes.default.5.tmpl @@ -1,204 +1,567 @@ -.\" $Id: AppleVolumes.default.5.tmpl,v 1.2.14.1 2003-11-30 22:07:36 rlewczuk Exp $ -.TH AppleVolumes.default 5 "20 September 2000" "netatalk 1.5" -.UC 4 -.SH NAME -AppleVolumes.default \- Configuration file used by \fBafpd\fR(8) -to determine the shares made available through Appletalk - -.SH DESCRIPTION -\fB:ETCDIR:/AppleVolumes.default\fR is the configuration file used -by afpd to determine what portions of the file system will be shared via -Appletalk, as well as their behaviors. - -Any line not prefixed with \fB#\fR is interpreted. The configuration lines -are composed like: - -.RS -.sp -.I path -.B [ -.I chooser name -.B ] [ -.I options -.B ] - -.sp -.RE -The path name must be a fully qualified path name, or a path name using -either the \fB~\fR shell shorthand or any of the substitution variables, -which are listed below. - -The chooser name is the name that appears in the Chooser on Macintoshes -to represent the appropriate share. If there are spaces in the name, it -should be in quotes (i.e. \fB"File Share"\fR). The chooser name may not -exceed 27 characters in length, and cannot contain the \fB:\fR character. - +'\" t +.\" Title: AppleVolumes.default +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.74.3 +.\" Date: 30 January 2009 +.\" Manual: Netatalk 2.0.5 +.\" Source: Netatalk 2.0.5 +.\" Language: English +.\" +.TH "APPLEVOLUMES\&.DEFAU" "5" "30 January 2009" "Netatalk 2.0.5" "Netatalk 2.0.5" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +AppleVolumes.default \- Configuration file used by \fBafpd\fR(8) to determine the shares made available through Appletalk +.SH "DESCRIPTION" +.PP +:ETCDIR:/AppleVolumes\&.default +is the configuration file used by +\fBafpd\fR +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: +.PP +path +\fI[ volume name ] [ options ]\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 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 +\':\' +character\&. +.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 possible options and their meanings are: - -.TP -.B allow:[users/groups] -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 \fB@\fR prefix. - -\fIExample:\fR \fBallow:user1,user2,@group\fR - -.TP -.B casefold:[option] -The casefold option handles how casenames should be mangled. The available -options are: - -\fBtolower\fR - Lowercases names in both directions. - -\fBtoupper\fR - Uppercases names in both directions. - -\fBxlatelower\fR - Client sees lowercase, server sees uppercase. - -\fBxlateupper\fR - Client sees uppercase, server sees lowercase. - -.TP -.B cnidscheme:[scheme] -Set the CNID database backend for the volume, default is [:DEFAULT_CNID_SCHEME:], -available backends are [:COMPLETED_BACKENDS:]. - -.TP -.B codepage:[nls file] -The codepage option loads a specific codepage from the nls directory. - -.TP -.B dbpath:[path] -Sets the database information to be stored in \fBpath\fR. - -.TP -.B deny:[users/groups] -The deny option specifies users and groups who are not allowed access -to the share. It follows the same format as the \fBallow\fR option. - -.TP -.B options:[option] -This allows multiple options to be specified in a comma delimited format. -The available options are: - -\fBcrlf\fR - Enables crlf translation for TEXT files. - -\fBdropbox\fR - Allows a volume to be declared as being a "dropbox." Note -that netatalk must be compiled with dropkludge support for this to -function. - -\fBlimitsize\fR - Hack for older Macintoshes using newer Appleshare -clients to limit the disk size reporting to 2 GB. - -\fBmswindows\fR - Forces filename restrictions imposed by MS WinXX, and -invokes the MS default codepage (iso8859-1) if one is not already -specified. - -\fBnoadouble\fR - Forces afpd to not create .AppleDouble unless a resource -fork needs to be created. - -\fBnofileid\fR - Don't advertise createfileid, resolveid and deleteid calls. - -\fBnohex\fR - Disables :hex translations for anything except dot files. -This option makes the \fB/\fR character illegal. - -\fBnostat\fR - Don't stat volume path when enumerating volumes list. - -\fBpreexec_close\fR - A non-zero return code from preexec close -the volume being mounted. - -\fBprodos\fR - Provides compatibility with Apple II clients. - -\fBro\fR - Specifies the share as being read only for all users. - -\fBroot_preexec_close\fR - A non-zero return code from root_preexec close -the volume being mounted. - -\fBusedots\fR - Don't do :hex translation for dot files. This makes all -files such as .Parent, .Apple* illegal. Dot files created on the server -side will be invisible to the client. - -\fBupriv\fR - Use UNIX privilege (AFP3x). - -.TP -.B password:[password] -This option allows you to set a volume password, which can be a maximum -of 8 characters long. - -.TP -.B postexec:[command] -Command to be run when the volume is closed, ignore for user defined volumes. - -.TP -.B preexec:[command] -Command to be run when the volume is mounted, ignore for user defined volumes. - -.TP -.B rolist:[users/groups] -Allows certain users and groups to have read-only access to a share. -This follows the \fBallow\fR option format. - -.TP -.B root_postexec:[command] -Command to be run as root when the volume is closed, ignore for user defined volumes. - -.TP -.B root_preexec:[command] -Command to be run as root when the volume is opened, ignore for user defined volumes. - -.TP -.B rwlist:[users/groups] -Allows certain users and groups to have read/write access to a share. -This follows the \fBallow\fR option format. - -.P -The variables which can be used for subsitutions are: - -.TP -.B $b -basename of path - -.TP -.B $c -client's ip or appletalk address - -.TP -.B $d +.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 uses currently (10\&.3\&.x), 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 +Using +\fBadouble:osx\fR +is +\fBnot\fR +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 +.sp .5v +.RE +.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[IPv4 host address/IPv4 netmask bits[, \&.\&.\&. ]]\fR +.RS 4 +Only listed hosts and networks are allowed, all others are rejected\&. Example: allowed_hosts:10\&.1\&.0\&.0/16,10\&.2\&.1\&.100 +.RE +.PP +denied_hosts:\fI[IPv4 host address/IPv4 netmask bits[, \&.\&.\&.]]\fR +.RS 4 +Listed hosts and nets are rejected, all others are allowed\&. Example: denied_hosts: 192\&.168\&.100/24,10\&.1\&.1\&.1 +.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 +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\&. +.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:[mode] +.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 +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 - -.TP -.B $f +.RE +.PP +$f +.RS 4 full name (contents of the gecos field in the passwd file) - -.TP -.B $g +.RE +.PP +$g +.RS 4 group name - -.TP -.B $h +.RE +.PP +$h +.RS 4 hostname - -.TP -.B $i -client IP without tcp port or appletalk network - -.TP -.B $s +.RE +.PP +$i +.RS 4 +client\'s ip, without port +.RE +.PP +$s +.RS 4 server name (this can be the hostname) - -.TP -.B $u +.RE +.PP +$u +.RS 4 user name (if guest, it is the user that guest is running as) - -.TP -.B $v +.RE +.PP +$v +.RS 4 volume name (either ADEID_NAME or basename of path) - -.TP -.B $z +.RE +.PP +$z +.RS 4 appletalk zone (may not exist) - -.TP -.B $$ -prints dollar sign (\fb$\fR) - -.SH SEE ALSO -afpd(8) +.RE +.PP +$$ +.RS 4 +prints dollar sign ($) +.RE +.PP +When using variable substitution in the volume name, always keep in mind, not to exceed the 27 characters limit +.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\&. This is 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 +cachecnid +.RS 4 +If set +\fBafpd\fR +uses the ID information stored in AppleDouble V2 header files to reduce database load\&. Don\'t set this option if the volume is modified by non AFP clients (NFS/SMB/local)\&. Defaults to off\&. +.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 +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 +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\&. +.RE +.RE +.SH "SEE ALSO" +.PP +\fBafpd.conf\fR(5), +\fBafpd\fR(8)