macOS Catalina is the first version of macOS which boots not from a single volume, but from two: a read-only System volume named by default Macintosh HD, and a writeable Data volume with the default name of Macintosh HD - Data. If you upgrade to macOS 10.15 Catalina, your boot volume will effectively be split into those two. When your Mac then starts up in Catalina, you won’t see the Data volume, as it’s hidden inside the System volume, in what is an APFS Volume Group.

Although new to macOS, this scheme is already in use in iOS, and specifies the read-only system volume as having the role APFS_VOL_ROLE_SYSTEM, and the writeable user volume has the role APFS_VOL_ROLE_DATA. In that, the volume with the System role is normally mounted at the root /, and that containing both user and mutable system data is then mounted in /System/Volumes and accessed from there using several firmlinks.

Volume layout

A bootable Catalina APFS container normally contains at least five APFS volumes:

• the read-only system volume, by default on the internal disk named Macintosh HD, which forms the root of the boot file system,
• the writable data volume, by default on the internal disk named Macintosh HD – Data, which is normally hidden from view at /System/Volumes and accessed via firmlinks,
• Preboot, a small volume of around 40-50 MB,
• Recovery, the Recovery Volume, of around 500 MB,
• VM, containing virtual memory caches, which is upwards of 20 KB depending on use.

Layout of standard folders and files on the System volume is shown in this roadmap:

available here as a PDF: Catalina System Volume

Layout of standard folders and files on the Data volume is shown in this roadmap:

available here as a PDF: Catalina Data Volume

An integrated view of how both volumes fit together is shown in this roadmap:

available here as a PDF: Catalina Volume Group

Firmlinks

Firmlinks are similar in some respects to traditional symbolic links, but are only made between folders, work in both directions, and with a little added magic effectively merge the contents of two linked folders. For example, the /Users directory on the read-only system volume contains some directories in /Shared. As /Users is a firmlink, the directories there are merged with those in the /Users/Shared directory on the writable (Data) volume.

A similar trick applies to the /Applications directory: user applications are installed in the Applications directory on the writable volume; SIP-protected Apple apps are installed in /System/Applications, which resides on the read-only system volume. When you browse the top-level Applications folder in the Finder, you’ll see the combination of both sets of apps, with user apps linked in using a firmlink between the two volumes. Further details about volume groups and the file system magic in Catalina is in this Carbon Copy Cloner KB article.

The current list of system firmlinks taken from /usr/share/firmlinks is:
/Applications <-> Applications
/Library <-> Library
/System/Library/Caches <-> System/Library/Caches
/System/Library/Assets <-> System/Library/Assets
/System/Library/PreinstalledAssets <-> System/Library/PreinstalledAssets
/System/Library/AssetsV2 <-> System/Library/AssetsV2
/System/Library/PreinstalledAssetsV2 <-> System/Library/PreinstalledAssetsV2
/System/Library/CoreServices/CoreTypes.bundle/Contents/Library <-> System/Library/CoreServices/CoreTypes.bundle/Contents/Library
/System/Library/Speech <-> System/Library/Speech
/Users <-> Users
/Volumes <-> Volumes
/cores <-> cores
/opt <-> opt
/private <-> private
/usr/local <-> usr/local
/usr/libexec/cups <-> usr/libexec/cups
/usr/share/snmp <-> usr/share/snmp
in each case shown as the system volume path and the Data volume path which are firmlinked. These haven’t changed since late betas.

You can also create your own synthetic firmlinks, which appear at root volume level and link to folders or symbolic links on the Data volume. These are stored in an /etc/synthetic.conf file, which is documented in man synthetic.conf. Rich Trouton has published an excellent tutorial on how to do this. Users who previously had their own custom folders at the root level of the boot volume can use this to create the same effect in Catalina.

Paths

The standard system firmlinks mean that, for most users and most purposes, you shouldn’t have to look anywhere different, or change the paths you use in Terminal. However, if you access anything for which there isn’t a convenient firmlink, you may find that its effective path has now changed – hence these new roadmaps, to help you see where things can now be found.

In Terminal, when you want to run a command tool which you installed in the /usr/local/bin directory, you might call it using the command /usr/local/bin/mytool. In Catalina, the firmlink between the /usr/local folder on the System volume takes that path through to the correct folder on the Data volume, so you don’t have to change the path to /System/Volumes/Data/usr/local/bin/mytool.

One valuable trick for always using the right path in Terminal is to locate the folder or file in a Finder window, and drag and drop that into the command line. macOS then magically performs any path conversions for you. You may also find my utility Precize useful, as it gives paths, inode numbers, and a great deal more.

inodes

In this new scheme, inode numbers are allocated relative to the root, so the files and directories of both volumes share the same volume inode and number space. Thus you can’t distinguish where an item is located by checking its volume inode. Furthermore, absolute URL paths are given from the root directory /, so they too don’t reveal which of the volumes in the volume group an item is stored on.

Inode numbers do make it easy to identify firmlinks: just like hard links, the two directories forming the firmlink have identical inode numbers; as they are directories and APFS doesn’t support directory hard links, they can only be firmlinks.

For details of the roles and purposes of standard folders in Mojave, and those within the Home folder, please refer back to the previous article detailing the volume layout of macOS 10.14.