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:
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.
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
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.
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.
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
Leave a Reply
Recent Comments
 | sxilderik on Using /etc/auto_home on Maveri… |
 | The Audience on Running recoverydiagnose in ma… |
 | Buddy on Suppressing the Data & Pri… |
| Buddy on Suppressing the Touch ID pop-u… |
 | dreamer (@alabrian) on Rebuilding your macOS Recovery… |
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 ?
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’?
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
after changing this my MAC is not booting after successful Login, any idea how to remove that File
Better to not do this. My Mac does not boot anymore.
Brilliant , I would never have figured this out myself.
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.