zrepl on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of zrepl on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. zrepl is an open source ZFS snapshot management and replication daemon: it takes automatic, periodic snapshots of your ZFS datasets and replicates them between datasets and between machines with configurable pruning on both ends. It is a single self contained Go binary whose entire behaviour is defined by one plain text file, /etc/zrepl/zrepl.yml, so you describe the backup and replication policy you want rather than scripting zfs send and zfs receive by hand.

The image installs zrepl 0.7.0 from the official prebuilt release binary, pinned and verified by SHA-512, and runs it under systemd as the zrepl.service daemon. zrepl publishes Prometheus metrics on loopback port 9811 and is driven entirely from the CLI (zrepl status, zrepl signal) and the config file. There is no web interface and no login.

Functional out of the box. Because a fresh VM has no spare block device, the first boot of every VM creates a small file backed demo ZFS pool called tank with a source dataset tank/src and a sink dataset tank/sink, and configures a self contained local push job: tank/src is snapshotted on a schedule and replicated into tank/sink over zrepl's local transport, then pruned to policy. This lets you see a real snapshot to replicate to prune cycle on a single node immediately, and gives you a working template to point at your own datasets and remote machines.

Secure by default — no shipped credentials. zrepl's local transport needs no keys or passwords, so this image ships no shared or default credential of any kind. When you later replicate between machines you add your own TLS or SSH transport; until then there is nothing to rotate and nothing exposed. The metrics endpoint is bound to loopback only.

What is included:

• zrepl 0.7.0 from the official prebuilt release binary (SHA-512 verified), run under systemd as zrepl.service

• A file backed demo ZFS pool tank created on first boot, with a tank/src source dataset and a tank/sink replication target

• A ready to run local push job with automatic periodic snapshots (prefix zrepl_) and pruning policies on both sender and receiver

• A Prometheus metrics endpoint on loopback 127.0.0.1:9811

• The whole policy in one readable file, /etc/zrepl/zrepl.yml, that you version control and apply with a single systemctl restart zrepl

• zfsutils-linux and the matching kernel module, so ZFS and zrepl work on first boot with no extra setup

Prerequisites

• Active Azure subscription, SSH public key, VNet + subnet in target region

• Subscription to the zrepl listing on Azure Marketplace

• Network Security Group rules allowing TCP 22 (admin). No product ports need to be open to the internet for the single node demo; replication to a remote machine uses a transport you configure and open deliberately

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) is ample for managing snapshots and replicating modest datasets. ZFS benefits from RAM for its cache, so size up for large, busy pools.

Step 1: Deploy from the Azure Portal

1. Open the zrepl offer on the Azure Marketplace and choose Get It Now, then Create.
2. Select your subscription, resource group and region, and choose the Standard_B2s size.
3. Provide your SSH public key for the azureuser account.
4. Allow inbound TCP 22 from your admin network in the Network Security Group, then create the VM.

Step 2: Deploy from the Azure CLI

az vm create \
  --resource-group my-rg \
  --name zrepl-01 \
  --image <zrepl-marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Step 3: First boot

On the first boot of every VM, zrepl-firstboot.service loads the ZFS kernel module, creates the file backed demo pool tank with the tank/src and tank/sink datasets, writes a layout note to /root/zrepl-info.txt, and then zrepl.service starts. The push job immediately snapshots tank/src and replicates it into tank/sink. First boot completes in a few seconds; give the daemon a moment to run its first cycle before you inspect it.

Step 4: Confirm the daemon is running

SSH in as azureuser and confirm the service is active and report its version:

systemctl is-active zrepl.service
zrepl version

You should see active and the reported zrepl version.

Step 5: Inspect the demo pool and datasets

Look at the file backed demo pool and its two datasets:

zfs list -o name,used,avail,mountpoint
zpool status -x tank

tank/src is the source that gets snapshotted, and tank/sink receives the replicated snapshots. zpool status -x reports all pools are healthy when the demo pool is online.

Step 6: See automatic snapshots and replication

Trigger a replication cycle now (it also runs on its own schedule) and list the snapshots on both datasets:

zrepl signal wakeup demo_push
zfs list -t snapshot -r tank

You will see zrepl_-prefixed snapshots on the source tank/src and the same snapshots replicated to the sink under tank/sink/demo_local/tank/src. That is the full snapshot to replicate cycle running on a single node. For a live view of jobs, snapshots and replication progress, run zrepl status (an interactive terminal dashboard).

Step 7: Prometheus metrics

zrepl exports Prometheus metrics on loopback port 9811, including replication bytes, replication errors, last successful replication time and snapshot duration histograms:

curl -s http://127.0.0.1:9811/metrics | grep -E '^zrepl_' | awk 'NR<=8'

Scrape this endpoint from Prometheus (open TCP 9811 only to your monitoring network) to alert on replication failures or a stalled last-successful timestamp.

Step 8: Back up your own datasets

To snapshot and replicate your own data instead of the demo dataset, edit the filesystems filter of the demo_push job in /etc/zrepl/zrepl.yml to select your datasets, then apply the change. This example is illustrative — adapt the dataset paths to your pool:

# In /etc/zrepl/zrepl.yml, under the demo_push job, list your datasets:
#   filesystems:
#     "mypool/data<": true      # replicate mypool/data and all children
#     "mypool/data/tmp<": false  # ... except this subtree
# then apply:
sudo systemctl restart zrepl

Step 9: Replicate to a remote machine

Single node replication uses zrepl's local transport. To replicate to a second machine for real off host backups, run a sink job on the destination and change the source's connect block to a TLS or SSH transport pointing at it (see the zrepl documentation on transports and the source/sink job types). This is illustrative:

# On the DESTINATION host: run a zrepl `sink` job that serves a tls or ssh+stdinserver
# transport and receives into a backup dataset.
# On THIS host: change demo_push's connect: block from `type: local` to
#   connect:
#     type: tls           # or ssh+stdinserver
#     address: "<remote-host>:8888"
#     ... your certificate / ssh settings ...
# then apply:
sudo systemctl restart zrepl

Step 10: Review the layout note

A note describing the demo layout and handy commands is written on first boot:

sudo cat /root/zrepl-info.txt

Step 11: Security recommendations

• Keep the metrics port (9811) bound to loopback, or expose it only to your monitoring network via a tightly scoped NSG rule; it is not authenticated.
• When you replicate between machines, use zrepl's TLS transport (mutual certificate authentication) or an SSH transport, and open the chosen port only to the peer.
• The demo tank pool is file backed for convenience. For production, create a pool on dedicated data disks (attach Azure managed disks and zpool create on them) so snapshots have real capacity and redundancy.
• Keep the OS patched. The image ships fully updated and with unattended security upgrades enabled.

Step 12: Support and Licensing

zrepl is free and open source software distributed under the MIT License. This image bundles zrepl unmodified; your use of zrepl is governed by its license.

cloudimg images include 24/7 support. If you need help deploying or configuring zrepl on Azure, contact us.

Deploy on Azure

Find this image on the Azure Marketplace and deploy in minutes.

Need Help?

Email support@cloudimg.co.uk and our team will help you get up and running.