Chapter 5. Upgrading from prior Netatalk versions

Frank Lahm

Table of Contents

Upgrading from Netatalk 3
Upgrading from Netatalk 2
New configuration
New AppleDouble backend
Other major changes
Upgrading procedure
Table with old and new configuration file names
Table with old and new option names

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.

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 AppleDouble backend appledouble = ea which stores Mac metadata and resource forks 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 AppleDouble backend

New AppleDouble backend appledouble = ea which stores Mac metadata and resource forks in extended attributes of the filesystem.

  • default backend (!)

  • requires a filesystem with Extended Attributes, fallback is appledouble = v2

  • converts filesystems from appledouble = v2 to appledouble = ea on the fly when accessed (can be disabled)

  • dbd can be used to do conversion in one shot

Implementation details:

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

  • 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

  • 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 loosing 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 (in the works).

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 under $prefix/var/netatalk/CNID/ by default, 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

Table with old and new configuration file names

Table 5.1. old and new configuration file names

Old File NameNew File NameDescription
-etc/afp.confnew ini-style format
-etc/extmap.confstarting with netatalk 3.0.2
etc/netatalk/afp_signature.confvar/netatalk/afp_signature.confmoved to $localstatedir
etc/netatalk/afp_voluuid.confvar/netatalk/afp_voluuid.confmoved to $localstatedir
etc/netatalk/netatalk.conf (/etc/default/netatalk)-obsolete
etc/netatalk/afpd.conf-obsolete
etc/netatalk/afp_ldap.conf-obsolete
etc/netatalk/AppleVolumes.default-obsolete
etc/netatalk/AppleVolumes.system-obsolete
~/.AppleVolumes-obsolete


Table with old and new option names

Table 5.2. from netatalk.conf (/etc/default/netatalk) to afp.conf

Old netatalk.confNew afp.confOld Default ValueNew Default ValueSectionDescription
ATALK_NAMEhostname--(G)use gethostname() by default
ATALK_UNIX_CHARSETunix charsetLOCALEUTF8(G)-
ATALK_MAC_CHARSETmac charsetMAC_ROMANMAC_ROMAN(G)/(V)-
CNID_METAD_RUN-yes--controlled by netatalk(8)
AFPD_RUN-yes--controlled by netatalk(8)
AFPD_MAX_CLIENTSmax connections20200(G)-
AFPD_UAMLISTuam list-U uams_dhx.so,uams_dhx2.souams_dhx.so uams_dhx2.so(G)-
AFPD_GUESTguest accountnobodynobody(G)-
CNID_CONFIGlog level-l log_notecnid:note(G)-
CNID_CONFIGlog file--(G)-
ATALKD_RUN-no--controlled by the init system
PAPD_RUN-no--controlled by the init system
TIMELORD_RUN-no--controlled by the init system
A2BOOT_RUN-no--controlled by the init system
ATALK_BGROUND-no--controlled by the init system
ATALK_ZONEddp zone--(G)Reinstated in 4.0.0


Table 5.3. from afpd.conf to afp.conf

Old afpd.confNew afp.confOld Default ValueNew Default ValueSectionDescription
1st field ("-" or "server name")hostname--(G)use gethostname() by default
-uamlistuam listuams_dhx.so,uams_dhx2.souams_dhx.so uams_dhx2.so(G)-
-nozeroconfzeroconf-yes (if supported)(G)-
-advertise_sshadvertise ssh-no(G)-
-[no]savepasswordsave password-savepasswordyes(G)-
-[no]setpasswordset password-nosetpasswordno(G)-
-client_pollingclient polling-no(G)-
-hostnamehostname--(G)use gethostname() by default
-loginmesglogin message--(G)/(V)-
-guestnameguest accountnobodynobody(G)-
-passwdfilepasswd fileafppasswdafppasswd(G)-
-passwdminlenpasswd minlen--(G)-
-ticklevaltickleval3030(G)-
-timeouttimeout44(G)-
-sleepsleep time1010(G)-
-dsireadbufdsireadbuf1212(G)-
-server_quantumserver quantum3038401048576(G)-
-volnamelenvolnamelen8080(G)-
-setuploglog leveldefault log_notedefault:note(G)-
-setuploglog file--(G)-
-admingroupadmingroup--(G)-
-k5servicek5 service--(G)-
-k5realmk5 realm--(G)-
-k5keytabk5 keytab--(G)-
-uampathuam pathetc/netatalk/uams/lib/netatalk/(G)moved to $libdir
-ipaddrafp listen--(G)-
-cnidservercnid serverlocalhost:4700localhost:4700(G)/(V)-
-portport548548(G)-
-signaturesignatureauto-(G)-
-fqdnfqdn--(G)-
-unixcodepageunix charsetLOCALEUTF8(G)-
-maccodepagemac charsetMAC_ROMANMAC_ROMAN(G)/(V)-
-closevolclose vol-no(G)-
-ntdomainnt domain--(G)-
-ntseparatornt separator--(G)-
-dircachesizedircachesize81928192(G)-
-tcpsndbuftcpsndbuf--(G)OS default
-tcprcvbuftcprcvbuf--(G)OS default
-fcelistenerfce listener--(G)-
-fcecoalescefce coalesce--(G)-
-fceeventsfce events--(G)-
-fceholdfmodfce holdfmod6060(G)-
-mimicmodelmimic model--(G)-
-adminauthuseradmin auth user--(G)-
-noacl2maccessmap acls-rights(G)-
-[no]tcp--tcp--TCP transport layer is always enabled
-[no]ddpappletalk-ddpno(G)Reinstated in 4.0.0
-[no]transall--transall--TCP transport layer is always enabled
-nodebug----obsolete
-[no]slp--noslp--SLP support is obsoleted
-[no]uservolfirst--nouservolfirst--uservol is obsoleted
-[no]uservol--uservol--uservol is obsoleted
-proxy----obsolete
-defaultvol-AppleVolumes.default--afp.conf only
-systemvol-AppleVolumes.system--extmap.conf only
-loginmaxfail----not supported from the beginning
-unsetuplog----obsolete
-authprintdir----CAP style auth is obsoleted
-ddpaddrddp address0.00.0(G)Reinstated in 4.0.0
-[no]iconlegacy icon-noicon-(G)Reinstated in 4.0.2
-keepsessions----obsolete. Use kill -HUP.


Table 5.4. from afp_ldap.conf to afp.conf

Old afp_ldap.confNew afp.confOld Default ValueNew Defalut ValueSectionDescription
ldap_serverldap server--(G)-
ldap_auth_methodldap auth method--(G)-
ldap_auth_dnldap auth dn--(G)-
ldap_auth_pwldap auth pw--(G)-
ldap_userbaseldap userbase--(G)-
ldap_userscopeldap userscope--(G)-
ldap_groupbaseldap groupbase--(G)-
ldap_groupscopeldap groupscope--(G)-
ldap_uuid_attrldap uuid attr--(G)-
ldap_uuid_stringldap uuid string--(G)-
ldap_name_attrldap name attr--(G)-
ldap_group_attrldap group attr--(G)-


Table 5.5. from AppleVolumes.* to afp.conf

Old AppleVolumes.*New afp.confOld Default ValueNew Defalut ValueSectionDescription
(leading-dot lines)----moved to extmap.conf
:DEFAULT:-options:upriv,usedots--use "vol preset"
1st field ("~")----use [Homes] section
1st field ("/path")path--(V)-
2nd field----use section name
allow:valid users--(V)-
deny:invalid users--(V)-
rwlist:rwlist--(V)-
rolist:rolist--(V)-
volcharset:vol charsetUTF8(same as unix charset)(G)/(V)-
maccharset:mac charsetMAC_ROMANMAC_ROMAN(G)/(V)-
veto:veto files--(V)-
cnidscheme:cnid schemedbddbd(V)-
casefold:casefold--(V)-
adouble:appledoublev2ea(V)v1, osx and sfm are obsoleted
cnidserver:cnid serverlocalhost:4700localhost:4700(G)/(V)-
dbpath:vol dbpath(volume directory)var/netatalk/CNID/(G)moved to $localstatedir
umask:umask00000000(V)-
dperm:directory perm00000000(V)-
fperm:file perm00000000(V)-
password:password--(V)-
root_preexec:root preexec--(V)-
preexec:preexec--(V)-
root_postexec:root postexec--(V)-
postexec:postexec--(V)-
allowed_hosts:hosts allow--(V)-
denied_hosts:hosts deny--(V)-
ea:eaautoauto(V)-
volsizelimit:vol size limit--(V)-
perm:----Use "directory perm" and "file perm"
forceuid:----obsolete
forcegid:----obsolete
options:roread only-no(V)-
options:invisibledotsinvisible dots-no(V)-
options:nostatstat vol-yes(V)-
options:preexec_closepreexec close-no(V)-
options:root_preexec_closeroot preexec close-no(V)-
options:uprivunix priv-yes(V)-
options:nodevcnid dev-yes(V)-
options:illegalseqillegal seq-no(V)-
options:tmtime machine-no(V)-
options:searchdbsearch db-no(V)-
options:nonetidsnetwork ids-yes(V)-
options:noaclsacls-yes(V)-
options:followsymlinksfollow symlinks-no(V)-
options:nohex----auto-convert from ":2f" to ":"
options:usedots----auto-convert from ":2e" to "."
options:nofileid----obsolete
options:prodosprodos-no(V)Reinstated in 4.0.0
options:mswindows----obsolete
options:crlf----obsolete
options:noadouble----obsolete
options:limitsizelegacy volume size-no(V)Reinstated in 4.0.0
options:dropbox----obsolete
options:dropkludge----obsolete
options:nocnidcache----obsolete
options:caseinsensitive----obsolete