AppleVolumes.default

5 08 Mar 2024 @NETATALK_VERSION@

AppleVolumes.default

AppleVolumes.system

AppleVolumes

Configuration file(s) used by `afpd`(8) to determine the shared volumes made available through AFP

          AppleVolumes.default

          AppleVolumes.system

          ~/AppleVolumes

          ~/.AppleVolumes

          ~/applevolumes

          ~/.applevolumes

## Description

`AppleVolumes.system` and one of `AppleVolumes.default`, `~/AppleVolumes`, `~/.AppleVolumes`, `~/applevolumes`, or `~/.applevolumes` are the configuration files used by `afpd` to determine what portions of the file system will be shared via Apple Filing Protocol, their behaviour, as well as file name extension mappings.

The present convention is that `AppleVolumes.system` contains the global file extension mappings, while `AppleVolumes.default` contains the global shared volumes. When present, the config file in the user's home dir contains user overrides to either.

Any line not prefixed with # is interpreted. Newline escaping is supported. The configuration lines are composed like:

`path` `[ volume name ] [ options ]`

`.extension` `[ type [ creator ] ]`

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.

The volume name is the name that appears in the Chooser or 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

Each volume has to be configured on a single line. Though newline escaping is supported.

The leading-dot lines specify file name extension mappings. The extension '.' sets the default creator and type for otherwise untyped Unix files.

File name extension mapping is useful for Mac OS 9 and earlier. However, it is not helpful on Mac OS X.

It is possible to specify default options for all volumes with a :DEFAULT: line preceding these volume definitions:

### :DEFAULT: configuration line

    :DEFAULT: options:upriv,usedots dbpath:/var/dbd/AppleDB/$v dperm:0775 fperm:0664

The possible options and their meanings are:

adouble:`[v1|v2]`

- Specify the format of the metadata files which are used for saving the Mac resource fork. Earlier versions of Netatalk used AppleDouble V1, while the current default format is V2.

volsizelimit:`size in MiB`

- Useful for Time Machine: 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. IMPORTANT: This is an approximated calculation taking into account the contents of TM sparsebundle images. Therefore you MUST NOT use this volume to store other content when using this option, because it would NOT be accounted for. The calculation works by reading the band size from the Info.plist XML file of the sparsebundle, reading the bands/ directory counting the number of band files, and then multiplying one with the other.

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 @ prefix. Example: allow:user1,user2,@group

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

allowed_hosts:`[IP host address/IP netmask bits[, ... ]]`

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

  Example: allowed_hosts:10.1.0.0/16,10.2.1.100,2001:0db8:1234::/48

denied_hosts:`[IP host address/IP netmask bits[, ...]]`

- Listed hosts and nets are rejected, all others are allowed.

  Example: denied_hosts: 192.168.100/24,10.1.1.1,2001:db8::1428:57ab

cnidscheme:`[backend]`

- set the CNID backend to be used for the volume, default is dbd

dbpath:`[path]`

- Sets the database information to be stored in path. You have to specify a writable location, even if the volume is read only.

cnidserver:`[fqdn|IP[:port]]`

- Query this servername or IP address (default:localhost) and port (default: 4700) for CNIDs. Only used with CNID backend "dbd". This option here overrides any setting from `afpd.conf`:`cnidserver`.

ea:`[none|auto|sys|ad]`

- Specify how Extended Attributes
  are stored. `auto` is the default.

  auto

- Try `sys` (by setting an EA on the shared directory itself), fallback to `ad`. Requires a writeable volume for performing the test. `options:ro` overwrites `auto` with `none`. Use explicit `ea:sys|ad` for read-only volumes where appropriate.

sys

- Use filesystem Extended Attributes.

ad

- Use files in .AppleDouble directories.

none

- No Extended Attributes support.

maccharset:`[charset]`

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

options:`[option]`

- This allows multiple options to be specified in a comma delimited format. The available options are:

  searchdb

- Use fast CNID database namesearch instead of slow recursive filesystem search. Relies on a consistent CNID database, so Samba or local filesystem access lead to inaccurate or wrong results. Works only for "dbd" CNID db volumes.

tm

- Enable Time Machine support for this volume.

invisibledots

- Use with `usedots` to make dot files invisible.

nonetids

- Try to force ACL unawareness on the client.

limitsize

- Limit disk size reporting to 2GB. This can be used for older Macintoshes using newer AppleShare clients.

ro

- Specifies the share as being read only for all users. The .AppleDB directory has to be writeable, and you can use the `-dbpath` option to relocate it. Overwrites `ea:auto` with `ea:none`

upriv

- 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: `perm|fperm|dperm`.

usedots

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

followsymlinks

- Follow symlinks on the server.

password:`[password]`

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

perm|fperm|dperm:`[mode]`

- Add(or) with the client requested permissions: `perm` affects files and directories, `fperm` is for files only, `dperm` is for directories only. Use with `options:upriv`.

  ### Volume for a collaborative workgroup

      /path/to/volume "Workgroup" options:upriv dperm:0770 fperm:0660

umask:`[mode]`

- set perm mask. Use with `options:upriv`.

rolist:[`users/groups`]

- Allows certain users and groups to have read-only access to a share. This follows the allow option format.

rwlist:`[users/groups]`

- Allows certain users and groups to have read/write access to a share. This follows the allow option format.

veto:`[vetoed names]`

- hide files and directories where the path matches one of the '/' delimited vetoed names. The veto string must always be terminated with a '/', e.g. "veto1/", "veto1/veto2/".

volcharset:`[charset]`

- specifies the volume codepage, e.g. "UTF8", "UTF8-MAC", "ISO-8859-15". Defaults to "UTF8".

## Variable substitutions

You can use variables in both volume path and volume name.

1. if you specify an unknown variable, it will not get converted.

2. if you specify a known variable, but that variable doesn't have a value, it will get ignored.

The variables which can be used for substitutions are:

$b

- basename

$c

- client's ip or appletalk address

$d

- volume pathname on server

$f

- full name (contents of the gecos field in the passwd file)

$g

- group name

$h

- hostname

$i

- client's ip, without port

$s

- server name (this can be the hostname)

$u

- user name (if guest, it is the user that guest is running as)

$v

- volume name (either ADEID_NAME or basename of path)

$z

- appletalk zone (may not exist)

$$

- prints dollar sign ($)

### Using variable substitution when defining volumes

    /home/groups/$g "Groupdir for $g"
    ~ "$f is the best one"

We define "groupdirs" for each primary group and use a personalized server name for homedir shares.

## 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 `.AppleDB` folder in the volume root.

dbd

- The "Database Daemon" backend is built on Berkeley DB. Access to the CNID database is restricted to the `cnid_metad` daemon process. `afpd` processes communicate with the daemon for database reads and updates.

last

- A simple backend without ID persistency. IDs are only valid for the current session. This is basically what `afpd` did in the 1.5 and 1.6 versions. This backend can be useful for sharing read-only filesystems, such as CR-ROMs.

  Warning: It is NOT recommended to use this backend for writable voumes, as `afpd` relies heavily on a persistent ID database. Aliases will likely not work and filename mangling is not supported.

## Charset options

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.

`afpd` 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 `usedots` is not specified, a leading dot '.' will be encoded as `:2e`.

This version now uses UTF-8 as the default encoding for names. Special characters, like '/' and a leading '.' will still be CAP style encoded .

The `-volcharset` option will allow you to select another volume encoding. E.g. for western users another useful setting could be -volcharset ISO-8859-15. `apfd` will accept any

`iconv`

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, `afpd` will convert the UTF-8
character to `-maccharset` first. If this conversion fails, you'll receive a -50 error on the mac.

Note: Whenever you can, please stick with the default UTF-8 volume format.

## Compatibility with earlier versions

To use a volume created with an earlier `afpd` version, you'll have to specify the following options:

### use a 1.x style volume

    /path/to/volume "Volname" adouble:v1 volcharset:ASCII

In case you used an NLS you could try using a compatible iconv charset for `-volcharset`.

### use a 1.x style volume, created with maccode.iso8859-1

    /path/to/volume "Volname" adouble:v1 volcharset:ISO-8859-1

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.

Note: Using above example options will allow you to downgrade to 1.x netatalk again.

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

## Advanced Options

The following options should only be used after serious consideration. Be sure you fully understood the, sometimes complex, consequences, before using them.

casefold:`[option]`

- The casefold option handles, if the case of filenames should be changed. The available options are:

  `tolower` - Lowercases names in both directions.

  `toupper` - Uppercases names in both directions.

  `xlatelower` - Client sees lowercase, server sees uppercase.

  `xlateupper` - Client sees uppercase, server sees lowercase.

options:[`option`]

- This allows multiple options to be specified in a comma delimited format. The available options are:

  caseinsensitive

- The underlying filesystem is case insensitive (only tested with JFS in OS2 mode).

crlf

- 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 switches the filetype in a second step. `afpd` will potentially destroy such files when "erroneously" changing bytes in order to do line break translation.

illegalseq

- Encode illegal sequences in filenames as is. For example "\217-", which is not a valid SHIFT-JIS char, is encoded as "U\217 -"

mswindows

- Forces filename restrictions imposed by MS WinXX. Warning: This is NOT recommended for volumes mainly used by Macs. Please make sure you fully understand this option before using it.

  This option breaks direct saving to netatalk volumes from some applications, i.e. OfficeX.

noadouble

- Forces `afpd` 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 `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 `noadouble` whenever possible.

nocnidcache

- If set, `afpd` 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.

nodev

- Always use 0 for device number, which helps when the device number is not constant across a reboot, cluster, ...

nofileid

- Don't advertise createfileid, resolveid, deleteid calls.

nohex

- Disables :hex translations for anything except dot files. This option makes the '/' character illegal.

prodos

- Provides compatibility with Apple II clients. (legacy)

## File Name Extension Mappings

### Extension is jpg. Type is "JPEG". Creator is "ogle".

    .jpg "JPEG" "ogle"

### Extension is lzh. Type is "LHA ". Creator is not defined.

    .lzh "LHA "

## See Also

afpd.conf

5 ,

afpd

8 ,

cnid_metad

8