Chapter 3. Setting up Netatalk

afpd.conf is the configuration file used by afpd to determine the behaviour and configuration of the different virtual file servers that it provides. Any line not prefixed with '#' is interpreted.

If afpd switches set on the command line are in conflict with afpd.conf settings, the latter will have higher priority.

Format: - [options] to specify options for the default server and/or "Server name" [options] to specify an additional server.

Leaving the afpd.conf file empty equals to the following configuration:

- -transall -uamlist uams_dhx.so,uams_dhx2.so

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

The AppleVolumes.default file is used to define volumes that will by default be shown to all users, including users logged in as guest. A volume will not be presented in the chooser, if the user has no read access to the specified volume path.

You can limit access to a specific volume by using the allow and deny options.

For a more detailed explanation of the available options, please refer to the AppleVolumes.default(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. As a database process gets spawned for each volume, you're probably better off using cdb for sharing home directories for a larger number of users.

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 semi-persistent backend. IDs will be reused and, what is much worse, you can get duplicate IDs. You should use it for sharing cdroms only, don't use it for sharing normal volumes.

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 $AFPD_UAM_LIST in netatalk.conf(5). 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. Fortunately this isn't such a problem these days since Mac OS X' AFP-client supports DHCAST128 from the beginning on. For older Macintoshes running Mac OS < X DHCAST128 support exists since AppleShare client 3.8.x.

On Mac 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 sent 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.

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

In detail:

Unless CUPS support has been compiled in (which is default from Netatalk 2.0 on) one simply defines the lpd queue in question by setting the pr parameter to the queue name. If no pr parameter is set, the default printer will be used.

An alternative to the technique outlined above is to direct papd's output via a pipe into another program. Using this mechanism almost all printing systems can be driven.

Starting with Netatalk 2.0, direct CUPS integration is available. In this case, defining only a queue name as pr parameter won't invoke the SysV lpd daemon but uses CUPS instead. Unless a specific PPD has been assigned using the pd switch, the PPD configured in CUPS will be used by papd, too.

There exists one special share named "cupsautoadd". If this is present in papd.conf, then all available CUPS queues will be served automagically using the parameters assigned to this global share. But subsequent printer definitions can be used to override these global settings for individual spoolers.

cupsautoadd:op=root: