zfs-create.8 (7943B)
- .\"
- .\" 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 for Swap
- Swapping to a ZFS volume is prone to deadlock and not recommended.
- See OpenZFS FAQ.
- .Pp
- Swapping to a file on a ZFS filesystem 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