nbdkit-tar-filter(1)

πŸ“¦
version 1.48.1 Β· 14 versions
, in fedora 44

πŸ’– nbdkit-tar-filter β€” the manual page, but make it make sense πŸ’–

okay bestie, gather round, because this is the nbdkit-tar-filter(1) page and it's genuinely iconic. it's a filter that lets you read and write files sitting inside a tar file without unpacking anything. no cap. the vibes are immaculate. πŸ¦‹

✨ NAME ✨

nbdkit-tar-filter β€” read and write files inside tar files without unpacking

πŸŽ€ SYNOPSIS πŸŽ€

nbdkit file FILENAME.tar
       --filter=tar tar-entry=PATH_INSIDE_TAR
                            [tar=TAR_COMMAND] [tar-limit=SIZE]

🌸 EXAMPLES 🌸

πŸ“ Serve a single file inside a tarball

literally just point it at the tar and name the entry, periodt:

nbdkit file file.tar --filter=tar tar-entry=some/disk.img
guestfish --format=raw -a nbd://localhost

🧚 Opening a disk image inside an OVA file

okay so the popular "Open Virtual Appliance" (OVA) format is really just an uncompressed tar file that contains (usually) VMDK-format files. so you can absolutely reach in and grab one file out of an OVA like this:

$ tar tf rhel.ova
rhel.ovf
rhel-disk1.vmdk
rhel.mf
$ nbdkit -r file rhel.ova --filter=tar tar-entry=rhel-disk1.vmdk
$ guestfish --ro --format=vmdk -a nbd://localhost

in this case the tarball is opened readonly (that's the -r option). the plugin does support write access, but writing to the VMDK file inside the tarball does not change the data checksums stored in the other files (the rhel.mf file in this example) β€” and since those checksums will become wrong, you probably won't be able to open the file with another tool afterwards. πŸ’€ so like, maybe don't.

πŸ¦‹ Open a disk image inside a remote tar file

you're not stuck with nbdkit-file-plugin(1) either! any plugin can hand over the tar file. for example, if the tar file lives on a web server, use this:

nbdkit -r curl https://example.com/file.tar \
       --filter=tar tar-entry=disk.img

⭐ Open a compressed tar file (read-only)

ngl, this filter cannot handle compressed tar files all by itself. but bestie, you can combine it with a decompression filter like nbdkit-gzip-filter(1) or nbdkit-xz-filter(1):

nbdkit file filename.tar.gz \
       --filter=tar tar-entry=disk.img --filter=gzip
nbdkit file filename.tar.xz \
       --filter=tar tar-entry=disk.img --filter=xz

πŸ‘‘ DESCRIPTION πŸ‘‘

nbdkit-tar-filter is a filter which can read and writes files inside an uncompressed tar file without unpacking the tar file.

the tar file itself is provided by the underlying plugin. you have to tell the filter which entry inside the tar file you want to read and write, and you do that with the tar-entry parameter. tar-entry must exactly match the file name in the tar index β€” like, character for character, no typos allowed πŸ’…. use tar tf filename.tar to list the index of a tar file.

this filter will not work directly on compressed tar files. you have to combine it with another filter, like the example up above shows.

use the nbdkit -r flag to open the file readonly. this is the safest option because it guarantees the tar file will not be modified. without -r, writes will modify the tar file. πŸ™ˆ

the disk image cannot be resized. that's just the rules.

πŸ’… PARAMETERS πŸ’…

  • [tar-entry=]PATH_INSIDE_TAR β€” the path of the file inside the tarball that you want to serve. this parameter is required (no skipping it, bestie). it must exactly match the name stored in the tarball, so seriously, use tar tf filename.tar.
  • [tar-limit=]SIZE β€” okay so when opening the tar file we have to locate the file (tar-entry) inside the tarball. and because tar files do not have a central index, we must iterate over the tar file to find the entry β€” which may be costly, especially with untrusted tar files 😭. in the worst case, where tar-entry starts near the end of the file, we may have to iterate over the whole tar file. if that's a problem you can set tar-limit to some smaller value, eg:
nbdkit -r curl https://example.com/file.tar \
       --filter=tar tar-entry=disk.img \
                    tar-limit=10M

which ensures no more than 10 megabytes are read before we give up and reject the tar file (sending an error back to the NBD client).

the default is 0, meaning no limit.

  • tar=gtar
  • tar=/PATH/TO/GTAR β€” specify the program name or full path of GNU tar, in case tar on $PATH is not GNU tar. this filter requires GNU tar and will not normally work with other tar programs (eg. on FreeBSD).

🌈 FILES 🌈

  • $filterdir/nbdkit-tar-filter.so β€” The plugin.

Use nbdkit --dump-config to find the location of $filterdir.

🫢 VERSION 🫢

nbdkit-tar-filter first appeared in nbdkit 1.22. it is derived from nbdkit-tar-plugin which first appeared in nbdkit 1.2. glow-up of the century honestly ✨

πŸ”₯ SEE ALSO πŸ”₯

nbdkit(1), nbdkit-curl-plugin(1), nbdkit-file-plugin(1), nbdkit-gzip-filter(1), nbdkit-lzip-filter(1), nbdkit-map-filter(1), nbdkit-offset-filter(1), nbdkit-plugin(3), nbdkit-ssh-plugin(1), nbdkit-xz-filter(1), tar(1).

πŸ’œ AUTHORS πŸ’œ

Richard W.M. Jones.

Based on the virt-v2v OVA importer written by TomΓ‘Ε‘ GolembiovskΓ½.

Copyright Red Hat

πŸ’– LICENSE πŸ’–

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • 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.

okay that's the whole page, we ate and left no crumbs πŸ“ this lil gem shipped in nbdkit-1.48.1, dated 2026-08-29, and it lives in the nbdkit-tar-filter(1) manual. mwah, go read a tarball πŸ’…πŸŒˆβœ¨

πŸ“¦ where this page comes from