OCI LXC Backup in Proxmox VE 9.1: vzdump Restore Guide

OCI LXC containers in Proxmox VE 9.1 back up and restore through the same vzdump and vzrestore paths as any other LXC, but the OCI image layer and the Docker or K3s state inside the writable layer introduce two specific failure modes you need to plan around. By the end of this guide you will have a repeatable backup job that captures a running OCI LXC with Docker containers intact, and a restore procedure that brings the workload back on the same or a different node in under 90 seconds on a ZFS-backed setup.

Key Takeaways

Storage matters: Snapshot-mode backups require ZFS or LVM-thin; directory storage forces a slower stop or suspend mode that can leave Docker volumes in an inconsistent state.
Image reference: The OCI image reference stored in the container config must be resolvable at restore time, or the image must already be cached on the target node.
Quiesce first: Running docker stop on all containers inside the LXC before the snapshot eliminates the most common cause of corrupted Docker volumes after restore.
K3s etcd: If you run K3s with built-in etcd, stop the K3s service before the snapshot to avoid a journal replay on first boot after restore.

How OCI LXC Containers Store Data

Proxmox VE 9.1 creates LXC containers from OCI images pulled from a registry. The resulting container has a layered filesystem: the read-only OCI image layers at the bottom, and a writable upper layer where all runtime changes accumulate. When you run Docker or K3s inside that container, their data lands in the writable layer:

Path	Contents	Typical size (3-month workload)
`/var/lib/docker/`	Images, containers, volumes, network config	2–18 GB
`/var/lib/rancher/k3s/`	K3s data, etcd, manifests, certs	1–4 GB
`/etc/`	Modified system config	< 50 MB
`/opt/`	Application code, scripts	100 MB – 2 GB

The OCI image itself is cached on the node under the local OCI image store. A backup of the container captures the full root filesystem (image layers + writable layer), so a container built from a 1.2 GB base image with 4 GB of Docker data will produce a backup in the 5–6 GB range before compression.

If you followed the Docker Compose setup on OCI LXC guide, your compose files and volume data are all inside that writable layer and will be captured by a container-level backup.

How to Back Up an OCI LXC Container

Prerequisites

Proxmox VE 9.1 or later
Container stored on ZFS or LVM-thin (for snapshot mode)
A backup target: local storage or a Proxmox Backup Server

Create a one-off backup with vzdump

vzdump 100 --mode snapshot --storage local-zfs --notes "pre-migration backup"

The --mode snapshot flag tells Proxmox to take a ZFS or LVM-thin snapshot of the container's dataset, copy it to the backup storage, then discard the snapshot. On a ZFS pool with a 1 GB/s write path, a 5 GB container backup completes in roughly 40–60 seconds. The container stays running the entire time.

If your container is on directory storage (the local storage type), snapshot mode is unavailable. You must use:

vzdump 100 --mode stop --storage local

This stops the container, copies the files, and starts it again. Downtime is proportional to the container size—plan for 2–5 minutes on a 5 GB container over NVMe.

Schedule a recurring backup job

In the web UI: Datacenter → Backup → Add. Set:

Storage: your PBS storage name (e.g., pbs1)
Mode: snapshot
Schedule: 0 3 * * * (daily at 03:00)
Containers: select your OCI LXC VMID
Prune: keep-last 7d, keep-weekly 4w, keep-monthly 12m

If you are already running PBS with S3 offsite, make sure your PBS 4.2 S3 backup pre-flight checklist is satisfied before pointing the job at the S3-backed PBS instance.

Verify the backup

# List recent backups for VM 100
pvesm backup pbs1 /100

# Check the backup metadata (size, timestamp, status)
pvesm backup pbs1 /100 --verify

A successful backup will show status: OK and a file size matching your expectations. If the size is dramatically smaller than the container's actual disk usage, the backup may have captured only the image layer and missed the writable layer—check that the container was running (not just created) when the backup fired.

How to Restore an OCI LXC Container

Restore to the same node

# Identify the backup file
pvesm backup pbs1 /100

# Restore to the same VMID (container must be stopped)
pct stop 100
vzrestore 100 /var/lib/vz/dump/vzdump-100-2026_02_10-03_00_00.tar.gz 100

The restore writes the full root filesystem back to the container's storage location. On ZFS, this is a dataset clone plus a sync—typically 30–60 seconds for a 5 GB container.

Restore to a different node

This is the scenario that trips people up. The target node must be able to resolve the OCI image reference, or the image must already be cached locally.

# On the target node, verify the image is available
pct list-oci-images registry.local:5000

# If not cached, pull it first
pct pull-oci-image registry.local:5000/myapp:2.4.1

# Then restore (use a new VMID if the old one doesn't exist on this node)
vzrestore 100 /path/to/backup.tar.gz 100

If you skip the pull step and the image isn't cached, the container will start but the read-only layers will be empty, causing exec format error or missing binaries in Docker containers.

Restore with a new VMID

vzrestore 100 /path/to/backup.tar.gz 200

The restored container gets VMID 200. You will need to update its network configuration (IP, bridge) in the web UI or via pct set 200 --ipconfig0 ip=10.0.1.50/24,gw=10.0.1.1.

Protecting Docker Workloads During Backup

This is where most backup failures originate. A ZFS snapshot is consistent at the filesystem level, but Docker has its own in-memory state: the daemon's container state, overlay2 layer metadata, and volume mount tracking. If you snapshot while Docker is actively writing to a volume, the filesystem snapshot is technically consistent, but Docker's internal state may not match what's on disk after restore.

The quiesce-then-snapshot pattern

Add a small script to the container that stops all Docker containers before the backup and restarts them after:

#!/bin/bash
# /usr/local/bin/docker-quiesce.sh - run inside the OCI LXC

docker stop $(docker ps -q) 2>/dev/null
docker system prune -f --volumes=false 2>/dev/null

Wire it into the backup job using Proxmox's --pre-script and --post-script (available in the backup job configuration):

# Pre-script (runs on the node, exec into the container)
pct exec 100 -- /usr/local/bin/docker-quiesce.sh

# Post-script
pct exec 100 -- bash -c 'docker start $(docker ps -aq --filter status=exited)'

In the web UI backup job, paste these into the Pre-Script and Post-Script fields. The total added downtime is 3–8 seconds depending on how many containers are running.

The honest tradeoff

Quiescing Docker means your services are briefly unavailable during every backup window. If you run a public-facing service inside the OCI LXC, a daily 03:00 backup with a 5-second Docker stop is usually acceptable. But if you need zero-downtime backups, you have two options:

Use Docker named volumes on a ZFS dataset mounted into the container. The snapshot captures the volume dataset independently, and you can restore the volume without stopping Docker.
Accept the risk: in practice, overlay2 is a copy-on-write filesystem, so a mid-write snapshot rarely corrupts a volume. The failure mode is a container that was mid-docker build or mid-docker push—the layer metadata may be incomplete, and Docker will report a "corrupt layer" on first start after restore.

Protecting K3s Workloads During Backup

K3s with built-in etcd is more fragile than Docker. The etcd WAL (write-ahead log) and snapshot files must be consistent, or K3s will attempt a journal replay on first boot after restore. A replay of a partially-written WAL can leave the cluster in a NotReady state for 10–30 seconds, or in rare cases require a manual etcdctl repair.

Recommended approach

# Inside the OCI LXC, before the snapshot:
systemctl stop k3s

# After restore, on first boot:
systemctl start k3s

If you run K3s in a multi-node configuration (agent nodes), stop the server node first, then the agents. The agents will reconnect automatically once the server is back.

K3s with external etcd

If you run K3s with an external etcd cluster (separate VM or service), the etcd data is not in the LXC container's filesystem. Your container backup captures the K3s control plane and agent state, but you must back up etcd separately using etcdctl snapshot save. The LXC seccomp profile guide covers the syscalls K3s and etcd need if you are running them in a restricted container.

Troubleshooting Common Restore Failures

"OCI image not found" on restore

The target node doesn't have the image cached. Fix:

pct pull-oci-image <image-reference-from-config>

You can find the image reference in the container's config:

pct config 100 | grep oci-image

Docker reports "overlay2: can't mount" after restore

The overlay2 metadata was captured mid-operation. Fix inside the restored container:

docker system df
docker rm -f $(docker ps -aq --filter status=created)
docker volume prune -f

If that doesn't resolve it, the nuclear option is to delete /var/lib/docker/overlay2 and re-pull your images. Your named volumes (in /var/lib/docker/volumes/) survive this.

Container starts but has no network

The restored container's IP config references a bridge or VLAN that doesn't exist on the target node. Check:

pct config 100 | grep -E "net0|ipconfig"

Then fix with:

pct set 100 --net0 name=eth0,bridge=vmbr1,ip=dhcp
pct restart 100

Backup is 3× larger than expected

The container's Docker image cache has bloated. Before the next backup:

pct exec 100 -- docker system prune -a --volumes=false

This removes dangling images and build cache. A container that was 6 GB can drop to 2.5 GB after pruning, cutting your backup window and PBS storage usage proportionally.

Sizing Your Backup Storage

As a rough planning figure: an OCI LXC running Docker Compose with 5–8 services and a 2 GB image cache produces backups in the 3–5 GB range per run. With PBS deduplication (which works well on LXC backups because the image layers are identical across runs), the incremental size after the first full backup typically drops to 200–800 MB per run. Over 30 days with daily backups, expect 3–8 GB of additional PBS storage for a single container.

If you are running multiple OCI LXC containers on the same node (for example, one for your edge stack and another for a K3s cluster), PBS deduplication across containers with the same base image will save significant space—identical image layers are stored only once in the PBS repository.

Conclusion

Backups of OCI LXC containers in Proxmox VE 9.1 use the standard vzdump/vzrestore toolchain, but the two things that will save you from a 2 AM restore are: (1) running on snapshot-capable storage so you can quiesce Docker in 5 seconds instead of stopping the whole container, and (2) verifying that the OCI image reference is resolvable on any node you might restore to. Your next step is to run a test restore of your most critical OCI LXC to a scratch VMID, boot it, and confirm that every Docker container and K3s pod comes up clean before you trust the backup job with production data.