Chapter 3. Setting up Netatalk

afp.conf is the configuration file used by afpd to determine the behaviour and configuration of the AFP file serverand 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 whos path is /home/NAME.

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

The following configuration is required:

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

If basedir regex contains 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 "concurrent database" backend is based on Berkeley DB. With this backend, several afpd daemons access the CNID database directly. Berkeley DB locking is used to synchronize access, if more than one afpd process is active for a volume. The drawback is, that the crash of a single afpd process might corrupt the database. cdb should only be used when sharing home directories for a larger number of users and it has been determined that a large number of cnid_dbd processes is problematic.

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.

tdb is another persistent CNID database, it's Samba's Trivial Database. It could be used instead of cdb for user volumes.

This backend is also used internally (as in-memory CNID database) as a fallback in case opening the primary database can't be opened, because tdb can work as in-memory database. This of course means upon restart the CNIDs are gone.

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

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, AFP 2.x clients use one of the Apple codepages.

At the time of this 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.pl(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, eg. 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 all sort of VPN stuff has nothing to do with AFP authentication and UAMs in general. But since Apple introduced an option called "Allow Secure Connections Using SSH" and many people tend to confuse both things, we'll speak about that here too.

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. For example folder whos UNIX mode would only result in in read-only permissions for a user will not be displayed with a read-only icon and the user will be able to write to the folder given the folder has an ACL giving the user write access.

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 Terminal will you be able to see the ACLs, that's a result 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, eg LDAP, OpenDirectory). The reason is, that in OS X ACLs are bound to UUIDs, not just uid's or gid's. Therefor 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.