Our thinking


Create empty directories and symlinks at the root of the boot volume on macOS Catalina 10.15 – synthetic.conf

On macOS Catalina 10.15, the entire boot volume is mounted read-only. All user data, apps, configuration, preferences etc, exists on the data volume which is mounted at /System/Volumes/Data. Even as the root user, you do not have access to create anything on the root volume in macOS Catalina.

Fortunately, Apple have provided a way to create empty directories and symlinks to other directories or files, via synthetic.conf

From the manpage:

synthetic.conf describes virtual symbolic links and empty directories to be created at the root mount point. Because the root mount point is read-only as of macOS 10.15, physical files may not be created at this location. All writeable paths must reside on the data volume, which is mounted at /System/Volumes/Data.

synthetic.conf provides a mechanism for some limited, user-controlled file-creation at /. The synthetic entities described in this file are synthesized by the kernel during early system boot. They are not physically present on the disk, but when the system is booted, they behave as if they were within certain parameters.

synthetic.conf is intended to be used for creating mount points at / (e.g. for use as NFS mount points in enterprise deployments) and symbolic links (e.g. for creating a package manager root without modifying the system volume). synthetic.conf is read by apfs.util during early system boot.

Examples

# create an empty directory named "foo" at / which may be
# mounted over
foo

# create a symbolic link named "bar" at / which points to
# "System/Volumes/Data/bar", a writeable location at the
# root of the data volume
bar     System/Volumes/Data/bar

# create a symbolic link named "baz" at / which points to
# "Users/me/baz"
baz     Users/me/baz

2 thoughts on “Create empty directories and symlinks at the root of the boot volume on macOS Catalina 10.15 – synthetic.conf

  1. Make sure you only use a tab between the items in the synthetic.conf file. If you use spaces it will not work. Some editors change tabs to spaces so be careful.

Leave a Reply