netatalk

netatalk.io

Compatibility details for Netatalk Client

A. Login methods

The following UAMs are implemented, in order of preference and security (most secure last):

Note that UAMs in bold are the encrypted ones, and will be built only when the libgcrypt library is available. By default, Mac OS X 10.5 and later only support encrypted UAMs, while modern macOS only supports DHX2. SRP is supported by Time Capsule, also known as “account based authentication”.

‘status’ will show you what UAMs are compiled in and what is being used.

B. Connect, disconnect

There are basic facilities to receive and send session keys, but these are not used.

Server disconnect and reconnect can be done with the FUSE client, with the afpc fs suspend and resume commands.

The client doesn’t recover if the server goes down partway through a transaction.

C. UID and GID mapping

One area of complication is around UID and GID mappings. These may differ between the client and server. There are two modes that are enabled in Netatalk Client:

Common user directory

This is where both the client and server have identical UIDs and GIDs. This is the case where you have an NIS server between them, or some other common directory.

Login IDs

This is where all the files appear as the user that logged in. This would typically be used where the databases are separate, and one user expects to be able to read/write all the files he sees. This can get confusing, since any files that aren’t his will appear to be owned by him, but writing to them will result in an EPERM.

Named mapping

This is where the name (not uid) of the owner is mapped correctly. This is not implemented.

Mapping from file

This is where a file is read that translates client and server ids. This is not implemented.

Netatalk Client attempts to detect the mapping type automatically; do ‘afpc fs status’ (for FUSE mounts) or ‘status’ within afpcmd to see what it guessed.

D. Meta information

Server icon

A readonly copy of the server icon can be found in /.servericon.

Resource forks

Depending on the AFP server type and version, Classic Mac OS resource forks may be stored as filesystem extended attributes or in AppleDouble sidecar files. The exact manner of storage is determined by the client and operating system.

Desktop functions

a) Comments

The only desktop function that’s actually implemented is comments. For file /dir/foo, they can be found in /dir/.AppleDouble/file.comment

Permissions for the comment are the same as the data fork.

  1. Catalog searching
  2. Icon searching
  3. APPL
  4. Finder info

1 through 3 are not really suitable as a filesystem. But you could get access to them if you wrote your own client.

Finder info for files and directories for /dir/foo can be found in /dir/.AppleDouble/foo.finderinfo.

E. ACLs and extended attributes

ACLs

ACLs have not been implemented.

Extended Attributes (AFP 3.2+)

Extended attributes (EAs) are supported for servers that support AFP 3.2 or later (including netatalk 3.0+). This allows preservation of macOS metadata like Finder tags, quarantine flags, and other file attributes.

Supported Operations

Platform-Specific Behavior

Linux

On Linux, extended attributes work fully across all operations. Linux requires the user. namespace prefix for user-defined attributes:

# Set an EA (automatically adds "user." prefix for AFP protocol)
setfattr -n user.myattr -v "myvalue" /mnt/afp/file.txt

# Read an EA
getfattr -n user.myattr /mnt/afp/file.txt

# List all EAs
getfattr -d /mnt/afp/file.txt

# Copy files with EAs preserved
cp -a source.txt /mnt/afp/          # GNU cp with -a flag
rsync -aX source.txt /mnt/afp/      # rsync with -X flag
macOS

On macOS, EA read, write, and list operations work correctly.

# List EAs
xattr -l /Volumes/afp/file.txt

# Read EA
xattr -p com.apple.metadata:kMDLabel /Volumes/afp/file.txt

# Write EA
xattr -w user.test "value" /Volumes/afp/file.txt

# Copying files with EAs
cp file.txt /Volumes/afp/
FreeBSD

On FreeBSD, all EA operations work correctly with setextattr and getextattr commands:

# Set an EA
setextattr user myattr "myvalue" /mnt/afp/file.txt

# Read an EA
getextattr user myattr /mnt/afp/file.txt

# List all EAs
lsextattr user /mnt/afp/file.txt

# Remove an EA
rmextattr user myattr /mnt/afp/file.txt

Important: FreeBSD’s native cp command does not preserve extended attributes, even with the -p flag. This is a known limitation of FreeBSD’s base system (see FreeBSD bug #240146).

To copy files with extended attributes preserved on FreeBSD:

# Use rsync with -X flag
rsync -aX source.txt /mnt/afp/

EA Filtering

Netatalk Client automatically filters internal server metadata to prevent corruption:

All other extended attributes, including macOS system attributes like com.apple.*, are transmitted to and stored on the server as expected.

Server Requirements

F. Internationalization

For servers that support it, UTF8 usernames, server names, volume names and files are supported.

Older clients (Mac OS 9) that don’t use filenames of type long. Other charsets for files (MacRomanian, etc) are not supported properly. Servernames are supported.

G. Networks

IPv6: As of v0.8.2, we have support for IPv6. IPv4: Yes, of course. Appletalk: There is no support for Appletalk.

There’s no concept of multiple protocols, eg. doing getstatus with one protocol, then connecting with another, which is what some Apple clients do.

afpc discover browses _afpovertcp._tcp and companion _device-info._tcp services advertised through Bonjour/DNS-SD or Avahi. It associates matching advertisements, extracts the device model, and resolves the AFP target host, port, interface, and addresses. Human-readable, verbose, and JSON output modes are available.

afpcmd --browse shows a live service picker with stable selection numbers. The picker contains advertised services and quit only; a known host is supplied as an AFP URL on the command line. After service selection, afpcmd prompts for a username and hidden password; an empty username requests guest access. FUSE mounts can use an exact advertised name with afpc fs mount --service; --volume selects a volume to mount, while omitting it lists the volumes available after authentication. Service lookup is non-interactive and there is no mount browser.

H. Server-specific information

Netatalk Client detects the server type by parsing the Machine Type field in getstatus. The command line ‘afpgetstatus’ will show this without you having to log in. ‘status’ will show you this also.

The detection is done in order to deal with some details.

Mac OS 8 and earlier

Netatalk Client has never been used with Mac OS 8 and earlier versions, so there’s no data.

Mac OS 9

This speaks AFP 2.1 or 2.2, which presents certain restrictions, such as:

Out of the classic Mac OS charsets, only MacRoman is supported presently.

Mac OS X

Various versions of the Mac OS X personal file sharing have been tested, including 10.2, 10.3, 10.4, 10.5, and 10.7. Note the restrictions on UAMs above.

Airport Extreme

The airport extreme with firmware 7.1 and 7.2.1 has been tested, and has two oddities:

Note that the Airport can serve up SMB and AFP disks; Netatalk Client only handles AFP.

Time Capsule

The Time Capsule is a network backup device meant to handle Time Machine backups over AFP. It supports the SRP, DHX2, and DHCAST128 UAMs.

It can also be used as a general purpose AFP file server, which has been tested with Netatalk Client. It has one notable quirk: it can take up to 20 seconds for the server to respond when the hard drive is spun down. For this purpose, Netatalk Client applies a 30 second timeout for AFP connections when a Time Capsule is detected, instead of the default 5 second timeout.

Tested against AirPort Time Capsule A1470 with firmware 7.9.1.

Netatalk

Netatalk Client was forked from afpfs-ng with the intention of being developed as a companion client to the Netatalk AFP server project.

You must use Netatalk 2.0.4 or later because earlier versions of the server has broken Unix privilege support, notably when setting the execute bit.

NAS devices by LaCie, Synology, and other vendors

Historically, most NAS devices with AFP support have bundled Netatalk 2.x or 3.x, so they are expected to work with Netatalk Client.

I. FUSE-specific bugs

There are no facilities for automounting home directories, which is something that people ask for frequently. This requires having integration into open directory.

J.Other

Deliberately left blank.

K. References

Not all references are easy to find. The useful ones are: