ZPOOL-IMPORT(8)

💖 zpool-import(8) 💖

okay bestie, gather round, because this is ZPOOL-IMPORT(8) from the System Manager's Manual and it's literally the page that tells you how to bring your ZFS storage pools home 🏠✨ — or just vibe-check which pools are out there waiting for you. Let's get into it. 🦋

---

✨ NAME ✨

zpool-import — import ZFS storage pools or list available pools 👑

---

🌈 SYNOPSIS 🌈

zpool import [-D] [-d dir|device]…
zpool import -a [-DflmN] [-F [-nTX]] [--rewind-to-checkpoint]
      [-c cachefile|-d dir|device] [-o mntopts] [-o property=value]…
      [-R root]
zpool import [-Dflmt] [-F [-nTX]] [--rewind-to-checkpoint]
      [-c cachefile|-d dir|device] [-o mntopts] [-o property=value]…
      [-R root] [-s] pool|id [newpool]

---

💅 DESCRIPTION 💅

🌸 zpool import [-D] [-d dir|device]… — the "so what's out there" one

This form lists the pools that are available to import. 🕵️‍♀️ If you don't hand it the -d or -c options, it goes hunting for devices on its own — using libblkid on Linux and geom on FreeBSD. And yes, you can drop -d more than once, and it'll search all the directories you gave it, no cap.

If a device looks like it's part of an exported pool, this command spills the tea: it shows a summary of the pool with the pool's name, a numeric identifier, plus the vdev layout and the current health of the device for every device or file. 🩺

Destroyed pools — like, pools you already took out with the zpool destroy command — will not show up here unless you pass -D. 💀

That numeric identifier? It's unique, and you can use it instead of the pool name whenever you've got multiple exported pools all flexing the same name. 🫶

• -c cachefile — reads the config from the cachefile you made with the cachefile pool property. This cachefile gets used instead of searching for devices. 📁
• -d dir|device — uses device, or searches for devices or files inside dir. You can pass -d more than once. 🔍
• -D — lists destroyed pools only. 💀

🎀 zpool import -a [-DflmN] [-F [-nTX]] [-c cachefile|-d dir|device] [-o mntopts] [-o property=value]… [-R root] [-s] — the "import literally everything" one

Imports all the pools it finds in the search directories. It's basically the previous command's twin, except it actually imports every pool that has enough devices available. Destroyed pools — y'know, the ones you previously destroyed with zpool destroy — won't get imported unless you say -D. 🚫

• -a — searches for and imports all pools it can find. 🌈
• -c cachefile — reads the config from the cachefile you made with the cachefile pool property. This cachefile is used instead of searching for devices. 📁
• -d dir|device — uses device, or searches for devices or files inside dir. You can pass -d more than once. Heads up though: this option is incompatible with the -c option. 🚧
• -D — imports destroyed pools only. And the -f option is also required. 💀➕
• -f — forces the import, even if the pool looks like it might be potentially active. 😤
• -F — recovery mode for a non-importable pool. It tries to bring the pool back to an importable state by tossing out the last few transactions. Not every damaged pool can be saved this way, ngl. And if it does work? The data from those discarded transactions is irretrievably lost. 😭 This option gets ignored if the pool is importable or already imported.
• -l — says that this command will request encryption keys 🔑 for every encrypted dataset it tries to mount while bringing the pool online. Careful though: if any datasets have a keylocation of prompt, this command will block waiting for the keys to be typed in. Without this flag, encrypted datasets just sit there unavailable until the keys get loaded. 🙈
• -m — lets a pool import even when there's a missing log device. Recent transactions can be lost, because the log device is gonna get discarded. 🗑️
• -n — used together with the -F recovery option. It figures out whether a non-importable pool can be made importable again, but it does not actually perform the pool recovery. More deets on pool recovery mode are under the -F option, above. 👆
• -N — imports the pool without mounting any file systems. 🚫📂
• -o mntopts — a comma-separated list of mount options to use when mounting datasets inside the pool. Peep zfs(8) for a rundown of dataset properties and mount options. 🧾
• -o property=value — sets the given property on the imported pool. Check the zpoolprops(7) manual page for more on the available pool properties. 🛠️
• -R root — sets the cachefile property to none and the altroot property to root. 🌳
• --rewind-to-checkpoint — rewinds the pool to its checkpointed state. ⏪ And bestie, listen: once the pool is imported with this flag, there is no way to undo the rewind. Every change and every bit of data written after the checkpoint is lost! 😱 The one exception is when the readonly mounting option is enabled — in that case the checkpointed state of the pool is opened, and an admin can see how the pool would look if they were to fully rewind. 👀
• -s — scans using the default search path, and the libblkid cache will not be consulted. You can specify a custom search path by setting the ZPOOL_IMPORT_PATH environment variable. 🧭
• -X — used with the -F recovery option. It decides whether extreme measures to find a valid txg should happen. This lets the pool be rolled back to a txg that is no longer guaranteed to be consistent. Pools imported at an inconsistent txg may contain uncorrectable checksum errors. More deets on pool recovery mode live under the -F option, above. 👆

WARNING: this option can be extremely hazardous to the health of your pool and should only ever be used as a last resort. 🚨💀

• -T — specify the txg to use for rollback. It implies -FX. More deets on pool recovery mode are under the -X option, above. 👆

WARNING: this option can be extremely hazardous to the health of your pool and should only ever be used as a last resort. 🚨💀

💜 zpool import [-Dflmt] [-F [-nTX]] [-c cachefile|-d dir|device] [-o mntopts] [-o property=value]… [-R root] [-s] pool|id [newpool] — the "import this specific one" one

Imports one specific pool. 🎯 You can point at it by its name or by its numeric identifier. If you hand it newpool, the pool gets imported under the name newpool. Otherwise, it comes in with the same name it had when it was exported. 🏷️

Now here's a thing: if a device got yanked out of a system without running zpool export first, that device shows up as potentially active. There's genuinely no way to tell whether that was a failed export or whether the device is actually in use from some other host. To import a pool in that state, the -f option is required. 😬

• -c cachefile — reads the config from the cachefile you made with the cachefile pool property. This cachefile is used instead of searching for devices. 📁
• -d dir|device — uses device, or searches for devices or files inside dir. You can pass -d more than once. Just know this option is incompatible with the -c option. 🚧
• -D — imports a destroyed pool. The -f option is also required. 💀➕
• -f — forces the import, even if the pool looks like it might be potentially active. 😤
• -F — recovery mode for a non-importable pool. It attempts to return the pool to an importable state by discarding the last few transactions. Not all damaged pools can be recovered with this option. If it succeeds, the data from the discarded transactions is irretrievably lost. 😭 This option is ignored if the pool is importable or already imported.
• -l — indicates that this command will request encryption keys 🔑 for all encrypted datasets it attempts to mount while it's bringing the pool online. Note that if any datasets have a keylocation of prompt, this command will block waiting for the keys to be entered. Without this flag, encrypted datasets are left unavailable until the keys get loaded. 🙈
• -m — allows a pool to import when there's a missing log device. Recent transactions can be lost because the log device will be discarded. 🗑️
• -n — used with the -F recovery option. Determines whether a non-importable pool can be made importable again, but does not actually perform the pool recovery. For more details about pool recovery mode, see the -F option, above. 👆
• -o mntopts — comma-separated list of mount options to use when mounting datasets within the pool. See zfs(8) for a description of dataset properties and mount options. 🧾
• -o property=value — sets the specified property on the imported pool. See the zpoolprops(7) manual page for more information on the available pool properties. 🛠️
• -R root — sets the cachefile property to none and the altroot property to root. 🌳
• -s — scans using the default search path, and the libblkid cache will not be consulted. A custom search path may be specified by setting the ZPOOL_IMPORT_PATH environment variable. 🧭

---

part 2 is coming bestie, don't you dare go anywhere 💖🦋

• -X — Used with the -F recovery option. Determines whether extreme measures to find a valid txg should take place. This allows the pool to be rolled back to a txg which is no longer guaranteed to be consistent. Pools imported at an inconsistent txg may contain uncorrectable checksum errors. For more details about pool recovery mode, see the -F option, above. WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort.
• -T — Specify the txg to use for rollback. Implies -FX. For more details about pool recovery mode, see the -X option, above. WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort.
• -t — Used with newpool. Specifies that newpool is temporary. Temporary pool names last until export. Ensures that the original pool name will be used in all label updates and therefore is retained upon export. Will also set -o cachefile=none when not explicitly specified.

---

✨ EXAMPLES ✨

🦋 Example 9: Importing a ZFS Storage Pool 🦋

Okay so this command? It displays available pools, and then imports the pool tank for use on the system. The results from this command are similar to the following:

             # zpool import
               pool: tank
                 id: 15451357997522795478
              state: ONLINE
             action: The pool can be imported using its name or numeric identifier.
             config:

                     tank        ONLINE
                       mirror    ONLINE
                         sda     ONLINE
                         sdb     ONLINE

             # zpool import tank

---

💖 SEE ALSO 💖

• zpool-export(8)
• zpool-list(8)
• zpool-status(8)

---

This page is from the OpenZFS crew 💖 July 11, 2022 ZPOOL-IMPORT(8) — stay slay, bestie 💅✨