Australian cloud for business software — built and run in Sydney since 2003

+61 2 8282 5656
support@netleverage.com
Talk to an engineer
Talk to an engineer
NetLeverage
NetLeverage

Mac files on Linux and NAS shares: resource forks, Finder metadata and AppleDouble in backup and restore

Technical article
Backup & Recovery

Originally published:

About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.

A Mac document can depend on information beyond its main data stream. Apple's technical note on the HFS Plus volume format puts it simply: "Files on an HFS volume have two forks: a data fork and a resource fork, either of which may be empty (zero length)." It adds that "Files and directories also contain a small amount of additional information (known as catalog information or metadata) such as the modification date or Finder info."

A Linux file system has a single stream of bytes per file, plus extended attributes. When Macs save files to a Linux server or a NAS, through Samba over SMB or through Netatalk over AFP, the server has to put the extra parts somewhere. Where it puts them depends on the server configuration, and each choice is lost in a backup in a different way.

This guide works through that storage from the Samba and Netatalk manuals and the Linux extended attribute page, then sets out what a backup must capture and what a restore target must be able to accept. It covers the server side only; how macOS itself stores these parts on its own disks is outside its scope.

Why it matters

A restore can retain the main data fork while losing information needed to interpret or use the document. What may not come back is the Finder information, custom icons, older applications' resource forks, and other named streams that Mac applications attach to files. Users notice later, and by then the backup that could have fixed it may have expired.

There is also a migration risk. Samba and Netatalk can convert between storage formats, sometimes automatically when files are accessed. A restore into a server with different settings can trigger a conversion nobody planned.

How it works

What Samba does with Mac streams

The vfs_fruit module "provides enhanced compatibility with Apple SMB clients and interoperability with a Netatalk 3 AFP fileserver." Its manual explains that it "enables alternate data streams (ADS) support for a share", treats two special Mac streams, AFP_AfpInfo and AFP_Resource, in its own way, and that "All other named streams are deferred to vfs_streams_xattr which must be loaded together with vfs_fruit."

That gives three kinds of Mac data on a Samba share:

  • the resource fork (the AFP_Resource stream);
  • the Mac metadata (the AFP_AfpInfo stream, which the manual says Apple clients use "to store structured file metadata.");
  • any other named stream, handled by vfs_streams_xattr.

Where the resource fork goes

The fruit:resource option "Controls where the OS X resource fork is stored." It has three settings:

  • file, the default: "use a ._ AppleDouble file compatible with OS X and Netatalk";
  • xattr: "use a xattr, requires a filesystem with large xattr support and a file IO API compatible with xattrs, this boils down to Solaris and derived platforms and ZFS";
  • stream, marked experimental: "pass the stream on to the next module in the VFS stack." The manual warns that "this option should not be used with the streams_xattr module due to the extended attributes size limitations of most filesystems."

So on an ordinary Linux Samba server left at the default, every Mac file with a resource fork can have a companion file beside it whose name starts with a dot and an underscore. These are AppleDouble sidecar files. They are ordinary files on disk, but backup filters, hidden-file exclusions and partial selection can omit them. They are also hidden from SMB clients by default: fruit:veto_appledouble "controls whether these ._ AppleDouble files are vetoed which prevents the client from accessing them", and "The default is yes."

Where the metadata goes

The fruit:metadata option "Controls where the OS X metadata stream is stored". The default is netatalk, described as "use Netatalk compatible xattr"; the alternative, stream, will "pass the stream on to the next module in the VFS stack". Either way, on a default Linux setup the Finder metadata ends up in an extended attribute, not in a separate file (our reading of the two settings together).

Where other streams go

The vfs_streams_xattr manual explains the general mechanism: "As a normal posix file system does not support the concept of multiple data streams per file, the streams_xattr module stores the data in posix extended attributes (xattrs)." Attribute names begin by default with the prefix user.DosStream. followed by the stream name. The prefix matters for backup, because it places these attributes in the user namespace.

The same page is direct about limits: "Please note that most file systems have severe limitations on the size of xattrs. So this module might work for applications like IE that stores small zone information in streams but will fail for applications that store serious amounts of data in ADSs." An option, streams_xattr:max xattrs per stream, lets one stream be split across several attributes. The page gives an example: "Linux has a limit of 64kB per xattr, but XFS can store more than that per inode." The smb.conf manual's smbd max xattr size entry agrees: "The Linux VFS currently sets an upper boundary of 64 KiB per extended attribute."

File systems have different attribute limits

The Linux xattr(7) page describes filesystem-specific limits, but its blanket single-block statement for ext4 is incomplete for modern feature combinations. The kernel ext4 attribute documentation explains that the EA_INODE feature can store attribute values in separate inodes. A target must be assessed by its actual kernel, filesystem features and limits, rather than by the name ext4 alone. By contrast, "In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no practical limit on the number of extended attributes associated with a file". For Btrfs, "the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem nodesize value (16 kB by default)."

This is the detail that turns a routine restore into a failure. Metadata that fitted on an XFS source may not fit on an ext4 target, and a stream stored across several attributes on one server may have nowhere to go on another.

Netatalk's choices

Netatalk, the AFP server, has its own setting. Its afp.conf manual describes ea, which can be sys, samba, ad or none, and which will "Specify how Extended Attributes and Mac OS Resource Forks are stored." By default it attempts "to enable sys (filesystem Extended Attributes) with a fallback to ad (AppleDouble sidecars.)" The samba setting uses attributes "but append a 0 byte to each xattr in order to be compatible with Samba’s vfs_streams_xattr." The ad setting will "Use AppleDouble v2 metadata stored as files in .AppleDouble sidecar directories", which the manual says "is only recommended when the host’s filesystem does not support Extended Attributes."

The manual carries a warning that applies to any restore into a Netatalk server: "The samba option should not be used on a volume that was previously set to sys. This may lead to data loss". The storage format is a property of the data, not just the server, and must match when data comes back.

Conversion on access

Both servers can convert old sidecar files into attributes. Samba's fruit:convert_adouble decides "Whether an attempt shall be made to convert ._ AppleDouble sidecar files to native streams (xattrs when using vfs_streams_xattr)", and "The default is yes." Netatalk's convert appledouble will "Perform automatic conversion of AppleDouble v2 metadata files to filesystem Extended Attributes dynamically when accessing filesystems from clients." Its default is no.

For recovery, this means that restoring sidecar files into a Samba share with default settings may lead Samba to rewrite them as attributes as Mac users open folders. That may be exactly what is wanted, but the next backup will then need to capture attributes as well.

File names

Macs use characters in file names that are not allowed on Windows file systems. The fruit manual says "OS X maps NTFS illegal characters to the Unicode private range in SMB requests." The fruit:encoding option decides how those characters are stored on disk: private, the default, stores them "as encoded by the OS X client", while native stores them "with their native ASCII value" and "requires the use of vfs_catia in the VFS module stack". Restoring files written under one setting into a share using the other can leave names that look wrong to Mac users. The vfs_catia page warns that "Character mapping must work in BOTH directions (server -> client and client -> server) to get unique and existing file names!"

What the common tools do

Sidecar files. AppleDouble files are ordinary files. rsync, tar and cp copy them like any other file. The risks are restoring the data file without its sidecar, or a sidecar without its data file, in a partial restore.

Extended attributes with rsync. rsync preserves attributes only with --xattrs (-X); the manual's list of what -a does not include names xattrs. With -X, "a copy being done by a super-user copies all namespaces except system.. A normal user only copies the user. namespace." Samba's stream attributes are in the user namespace by default, so either kind of run can carry them, provided -X is given.

Extended attributes with GNU tar. tar records attributes only with --xattrs; the no-xattrs option is documented to disable extended attribute support, which is the default. The manual notes that with --xattrs all attribute namespaces can be stored, while extraction includes only the user namespace by default. Samba's stream attributes would come back by default; attributes in other namespaces need explicit options.

Through an SMB mount. Copying a share through a client mount instead of on the server sees the share the way a client does, with vetoed files hidden. The fruit manual records one side effect: with vetoing on, "rsync will also be unable to sync files beginning with underscores, as the temporary files it uses for these will start with ._ and so cannot be created." Backups of Mac shares are better taken from the server's file system than through the share.

Time Machine shares

Apple's Mac User Guide says Time Machine can use "a network-attached storage (NAS) device that supports Time Machine over Server Message Block (SMB) or Apple Filing Protocol (AFP)", and advises: "If given the choice between SMB and AFP, use SMB to back up to your external backup disk."

On Samba, fruit:time machine "Controls if Time Machine support via the FULLSYNC volume capability is advertised to clients." A size cap, fruit:time machine max size, is described as "an approximated calculation that only takes into account the contents of Time Machine sparsebundle images. Therefore you MUST NOT use this volume to store other content when using this option, because it would NOT be accounted."

A Time Machine destination can contain backup history, but advertising support does not prove that a successful, usable backup exists. For a second copy, plan a coherent capture of each required sparsebundle and its metadata with writers quiesced or an appropriate consistent snapshot. Copying every band file while the bundle changes does not establish consistency. Validate the recovered history with Time Machine in isolation; no such test was performed here.

A worked example

This is an illustration, not a measured case.

A design studio keeps its project archive on a Linux Samba server with vfs_fruit and vfs_streams_xattr, using default resource-fork and Finder-metadata placement on an XFS file system. Twenty Macs and a handful of Windows PCs use the share. The server is being replaced, and the new one has an ext4 data volume.

The migration is done overnight with rsync using -a only. In the morning the files open. Over the next weeks, designers find that some older files have lost their custom icons and that some Mac applications no longer recognise documents they created. The sidecar files came across, because they are ordinary files. The Finder metadata and named streams did not, because they were in attributes and rsync was not asked to copy them.

Suppose the source also used a non-default multi-attribute stream setting and the target lacks sufficient attribute capacity. A second attempt with -X can then report attribute errors. This is a hypothetical feature-dependent failure, not a rule that every XFS-to-ext4 migration fails; the default streams_xattr limit is one attribute per stream. The fix is to choose a target file system with room for the attributes, check the Samba settings match on both servers, and only then copy with attributes preserved.

A planning checklist

These are our recommendations, drawn from the sources above.

  1. Record every share's VFS stack and the fruit and streams_xattr settings, including fruit:resource, fruit:metadata, fruit:encoding and fruit:convert_adouble. For Netatalk, record ea.
  2. Prefer a supported server-side capture when it exposes all required metadata. If using an SMB-aware backup path, verify its stream and permission support explicitly; an ordinary client file copy is insufficient evidence.
  3. Preserve extended attributes explicitly: -X for rsync, --xattrs for tar. Check that the user namespace is included.
  4. Keep sidecar files with their data files. Test a partial restore of one folder to confirm both arrive.
  5. Measure the source attribute sizes and counts, and validate them against the target's actual filesystem features and tool path. Do not rely on an older generic limits table alone.
  6. Restore into a server whose fruit and Netatalk settings match the source, then change settings deliberately if a conversion is wanted.
  7. Capture Time Machine bundles consistently and test recovery, rather than assuming file presence establishes usable history.
  8. After a restore, check from a Mac that Finder information and named streams are present, not only that files open.

Risks and limits

  • Silent loss. A successful content-only copy does not report omitted attributes as a preservation failure.
  • Size limits. Large streams may not fit on the restore target, depending on the file system.
  • Unplanned conversion. Default Samba settings may convert sidecar files on access.
  • Netatalk format mismatch. The manual warns of data loss when switching a volume from sys to samba.
  • Scope. We did not research macOS's own on-disk storage on APFS, Apple's copy tools, or vendor NAS products that embed Samba or Netatalk with their own defaults. TN1150 describes the older HFS Plus format and is used here only for the definition of forks.

Sources

This article was originally published on .