You've already forked linux-apfs-rw
mirror of
https://github.com/linux-apfs/linux-apfs-rw.git
synced 2026-05-01 15:01:34 -07:00
Ernesto A. Fernández
6a24fdcb2e
Fusion drives now have read-only support, so update the readme. Signed-off-by: Ernesto A. Fernández <ernesto@corellium.com>
117 lines
4.0 KiB
ReStructuredText
117 lines
4.0 KiB
ReStructuredText
===========================
|
|
Apple File System for Linux
|
|
===========================
|
|
|
|
The Apple File System (APFS) is the copy-on-write filesystem currently used on
|
|
all Apple devices. This module provides a degree of experimental support on
|
|
Linux. It's intended to work with all kernel versions since 4.12, but testing
|
|
is focused on 5.18 and above.
|
|
|
|
To help test write support, a set of userland tools is also under development.
|
|
The git tree can be retrieved from https://github.com/eafer/apfsprogs.git.
|
|
|
|
Known limitations
|
|
=================
|
|
|
|
This module is the result of reverse engineering and testing has been limited.
|
|
If you make use of the write support, there is a real risk of data corruption,
|
|
so mounts are read-only by default. Please report any issues that you find.
|
|
|
|
Writes to fusion drives will likely never be supported, though I might
|
|
reconsider this if people actually need it. Encryption is not yet implemented
|
|
even in read-only mode.
|
|
|
|
Reporting bugs
|
|
==============
|
|
|
|
If you encounter any problem, the first thing you should do is run (as root)::
|
|
|
|
dmesg | grep -i apfs
|
|
|
|
to see all the error messages. If that doesn't help you, please file a github
|
|
issue at https://github.com/eafer/linux-apfs-rw/issues. Or send me an email if
|
|
you prefer.
|
|
|
|
Build
|
|
=====
|
|
|
|
Note that at this point the driver has been packaged for several distros, so
|
|
it may be more convenient to install it from there instead of building it
|
|
yourself. The distro packages are often outdated though, so be sure to check
|
|
the version.
|
|
|
|
In order to build a module out-of-tree, you will first need the Linux kernel
|
|
headers. Depending on your distro, you can get them by running (as root)::
|
|
|
|
# Debian/Ubuntu
|
|
apt-get install linux-headers-$(uname -r)
|
|
|
|
# Arch/Manjaro
|
|
pacman -Sy linux-headers
|
|
|
|
# RHEL/Rocky/CentOS/Fedora
|
|
yum install kernel-headers kernel-devel
|
|
|
|
Now you can just cd to the linux-apfs-rw directory and run::
|
|
|
|
make
|
|
|
|
The resulting module is the apfs.ko file. Before you can use it you must insert
|
|
it into the kernel, as well as its dependencies. Again as root::
|
|
|
|
modprobe libcrc32c
|
|
insmod apfs.ko
|
|
|
|
Mount
|
|
=====
|
|
|
|
Like all filesystems, apfs is mounted with::
|
|
|
|
mount [-o options] device dir
|
|
|
|
where ``device`` is the path to your device file or filesystem image, and
|
|
``dir`` is the mount point. The following options are accepted:
|
|
|
|
============ =================================================================
|
|
vol=n Volume number to mount. The default is volume 0.
|
|
|
|
snap=label Volume snapshot to mount (in read-only mode).
|
|
|
|
tier2=path Path to the tier 2 device. For fusion drives only.
|
|
|
|
uid=n, gid=n Override on-disk inode ownership data with given uid/gid.
|
|
|
|
cknodes Verify the checksum on all metadata nodes. Right now this has a
|
|
severe performance cost, so it's not recommended.
|
|
|
|
readwrite Enable the experimental write support. This may corrupt your
|
|
container.
|
|
============ =================================================================
|
|
|
|
So for instance, if you want to mount volume number 2, and you want the metadata
|
|
to be checked, you should run (as root)::
|
|
|
|
mount -o cknodes,vol=2 device dir
|
|
|
|
To unmount it, run::
|
|
|
|
umount dir
|
|
|
|
Credits
|
|
=======
|
|
|
|
Originally written by Ernesto A. Fernández <ernesto@corellium.com>, with
|
|
several contributions from Gabriel Krisman Bertazi <krisman@collabora.com>,
|
|
Arnaud Ferraris <arnaud.ferraris@collabora.com> and Stan Skowronek
|
|
<skylark@disorder.metrascale.com>. For attribution details see the historical
|
|
git tree at https://github.com/eafer/linux-apfs.git.
|
|
|
|
Work was first based on reverse engineering done by others [1]_ [2]_, and later
|
|
on the (very incomplete) official specification [3]_. Some parts of the code
|
|
imitate the ext2 module, and to a lesser degree xfs, udf, gfs2 and hfsplus.
|
|
|
|
.. [1] Hansen, K.H., Toolan, F., Decoding the APFS file system, Digital
|
|
Investigation (2017), https://dx.doi.org/10.1016/j.diin.2017.07.003
|
|
.. [2] https://github.com/sgan81/apfs-fuse
|
|
.. [3] https://developer.apple.com/support/apple-file-system/Apple-File-System-Reference.pdf
|