nbdkit-cdi-plugin(1)

📦
version 1.48.0 · 11 versions
, in ubuntu stonking

💅 nbdkit-cdi-plugin — like, the whole manual, but make it make sense

okay so bestie, welcome to nbdkit-cdi-plugin(1), one of the nbdkit manual pages, and honestly? it's a vibe. we're gonna talk about exporting a layer from a container image and it's gonna slay. 🎀

✨ NAME ✨

nbdkit-cdi-plugin — export a layer from a container image. that's it. that's the tweet. 💅

🦋 SYNOPSIS 🦋

nbdkit cdi [name=]NAME[:TAG|@DIGEST] [layer=N]

like literally that's all you type, no cap.

🌸 DESCRIPTION 🌸

okay so "nbdkit-cdi-plugin" — the Containerized Data Importer plugin — is a plugin for nbdkit(1) that downloads a container image using podman-pull(1) and then makes a single layer available over NBD. one layer. that's the whole plot. 🫶

it's essentially a convenient lil wrapper around podman(1) and jq(1), so heads up: both tools need to be installed. not optional, bestie. both. fr fr.

🔥 EXAMPLES 🔥

okay so imagine you've got a Containerized Data Importer (CDI) registry image and it's holding a VM disk inside. iconic. you can export the whole layer like this:

$ nbdkit cdi quay.io/kubevirt/fedora-cloud-container-disk-demo

and the layer that comes out over NBD? it's a tar file. no cap:

$ nbdcopy nbd://localhost - | file -
-: POSIX tar archive

but say you only want the VM disk image inside that layer — the way to do that is to combine this plugin with nbdkit-tar-filter(1). in the example below, the file exposed inside the tar archive is a qcow2 image, so you can turn it into a raw NBD export of the virtual machine using nbdkit-qcow2dec-filter(1). look at this diagram, it's giving nesting doll realness:

┌──────────────────────────────────────────┐
│ fedora-cloud-container-disk-demo layer=0 │
│ (uncompressed tar file)                  │
│ ┌──────────────────────────────────────┐ │
│ │ ./disk/downloaded                    │ │
│ │ (qcow2 image)                        │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────┘
$ nbdkit cdi \
        --filter=qcow2dec \
        --filter=tar tar-entry=./disk/downloaded \
        quay.io/kubevirt/fedora-cloud-container-disk-demo \
        --run 'nbdinfo "$uri"'
export="":
    export-size: 4294967296 (4G)
    content: DOS/MBR boot sector
[...]

ate. 🔥

👑 PARAMETERS 👑

  • [name=]NAME[:TAG|@DIGEST] — the name or URI of the container image. this gets passed straight to podman-pull(1). also, the "name=" prefix may be omitted in most cases — see "Magic parameters" in nbdkit(1). iykyk ✨
  • layer=N — export the N'th layer instead of layer 0. like picking which slice of cake you want. 🍓

🌈 ENVIRONMENT VARIABLES 🌈

  • "TMPDIR" — a temporary copy of the layer gets created in "TMPDIR". if this environment variable is not set, then /var/tmp is used instead. so like, that's where your lil temp clone lives. 🧚

💜 FILES 💜

  • $plugindir/nbdkit-cdi-plugin.so — the plugin itself. literally the whole thing. run "nbdkit --dump-config" to find the location of $plugindir. 🎀

⭐ VERSION ⭐

"nbdkit-cdi-plugin" first appeared in nbdkit 1.22. a classic. an icon. a legend.

🦋 SEE ALSO 🦋

nbdkit(1), nbdkit-plugin(3), nbdkit-qcow2dec-filter(1), nbdkit-tar-filter(1), podman(1), podman-pull(1), jq(1), and this link which we're keeping exactly as-is because it's a real URL and we don't mess with those: https://github.com/kubevirt/containerized-data-importer/blob/master/doc/image-from-registry.md.

go read them. main character energy only. 💅

🌸 AUTHORS 🌸

Richard W.M. Jones — the moment. the legend. 👑

Copyright Red Hat

🎀 LICENSE 🎀

okay so redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met. read them carefully bestie, this part is not a vibe, it's the rules:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
⚠️ THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

like, all caps for a reason. 💀

and that's the whole page, bestie — this version of the manual is from nbdkit-1.48.0, dated 2026-08-22, and the page you just read is nbdkit-cdi-plugin(1). slay, go export a layer, ily 🫶✨💖

📦 where this page comes from