ucg-config-backup
Docker app from Tomjoad's Repository
Logs in to the local UniFi OS API of a UCG Ultra (or another UniFi OS console), and downloads the Network backup and the console's system backup on a cron schedule.
Overview
Readme
View on GitHubucg-config-backup Docker Container
A self-contained container that backs up the configuration of a Ubiquiti UniFi Cloud Gateway Ultra — or any other UniFi OS console (UDM, UDM-Pro, UDM-SE, Cloud Key Gen2+, ...) — on a timer, without needing the console to be connected to Ubiquiti's cloud.
Instead of relying on UniFi OS "Automated System Backups" (which only run when the console is cloud-connected and upload the backup off-site), this container calls the same local API the console's own Download Backup buttons use. It logs in with a local admin account and saves two files to a mounted volume:
- the system backup of the console (the one the UniFi OS settings offer
as "Backup for All Applications and Settings"), a
.unififile, and - the backup of the Network application (
cmd/backup), a.unffile. It is part of the system backup, and it is the file a self-hosted UniFi Network server can restore.
Built on linuxserver.io's Alpine base image, with the usual PUID, PGID,
UMASK and TZ settings.
Table of contents
- How it works
- Prerequisites on the UCG Ultra
- Supported architectures
- Version tags
- Usage
- Parameters
- Environment variables
- Webhook notifications
- Volumes / paths
- Upgrading
- Security notes
- Troubleshooting
- Support info
- Building locally and running the tests
- Changelog, security and license
How it works
On each run (scheduled via CRON_SCHEDULE, plus an optional immediate run
at container start via RUN_ON_START) the container:
- Logs in at
/api/auth/loginwith a local admin account (username + password, no cloud SSO, no 2FA) and captures the CSRF token. - Triggers a backup via the proxied Network API (
cmd/backup). - Downloads the returned one-time backup URL and saves it as
ucg-backup-<timestamp>.unfinto/backups. A download that turns out to be a web page, an error message or something far too small to be a backup (under 1 KiB) fails the run and is not kept. - Downloads the console's system backup (
/api/backup/download) and saves it asucg-system-backup-<timestamp>.unifi, with the same check. If the console refuses it, the run fails, and the Network backup from step 3 stays.SYSTEM_BACKUP=falseskips this step. - Logs out again, also when a step failed.
- Deletes local backups older than
RETENTION_DAYS(never the newest three of each kind, however old: if the console fails for weeks, the last good backups stay), and optionally posts a notification toWEBHOOK_URL.
Only one backup runs at a time: a run that starts while another one is
still going (the start-up run, a manual one) is skipped with a warning.
A run that takes longer than RUN_TIMEOUT (30 minutes by default) is
stopped, and when three runs in a row were skipped, a failed notification
goes to WEBHOOK_URL. Run a manual backup as root
(docker exec ucg-config-backup ucg-backup, without -u): the script
switches to PUID:PGID itself.
Prerequisites on the UCG Ultra
Create a dedicated local admin account for the backups (not a cloud/SSO account, and without two-factor authentication — both would block this simple login flow):
UniFi OS UI → Settings → Admins & Users → Invite Admin → enable
"Restrict to local access only" (or the equivalent for your firmware),
give it the Administrator role with full management rights on the
Network application (required for cmd/backup) and on the console itself
(required for the system backup), and do not enable 2FA for this
account.
Supported architectures
Simply pulling ghcr.io/tom-joad/ucg-config-backup:latest retrieves the
correct image for your architecture.
| Architecture | Available | Tag |
|---|---|---|
| x86-64 | yes | latest / <version> |
| arm64 | yes | latest / <version> |
Version tags
| Tag | Available | Description |
|---|---|---|
| latest | yes | The latest release, or the latest manual build (see below) |
| <version> | yes | A specific release, e.g. 2.2.0, or 2.2 for the latest patch of a minor |
| <sha> | yes | Immutable build of a specific commit |
Images are built from v* tags and, rarely, by a manual run of the build
workflow on main. A manual run also moves latest and publishes a sha-…
tag, so it can contain commits that aren't released yet. Images are signed with cosign (releases after 2.0.0 need a cosign 3.x client to
verify; 2.0.0 and older also verify with 2.x). To verify one:
cosign verify ghcr.io/tom-joad/ucg-config-backup:latest \
--certificate-identity-regexp 'https://github.com/Tom-Joad/ucg-config-backup/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
Usage
docker compose (recommended)
This repository ships a docker-compose.yml and an
.env.example. Copy .env.example to .env, fill in the
console login (and the webhook URL, if you use one), uncomment and change
any optional setting, then run docker compose up -d. .env keeps the
password out of the compose file. Without a value, PUID and PGID are
1000, UMASK is 022 and TZ is Etc/UTC.
services:
ucg-config-backup:
image: ghcr.io/tom-joad/ucg-config-backup:latest
container_name: ucg-config-backup
restart: unless-stopped
env_file:
- .env # UCG_HOST, UCG_USERNAME, UCG_PASSWORD, WEBHOOK_URL, optional settings
environment:
PUID: ${PUID:-1000}
PGID: ${PGID:-1000}
UMASK: ${UMASK:-022}
TZ: ${TZ:-Etc/UTC}
volumes:
- /path/to/backups:/backups
security_opt:
- no-new-privileges:true
docker cli
docker run -d \
--name=ucg-config-backup \
-e UCG_HOST=<CONSOLE-IP> \
-e UCG_USERNAME=backup-bot \
-e UCG_PASSWORD=change-me \
-e PUID=1000 \
-e PGID=1000 \
-e UMASK=022 \
-e TZ=Europe/Berlin \
-v /path/to/backups:/backups \
--security-opt no-new-privileges \
--restart unless-stopped \
ghcr.io/tom-joad/ucg-config-backup:latest
Unraid
Install it from Community Applications (search for
ucg-config-backup), or add the template by hand. Both ways, and how to
update an existing container, are in
unraid/README-UNRAID.md.
This container has no web UI and exposes no ports. It writes .unf and
.unifi files to /backups and reports in the container log.
Synology (Container Manager / Docker)
The image is hosted on GitHub Container Registry (ghcr.io), not Docker
Hub, so DSM's built-in registry search won't find it — you need to add the
registry first.
- Open Container Manager (DSM 7.2+) or Docker (older DSM) →
Registry → settings gear icon → Add, and add:
- Name: anything, e.g.
ghcr - URL:
https://ghcr.io
- Name: anything, e.g.
- Go to Registry, search for
tom-joad/ucg-config-backup, and download thelatesttag — or, if search doesn't surface it, use Image → Add → Add From URL withghcr.io/tom-joad/ucg-config-backup:latestdirectly. - Image → select the downloaded image → Run to open the container
wizard:
- Port Settings: none needed — this container exposes no ports.
- Volume: map a shared folder (e.g.
docker/ucg-config-backup/backups) to/backups. - Environment: add
UCG_HOST,UCG_USERNAME,UCG_PASSWORD,PUID,PGID(the ID of your DSM user, seeid <user>over SSH),TZ, and any optional variables below. - Enable Enable auto-restart.
- Start the container, then confirm via Container → Details →
Log that the first backup ran cleanly. Finished backup files appear
in the shared folder you mapped to
/backups.
You can also schedule DSM's own Hyper Backup or a Task Scheduler job to copy that shared folder off the NAS, so the UniFi config ends up in your existing 3-2-1 backup rotation.
Parameters
Container images are configured using parameters passed at runtime (such as those above). The usual linuxserver.io parameters apply:
| Parameter | Function |
|---|---|
-e PUID=1000 |
User ID the backup runs as, and the owner of the backup files |
-e PGID=1000 |
Group ID of the same |
-e UMASK=022 |
Umask of the backup files (002 lets the group write; 027 or 077 hide them from other users, see Security notes) |
-e TZ=Europe/Berlin |
Timezone for the schedule and log timestamps |
-v /backups |
The downloaded backup files (.unf and .unifi) |
Don't use --user or --init; the image runs s6-overlay as PID 1 and
drops to PUID:PGID itself. LSIO_NON_ROOT_USER is not supported either:
the schedule goes into root's crontab, so the container refuses to start
with it set.
Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
UCG_HOST |
yes | – | IP address or host name of the UCG Ultra, optionally with :port; no https:// and no path |
UCG_USERNAME |
yes | – | Local admin username (see Prerequisites) |
UCG_PASSWORD |
yes | – | Password for that account |
UCG_SITE |
default |
UniFi site name (letters, digits, - and _ only; anything else stops the container) |
|
SYSTEM_BACKUP |
true |
true or false: also save the console's system backup (all applications and settings) next to the Network backup |
|
VERIFY_SSL |
false |
true or false (any case; anything else stops the container): verify the console's TLS certificate (UniFi OS ships a self-signed cert by default) |
|
CRON_SCHEDULE |
0 3 * * * |
Cron expression for the backup run (five fields, each inside its range, separated by spaces or tabs; anything else stops the container with an ERROR: line) |
|
RETENTION_DAYS |
30 |
Delete local backups older than N days (0 = keep forever; anything but a whole number of 0 or more stops the container). The newest three backups of each kind are always kept |
|
UCG_CERT_SHA256 |
– | SHA-256 fingerprint of the console's TLS certificate (64 hex digits, colons optional, any case). When set, every connection must present exactly that certificate, whatever VERIFY_SSL says; a mismatch fails the run. See Pinning the console's certificate |
|
LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING or ERROR (any case; anything else stops the container). DEBUG adds the steps of a run (login, trigger, download). The starting line is always logged |
|
RUN_TIMEOUT |
1800 |
Seconds one run may take before it is stopped as stuck (a whole number, 1 or more) | |
LOCAL_BACKUP_DIR |
/backups |
Folder inside the container the backups are written to. Leave it alone and map the host folder to /backups; change it only if you must, then map your volume to the new path |
|
RUN_ON_START |
true |
true or false: run a backup immediately when the container starts |
|
NOTIFY_ON_SUCCESS |
false |
true or false: also send a webhook on success, not just on failure |
|
WEBHOOK_URL |
– | URL to POST run notifications to (e.g. ntfy.sh, Healthchecks.io, Home Assistant) — must start with http:// or https://; treat it as a secret, see Webhook notifications |
|
WEBHOOK_FORMAT |
text |
text for a plain-text body, json for structured fields (Home Assistant); anything else stops the container |
|
PUID / PGID |
911 |
User and group ID of the backup files, see Parameters | |
UMASK |
022 |
Umask of the backup files | |
TZ |
UTC |
Timezone for the schedule and log timestamps |
Webhook notifications
If WEBHOOK_URL is set, the container sends a POST after a failed run —
and after a successful one too with NOTIFY_ON_SUCCESS=true.
WEBHOOK_FORMAT picks the body:
text(default) —UCG backup OK: <filenames>orUCG backup FAILED: <error>as a plain-text body. Works with ntfy.sh and Healthchecks.io.json— anapplication/jsonbody with a fixed set of fields. Use this for Home Assistant: its webhook trigger only parses JSON and form bodies and silently drops a plain-text one.
{
"status": "ok",
"message": "ucg-backup-20261020-030014.unf, ucg-system-backup-20261020-030015.unifi",
"filename": "ucg-backup-20261020-030014.unf",
"size_bytes": 2410496,
"duration_s": 12.4,
"host": "192.168.1.1",
"site": "default",
"retention_days": 30,
"backups_kept": 30,
"system_filename": "ucg-system-backup-20261020-030015.unifi",
"system_size_bytes": 2731008,
"system_backups_kept": 30,
"timestamp": "2026-10-20T03:00:26+02:00",
"version": "2.2.0"
}
| Field | Description |
|---|---|
status |
Always ok or failed (lowercase) — the value to trigger on |
message |
Human-readable part: the filenames on success, the error on failure |
filename |
Name of the saved Network backup (.unf) |
size_bytes |
Size of that file — use it to catch empty or suspiciously small backups that still report ok |
duration_s |
Run duration in seconds |
host, site |
UCG_HOST and UCG_SITE of the run |
retention_days |
Effective RETENTION_DAYS |
backups_kept |
Number of ucg-backup-*.unf files in /backups after retention |
system_filename |
Name of the saved system backup (.unifi); null with SYSTEM_BACKUP=false |
system_size_bytes |
Size of that file |
system_backups_kept |
Number of ucg-system-backup-* files in /backups after retention |
timestamp |
ISO 8601 with the offset of TZ |
version |
Container version |
Every key is always present; values that aren't known (e.g. filename
when the login failed) are null.
A failing webhook never fails the backup run: connection errors and
5xx answers are retried twice (after 2 s and 5 s), then the run carries
on. Logs only ever show the scheme and host of WEBHOOK_URL, since its
path usually is the secret (HA webhook id, ntfy topic, Healthchecks UUID).
Home Assistant
Set WEBHOOK_FORMAT=json and point WEBHOOK_URL at a webhook trigger,
e.g. http://homeassistant.local:8123/api/webhook/ucg-backup-change-me.
This automation pushes a notification whenever a run fails:
automation:
- alias: "UCG backup failed"
triggers:
- trigger: webhook
webhook_id: ucg-backup-change-me
allowed_methods: [POST]
local_only: true
conditions:
- condition: template
value_template: "{{ trigger.json.status == 'failed' }}"
actions:
- action: notify.notify
data:
title: "UCG backup failed"
message: "{{ trigger.json.message }}"
With NOTIFY_ON_SUCCESS=true every run reports in, so Home Assistant can
also track trigger.json.timestamp as a heartbeat and warn on an unusual
size_bytes. Pick a long random webhook id — anyone who knows it can
trigger the automation.
Volumes / paths
| Path | Contents |
|---|---|
/backups |
Downloaded backup files, named ucg-backup-<timestamp>.unf (Network application) and ucg-system-backup-<timestamp>.unifi (whole console), owned by PUID:PGID |
/backups is the only volume; the container keeps no other state. Its
crontab is rebuilt from CRON_SCHEDULE at every start. If the host folder
for /backups doesn't exist yet or belongs to root, the container hands
it to PUID:PGID at start (not recursively); a folder that already
belongs to someone else is left alone.
Upgrading
- From 2.2.x: every run now also saves the console's system backup,
so
/backupsholds two files per run. If the log showsSystem backup download rejected, give the backup account full rights on the console, or setSYSTEM_BACKUP=falseto keep the old behaviour. The webhook's JSON body has three new fields; the existing ones are unchanged. - From 2.1.x: the
/configvolume is no longer used. Remove the mapping (Unraid: the Config Directory path) and delete the folder on the host when you like; leaving it mapped does no harm. - From 1.x: see the 2.0.0 entry in the changelog: set
PUID/PGID(andUMASK), and hand existing root-owned backups over once, e.g.chown -R 99:100 /mnt/user/appdata/ucg-config-backup/backups.
Security notes
- Credentials are passed as environment variables. As in every
linuxserver.io image, s6-overlay keeps a copy of the container
environment in
/run/s6/container_environmentinside the container, so the password does sit in the container's file system (on the Docker host's disk) while the container exists. It is never built into the image, never written to/backups, and never logged. Anyone with root on the Docker host ordocker execaccess can read it — as they could withdocker inspectanyway. - The backup runs as the unprivileged
abcuser (PUID:PGID), not as root. Only the cron daemon itself and the start-up scripts run as root. VERIFY_SSL=falseis the default because UniFi OS consoles ship a self-signed certificate. The login then goes over TLS without checking who answers, so someone in your LAN who can intercept the traffic could capture the password. If you've installed a trusted certificate on the console, setVERIFY_SSL=true.UCG_CERT_SHA256pins the console's certificate and closes that gap, see Pinning the console's certificate. The pin replaces the certificate-authority and host-name checks: a certificate renewed on the console needs the new fingerprint here.- Use a dedicated local admin account scoped to what backups need — don't reuse your primary login.
- The backup files hold the console's whole configuration. With the
default
UMASK=022every user on the Docker host can read them. SetUMASK=027(owner and group) orUMASK=077(owner only) to close that, and keep/backupsreadable only by the users who need it. A backup that was written before can be tightened withchmod.
Troubleshooting
Login rejected (401)— wrong username/password, or the account is a cloud/SSO account rather than a local one.No CSRF token received after login— usually means 2FA is enabled on the account; this flow doesn't support 2FA. Use a dedicated account without it.403on thecmd/backupcall (login succeeded) — most often insufficient permissions: the account needs full Administrator / Full Management rights on the Network application, not "Limited Admin" or "View Only". Raise its role under Admins & Users. Less commonly it's a rotating CSRF token between login and the backup call — the script automatically adopts anx-updated-csrf-tokenfrom UniFi OS if present, and a403is retried once after a fresh login before the run fails.System backup download rejected (401/403/404)— the console didn't hand out its system backup.401/403: the account lacks rights on the console itself (see Prerequisites).404: this UniFi OS version doesn't have the download. The Network backup of the run is saved either way;SYSTEM_BACKUP=falseturns the system backup off.Unexpected backup response, no download URL— the API response shape can differ slightly between firmware versions; check the log (docker logs ucg-config-backup) and verifyUCG_SITE(the site name isdefaultunless you renamed it). The console's answer itself is not logged.Download is only N bytes/Download is plain text— the console answered with an error text instead of a backup. It is not kept and doesn't count towards the retention. Check the account's rights and run it again.The run took longer than RUN_TIMEOUT— the console or the network stalled. The run was stopped, the next scheduled one starts normally.Download returned text/html instead of a backup file— the console answered the download with a web page, usually because the session ended or the firmware changed the download path. Run it again; if it stays, open an issue with the log lines.run_skipped(a backup is already running) — a scheduled or manual run started while another one was still going. Nothing to do.The console's certificate does not match UCG_CERT_SHA256— the console presents another certificate than the pinned one. If you renewed or replaced it, copy the new fingerprint from the message (or theconsole_certificatelog line) intoUCG_CERT_SHA256; if you did not, someone else may be answering at that address.
Pinning the console's certificate
UniFi OS consoles ship a self-signed certificate, so VERIFY_SSL=true only
works once you have installed a trusted one. Instead, you can pin the
console's own certificate: set UCG_CERT_SHA256 to its SHA-256
fingerprint, and the run fails unless the console presents exactly that
certificate. It works independently of VERIFY_SSL (a self-signed
console with a pin is the intended use), and the login only goes out after
the check.
Get the fingerprint from the log: every run logs a console_certificate
line with the sha256 the console presents (check it is really your
console, for example in the browser's certificate details, before you pin
it), or ask openssl:
openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null \
| openssl x509 -noout -fingerprint -sha256
Colons and case don't matter: AB:CD:... and abcd... are the same. A
value that is not 64 hex digits stops the container at start with an
ERROR: line. The pin has to be updated when the console's certificate is
renewed or replaced.
Logging
Everything goes to the container log (docker logs ucg-config-backup),
one JSON object per line, as in the other containers of this family:
{"ts":"2026-11-13T03:00:00.123+01:00","level":"INFO","event":"backup_saved","file":"ucg-backup-20261113-030000.unf","size_bytes":123456}
ts is local time (the container's TZ) with milliseconds and offset
(Z for UTC), event a short stable name, the other keys depend on the
event. The first line of every run is starting with the version and the
settings in use (never the password; the webhook URL only as set or
off). Failures are level ERROR with the reason in error: run_failed
for a failed run, config_invalid for a wrong setting. LOG_LEVEL filters.
The container's start-up (settings check, schedule, the base image's
banner) is plain text before the first run.
Support info
- Shell access while the container is running:
docker exec -it ucg-config-backup /bin/bash - Follow the logs in realtime:
docker logs -f ucg-config-backup - Trigger an on-demand backup without waiting for the schedule:
docker exec ucg-config-backup ucg-backup - The version:
docker exec ucg-config-backup cat /build_version
Building locally and running the tests
git clone https://github.com/Tom-Joad/ucg-config-backup.git
cd ucg-config-backup
docker build --pull -t ucg-config-backup:test .
# Unit tests (Python 3.14, like the image)
pip install -r requirements.txt pytest
pytest -q
# Smoke test of the built image (needs Docker, no console)
tests/smoke.sh ucg-config-backup:test
Changelog, security and license
- CHANGELOG.md — what changed in each release
- SECURITY.md — how to report a vulnerability, and how to verify an image
- MIT
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/tom-joad/ucg-config-backup:latestRuntime arguments
- Network
bridge- Shell
bash- Privileged
- false
- Extra Params
--security-opt no-new-privileges
Template configuration
Where the backup files (.unf and .unifi) are stored
- Target
- /backups
- Default
- /mnt/user/appdata/ucg-config-backup/backups
User that owns the backups (nobody)
- Default
- 99
Group for the backups (users)
- Default
- 100
002: new files are writable for the users group, e.g. over SMB
- Default
- 002
IP address or host name of the UCG Ultra / UniFi OS console
Local admin user dedicated to backups (no cloud/SSO account, no 2FA)
Password of that user
UniFi site name
- Default
- default
Also save the console's system backup (all applications and settings); false = Network backup only
- Default
- true
Check the console's TLS certificate (UniFi OS ships a self-signed one)
- Default
- false
When the backup runs (cron: minute hour day month weekday)
- Default
- 0 3 * * *
Delete local backups older than N days (0 = keep everything)
- Default
- 30
Seconds one run may take before it is stopped as stuck
- Default
- 1800
Optional: SHA-256 fingerprint of the console's TLS certificate (colons optional). When set, only that certificate is accepted, whatever VERIFY_SSL says. The log shows the console's fingerprint
DEBUG, INFO, WARNING or ERROR
- Default
- INFO
Run a backup right after the container starts
- Default
- true
Also notify the webhook on success, not only on failure
- Default
- false
Optional: URL for POST notifications (ntfy.sh, Healthchecks.io, Home Assistant webhook). Usually contains a secret
text (plain text, ntfy.sh/Healthchecks.io) or json (structured fields, Home Assistant)
- Default
- text