Chapter 3. Setting up Netatalk

afp.conf is the configuration file used by afpd to determine the behaviour and configuration of the AFP file server and the AFP volume that it provides.

The afp.conf is divided into several sections:

Any section not called Global or Homes is interpreted as an AFP volume.

For sharing user homes by defining a Homes section you must specify the option basedir regex which can be a simple string with the path to the parent directory of all user homes or a regular expression.

Example:

[Homes]
basedir regex = /home

Now any user logging into the AFP server will have a user volume available whose path is /home/NAME.

A more complex setup would be a server with a large amount of user homes which are split across e.g. two different filesystems:

The following configuration is required:

[Homes]
basedir regex = /RAID./.*homes

If basedir regex contains a symlink, set the canonicalized absolute path. When /home links to /usr/home:

[Homes]
basedir regex = /usr/home

For a more detailed explanation of the available options, please refer to the afp.conf(5) man page.

The "Database Daemon" backend is built on Berkeley DB. Access to the CNID database is restricted to the cnid_dbd daemon process. afpd processes communicate with the daemon for database reads and updates. The probability for database corruption is practically zero.

This is the default backend since Netatalk 2.1.

The last backend is an in-memory tdb database. It is not persistent. Starting with netatalk 3.0, it operates in read only mode automatically. This is useful e.g. for CD-ROMs.

CNID backend using a MySQL server. It gets automatically configured if the MySQL client development libraries are detected. Disable it through the mysql-config setting of the build system.

Internally, computers don't know anything about characters and texts, they only know numbers. Therefore, each letter is assigned a number. A character set, often referred to as charset or codepage, defines the mappings between numbers and letters.

If two or more computer systems need to communicate with each other, the have to use the same character set. In the 1960s the ASCII (American Standard Code for Information Interchange) character set was defined by the American Standards Association. The original form of ASCII represented 128 characters, more than enough to cover the English alphabet and numerals. Up to date, ASCII has been the normative character scheme used by computers.

Later versions defined 256 characters to produce a more international fluency and to include some slightly esoteric graphical characters. Using this mode of encoding each character takes exactly one byte. Obviously, 256 characters still wasn't enough to map all the characters used in the various languages into one character set.

As a result localized character sets were defined later, e.g the ISO-8859 character sets. Most operating system vendors introduced their own characters sets to satisfy their needs, e.g. IBM defined the codepage 437 (DOSLatinUS), Apple introduced the MacRoman codepage and so on. The characters that were assigned number larger than 127 were referred to as extended characters. These character sets conflict with another, as they use the same number for different characters, or vice versa.

Almost all of those characters sets defined 256 characters, where the first 128 (0-127) character mappings are identical to ASCII. As a result, communication between systems using different codepages was effectively limited to the ASCII charset.

To solve this problem new, larger character sets were defined. To make room for more character mappings, these character sets use at least 2 bytes to store a character. They are therefore referred to as multibyte character sets.

One standardized multibyte charset encoding scheme is known as unicode. A big advantage of using a multibyte charset is that you only need one. There is no need to make sure two computers use the same charset when they are communicating.

In the past, Apple clients used single-byte charsets to communicate over the network. Over the years Apple defined a number of codepages, western users will most likely be using the MacRoman codepage.

Codepages defined by Apple include:

Starting with Mac OS X and AFP3, UTF-8 is used. UTF-8 encodes Unicode characters in an ASCII compatible way, each Unicode character is encoded into 1-6 ASCII characters. UTF-8 is therefore not really a charset itself, it's an encoding of the Unicode charset.

To complicate things, Unicode defines several normalization forms. While samba uses precomposed Unicode, which most Unix tools prefer as well, Apple decided to use the decomposed normalization.

For example lets take the German character 'ä'. Using the precomposed normalization, Unicode maps this character to 0xE4. In decomposed normalization, 'ä' is actually mapped to two characters, 0x61 and 0x308. 0x61 is the mapping for an 'a', 0x308 is the mapping for a COMBINING DIAERESIS.

Netatalk refers to precomposed UTF-8 as UTF8 and to decomposed UTF-8 as UTF8-MAC.

To support new AFP 3.x and older AFP 2.x clients at the same time, afpd needs to be able to convert between the various charsets used. AFP 3.x clients always use UTF8-MAC, while AFP 2.x clients use one of the Apple codepages.

At the time of writing, netatalk supports the following Apple codepages:

afpd handles three different character set options:

Apple chose a flexible model called "User Authentication Modules" (UAMs) for authentication purposes between AFP client and server. An AFP client initially connecting to an AFP server will ask for the list of UAMs which the server provides, and will choose the one with strongest encryption that the client supports.

Several UAMs have been developed by Apple over the time, some by 3rd-party developers.

Netatalk supports the following ones by default:

There exist other optional UAMs as well:

You can configure which UAMs should be activated by defining "uam list" in Global section. afpd will log which UAMs it's using and if problems occur while activating them in either netatalk.log or syslog at startup time. asip-status(1) can be used to query the available UAMs of AFP servers as well.

Having a specific UAM available at the server does not automatically mean that a client can use it. Client-side support is also necessary. For older Macintoshes running Mac OS < X DHCAST128 support exists since AppleShare client 3.8.x.

On OS X, there exist some client-side techniques to make the AFP-client more verbose, so one can have a look what's happening while negotiating the UAMs to use. Compare with this hint.

It depends primarily on your needs and on the kind of Mac OS versions you have to support. Basically one should try to use DHCAST128 and DHX2 where possible because of its strength of password encryption.

For a more detailed overview over the technical implications of the different UAMs, please have a look at Apple's File Server Security pages.

Some UAMs provide the ability to use different authentication "backends", namely uams_cleartext.so, uams_dhx.so and uams_dhx2.so. They can use either classic Unix passwords from /etc/passwd (/etc/shadow) or PAM if the system supports that. uams_cleartext.so can be symlinked to either uams_passwd.so or uams_pam.so, uams_dhx.so to uams_dhx_passwd.so or uams_dhx_pam.so and uams_dhx2.so to uams_dhx2_passwd.so or uams_dhx2_pam.so.

So, if it looks like this in Netatalk's UAMs folder (per default /etc/netatalk/uams/):

uams_clrtxt.so -> uams_pam.so
uams_dhx.so -> uams_dhx_pam.so
uams_dhx2.so -> uams_dhx2_pam.so

then you're using PAM, otherwise classic Unix passwords. The main advantage of using PAM is that one can integrate Netatalk in centralized authentication scenarios, e.g. via LDAP, NIS and the like. Please always keep in mind that the protection of your user's login credentials in such scenarios also depends on the strength of encryption that the UAM in question supplies. So think about eliminating weak UAMs like "ClearTxt Passwrd" and "Randnum exchange" completely from your network.

A small overview of the most common used UAMs.

* Have a look at this Kerberos overview

Tunneling and VPNs usually have nothing to do with AFP authentication and UAMs. But since Apple introduced an option called "Allow Secure Connections Using SSH" and many people tend to confuse the two, we'll cover this here.

ssh -l $USER $SERVER -L 10548:127.0.0.1:548 sleep 3000

For a basic mode of operation there's nothing to configure. Netatalk reads ACLs on the fly and calculates effective permissions which are then send to the AFP client via the so called UARights permission bits. On a Mac, the Finder uses these bits to adjust permission in Finder windows. Example: a folder whose UNIX mode is read-only and an ACL giving the user write access, will display the effective read-write permission. Without the permission mapping the Finder would display a read-only icon and the user wouldn't be able to write to the folder.

By default, the effective permission of the authenticated user are only mapped to the mentioned UARightspermission structure, not the UNIX mode. You can adjust this behaviour with the configuration option map acls.

However, neither in Finder "Get Info" windows nor in the Terminal will you be able to see the ACLs, because of how ACLs in OS X are designed. If you want to be able to display ACLs on the client, things get more involved as you must then setup both client and server to be part on a authentication domain (directory service, e.g. LDAP, OpenDirectory). The reason is, that in OS X ACLs are bound to UUIDs, not just uid's or gid's. Therefore afpd must be able to map every filesystem uid and gid to a UUID so that it can return the server side ACLs which are bound to UNIX uid and gid mapped to OS X UUIDs.

Netatalk can query a directory server using LDAP queries. Either the directory server already provides an UUID attribute for user and groups (Active Directory, Open Directory) or you reuse an unused attribute (or add a new one) to you directory server (eg OpenLDAP).

In detail:

With Access Control Lists (ACLs) Mac OS X offers a powerful extension of the traditional UNIX permissions model. An ACL is an ordered list of Access Control Entries (ACEs) explicitly granting or denying a set of permissions to a given user or group.

Unlike UNIX permissions, which are bound to user or group IDs, ACLs are tied to UUIDs. For this reason accessing an object's ACL requires server and client to use a common directory service which translates between UUIDs and user/group IDs.

ACLs and UNIX permissions interact in a rather simple way. As ACLs are optional UNIX permissions act as a default mechanism for access control. Changing an objects's UNIX permissions will leave it's ACL intact and modifying an ACL will never change the object's UNIX permissions. While doing access checks, OS X first examines an object's ACL evaluating ACEs in order until all requested rights have been granted, a requested right has been explicitly denied by an ACE or the end of the list has been reached. In case there is no ACL or the permissions granted by the ACL are not sufficient to fulfill the request, OS X next evaluates the object's UNIX permissions. Therefore ACLs always have precedence over UNIX permissions.

ZFS ACLs closely match OS X ACLs. Both offer mostly identical fine grained permissions and inheritance settings.

You can enable Spotlight and indexing either globally or on a per volume basis with the spotlight option.

The dbus-daemon binary has to be installed for Spotlight feature. The path to dbus-daemon is determined at compile time the dbus-daemon build system option.

In case the dbus-daemon binary is installed at the other path, you must use the global option dbus daemon to point to the path, e.g. for Solaris with Tracker from OpenCSW:

dbus daemon = /opt/csw/bin/dbus-daemon

Netatalk must be running, commands must be executed as root and some environment variables must be set up.

If the .tracker_profile file does not exist, create it first. If you need to make the environment variables persistent, source .tracker_profile from /root/.profile. If needed, adjust PREFIX to point to the base directory Netatalk is installed to, and replace "/var" with the localstate directory configured at compile time.

$ su
      # cat .tracker_profile
      PREFIX="/usr/local"
      export XDG_DATA_HOME="$PREFIX/var/netatalk/"
      export XDG_CACHE_HOME="$PREFIX/var/netatalk/"
      export DBUS_SESSION_BUS_ADDRESS="unix:path=$PREFIX/var/netatalk/spotlight.ipc"
      # . .tracker_profile
      #
      

When using Tracker from OpenCSW you must also update your PATH:

# export PATH=/opt/csw/bin:$PATH

# gsettings list-recursively | grep Tracker
org.freedesktop.Tracker.Writeback verbosity 'debug'
...

The following table lists the supported Spotlight metadata attributes