Upgrading from prior Netatalk versions

Upgrading from Netatalk 4.5

Netatalk 4.6 changes how the credential store used by the SRP UAM is maintained. Review the following steps before starting the new server if uams_srp.so is enabled.

afppasswd invocation

afppasswd again accepts -p path for a non-default credential store. In SRP mode, path is the verifier directory and must match srp verifier path in afp.conf. With -r, it is the Randnum password file and must match passwd file. The compiled-in default covers packaged installations.

For example, with a srp verifier path setting of /path/to/verifiers, run:

sudo afppasswd -p /path/to/verifiers -a alice

Regular users may use -p when changing their own SRP verifier. It grants no additional privilege: filesystem permissions enforce access, so selecting someone else’s store results in an access error.

SRP verifier migration

SRP no longer uses one shared afppasswd.srp flat file. Its configured path is now a root-owned verifier directory containing one file for each numeric uid. Each verifier file is mode 0600. Active verifiers are user-owned, allowing enrolled users to change their own SRP password without giving afppasswd elevated privileges. Disabled placeholders are root-owned and cannot be enabled by the corresponding local user. Root enrolls a user with afppasswd -a username: ownership is transferred to the user only after a real verifier has been written and synchronized.

If a restore changes an enrolled verifier’s ownership or mode, stop afpd and repair that uid-named file as root before restarting it. Restore ownership to the matching local user and mode 0600; for example, alice’s verifier at a custom path can be repaired with chown alice /path/to/verifiers/$(id -u alice) followed by chmod 0600 on that file. Do not apply this to root-owned disabled placeholders: use afppasswd -a username to set a password and re-enable the account. A verifier with more than one hard link must be replaced or have its additional links removed.

In afp.conf, the new srp verifier path option replaces the old srp passwd file option. The old name is still accepted as a deprecated alias, but its value is now interpreted as a directory and logs a migration warning.

Existing SRP credentials must be migrated before users can log in with their existing passwords. The migration is performed with afppasswd -m.

1. Stop netatalk and keep it stopped for the complete migration.

2. If your afp.conf explicitly configures the srp passwd file path, update it to the srp verifier path option pointing to the location of the existing flat file to be migrated.

3. Run the migration as root. For the standard configuration, use:

   sudo afppasswd -m

If the verifier path is non-default, pass that directory:

   sudo afppasswd -m -p /path/to/verifiers

The migration preserves the existing salts and verifiers, so users keep their SRP passwords. Active credentials become user-owned; disabled placeholders remain root-owned and require root’s afppasswd -a before use. It validates all records and local accounts, creates the new directory atomically, and retains the original flat file as afppasswd.srp.legacy (or a numbered sibling). Do not start netatalk if migration reports a failure; resolve the reported condition first.

1. Start netatalk and test an SRP login. Thereafter, a local user changes that user’s SRP password simply with afppasswd. An administrator uses afppasswd -a username to set or reset a user’s SRP credential.

Alternatively, if retaining user passwords is not desired: delete the legacy file, typically at /etc/netatalk/afppasswd.srp, and initialize a new store with afppasswd -c. This creates root-owned disabled placeholders; set passwords individually as root with afppasswd -a username to enroll users.

After enrollment, users own their verifier and can replace it directly. The old-password proof and optional CrackLib check in afppasswd do not enforce server-wide password policy. To disable future SRP logins for a user, run afppasswd -d username as root. It replaces the uid verifier with a root-owned disabled placeholder (and creates one if it is absent); use afppasswd -a username to set a password and re-enable the account. Existing sessions and other UAMs are unaffected.

Randnum hardening

Randnum remains a legacy, weak UAM intended only for old clients. Managing its afppasswd file is now root-only: use afppasswd -r -a username to reset or update a Randnum credential.

Upgrading from Netatalk 3

Upgrading to Netatalk 4 from Netatalk 3 is trivial. Just install the new version on top of the old one. The primary difference is that Netatalk 4 brings back essential AppleTalk services, configuration files, and tools that were removed between Netatalk 2 and Netatalk 3.

Notably, the atalkd daemon with its atalkd.conf configuration file, and the papd daemon with its papd.conf configuration file are once more available.

A handful of options in afp.conf have been changed or removed incrementally throughout the Netatalk v4 release history. See the table of old and new option names below for details.

afpstats breaking changes

The afpstats tool was introduced as a replacement for the historical macusers script in Netatalk 3.0. In its original shape, the tool communicated with afpd over D-Bus, but as of Netatalk 4.5 it has been rewritten to use a standard Unix socket for simplicity and portability.

If you upgrade from a previous version, you may need to manually delete the netatalk-dbus.conf file which is usually stored in /usr/share/dbus-1/system.d.

Upgrading from Netatalk 2

There are three major changes between Netatalk 2 and Netatalk 4:

1. New configuration files that replaces most of the previous ones: afp.conf and extmap.conf

2. New backend for file metadata which stores metadata in extended attributes of the filesystem.

3. The AppleTalk transport layer is disabled by default. If you want to use Netatalk with very old Macs, turn it on with the appletalk = yes option in afp.conf. Then start the atalkd daemon before netatalk in order to activate the AppleTalk transport layer.

New configuration

afp.conf

• ini style syntax (akin to Samba’s smb.conf)

• one to rule them all: configure AFP settings and volumes in one file

• obsoletes afpd.conf, netatalk.conf, AppleVolumes.default and afp_ldap.conf

WARNING: Most option names have changed. Read the full manpage afp.conf for details.

extmap.conf

• maps file extensions to Classic Mac OS type/creator

• unlike 2.x, the mappings are disabled by default; uncomment the lines in the file to enable them

• obsoletes AppleVolumes.system

New metadata backend

New file metadata backend ea = sys which stores macOS extended attributes and Classic Mac OS resource forks in extended attributes of the filesystem.

• default backend (!)

• requires a filesystem with Extended Attributes, fallback is AppleDouble v2 which is enabled with ea = ad

• on the fly conversion from AppleDouble v2 to Extended Attributes when accessed by clients, enabled with convert appledouble = yes

• dbd can be used to do conversion in one shot

Implementation details:

• stores Mac Metadata (e.g. FinderInfo, AFP Flags, Comment, CNID) in an Extended Attributed named org.netatalk.Metadata

• Additionally, on macOS hosts running Netatalk 4.1.0 or later, FinderInfo is natively stored in the file system and appears as an Extended Attribute named com.apple.FinderInfo

• stores Mac ResourceFork either in

• an Extended Attribute named org.netatalk.ResourceFork on Solaris w. ZFS, or in

• an extra AppleDouble file named ._file for a file named file, or

• natively stored in the resource fork on macOS hosts as of Netatalk 4.1.0.

• the format of the ._ file is exactly as the Mac’s CIFS client expects it when accessing the same filesystem via a CIFS server (Samba), thus you can have parallel access from Macs to the same dataset via AFP and CIFS without the risk of losing data (resources or metadata). Accessing the same dataset with CIFS from Windows clients will still break the coupling of file and ._file on non ZFS filesystems (see above), so for this we still need an enhanced Samba VFS module.

Other major changes

• New service controller daemon netatalk which is responsible for starting and restarting the AFP and CNID daemons. All bundled start scripts have been updated, make sure to update yours!

• All CNID databases are now stored in a netatalk/CNID subdirectory of your system’s state directory path, e.g. /var/lib, rather than in the individual shared volume directories

• Netatalk 2.x volume options usedots and upriv now enabled by default

• Removed SLP and AFP proxy support

Upgrading procedure

1. Stop Netatalk 2.x

2. Install Netatalk 4

3. Manually recreate configurations in afp.conf and extmap.conf

4. Update your Netatalk init script to start netatalk instead of afpd and cnid_metad, or replace it with the appropriate stock init script for your system.

5. Move afp_voluuid.conf and afp_signature.conf to the localstate directory (default $prefix/var/netatalk/), you can use afpd -v in order to find the correct path

6. Start Netatalk 4

Old and new configuration file names

Old and new option names

Mappings from netatalk.conf (Debian: /etc/default/netatalk) to afp.conf or to the means of invocation

Mappings from afpd.conf to afp.conf

Mappings from afp_ldap.conf to afp.conf

Mappings from AppleVolumes.* to afp.conf