We have mentions of the feature, however (unless I'm missing something): * there's nothing like a plain English explanation of the feature. As far as I can tell, this bug affects: * documentation, including the FreeBSD Handbook and its detached glossary e.g. <https://docs.freebsd.org/en/books/handbook/glossary/#_s> * manual pages, e.g. tuning(7) <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7&manpath=FreeBSD> and/or tunefs(8) <https://www.freebsd.org/cgi/man.cgi?query=tunefs&sektion=8&manpath=FreeBSD> For a manual page: a single sentence should suffice. For more detailed documentation: something more explanatory, to include pros and cons. Thanks
(In reply to Graham Perrin from comment #0) FAQ 8.3 in https://docs.freebsd.org/en/books/faq/#disks has some of the pros and cons for using SU or SU+J, but doesn't describe their workings. For that, see https://dsf.berkeley.edu/cs262/seltzer00.pdf and https://freebsdfoundation.org/wp-content/uploads/2014/03/Journaled-Soft-Updates.pdf.
(In reply to PauAmma from comment #1) <https://docs.freebsd.org/en/books/faq/#safe-softupdates> (8.3) ends with this (a con, not a pro): > … dump(8) does not work in live mode (-L) on a filesystem, with > Journaled Soft Updates (SU+J). I see no pro anywhere in 8.3. Please, am I missing something?
(In reply to Graham Perrin from comment #2) The pros, as I see it, are implicit in the "these restrictions and caveats are probably outweighed by the (unstated) benefits for most use case, but you should weigh them for your own" tone I see in that FAQ. So I don't think you did. I was arguably confusingly terse here.
Noting here that both are discussed in 12.10.2 (in Configuration and Tuning), but that may not be the best location for that. Maybe they would fit better in Storage (chapter 18).
Re: bug 263433 comment 1 Previously undiscovered by me (not mentioned in relevant pages): ffs(7) > … Soft updates can also add journaling that reduces the time spent by > fsck_ffs(8) cleaning up a filesystem after a crash from several minutes > to a few seconds. The journal is placed in an inode named .sujournal, > and is kept as a circular log of segments containing records that > describe metadata operations. …
(In reply to Graham Perrin from comment #0) (In reply to Graham Perrin from comment #5) > Previously undiscovered by me (not mentioned in relevant pages): I mean, there's no mention of ffs(7) in: * fsck_ffs(8) * tunefs(8) * tuning(7) * the FreeBSD Handbook * …
Sorry, not closed. I'd like to blame one of my cats for treading on the status menu whilst I was in the kitchen. Incidentally, around <https://discord.com/channels/727023752348434432/757305697527398481/999430021242425454> in #storage there's not yet a shared understanding of the purpose and effects of journaling.
(In reply to Graham Perrin from comment #5) mckusick@ please: what's the essence of journaling (in the context of SU)? Is it as described in ffs(7)? > … reduces the time spent by fsck_ffs(8) cleaning up … <https://www.freebsd.org/cgi/man.cgi?query=ffs&sektion=7&manpath=FreeBSD#DESCRIPTION>
(In reply to Graham Perrin from comment #8) Here is an expanded explanation of journaled soft updates: I will leave it to you / others to figure out where it should go. My take is that all but the last paragraph should at least be added to tunefs(8). =-=-= Soft updates can add journaling that reduces the time spent by fsck_ffs(8) cleaning up a filesystem after a crash to a few seconds from minutes to hours. It is possible to run fsck_ffs(8) in background on a live filesystem though the filesystem performance will be about half of normal during the time that the background fsck_ffs(8) is running. Without journaling, the time to recover after a crash is a function of the number of files in the filesystem and the size of the filesystem. With journaling, the time to recover after a crash is a function of the amount of activity in the filesystem in the minute before the crash. Journaled recovery time is usually only a few seconds and never exceeds a minute. The drawback to using journaling is that the writes to its log adds an extra write load to the media containing the filesystem. Thus a write-intensive workload will have reduced throughput on a filesystem running with journaling. Like all journaling filesystems, the journal recovery will only fix issues known to the journal. Specifically if a media error occurs, the journal will not know about it and hence will not fix it. Thus when using journaling, it is still necessary to run a full fsck every few months or after a filesystem panic to check for and fix any errors brought on by media failure. A full fsck can be done by running a background fsck on a live filesystem or by running with the -f flag on an unmounted filesystem. Running a full fsck on a UFS filesystem is the equivalent of running a scrub on a ZFS filesystem. Presently it is not possible to take a snapshot on a UFS filesystem running with journaled soft updates. Thus it is not possible to reliably dump mounted filesystems or to run background fsck on them. The FreeBSD Foundation has sponsored me to make snapshots possible on journaled filesystems. I anticipate having that project completed by July 2023.
8.3 in https://docs.freebsd.org/en/books/faq/#disks may also be relevant - and or need an update.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=82493ff7007abb5a2d059c74748d2907dafc5395 commit 82493ff7007abb5a2d059c74748d2907dafc5395 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-15 20:44:49 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-08-15 20:45:48 +0000 Add a description of soft updates journaling to tunefs(8). Add a descrition to the tunefs(8) -j (journal enablement) flag that explains what soft updates journaling does, the tradeoffs to using it, and the limitations that it imposes. Requested by: Graham Perrin PR: 261944 Sponsored by: The FreeBSD Foundation sbin/tunefs/tunefs.8 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
I have added the text to tunefs(8) to explain the journaling (-j) option. I have left this PR `In Progress' as a reminder that this information also needs to be added to other parts of the FreeBSD documentation.
(In reply to Kirk McKusick from comment #12) Many thanks.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=128b0398a1d420e3cb6ab3a535558ae0a55df04b commit 128b0398a1d420e3cb6ab3a535558ae0a55df04b Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-16 23:46:12 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-08-16 23:46:59 +0000 Update date in tunefs(8) manual page. Requested by: Li-Wen Hsu PR: 261944 Sponsored by: The FreeBSD Foundation sbin/tunefs/tunefs.8 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
<https://cgit.freebsd.org/doc/tree/documentation/content/en/books/handbook/disks/_index.adoc?id=a8c5c8965cd534ff9634d95e6d84edb321c273d5#n1609>: > For more information about `softupdates` and file system snapshots, > including technical papers, visit Marshall Kirk McKusick's website at > http://www.mckusick.com/[http://www.mckusick.com/]. Instead of `softupdates`, easier on the eye for a first-time reader: soft updates It's certain that information about software updates is at (HTTPS) <https://www.mckusick.com/>, however it's not immediately obvious where to begin looking. Let's also refer from this part of the FreeBSD Handbook, to ffs(7). <https://www.freebsd.org/cgi/man.cgi?query=ffs&sektion=7&manpath=FreeBSD> Plus (comment 6) include ffs(7) under SEE ALSO sections such as <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7&manpath=FreeBSD#SEE_ALSO>.
(In reply to Graham Perrin from comment #15) > software updates Oops. Of course, I meant: > soft updates
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=0929a153fc5cfe35f7390ab5870a36daed19b0ce commit 0929a153fc5cfe35f7390ab5870a36daed19b0ce Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-10-21 17:56:20 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-21 17:57:31 +0000 Add a description of soft updates journaling to newfs(8). Add a descrition to the newfs(8) -j (journal enablement) flag that explains what soft updates journaling does, the tradeoffs to using it, and the limitations that it imposes. Copied from the description in tunefs(8). PR: 261944 Sponsored by: The FreeBSD Foundation sbin/newfs/newfs.8 | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-)
Merge all three commits to both stable/12 and stable/13? 82493ff7007abb5a2d059c74748d2907dafc5395 128b0398a1d420e3cb6ab3a535558ae0a55df04b 0929a153fc5cfe35f7390ab5870a36daed19b0ce In time for 12.4-RELEASE would be nice. Thanks again. <https://www.freebsd.org/releases/12.4R/>
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=9f004375ae01b5536a5bb9ca09bc29a69750cedf commit 9f004375ae01b5536a5bb9ca09bc29a69750cedf Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-15 20:44:49 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-31 03:41:30 +0000 Add a description of soft updates journaling to tunefs(8). Requested by: Graham Perrin PR: 261944 Sponsored by: The FreeBSD Foundation (cherry picked from commit 82493ff7007abb5a2d059c74748d2907dafc5395) sbin/tunefs/tunefs.8 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=759ee8654012dc35380eed6204bf4f35f6eacaaf commit 759ee8654012dc35380eed6204bf4f35f6eacaaf Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-10-21 17:56:20 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-31 03:45:10 +0000 Add a description of soft updates journaling to newfs(8). PR: 261944 Sponsored by: The FreeBSD Foundation (cherry picked from commit 0929a153fc5cfe35f7390ab5870a36daed19b0ce) sbin/newfs/newfs.8 | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-)
A commit in branch stable/12 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=de1f80e4c1386614a8b6c7b31d861d20930995cc commit de1f80e4c1386614a8b6c7b31d861d20930995cc Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-15 20:44:49 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-31 03:49:17 +0000 Add a description of soft updates journaling to tunefs(8). Requested by: Graham Perrin PR: 261944 Sponsored by: The FreeBSD Foundation (cherry picked from commit 82493ff7007abb5a2d059c74748d2907dafc5395) sbin/tunefs/tunefs.8 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
A commit in branch stable/12 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=1639fa2cd5483e43d0fe1418f92090587f975b88 commit 1639fa2cd5483e43d0fe1418f92090587f975b88 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-16 23:46:12 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-31 03:50:07 +0000 Update date in tunefs(8) manual page. PR: 261944 Sponsored by: The FreeBSD Foundation (cherry picked from commit 128b0398a1d420e3cb6ab3a535558ae0a55df04b) sbin/tunefs/tunefs.8 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
A commit in branch stable/12 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=b06a5f6f5e3910951f61ee8314ac66fb9ec7029e commit b06a5f6f5e3910951f61ee8314ac66fb9ec7029e Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-10-21 17:56:20 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-10-31 03:53:19 +0000 Add a description of soft updates journaling to newfs(8). Requested by: Graham Perrin PR: 261944 Sponsored by: The FreeBSD Foundation (cherry picked from commit 0929a153fc5cfe35f7390ab5870a36daed19b0ce) sbin/newfs/newfs.8 | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-)
A commit in branch releng/12.4 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=0f58c5454c660ea744963bc0cb347646da4b4cb8 commit 0f58c5454c660ea744963bc0cb347646da4b4cb8 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-10-21 17:56:20 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-11-01 00:11:22 +0000 Add a description of soft updates journaling to newfs(8). Requested by: Graham Perrin PR: 261944 Approved by: re (gjb) Sponsored by: The FreeBSD Foundation (cherry picked from commit 0929a153fc5cfe35f7390ab5870a36daed19b0ce) (cherry picked from commit 759ee8654012dc35380eed6204bf4f35f6eacaaf) sbin/newfs/newfs.8 | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-)
A commit in branch releng/12.4 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=aff7cd295fdb8caf2d58d5ec4eb295c6d164f13a commit aff7cd295fdb8caf2d58d5ec4eb295c6d164f13a Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-16 23:46:12 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-11-01 00:04:18 +0000 Update date in tunefs(8) manual page. PR: 261944 Approved by: re (gjb) Sponsored by: The FreeBSD Foundation (cherry picked from commit 128b0398a1d420e3cb6ab3a535558ae0a55df04b) (cherry picked from commit 1639fa2cd5483e43d0fe1418f92090587f975b88) sbin/tunefs/tunefs.8 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
A commit in branch releng/12.4 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=a1017358b35e81ce2057ebf06d00b83cdb7f9ac9 commit a1017358b35e81ce2057ebf06d00b83cdb7f9ac9 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2022-08-15 20:44:49 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2022-11-01 00:01:40 +0000 Add a description of soft updates journaling to tunefs(8). Requested by: Graham Perrin PR: 261944 Approved by: re (gjb) Sponsored by: The FreeBSD Foundation (cherry picked from commit 82493ff7007abb5a2d059c74748d2907dafc5395) (cherry picked from commit de1f80e4c1386614a8b6c7b31d861d20930995cc) sbin/tunefs/tunefs.8 | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
Changes have been MFC'ed to 13 and 12 plus pushed to releng/12.4.