Home > Mac administration, macOS > Creating root-level directories and symbolic links on macOS Catalina

Creating root-level directories and symbolic links on macOS Catalina

One of the changes which came with macOS Catalina was the introduction of a read-only root volume for the OS. For users or environments which were used to using adding directories to the root level of the boot drive, this change meant they could no longer do that.

To address this need, Apple added a new method for creating directories at the root level which leverages Apple File System’s new firmlink functionality. Firmlinks are new in macOS Catalina and are similar in function to Unix symbolic links, but instead of only allowing travel one way (from source to destination) firmlinks allow bi-directional travel.

The use of firmlinks is exclusively reserved for the OS’s own use, but Apple has also made available what are called synthetic firmlinks. These synthetic firmlinks are how the OS enables folks to create directories and symbolic links on the read-only boot volume. For more details, please see below the jump.

To create a synthetic firmlink, you need to do the following:

1. Create a file in the /etc directory named synthetic.conf.
2. Make sure /etc/synthetic.conf has the following permissions:

  • root: read, write
  • wheel: read
  • everyone: read

3. In /etc/synthetic.conf, define the name(s) of the empty directory or symbolic link you want to have appear at the root level.

4. After all desired entries have been made, save the /etc/synthetic.conf file.

5. Restart the Mac to apply the changes.

For example, /etc/synthetic.conf may look like this:

# 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

view raw
synthetic.conf
hosted with ❤ by GitHub

Note: In those cases where you’re creating a symbolic link and are including a path, the start point for the directory path is not /. Instead, it is the next directory level down.

To show how this works, I’ve created a directory containing installer packages located at /Users/Shared/installers.

Screen Shot 2020 01 17 at 10 46 06 PM

To create a symbolic link at the root level named installers which points to /Users/Shared/installers, I would do the following:

1. Create the /etc/synthetic.conf file if it didn’t already exist.
2. Add the following entry to the /etc/synthetic.conf file:

installers	Users/Shared/installers

Screen Shot 2020 01 17 at 10 32 45 PM

3. Reboot the Mac.

Note: Whomever designed this came down on the “tabs” side of the “tabs vs. spaces” debate. When creating the separation between installers and Users/Shared/installers in the /etc/synthetic.conf file, you need to use tabs. If you use spaces instead, the synthetic firmlink won’t be created.

After the reboot, you should see a symbolic link named installers at the root level of the boot volume. When you navigate to it, you should see the contents of /Users/Shared/installers.

Screen Shot 2020 01 17 at 10 33 30 PM

To remove the symbolic link, remove the relevant entry from /etc/synthetic.conf and then restart. After the reboot, the installers symbolic link should be missing from the root level of the boot volume.

Screen Shot 2020 01 17 at 10 46 15 PM

For more information, please see the synthetic.conf man page. This is available by entering the following command in Terminal on macOS Catalina:

man synthetic.conf
SYNTHETIC.CONF(5) BSD File Formats Manual SYNTHETIC.CONF(5)
NAME
synthetic.conf
SYNOPSIS
synthetic.conf — synthetic symbolic link and directory manifest
DESCRIPTION
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 loca-
tion. 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 physi-
cally 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(8) during early sys-
tem boot.
FORMAT
synthetic.conf specifies a single synthetic entity per line. Each line
may have one or two columns, separated by a tab character. If a line has
a single column, it denotes a virtual empty directory to be created at /.
If a line has two columns, it denotes a symbolic link at / whose link
target is given in the second column.
In either case, the first column denotes the name of the entity to be
created at /.
A line beginning with the # character indicates a comment that is not
parsed.
SYNTHETIC ENTITIES
Synthetic entities may not be deleted at runtime. In order to delete a
synthetic entity, it must be removed from synthetic.conf, and the host
must be rebooted.
New files and directories may not be created within a synthetic empty
directory.
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
FILES
/etc/synthetic.conf
SEE ALSO
apfs.util(8) shutdown(8) reboot(2)
Darwin/macOS 2 July 2019 Darwin/macOS

view raw
synthetic_conf.txt
hosted with ❤ by GitHub

Categories: Mac administration, macOS
  1. Laurent
    February 26, 2020 at 1:41 pm

    Thanks for the explanation.

    Do you know if there is a way to create such symlinks without rebooting and just a signal to a process ?

  2. March 4, 2020 at 10:18 pm

    Thank you for this solution, this works if the volume_name is used at the root of the volume. Now what if your entire company relies on pathing ‘/mnt/volume_name’ instead of ‘/volume_name’?

    • March 10, 2020 at 2:07 pm

      Figured this out, by reading the documentation. You can create empty dirs as well as symlinks.

      /etc/synthetic.conf
      mnt /System/Volumes/Data/../Data/Volumes/mnt
      mnt/directory /System/Volumes/Data/../Data/Volumes/mnt/directory

      /etc/auto_company
      /System/Volumes/Data/../Data/Volumes/mnt/directory -fstype=nfs, nfs.company.com:/ingest

  3. Ram
    May 7, 2020 at 12:29 pm

    after changing this my MAC is not booting after successful Login, any idea how to remove that File

  4. Amol
    June 5, 2020 at 6:58 pm

    Better to not do this. My Mac does not boot anymore.

  5. Dave
    July 23, 2020 at 6:46 am

    Brilliant , I would never have figured this out myself.

  6. AZ
    July 23, 2020 at 5:46 pm

    I need to simulate a series of folders at a mount point and a friend helped me come up with a solution that uses a traditional symbolic link and the new firmlink. I thought I would share to help anyone else that has this problem.

    Path I need to simulate: mnt/NAS/data/Documents/DB. Actual location is /Volumes/Documents/DB

    From the writable location /System/Volumes/Data, I created directories (must use sudo) for /System/Volumes/Data/mnt/NAS/data

    Then while connected to the server,
    sudo ln -s /Volumes/Documents /System/Volumes/Data/mnt/NAS/data/Documents

    Then in /etc/synthetic.conf
    mnt /System/Volumes/Data/mnt

    After restart, items can be accessed from the /mnt/NAS/data/Documents/ filepath.

  7. Michelle Dougenik
    August 30, 2020 at 1:44 am

    If you do this and your mac no longer boots up, boot into Recovery mode, use the Terminal utility to mount the volume and remove the synthetic.conf file. Then reboot.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: