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