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