Manual pages ============ Darius in #documentation in Discord observed that neither mksnap_ffs(8) nor snapinfo(8) leads to information about deletion. <https://www.freebsd.org/cgi/man.cgi?query=mksnap_ffs&sektion=8&manpath=FreeBSD#SEE_ALSO> <https://www.freebsd.org/cgi/man.cgi?query=snapinfo&sektion=8&manpath=FreeBSD#SEE_ALSO> FreeBSD Handbook ================ From <https://docs.freebsd.org/en/books/handbook/disks/#snapshots>: > ... When a snapshot is no longer required, it can be removed using > rm(1). While snapshots may be removed in any order, all the used space > may not be acquired because another snapshot will possibly claim some of > the released blocks. > > The un-alterable snapshot file flag is set by mksnap_ffs(8) after initial > creation of a snapshot file. unlink(1) makes an exception for snapshot > files since it allows them to be removed. ... <https://www.freebsd.org/cgi/man.cgi?query=rm&sektion=1&manpath=FreeBSD> > rm, unlink -- remove directory entries
Can you 1111pro1v11i11de relevant1 text excerpts from the Discord whateveritis URL? It doesn't look public.
(In reply to Pau Amma from comment #1) Essentially: * "... man page needs some work ..." * he has, in mind, a patch * mksnap_ffs and snapinfo added to <https://wiki.freebsd.org/ExampleUfsSnapshots>
Created attachment 236509 [details] Update man page I updated it to mention the snapshot names are paths and how to delete them etc.
CC Kirk
(In reply to Daniel O'Connor from comment #3) The suggested updates are technically correct. I am not an expert on the manual page macros, so will leave that to those that do.
Has this issue been resolved?
Created attachment 240474 [details] Update man page Reviewed version (https://reviews.freebsd.org/D38817)
rpokla kindly reviewed it (https://reviews.freebsd.org/D38817) and I have updated it based on their feedback so I think it can be committed now.
Created attachment 240572 [details] Update man page Updated to fix whitespace problems.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=528d8e55c8d338e78fa4e6c9f182e8975f75199a commit 528d8e55c8d338e78fa4e6c9f182e8975f75199a Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-06 05:37:23 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2023-03-06 05:38:57 +0000 FFS/UFS snapshots: improve documentation. This update provides a more detailed description of FFS/UFS snapshots and adds links to useful man pages. Requested by: Graham Perrin Submitted by: darius-dons.net.au Reviewed by: Ravi Pokala PR: 266358 MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D38817 sbin/mksnap_ffs/mksnap_ffs.8 | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-)
This bug will be closed when the documentation has been MFC'ed to 13-stable.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=129ea078cd16b768a1100b497282fd9359e8dfea commit 129ea078cd16b768a1100b497282fd9359e8dfea Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-08 06:02:07 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2023-03-08 06:03:00 +0000 FFS/UFS snapshots: improve documentation for removal (deletion) and unlinking. Clarification of the size of the snapshot file. Suggested by: Matteo Riondato PR: 266358 MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D38817 sbin/mksnap_ffs/mksnap_ffs.8 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=85dc1a471591990618bc22ce6b25ac407ad4722e commit 85dc1a471591990618bc22ce6b25ac407ad4722e Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-08 06:02:07 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2023-03-20 05:22:06 +0000 FFS/UFS snapshots: improve documentation for removal (deletion) and unlinking. Clarification of the size of the snapshot file. Suggested by: Matteo Riondato PR: 266358 Differential Revision: https://reviews.freebsd.org/D38817 (cherry picked from commit 129ea078cd16b768a1100b497282fd9359e8dfea) sbin/mksnap_ffs/mksnap_ffs.8 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=24ed6ac445497ce2489c7be1723462030eef47d4 commit 24ed6ac445497ce2489c7be1723462030eef47d4 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-06 05:37:23 +0000 Commit: Kirk McKusick <mckusick@FreeBSD.org> CommitDate: 2023-03-20 05:22:06 +0000 FFS/UFS snapshots: improve documentation. This update provides a more detailed description of FFS/UFS snapshots and adds links to useful man pages. Requested by: Graham Perrin Submitted by: darius-dons.net.au Reviewed by: Ravi Pokala PR: 266358 Differential Revision: https://reviews.freebsd.org/D38817 (cherry picked from commit 528d8e55c8d338e78fa4e6c9f182e8975f75199a) sbin/mksnap_ffs/mksnap_ffs.8 | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-)
A commit in branch releng/13.2 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=33e13e4c921be81280c33e9baa8a2c7699776538 commit 33e13e4c921be81280c33e9baa8a2c7699776538 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-06 05:37:23 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2023-03-22 06:32:29 +0000 FFS/UFS snapshots: improve documentation. This update provides a more detailed description of FFS/UFS snapshots and adds links to useful man pages. Requested by: Graham Perrin Submitted by: darius-dons.net.au Reviewed by: Ravi Pokala PR: 266358 Differential Revision: https://reviews.freebsd.org/D38817 Approved by: re (gjb) (cherry picked from commit 528d8e55c8d338e78fa4e6c9f182e8975f75199a) sbin/mksnap_ffs/mksnap_ffs.8 | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-)
A commit in branch releng/13.2 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=8295571e3f6a3de2fd0d3fcdcb9882bf73a47967 commit 8295571e3f6a3de2fd0d3fcdcb9882bf73a47967 Author: Kirk McKusick <mckusick@FreeBSD.org> AuthorDate: 2023-03-08 06:02:07 +0000 Commit: Gordon Bergling <gbe@FreeBSD.org> CommitDate: 2023-03-22 06:34:15 +0000 FFS/UFS snapshots: improve documentation for removal (deletion) and unlinking. Clarification of the size of the snapshot file. Suggested by: Matteo Riondato PR: 266358 Differential Revision: https://reviews.freebsd.org/D38817 Approved by: re (gjb) (cherry picked from commit 129ea078cd16b768a1100b497282fd9359e8dfea) sbin/mksnap_ffs/mksnap_ffs.8 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
The changes have been made and MFC'ed to 13-stable
Thanks!
mksnap_ffs(8) in 13.2-RC4 has a three-paragraph description, and the second example is 'Delete a snapshot:'. mksnap_ffs(8) in CURRENT built a few hours ago has a two-paragraph description, and only one example: ---- root@mowa219-gjp4-8570p-freebsd:~ # man -P more mksnap_ffs MKSNAP_FFS(8) FreeBSD System Manager's Manual MKSNAP_FFS(8) NAME mksnap_ffs – take a file system snapshot SYNOPSIS mksnap_ffs snapshot_name DESCRIPTION The mksnap_ffs utility creates a snapshot named snapshot_name. The group ownership of the file is set to “operator”; the owner of the file remains “root”. The mode of the snapshot is set to be readable by the owner or members of the “operator” group. EXAMPLES Create a snapshot of /usr/home file system and mount the snapshot elsewhere: mksnap_ffs /usr/home/snapshot mdconfig -a -t vnode -o readonly -f /usr/home/snapshot mount -o ro /dev/md0 /mnt/ SEE ALSO chmod(2), chown(8), mdconfig(8), mount(8) HISTORY The mksnap_ffs utility first appeared in FreeBSD 5.1. CAVEATS The disk full situation is not handled gracefully and may lead to a system panic when no free blocks are found. Every filesystem can have only up to 20 active snapshots. When this limit is reached, attempting to create more snapshots fails with ENOSPC, and mksnap_ffs reports that it is “out of space”. FreeBSD 14.0-CURRENT October 3, 2016 FreeBSD 14.0-CURRENT root@mowa219-gjp4-8570p-freebsd:~ # uname -aKU FreeBSD mowa219-gjp4-8570p-freebsd 14.0-CURRENT FreeBSD 14.0-CURRENT #36 main-n261767-508aee968143: Sat Mar 25 23:33:05 GMT 2023 grahamperrin@mowa219-gjp4-8570p-freebsd:/usr/obj/usr/src/amd64.amd64/sys/GENERIC-NODEBUG amd64 1400084 1400084 root@mowa219-gjp4-8570p-freebsd:~ #
(In reply to Graham Perrin from comment #19) You must have an out of date CURRENT. I just did: % cd /usr/src/sbin/mksnap_ffs % rm mksnap_ffs.8 % git restore mksnap_ffs.8 And that mksnap_ffs.8 has what you claim is missing. Please verify that you are up to date. And unless I am wrong, please close this bug report.
(In reply to Kirk McKusick from comment #20) > … Please verify that you are up to date. … My /usr/src has the proper file – I should have checked this before reopening the report, sorry. Things were built then installed on 25th/26th March, and the correct boot environment is active now, so the outdated page puzzles me. I'll close the report here and look elsewhere for an explanation. Apologies for the noise. ---- % grep Delete /usr/src/sbin/mksnap_ffs/mksnap_ffs.8 Delete a snapshot: % ls -hlnrt /usr/src/*.log -rw-r--r-- 1 1002 0 3.6M 25 Mar 22:16 /usr/src/buildworld.log -rw-r--r-- 1 1002 0 5.9M 26 Mar 00:01 /usr/src/buildkernel.log -rw-r--r-- 1 1002 0 308K 26 Mar 03:33 /usr/src/installkernel.log -rw-r--r-- 1 1002 0 4.8M 26 Mar 04:45 /usr/src/installworld.log % git -C /usr/src rev-list --first-parent --count HEAD 261767 % bectl list -c creation BE Active Mountpoint Space Created n260316-9922bccbc9c4-f - - 5.69G 2023-02-10 08:12 n261014-cd406ac94d8b-k - - 1.88G 2023-03-09 10:55 n261465-22bf2a479f68-a - - 768M 2023-03-12 09:20 n261465-22bf2a479f68-b - - 366M 2023-03-15 17:24 n261613-2b4b3789f877-a - - 470M 2023-03-19 05:29 n261613-2b4b3789f877-b - - 781M 2023-03-19 22:28 n261613-2b4b3789f877-c - - 48.7M 2023-03-24 17:17 n261767-508aee968143-a NR / 364G 2023-03-26 03:21 %