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