Features introduced with AFP 3.1
100% AFP file and directory ID compatibility with EtherShare
Supported Operation Systems (for AFP clients)
2. HELIOS AFP 3.1 smart permissions (new since preview-7)
3. AFP 3.1 and UNIX Permissions
No Network Trash Folder on Mac OS X
Mac OS X Finder window actualization problem
Using special characters in user/group names
Prerequisites
- EtherShare 3.1
- Mac OS X 10.2 or newer clients, to benefit from AFP 3.1
- Mac OS 8.1 or newer
- Volumes in Unicode/UTF-8 Format. (":hex" volumes, e.g. MacRoman will be disabled)
The AFP 3.1 preview-17 is a fully supported EtherShare module. It is a pre-release of a feature from the next EtherShare version, and is not beta code. It is suitable for deployment in production environments. We encourage all EtherShare 3.1 users to take advantage of this early availability. Note though, that AFP 3.1 preview-17 will time-out February 1, 2008. We require that all customers using the AFP 3.1 preview server maintain a Software Upgrade Service agreement. We recommend that all customers upgrade to UB (EtherShare UB already includes AFP 3.1 and many more enhancements).
Features introduced with AFP 3.1
| Feature | Description |
| Directory enumerations | AFP 3.1 does faster directory enumerations. |
| Long file name support | File names can contain up to 255 characters. |
| Unicode/UTF-8 support | All names for users, groups, volumes and servers are Unicode/UTF-8 based and are compatible with HELIOS Unicode/UTF-8 volumes. ":hex" volumes are disabled for AFP 3.1.
For AFP 2.2 clients (Mac OS 8/9), the Unicode/UTF-8 encoding is transformed back into the client encoding specified by the AFP charset in the volume settings. |
| UNIX ownership & permissions | AFP 3.1 utilizes UNIX users and groups and uses UNIX permissions for files and folders. |
| Mac OS X symlink support | This feature allows copying application packages to/from the server, without loss of information. |
| Very large files (64-bit file offsets) | With AFP 3.1, very large files up to millions of terabytes can be handled. The support of file sizes that large is needed e.g. for large PrePress jobs, video data and backup archive files. This was not possible with the 2/4 GB file size limit of AFP 2.2. HELIOS has already supported 64-bit file offsets in its 4th generation modules including EtherShare 3.1 and PCShare 3.1! |
| Client/Server reconnect support | The Client/Server reconnect support allows automatic reconnection on network time-outs or failures as well as on server failures (good for high availability). In case of a reconnection, all open files are closed and re-opened. |
| Mac OS X client sleep support | Disables connection traffic during sleep (no immediate time-out). Users using "Energy Saver" features (no connection time-out). |
Faster performance
The EtherShare AFP 3.1 preview server works great with Mac OS X clients. The performance is several times faster than NFS or SMB/CIFS. Using a 1 GHz G4 Mac OS X 10.2 client via Gigabit Ethernet against a fast EtherShare AFP 3.1 server, we have seen LanTest read/write performance up to 60 MBytes per second when using a single OS X client. Server based FindFile using AFP volumes is done in seconds versus hours using NFS or SMB/CIFS volumes. AFP 3.1 support means: File & Directory IDs, resource files, Exchange File, UNIX permissions, FinderInfo (type/creator, etc.), full file & record locking, file creation and backup dates, 64-bit file offsets, and more. Most of these features are not available when using NFS or SMB/CIFS volumes, which may cause incompatibilities with applications, e.g. Acrobat, Keynote, Explorer will fail saving files in NFS or SMB/CIFS server volumes, Classic will not work at all in NFS or SMB/CIFS server volumes.
In a nutshell, AFP 3.1 is the easiest, best performing and most reliable protocol to connect Mac OS X clients to a server.
100% AFP file and directory ID compatibility with EtherShare
HELIOS EtherShare offers 100% AFP compatible file and directory IDs, which are used by Mac OS 8/9 and Mac OS X clients to reference files and folders. An example: A Mac OS 9 or X client usually asks the server to open folder ID 12004 with file name "image.tif", or it asks to resolve file ID 16732 and the server responds with the correct file name. The volume unique IDs are stored in .rsrc files as well as in the desktop database, to allow a database search. Removing a file/folder will also remove the unique ID, which is never used again.
EtherShare includes the Desktop utilities ("dt mv", etc.), which ensure that the file/directory IDs and resource files are preserved or updated when working with UNIX batch scripts. HELIOS PCShare, WebShare, ImageServer, PDF HandShake and PrintPreview as well as third party solutions, e.g. Archiware & UGS Backup and many others, support this by using our Desktop utilities ("dt").
Note: Other AFP server solutions without 100% AFP ID support, e.g. simulating an ID with UNIX inode or temporary ID numbers without using a desktop database, suffer from major multiuser problems such as removing or using wrong files/folders. This problem occurs more often using multiple Mac OS X clients. Working with HELIOS EtherShare eliminates this problem.
Installation
Download the AFP 3.1 preview software for the required server platform at: http://www.helios.de/afp3preview/ and follow the instructions below.
Note: The above page is only accessible to UB product customers or those who own an active HELIOS Software Upgrade Service Agreement! Enter the product serial number in the "User Name" field (8 digits) and the machine ID in the "Password" field (8+2 digits; lower case!).
AFP 3.1 preview cannot be installed (or updated) via HELIOS Update Installer!
Stop the existing AFP server:
# cd /usr/local/helios
# bin/srvutil stop -f afpsrv
Save the original AFP server, e.g:
# mv sbin/afpsrv sbin/afpsrv.save
Extract the downloaded "<arch>.tgz" archive.
The following example is for Apple Mac OS X 10.2:
# gunzip < macosx.tgz | tar xvf -
In case you encounter problems extracting the downloaded "<arch>.tgz" file, run the UNIX command-line tool "cksum" and compare the generated output with the values given in the file "sums.txt".
Then start the AFP server again:
# bin/srvutil start afpsrv
Supported Operating Systems (for AFP clients)
- Mac OS 8.1 or newer (uses only AFP 2.2)
- Mac OS X 10.0 is not supported
- Mac OS X 10.1 has received very limited testing
- Mac OS X 10.2 or newer is supported
- Mac OS X 10.3 or newer is supported and recommended
Permission notes
1. Creating files/foldersUNIX command line utilities in AFP volumes will create files according to "umask" and work as expected.
However, all new files and directories created by Mac OS X GUI applications will be created with the permissions:
- read/write for the owner
- read-only for the group and others
This is the default for many GUI applications and causes problems because many users cannot write into files or directories created by others. This problem caused by applications can be avoided by using HELIOS AFP 3.1 smart permissions (the default).
2. HELIOS AFP 3.1 smart permissions (new since preview-7)
One of the biggest problems using Mac OS X clients is that new files and folders cannot be changed by other users, unless - after every saving - the write permissions are granted. HELIOS' new AFP 3.1 preview-7 addresses this with a default behavior of the server similar to AFP 2.2, which means that parent permissions are inherited in a server volume. See useunixperm volume preference below.
3. AFP 3.1 and UNIX permissions
Mac OS X is a UNIX-based operating system, so AFP 3.1 file/directory access permissions are identical to the UNIX permissions. However, HELIOS AFP 3.1 supports two (mutually exclusive, server wide) permissions modes for saving files and folders: HELIOS AFP 3.1 smart permissions; and UNIX permissions. As mentioned above, the default setting is to use smart permissions, so that files saved to the server will inherit the permissions of the parent folder. When smart permissions are turned off, standard UNIX permissions will be used when saving files and folders. See useunixperm volume preference below.
4. Changing access modes from the Finder
With enabled UNIX permissions (useunixperm = TRUE), permissions can be changed using the Get Info dialog from the Mac OS X Finder as usual.
With disabled UNIX permissions (useunixperm = FALSE), which is the default, permissions cannot be changed directly. This feature is only available with active UNIX permissions. However, to allow an authorized user to change the permissions, do the following:
Open the Finder's Get Info dialog for a file/folder in the server volume.
Open the permission details, enter the new user name "unixperm" and press the "TAB" key.
A Finder message pops up ("invalid user name"), together with the AFP message:
Now the UNIX permissions are enabled for the AFP server client process, irrespective of the volumes' smart permissions status, so you can change the permissions as required. The UNIX permissions for the particular client are enabled until the client disconnects from all server volumes or the UNIX permissions are switched off.
Switching off the UNIX permissions is done by entering the user name "reset" in the Get Info dialog, followed by pressing the "TAB" key. Then again, a Finder error ("invalid user name") pops up, together with the AFP message:
The owner can change the read/write mode within the Finder for owner, group and others.
Note: AFP 2.2 allows the owner of directories to transfer the ownership to a different user. AFP 3.1 does not support changing the owner unless you are the user root.
Mac OS X works best if the local (GUI) login user-ID, user name, group-ID and group names are identical with the server-based IDs and names. During the AFP server login, Mac OS X verifies if the GUI user name and user-ID are identical to the AFP login user name and user-ID on the server. If the IDs/names between the GUI and AFP login are different, Mac OS X turns on a special ID mapping which will do the following:
The AFP login name will be mapped into the GUI name. For example, the GUI name is Michael, the AFP login name is Dave. The name mapping will show with UNIX tools on a Mac OS X client that all server files owned by Dave are owned by Michael on the Mac OS X client. The Finder will also display incorrect owner/group names.
HELIOS worked together with Apple to resolve this as well. In Mac OS X 10.3, the Finder always shows correct user and group names, and ID mapping can be avoided by having identical user names and IDs in the GUI login and in the AFP volume login. Mac OS X UNIX tools will still show the GUI user instead of the real server file/directory owner.
See also Apple support document Mac OS X Server 10.2: About Privilege Mapping and When It Is Used
Hidden files
Our AFP 3.1 server will issue the hidden attribute for ".DS_Store" files so that Mac OS 8/9 users will not see the Mac OS X ".DS_Store" files. If the volume option "Hide dot files" is turned on, all dot files will be hidden with the Finder attributes. If desired, these files can be seen via the "ls -la" command. Mac OS X GUI applications will only show hidden files if this is supported by the application. (For example, ResEdit or Resorcerer support hidden files.)
No Network Trash Folder on Mac OS X
There is no Network Trash Folder support in Mac OS X. Therefore, data which are deleted from an AFP volume are deleted immediately without being stored in a Network Trash Folder prior to deletion.
Long file names on Mac OS 8/9
Mac OS 9 has no support for AFP 3.1, AFP 2.2 is used instead by Mac OS 8/9 clients. As a result, file/directory names containing more than 31 characters will be truncated. In this case the file name, beginning with the 26th character, is replaced with a "#" followed by a four hexadecimal character checksum. It is possible to rename these files to a different file name from Mac OS 8/9. Working on the files with the truncated names is not recommended though.
Long file names on Mac OS X 10.2
The Mac OS X 10.2 "Finder" cannot directly rename files/folders in an AFP 3.1 volume with names that are longer than 31 characters. This is a "Finder" issue and has been reported to Apple.
A workaround under Mac OS X 10.2 was to create a file/folder with a long name on the local hard disk and then copy it to the volume.
HELIOS worked together with Apple to resolve this. In Mac OS X 10.3 it has been fixed.
Note: UNIX systems do have a limitation for the length an absolute path can have. This length is usually 1024 bytes.
It is not possible for example, to create three folder hierarchies with names of 255 characters/bytes each, and then place a file name with again 255 characters/bytes into that folder:
/255charactername/255charactername/255charactername/255charactername
The calculation is: 255 characters/bytes * 4=1020 + 4 "/" characters and the ending zero byte = 1025, which is too long.
Unicode/UTF-8 characters can be represented as single or multibyte characters. In case of multibyte characters, the length of the absolute path is limited to 1024 bytes and the length for each path element (folder or file) is limited to 255 bytes.
As Mac OS X is based on UNIX, the same limitation will apply for Mac OS X applications.
New Preferences
HELIOS introduced two new preferences for the AFP server:
afp3, of type boolean with the default value TRUE. This preference allows disabling the AFP 3.1 features for Mac OS X clients. Setting it to FALSE causes the server to connect Mac OS X clients via the AFP 2.2 protocol version. The following examples show how to turn AFP 3.1 support off (1) and how to delete the preference, i.e. how to switch AFP 3.1 compatibility back on (2):
(1) prefvalue -k "Programs/afpsrv/afp3" -t bool FALSE
(2) prefvalue -k "Programs/afpsrv/afp3" -d
useunixperm, of type boolean with the default value FALSE which does inherit the permissions of the parent folder. The following examples show how to turn AFP 3.1 UNIX permissions on (1) and how to delete the preference, i.e. how to switch AFP 3.1 smart permissions back on (2):
(1) prefvalue -k "Volumes/\/data1\/demovol/useunixperm" -t bool TRUE
(2) prefvalue -k "Volumes/\/data1\/demovol/useunixperm" -d
The volume path in the examples above is "/data1/demovol". Note the double quotes and the quoting of path delimiters ("\/").
Mac OS X Finder window actualization problem
If one and the same AFP volume is mounted by more than one client concurrently, and one of the clients adds a file to or deletes a file from this volume, the Mac OS X Finder may not refresh the displayed volume content. This is a problem with the Mac OS X Finder for which the following workaround is recommended:
Create a new (temporary) folder in the volume and subsequently delete it.
In doing so, the Finder is forced to read in and display the current content of the volume anew.
Note: Under Mac OS X 10.3 the above mentioned workaround becomes obsolete; new or deleted files are updated in the Finder view after opening the folder, or selecting the file(s).
Using special characters in user/group names
AFP 3.1 supports Unicode/UTF-8 user/group/volume/server name encoding. However, at the moment HELIOS provides no administration tools for this purpose. Therefore we do not recommend using special characters in user/group/volume/server names.
Changes for AFP 3.1 preview-5
Some special Unicode/UTF-8 characters were not handled properly.Changes for AFP 3.1 preview-6
AFP 3.1 preview-6 fixes a possible connection loss problem for Mac OS X clients on heavy server load. Please note that a different connection loss problem is solved in Mac OS X 10.3.5.
We recommend to use Mac OS X 10.3.5 or newer.
Changes for AFP 3.1 preview-7
The "smartafp3perms" preference has been removed from the server. Use the following command to remove the obsolete preference from your settings:
prefvalue -k "Programs/afpsrv/smartafp3perms" -d
Changes for AFP 3.1 preview-8
Fixed problem with folder permissions.
Changes for AFP 3.1 preview-9
The volume root directory can now also be a symlink
Changing file or directory permissions does not lead to an error message anymore
The "g+s"-bit on directories is now set on new folders.
Changes for AFP 3.1 preview-10
The "g+s"-bit on directories is now always honored when the "useunixperm" preference is not set.
With active UNIX permissions the "g+s"-bit cannot be set, unless the user is member of the group of the parent directory.
Changes for AFP 3.1 preview-11
Fix for some programs which save documents in folder names exceeding 31 characters.
Changes for AFP 3.1 preview-12
Preview-12 contains a fix for Mac OS X 10.4 Tiger, which cannot copy files if the owner of the current folder is different from the current user session.
Changes for AFP 3.1 preview-13
Preview-13 fixes a problem with smart permissions, that after the Finder Get Info "unixperm" command, a wrong user ID was shown for the owner.
Changes for AFP 3.1 preview-14
Fix for an AppleTalk browsing problem for Mac OS X 10.4 ("Tiger") clients.
Changes for AFP 3.1 preview-15
Time-out of AFP 3.1 preview-15 has been extended to June 1, 2006.
Changes for AFP 3.1 preview-16
Time-out of AFP 3.1 preview-16 has been extended to February 1, 2007.
Changes for AFP 3.1 preview-17
Time-out of AFP 3.1 preview-17 has been extended to February 1, 2008. The preview will work for testing purposes with demo keys or on a fully licensed installation.
Note: Only customers owning an EtherShare UB upgrade are entitled to install and use the AFP 3.1 preview-17 software!
Changes for AFP 3.1 preview-18
Time-out of AFP 3.1 preview-18 has been extended to February 1, 2009.
Known Issues
There are no known bugs as of November 2007.