man/man8/zfs-create.8

   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 http://www.opensolaris.org/os/licensing.
  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 December 1, 2020
  33 .Dt ZFS-CREATE 8
  34 .Os
  35 .
  36 .Sh NAME
  37 .Nm zfs-create
  38 .Nd create ZFS dataset
  39 .Sh SYNOPSIS
  40 .Nm zfs
  41 .Cm create
  42 .Op Fl Pnpuv
  43 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  44 .Ar filesystem
  45 .Nm zfs
  46 .Cm create
  47 .Op Fl ps
  48 .Op Fl b Ar blocksize
  49 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  50 .Fl V Ar size Ar volume
  51 .
  52 .Sh DESCRIPTION
  53 .Bl -tag -width ""
  54 .It Xo
  55 .Nm zfs
  56 .Cm create
  57 .Op Fl Pnpuv
  58 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  59 .Ar filesystem
  60 .Xc
  61 Creates a new ZFS file system.
  62 The file system is automatically mounted according to the
  63 .Sy mountpoint
  64 property inherited from the parent, unless the
  65 .Fl u
  66 option is used.
  67 .Bl -tag -width "-o"
  68 .It Fl o Ar property Ns = Ns Ar value
  69 Sets the specified property as if the command
  70 .Nm zfs Cm set Ar property Ns = Ns Ar value
  71 was invoked at the same time the dataset was created.
  72 Any editable ZFS property can also be set at creation time.
  73 Multiple
  74 .Fl o
  75 options can be specified.
  76 An error results if the same property is specified in multiple
  77 .Fl o
  78 options.
  79 .It Fl p
  80 Creates all the non-existing parent datasets.
  81 Datasets created in this manner are automatically mounted according to the
  82 .Sy mountpoint
  83 property inherited from their parent.
  84 Any property specified on the command line using the
  85 .Fl o
  86 option is ignored.
  87 If the target filesystem already exists, the operation completes successfully.
  88 .It Fl n
  89 Do a dry-run
  90 .Pq Qq No-op
  91 creation.
  92 No datasets will be created.
  93 This is useful in conjunction with the
  94 .Fl v
  95 or
  96 .Fl P
  97 flags to validate properties that are passed via
  98 .Fl o
  99 options and those implied by other options.
 100 The actual dataset creation can still fail due to insufficient privileges or
 101 available capacity.
 102 .It Fl P
 103 Print machine-parsable verbose information about the created dataset.
 104 Each line of output contains a key and one or two values, all separated by tabs.
 105 The
 106 .Sy create_ancestors
 107 and
 108 .Sy create
 109 keys have
 110 .Em filesystem
 111 as their only value.
 112 The
 113 .Sy create_ancestors
 114 key only appears if the
 115 .Fl p
 116 option is used.
 117 The
 118 .Sy property
 119 key has two values, a property name that property's value.
 120 The
 121 .Sy property
 122 key may appear zero or more times, once for each property that will be set local
 123 to
 124 .Em filesystem
 125 due to the use of the
 126 .Fl o
 127 option.
 128 .It Fl u
 129 Do not mount the newly created file system.
 130 .It Fl v
 131 Print verbose information about the created dataset.
 132 .El
 133 .It Xo
 134 .Nm zfs
 135 .Cm create
 136 .Op Fl ps
 137 .Op Fl b Ar blocksize
 138 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
 139 .Fl V Ar size Ar volume
 140 .Xc
 141 Creates a volume of the given size.
 142 The volume is exported as a block device in
 143 .Pa /dev/zvol/path ,
 144 where
 145 .Em path
 146 is the name of the volume in the ZFS namespace.
 147 The size represents the logical size as exported by the device.
 148 By default, a reservation of equal size is created.
 149 .Pp
 150 .Ar size
 151 is automatically rounded up to the nearest multiple of the
 152 .Sy blocksize .
 153 .Bl -tag -width "-b"
 154 .It Fl b Ar blocksize
 155 Equivalent to
 156 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
 157 If this option is specified in conjunction with
 158 .Fl o Sy volblocksize ,
 159 the resulting behavior is undefined.
 160 .It Fl o Ar property Ns = Ns Ar value
 161 Sets the specified property as if the
 162 .Nm zfs Cm set Ar property Ns = Ns Ar value
 163 command was invoked at the same time the dataset was created.
 164 Any editable ZFS property can also be set at creation time.
 165 Multiple
 166 .Fl o
 167 options can be specified.
 168 An error results if the same property is specified in multiple
 169 .Fl o
 170 options.
 171 .It Fl p
 172 Creates all the non-existing parent datasets.
 173 Datasets created in this manner are automatically mounted according to the
 174 .Sy mountpoint
 175 property inherited from their parent.
 176 Any property specified on the command line using the
 177 .Fl o
 178 option is ignored.
 179 If the target filesystem already exists, the operation completes successfully.
 180 .It Fl s
 181 Creates a sparse volume with no reservation.
 182 See
 183 .Sy volsize
 184 in the
 185 .Em Native Properties
 186 section of
 187 .Xr zfsprops 8
 188 for more information about sparse volumes.
 189 .It Fl n
 190 Do a dry-run
 191 .Pq Qq No-op
 192 creation.
 193 No datasets will be created.
 194 This is useful in conjunction with the
 195 .Fl v
 196 or
 197 .Fl P
 198 flags to validate properties that are passed via
 199 .Fl o
 200 options and those implied by other options.
 201 The actual dataset creation can still fail due to insufficient privileges or
 202 available capacity.
 203 .It Fl P
 204 Print machine-parsable verbose information about the created dataset.
 205 Each line of output contains a key and one or two values, all separated by tabs.
 206 The
 207 .Sy create_ancestors
 208 and
 209 .Sy create
 210 keys have
 211 .Em volume
 212 as their only value.
 213 The
 214 .Sy create_ancestors
 215 key only appears if the
 216 .Fl p
 217 option is used.
 218 The
 219 .Sy property
 220 key has two values, a property name that property's value.
 221 The
 222 .Sy property
 223 key may appear zero or more times, once for each property that will be set local
 224 to
 225 .Em volume
 226 due to the use of the
 227 .Fl b
 228 or
 229 .Fl o
 230 options, as well as
 231 .Sy refreservation
 232 if the volume is not sparse.
 233 .It Fl v
 234 Print verbose information about the created dataset.
 235 .El
 236 .El
 237 .Ss ZFS Volumes as Swap
 238 ZFS volumes may be used as swap devices.
 239 After creating the volume with the
 240 .Nm zfs Cm create Fl V
 241 enable the swap area using the
 242 .Xr swapon 8
 243 command.
 244 Swapping to files on ZFS filesystems is not supported.
 245 .
 246 .Sh SEE ALSO
 247 .Xr zfs-destroy 8 ,
 248 .Xr zfs-list 8 ,
 249 .Xr zpool-create 8