zpool-create.8 (7740B)
- .\"
- .\" 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) 2007, Sun Microsystems, Inc. All Rights Reserved.
- .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
- .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
- .\" Copyright (c) 2017 Datto Inc.
- .\" Copyright (c) 2018 George Melikov. All Rights Reserved.
- .\" Copyright 2017 Nexenta Systems, Inc.
- .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
- .\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
- .\"
- .Dd March 16, 2022
- .Dt ZPOOL-CREATE 8
- .Os
- .
- .Sh NAME
- .Nm zpool-create
- .Nd create ZFS storage pool
- .Sh SYNOPSIS
- .Nm zpool
- .Cm create
- .Op Fl dfn
- .Op Fl m Ar mountpoint
- .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
- .Oo Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value Oc
- .Op Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
- .Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns …
- .Op Fl R Ar root
- .Op Fl t Ar tname
- .Ar pool
- .Ar vdev Ns …
- .
- .Sh DESCRIPTION
- Creates a new storage pool containing the virtual devices specified on the
- command line.
- The pool name must begin with a letter, and can only contain
- alphanumeric characters as well as the underscore
- .Pq Qq Sy _ ,
- dash
- .Pq Qq Sy \&- ,
- colon
- .Pq Qq Sy \&: ,
- space
- .Pq Qq Sy \&\ ,
- and period
- .Pq Qq Sy \&. .
- The pool names
- .Sy mirror ,
- .Sy raidz ,
- .Sy draid ,
- .Sy spare
- and
- .Sy log
- are reserved, as are names beginning with
- .Sy mirror ,
- .Sy raidz ,
- .Sy draid ,
- and
- .Sy spare .
- The
- .Ar vdev
- specification is described in the
- .Sx Virtual Devices
- section of
- .Xr zpoolconcepts 7 .
- .Pp
- The command attempts to verify that each device specified is accessible and not
- currently in use by another subsystem.
- However this check is not robust enough
- to detect simultaneous attempts to use a new device in different pools, even if
- .Sy multihost Ns = Sy enabled .
- The administrator must ensure that simultaneous invocations of any combination
- of
- .Nm zpool Cm replace ,
- .Nm zpool Cm create ,
- .Nm zpool Cm add ,
- or
- .Nm zpool Cm labelclear
- do not refer to the same device.
- Using the same device in two pools will result in pool corruption.
- .Pp
- There are some uses, such as being currently mounted, or specified as the
- dedicated dump device, that prevents a device from ever being used by ZFS.
- Other uses, such as having a preexisting UFS file system, can be overridden with
- .Fl f .
- .Pp
- The command also checks that the replication strategy for the pool is
- consistent.
- An attempt to combine redundant and non-redundant storage in a single pool,
- or to mix disks and files, results in an error unless
- .Fl f
- is specified.
- The use of differently-sized devices within a single raidz or mirror group is
- also flagged as an error unless
- .Fl f
- is specified.
- .Pp
- Unless the
- .Fl R
- option is specified, the default mount point is
- .Pa / Ns Ar pool .
- The mount point must not exist or must be empty, or else the root dataset
- will not be able to be be mounted.
- This can be overridden with the
- .Fl m
- option.
- .Pp
- By default all supported features are enabled on the new pool.
- The
- .Fl d
- option and the
- .Fl o Ar compatibility
- property
- .Pq e.g Fl o Sy compatibility Ns = Ns Ar 2020
- can be used to restrict the features that are enabled, so that the
- pool can be imported on other releases of ZFS.
- .Bl -tag -width "-t tname"
- .It Fl d
- Do not enable any features on the new pool.
- Individual features can be enabled by setting their corresponding properties to
- .Sy enabled
- with
- .Fl o .
- See
- .Xr zpool-features 7
- for details about feature properties.
- .It Fl f
- Forces use of
- .Ar vdev Ns s ,
- even if they appear in use or specify a conflicting replication level.
- Not all devices can be overridden in this manner.
- .It Fl m Ar mountpoint
- Sets the mount point for the root dataset.
- The default mount point is
- .Pa /pool
- or
- .Pa altroot/pool
- if
- .Sy altroot
- is specified.
- The mount point must be an absolute path,
- .Sy legacy ,
- or
- .Sy none .
- For more information on dataset mount points, see
- .Xr zfsprops 7 .
- .It Fl n
- Displays the configuration that would be used without actually creating the
- pool.
- The actual pool creation can still fail due to insufficient privileges or
- device sharing.
- .It Fl o Ar property Ns = Ns Ar value
- Sets the given pool properties.
- See
- .Xr zpoolprops 7
- for a list of valid properties that can be set.
- .It Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
- Specifies compatibility feature sets.
- See
- .Xr zpool-features 7
- for more information about compatibility feature sets.
- .It Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value
- Sets the given pool feature.
- See the
- .Xr zpool-features 7
- section for a list of valid features that can be set.
- Value can be either disabled or enabled.
- .It Fl O Ar file-system-property Ns = Ns Ar value
- Sets the given file system properties in the root file system of the pool.
- See
- .Xr zfsprops 7
- for a list of valid properties that can be set.
- .It Fl R Ar root
- Equivalent to
- .Fl o Sy cachefile Ns = Ns Sy none Fl o Sy altroot Ns = Ns Ar root
- .It Fl t Ar tname
- Sets the in-core pool name to
- .Ar tname
- while the on-disk name will be the name specified as
- .Ar pool .
- This will set the default of the
- .Sy cachefile
- property to
- .Sy none .
- This is intended
- to handle name space collisions when creating pools for other systems,
- such as virtual machines or physical machines whose pools live on network
- block devices.
- .El
- .
- .Sh EXAMPLES
- .\" These are, respectively, examples 1, 2, 3, 4, 11, 12 from zpool.8
- .\" Make sure to update them bidirectionally
- .Ss Example 1 : No Creating a RAID-Z Storage Pool
- The following command creates a pool with a single raidz root vdev that
- consists of six disks:
- .Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf
- .
- .Ss Example 2 : No Creating a Mirrored Storage Pool
- The following command creates a pool with two mirrors, where each mirror
- contains two disks:
- .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd
- .
- .Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions
- The following command creates a non-redundant pool using two disk partitions:
- .Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2
- .
- .Ss Example 4 : No Creating a ZFS Storage Pool by Using Files
- The following command creates a non-redundant pool using files.
- While not recommended, a pool based on files can be useful for experimental
- purposes.
- .Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b
- .
- .Ss Example 5 : No Managing Hot Spares
- The following command creates a new pool with an available hot spare:
- .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa sdc
- .
- .Ss Example 6 : No Creating a ZFS Pool with Mirrored Separate Intent Logs
- The following command creates a ZFS storage pool consisting of two, two-way
- mirrors and mirrored log devices:
- .Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf
- .
- .Sh SEE ALSO
- .Xr zpool-destroy 8 ,
- .Xr zpool-export 8 ,
- .Xr zpool-import 8