man/man5/afpd.conf.5.tmpl

   1 .TH afpd.conf 5 "24 September 2004" 2.0.0 Netatalk
   2 .SH NAME
   3 afpd.conf \- Configuration file used by afpd(8) to determine the setup of its file sharing services
   4 .SH DESCRIPTION
   5 \fB:ETCDIR:/afpd.conf\fR is the configuration file
   6 used by afpd to determine the behavior and
   7 configuration of the different virtual file servers that it
   8 provides.
   9 .PP
  10 Any line not prefixed with # is interpreted. The configuration lines
  11 are composed like: server name [ options ] If a \fB\-\fR is used
  12 instead of a server name, the default server is specified. Server names
  13 must be quoted if they contain spaces. They must not contain ":" or "@".
  14 The path name must be a fully qualified path name, or a path name using
  15 either the ~ shell shorthand or any of the substitution variables, which
  16 are listed below.
  17 .PP
  18 .RS
  19 \fBNote\fR
  20 .PP
  21 Each server has to be configured on a \fBsingle\fR line.
  22 .RE
  23
  24 The possible options and their meanings are:
  25 .SH "APPLEVOLUMES FILES"
  26 .TP
  27 \-defaultvol \fI[path]\fR
  28 Specifies path to AppleVolumes.default file (default is
  29 \fB:ETCDIR:/AppleVolumes.default\fR).
  30 .TP
  31 \-systemvol \fI[path]\fR
  32 Specifies path to AppleVolumes.system file (default is
  33 \fB:ETCDIR:/AppleVolumes.system\fR).
  34 .TP
  35 \-[no]uservol
  36 Enables or disables reading of the users' individual volumes
  37 file entirely.
  38 .TP
  39 \-[no]uservolfirst
  40 Enables or disables reading of the users' individual volumes
  41 file before processing the global
  42 \fBAppleVolumes.default\fR file.
  43 .SH "AUTHENTICATION METHODS"
  44 .TP
  45 \-uamlist \fI[uams list]\fR
  46 Comma separated list of UAMs. (The default is
  47 uams_guest.so,uams_clrtxt.so,uams_dhx.so).
  48
  49 The most commonly used UAMs are:
  50 .RS
  51 .TP
  52 uams_guest.so
  53 allows guest logins
  54 .TP
  55 uams_clrtxt.so
  56 (uams_pam.so or uams_passwd.so) Allow logins with
  57 passwords transmitted in the clear.
  58 .TP
  59 uams_randum.so
  60 allows Random Number and Two\-Way Random Number Exchange
  61 for authentication (requires a separate file containing the
  62 passwords, either :ETCDIR:/afppasswd file or the one specified
  63 via \fB\-passwdfile\fR. See \fBafppasswd\fR(1) for details
  64 .TP
  65 uams_dhx.so
  66 (uams_dhx_pam.so or uams_dhx_passwd.so) Allow
  67 Diffie\-Hellman eXchange (DHX) for authentication.
  68 .TP
  69 uam_gss.so
  70 Allow Kerberos V for authentication (optional)
  71 .RE
  72 .TP
  73 \-uampath \fI[path]\fR
  74 Sets the default path for UAMs for this server (default is
  75 :ETCDIR:/uams).
  76 .TP
  77 \-k5keytab \fI[path]\fR, \-k5service \fI[service]\fR, \-k5realm \fI[realm]\fR
  78 These are required if the server supports the Kerberos 5
  79 authentication UAM.
  80 .SH "CODEPAGE OPTIONS"
  81 With OS X Apple introduced the AFP3 protocol. One of the big changes
  82 was, that AFP3 uses Unicode names encoded as UTF\-8 decomposed. Previous
  83 AFP/OS versions used codepages like MacRoman, MacCentralEurope,
  84 etc.
  85 .PP
  86 To be able to serve AFP3 and older clients at the same time,
  87 afpd needs to be able to convert between UTF\-8 and Mac
  88 codepages. Even OS X clients partly still rely on codepages. As there's no
  89 way, afpd can detect the codepage a pre AFP3 client
  90 uses, you have to specify it using the \fB\-maccodepage\fR
  91 option. The default is MacRoman, which should be fine for most western
  92 users.
  93 .PP
  94 As afpd needs to interact with unix operating
  95 system as well, it need's to be able to convert from UTF\-8/MacCodepage to
  96 the unix codepage. By default afpd uses the systems
  97 LOCALE, or ASCII if your system doesn't support locales. You can set the
  98 unix codepage using the \fB\-unixcodepage\fR option. If you're
  99 using extended characters in the configuration files for
 100 afpd, make sure your terminal matches the
 101 \fB\-unixcodepage\fR.
 102 .TP
 103 \-unixcodepage [CODEPAGE]
 104 Specifies the servers unix codepage, e.g. "ISO\-8859\-15" or
 105 "UTF8". This is used to convert strings to/from the systems locale,
 106 e.g. for authenthication, server messages and volume names. Defaults
 107 to LOCALE if your system supports it, otherwise ASCII will be
 108 used.
 109 .TP
 110 \-maccodepage [CODEPAGE]
 111 Specifies the mac clients codepage, e.g. "MAC_ROMAN". This is
 112 used to convert strings and filenames to the clients codepage for
 113 OS9 and Classic, i.e. for authentication and AFP messages (SIGUSR2
 114 messaging). This will also be the default for the volumes
 115 maccharset. Defaults to MAC_ROMAN.
 116 .SH "PASSWORD OPTIONS"
 117 .TP
 118 \-loginmaxfail [number]
 119 Sets the maximum number of failed logins, if supported by the
 120 UAM (currently none)
 121 .TP
 122 \-passwdfile [path]
 123 Sets the path to the Randnum UAM passwd file for this server
 124 (default is :ETCDIR:/afppasswd).
 125 .TP
 126 \-passwdminlen [number]
 127 Sets the minimum password length, if supported by the
 128 UAM
 129 .TP
 130 \-[no]savepassword
 131 Enables or disables the ability of clients to save passwords
 132 locally
 133 .TP
 134 \-[no]setpassword
 135 Enables or disables the ability of clients to change their
 136 passwords via chooser or the "connect to server" dialog
 137 .SH "TRANSPORT PROTOCOLS"
 138 .TP
 139 \-[no]ddp
 140 Enables or disables AFP\-over\-Appletalk. If
 141 \fB\-proxy\fR is specified, you must instead use
 142 \fB\-uamlist ""\fR to prevent DDP connections from
 143 working.
 144 .TP
 145 \-[no]tcp
 146 Enables or disables AFP\-over\-TCP
 147 .TP
 148 \-transall
 149 Make both available (default)
 150 .SH "TRANSPORT OPTIONS"
 151 .TP
 152 \-advertise_ssh
 153 Allows Mac OS X clients (10.3.3 or above) to automagically
 154 establish a tunneled AFP connection through SSH. If this option is
 155 set, the server's answers to client's FPGetSrvrInfo requests contain
 156 an additional entry. It depends on both client's settings and a
 157 correctly configured and running \fBsshd\fR(8) on the server to let things work.
 158 .RS
 159 \fBNote\fR
 160
 161 Setting this option is not recommended since globally
 162 encrypting AFP connections via SSH will increase the server's load
 163 significantly. On the other hand, Apple's client side
 164 implementation of this feature in MacOS X versions prior to 10.3.4
 165 contained a security flaw.
 166 .RE
 167 .TP
 168 \-ddpaddr \fI[ddp address]\fR
 169 Specifies the DDP address of the server. The default is to
 170 auto\-assign an address (0.0). This is only useful if you are running
 171 AppleTalk on more than one interface.
 172 .TP
 173 \-fqdn \fI[name:port]\fR
 174 Specifies a fully\-qualified domain name, with an optional
 175 port. This is discarded if the server cannot resolve it. This option
 176 is not honored by AppleShare clients <= 3.8.3. This option is
 177 disabled by default. Use with caution as this will involve a second
 178 name resolution step on the client side. Also note that afpd will
 179 advertise this name:port combination but not automatically listen to
 180 it.
 181 .TP
 182 \-ipaddr \fI[ip address]\fR
 183 Specifies the IP address that the server should advertise
 184 \fBand\fR listens to (the default is the
 185 first IP address of the system). This option also allows to use one
 186 machine to advertise the AFP\-over\-TCP/IP settings of another machine
 187 via NBP when used together with the \fB\-proxy\fR
 188 option.
 189 .TP
 190 \-port \fI[port number]\fR
 191 Allows a different TCP port to be used for AFP\-over\-TCP. The
 192 default is 548.
 193 .TP
 194 \-proxy
 195 Runs an AppleTalk proxy server for the specified AFP\-over\-TCP
 196 server. If the address and port aren't given, then the first IP
 197 address of the system and port 548 will be used. If you don't want
 198 the proxy server to act as a DDP server as well, set \fB\-uamlist
 199 ""\fR.
 200 .TP
 201 \-server_quantum \fI[number]\fR
 202 This specifoes the DSI server quantum. The minimum value is
 203 303840 (0x4A2E0). The maximum value is 0xFFFFFFFFF. If you specify a
 204 value that is out of range, the default value will be set (which is
 205 the minimum). Do not change this value unless you're absolutely
 206 sure, what you're doing
 207 .TP
 208 \-noslp
 209 Do not register this server using the Service Location
 210 Protocol (if SLP support was compiled in). This is useful if you are
 211 running multiple servers and want one to be hidden, perhaps because
 212 it is advertised elsewhere, ie. by a SLP Directory Agent.
 213 .SH "MISCELLANEOUS OPTIONS"
 214 .TP
 215 \-admingroup \fI[group]\fR
 216 Allows users of a certain group to be seen as the superuser
 217 when they log in. This option is disabled by default.
 218 .TP
 219 \-authprintdir \fI[path]\fR
 220 Specifies the path to be used (per server) to store the files
 221 required to do CAP\-style print authentication which papd will
 222 examine to determine if a print job should be allowed. These files
 223 are created at login and if they are to be properly removed, this
 224 directory probably needs to be umode 1777.
 225 .RS
 226 \fBNote\fR
 227
 228 \fB\-authprintdir\fR will only work for clients
 229 connecting via DDP. Almost all modern Clients will use TCP.
 230 .RE
 231 .TP
 232 \-client_polling
 233 With this switch enabled, afpd won't advertise that it is
 234 capable of server notifications, so that connected clients poll the
 235 server every 10 seconds to detect changes in opened server windows.
 236 \fINote\fR: Depending on the number of simultaneously
 237 connected clients and the network's speed, this can lead to a
 238 significant higher load on your network!
 239 .RS
 240 \fBNote\fR
 241
 242 Do not use this option any longer as Netatalk 2.0 correctly
 243 supports server notifications, allowing connected clients to
 244 update folder listings in case another client changed the
 245 contents.
 246 .RE
 247 .TP
 248 \-cnidserver \fI[ipaddress:port]\fR
 249 Specifies the IP address and port of a cnid_metad server,
 250 required for CNID dbd backend. Defaults to localhost:4700.
 251 .TP
 252 \-guestname \fI[name]\fR
 253 Specifies the user that guests should use (default is
 254 "nobody"). The name should be quoted.
 255 .TP
 256 \-icon
 257 Use the platform\-specific icon
 258 .TP
 259 \-loginmesg \fI[message]\fR
 260 Sets a message to be displayed when clients logon to the
 261 server. The message should be in \fBunixcodepage\fR and
 262 should be quoted. Extended characters are allowed.
 263 .TP
 264 \-nodebug
 265 Disables debugging.
 266 .TP
 267 \-sleep \fI[number]\fR
 268 AFP 3.x waits number hours before
 269 disconnecting clients in sleep mode. Default is 10 hours.
 270 .TP
 271 \-signature { user:<text> | host }
 272 Specify a server signature. This option is useful while
 273 running multiple independent instances of afpd on one machine (eg.
 274 in clustered environments, to provide fault isolation etc.). "host"
 275 signature type allows afpd generating signature automatically (based
 276 on machine primary IP address). "user" signature type allows
 277 administrator to set up a signature string manually. The maximum
 278 length is 16 characters
 279
 280 \fBThree server definitions using 2 different server
 281 signatures\fR
 282
 283 .nf
 284 first \-signature user:USERS
 285 second \-signature user:USERS
 286 third \-signature user:ADMINS
 287 .fi
 288
 289 First two servers will appear as one logical AFP service to
 290 the clients \- if user logs in to first one and then connects to
 291 second one, session will be automatically redirected to the first
 292 one. But if client connects to first and then to third, will be
 293 asked for password twice and will see resources of both servers.
 294 Traditional method of signature generation causes two independent
 295 afpd instances to have the same signature and thus cause clients to
 296 be redirected automatically to server (s)he logged in first.
 297 .SH "LOGGING OPTIONS"
 298 .RS
 299 \fBNote\fR
 300 .PP
 301 Extended logging capabilities are only available if Netatalk was
 302 built using \-\-with\-logfile. As of Netatalk 2.0, the
 303 default is \-\-without\-logfile since the logger code is
 304 partially broken and needs a complete rewrite (the
 305 \fB\-setuplog\fR option might not work as expected). If
 306 Netatalk was built without logger support then the daemons log to
 307 syslog.
 308 .RE
 309 .TP
 310 \-[un]setuplog "<logtype> <loglevel> [<filename>]"
 311 Specify that the given loglevel should be applied to log
 312 messages of the given logtype and that these messages should be
 313 logged to the given file. If the filename is ommited the loglevel
 314 applies to messages passed to syslog. Each logtype may have a
 315 loglevel applied to syslog and a loglevel applied to a single file.
 316 Latter \fB\-setuplog\fR settings will override earlier
 317 ones of the same logtype (file or syslog).
 318
 319 logtypes: Default, Core, Logger, CNID, AFP
 320
 321 Daemon loglevels: LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE,
 322 LOG_INFO, LOG_DEBUG, LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8, LOG_DEBUG9,
 323 LOG_MAXDEBUG
 324
 325 \fBSome ways to change afpd's logging behaviour via
 326 \-[un]setuplog\fR
 327
 328 Example:
 329
 330 .nf
 331 \-setuplog "logger log_maxdebug /var/log/netatalk\-logger.log"
 332 \-setuplog "afpdaemon log_maxdebug /var/log/netatalk\-afp.log"
 333 \-unsetuplog "default level file"
 334 \-setuplog "default log_maxdebug"
 335 .fi
 336 .SH "DEBUG OPTIONS"
 337 These options are useful for debugging only.
 338 .TP
 339 \-tickleval \fI[number]\fR
 340 Sets the tickle timeout interval (in seconds). Defaults to
 341 30.
 342 .TP
 343 \-timeout \fI[number]\fR
 344 Specify the number of tickles to send before timing out a
 345 connection. The default is 4, therefore a connection will timeout
 346 after 2 minutes.
 347 .SH EXAMPLES
 348 \fBafpd.conf default configuration\fR
 349 .PP
 350 .nf
 351 \- \-transall \-uamlist uams_clrtxt.so,uams_dhx.so,uams_guest.so
 352 .fi
 353 .PP
 354 \fBafpd.conf MacCyrillic setup / UTF8 unix locale\fR
 355 .PP
 356 .nf
 357 \- \-transall \-maccodepage mac_cyrillic \-unixcodepage utf8
 358 .fi
 359 .PP
 360 \fBafpd.conf setup for Kerberos V auth\fR
 361 .PP
 362 .nf
 363 \- \-transall \-uamlist uams_clrtxt.so,uams_dhx.so,uams_guest.so,uams_gss.so \\
 364 \-k5service afpserver \-k5keytab /path/to/afpserver.keytab \\
 365 \-k5realm YOUR.REALM \-fqdn your.fqdn.namel:548
 366 .fi
 367 .PP
 368 \fBafpd.conf letting afpd appear as three servers on the net\fR
 369 .PP
 370 .nf
 371 "Guest Server" \-uamlist uams_guest.so \-loginmesg "Welcome guest!"
 372 "User Server" \-uamlist uams_dhx.so \-port 12000
 373 "special" \-notcp \-defaultvol <path> \-systemvol <path>
 374 .fi
 375 .SH "SEE ALSO"
 376 \fBafpd\fR(8), \fBafppasswd\fR(1), \fBAppleVolumes.default\fR(5)
 377