Skip to content

zrepl

Upstream GitHub Container source GHCR Pulls: 672

About zrepl

zrepl is a ZFS replication tool. This image includes the zrepl daemon and Debian ZFS userland utilities.

Host setup

The image runs as tuxcrate, UID/GID 1000:1000. The host must have the ZFS kernel module loaded and the relevant pools imported. The container uses the host's /dev/zfs; it does not load modules or import pools.

Before starting the container:

  • Make zrepl.yml and any mounted credentials readable by UID 1000. Keep secrets restricted to that user rather than making them world-readable.
  • Allow the container user to open /dev/zfs for reading and writing. If the device is restricted to a host group, add its numeric GID with --group-add or Compose group_add. Do not make the device world-writable just for this container.
  • Delegate ZFS permissions to the host UID corresponding to container UID 1000. Without user-namespace remapping, this is host UID 1000. Check which host account owns that UID before granting access.

For a snapshot/send/prune job, the following is a starting permission set. Run it as a host administrator, replacing tank/source with a dataset selected by your zrepl configuration:

sudo zfs allow -u 1000 snapshot,send,destroy,hold,release,bookmark tank/source

By default, these permissions apply to the dataset and its descendants. destroy allows destructive operations, so delegate only on datasets this instance should manage. Jobs that set ZFS properties need the corresponding property permissions as well. Review the daemon logs for permission failures.

Ensure the host ZFS kernel module includes the fix for CVE-2026-79619 before exposing /dev/zfs to a user-namespace container. Updating the utilities inside the image does not fix the host kernel module.

Non-root operation and limitations

The examples expose only /dev/zfs, drop Linux capabilities, and do not use --privileged. ZFS access is controlled by host device permissions and zfs allow delegation. Configuration may also require network ports, credentials, or mounts for hooks; add these according to your jobs.

Receiving needs additional dataset-creation, receive, and property permissions. Linux does not support delegation of mounting and certain related operations. An unmounted backup target may avoid mounting, but receive and pruning behavior must be tested on a disposable dataset before using this setup for backups.

Running as a non-root user is not the same as running a rootless Docker or Podman engine. Rootless engines introduce UID/GID mapping, device-access, and ZFS namespace constraints. Full rootless-engine support has not been verified.

/var/run/zrepl and /home/tuxcrate are writable by the image's default user. If you override the user or mount over those directories, provide suitable ownership yourself. To revert delegation granted by the example above:

sudo zfs unallow -u 1000 snapshot,send,destroy,hold,release,bookmark tank/source

For workloads that still require root, overriding the image user with --user 0:0 (Compose user: "0:0") is a compatibility option. Device access and any required capabilities must be configured separately; changing the user alone does not provide them.

Published versions

Published releases are listed newest first, with all tags currently pointing to each image.

Stable

Image Tags App Version OS Published
0.7.0 Debian/13.7 2026-11-16 13:03
0.7.0 Debian/13.7 2026-11-09 13:13
0.7.0 Debian/13.7 2026-11-05 16:23
0.7.0 Debian/13.7 2026-11-02 12:47
0.7.0 Debian/13.7 2026-11-01 20:08
0.7.0 Debian/13.7 2026-11-01 17:43
0.7.0 Debian/13.7 2026-10-30 12:19
0.7.0 Debian/13.7 2026-10-30 12:11
0.7.0 Debian/13.7 2026-10-29 00:12
0.7.0 Debian/13.7 2026-10-28 06:09
0.7.0 Debian/13.7 2026-10-26 10:24
0.7.0 Debian/13.7 2026-10-25 19:01
0.7.0 Debian/13.7 2026-10-23 08:20
0.7.0 Debian/13.7 2026-10-23 08:12
0.7.0 Debian/13.7 2026-10-18 13:28
0.7.0 Debian/13.7 2026-10-18 13:12
0.7.0 Debian/13.7 2026-10-18 09:37
0.7.0 Debian/13.7 2026-10-18 08:39
0.7.0 — 2026-10-17 21:28
0.7.0 — 2026-10-17 15:27
0.7.0 — 2026-10-17 14:55
0.7.0 — 2026-10-17 14:33
0.7.0 — 2026-10-17 13:56
0.7.0 — 2026-10-17 13:32
0.7.0 — 2026-10-17 13:18

Usage

1
2
3
4
5
6
7
8
docker run \
  --rm \
  --name zrepl \
  --device /dev/zfs:/dev/zfs \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  --mount "type=bind,src=$PWD/zrepl.yml,dst=/etc/zrepl/zrepl.yml,readonly" \
  ghcr.io/tuxcrate/zrepl:0.7.0-r24
services:
  zrepl:
    image: ghcr.io/tuxcrate/zrepl:0.7.0-r24
    volumes:
    - ./zrepl.yml:/etc/zrepl/zrepl.yml:ro
    devices:
    - /dev/zfs:/dev/zfs
    cap_drop:
    - ALL
    security_opt:
    - no-new-privileges:true