From ee05e730466f250e131eb92165bcdb8bab68c864 Mon Sep 17 00:00:00 2001 From: willcl-ark Date: Tue, 10 Dec 2024 14:27:20 +0000 Subject: [PATCH] util: document recommended filesystems In particular, recommend against using exFAT on MacOS as this is known to cause breakages. See #31454 for more context. --- doc/files.md | 8 ++++++++ src/common/init.cpp | 5 ++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/files.md b/doc/files.md index b738d6055a..3732a7d24a 100644 --- a/doc/files.md +++ b/doc/files.md @@ -16,6 +16,8 @@ - [Legacy subdirectories and files](#legacy-subdirectories-and-files) +- [Filesystem recommendations](#filesystem-recommendations) + - [Notes](#notes) ## Data directory location @@ -123,6 +125,12 @@ Path | Description | Repository notes `addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/bitcoin/bitcoin/pull/1198), [`928d3a01`](https://github.com/bitcoin/bitcoin/commit/928d3a011cc66c7f907c4d053f674ea77dc611cc) `onion_private_key` | Cached Tor onion service private key for `-listenonion` option. Was used for Tor v2 services; replaced by `onion_v3_private_key` in [0.21.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.21.0.md) | [PR #19954](https://github.com/bitcoin/bitcoin/pull/19954) +## Filesystem recommendations + +When choosing a filesystem for the data directory (`datadir`) or blocks directory (`blocksdir`), some filesystems should be avoided: + +- **MacOS**: The exFAT filesystem should not be used. There have been multiple reports of database corruption when using exFAT on MacOS for Bitcoin Core. This appears to be due to filesystem-level issues with exFAT on MacOS. See [Issue #31454](https://github.com/bitcoin/bitcoin/issues/31454) for more details. + ## Notes 1. The `/` (slash, U+002F) is used as the platform-independent path component separator in this document. diff --git a/src/common/init.cpp b/src/common/init.cpp index 40ca848344..812a781c5a 100644 --- a/src/common/init.cpp +++ b/src/common/init.cpp @@ -79,7 +79,10 @@ std::optional InitConfig(ArgsManager& args, SettingsAbortFn setting FSType fs_type = GetFilesystemType(check.path); switch(fs_type) { case FSType::EXFAT: - InitWarning(strprintf(_("Specified %s \"%s\" is exFAT which is known to have intermittent corruption problems on MacOS."), check.description, fs::PathToString(check.path))); + InitWarning(strprintf(_("Specified %s \"%s\" is exFAT which is known to have intermittent corruption problems on MacOS. " + "See https://github.com/bitcoin/bitcoin/blob/master/doc/files.md#filesystem-recommendations for more information."), + check.description, + fs::PathToString(check.path))); break; case FSType::ERROR: LogInfo("Failed to detect filesystem type of %s: %s\n", check.description, fs::PathToString(check.path));