# Setting up Netatalk

## File Services

Netatalk supplies two different transport protocols for AFP
services and both can run at the same time. Classic AFP over AppleTalk requires the `afpd` and `atalkd` daemons. AFP over IP only requires `afpd`.

### Setting up the AFP file server

AFP (the Apple Filing Protocol) is the protocol used on the Apple Macintosh for file services up until OS X Mountain Lion (10.8). The protocol has evolved over the years. The latest change to the protocol, AFP 3.4, was introduced with the release of OS X Mountain Lion
. Netatalk 2 supports up to AFP 3.3.

AFP3 brought some big changes. For the first time, AFP3 supports pathnames up to 65535 characters. It is virtually unlimited. Netatalk 2 supports filenames up to 255 characters because Mac OS X 10.4 and earlier can use it up to 255 characters (actually 255 bytes leading to 85-255 chars depending on the glyphs used), Decomposed UTF-8 (UTF8-MAC) is used on the wire and large files (>4GB) are supported.

The afpd daemon offers the fileservices to Apple Clients. It's configured using the `afpd.conf` and the `AppleVolumes.*` files.

Mac OS X 10.5 (Leopard) added support for Time Machine backups over AFP. Two new functions ensure that backups are written to spinning disk, not just in the server's cache. Different host operating systems honour this cache flushing differently. To make a volume a Time Machine target use the

AppleVolumes.default

5 volume option `tm`.

Starting with Netatalk 2.1 UNIX symlinks
can be used on the server. Semantics are the same as for eg NFS, i.e. they are not resolved on the server side but instead it's completely up to the client to resolve them, resulting in links that point somewhere inside the clients filesystem view.

#### afpd.conf

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.

#### AppleVolumes.default

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.

### CNID
backends

Unlike other protocols like SMB or NFS, the AFP protocol mostly refers to files and directories by ID and not by a path (the IDs are also called CNID, that means Catalog Node ID). A typical AFP request uses a directory ID
and a filename, something like "server, please open the file named 'Test' in the directory with id 167". For example "Aliases" on the Mac basically work by ID (with a fallback to the absolute path in more recent AFP clients. But this applies only to Finder, not to applications).

Every file in an AFP volume has to have a unique file ID
, IDs must, according to the specs, never be reused, and IDs are 32 bit numbers (Directory IDs use the same ID pool). So, after ~4 billion files/folders have been written to an AFP volume, the ID pool is depleted and no new file can be written to the volume. No whining please. :-)

Netatalk needs to map IDs to files and folders in the host filesystem. To achieve this, several different CNID backends
are available and can be selected with the `cnidscheme`
option in the

AppleVolumes.default

5 configuration file. A CNID backend is basically a database storing ID <-> name mappings.

The CNID Databases are by default located in the .AppleDB
folder in every afpd volume root. With the new ADv2
format, afpd stores the files/directories ID in the corresponding .AppleDouble file as well.

Starting with Netatalk 2.1 there is a command line utility called `dbd` available which can be used to verify, repair and rebuild the CNID database.

There are some CNID related things you should keep in mind when working with netatalk:

- Don't nest volumes
  .

- CNID backends are databases, so they turn afpd into a file server/database mix. Keep this in mind, killing an afpd process with `kill -9` will likely leave the database unusable.

- If there's no more space on the filesystem left, the database will get corrupted. You can work around this by either using the -dbpath option and put the database files into another location or, if you use quotas, make sure the .AppleDB folder is owned by a user/group without a quota
  .

- Be careful with CNID databases for volumes that are mounted via NFS. That is a pretty audacious decision to make anyway, but putting a database there as well is really asking for trouble, i.e. database corruption. Use the dbpath: directive in the `AppleVolumes.*` configuration files to put the databases onto a local disk if you must use NFS
  mounted volumes.

#### dbd

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.

#### last

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 read-only volumes only. Don't use it for sharing normal volumes.

### Charsets
/Unicode

#### Why Unicode?

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.

#### character sets used by Apple

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:

- MacArabic, MacFarsi

- MacCentralEurope

- MacChineseSimple

- MacChineseTraditional

- MacCroatian

- MacCyrillic

- MacDevanagari

- MacGreek

- MacHebrew

- MacIcelandic

- MacJapanese

- MacKorean

- MacRoman

- MacRomanian

- MacThai

- MacTurkish

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
.

#### afpd and character sets

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:

- MAC_CENTRALEUROPE

- MAC_CHINESE_SIMP

- MAC_CHINESE_TRAD

- MAC_CYRILLIC

- MAC_GREEK

- MAC_HEBREW

- MAC_JAPANESE

- MAC_KOREAN

- MAC_ROMAN

- MAC_TURKISH

afpd handles three different character set options:

unixcodepage

- This is the codepage used internally by your operating system. If not specified and your system support Unix locales, afpd tries to detect the codepage, otherwise it defaults to ASCII
  . afpd uses this codepage to read its configuration files, so you can use extended characters for volume names, login messages, etc. see

  afpd.conf

  5 .

maccodepage

- As already mentioned, older Mac OS clients (up to AFP 2.2) use codepages to communicate with afpd. However, there is no support for negotiating the codepage used by the client in the AFP protocol. If not specified otherwise, afpd assumes the MacRoman codepage is used. In case you're clients use another codepage, e.g. MacCyrillic, you'll have to explicitly configure this. see

  afpd.conf

  5 .

volcharset

- This defines the charset afpd should use for filenames on disk. The default is UTF8. If you have iconv
  installed, you can use any iconv provided charset as well.

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

  Even though this version now uses UTF-8 as the default encoding for filenames, special characters, like '/' and a leading '.' will still be CAP style encoded. For western users another useful setting could be -volcharset ISO-8859-15.

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

  AppleVolumes.default

  5 .

### Authentication

#### AFP authentication basics

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.

#### UAMs supported by Netatalk

Netatalk supports the following ones by default:

- "No User Authent"
  UAM (guest access without authentication)

- "Cleartxt Passwrd"
  UAM (no password encryption)

- "Randnum exchange"
  /"2-Way Randnum exchange"
  UAMs (weak password encryption, separate password storage)

- "DHCAST128"
  UAM (a.k.a. DHX; stronger password encryption)

- "DHX2"
  UAM (successor of DHCAST128)

There exist other optional UAMs as well:

- "PGPuam 1.0"
  UAM (PGP-based authentication for pre-Mac OS X clients. You'll also need the PGPuam client to let this work)

  You may have to enable it at compile time to have this UAM available.

- "Client Krb v2"
  UAM (Kerberos V, suitable for "Single Sign On" Scenarios with Mac OS X clients -- see below)

  You may have to deliberately enable this one too when compiling the code.

You can configure which UAMs should be activated by defining `$AFPD_UAM_LIST` in

netatalk.conf

5 or -uamlist in

afpd.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's AFP-client supports DHX2 out of he box. 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.

#### Which UAMs to activate?

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.

- Unless you really have to supply guest access to your server's volumes ensure that you disable "No User Authent" since it might lead accidentally to unauthorized access. In case you must enable guest access take care that you enforce this on a per volume base using the access controls the

  AppleVolumes.default

  5 config file supplies or think about setting up an own server definition serving these public shares in

  afpd.conf

  5 .

- The "ClearTxt Passwrd" UAM is as bad as it sounds since passwords go unencrypted over the wire. Try to avoid it at both the server's side as well as on the client's. Note: If you want to provide Mac OS 8/9 clients with NetBoot-services then you need uams_cleartext.so since the AFP-client integrated into the Mac's firmware can only deal with this basic form of authentication.

- Since "Randnum exchange"/"2-Way Randnum exchange" uses only 56 bit DES for encryption it should be avoided as well. Another disadvantage is the fact that the passwords have to be stored in cleartext on the server and that it doesn't integrate into both PAM scenarios or classic /etc/shadow (you have to administrate passwords separately by using the

  afppasswd

  1 utility, in order for clients to use these UAMs)

- "DHCAST128" or "DHX2" should be the sweet spot for most people since it combines stronger encryption with PAM integration.

- Using the Kerberos V
  ("Client Krb v2") UAM, it's possible to implement real single sign on scenarios using Kerberos tickets. The password is not sent over the network. Instead, the user password is used to decrypt a service ticket for the appleshare server. The service ticket contains an encryption key for the client and some encrypted data (which only the appleshare server can decrypt). The encrypted portion of the service ticket is sent to the server and used to authenticate the user. Because of the way that the afpd service principal detection is implemented, this authentication method is vulnerable to man-in-the-middle attacks.

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

#### Using different authentication sources with specific UAMs

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.

#### Netatalk UAM overview table

A small overview of the most common used UAMs.

#### Netatalk UAM overview

UAM | No User Authent | Cleartxt Passwrd | (2-Way) Randnum exchange | DHCAST128 | DHX2 | Client Krb v2
Password length | guest access | max. 8 characters | max. 8 characters | max. 64 characters | max. 256 characters | Kerberos tickets
Client support | built-in into all Mac OS versions | built-in in all Mac OS versions except 10.0. Has to be activated explicitly in recent Mac OS X versions | built-in into almost all Mac OS versions | built-in since AppleShare client 3.8.4, available as a plug-in for 3.8.3, integrated in Mac OS X' AFP client | built-in since MacOS X 10.2 | built-in since MacOS X 10.2
Encryption | Enables guest access without authentication between client and server. | Password will be sent in cleartext over the wire. Just as bad as it sounds, therefore avoid at all if possible (note: providing NetBoot services requires the ClearTxt UAM) | 8-byte random numbers are sent over the wire, comparable with DES, 56 bits. Vulnerable to offline dictionary attack. Requires passwords in clear on the server. | Password will be encrypted with 128 bit SSL, user will be authenticated against the server but not vice versa. Therefore weak against man-in-the-middle attacks. | Password will be encrypted using libgcrypt with CAST 128 in CBC mode. User will be authenticated against the server but not vice versa. Therefore weak against man-in-the-middle attacks. | Password is not sent over the network. Due to the service principal detection method, this authentication method is vulnerable to man-in-the-middle attacks.
Server support | uams_guest.so | uams_cleartxt.so | uams_randnum.so | uams_dhx.so | uams_dhx2.so | uams_gss.so
Password storage method | None | Either /etc/passwd (/etc/shadow) or PAM | Passwords stored in clear text in a separate text file | Either /etc/passwd (/etc/shadow) or PAM | Either /etc/passwd (/etc/shadow) or PAM | At the Kerberos Key Distribution Center*

* Have a look at this Kerberos overview

#### SSH tunneling

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.

##### Manually tunneling an AFP session

This works since the first AFP servers that spoke "AFP over TCP" appeared in networks. One simply tunnels the remote server's AFP port to a local port different than 548 and connects locally to this port afterwards. On MacOS X this can be done by

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

After establishing the tunnel one will use `"afp://127.0.0.1:10548"` in the "Connect to server" dialog. All AFP traffic including the initial connection attempts will be sent encrypted over the wire since the local AFP client will connect to the Mac's local port 10548 which will be forwarded to the remote server's AFP port (we used the default 548) over SSH.

This sort of tunnel is an ideal solution if you must access an AFP server through the Internet without having the ability or desire to use a "real" VPN. Note that you can let `ssh` compress the data by using its "-C" switch and that the tunnel endpoints can be different from both AFP client and server (compare with the SSH documentation for details).

##### Automatically establishing a tunneled AFP connection

From Mac OS X 10.2 to 10.4, Apple added an "Allow Secure Connections Using SSH" checkbox to the "Connect to Server" dialog. The idea behind: When the server signals that it can be contacted by SSH then Mac OS X' AFP client tries to establish the tunnel and automagically sends all AFP traffic through it.

But it took until the release of Mac OS X 10.3 that this feature worked the first time... partly. In case, the SSH tunnel can't be established the AFP client silently fell back to an unencrypted AFP connection attempt.

Netatalk's afpd will report that it is capable of handling SSH tunneled AFP requests, when both `-advertise_ssh` and `-fqdn` options are set in

afpd.conf

5 (double check with

asip-status

1 after you restarted afpd when you made changes to the settings). But there are a couple of reasons why you don't want to use this option at all:

- Most users who need such a feature are probably already familiar with using a VPN; it might be easier for the user to employ the same VPN software in order to connect to the network on which the AFP server is running, and then to access the AFP server as normal.

  That being said, for the simple case of connecting to one specific AFP server, a direct SSH connection is likely to perform better than a general-purpose VPN; contrary to popular belief, tunneling via SSH does not result in what's called "TCP-over-TCP meltdown", because the AFP data that are being tunneled do not encapsulate TCP data.

- Since this SSH kludge isn't a normal UAM that integrates directly into the AFP authentication mechanisms but instead uses a single flag signalling clients whether they can try to establish a tunnel or not, it makes life harder to see what's happening when things go wrong.

- You cannot control which machines are logged on by Netatalk tools like a `macusers` since all connection attempts seem to be made from localhost.

- Indeed, to ensure that all AFP over TCP sessions are encrypted via SSH, you need to limit afpd to connections that originate only from localhost (e.g., by using Wietse Venema's TCP Wrappers, or by using suitable firewall or packet-filtering facilities, etc.).

  Otherwise, when you're using Mac OS X 10.2 through 10.3.3, you get the opposite of what you'd expect: potentially unencrypted AFP communications (including login credentials) being sent across the network without a single notification that establishing the tunnel failed. Apple fixed that not until Mac OS X 10.3.4.

- Encrypting all AFP sessions via SSH can lead to a significantly higher load on the computer that is running the AFP server, because that computer must also handle encryption.

### ACL Support

ACL support for AFP is implemented for ZFS ACLs on Solaris and derived platforms and for POSIX 1e ACLs on Linux.

#### Configuration

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, 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, 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:

1. For Solaris/ZFS: ZFS Volumes

   You should configure a ZFS ACL know for any volume you want to use with Netatalk:

       aclinherit = passthrough
       aclmode = passthrough (if available)

   For an explanation of what this knob doea and how to apply it, check your hosts ZFS documentation (eg man zfs).

2. Authentication Domain

   Your server and the clients must be part of a security association where identity data is coming from a common source. ACLs in Darwin are based on UUIDs and so is the ACL specification in AFP 3.2. Therefore your source of identity data has to provide an attribute for every user and group where a UUID is stored as a ASCII string. In other words:

   - you need an Open Directory Server or an LDAP server where you store UUIDs in some attribute

   - your clients must be configured to use this server

   - your server should be configured to use this server via nsswitch and PAM

   - configure Netatalk via afp_ldap.conf so that Netatalk is able to retrieve the UUID for users and groups via LDAP search queries

## AppleTalk

AppleTalk, the network protocol family created by Apple, contains different protocols for different uses: address resolution, address/name mapping, service location, establishing connections, and the like.

A complete overview can be found inside the developer documentation.

### To use AppleTalk or not

You'll need the AppleTalk support built into netatalk in case you want to provide printing services via PAP by

papd

8 or file services via AppleTalk via

afpd

8 for older AFP clients not capable of using AFP over TCP. You'll need it also if you want to use the AppleTalk-based timeserver

timelord

8 for older Mac clients, or netboot server a2boot for Apple II clients.

But even if you don't need PAP or AFP over AppleTalk, you might consider using AppleTalk for service propagation/location, having the ease of use for your network clients in mind. The Apple engineers implemented a way to easily locate an AFP server via AppleTalk but establishing the AFP connection itself via AFP over TCP (see the developer documentation for details on this cool feature, too).

To use the different base AppleTalk protocols with netatalk, one has to use

atalkd

8 . It can also be used as an AppleTalk router to connect different independent network segments to each other.

To use AppleTalk/atalkd, your system has to have kernel support for AppleTalk. On some systems supported by netatalk, this isn't currently true so you can use only netatalk services that do not rely on AppleTalk. This means "AFP over TCP" and requires the -noddp switch in afpd.conf.

### No AppleTalk routing

This is the most simple form, you can use AppleTalk with netatalk. In case, you have only one network interface up and running, you haven't to deal with atalkd's config at all: atalkd will use AppleTalk's self-configuration features to get an AppleTalk address and to register itself in the network automagically.

In case, you have more than one active network interface, you have to make a decision:

- Using only one interface: Just add the interface name (en1, le0, eth2, ... for example) to atalkd.conf on a single line. Do only list one interface here.

  #### atalkd.conf containing one entry

      eth0

  AppleTalk networking should be enabled on eth0 interface. All the necessary configuration will be fetched from the network

  At startup time, atalkd will add the real settings (address and network and eventually a zone) to atalkd.conf on its own

  #### atalkd.conf containing one entry after atalkd started

      eth0 -phase 2 -net 0-65534 -addr 65280.166

  atalkd filled in the AppleTalk settings that apply to this network segment. A netrange of 0-65534 indicates that there is no AppleTalk router present, so atalkd will fetch an address that matches the following criteria: netrange from inside the so called "startup range" 65280-65533 and a node address between 142 and 255.

- When using several interfaces you have to add them line by line following the -dontroute switch in atalkd.conf.

  #### atalkd.conf containing several entries with the -dontroute option

      eth0 -dontroute eth1 -dontroute eth2 -dontroute

  Appletalk networking should be enabled on all three interfaces, but no routing should be done between the different segments. Again, all the necessary configuration will be fetched from the connected networks.

  #### atalkd.conf containing several entries with the -dontroute option after atalkd started

      eth0 -dontroute -phase 2 -net 0-65534 -addr 65280.152
      eth1 -dontroute -phase 2 -net 0-65534 -addr 65280.208
      eth2 -dontroute -phase 2 -net 1-1000 -addr 10.142 -zone "Printers"

  On eth0 and eth1, there are no other routers present, so atalkd chooses an address from within the startup range. But on eth2 there lives an already connected AppleTalk router, publishing one zone called "Printers" and forcing clients to assign themselves an address in a netrange between 1 and 1000.

  In this case, atalkd will handle each interface as it would be the only active one. This can have some side effects when it comes to the point where AFP clients want to do the magic switch from AppleTalk to TCP, so use this with caution.

In case, you have more than one active network interface and do not take special precautions as outlined above, then autoconfiguration of the interfaces might fail in a situation where one of your network interfaces is connected to a network where no other active AppleTalk router is present and supplies appropriate routing settings.

For further information see

atalkd.conf

5 and the developer documentation.

### atalkd acting as an AppleTalk router

There exist several types of AppleTalk routers: seed, non-seed and so called soft-seed routers.

- A seed router has its own configuration and publishes this into the network segments it is configured for.

- A non-seed router needs a seed router on the interface to which it is connected to learn the network configuration. So this type of AppleTalk router can work completely without manual configuration.

- A so called soft-seed router is exactly the same as a non-seed router except the fact, that it can also remember the configuration of a seed router and act as a replacement in case, the real seed router disappears from the net.

Netatalk's atalkd can act as both a seed and a soft-seed router, even in a mixed mode, where it acts on one interface in this way and on the other in another.

If you leave your atalkd.conf completely empty or simply add all active interfaces line by line without using seed settings (atalkd will act identically in both cases), then atalkd is forced to act as a soft-seed router on each interface, so it will fail on the first interface, where no seed router is accessible to fetch routing information from.

In this case, other services, that depend on atalkd, might also fail.

So you should have atalkd act as a seed router on one or all active interfaces. A seed router has to supply informations about:

- The specific netrange on this segment

- Its own AppleTalk address

- The zones (one to many) available in this segment

- The so called "default zone" for this segment

Unless you are the network admin yourself, consider asking her/him before changing anything related to AppleTalk routing, as changing these settings might have side effects for all of your AppleTalk network clients!

In an AppleTalk network netranges have to be unique and must not overlap each other. Fortunately netatalk's atalkd is polite enough to check whether your settings are in conflict with already existing ones on the net. In such a case it simply discards your settings and tries to adapt the already established ones on the net (if in doubt, always check syslog for details).

Netranges, you can use, include pretty small ones, eg. 42-42, to very large ones, eg. 1-65279 - the latter one representing the maximum. In routed environments you can use any numbers in the range between 1 and 65279 unless they do not overlap with settings of other connected subnets.

The own AppleTalk address consists of a net part and a node part (the former 16 bit, the latter 8 bit, for example 12057.143). Apple recommends using node addresses of 128 or above for servers, letting client Macs assign themselves an address faster (as they will primarily search for a node address within 1-127 in the supplied netrange). As we don't want to get in conflict with Apple servers, we prefer using node addresses of 142 or above.

AppleTalk zones have nothing to do with physical networks. They're just a hint for your client's convenience, letting them locate network resources in a more comfortable/faster way. You can either use one zone name across multiple physical segments as well as more than one zone name on a single segment (and various combinations of this).

So all you have to do is to draw a network chart containing the physical segments, the netranges you want to assign to each one, the zone names you want to publish in which segments and the default zone per segment (this is always the first zone name, you supply with the -zone switch in atalkd.conf).

Given, you finished the steps outlined above, you might want to edit atalkd.conf to fit your needs.

You'll have to set the following options in atalkd.conf:

- -net (use reasonable values between 1-65279 for each interface)

  In case, this value is suppressed but -addr is present, the netrange from this specific address will be used

- -addr (the net part must match the -net settings if present, the node address should be between 142 and 255)

- -zone (can be used multiple times in one single line, the first entry is the default zone)

Note that you are able to set up "zone mapping", that means publishing exactly the same zone name on all AppleTalk segments, as well as providing more than one single zone name per interface. Dumb AppleTalk devices, like LaserWriters, will always register themselves in the default zone (the first zone entry you use in atalkd.conf per interface), more intelligent ones will have the ability to choose one specific zone via a user interface.

#### atalkd.conf making netatalk a seed router on two interfaces

    eth0 -seed -phase 2 -net 1-1000 -addr 1000.142 -zone "Printers" -zone "Spoolers"
    eth1 -seed -phase 2 -net 1001-2000 -addr 2000.142 -zone "Macs" -zone "Servers"

The settings for eth0 force AppleTalk devices within the connected network to assign themselves an address in the netrange 1-1000. Two zone names are published into this segment, "Printers" being the so called "standard zone", forcing dumb AppleTalk devices like Laser printers to show up automatically into this zone. AppleTalk printer queues supplied by netatalk's papd can be registered into the zone "Spoolers" simply by adjusting the settings in

papd.conf

5 . On eth1 we use the different and non-overlapping netrange 1001-2000, set the default zone to "Macs" and publish a fourth zone name "Servers".

#### atalkd.conf configured for "zone mapping"

    eth0 -seed -phase 2 -net 1-1000 -addr 1000.142 -zone "foo"
    lo0 -phase 1 -net 1 -addr 1.142 -zone "foo"

We use the same network settings as in the example above but let atalkd publish the same zone name on both segments. As the same zone name will be used on all segments of the AppleTalk network no zone names will show up at all... but AppleTalk routing will still be active. In this case, we connect a so called "non-extended" LocalTalk network (phase 1) to an EtherTalk "extended" network (phase 2) transparently.

#### atalkd.conf for a soft-seed router configuration

    eth0 eth1 eth2

As we have more than one interface, atalkd will try to act as an AppleTalk router between both segments. As we don't supply any network configuration on our own we depend on the availability of seed routers in every connected segment. If only one segment is without such an available seed router the whole thing will fail.

#### atalkd.conf for a soft-seed router configuration after atalkd started

    eth0 -phase 2 -net 10-10 -addr 10.166 -zone "Parking"
    eth1 -phase 2 -net 10000-11000 -addr 10324.151 -zone "No Parking" -zone "Parking"
    eth2 -phase 2 -net 65279-65279 -addr 65279.142 -zone "Parking" -zone "No Parking"

In this case, active seed routers are present in all three connected networks, so atalkd was able to fetch the network configuration from them and, since the settings do not conflict, act as a soft-seed router from now on between the segments. So even in case, all of the three seed routers would disappear from the net, atalkd would still supply the connected network with the network configuration once learned from them. Only in case, atalkd would be restarted afterwards, the routing information will be lost (as we're not acting as seed router).

#### atalkd.conf ready for mixed seed/soft-seed mode

    eth0
    eth1 -seed -phase 2 -net 99-100 -addr 99.200 -zone "Testing"

In case in the network connected to eth0 lives no active seed router or one with a mismatching configuration (eg. an overlapping netrange of 1-200) atalkd will fail. Otherwise it will fetch the configuration from this machine and will route between eth0 and eth1, on the latter acting as a seed router itself.

By the way: It is perfectly legal to have more than one seed router connected to a network segment. But in this case, you should take care that the configuration of all connected routers is exactly the same regarding netranges, published zone names and also the "standard zone" per segment

## Printing

Netatalk can act as both a PAP
client to access AppleTalk-capable printers and a PAP server. The former by using the

`pap`

1 utility and the latter by starting the

`papd`

8 service.

The "Printer Access Protocol" as part of the AppleTalk protocol suite is a fully 8 bit aware and bidirectional printing protocol, developed by Apple in 1985. 8 bit aware means that the whole set of bytes can be used for printing (binary encoding). This has been a great advantage compared with other protocols like Adobe's Standard Protocol to drive serial and parallel PostScript printers (compare with Adobe TechNote 5009) or LPR
which made only use of the lower 128 bytes for printing because the 8th bit has been reserved for control codes.

Bidirectional means that printing source (usually a Macintosh computer) and destination (a printer or spooler implementation) communicate about both destination's capabilities via feature queries (compare with Adobe TechNote 5133) and device status. This allows the LaserWriter driver on the Macintosh to generate appropriate device specific PostScript code (color or b/w, only embedding needed fonts, and so on) on the one hand and notifications about the printing process or problems (paper jam for example) on the other.

### Setting up the PAP print server

Netatalk's `papd` is able to provide AppleTalk printing services for Macintoshes or, to be more precise, PAP clients in general. Netatalk does not contain a full-blown spooler implementation itself, papd only handles the bidirectional communication and submittance of printjobs from PAP clients. So normally one needs to integrate papd with a Unix printing system like eg. classic SysV lpd
, BSD lpr
, LPRng
, CUPS
or the like.

Since it is so important to answer the client's feature queries correctly, how does papd achieve this? By parsing the relevant keywords of the assigned PPD
file. That said, it's always necessary to carefully choose the right PPD at the server's side.

Netatalk formerly had built-in support for System V lpd printing in a way that papd saved the printed job directly into the spooldir and calls `lpd` afterwards, to pick up the file and do the rest. Due to incompatibilities with many lpd implementations the normal behaviour was to print directly into a pipe instead of specifying a printer by name and using lpd interaction. With Netatalk 2.0 another alternative has been implemented: direct interaction with CUPS (Note: when CUPS support is compiled in, then the SysV lpd support doesn't work at all). Detailed examples can be found in the

papd.conf

5 manual page.

#### Integrating `papd` with SysV lpd

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.

#### Using pipes with `papd`

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.

#### Using direct CUPS support

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.

##### Example syntax, assigning root as operator:

    cupsautoadd:op=root:

### Using AppleTalk printers

Netatalk's

`papstatus`

8 can be used to query AppleTalk printers,

`pap`

1 to print to them. With

`psf`

8 there exists a lpd filter program suitable for converting other formats (like text) to PostScript output, do page accounting
and eventually change the page order using

`psorder`

1 . But these days, modern printing systems like CUPS can do the latter tasks for themselves in a more reliable way.

`pap` can be used stand-alone or as part of an output filter or a CUPS backend
(which is the preferred method since one does not have to deal with all the options).

#### `pap` printing to a PostScript LaserWriter

    pap -p"ColorLaserWriter 16/600@*" /usr/share/doc/gs/examples/tiger.ps

The file `/usr/share/doc/gs/examples/tiger.ps` is sent to a printer called "ColorLaserWriter 16/600" in the standard zone "*". The device type is "LaserWriter" (can be suppressed since it is the default).

#### `pap` printing to a non-PostScript printer

    gs -q -dNOPAUSE -sDEVICE=cdjcolor -sOutputFile=test.ps | pap -E

GhostScript is used to convert a PostScript job to PCL3 output suitable for a Color DeskWriter. Since no file has been supplied on the command line, `pap` reads the data from stdin. The printer's address will be read from the `.paprc` file in the same directory, `pap` will be called (in our example simply containing "Color DeskWriter:DeskWriter@Printers"). The `-E` switch forces `pap` to not wait for an EOF from the printer.

## Time Services

### Using Netatalk as a time server for Macintoshes

`timelord`
, an AppleTalk based time server, is useful for automatically synchronizing the system time on older Macintosh or Apple II clients that do not support NTP
.

Netatalk's `timelord` is compatible with the tardis client for Macintosh developed at the University of Melbourne.

For further information please have a look at the

timelord

8 manual page.