Skip to content

Instantly share code, notes, and snippets.

@rrrix
Last active September 13, 2022 00:44
Show Gist options
  • Save rrrix/fa91a0d912ce98f2d60075765f947d2e to your computer and use it in GitHub Desktop.
Save rrrix/fa91a0d912ce98f2d60075765f947d2e to your computer and use it in GitHub Desktop.
Man: synthetic.conf(5) - synthetic symbolic link and directory manifest
SYNTHETIC.CONF(5) File Formats Manual SYNTHETIC.CONF(5)
NAME
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 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(8) during early system boot.
FILES
/etc/synthetic.conf
CONFIGURATION DIRECTORY
Individual subsystems may add their own synthetic manifests to
/etc/synthetic.d to avoid having to append to to share the content of
synthetic.conf. This is similar to the mechanisms which exist for shell
and manual page paths, paths.d and manpaths.d, respectively. If multiple
manifests specify the same synthetic link or directory name, the one
respected by the implementation is undefined. The structure of these
manifests is identical to that of synthetic.conf.
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 a symbolic link named "srv" at / which points to
# "System/Volumes/Data/srv", a writeable location at the root of the data volume
srv /System/Volumes/Data/srv
# create an empty directory named "foo" at / which may be mounted over
foo
# create a symbolic link named "baz" at / which points to "Users/me/baz"
baz Users/me/baz
DIRECTORIES
/etc/synthetic.d
SEE ALSO
reboot(2), apfs.util(8), shutdown(8)
Darwin/macOS September 3, 2019 Darwin/macOS
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment