man/man8/zfs-destroy.8

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or https://opensource.org/licenses/CDDL-1.0.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
  22 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
  23 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
  24 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
  25 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  26 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  27 .\" Copyright (c) 2014 Integros [integros.com]
  28 .\" Copyright 2019 Richard Laager. All rights reserved.
  29 .\" Copyright 2018 Nexenta Systems, Inc.
  30 .\" Copyright 2019 Joyent, Inc.
  31 .\"
  32 .Dd March 16, 2022
  33 .Dt ZFS-DESTROY 8
  34 .Os
  35 .
  36 .Sh NAME
  37 .Nm zfs-destroy
  38 .Nd destroy ZFS dataset, snapshots, or bookmark
  39 .Sh SYNOPSIS
  40 .Nm zfs
  41 .Cm destroy
  42 .Op Fl Rfnprv
  43 .Ar filesystem Ns | Ns Ar volume
  44 .Nm zfs
  45 .Cm destroy
  46 .Op Fl Rdnprv
  47 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
  48 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns …
  49 .Nm zfs
  50 .Cm destroy
  51 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
  52 .
  53 .Sh DESCRIPTION
  54 .Bl -tag -width ""
  55 .It Xo
  56 .Nm zfs
  57 .Cm destroy
  58 .Op Fl Rfnprv
  59 .Ar filesystem Ns | Ns Ar volume
  60 .Xc
  61 Destroys the given dataset.
  62 By default, the command unshares any file systems that are currently shared,
  63 unmounts any file systems that are currently mounted, and refuses to destroy a
  64 dataset that has active dependents
  65 .Pq children or clones .
  66 .Bl -tag -width "-R"
  67 .It Fl R
  68 Recursively destroy all dependents, including cloned file systems outside the
  69 target hierarchy.
  70 .It Fl f
  71 Forcibly unmount file systems.
  72 This option has no effect on non-file systems or unmounted file systems.
  73 .It Fl n
  74 Do a dry-run
  75 .Pq Qq No-op
  76 deletion.
  77 No data will be deleted.
  78 This is useful in conjunction with the
  79 .Fl v
  80 or
  81 .Fl p
  82 flags to determine what data would be deleted.
  83 .It Fl p
  84 Print machine-parsable verbose information about the deleted data.
  85 .It Fl r
  86 Recursively destroy all children.
  87 .It Fl v
  88 Print verbose information about the deleted data.
  89 .El
  90 .Pp
  91 Extreme care should be taken when applying either the
  92 .Fl r
  93 or the
  94 .Fl R
  95 options, as they can destroy large portions of a pool and cause unexpected
  96 behavior for mounted file systems in use.
  97 .It Xo
  98 .Nm zfs
  99 .Cm destroy
 100 .Op Fl Rdnprv
 101 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
 102 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns …
 103 .Xc
 104 The given snapshots are destroyed immediately if and only if the
 105 .Nm zfs Cm destroy
 106 command without the
 107 .Fl d
 108 option would have destroyed it.
 109 Such immediate destruction would occur, for example, if the snapshot had no
 110 clones and the user-initiated reference count were zero.
 111 .Pp
 112 If a snapshot does not qualify for immediate destruction, it is marked for
 113 deferred deletion.
 114 In this state, it exists as a usable, visible snapshot until both of the
 115 preconditions listed above are met, at which point it is destroyed.
 116 .Pp
 117 An inclusive range of snapshots may be specified by separating the first and
 118 last snapshots with a percent sign.
 119 The first and/or last snapshots may be left blank, in which case the
 120 filesystem's oldest or newest snapshot will be implied.
 121 .Pp
 122 Multiple snapshots
 123 .Pq or ranges of snapshots
 124 of the same filesystem or volume may be specified in a comma-separated list of
 125 snapshots.
 126 Only the snapshot's short name
 127 .Po the part after the
 128 .Sy @
 129 .Pc
 130 should be specified when using a range or comma-separated list to identify
 131 multiple snapshots.
 132 .Bl -tag -width "-R"
 133 .It Fl R
 134 Recursively destroy all clones of these snapshots, including the clones,
 135 snapshots, and children.
 136 If this flag is specified, the
 137 .Fl d
 138 flag will have no effect.
 139 .It Fl d
 140 Destroy immediately.
 141 If a snapshot cannot be destroyed now, mark it for deferred destruction.
 142 .It Fl n
 143 Do a dry-run
 144 .Pq Qq No-op
 145 deletion.
 146 No data will be deleted.
 147 This is useful in conjunction with the
 148 .Fl p
 149 or
 150 .Fl v
 151 flags to determine what data would be deleted.
 152 .It Fl p
 153 Print machine-parsable verbose information about the deleted data.
 154 .It Fl r
 155 Destroy
 156 .Pq or mark for deferred deletion
 157 all snapshots with this name in descendent file systems.
 158 .It Fl v
 159 Print verbose information about the deleted data.
 160 .Pp
 161 Extreme care should be taken when applying either the
 162 .Fl r
 163 or the
 164 .Fl R
 165 options, as they can destroy large portions of a pool and cause unexpected
 166 behavior for mounted file systems in use.
 167 .El
 168 .It Xo
 169 .Nm zfs
 170 .Cm destroy
 171 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
 172 .Xc
 173 The given bookmark is destroyed.
 174 .El
 175 .
 176 .Sh EXAMPLES
 177 .\" These are, respectively, examples 3, 10, 15 from zfs.8
 178 .\" Make sure to update them bidirectionally
 179 .Ss Example 1 : No Creating and Destroying Multiple Snapshots
 180 The following command creates snapshots named
 181 .Ar yesterday No of Ar pool/home
 182 and all of its descendent file systems.
 183 Each snapshot is mounted on demand in the
 184 .Pa .zfs/snapshot
 185 directory at the root of its file system.
 186 The second command destroys the newly created snapshots.
 187 .Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday
 188 .Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday
 189 .
 190 .Ss Example 2 : No Promoting a ZFS Clone
 191 The following commands illustrate how to test out changes to a file system, and
 192 then replace the original file system with the changed one, using clones, clone
 193 promotion, and renaming:
 194 .Bd -literal -compact -offset Ds
 195 .No # Nm zfs Cm create Ar pool/project/production
 196   populate /pool/project/production with data
 197 .No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today
 198 .No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta
 199   make changes to /pool/project/beta and test them
 200 .No # Nm zfs Cm promote Ar pool/project/beta
 201 .No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy
 202 .No # Nm zfs Cm rename Ar pool/project/beta pool/project/production
 203   once the legacy version is no longer needed, it can be destroyed
 204 .No # Nm zfs Cm destroy Ar pool/project/legacy
 205 .Ed
 206 .
 207 .Ss Example 3 : No Performing a Rolling Snapshot
 208 The following example shows how to maintain a history of snapshots with a
 209 consistent naming scheme.
 210 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
 211 renames the remaining snapshots, and then creates a new snapshot, as follows:
 212 .Bd -literal -compact -offset Ds
 213 .No # Nm zfs Cm destroy Fl r Ar pool/users@7daysago
 214 .No # Nm zfs Cm rename Fl r Ar pool/users@6daysago No @ Ns Ar 7daysago
 215 .No # Nm zfs Cm rename Fl r Ar pool/users@5daysago No @ Ns Ar 6daysago
 216 .No # Nm zfs Cm rename Fl r Ar pool/users@4daysago No @ Ns Ar 5daysago
 217 .No # Nm zfs Cm rename Fl r Ar pool/users@3daysago No @ Ns Ar 4daysago
 218 .No # Nm zfs Cm rename Fl r Ar pool/users@2daysago No @ Ns Ar 3daysago
 219 .No # Nm zfs Cm rename Fl r Ar pool/users@yesterday No @ Ns Ar 2daysago
 220 .No # Nm zfs Cm rename Fl r Ar pool/users@today No @ Ns Ar yesterday
 221 .No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today
 222 .Ed
 223 .
 224 .Sh SEE ALSO
 225 .Xr zfs-create 8 ,
 226 .Xr zfs-hold 8