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-SNAPSHOT 8 35.Os 36. 37.Sh NAME 38.Nm zfs-snapshot 39.Nd create snapshots of ZFS datasets 40.Sh SYNOPSIS 41.Nm zfs 42.Cm snapshot 43.Op Fl r 44.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … 45.Ar dataset Ns @ Ns Ar snapname Ns … 46. 47.Sh DESCRIPTION 48Creates a snapshot of a dataset or multiple snapshots of different 49datasets. 50.Pp 51Snapshots are created atomically. 52That is, a snapshot is a consistent image of a dataset at a specific 53point in time; it includes all modifications to the dataset made by 54system calls that have successfully completed before that point in time. 55Recursive snapshots created through the 56.Fl r 57option are all created at the same time. 58.Pp 59.Nm zfs Cm snap 60can be used as an alias for 61.Nm zfs Cm snapshot . 62.Pp 63See the 64.Sx Snapshots 65section of 66.Xr zfsconcepts 7 67for details. 68.Bl -tag -width "-o" 69.It Fl o Ar property Ns = Ns Ar value 70Set the specified property; see 71.Nm zfs Cm create 72for details. 73.It Fl r 74Recursively create snapshots of all descendent datasets 75.El 76. 77.Sh EXAMPLES 78.\" These are, respectively, examples 2, 3, 10, 15 from zfs.8 79.\" Make sure to update them bidirectionally 80.Ss Example 1 : No Creating a ZFS Snapshot 81The following command creates a snapshot named 82.Ar yesterday . 83This snapshot is mounted on demand in the 84.Pa .zfs/snapshot 85directory at the root of the 86.Ar pool/home/bob 87file system. 88.Dl # Nm zfs Cm snapshot Ar pool/home/bob Ns @ Ns Ar yesterday 89. 90.Ss Example 2 : No Creating and Destroying Multiple Snapshots 91The following command creates snapshots named 92.Ar yesterday No of Ar pool/home 93and all of its descendent file systems. 94Each snapshot is mounted on demand in the 95.Pa .zfs/snapshot 96directory at the root of its file system. 97The second command destroys the newly created snapshots. 98.Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday 99.Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday 100. 101.Ss Example 3 : No Promoting a ZFS Clone 102The following commands illustrate how to test out changes to a file system, and 103then replace the original file system with the changed one, using clones, clone 104promotion, and renaming: 105.Bd -literal -compact -offset Ds 106.No # Nm zfs Cm create Ar pool/project/production 107 populate /pool/project/production with data 108.No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today 109.No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta 110 make changes to /pool/project/beta and test them 111.No # Nm zfs Cm promote Ar pool/project/beta 112.No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy 113.No # Nm zfs Cm rename Ar pool/project/beta pool/project/production 114 once the legacy version is no longer needed, it can be destroyed 115.No # Nm zfs Cm destroy Ar pool/project/legacy 116.Ed 117. 118.Ss Example 4 : No Performing a Rolling Snapshot 119The following example shows how to maintain a history of snapshots with a 120consistent naming scheme. 121To keep a week's worth of snapshots, the user destroys the oldest snapshot, 122renames the remaining snapshots, and then creates a new snapshot, as follows: 123.Bd -literal -compact -offset Ds 124.No # Nm zfs Cm destroy Fl r Ar pool/users@7daysago 125.No # Nm zfs Cm rename Fl r Ar pool/users@6daysago No @ Ns Ar 7daysago 126.No # Nm zfs Cm rename Fl r Ar pool/users@5daysago No @ Ns Ar 6daysago 127.No # Nm zfs Cm rename Fl r Ar pool/users@4daysago No @ Ns Ar 5daysago 128.No # Nm zfs Cm rename Fl r Ar pool/users@3daysago No @ Ns Ar 4daysago 129.No # Nm zfs Cm rename Fl r Ar pool/users@2daysago No @ Ns Ar 3daysago 130.No # Nm zfs Cm rename Fl r Ar pool/users@yesterday No @ Ns Ar 2daysago 131.No # Nm zfs Cm rename Fl r Ar pool/users@today No @ Ns Ar yesterday 132.No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today 133.Ed 134. 135.Sh SEE ALSO 136.Xr zfs-bookmark 8 , 137.Xr zfs-clone 8 , 138.Xr zfs-destroy 8 , 139.Xr zfs-diff 8 , 140.Xr zfs-hold 8 , 141.Xr zfs-rename 8 , 142.Xr zfs-rollback 8 , 143.Xr zfs-send 8 144