logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zpool-import.8 (12212B)


  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 https://opensource.org/licenses/CDDL-1.0.
  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. tank ONLINE
  424. mirror ONLINE
  425. sda ONLINE
  426. sdb ONLINE
  427. .No # Nm zpool Cm import Ar tank
  428. .Ed
  429. .
  430. .Sh SEE ALSO
  431. .Xr zpool-export 8 ,
  432. .Xr zpool-list 8 ,
  433. .Xr zpool-status 8