xref: /freebsd/sys/contrib/openzfs/man/man8/zpool-create.8 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
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.\"
22.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
23.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
24.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
25.\" Copyright (c) 2017 Datto Inc.
26.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
27.\" Copyright 2017 Nexenta Systems, Inc.
28.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
29.\"
30.Dd August 9, 2019
31.Dt ZPOOL-CREATE 8
32.Os
33.Sh NAME
34.Nm zpool-create
35.Nd Creates a new ZFS storage pool
36.Sh SYNOPSIS
37.Nm zpool
38.Cm create
39.Op Fl dfn
40.Op Fl m Ar mountpoint
41.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
42.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc
43.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
44.Op Fl R Ar root
45.Ar pool vdev Ns ...
46.Sh DESCRIPTION
47.Bl -tag -width Ds
48.It Xo
49.Nm zpool
50.Cm create
51.Op Fl dfn
52.Op Fl m Ar mountpoint
53.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
54.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc Ns ...
55.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
56.Op Fl R Ar root
57.Op Fl t Ar tname
58.Ar pool vdev Ns ...
59.Xc
60Creates a new storage pool containing the virtual devices specified on the
61command line.
62The pool name must begin with a letter, and can only contain
63alphanumeric characters as well as underscore
64.Pq Qq Sy _ ,
65dash
66.Pq Qq Sy \&- ,
67colon
68.Pq Qq Sy \&: ,
69space
70.Pq Qq Sy \&\  ,
71and period
72.Pq Qq Sy \&. .
73The pool names
74.Sy mirror ,
75.Sy raidz ,
76.Sy draid ,
77.Sy spare
78and
79.Sy log
80are reserved, as are names beginning with
81.Sy mirror ,
82.Sy raidz ,
83.Sy draid ,
84.Sy spare ,
85and the pattern
86.Sy c[0-9] .
87The
88.Ar vdev
89specification is described in the
90.Em Virtual Devices
91section of
92.Xr zpoolconcepts.
93.Pp
94The command attempts to verify that each device specified is accessible and not
95currently in use by another subsystem.  However this check is not robust enough
96to detect simultaneous attempts to use a new device in different pools, even if
97.Sy multihost
98is
99.Sy enabled.
100The
101administrator must ensure that simultaneous invocations of any combination of
102.Sy zpool replace ,
103.Sy zpool create ,
104.Sy zpool add ,
105or
106.Sy zpool labelclear ,
107do not refer to the same device.  Using the same device in two pools will
108result in pool corruption.
109.Pp
110There are some uses, such as being currently mounted, or specified as the
111dedicated dump device, that prevents a device from ever being used by ZFS.
112Other uses, such as having a preexisting UFS file system, can be overridden with
113the
114.Fl f
115option.
116.Pp
117The command also checks that the replication strategy for the pool is
118consistent.
119An attempt to combine redundant and non-redundant storage in a single pool, or
120to mix disks and files, results in an error unless
121.Fl f
122is specified.
123The use of differently sized devices within a single raidz or mirror group is
124also flagged as an error unless
125.Fl f
126is specified.
127.Pp
128Unless the
129.Fl R
130option is specified, the default mount point is
131.Pa / Ns Ar pool .
132The mount point must not exist or must be empty, or else the root dataset
133cannot be mounted.
134This can be overridden with the
135.Fl m
136option.
137.Pp
138By default all supported features are enabled on the new pool unless the
139.Fl d
140option is specified.
141.Bl -tag -width Ds
142.It Fl d
143Do not enable any features on the new pool.
144Individual features can be enabled by setting their corresponding properties to
145.Sy enabled
146with the
147.Fl o
148option.
149See
150.Xr zpool-features 5
151for details about feature properties.
152.It Fl f
153Forces use of
154.Ar vdev Ns s ,
155even if they appear in use or specify a conflicting replication level.
156Not all devices can be overridden in this manner.
157.It Fl m Ar mountpoint
158Sets the mount point for the root dataset.
159The default mount point is
160.Pa /pool
161or
162.Pa altroot/pool
163if
164.Ar altroot
165is specified.
166The mount point must be an absolute path,
167.Sy legacy ,
168or
169.Sy none .
170For more information on dataset mount points, see
171.Xr zfs 8 .
172.It Fl n
173Displays the configuration that would be used without actually creating the
174pool.
175The actual pool creation can still fail due to insufficient privileges or
176device sharing.
177.It Fl o Ar property Ns = Ns Ar value
178Sets the given pool properties.
179See the
180.Xr zpoolprops
181manual page for a list of valid properties that can be set.
182.It Fl o Ar feature@feature Ns = Ns Ar value
183Sets the given pool feature. See the
184.Xr zpool-features 5
185section for a list of valid features that can be set.
186Value can be either disabled or enabled.
187.It Fl O Ar file-system-property Ns = Ns Ar value
188Sets the given file system properties in the root file system of the pool.
189See the
190.Xr zfsprops 8
191manual page for a list of valid properties that can be set.
192.It Fl R Ar root
193Equivalent to
194.Fl o Sy cachefile Ns = Ns Sy none Fl o Sy altroot Ns = Ns Ar root
195.It Fl t Ar tname
196Sets the in-core pool name to
197.Sy tname
198while the on-disk name will be the name specified as the pool name
199.Sy pool .
200This will set the default cachefile property to none. This is intended
201to handle name space collisions when creating pools for other systems,
202such as virtual machines or physical machines whose pools live on network
203block devices.
204.El
205.El
206.Sh SEE ALSO
207.Xr zpool-destroy 8 ,
208.Xr zpool-export 8 ,
209.Xr zpool-import 8
210