.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
-behavior. Any line not prefixed with # is interpreted. The configuration
-lines are composed like:
+portions of the file system will be shared via Apple Filing Protocol, as
+well as their behaviour. Any line not prefixed with # is interpreted. The
+configuration lines are composed like:
.PP
-path [ chooser name ] [ options ]
+\fBpath\fR \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 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. "File Share"). The chooser name
-may not exceed 27 characters in length, and cannot contain the
-\fB\&':'\fR character.
+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 \fB':'\fR
+character.
.RS
\fBNote\fR
.PP
.TP
ro
Specifies the share as being read only for all users.
-\&.AppleDB has to be writeable, you can use the
+The .AppleDB directory has to be writeable, you can use the
\fB\-dbpath\fR option to relocate it.
.TP
usedots
.TP
root_preexec_close
a non\-zero return code from root_preexec closes the
-volume being mounted.
+volume immediately, preventing clients to mount/see the volume
+in question
.TP
preexec_close
a non\-zero return code from preexec close the volume
-being mounted.
+being immediately, preventing clients to mount/see the volume
+in question
.RE
.TP
password:\fI[password]\fR
This option allows you to set a volume password, which can be
-a maximum of 8 characters long.
+a maximum of 8 characters long (using ASCII strongly recommended at
+the time of this writing)
.TP
preexec:\fI[command]\fR
command to be run when the volume is mounted, ignored for user
.TP
$$
prints dollar sign ($)
+.PP
+When using variable substitution in the volume name, always keep in
+mind, not to exceed the 27 characters limit
+.PP
+\fBUsing variable substitution when defining volumes\fR
+.PP
+.nf
+/home/groups/$g "Groupdir for $g"
+~ "$f is the best one"
+.fi
+
+We define "groupdirs"
+for each primary group and use a personalized server name for homedir
+shares.
.SH CNID\ BACKENDS
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 .\fBAppleDB\fR
+CNID Databases are by default located in the \fB.AppleDB\fR
folder in the volume root.
.TP
cdb
corrupt the database.
.TP
dbd
-Access to the CNID database is restricted to a the
+Access to the CNID database is restricted to the
cnid_metad daemon process. afpd
processes communicate with the daemon for database reads and
updates. If built with Berkeley DB transactions the probability for
.RS
.TP
crlf
-Enables crlf translation for TEXT files.
+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. Afpd
+will potentially destroy such files when "erroneously"
+changing bytes in order to do line break translation
.TP
dropbox
Allows a volume to be declared as being a
.TP
noadouble
Forces afpd to not create
-\&.AppleDouble unless a resource fork needs to be created.
+\&.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 afpd to
+not automatically create .AppleDouble subdirs containing AD
+header files in every directory it enters (which will it do by
+default).
+
+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.
+
+Try to avoid \fBnoadouble\fR whenever
+possible
.TP
nodev
always use 0 for device number, helps when the device
-number is not constant across a reboot, cluster, ....
+number is not constant across a reboot, cluster, ...
.TP
nofileid
don't advertise createfileid, resolveid, deleteid
script.
.TP
upriv
-use AFP3 unix privileges
+use AFP3 unix privileges. Become familiar with the new
+"unix privileges" AFP permissions concepts in MacOS X
+before using this option.
.RE
.SH SEE\ ALSO
\fBafpd.conf\fR(5),
\fBafpd\fR(8)
-
configuration of the different virtual file servers that it provides.
.PP
Any line not prefixed with # is interpreted. The configuration lines
-are composed like: server name [ options ] If a \- is used instead of a
-server name, the default server is specified. Server names must be quoted
-if they contain spaces. 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.
+are composed like: server name [ options ] If a \fB\-\fR is used
+instead of a server name, the default server is specified. Server names
+must be quoted if they contain spaces. They must not contain ":"
+or "@". 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
.RS
\fBNote\fR
.TP
uams_randum.so
allows Random Number and Two\-Way Random Number Exchange
-for authentication (requires
-:ETCDIR:/afppaswd file)
+for authentication (requires a separate file containing the
+passwords, either :ETCDIR:/afppasswd file or the one specified
+via \fB\-passwdfile\fR. See
+\fBafppasswd\fR(1)
+for details
.TP
uams_dhx.so
(uams_dhx_pam.so or uams_dhx_passwd.so) Allow
Diffie\-Hellman eXchange (DHX) for authentication.
.TP
uam_gss.so
-Allow Kerberos V for authetication (optional)
+Allow Kerberos V for authentication (optional)
.RE
.TP
\-uampath \fI[path]\fR
Sets the default path for UAMs for this server (default is
-/usr/local/netatalk\-head\-testing//etc/netatalk/uams).
+:ETCDIR:/uams).
.TP
\-k5keytab \fI[path]\fR, \-k5service \fI[service]\fR, \-k5realm \fI[realm]\fR
These are required if the server supports the Kerberos 5
.SH CODEPAGE\ OPTIONS
With OS X Apple introduced the AFP3 protocol. One of the big changes
was, that AFP3 uses Unicode names encoded as UTF\-8 decomposed. Previous
-AFP/OS versions used codepages, like MacRoman, MacCentralEurope, etc.
+AFP/OS versions used codepages like MacRoman, MacCentralEurope, etc.
.PP
To be able to serve AFP3 and older clients at the same time,
-afpd needs to be able to convert betweend UTF\-8 and Mac
+afpd needs to be able to convert between UTF\-8 and Mac
codepages. Even OS X clients partly still rely on codepages. As
there's no way, afpd can detect the codepage a pre
AFP3 client uses, you have to specify it using the \fB\-maccodepage\fR
.TP
\-maccodepage [CODEPAGE]
Specifies the mac clients codepage, e.g. "MAC_ROMAN".
-This is used to convert strings and filename to the clients codepage
-for OS9 and Classic, i.e. for authentication and SIGUSR2 messaging.
-This will also be the default for the volumes maccharset. Defaults
-to MAC_ROMAN.
+This is used to convert strings and filenames to the clients
+codepage for OS9 and Classic, i.e. for authentication and AFP
+messages (SIGUSR2 messaging). This will also be the default for the
+volumes maccharset. Defaults to MAC_ROMAN.
.SH PASSWORD\ OPTIONS
.TP
-\-loginmaxmail [number]
+\-loginmaxfail [number]
Sets the maximum number of failed logins, if supported by the
-UAM
+UAM (currently none)
.TP
\-passwdfile [path]
Sets the path to the Randnum UAM passwd file for this server
-(default is
-/usr/local/netatalk\-head\-testing//etc/netatalk/afppasswd).
+(default is :ETCDIR:/afppasswd).
.TP
\-passwdminlen [number]
Sets the minimum password length, if supported by the UAM
.TP
\-[no]setpassword
Enables or disables the ability of clients to change their
-passwords
+passwords via chooser or the "connect to server" dialog
.SH TRANSPORT\ PROTOCOLS
.TP
\-[no]ddp
-Enables or disables AFP\-over\-Appletalk. If \-proxy is
-specified, you must instead use \-uamlist "" to prevent DDP
-connections from working.
+Enables or disables AFP\-over\-Appletalk. If \fB\-proxy\fR
+is specified, you must instead use \fB\-uamlist ""\fR
+to prevent DDP connections from working.
.TP
\-[no]tcp
Enables or disables AFP\-over\-TCP
\-ddpaddr \fI[ddp address]\fR
Specifies the DDP address of the server. The default is to
auto\-assign an address (0.0). This is only useful if you are running
-on a multihomed host.
+AppleTalk on more than one interface.
.TP
\-fqdn \fI[name:port]\fR
Specifies a fully\-qualified domain name, with an optional
port. This is discarded if the server cannot resolve it. This option
is not honored by AppleShare clients <= 3.8.3. This option is
-disabled by default.
+disabled by default. Use with caution as this will involve a second
+name resolution step
.TP
\-ipaddr \fI[ip address]\fR
-Specifies the IP that the server should respond to (the
+Specifies the IP address that the server should advertise (the
default is the first IP address of the system). This option also
-allows one machine to advertise TCP/IP for another machine.
+allows to use one machine to advertise the AFP\-over\-TCP/IP
+settings of another machine via NBP.
.TP
\-port \fI[port number]\fR
-Allows a different TCP port to be specified for AFP\-over\-TCP.
-The default is 548.
+Allows a different TCP port to be used for AFP\-over\-TCP. The
+default is 548.
.TP
\-proxy
Runs an AppleTalk proxy server for the specified AFP\-over\-TCP
server. If the address and port aren't given, then the first IP
address of the system and port 548 will be used. If you don't
-want the proxy server to act as a DDP server as well, set \-uamlist
-"".
+want the proxy server to act as a DDP server as well, set
+\fB\-uamlist ""\fR.
.TP
\-server_quantum \fI[number]\fR
This specifoes the DSI server quantum. The minimum value is
303840 (0x4A2E0). The maximum value is 0xFFFFFFFFF. If you specify a
value that is out of range, the default value will be set (which is
-the minimum).
+the minimum). Do not change this value unless you're absolutely
+sure, what you're doing
.TP
\-noslp
Do not register this server using the Service Location
Protocol (if SLP support was compiled in). This is useful if you are
running multiple servers and want one to be hidden, perhaps because
-it is advertised elsewhere.
+it is advertised elsewhere, ie. by a SLP Directory Agent.
.SH MISCELLANEOUS\ OPTIONS
.TP
\-admingroup \fI[group]\fR
Allows users of a certain group to be seen as the superuser
-when they log in. This option is disabled, by default.
+when they log in. This option is disabled by default.
.TP
\-authprintdir \fI[path]\fR
Specifies the path to be used (per server) to store the files
\fBNote\fR
\fB\-authprintdir\fR will only work for clients
-connecting via DDP. Most modern Clients will use TCP.
+connecting via DDP. Almost all modern Clients will use TCP.
.RE
.TP
\-client_polling
\fINote\fR: Depending on the number of simultaneously
connected clients and the network's speed, this can lead to a
significant higher load on your network!
+.RS
+\fBNote\fR
+
+Do not use this option any longer as Netatalk 2.0 correctly
+supports server notifications, allowing connected clients to
+update folder listings in case another client changed the contents
+.RE
.TP
\-cnidserver \fI[ipaddress:port]\fR
Specifies the IP address and port of a cnid_metad server,
-required for CNID bdb backend. Defaults to localhost:4700.
+required for CNID dbd backend. Defaults to localhost:4700.
.TP
\-guestname \fI[name]\fR
Specifies the user that guests should use (default is
"host" signature type allows afpd generating signature
automatically (based on machine primary IP address). "user"
signature type allows administrator to set up a signature string
-manually.
+manually. The maximum length is 16 characters
-Examples: three servers running on one machine: first
-\-signature user:USERS second \-signature user:USERS third \-signature
-user:ADMINS
+\fBThree server definitions using 2 different server
+signatures\fR
+
+.nf
+first \-signature user:USERS
+second \-signature user:USERS
+third \-signature user:ADMINS
+.fi
-First two servers will act as one logical AFP service \- if
-user logs in to first one and then connects to second one, session
-will be automatically redirected to the first one. But if client
-connects to first and then to third, will be asked for password
-twice and will see resources of both servers. Traditional method of
-signature generation causes two independent afpd instancesto have
-the same signature and thus cause clients to be redirected
-automatically to server (s)he logged in first.
+First two servers will appear as one logical AFP service to
+the clients \- if user logs in to first one and then connects to
+second one, session will be automatically redirected to the first
+one. But if client connects to first and then to third, will be
+asked for password twice and will see resources of both servers.
+Traditional method of signature generation causes two independent
+afpd instances to have the same signature and thus cause clients to
+be redirected automatically to server (s)he logged in first.
.SH LOGGING\ OPTIONS
.TP
\-[un]setuplog "<logtype> <loglevel> [<filename>]"
Latter \fB\-setuplog\fR settings will override earlier
ones of the same logtype (file or syslog).
-logtypes: Default, Core, Logger, CNID, AFPDaemon loglevels:
-LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE, LOG_INFO, LOG_DEBUG,
-LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8, LOG_DEBUG9, LOG_MAXDEBUG
+logtypes: Default, Core, Logger, CNID, AFP
-Example: \-setuplog "logger log_maxdebug
-/var/log/netatalk\-logger.log" \-setuplog "afpdaemon
-log_maxdebug /var/log/netatalk\-afp.log" \-unsetuplog "default
-level file" \-setuplog "default log_maxdebug"
+Daemon loglevels: LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE,
+LOG_INFO, LOG_DEBUG, LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8, LOG_DEBUG9,
+LOG_MAXDEBUG
+
+\fBSome ways to change afpd's logging behaviour via \-[un]setuplog\fR
+
+Example:
+
+.nf
+\-setuplog "logger log_maxdebug /var/log/netatalk\-logger.log"
+\-setuplog "afpdaemon log_maxdebug /var/log/netatalk\-afp.log"
+\-unsetuplog "default level file"
+\-setuplog "default log_maxdebug"
+.fi
.SH DEBUG\ OPTIONS
These options are useful for debugging only.
.TP
\-tickleval \fI[number]\fR
-Sets the tickle timeout interval (in seconds).
+Sets the tickle timeout interval (in seconds). Defaults to 30.
.TP
\-timeout \fI[number]\fR
Specify the number of tickles to send before timing out a
-connection. The default is 4, therefore a connection will timeout in
-2 minutes.
+connection. The default is 4, therefore a connection will timeout
+after 2 minutes.
.SH EXAMPLES
-\fBDefault configuration\fR
+\fBafpd.conf default configuration\fR
.PP
.nf
\- \-transall \-uamlist uams_clrtxt.so,uams_dhx.so,uams_guest.so
.fi
.PP
-\fBMacCyrillic setup / UTF8 unix locale\fR
+\fBafpd.conf MacCyrillic setup / UTF8 unix locale\fR
.PP
.nf
\- \-transall \-maccodepage mac_cyrillic \-unixcodepage utf8
.fi
.PP
-\fBSetup for Kerberos V auth\fR
+\fBafpd.conf setup for Kerberos V auth\fR
.PP
.nf
\- \-transall \-uamlist uams_clrtxt.so,uams_dhx.so,uams_guest.so,uams_gss.so \-k5service afpserver \-k5keytab /path/to/afpserver.keytab \-k5realm YOUR.REALM \-fqdn your.fqdn.namel:548
.fi
.PP
-\fBThree servers on one machine\fR
+\fBafpd.conf letting afpd appear as three servers on the net\fR
.PP
.nf
"Guest Server" \-uamlist uams_guest.so \-loginmesg "Welcome guest!"
.fi
.SH SEE\ ALSO
\fBafpd\fR(8),
+\fBafppasswd\fR(1),
\fBAppleVolumes.default\fR(5)
-
projects / netatalk.git / commitdiff