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 61Destroys the given dataset. 62By default, the command unshares any file systems that are currently shared, 63unmounts any file systems that are currently mounted, and refuses to destroy a 64dataset that has active dependents 65.Pq children or clones . 66.Bl -tag -width "-R" 67.It Fl R 68Recursively destroy all dependents, including cloned file systems outside the 69target hierarchy. 70.It Fl f 71Forcibly unmount file systems. 72This option has no effect on non-file systems or unmounted file systems. 73.It Fl n 74Do a dry-run 75.Pq Qq No-op 76deletion. 77No data will be deleted. 78This is useful in conjunction with the 79.Fl v 80or 81.Fl p 82flags to determine what data would be deleted. 83.It Fl p 84Print machine-parsable verbose information about the deleted data. 85.It Fl r 86Recursively destroy all children. 87.It Fl v 88Print verbose information about the deleted data. 89.El 90.Pp 91Extreme care should be taken when applying either the 92.Fl r 93or the 94.Fl R 95options, as they can destroy large portions of a pool and cause unexpected 96behavior 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 104Attempts to destroy the given snapshot(s). 105This will fail if any clones of the snapshot exist or if the snapshot is held. 106In this case, by default, 107.Nm zfs Cm destroy 108will have no effect and exit in error. 109If the 110.Fl d 111option is applied, the command will instead mark the given snapshot for 112automatic destruction as soon as it becomes eligible. 113While marked for destruction, a snapshot remains visible, and the user may 114create new clones from it and place new holds on it. 115.Pp 116The read-only snapshot properties 117.Sy defer_destroy 118and 119.Sy userrefs 120are used by 121.Nm zfs Cm destroy 122to determine eligibility and marked status. 123.Pp 124An inclusive range of snapshots may be specified by separating the first and 125last snapshots with a percent sign. 126The first and/or last snapshots may be left blank, in which case the 127filesystem's oldest or newest snapshot will be implied. 128.Pp 129Multiple snapshots 130.Pq or ranges of snapshots 131of the same filesystem or volume may be specified in a comma-separated list of 132snapshots. 133Only the snapshot's short name 134.Po the part after the 135.Sy @ 136.Pc 137should be specified when using a range or comma-separated list to identify 138multiple snapshots. 139.Bl -tag -width "-R" 140.It Fl R 141Recursively destroy all clones of these snapshots, including the clones, 142snapshots, and children. 143If this flag is specified, the 144.Fl d 145flag will have no effect. 146.It Fl d 147Rather than returning error if the given snapshot is ineligible for immediate 148destruction, mark it for deferred, automatic destruction once it becomes 149eligible. 150.It Fl n 151Do a dry-run 152.Pq Qq No-op 153deletion. 154No data will be deleted. 155This is useful in conjunction with the 156.Fl p 157or 158.Fl v 159flags to determine what data would be deleted. 160.It Fl p 161Print machine-parsable verbose information about the deleted data. 162.It Fl r 163Destroy 164.Pq or mark for deferred deletion 165all snapshots with this name in descendent file systems. 166.It Fl v 167Print verbose information about the deleted data. 168.El 169.Pp 170Extreme care should be taken when applying either the 171.Fl r 172or the 173.Fl R 174options, as they can destroy large portions of a pool and cause unexpected 175behavior for mounted file systems in use. 176.It Xo 177.Nm zfs 178.Cm destroy 179.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark 180.Xc 181The given bookmark is destroyed. 182.El 183. 184.Sh EXAMPLES 185.\" These are, respectively, examples 3, 10, 15 from zfs.8 186.\" Make sure to update them bidirectionally 187.Ss Example 1 : No Creating and Destroying Multiple Snapshots 188The following command creates snapshots named 189.Ar yesterday No of Ar pool/home 190and all of its descendent file systems. 191Each snapshot is mounted on demand in the 192.Pa .zfs/snapshot 193directory at the root of its file system. 194The second command destroys the newly created snapshots. 195.Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday 196.Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday 197. 198.Ss Example 2 : No Promoting a ZFS Clone 199The following commands illustrate how to test out changes to a file system, and 200then replace the original file system with the changed one, using clones, clone 201promotion, and renaming: 202.Bd -literal -compact -offset Ds 203.No # Nm zfs Cm create Ar pool/project/production 204 populate /pool/project/production with data 205.No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today 206.No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta 207 make changes to /pool/project/beta and test them 208.No # Nm zfs Cm promote Ar pool/project/beta 209.No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy 210.No # Nm zfs Cm rename Ar pool/project/beta pool/project/production 211 once the legacy version is no longer needed, it can be destroyed 212.No # Nm zfs Cm destroy Ar pool/project/legacy 213.Ed 214. 215.Ss Example 3 : No Performing a Rolling Snapshot 216The following example shows how to maintain a history of snapshots with a 217consistent naming scheme. 218To keep a week's worth of snapshots, the user destroys the oldest snapshot, 219renames the remaining snapshots, and then creates a new snapshot, as follows: 220.Bd -literal -compact -offset Ds 221.No # Nm zfs Cm destroy Fl r Ar pool/users@7daysago 222.No # Nm zfs Cm rename Fl r Ar pool/users@6daysago No @ Ns Ar 7daysago 223.No # Nm zfs Cm rename Fl r Ar pool/users@5daysago No @ Ns Ar 6daysago 224.No # Nm zfs Cm rename Fl r Ar pool/users@4daysago No @ Ns Ar 5daysago 225.No # Nm zfs Cm rename Fl r Ar pool/users@3daysago No @ Ns Ar 4daysago 226.No # Nm zfs Cm rename Fl r Ar pool/users@2daysago No @ Ns Ar 3daysago 227.No # Nm zfs Cm rename Fl r Ar pool/users@yesterday No @ Ns Ar 2daysago 228.No # Nm zfs Cm rename Fl r Ar pool/users@today No @ Ns Ar yesterday 229.No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today 230.Ed 231. 232.Sh SEE ALSO 233.Xr zfs-create 8 , 234.Xr zfs-hold 8 , 235.Xr zfsprops 8 236