{"id":13645705,"url":"https://github.com/sgan81/apfs-fuse","last_synced_at":"2025-05-15T11:07:35.135Z","repository":{"id":39620256,"uuid":"106879638","full_name":"sgan81/apfs-fuse","owner":"sgan81","description":"FUSE driver for APFS (Apple File System)","archived":false,"fork":false,"pushed_at":"2024-08-13T19:36:10.000Z","size":759,"stargazers_count":1895,"open_issues_count":111,"forks_count":166,"subscribers_count":53,"default_branch":"master","last_synced_at":"2025-04-11T20:00:00.851Z","etag":null,"topics":["apfs","apfs-fuse","apple","driver","encryption","filesystem","fuse-driver","linux","mount","volume"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgan81.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-13T22:40:39.000Z","updated_at":"2025-04-11T18:40:36.000Z","dependencies_parsed_at":"2024-01-13T10:42:59.784Z","dependency_job_id":"16801c56-bedc-40a7-a114-0ac6f3dc9884","html_url":"https://github.com/sgan81/apfs-fuse","commit_stats":{"total_commits":96,"total_committers":7,"mean_commits":"13.714285714285714","dds":"0.19791666666666663","last_synced_commit":"66b86bd525e8cb90f9012543be89b1f092b75cf3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgan81%2Fapfs-fuse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgan81%2Fapfs-fuse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgan81%2Fapfs-fuse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgan81%2Fapfs-fuse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgan81","download_url":"https://codeload.github.com/sgan81/apfs-fuse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apfs","apfs-fuse","apple","driver","encryption","filesystem","fuse-driver","linux","mount","volume"],"created_at":"2024-08-02T01:02:40.159Z","updated_at":"2025-05-15T11:07:35.112Z","avatar_url":"https://github.com/sgan81.png","language":"C++","funding_links":[],"categories":["C++","Challenges","Linux","Tools","Static Analysis"],"sub_categories":["OS X Forensics","Kernel"],"readme":"\n# APFS FUSE Driver for Linux\n\nThis project is a read-only FUSE driver for the new Apple File System. It also supports software\nencrypted volumes and fusion drives. Firmlinks are not supported yet.\n\nBe aware that not all compression methods are supported yet (only the ones I have encountered so far).\nThus, the driver may return compressed files instead of uncompressed ones. Although most of the time it\nshould just report an error.\n\n## Changelog\n\n| Date | Comment |\n|------|---------|\n| 2020-07-08 | Added support for mounting snapshots and sealed volumes |\n| 2018-04-20 | Added support for mounting DMGs |\n| 2018-04-14 | Added support for partition tables (GPT only) |\n| 2018-04-10 | Fixed and extended FileVault encryption support |\n| 2018-03-28 | Added support for FileVault encryption |\n| 2017-10-25 | Added support for encryption |\n| 2017-10-14 | Initial version |\n\n## Usage\n\n### Compile the source code\nThe following libraries are needed (including the -dev/-devel packages):\n\n* FUSE 2.6 or greater (on 32-bit systems, FUSE 3.0 or greater)\n* zlib\n* bzip2\n* libattr (on some Linux distributions)\n\nDevelopment tools:\n* cmake\n* gcc-c++ (or clang++)\n* git (for cloning)\n\nExample for Linux:\n```\nsudo apt update\nsudo apt install fuse libfuse3-dev bzip2 libbz2-dev cmake gcc-c++ git libattr1-dev zlib1g-dev\n```\nOf course these commands depend on the Linux distribution.\n\nClone the repository:\n```\ngit clone https://github.com/sgan81/apfs-fuse.git\ncd apfs-fuse\ngit submodule init\ngit submodule update\n```\nThe driver uses Apple's lzfse library and includes it as a submodule.\n\nCompile the driver:\n```\nmkdir build\ncd build\ncmake ..\nccmake . # Only if you want to change build options\nmake\n```\n\nNote that the driver uses FUSE 3.0 by default (required on 32-bit systems). If\nyou want do compile using FUSE 2.6, use `ccmake .` to change the option\n`USE_FUSE3` to `OFF`.\n\n### Mount a drive\n```\napfs-fuse \u003cdevice\u003e \u003cmount-directory\u003e\n```\n#### Supported options:\n* `-d n`: If n \u003e 0, enable debug output (see below for details).\n* `-f device`: Specify secondary device for Fusion drive.\n* `-o opts`: Comma-separated list of mount options.\n* `-l`: Lax mode: when unexpected data is encountered, try to continue, even if this means\n  returning potentially incorrect data.\n* `-v n`: Instead of mounting the first volume in a container, mount volume n (starting at 0).\n* `-r recovery_key`: Mount an encrypted volume by supplying a password or Personal Recovery Key (PRK).\n* `-s n`: Find the container at offset n inside the device. This is useful when using an image file\n  instead of a disk device, and therefore partitions are not exposed.\n* `-p n`: Find the container at partition n inside the device.\n\nIf you are using an image file containing partitions, the driver will now detect if there is a valid GPT\npartition table. If there is, it will look for the first APFS partition and use that one for the container.\nIf your drive contains more than one APFS container, you can specify the partition/container id with the\n`-p` option.\n\nThe device has to be the one containing the APFS container. If a container contains more than one volume,\nthe volume can be specified by the `-v` option.\n\nIf a volume is encrypted, the apfs-fuse command will prompt for a password, unless a password or PRK is\nspecified on the command line. The PRK can also be used as password.\n\nIt is also possible to directly mount DMG files. The driver will automatically detect if a dmg\nhas to be mounted and take appropriate action. If a dmg is encrypted, you will be asked for the password.\nNote that dmg support is currently a bit slow (especially when compressed), but it should work properly.\n\nThe debug flags are now a combination of bits. So to enable specific output, you just add the numbers\nmentioned below together, and use the result as parameter for -d.\n\n* 1 Display more information about errors\n* 2 Display additional generic information\n* 4 Display information about directory-related operations\n* 8 Display information about on-the-fly compression\n* 16 Display information about cryptographic operations (caution, displays keys as well)\n\n#### Mount options (-o ...)\nIn addition to the mount options supported by fuse, the following mount options are supported:\n* uid=n: Pretend that all files have UID n.\n* gid=n: Pretend that all files have GID n.\n* vol=n: Same as -v, specify the volume number to mount if you don't want volume 0.\n* blksize=n: Set the physical block size (default: 512 bytes).\n* pass=...: Specify volume passphrase (same as -r).\n* xid=...: Try to mount older XID. May be useful if the container is corrupt.\n* snap=...: Mount snapshot with given XID. Use apfsutil to display snapshot ids.\n\nThe blksize parameter is required for proper partition table parsing on some newer\nmacs. However the current driver should be able to detect the block size automatically.\n\nIf you mount a volume as root and want some user to be able to access it, use:\n```\napfs-fuse -o uid=\u003cuid\u003e,gid=\u003cgid\u003e,allow_other /dev/\u003cdevice\u003e \u003cmount-path\u003e\n```\n\nIf you want to mount a device as user, add yourself to the disk group. This might not be too safe though,\nas it allows any application to read and write anywhere on a drive.\n\n### Unmount a drive\nAs root:\n```\numount \u003cmount-directory\u003e\n```\n\nAs user:\n```\nfusermount -u \u003cmount-directory\u003e\n```\n\n## Features\nThe following features are implemented:\n\n* Can read macOS 10.13 case sensitive and insensitive volumes, as well as iOS 11 / macOS 10.12 volumes\n* Transparent decompression of ZLib and LZVN\n* Symlinks\n* Hardlinks (it seems ...)\n* Extended attributes\n* Software encryption (at least full-disk encryption)\n* Automatic detection of GPT partition tables\n* Direct mounting of DMG images (supports zlib/adc compression and encryption)\n\n## Limitations\nThese things are not supported (yet):\n\n* Transparent decompression of LZFSE\n* Writing\n* Hardware-encrypted volumes (internal drives of Macs with T2 chip)\n\n## Debugging\n\nSince the driver is still experimental and based on analysis of a limited set of drives / volumes, crashes\nmay unfortunately still happen. If a crash happens, providing me with useful information can be very helpful.\n\nOne of the most important pieces of information is the location where the program crashed. You can find that\nout by debugging the tool. In order to debug the program, do the following:\n\nChange the main CMakeLists.txt as follows: In the line `set(CMAKE_BUILD_TYPE Release)`,\nreplace `Release` with `Debug`.\n\nRebuild everything.\n\nRun it under `gdb`. Like this:\n```\ngdb apfs-fuse\n\n(In gdb):\nset args \u003coptions\u003e \u003cdevice\u003e \u003cmount-directory\u003e\nrun\n\n(And if/when it crashes):\nbacktrace\n\n(When you're finished):\nquit\n```\nAnd then send the output of `backtrace` to me. Adding `-d 1` to options might help as well, but be aware that\nit will generate a lot of output on the text console.\n\n### Some tools that might be useful\n#### apfs-dump-quick\n\nIf you encounter problems with some file, it may be that I overlooked something during reverse engineering. In that\ncase, you can use the `apfs-dump-quick` command to dump the management structures of the whole drive. It can be run\nas follows:\n```\napfs-dump-quick \u003cdrive\u003e \u003clogfile.txt\u003e\n```\nThe tool will dump the most current version of the disk structures into a logfile. This file can become quite big, like\na few 100 MB. So to limit the amount of information to report, look for the name of the file in the log. Try to find a\nline starting with `File` and containing the filename. The number immediately after `File` is the ID. Find all lines\nhaving this ID, and include them in your bug report.\n#### apfs-dump\nThere is another command available:\n```\napfs-dump \u003cdrive\u003e \u003clogfile.txt\u003e\n```\nThis tool was the one I originally used for reverse engineering. It will scan the whole volume for clusters having\ncorrect checksums (and thus being part of some management structure), and then it will try to dump them. This will\ntake a very long time to run on big volumes, and create huge log files. So using the quick version will be much faster.\n#### apfsutil\n```\napfsutil \u003cdevice\u003e\n```\nThis is a new tool that just displays some information from a container. For now, it lists the volumes a container\ncontains, and snapshots if there are some. This tool might be extended in the future.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgan81%2Fapfs-fuse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgan81%2Fapfs-fuse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgan81%2Fapfs-fuse/lists"}