7.29.2013
Frank
Lahm
29 Jul, 2013

# Upgrading from Netatalk 2

## Overview

There are two major changes in Netatalk:

1. New configuration file `afp.conf`, obsoleting all previous configuration files

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

### New configuration

- ini style syntax (like 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`

most option names have changed, read the full manpage afp.conf for details

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

As these days the only applications making use of Resource Forks are Adobe Photoshop (image preview) and Postscript Type 1 fonts, even on eg Linux you’ll get rid of 99% of any extra Netatalk AppleDouble files (and folders).

### 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!

- The CNID databases are now stored under `/var/netatalk/CNID/` by default. You can use configure --localstatedir=PATH at compile time to change the location.

- Netatalk 2.x volume options “usedots” and “upriv” now enabled by default

- Removed SLP and AFP proxy support

- Removed type/creator extension mapping support

## Upgrading

1. Stop Netatalk 2.x

2. Install Netatalk 3

3. Manually recreate configuration in `afp.conf` and `extmap.conf`

4. Update your Netatalk start script (SMF, systemd, whatever...) to only start netatalk

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

6. Start Netatalk 3

## Table with old and new configuration file names

### old and new configuration file names

Old File Name | New File Name | Description
--- | --- | ---
- | `etc/afp.conf` | new ini-style format
- | `etc/extmap.conf` | starting with netatalk 3.0.2
`etc/netatalk/afp_signature.conf` | `var/netatalk/afp_signature.conf` | moved to $localstatedir
`etc/netatalk/afp_voluuid.conf` | `var/netatalk/afp_voluuid.conf` | moved 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

### from netatalk.conf (/etc/default/netatalk) to afp.conf

Old netatalk.conf | New afp.conf | Old Default Value | New Default Value | Section | Description
--- | --- | --- | --- | --- | ---
ATALK_NAME | hostname | - | - | (G) | use gethostname() by default
ATALK_UNIX_CHARSET | unix charset | LOCALE | UTF8 | (G) | -
ATALK_MAC_CHARSET | mac charset | MAC_ROMAN | MAC_ROMAN | (G)/(V) | -
CNID_METAD_RUN | - | yes | - | - | controlled by netatalk(8)
AFPD_RUN | - | yes | - | - | controlled by netatalk(8)
AFPD_MAX_CLIENTS | max connections | 20 | 200 | (G) | -
AFPD_UAMLIST | uam list | -U uams_dhx.so,uams_dhx2.so | uams_dhx.so uams_dhx2.so | (G) | -
AFPD_GUEST | guest account | nobody | nobody | (G) | -
CNID_CONFIG | log level | -l log_note | cnid:note | (G) | -
CNID_CONFIG | log file | - | - | (G) | -
ATALKD_RUN | - | no | - | - | AppleTalk is obsoleted
PAPD_RUN | - | no | - | - | AppleTalk is obsoleted
TIMELORD_RUN | - | no | - | - | AppleTalk is obsoleted
A2BOOT_RUN | - | no | - | - | AppleTalk is obsoleted
ATALK_BGROUND | - | no | - | - | AppleTalk is obsoleted
ATALK_ZONE | - | no | - | - | AppleTalk is obsoleted

### from afpd.conf to afp.conf

Old afpd.conf | New afp.conf | Old Default Value | New Default Value | Section | Description
--- | --- | --- | --- | --- | ---
1st field ("-" or "server name") | hostname | - | - | (G) | use gethostname() by default
-uamlist | uam list | -U uams_dhx.so,uams_dhx2.so | uams_dhx.so uams_dhx2.so | (G) | -
-nozeroconf | zeroconf | - | yes (if supported) | (G) | -
-advertise_ssh | advertise ssh | - | no | (G) | -
-[no]savepassword | save password | -savepassword | yes | (G) | -
-[no]setpassword | set password | -nosetpassword | no | (G) | -
-client_polling | client polling | - | no | (G) | -
-hostname | hostname | - | - | (G) | use gethostname() by default
-loginmesg | login message | - | - | (G)/(V) | -
-guestname | guest account | nobody | nobody | (G) | -
-passwdfile | passwd file | afppasswd | afppasswd | (G) | -
-passwdminlen | passwd minlen | - | - | (G) | -
-tickleval | tickleval | 30 | 30 | (G) | -
-timeout | timeout | 4 | 4 | (G) | -
-sleep | sleep time | 10 | 10 | (G) | -
-dsireadbuf | dsireadbuf | 12 | 12 | (G) | -
-server_quantum | server quantum | 303840 | 303840 | (G) | -
-volnamelen | volnamelen | 80 | 80 | (G) | -
-setuplog | log level | default log_note | default:note | (G) | -
-setuplog | log file | - | - | (G) | -
-admingroup | admingroup | - | - | (G) | -
-k5service | k5 service | - | - | (G) | -
-k5realm | k5 realm | - | - | (G) | -
-k5keytab | k5 keytab | - | - | (G) | -
-uampath | uam path | etc/netatalk/uams/ | lib/netatalk/ | (G) | moved to $libdir
-ipaddr | afp listen | - | - | (G) | -
-cnidserver | cnid server | localhost:4700 | localhost:4700 | (G)/(V) | -
-port | port | 548 | 548 | (G) | -
-signature | signature | auto | - | (G) | -
-fqdn | fqdn | - | - | (G) | -
-unixcodepage | unix charset | LOCALE | UTF8 | (G) | -
-maccodepage | mac charset | MAC_ROMAN | MAC_ROMAN | (G)/(V) | -
-closevol | close vol | - | no | (G) | -
-ntdomain | nt domain | - | - | (G) | -
-ntseparator | nt separator | - | - | (G) | -
-dircachesize | dircachesize | 8192 | 8192 | (G) | -
-tcpsndbuf | tcpsndbuf | - | - | (G) | OS default
-tcprcvbuf | tcprcvbuf | - | - | (G) | OS default
-fcelistener | fce listener | - | - | (G) | -
-fcecoalesce | fce coalesce | - | - | (G) | -
-fceevents | fce events | - | - | (G) | -
-fceholdfmod | fce holdfmod | 60 | 60 | (G) | -
-mimicmodel | mimic model | - | - | (G) | -
-adminauthuser | admin auth user | - | - | (G) | -
-noacl2maccess | map acls | - | rights | (G) | -
-[no]tcp | - | -tcp | - | - | always TCP only
-[no]ddp | - | -noddp | - | - | AppleTalk is obsoleted
-[no]transall | - | -tcp -noddp | - | - | always TCP only
-nodebug | - | - | - | - | obsolete
-[no]slp | - | -noslp | - | - | SLP support is obsoleted
-[no]uservolfirst | - | -nouservolfirst | - | - | uservol is obsoleted
-[no]uservol | - | -uservol | - | - | uservol is obsoleted
-proxy | - | - | - | - | AppleTalk is obsoleted
-defaultvol | - | AppleVolumes.default | - | - | afp.conf only
-systemvol | - | AppleVolumes.system | - | - | afp.conf only
-loginmaxfail | - | - | - | - | not supported from the biginning
-unsetuplog | - | - | - | - | obsolete
-authprintdir | - | - | - | - | AppleTalk is obsoleted
-ddpaddr | - | - | - | - | AppleTalk is obsoleted
-[no]icon | - | -noicon |  | - | obsolete
-keepsessions | - | - | - | - | obsolete. Use kill -HUP.

### from afp_ldap.conf to afp.conf

Old afp_ldap.conf | New afp.conf | Old Default Value | New Defalut Value | Section | Description
--- | --- | --- | --- | --- | ---
ldap_server | ldap server | - | - | (G) | -
ldap_auth_method | ldap auth method | - | - | (G) | -
ldap_auth_dn | ldap auth dn | - | - | (G) | -
ldap_auth_pw | ldap auth pw | - | - | (G) | -
ldap_userbase | ldap userbase | - | - | (G) | -
ldap_userscope | ldap userscope | - | - | (G) | -
ldap_groupbase | ldap groupbase | - | - | (G) | -
ldap_groupscope | ldap groupscope | - | - | (G) | -
ldap_uuid_attr | ldap uuid attr | - | - | (G) | -
ldap_uuid_string | ldap uuid string | - | - | (G) | -
ldap_name_attr | ldap name attr | - | - | (G) | -
ldap_group_attr | ldap group attr | - | - | (G) | -

### from AppleVolumes.* to afp.conf

Old AppleVolumes.* | New afp.conf | Old Default Value | New Defalut Value | Section | Description
--- | --- | --- | --- | --- | ---
(leading-dot lines) | - | - | - | - | move 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 charset | UTF8 | (same as unix charset) | (G)/(V) | -
maccharset: | mac charset | MAC_ROMAN | MAC_ROMAN | (G)/(V) | -
veto: | veto files | - | - | (V) | -
cnidscheme: | cnid scheme | dbd | dbd | (V) | -
casefold: | casefold | - | - | (V) | -
adouble: | appledouble | v2 | ea | (V) | v1, osx and sfm are obsoleted
cnidserver: | cnid server | localhost:4700 | localhost:4700 | (G)/(V) | -
dbpath: | vol dbpath | (volume directory) | var/netatalk/CNID/ | (G) | moved to $localstatedir
umask: | umask | 0000 | 0000 | (V) | -
dperm: | directory perm | 0000 | 0000 | (V) | -
fperm: | file perm | 0000 | 0000 | (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: | ea | auto | auto | (V) | -
volsizelimit: | vol size limit | - | - | (V) | -
perm: | - | - | - | - | Use "directory perm" and "file perm"
forceuid: | - | - | - | - | obsolete
forcegid: | - | - | - | - | obsolete
options:ro | read only | - | no | (V) | -
options:invisibledots | invisible dots | - | no | (V) | -
options:nostat | stat vol | - | yes | (V) | -
options:preexec_close | preexec close | - | no | (V) | -
options:root_preexec_close | root preexec close | - | no | (V) | -
options:upriv | unix priv | - | yes | (V) | -
options:nodev | cnid dev | - | yes | (V) | -
options:illegalseq | illegal seq | - | no | (V) | -
options:tm | time machine | - | no | (V) | -
options:searchdb | search db | - | no | (V) | -
options:nonetids | network ids | - | yes | (V) | -
options:noacls | acls | - | yes | (V) | -
options:followsymlinks | follow symlinks | - | no | (V) | -
options:nohex | - | - | - | - | auto-convert from ":2f" to ":"
options:usedots | - | - | - | - | auto-convert from ":2e" to "."
options:nofileid | - | - | - | - | obsolete
options:prodos | - | - | - | - | obsolete
options:mswindows | - | - | - | - | obsolete
options:crlf | - | - | - | - | obsolete
options:noadouble | - | - | - | - | obsolete
options:limitsize | - | - | - | - | obsolete
options:dropbox | - | - | - | - | obsolete
options:dropkludge | - | - | - | - | obsolete
options:nocnidcache | - | - | - | - | obsolete
options:caseinsensitive | - | - | - | - | obsolete

## To Do

- test `ad` utils with `appledouble = ea`