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:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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 |
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
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
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 ?
I found that running `/System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B` will help generate any new firmlinks added to synthetic.conf without needing to reboot.
On macOS 11.6 it is the -t switch:
/System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
man apfs.util: “Stitches and creates synthetic objects on root volume group.”
When you’re stuck in Boot loop with seemingly correct syntax, try adding a comment at the end of synthetic.conf.
It seems blank mountpoint entries confuse macOS. Example comment:
#end of synthethic.conf for the sake of booting!
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.
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.
Thanks a lot,Solved the urgent need
inside /etc/synthetic.conf
aie /Users/dave/aie
but not create aie folder anymore.Please help to explain what you did.Thanks.
Remove the leading slash from Users
aie/System/Volumes/Data/../Data/Volumes/Users/Dave/aie
There should be a tab between aie and /System… otherwise it won’t work
I don’t think there is a “tabs vs spaces” debate here…the reason to use a tab to separate the two parameters is so the file paths can contain spaces without needed to quote them…keeps it all very simple.
This is a very useful and helpful page; I think I hit a Tab problem; I added a Tab with Emacs but I think this did not format the Tab properly; maybe also a blank.
My Macbook would not boot up so I had to boot into Safe mode and had to rm /etc/synthetic.conf. I manage to add a Tab properly with vi and then it worked OK.
My example was:
data Volumes/data
I am trying unsuccessfully to create a link to /Users/rgm from /home/rgm to make my Mac similar to my Linux box.
I tried this
System/Volumes/Data/home/rgm Users/rgm
but it does not work?
Any pointers would be welcome?
Hi,
I have local dir /home/dm/fusionops and I want this to be accessed as /home/fusionops so the below line in /etc/synthetic.conf is not working for me. I did reboot
/Users/dm/fusionops /System/Volumes/Data/home
Please help
I have mentioned the invalid local dir path … the valid path is: /Users/dm/fusionops
The line in /etc/synthetic.conf should be
Users/dm/fusionops/System/Volumes/Data/../Data/Volumes/home/fusionops
Will firm links work in the latest macOS(Monterey)?
I have tried to create such a /etc/synthetic.conf file under Monterey, but I forget to use tabs, so when I rebooted, my Mac would no boot, and when I used the recovery terminal the file wasn’t there. So there was nothing to delete. Now I’m trying to re-install Monterey hoping it will work otherwise I’m in d… s…
Follow-up: re-installing Monterey would not work, 12 minutes before the end of the re-install I got an error message “Re-install encountered an error”. Fortunately I had a backup of the disk before installing Monterey, so I used it. What an adventure…
You need not have re-installed macOS. See https://apple.stackexchange.com/questions/405323/remove-or-edit-a-synthetic-conf-file-in-etc The file wasn’t there in /etc because the volume isn’t mounted. It can be discovered elsewhere by running find / -name synthetic.conf
Would it be possible to use such links for an outsourced user folder?
The background of my question is, that we have several Intel Mac Mini from ’20 and ’21, that are connected in a network. Also in this network is a common Linux fileserver. Depending on the project, it can happen that our coworkers have to move to a different room and have to take their computer with them.
My idea was, do put all user accounts (folders) to a central place on the fileserver, so that you have access to all user accounts from all computer in the network.
The reason I want to have a new folder is that I have lot of movies under my “documents” folder (almost 180gb) and I don’t want to to be linked to icloud as it fills all the space.