c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2025-05-10 10:48:27 +03:00
Code Issues Packages Projects Releases Wiki Activity

Clarify documentation of zfs destroy on snapshots (#17021)

Browse Source 
The current documentation of `zfs destroy` in application to snapshots
is particularly difficult to understand. The following changes are made:

- Remove circular reference to `zfs destroy` in the documentation of
  that command.
- Remove use of "for example", which implies there are more,
  undocumented reasons that ZFS may fail to destroy a snapshot
  immediately.
- Mention properties `defer_destroy` and `userrefs`.
- Add `zfsprops(8)` to "SEE ALSO" list.
- Clarify meaning of `-d` option.



Requires-builders: none

Signed-off-by: mnrx <83848843+mnrx@users.noreply.github.com>
Co-authored-by: Alexander Motin <mav@FreeBSD.org>
Reviewed-by: Alexander Motin <mav@FreeBSD.org>
Reviewed-by: George Amanakis <gamanakis@gmail.com>
Reviewed-by: Tony Hutter <hutter2@llnl.gov>
This commit is contained in:
mnrx 2025-02-05 22:47:03 +00:00 committed by Ameer Hamza
parent 3266d4d655
commit d1b0c4ec5a
1 changed files with 21 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
man/man8/zfs-destroy.8
View File

@ -101,18 +101,25 @@ behavior for mounted file systems in use.
.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns … .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns …
.Xc .Xc
The given snapshots are destroyed immediately if and only if the Attempts to destroy the given snapshot(s).
This will fail if any clones of the snapshot exist or if the snapshot is held.
In this case, by default,
.Nm zfs Cm destroy .Nm zfs Cm destroy
command without the will have no effect and exit in error.
If the
.Fl d .Fl d
option would have destroyed it. option is applied, the command will instead mark the given snapshot for
Such immediate destruction would occur, for example, if the snapshot had no automatic destruction as soon as it becomes eligible.
clones and the user-initiated reference count were zero. While marked for destruction, a snapshot remains visible, and the user may
create new clones from it and place new holds on it.
.Pp .Pp
If a snapshot does not qualify for immediate destruction, it is marked for The read-only snapshot properties
deferred deletion. .Sy defer_destroy
In this state, it exists as a usable, visible snapshot until both of the and
preconditions listed above are met, at which point it is destroyed. .Sy userrefs
are used by
.Nm zfs Cm destroy
to determine eligibility and marked status.
.Pp .Pp
An inclusive range of snapshots may be specified by separating the first and An inclusive range of snapshots may be specified by separating the first and
last snapshots with a percent sign. last snapshots with a percent sign.
@ -137,8 +144,9 @@ If this flag is specified, the
.Fl d .Fl d
flag will have no effect. flag will have no effect.
.It Fl d .It Fl d
Destroy immediately. Rather than returning error if the given snapshot is ineligible for immediate
If a snapshot cannot be destroyed now, mark it for deferred destruction. destruction, mark it for deferred, automatic destruction once it becomes
eligible.
.It Fl n .It Fl n
Do a dry-run Do a dry-run
.Pq Qq No-op .Pq Qq No-op
@ -223,4 +231,5 @@ renames the remaining snapshots, and then creates a new snapshot, as follows:
. .
.Sh SEE ALSO .Sh SEE ALSO
.Xr zfs-create 8 , .Xr zfs-create 8 ,
.Xr zfs-hold 8 .Xr zfs-hold 8 ,
.Xr zfsprops 8