synthetic.conf

SYNTHETIC.CONF(5)           BSD File Formats Manual          SYNTHETIC.CONF(5)

NNAAMMEE
     ssyynntthheettiicc..ccoonnff

SSYYNNOOPPSSIISS
     ssyynntthheettiicc..ccoonnff -- synthetic symbolic link and directory manifest

DDEESSCCRRIIPPTTIIOONN
     ssyynntthheettiicc..ccoonnff 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 _/_S_y_s_t_e_m_/_V_o_l_u_m_e_s_/_D_a_t_a.

     ssyynntthheettiicc..ccoonnff 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.

     ssyynntthheettiicc..ccoonnff 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).  ssyynntthheettiicc..ccoonnff is read by apfs.util(8) during early sys-
     tem boot.

FFOORRMMAATT
     ssyynntthheettiicc..ccoonnff 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.

SSYYNNTTHHEETTIICC EENNTTIITTIIEESS
     Synthetic entities may not be deleted at runtime. In order to delete a
     synthetic entity, it must be removed from ssyynntthheettiicc..ccoonnff, and the host
     must be rebooted.

     New files and directories may not be created within a synthetic empty
     directory.

EEXXAAMMPPLLEESS
           # 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

FFIILLEESS
     _/_e_t_c_/_s_y_n_t_h_e_t_i_c_._c_o_n_f

SSEEEE AALLSSOO
     apfs.util(8) shutdown(8) reboot(2)

Darwin/macOS                      2 July 2019                     Darwin/macOS