sys/contrib/openzfs/man/man8/zpool-import.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 .\"
  29 .Dd March 16, 2022
  30 .Dt ZPOOL-IMPORT 8
  31 .Os
  32 .
  33 .Sh NAME
  34 .Nm zpool-import
  35 .Nd import ZFS storage pools or list available pools
  36 .Sh SYNOPSIS
  37 .Nm zpool
  38 .Cm import
  39 .Op Fl D
  40 .Oo Fl d Ar dir Ns | Ns Ar device Oc Ns …
  41 .Nm zpool
  42 .Cm import
  43 .Fl a
  44 .Op Fl DflmN
  45 .Op Fl F Op Fl nTX
  46 .Op Fl -rewind-to-checkpoint
  47 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device
  48 .Op Fl o Ar mntopts
  49 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  50 .Op Fl R Ar root
  51 .Nm zpool
  52 .Cm import
  53 .Op Fl Dflmt
  54 .Op Fl F Op Fl nTX
  55 .Op Fl -rewind-to-checkpoint
  56 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device
  57 .Op Fl o Ar mntopts
  58 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
  59 .Op Fl R Ar root
  60 .Op Fl s
  61 .Ar pool Ns | Ns Ar id
  62 .Op Ar newpool
  63 .
  64 .Sh DESCRIPTION
  65 .Bl -tag -width Ds
  66 .It Xo
  67 .Nm zpool
  68 .Cm import
  69 .Op Fl D
  70 .Oo Fl d Ar dir Ns | Ns Ar device Oc Ns …
  71 .Xc
  72 Lists pools available to import.
  73 If the
  74 .Fl d
  75 or
  76 .Fl c
  77 options are not specified, this command searches for devices using libblkid
  78 on Linux and geom on
  79 .Fx .
  80 The
  81 .Fl d
  82 option can be specified multiple times, and all directories are searched.
  83 If the device appears to be part of an exported pool, this command displays a
  84 summary of the pool with the name of the pool, a numeric identifier, as well as
  85 the vdev layout and current health of the device for each device or file.
  86 Destroyed pools, pools that were previously destroyed with the
  87 .Nm zpool Cm destroy
  88 command, are not listed unless the
  89 .Fl D
  90 option is specified.
  91 .Pp
  92 The numeric identifier is unique, and can be used instead of the pool name when
  93 multiple exported pools of the same name are available.
  94 .Bl -tag -width Ds
  95 .It Fl c Ar cachefile
  96 Reads configuration from the given
  97 .Ar cachefile
  98 that was created with the
  99 .Sy cachefile
 100 pool property.
 101 This
 102 .Ar cachefile
 103 is used instead of searching for devices.
 104 .It Fl d Ar dir Ns | Ns Ar device
 105 Uses
 106 .Ar device
 107 or searches for devices or files in
 108 .Ar dir .
 109 The
 110 .Fl d
 111 option can be specified multiple times.
 112 .It Fl D
 113 Lists destroyed pools only.
 114 .El
 115 .It Xo
 116 .Nm zpool
 117 .Cm import
 118 .Fl a
 119 .Op Fl DflmN
 120 .Op Fl F Op Fl nTX
 121 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device
 122 .Op Fl o Ar mntopts
 123 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
 124 .Op Fl R Ar root
 125 .Op Fl s
 126 .Xc
 127 Imports all pools found in the search directories.
 128 Identical to the previous command, except that all pools with a sufficient
 129 number of devices available are imported.
 130 Destroyed pools, pools that were previously destroyed with the
 131 .Nm zpool Cm destroy
 132 command, will not be imported unless the
 133 .Fl D
 134 option is specified.
 135 .Bl -tag -width Ds
 136 .It Fl a
 137 Searches for and imports all pools found.
 138 .It Fl c Ar cachefile
 139 Reads configuration from the given
 140 .Ar cachefile
 141 that was created with the
 142 .Sy cachefile
 143 pool property.
 144 This
 145 .Ar cachefile
 146 is used instead of searching for devices.
 147 .It Fl d Ar dir Ns | Ns Ar device
 148 Uses
 149 .Ar device
 150 or searches for devices or files in
 151 .Ar dir .
 152 The
 153 .Fl d
 154 option can be specified multiple times.
 155 This option is incompatible with the
 156 .Fl c
 157 option.
 158 .It Fl D
 159 Imports destroyed pools only.
 160 The
 161 .Fl f
 162 option is also required.
 163 .It Fl f
 164 Forces import, even if the pool appears to be potentially active.
 165 .It Fl F
 166 Recovery mode for a non-importable pool.
 167 Attempt to return the pool to an importable state by discarding the last few
 168 transactions.
 169 Not all damaged pools can be recovered by using this option.
 170 If successful, the data from the discarded transactions is irretrievably lost.
 171 This option is ignored if the pool is importable or already imported.
 172 .It Fl l
 173 Indicates that this command will request encryption keys for all encrypted
 174 datasets it attempts to mount as it is bringing the pool online.
 175 Note that if any datasets have a
 176 .Sy keylocation
 177 of
 178 .Sy prompt
 179 this command will block waiting for the keys to be entered.
 180 Without this flag
 181 encrypted datasets will be left unavailable until the keys are loaded.
 182 .It Fl m
 183 Allows a pool to import when there is a missing log device.
 184 Recent transactions can be lost because the log device will be discarded.
 185 .It Fl n
 186 Used with the
 187 .Fl F
 188 recovery option.
 189 Determines whether a non-importable pool can be made importable again, but does
 190 not actually perform the pool recovery.
 191 For more details about pool recovery mode, see the
 192 .Fl F
 193 option, above.
 194 .It Fl N
 195 Import the pool without mounting any file systems.
 196 .It Fl o Ar mntopts
 197 Comma-separated list of mount options to use when mounting datasets within the
 198 pool.
 199 See
 200 .Xr zfs 8
 201 for a description of dataset properties and mount options.
 202 .It Fl o Ar property Ns = Ns Ar value
 203 Sets the specified property on the imported pool.
 204 See the
 205 .Xr zpoolprops 7
 206 manual page for more information on the available pool properties.
 207 .It Fl R Ar root
 208 Sets the
 209 .Sy cachefile
 210 property to
 211 .Sy none
 212 and the
 213 .Sy altroot
 214 property to
 215 .Ar root .
 216 .It Fl -rewind-to-checkpoint
 217 Rewinds pool to the checkpointed state.
 218 Once the pool is imported with this flag there is no way to undo the rewind.
 219 All changes and data that were written after the checkpoint are lost!
 220 The only exception is when the
 221 .Sy readonly
 222 mounting option is enabled.
 223 In this case, the checkpointed state of the pool is opened and an
 224 administrator can see how the pool would look like if they were
 225 to fully rewind.
 226 .It Fl s
 227 Scan using the default search path, the libblkid cache will not be
 228 consulted.
 229 A custom search path may be specified by setting the
 230 .Sy ZPOOL_IMPORT_PATH
 231 environment variable.
 232 .It Fl X
 233 Used with the
 234 .Fl F
 235 recovery option.
 236 Determines whether extreme measures to find a valid txg should take place.
 237 This allows the pool to
 238 be rolled back to a txg which is no longer guaranteed to be consistent.
 239 Pools imported at an inconsistent txg may contain uncorrectable checksum errors.
 240 For more details about pool recovery mode, see the
 241 .Fl F
 242 option, above.
 243 WARNING: This option can be extremely hazardous to the
 244 health of your pool and should only be used as a last resort.
 245 .It Fl T
 246 Specify the txg to use for rollback.
 247 Implies
 248 .Fl FX .
 249 For more details
 250 about pool recovery mode, see the
 251 .Fl X
 252 option, above.
 253 WARNING: This option can be extremely hazardous to the
 254 health of your pool and should only be used as a last resort.
 255 .El
 256 .It Xo
 257 .Nm zpool
 258 .Cm import
 259 .Op Fl Dflmt
 260 .Op Fl F Op Fl nTX
 261 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device
 262 .Op Fl o Ar mntopts
 263 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns …
 264 .Op Fl R Ar root
 265 .Op Fl s
 266 .Ar pool Ns | Ns Ar id
 267 .Op Ar newpool
 268 .Xc
 269 Imports a specific pool.
 270 A pool can be identified by its name or the numeric identifier.
 271 If
 272 .Ar newpool
 273 is specified, the pool is imported using the name
 274 .Ar newpool .
 275 Otherwise, it is imported with the same name as its exported name.
 276 .Pp
 277 If a device is removed from a system without running
 278 .Nm zpool Cm export
 279 first, the device appears as potentially active.
 280 It cannot be determined if this was a failed export, or whether the device is
 281 really in use from another host.
 282 To import a pool in this state, the
 283 .Fl f
 284 option is required.
 285 .Bl -tag -width Ds
 286 .It Fl c Ar cachefile
 287 Reads configuration from the given
 288 .Ar cachefile
 289 that was created with the
 290 .Sy cachefile
 291 pool property.
 292 This
 293 .Ar cachefile
 294 is used instead of searching for devices.
 295 .It Fl d Ar dir Ns | Ns Ar device
 296 Uses
 297 .Ar device
 298 or searches for devices or files in
 299 .Ar dir .
 300 The
 301 .Fl d
 302 option can be specified multiple times.
 303 This option is incompatible with the
 304 .Fl c
 305 option.
 306 .It Fl D
 307 Imports destroyed pool.
 308 The
 309 .Fl f
 310 option is also required.
 311 .It Fl f
 312 Forces import, even if the pool appears to be potentially active.
 313 .It Fl F
 314 Recovery mode for a non-importable pool.
 315 Attempt to return the pool to an importable state by discarding the last few
 316 transactions.
 317 Not all damaged pools can be recovered by using this option.
 318 If successful, the data from the discarded transactions is irretrievably lost.
 319 This option is ignored if the pool is importable or already imported.
 320 .It Fl l
 321 Indicates that this command will request encryption keys for all encrypted
 322 datasets it attempts to mount as it is bringing the pool online.
 323 Note that if any datasets have a
 324 .Sy keylocation
 325 of
 326 .Sy prompt
 327 this command will block waiting for the keys to be entered.
 328 Without this flag
 329 encrypted datasets will be left unavailable until the keys are loaded.
 330 .It Fl m
 331 Allows a pool to import when there is a missing log device.
 332 Recent transactions can be lost because the log device will be discarded.
 333 .It Fl n
 334 Used with the
 335 .Fl F
 336 recovery option.
 337 Determines whether a non-importable pool can be made importable again, but does
 338 not actually perform the pool recovery.
 339 For more details about pool recovery mode, see the
 340 .Fl F
 341 option, above.
 342 .It Fl o Ar mntopts
 343 Comma-separated list of mount options to use when mounting datasets within the
 344 pool.
 345 See
 346 .Xr zfs 8
 347 for a description of dataset properties and mount options.
 348 .It Fl o Ar property Ns = Ns Ar value
 349 Sets the specified property on the imported pool.
 350 See the
 351 .Xr zpoolprops 7
 352 manual page for more information on the available pool properties.
 353 .It Fl R Ar root
 354 Sets the
 355 .Sy cachefile
 356 property to
 357 .Sy none
 358 and the
 359 .Sy altroot
 360 property to
 361 .Ar root .
 362 .It Fl s
 363 Scan using the default search path, the libblkid cache will not be
 364 consulted.
 365 A custom search path may be specified by setting the
 366 .Sy ZPOOL_IMPORT_PATH
 367 environment variable.
 368 .It Fl X
 369 Used with the
 370 .Fl F
 371 recovery option.
 372 Determines whether extreme measures to find a valid txg should take place.
 373 This allows the pool to
 374 be rolled back to a txg which is no longer guaranteed to be consistent.
 375 Pools imported at an inconsistent txg may contain uncorrectable
 376 checksum errors.
 377 For more details about pool recovery mode, see the
 378 .Fl F
 379 option, above.
 380 WARNING: This option can be extremely hazardous to the
 381 health of your pool and should only be used as a last resort.
 382 .It Fl T
 383 Specify the txg to use for rollback.
 384 Implies
 385 .Fl FX .
 386 For more details
 387 about pool recovery mode, see the
 388 .Fl X
 389 option, above.
 390 .Em WARNING :
 391 This option can be extremely hazardous to the
 392 health of your pool and should only be used as a last resort.
 393 .It Fl t
 394 Used with
 395 .Ar newpool .
 396 Specifies that
 397 .Ar newpool
 398 is temporary.
 399 Temporary pool names last until export.
 400 Ensures that the original pool name will be used
 401 in all label updates and therefore is retained upon export.
 402 Will also set
 403 .Fl o Sy cachefile Ns = Ns Sy none
 404 when not explicitly specified.
 405 .El
 406 .El
 407 .
 408 .Sh EXAMPLES
 409 .\" These are, respectively, examples 9 from zpool.8
 410 .\" Make sure to update them bidirectionally
 411 .Ss Example 9 : No Importing a ZFS Storage Pool
 412 The following command displays available pools, and then imports the pool
 413 .Ar tank
 414 for use on the system.
 415 The results from this command are similar to the following:
 416 .Bd -literal -compact -offset Ds
 417 .No # Nm zpool Cm import
 418   pool: tank
 419     id: 15451357997522795478
 420  state: ONLINE
 421 action: The pool can be imported using its name or numeric identifier.
 422 config:
 423
 424         tank        ONLINE
 425           mirror    ONLINE
 426             sda     ONLINE
 427             sdb     ONLINE
 428
 429 .No # Nm zpool Cm import Ar tank
 430 .Ed
 431 .
 432 .Sh SEE ALSO
 433 .Xr zpool-export 8 ,
 434 .Xr zpool-list 8 ,
 435 .Xr zpool-status 8