---
title: Tarballs
eleventyNavigation:
  key: Tarballs
  parent: 🗄️ Data sources
---

If you backup [tarballs](https://en.wikipedia.org/wiki/Tar_(computing)) as part
of your source directories, Borg can't effectively deduplicate their contents
because of the way that a tarball's files are packed together (and often
compressed). This isn't a big deal for small tarballs, but it can really hurt
for large ones like virtual machine exports.

<span class="minilink minilink-addedin">New in version 2.2.0</span> <span
class="minilink minilink-addedin">Beta feature</span> borgmatic supports
configuring tarballs as data sources for backups, unpacking their contained
files directly into a Borg archive so that deduplication works properly.

To take advantage of this feature, use the `tarballs:` hook. For example:

```yaml
tarballs:
    - name: virtual-machine
      path: /var/lib/vz/dump/vzdump-vm.tar
```

And to restore such a tarball to its original path:

```bash
borgmatic restore --archive latest --data-source virtual-machine
```

During backup, borgmatic streams each tarball to Borg, unpacking its files
directly into the created Borg archive. Under the hood, this doesn't use Borg's
native `import-tar`, because that's limited to a single tarball per archive—and
no additional source directories.

Upon
[restore](https://torsion.org/borgmatic/reference/command-line/actions/restore/),
borgmatic exports the tarball from the archive, rewriting it on the fly to
inject its original contained file permissions, ownership, symlinks, etc. The
resulting tarball ends up at its original `path` (or `restore_path`).

Both `create` and `restore` operate without using any temporary files for
tarball data.


## Limitations

 * Within an archive, tarball contents are not stored at their original path.
   Instead, they are stored within `borgmatic/tarballs/` (with Borg 1.4+) so
   that the `restore` action can find them.
 * Due to the way that borgmatic streams tarballs to Borg via named pipes,
   per-file information (permissions, ownership, symlink targets, etc.) is
   stored separately from file contents in a per-tarball manifest file within
   `borgmatic/tarballs/`. This is consumed by the `restore` action.
 * During restore, borgmatic attempts to match the compression (if any) of the
   original tarball based on its file extension. If it can't determine the
   compression method, it errors.
 * If a tarball that you've configured under `tarballs:` also appears in your
   source directories, it will get backed up twice—once tarred and once
   untarred. You can of course add an exclude if you'd like a tarball to only
   get backed up once.
 * When this hook is enabled, borgmatic instructs Borg to consume special files
   (via `--read-special`) to support tarball streaming—regardless of the value
   of your `read_special` configuration option.
 * Tarballs backed up and restored with this data source hook are not
   bit-identical to their corresponding original tarballs, even though their
   file contents and metadata should be the same.
 * During the `restore` action, borgmatic removes any existing tarball already
   present at the restore path before replacing it with the restored tarball.
 * Currently, this hook only supports the following compression types on
   tarballs: gzip, bzip2, xz, and no compression.


## Full configuration

{% include snippet/configuration/sample.md %}

```yaml
{% include borgmatic/tarballs.yaml %}
```