xref: /freebsd/sys/contrib/openzfs/man/man8/zpool-attach.8 (revision 61145dc2b94f12f6a47344fb9aac702321880e43)
1*61145dc2SMartin Matuska.\" SPDX-License-Identifier: CDDL-1.0
2eda14cbcSMatt Macy.\"
3eda14cbcSMatt Macy.\" CDDL HEADER START
4eda14cbcSMatt Macy.\"
5eda14cbcSMatt Macy.\" The contents of this file are subject to the terms of the
6eda14cbcSMatt Macy.\" Common Development and Distribution License (the "License").
7eda14cbcSMatt Macy.\" You may not use this file except in compliance with the License.
8eda14cbcSMatt Macy.\"
9eda14cbcSMatt Macy.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10271171e0SMartin Matuska.\" or https://opensource.org/licenses/CDDL-1.0.
11eda14cbcSMatt Macy.\" See the License for the specific language governing permissions
12eda14cbcSMatt Macy.\" and limitations under the License.
13eda14cbcSMatt Macy.\"
14eda14cbcSMatt Macy.\" When distributing Covered Code, include this CDDL HEADER in each
15eda14cbcSMatt Macy.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16eda14cbcSMatt Macy.\" If applicable, add the following below this CDDL HEADER, with the
17eda14cbcSMatt Macy.\" fields enclosed by brackets "[]" replaced with your own identifying
18eda14cbcSMatt Macy.\" information: Portions Copyright [yyyy] [name of copyright owner]
19eda14cbcSMatt Macy.\"
20eda14cbcSMatt Macy.\" CDDL HEADER END
21eda14cbcSMatt Macy.\"
22eda14cbcSMatt Macy.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
23eda14cbcSMatt Macy.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
24eda14cbcSMatt Macy.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
25eda14cbcSMatt Macy.\" Copyright (c) 2017 Datto Inc.
26eda14cbcSMatt Macy.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
27eda14cbcSMatt Macy.\" Copyright 2017 Nexenta Systems, Inc.
28eda14cbcSMatt Macy.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
29eda14cbcSMatt Macy.\"
30e716630dSMartin Matuska.Dd June 28, 2023
31eda14cbcSMatt Macy.Dt ZPOOL-ATTACH 8
32eda14cbcSMatt Macy.Os
3316038816SMartin Matuska.
34eda14cbcSMatt Macy.Sh NAME
357877fdebSMatt Macy.Nm zpool-attach
3616038816SMartin Matuska.Nd attach new device to existing ZFS vdev
37eda14cbcSMatt Macy.Sh SYNOPSIS
387877fdebSMatt Macy.Nm zpool
39eda14cbcSMatt Macy.Cm attach
40eda14cbcSMatt Macy.Op Fl fsw
41eda14cbcSMatt Macy.Oo Fl o Ar property Ns = Ns Ar value Oc
42eda14cbcSMatt Macy.Ar pool device new_device
4316038816SMartin Matuska.
44eda14cbcSMatt Macy.Sh DESCRIPTION
45eda14cbcSMatt MacyAttaches
46eda14cbcSMatt Macy.Ar new_device
47eda14cbcSMatt Macyto the existing
48eda14cbcSMatt Macy.Ar device .
49e716630dSMartin MatuskaThe behavior differs depending on if the existing
50e716630dSMartin Matuska.Ar device
51e716630dSMartin Matuskais a RAID-Z device, or a mirror/plain device.
52e716630dSMartin Matuska.Pp
53e716630dSMartin MatuskaIf the existing device is a mirror or plain device
54e716630dSMartin Matuska.Pq e.g. specified as Qo Li sda Qc or Qq Li mirror-7 ,
55e716630dSMartin Matuskathe new device will be mirrored with the existing device, a resilver will be
56e716630dSMartin Matuskainitiated, and the new device will contribute to additional redundancy once the
57e716630dSMartin Matuskaresilver completes.
58eda14cbcSMatt MacyIf
59eda14cbcSMatt Macy.Ar device
60eda14cbcSMatt Macyis not currently part of a mirrored configuration,
61eda14cbcSMatt Macy.Ar device
62eda14cbcSMatt Macyautomatically transforms into a two-way mirror of
63eda14cbcSMatt Macy.Ar device
64eda14cbcSMatt Macyand
65eda14cbcSMatt Macy.Ar new_device .
66eda14cbcSMatt MacyIf
67eda14cbcSMatt Macy.Ar device
68eda14cbcSMatt Macyis part of a two-way mirror, attaching
69eda14cbcSMatt Macy.Ar new_device
70eda14cbcSMatt Macycreates a three-way mirror, and so on.
71eda14cbcSMatt MacyIn either case,
72eda14cbcSMatt Macy.Ar new_device
73*61145dc2SMartin Matuskabegins to resilver immediately and any running scrub is canceled.
74e716630dSMartin Matuska.Pp
75e716630dSMartin MatuskaIf the existing device is a RAID-Z device
76e716630dSMartin Matuska.Pq e.g. specified as Qq Ar raidz2-0 ,
77e716630dSMartin Matuskathe new device will become part of that RAID-Z group.
78e716630dSMartin MatuskaA "raidz expansion" will be initiated, and once the expansion completes,
79e716630dSMartin Matuskathe new device will contribute additional space to the RAID-Z group.
80e716630dSMartin MatuskaThe expansion entails reading all allocated space from existing disks in the
81e716630dSMartin MatuskaRAID-Z group, and rewriting it to the new disks in the RAID-Z group (including
82e716630dSMartin Matuskathe newly added
83e716630dSMartin Matuska.Ar device ) .
84e716630dSMartin MatuskaIts progress can be monitored with
85e716630dSMartin Matuska.Nm zpool Cm status .
86e716630dSMartin Matuska.Pp
87e716630dSMartin MatuskaData redundancy is maintained during and after the expansion.
88e716630dSMartin MatuskaIf a disk fails while the expansion is in progress, the expansion pauses until
89e716630dSMartin Matuskathe health of the RAID-Z vdev is restored (e.g. by replacing the failed disk
90e716630dSMartin Matuskaand waiting for reconstruction to complete).
91e716630dSMartin MatuskaExpansion does not change the number of failures that can be tolerated
92e716630dSMartin Matuskawithout data loss (e.g. a RAID-Z2 is still a RAID-Z2 even after expansion).
93e716630dSMartin MatuskaA RAID-Z vdev can be expanded multiple times.
94e716630dSMartin Matuska.Pp
95e716630dSMartin MatuskaAfter the expansion completes, old blocks retain their old data-to-parity
96e716630dSMartin Matuskaratio
97e716630dSMartin Matuska.Pq e.g. 5-wide RAID-Z2 has 3 data and 2 parity
98e716630dSMartin Matuskabut distributed among the larger set of disks.
99e716630dSMartin MatuskaNew blocks will be written with the new data-to-parity ratio (e.g. a 5-wide
100e716630dSMartin MatuskaRAID-Z2 which has been expanded once to 6-wide, has 4 data and 2 parity).
101e716630dSMartin MatuskaHowever, the vdev's assumed parity ratio does not change, so slightly less
102e716630dSMartin Matuskaspace than is expected may be reported for newly-written blocks, according to
103e716630dSMartin Matuska.Nm zfs Cm list ,
104e716630dSMartin Matuska.Nm df ,
105e716630dSMartin Matuska.Nm ls Fl s ,
106e716630dSMartin Matuskaand similar tools.
107e716630dSMartin Matuska.Pp
108e716630dSMartin MatuskaA pool-wide scrub is initiated at the end of the expansion in order to verify
109e716630dSMartin Matuskathe checksums of all blocks which have been copied during the expansion.
110eda14cbcSMatt Macy.Bl -tag -width Ds
111eda14cbcSMatt Macy.It Fl f
112eda14cbcSMatt MacyForces use of
113eda14cbcSMatt Macy.Ar new_device ,
114eda14cbcSMatt Macyeven if it appears to be in use.
115eda14cbcSMatt MacyNot all devices can be overridden in this manner.
116eda14cbcSMatt Macy.It Fl o Ar property Ns = Ns Ar value
11716038816SMartin MatuskaSets the given pool properties.
11816038816SMartin MatuskaSee the
1193ff01b23SMartin Matuska.Xr zpoolprops 7
12016038816SMartin Matuskamanual page for a list of valid properties that can be set.
12116038816SMartin MatuskaThe only property supported at the moment is
12216038816SMartin Matuska.Sy ashift .
123eda14cbcSMatt Macy.It Fl s
124e716630dSMartin MatuskaWhen attaching to a mirror or plain device, the
125eda14cbcSMatt Macy.Ar new_device
126eda14cbcSMatt Macyis reconstructed sequentially to restore redundancy as quickly as possible.
127e92ffd9bSMartin MatuskaChecksums are not verified during sequential reconstruction so a scrub is
128eda14cbcSMatt Macystarted when the resilver completes.
129eda14cbcSMatt Macy.It Fl w
130eda14cbcSMatt MacyWaits until
131eda14cbcSMatt Macy.Ar new_device
132e716630dSMartin Matuskahas finished resilvering or expanding before returning.
133eda14cbcSMatt Macy.El
13416038816SMartin Matuska.
135eda14cbcSMatt Macy.Sh SEE ALSO
136eda14cbcSMatt Macy.Xr zpool-add 8 ,
13716038816SMartin Matuska.Xr zpool-detach 8 ,
138eda14cbcSMatt Macy.Xr zpool-import 8 ,
139eda14cbcSMatt Macy.Xr zpool-initialize 8 ,
140eda14cbcSMatt Macy.Xr zpool-online 8 ,
141eda14cbcSMatt Macy.Xr zpool-replace 8 ,
142eda14cbcSMatt Macy.Xr zpool-resilver 8
143