zfs-create.8

.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or https://opensource.org/licenses/CDDL-1.0.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
.\" Copyright (c) 2014 Integros [integros.com]
.\" Copyright 2019 Richard Laager. All rights reserved.
.\" Copyright 2018 Nexenta Systems, Inc.
.\" Copyright 2019 Joyent, Inc.
.\"
.Dd March 16, 2022
.Dt ZFS-CREATE 8
.Os
.
.Sh NAME
.Nm zfs-create
.Nd create ZFS dataset
.Sh SYNOPSIS
.Nm zfs
.Cm create
.Op Fl Pnpuv
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
.Ar filesystem
.Nm zfs
.Cm create
.Op Fl ps
.Op Fl b Ar blocksize
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
.Fl V Ar size Ar volume
.
.Sh DESCRIPTION
.Bl -tag -width ""
.It Xo
.Nm zfs
.Cm create
.Op Fl Pnpuv
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
.Ar filesystem
.Xc
Creates a new ZFS file system.
The file system is automatically mounted according to the
.Sy mountpoint
property inherited from the parent, unless the
.Fl u
option is used.
.Bl -tag -width "-o"
.It Fl o Ar property Ns = Ns Ar value
Sets the specified property as if the command
.Nm zfs Cm set Ar property Ns = Ns Ar value
was invoked at the same time the dataset was created.
Any editable ZFS property can also be set at creation time.
Multiple
.Fl o
options can be specified.
An error results if the same property is specified in multiple
.Fl o
options.
.It Fl p
Creates all the non-existing parent datasets.
Datasets created in this manner are automatically mounted according to the
.Sy mountpoint
property inherited from their parent.
Any property specified on the command line using the
.Fl o
option is ignored.
If the target filesystem already exists, the operation completes successfully.
.It Fl n
Do a dry-run
.Pq Qq No-op
creation.
No datasets will be created.
This is useful in conjunction with the
.Fl v
or
.Fl P
flags to validate properties that are passed via
.Fl o
options and those implied by other options.
The actual dataset creation can still fail due to insufficient privileges or
available capacity.
.It Fl P
Print machine-parsable verbose information about the created dataset.
Each line of output contains a key and one or two values, all separated by tabs.
The
.Sy create_ancestors
and
.Sy create
keys have
.Em filesystem
as their only value.
The
.Sy create_ancestors
key only appears if the
.Fl p
option is used.
The
.Sy property
key has two values, a property name that property's value.
The
.Sy property
key may appear zero or more times, once for each property that will be set local
to
.Em filesystem
due to the use of the
.Fl o
option.
.It Fl u
Do not mount the newly created file system.
.It Fl v
Print verbose information about the created dataset.
.El
.It Xo
.Nm zfs
.Cm create
.Op Fl ps
.Op Fl b Ar blocksize
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
.Fl V Ar size Ar volume
.Xc
Creates a volume of the given size.
The volume is exported as a block device in
.Pa /dev/zvol/path ,
where
.Em path
is the name of the volume in the ZFS namespace.
The size represents the logical size as exported by the device.
By default, a reservation of equal size is created.
.Pp
.Ar size
is automatically rounded up to the nearest multiple of the
.Sy blocksize .
.Bl -tag -width "-b"
.It Fl b Ar blocksize
Equivalent to
.Fl o Sy volblocksize Ns = Ns Ar blocksize .
If this option is specified in conjunction with
.Fl o Sy volblocksize ,
the resulting behavior is undefined.
.It Fl o Ar property Ns = Ns Ar value
Sets the specified property as if the
.Nm zfs Cm set Ar property Ns = Ns Ar value
command was invoked at the same time the dataset was created.
Any editable ZFS property can also be set at creation time.
Multiple
.Fl o
options can be specified.
An error results if the same property is specified in multiple
.Fl o
options.
.It Fl p
Creates all the non-existing parent datasets.
Datasets created in this manner are automatically mounted according to the
.Sy mountpoint
property inherited from their parent.
Any property specified on the command line using the
.Fl o
option is ignored.
If the target filesystem already exists, the operation completes successfully.
.It Fl s
Creates a sparse volume with no reservation.
See
.Sy volsize
in the
.Em Native Properties
section of
.Xr zfsprops 7
for more information about sparse volumes.
.It Fl n
Do a dry-run
.Pq Qq No-op
creation.
No datasets will be created.
This is useful in conjunction with the
.Fl v
or
.Fl P
flags to validate properties that are passed via
.Fl o
options and those implied by other options.
The actual dataset creation can still fail due to insufficient privileges or
available capacity.
.It Fl P
Print machine-parsable verbose information about the created dataset.
Each line of output contains a key and one or two values, all separated by tabs.
The
.Sy create_ancestors
and
.Sy create
keys have
.Em volume
as their only value.
The
.Sy create_ancestors
key only appears if the
.Fl p
option is used.
The
.Sy property
key has two values, a property name that property's value.
The
.Sy property
key may appear zero or more times, once for each property that will be set local
to
.Em volume
due to the use of the
.Fl b
or
.Fl o
options, as well as
.Sy refreservation
if the volume is not sparse.
.It Fl v
Print verbose information about the created dataset.
.El
.El
.Ss ZFS Volumes as Swap
ZFS volumes may be used as swap devices.
After creating the volume with the
.Nm zfs Cm create Fl V
enable the swap area using the
.Xr swapon 8
command.
Swapping to files on ZFS filesystems is not supported.
.
.Sh EXAMPLES
.\" These are, respectively, examples 1, 10 from zfs.8
.\" Make sure to update them bidirectionally
.Ss Example 1 : No Creating a ZFS File System Hierarchy
The following commands create a file system named
.Ar pool/home
and a file system named
.Ar pool/home/bob .
The mount point
.Pa /export/home
is set for the parent file system, and is automatically inherited by the child
file system.
.Dl # Nm zfs Cm create Ar pool/home
.Dl # Nm zfs Cm set Sy mountpoint Ns = Ns Ar /export/home pool/home
.Dl # Nm zfs Cm create Ar pool/home/bob
.
.Ss Example 2 : No Promoting a ZFS Clone
The following commands illustrate how to test out changes to a file system, and
then replace the original file system with the changed one, using clones, clone
promotion, and renaming:
.Bd -literal -compact -offset Ds
.No # Nm zfs Cm create Ar pool/project/production
  populate /pool/project/production with data
.No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today
.No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta
  make changes to /pool/project/beta and test them
.No # Nm zfs Cm promote Ar pool/project/beta
.No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy
.No # Nm zfs Cm rename Ar pool/project/beta pool/project/production
  once the legacy version is no longer needed, it can be destroyed
.No # Nm zfs Cm destroy Ar pool/project/legacy
.Ed
.
.Sh SEE ALSO
.Xr zfs-destroy 8 ,
.Xr zfs-list 8 ,
.Xr zpool-create 8