Support of vfs_fruit for the SMB protocol

The vfs_fruit module of the IBM Storage Scale SMB server provides enhanced compatibility for Apple SMB2 clients by implementing a set of SMB2 protocol extensions that are added by Apple to their SMB client and server.

These extensions help to increase the browsing speed in the Apple Finder application on network shares by enhancing directory listings and Apple metadata handling. This metadata is Apple-specific information on files like coloring for example (in contrast to file system metadata like i-nodes, timestamps that are not affected). Without these extensions Mac SMB2 clients store their Apple file metadata in accompanying files for each file (resource fork, file names that are starting with “._”).

The vfs_fruit module is disabled by default. The vfs_fruit module must be enabled to improve the performance of Apple file system. You must take precise decision to enable the vfs_fruit module because disabling the module again requires an extended downtime to find all the files with fruit xattrs and converting the files into apple-double files.

The vfs_fruit module relies on Alternate Data Streams (ADS) support of a share. With IBM Storage Scale, the alternate data streams are stored in the extended attributes in the file system. As Mac clients need to see a consistent file server that either supports these extensions or not, vfs_fruit (and consequently stream) support is enabled globally and it cannot be configured on the share level. This means that Windows clients also notice that the IBM Storage Scale SMB2 server offers support of streams. As streams are stored in extended attributes certain size limitations apply, a single stream can be at most 16 KB and all streams in total can be 50 KB. Applications trying to write beyond those limits receive the error NTSTATUS_DISK_FULL.

The module intercepts the OS X special streams "AFP_AfpInfo" and "AFP_Resource" and handles them in a special way. Moreover, it enhances directory listings with Apple-specific metadata to reduce the number of network round trips on SMB2 find requests.

If files on a file server were accessed previously by Mac clients over SMB2, the Apple file metadata is already written to the accompanying files. Enabling fruit finds and reads this metadata, moves it into streams (extended attributes) and removes the accompanying files on file access. Thus, the metadata that is written earlier is not lost but it can take some time until all metadata is converted. Creating new files use streams (extended attributes) directly.

Disabling vfs_fruit support requires a conversion of the Apple-specific file metadata back from extended attributes to resource fork files to avoid losing metadata. For more information, see the Disabling vfs_fruit support topic, which is provided later in this section.

Enabling vfs_fruit support

The module can be activated globally by using the mmsmb command. To enable it consistently for all clients, the SMB service must be stopped on all CES nodes. Trying to enable it while SMB is running leads to the following error message:

[root@gpfs-11 rhel7] mmsmb config change --vfs-fruit-enable
SMB Environment check failed.
Required: SMB service is not running on any CES node
Detected: SMB service is running on at least one CES node

Here is how to stop SMB on all CES nodes. If NFS is also enabled and has an AD dependency, then NFS needs to be stopped first.

[root@gpfs-11 rhel7] mmces service stop smb -N cesnodes
gpfs-11.novalocal:  SMB: service already stopped.
gpfs-12.novalocal:  Redirecting to /bin/systemctl stop gpfs-smb.service
gpfs-12.novalocal:  SMB: service successfully stopped.
gpfs-11.novalocal:  CTDB: service already stopped.
gpfs-12.novalocal:  Redirecting to /bin/systemctl stop gpfs-ctdb.service
gpfs-12.novalocal:  CTDB: service successfully stopped.

To check whether SMB is running, issue the following command:

[root@gpfs-11 rhel7] mmces service list -N cesnodes
Enabled services: SMB
gpfs-11.novalocal:  SMB is not running
gpfs-12.novalocal:  SMB is not running

Now that SMB is stopped, you can enable vfs_fruit:

[root@gpfs-11 rhel7] mmsmb config change --vfs-fruit-enable
WARNING: You are about to enable the vfs_fruit module. It is not possible
to disable this module again without contacting IBM support first.

Are you sure you want to continue?
Enter "yes" or "no": yes
vfs_fruit enabled.

Now, the SMB service can be restarted:

[root@gpfs-11 rhel7] mmces service start SMB -N cesnodes
gpfs-12.novalocal:  Redirecting to /bin/systemctl start gpfs-ctdb.service
gpfs-11.novalocal:  Redirecting to /bin/systemctl start gpfs-ctdb.service
gpfs-12.novalocal:  CTDB: service successfully started.
gpfs-11.novalocal:  CTDB: service successfully started.
gpfs-12.novalocal:  Wait for ctdb to become ready. State=STARTUP
gpfs-11.novalocal:  Wait for ctdb to become ready. State=STARTUP
gpfs-12.novalocal:  Redirecting to /bin/systemctl start gpfs-smb.service
gpfs-11.novalocal:  Redirecting to /bin/systemctl start gpfs-smb.service
gpfs-12.novalocal:  SMB: service successfully started.
gpfs-11.novalocal:  SMB: service successfully started.

Disabling vfs_fruit support

Enabling the vfs_fruit module changes how the Apple file metadata is stored, namely in extended attributes rather than in accompanying files. Thus, disabling vfs_fruit causes the Apple file metadata not to be used or found anymore. If vfs_fruit really needs to be disabled on a cluster after Apple file metadata, which should not be lost, is written, then contact IBM® support for ways how to move Apple file metadata back out of the extended attributes into resource fork files. This procedure involves running a GPFS policy and a tool to move Apple-specific metadata that is changed by Mac OS clients from extended attributes back to resource fork files. This requires an SMB downtime.

Verifying vfs_fruit running status

To verify if the vfs_fruit module is enabled, issue the following command:

mmsmb config change --vfs-fruit-enable

After you issue the command, if the vfs_fruit module is enabled, you get a message as shown in the following sample output:

SMB Module vfs_fruit already enabled!

Alternatively, you can verify the vfs_fruit status by using the following net command while the SMB service is running:


net conf list |grep "vfs objects"
vfs objects = shadow_copy2 syncops fruit streams_xattr gpfs fileid time_audit
Disabling vfs_fruit support

ACL considerations

Normally the main file and the ._ file has the same user and group permissions. If not, then the ._ file cannot be read the fruit module does not work as expected. Thus, if the conversion does not take place as planned, then ACLs are the items to check for troubleshooting.

Remaining ._ files

Under certain circumstances some ._ files might still reappear in the file system. This can be the case if either the file is not written since the configuration change to enable vfs_fruit or if the data does not fit into an extended attribute due to its size, like for a large custom icon.

For more information, see Planning for SMB.