afpd.conf

5 24 May 2024 @NETATALK_VERSION@

afpd.conf

Configuration file used by `afpd`(8) to determine the capabilities of its file sharing services

## Description

`afpd.conf` is the configuration file used by `afpd` to determine the behavior and capabilities of one or more virtual file servers that it provides.

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. 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.

Each server has to be configured on a single line. Though, using "\" character, newline escaping is supported.

The possible options and their meanings are:

## AppleVolumes Files

-defaultvol `[path]`

- Specifies path to AppleVolumes.default file.

-systemvol `[path]`

- Specifies path to AppleVolumes.system file.

-[no]uservol

- Enables or disables reading of the users' individual volumes file entirely.

-[no]uservolfirst

- Enables or disables reading of the users' individual volumes file before processing the global `AppleVolumes.default` file.

## Authentication Methods

-uamlist `[uams list]`

- Comma separated list of UAMs. (The default is uams_dhx.so,uams_dhx2.so).

  The most commonly used UAMs are:

  uams_guest.so

- allows guest logins

uams_clrtxt.so

- (uams_pam.so or uams_passwd.so) Allow logins with passwords transmitted in the clear. (legacy)

uams_randnum.so

- allows Random Number and Two-Way Random Number Exchange for authentication (requires a separate file containing the passwords, either afppasswd file or the one specified via `-passwdfile`. See

  afppasswd

  1 for details. (legacy)

uams_dhx.so

- (uams_dhx_pam.so or uams_dhx_passwd.so) Allow Diffie-Hellman eXchange (DHX) for authentication.

uams_dhx2.so

- (uams_dhx2_pam.so or uams_dhx2_passwd.so) Allow Diffie-Hellman eXchange 2 (DHX2) for authentication.

uam_gss.so

- Allow Kerberos V for authentication (optional)

-uampath `[path]`

- Sets the default path for UAMs for this server.

-k5keytab `[path]`

-k5service `[service]`

-k5realm `[realm]`

- These are required if the server supports the Kerberos 5 authentication UAM.

-ntdomain

-ntseparator

- Use for e.g. winbind authentication, prepends both strings before the username from login and then tries to authenticate with the result through the available and active UAM authentication modules.

-adminauthuser

- Specifying e.g. `-adminauthuser root` whenever a normal user login fails, afpd will try to authenticate as the specified `adminauthuser`. If this succeeds, a normal session is created for the original connecting user. Said differently: if you know the password of `adminauthuser`, you can authenticate as any other user.

## Codepage Options

With OS X Apple introduced the AFP3 protocol. One of the big changes was, that AFP3 uses Unicode names encoded as Decomposed UTF-8 (UTF8-MAC). Previous AFP/OS versions used codepages like MacRoman, MacCentralEurope, etc.

To be able to serve AFP3 and older clients at the same time, `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 `-maccodepage` option. The default is MacRoman, which should be fine for most western users.

As `afpd` needs to interact with unix operating system as well, it needs to be able to convert from UTF8-MAC/MacCodepage to the unix codepage. By default `afpd` uses the systems LOCALE, or ASCII if your system doesn't support locales. You can set the unix codepage using the `-unixcodepage` option. If you're using extended characters in the configuration files for `afpd`, make sure your terminal matches the `-unixcodepage`.

-unixcodepage [`CODEPAGE`]

- Specifies the server's unix codepage, e.g. "ISO-8859-15" or "UTF8". This is used to convert strings to/from the system's locale, e.g. for authenthication, server messages and volume names. Defaults to LOCALE if your system supports it, otherwise ASCII will be used.

-maccodepage [`CODEPAGE`]

- Specifies the Mac client's codepage, e.g. "MAC_ROMAN". This is used to convert strings and filenames to the clients codepage for Mac OS 9 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.

## Password Options

-passwdfile [`path`]

- Sets the path to the Randnum UAM passwd file for this server.

-[no]savepassword

- Enables or disables the ability of clients to save passwords locally

-[no]setpassword

- Enables or disables the ability of clients to change their passwords via the Chooser or the "connect to server" dialog

## Transport Protocols

-[no]ddp

- Enables or disables AFP-over-Appletalk. If `-proxy` is specified, you must instead use `-uamlist ""` to prevent DDP connections from working.

-[no]tcp

- Enables or disables AFP-over-TCP

-[no]transall

- Enables or disables both transport protocols. Default is `-transall`.

## Transport Options

-advertise_ssh

- Allows Mac OS X clients (10.3.3-10.4) to automagically establish a tunneled AFP connection through SSH. If this option is set, the server's answers to client's FPGetSrvrInfo requests contain an additional entry. It depends on both client's settings and a correctly configured and running

  sshd

  8 on the server to let things work.

  Apple's client side implementation of this feature in Mac OS X versions prior to 10.3.4 contained a security flaw.

-ddpaddr `[ddp address]`

- 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 AppleTalk on more than one interface.

-fqdn `[name:port]`

- 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. Use with caution as this will involve a second name resolution step on the client side. Also note that afpd will advertise this name:port combination but not automatically listen to it.

-hostname`[name]`

- Use this instead of the result from calling hostname for determining which IP address to advertise, therefore the hostname is resolved to an IP which is the advertised one. This is NOT used for listening and it is also overwritten by `-ipaddr`.

-ipaddr `[ip address]`

- Specifies the IP address that the server should advertise and listen to. The default is to advertise the first IP address of the system, but to listen for any incoming request. The network address may be specified either in dotted-decimal format for IPv4 or in hexadecimal format for IPv6. This option also allows one to use one machine to advertise the AFP-over-TCP/IP settings of another machine via NBP
  when used together with the `-proxy` option.

  ### afpd.conf configuration line

                    fluxxus -hostname afp.example.org -ipaddr 192.168.0.1 -fqdn www.example.com

  Result

  (UTF8) Server name: fluxxus, Listening and advertised network address: 192.168.0.1, Advertised network address: www.example.com, hostname is not used.

-port `[port number]`

- Allows a different TCP port to be used for AFP-over-TCP. The default is 548.

-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 ""`.

-server_quantum `[number]`

- This specifies the DSI server quantum. The default value is 303840. The maximum value is 0xFFFFFFFFF, the minimum is 32000. If you specify a value that is out of range, the default value will be set. Do not change this value unless you're absolutely sure, what you're doing

-dsireadbuf `[number]`

- Scale factor that determines the size of the DSI/TCP readahead buffer, default is 12. This is multiplied with the DSI server quantum (default ~300k) to give the size of the buffer. Increasing this value might increase throughput in fast local networks for volume to volume copies.

  This buffer is allocated per afpd child process, so specifying large values will eat up large amounts of memory (buffer size * number of clients).

-tcprcvbuf `[number]`

- Try to set TCP receive buffer using setsockpt(). Often OSes impose restrictions on the applications' ability to set this value.

-tcpsndbuf `[number]`

- Try to set TCP send buffer using setsockpt(). Often OSes impose restrictions on the applications' ability to set this value.

-nozeroconf

- Disable automatic Zeroconf
  service registration if support was compiled in.

-slp

- Register this server using the Service Location Protocol (if SLP
  support was compiled in).

## Miscellaneous Options

-admingroup `[group]`

- Allows users of a certain group to be seen as the superuser when they log in. This option is disabled by default.

-authprintdir `[path]`

- Specifies the path to be used (per server) to store the files required to do CAP-style print authentication which papd will examine to determine if a print job should be allowed. These files are created at login, and if they are to be properly removed, this directory probably needs to be umode 1777.

-closevol

- Immediately unmount volumes removed from AppleVolumes files on SIGHUP sent to the afpd master process.

-cnidserver `[ipaddress:port]`

- Specifies the IP address and port of a cnid_metad server, required for the CNID dbd backend. Defaults to localhost:4700. The network address may be specified either in dotted-decimal format for IPv4 or in hexadecimal format for IPv6.

-dircachesize`entries`

- Maximum possible entries in the directory cache. The cache stores directories and files. It is used to cache the full path to directories and CNIDs which considerably speeds up directory enumeration.

  Default size is 8192, maximum size is 131072. Given value is rounded up to nearest power of 2. Each entry takes about 100 bytes, which is not much, but remember that every afpd child process for every connected user has its own cache.

-fcelistener `host[:port]`

- Enables sending FCE events to the specified `host`, default `port` is 12250 if not specified. Specifying multiple listeners is done by having this option once for each of them.

-fceevents `fmod,fdel,ddel,fcre,dcre,tmsz`

- Specifies which FCE events are active, default is `fmod,fdel,ddel,fcre,dcre`.

-fcecoalesce `all|delete|create`

- Coalesce FCE events.

-fceholdfmod `seconds`

- This determines the time delay in seconds which is always waited if another file modification for the same file is done by a client before sending an FCE file modification event (fmod). For example, saving a file in Photoshop would generate multiple events by itself because the application is opening, modifying and closing a file multiple times for every "save". Default: 60 seconds.

-guestname `[name]`

- Specifies the user that guests should use (default is "nobody"). The name should be quoted.

-[no]icon

- [Don't] Use the Netatalk icon for mounted volumes. Later Mac OS versions ignores this.

-keepsessions

- Enable "Continuous AFP Service". This means the ability to stop the master afpd process with a SIGQUIT signal, possibly install an afpd update and start the afpd process. Existing AFP sessions' afpd processes will remain unaffected. Technically they will be notified of the master afpd shutdown, sleep 15-20 seconds and then try to reconnect their IPC channel to the master afpd process. If this reconnect fails, the sessions are in an undefined state. Therefore it's absolutely critical to restart the master process in time!

-loginmesg `[message]`

- Sets a message to be displayed when clients logon to the server. The message should be in `unixcodepage` and should be quoted. Extended characters are allowed.

-mimicmodel `model`

- Specifies a custom icon for the mounted AFP volume on macOS / Mac OS X clients. Default is to let macOS choose. Requires netatalk to be built with Zeroconf. Examples:

  - `Laptop`

  - `RackMount`

  - `Tower`

  A complete set of supported model codes by a macOS client can be found by inspecting `/System/Library/CoreServices/CoreTypes.bundle/Contents/Info.plist` (as of macOS 14 Sonoma).

-noacl2maccess

- Don't map filesystem ACLs to effective permissions.

-sleep `[number]`

- AFP 3.x waits `number` hours before disconnecting clients in sleep mode. Default is 10 hours.

-signature { user:<text> | auto }

- Specify a server signature. This option is useful while running multiple independent instances of afpd on one machine (e.g. in clustered environments, to provide fault isolation etc.). Default is "auto". "auto" signature type allows afpd to generate a signature and saving it to `afp_signature.conf` automatically (based on a random number). The "host" signature type switches back to "auto" because it is obsoleted. The "user" signature type allows an administrator to set up a signature string manually. The maximum length is 16 characters.

  ### Three server definitions using 2 different server signatures

      first -signature user:USERS
                  second -signature user:USERS
                  third -signature user:ADMINS

  The first two servers will appear as one logical AFP service to the clients - if a user logs in to the first one and then connects to the second one, the session will be automatically redirected to the first one. But if a client connects to the first and then to the third, they will be asked for the password twice and will see resources of both servers. The traditional method of signature generation causes two independent afpd instances to have the same signature and thus cause clients to be redirected automatically to the server they logged in to first.

-volnamelen `[number]`

- Max length of UTF8-MAC volume name for Mac OS X. Note that Hangul is especially sensitive to this.

      73:  limit of Mac OS X 10.1
                80:  limit for Mac OS X 10.4/10.5 (default)
      	  255: limit of spec

  Mac OS 9 and earlier are not influenced by this, because Maccharset volume name is always limited to 27 bytes.

## Logging Options

-setuplog "`<logtype> <loglevel> [<filename>]`"

- Specify that any message of a loglevel up to the given `loglevel` should be logged to the given file. If the filename is omitted, the loglevel applies to messages passed to syslog.

  By default afpd logs to syslog with a default logging setup equivalent to `-setuplog "default log_note"`.

  logtypes: Default, AFPDaemon, Logger, UAMSDaemon

  loglevels: LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE, LOG_INFO, LOG_DEBUG, LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8, LOG_DEBUG9, LOG_MAXDEBUG

  The config is case insensitive

  ### Useful default config

      - -setuplog "default log_info /var/log/afpd.log"

  ### Debugging config

      - -setuplog "default log_maxdebug /var/log/afpd.log"

  ### afpd logging to different files

      - -setuplog "default log_info /var/log/afpd.log" \
      -setuplog "UAMSDaemon log_maxdebug /var/log/uams.log"

-unsetuplog "`<logtype> [<filename>]`"

- Note that for `unsetuplog` specifying any string as filename is sufficient for the config parser to distinguish between requests to disable syslog logging or file-logging.

  ### Disable afpd logging set at build-time from configure

      - -unsetuplog "default -"

## Debug Options

These options are useful for debugging only.

-tickleval `[number]`

- Sets the tickle timeout interval (in seconds). Defaults to 30. A value of 0 disables session timer tickles.

-timeout `[number]`

- Specify the number of tickles to send before timing out a connection. The default is 4, therefore a connection will timeout after 2 minutes.

## Examples

### afpd.conf MacCyrillic setup / UTF8 unix locale

    - -maccodepage mac_cyrillic -unixcodepage utf8

### afpd.conf setup for Kerberos V auth with newline escaping

    - -uamlist uams_dhx.so,uams_dhx2.so,uams_guest.so,uams_gss.so \
    -k5service afpserver -k5keytab /path/to/afpserver.keytab \
    -k5realm YOUR.REALM -fqdn your.fqdn.namel:548

### afpd.conf letting afpd appear as three servers on the net

    "Guest Server" -uamlist uams_guest.so -loginmesg "Welcome guest!"
    "User Server" -uamlist uams_dhx2.so -port 12000
    "special" -ddp -notcp -defaultvol <path> -systemvol <path>

## See also

afpd

8 ,

afppasswd

1 ,

AppleVolumes.default

5 ,

afp_signature.conf

5 ,

cnid_metad

8