sys/contrib/openzfs/man/man8/zpool-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) 2007, Sun Microsystems, Inc. All Rights Reserved.
  22 .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
  23 .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
  24 .\" Copyright (c) 2017 Datto Inc.
  25 .\" Copyright (c) 2018 George Melikov. All Rights Reserved.
  26 .\" Copyright 2017 Nexenta Systems, Inc.
  27 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
  28 .\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
  29 .\"
  30 .Dd March 16, 2022
  31 .Dt ZPOOL-CREATE 8
  32 .Os
  33 .
  34 .Sh NAME
  35 .Nm zpool-create
  36 .Nd create ZFS storage pool
  37 .Sh SYNOPSIS
  38 .Nm zpool
  39 .Cm create
  40 .Op Fl dfn
  41 .Op Fl m Ar mountpoint
  42 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  43 .Oo Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value Oc
  44 .Op Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
  45 .Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns …
  46 .Op Fl R Ar root
  47 .Op Fl t Ar tname
  48 .Ar pool
  49 .Ar vdev Ns …
  50 .
  51 .Sh DESCRIPTION
  52 Creates a new storage pool containing the virtual devices specified on the
  53 command line.
  54 The pool name must begin with a letter, and can only contain
  55 alphanumeric characters as well as the underscore
  56 .Pq Qq Sy _ ,
  57 dash
  58 .Pq Qq Sy \&- ,
  59 colon
  60 .Pq Qq Sy \&: ,
  61 space
  62 .Pq Qq Sy \&\  ,
  63 and period
  64 .Pq Qq Sy \&. .
  65 The pool names
  66 .Sy mirror ,
  67 .Sy raidz ,
  68 .Sy draid ,
  69 .Sy spare
  70 and
  71 .Sy log
  72 are reserved, as are names beginning with
  73 .Sy mirror ,
  74 .Sy raidz ,
  75 .Sy draid ,
  76 and
  77 .Sy spare .
  78 The
  79 .Ar vdev
  80 specification is described in the
  81 .Sx Virtual Devices
  82 section of
  83 .Xr zpoolconcepts 7 .
  84 .Pp
  85 The command attempts to verify that each device specified is accessible and not
  86 currently in use by another subsystem.
  87 However this check is not robust enough
  88 to detect simultaneous attempts to use a new device in different pools, even if
  89 .Sy multihost Ns = Sy enabled .
  90 The administrator must ensure, that simultaneous invocations of any combination of
  91 .Nm zpool Cm replace ,
  92 .Nm zpool Cm create ,
  93 .Nm zpool Cm add ,
  94 or
  95 .Nm zpool Cm labelclear ,
  96 do not refer to the same device.
  97 Using the same device in two pools will result in pool corruption.
  98 .Pp
  99 There are some uses, such as being currently mounted, or specified as the
 100 dedicated dump device, that prevents a device from ever being used by ZFS.
 101 Other uses, such as having a preexisting UFS file system, can be overridden with
 102 .Fl f .
 103 .Pp
 104 The command also checks that the replication strategy for the pool is
 105 consistent.
 106 An attempt to combine redundant and non-redundant storage in a single pool,
 107 or to mix disks and files, results in an error unless
 108 .Fl f
 109 is specified.
 110 The use of differently-sized devices within a single raidz or mirror group is
 111 also flagged as an error unless
 112 .Fl f
 113 is specified.
 114 .Pp
 115 Unless the
 116 .Fl R
 117 option is specified, the default mount point is
 118 .Pa / Ns Ar pool .
 119 The mount point must not exist or must be empty, or else the root dataset
 120 will not be able to be be mounted.
 121 This can be overridden with the
 122 .Fl m
 123 option.
 124 .Pp
 125 By default all supported features are enabled on the new pool.
 126 The
 127 .Fl d
 128 option and the
 129 .Fl o Ar compatibility
 130 property
 131 .Pq e.g Fl o Sy compatibility Ns = Ns Ar 2020
 132 can be used to restrict the features that are enabled, so that the
 133 pool can be imported on other releases of ZFS.
 134 .Bl -tag -width "-t tname"
 135 .It Fl d
 136 Do not enable any features on the new pool.
 137 Individual features can be enabled by setting their corresponding properties to
 138 .Sy enabled
 139 with
 140 .Fl o .
 141 See
 142 .Xr zpool-features 7
 143 for details about feature properties.
 144 .It Fl f
 145 Forces use of
 146 .Ar vdev Ns s ,
 147 even if they appear in use or specify a conflicting replication level.
 148 Not all devices can be overridden in this manner.
 149 .It Fl m Ar mountpoint
 150 Sets the mount point for the root dataset.
 151 The default mount point is
 152 .Pa /pool
 153 or
 154 .Pa altroot/pool
 155 if
 156 .Sy altroot
 157 is specified.
 158 The mount point must be an absolute path,
 159 .Sy legacy ,
 160 or
 161 .Sy none .
 162 For more information on dataset mount points, see
 163 .Xr zfsprops 7 .
 164 .It Fl n
 165 Displays the configuration that would be used without actually creating the
 166 pool.
 167 The actual pool creation can still fail due to insufficient privileges or
 168 device sharing.
 169 .It Fl o Ar property Ns = Ns Ar value
 170 Sets the given pool properties.
 171 See
 172 .Xr zpoolprops 7
 173 for a list of valid properties that can be set.
 174 .It Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
 175 Specifies compatibility feature sets.
 176 See
 177 .Xr zpool-features 7
 178 for more information about compatibility feature sets.
 179 .It Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value
 180 Sets the given pool feature.
 181 See the
 182 .Xr zpool-features 7
 183 section for a list of valid features that can be set.
 184 Value can be either disabled or enabled.
 185 .It Fl O Ar file-system-property Ns = Ns Ar value
 186 Sets the given file system properties in the root file system of the pool.
 187 See
 188 .Xr zfsprops 7
 189 for a list of valid properties that can be set.
 190 .It Fl R Ar root
 191 Equivalent to
 192 .Fl o Sy cachefile Ns = Ns Sy none Fl o Sy altroot Ns = Ns Ar root
 193 .It Fl t Ar tname
 194 Sets the in-core pool name to
 195 .Ar tname
 196 while the on-disk name will be the name specified as
 197 .Ar pool .
 198 This will set the default of the
 199 .Sy cachefile
 200 property to
 201 .Sy none .
 202 This is intended
 203 to handle name space collisions when creating pools for other systems,
 204 such as virtual machines or physical machines whose pools live on network
 205 block devices.
 206 .El
 207 .
 208 .Sh EXAMPLES
 209 .\" These are, respectively, examples 1, 2, 3, 4, 11, 12 from zpool.8
 210 .\" Make sure to update them bidirectionally
 211 .Ss Example 1 : No Creating a RAID-Z Storage Pool
 212 The following command creates a pool with a single raidz root vdev that
 213 consists of six disks:
 214 .Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf
 215 .
 216 .Ss Example 2 : No Creating a Mirrored Storage Pool
 217 The following command creates a pool with two mirrors, where each mirror
 218 contains two disks:
 219 .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd
 220 .
 221 .Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions
 222 The following command creates a non-redundant pool using two disk partitions:
 223 .Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2
 224 .
 225 .Ss Example 4 : No Creating a ZFS Storage Pool by Using Files
 226 The following command creates a non-redundant pool using files.
 227 While not recommended, a pool based on files can be useful for experimental
 228 purposes.
 229 .Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b
 230 .
 231 .Ss Example 5 : No Managing Hot Spares
 232 The following command creates a new pool with an available hot spare:
 233 .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa sdc
 234 .
 235 .Ss Example 6 : No Creating a ZFS Pool with Mirrored Separate Intent Logs
 236 The following command creates a ZFS storage pool consisting of two, two-way
 237 mirrors and mirrored log devices:
 238 .Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf
 239 .
 240 .Sh SEE ALSO
 241 .Xr zpool-destroy 8 ,
 242 .Xr zpool-export 8 ,
 243 .Xr zpool-import 8