ucg-config-backup

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
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. The console needs no cloud connection. Old backups are deleted after RETENTION_DAYS; failures (and optionally successes) can be sent to a webhook. Progress is in the container log.

ucg-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 .unifi file, and
  • the backup of the Network application (cmd/backup), a .unf file. 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

On each run (scheduled via CRON_SCHEDULE, plus an optional immediate run at container start via RUN_ON_START) the container:

  1. Logs in at /api/auth/login with a local admin account (username + password, no cloud SSO, no 2FA) and captures the CSRF token.
  2. Triggers a backup via the proxied Network API (cmd/backup).
  3. Downloads the returned one-time backup URL and saves it as ucg-backup-<timestamp>.unf into /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.
  4. Downloads the console's system backup (/api/backup/download) and saves it as ucg-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=false skips this step.
  5. Logs out again, also when a step failed.
  6. 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 to WEBHOOK_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.

  1. 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
  2. Go to Registry, search for tom-joad/ucg-config-backup, and download the latest tag — or, if search doesn't surface it, use Image → Add → Add From URL with ghcr.io/tom-joad/ucg-config-backup:latest directly.
  3. 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, see id <user> over SSH), TZ, and any optional variables below.
    • Enable Enable auto-restart.
  4. 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> or UCG backup FAILED: <error> as a plain-text body. Works with ntfy.sh and Healthchecks.io.
  • json — an application/json body 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 /backups holds two files per run. If the log shows System backup download rejected, give the backup account full rights on the console, or set SYSTEM_BACKUP=false to keep the old behaviour. The webhook's JSON body has three new fields; the existing ones are unchanged.
  • From 2.1.x: the /config volume 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 (and UMASK), 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_environment inside 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 or docker exec access can read it — as they could with docker inspect anyway.
  • The backup runs as the unprivileged abc user (PUID:PGID), not as root. Only the cron daemon itself and the start-up scripts run as root.
  • VERIFY_SSL=false is 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, set VERIFY_SSL=true.
  • UCG_CERT_SHA256 pins 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=022 every user on the Docker host can read them. Set UMASK=027 (owner and group) or UMASK=077 (owner only) to close that, and keep /backups readable only by the users who need it. A backup that was written before can be tightened with chmod.

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.
  • 403 on the cmd/backup call (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 an x-updated-csrf-token from UniFi OS if present, and a 403 is 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=false turns 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 verify UCG_SITE (the site name is default unless 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 the console_certificate log line) into UCG_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

Categories

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/tom-joad/ucg-config-backup:latest
Last Updated2026-11-22
First Seen2026-10-05

Runtime arguments

Network
bridge
Shell
bash
Privileged
false
Extra Params
--security-opt no-new-privileges

Template configuration

Backup DirectoryPathrw

Where the backup files (.unf and .unifi) are stored

Target
/backups
Default
/mnt/user/appdata/ucg-config-backup/backups
PUIDVariable

User that owns the backups (nobody)

Default
99
PGIDVariable

Group for the backups (users)

Default
100
UMASKVariable

002: new files are writable for the users group, e.g. over SMB

Default
002
UCG_HOSTVariable

IP address or host name of the UCG Ultra / UniFi OS console

UCG_USERNAMEVariable

Local admin user dedicated to backups (no cloud/SSO account, no 2FA)

UCG_PASSWORDVariable

Password of that user

UCG_SITEVariable

UniFi site name

Default
default
SYSTEM_BACKUPVariable

Also save the console's system backup (all applications and settings); false = Network backup only

Default
true
VERIFY_SSLVariable

Check the console's TLS certificate (UniFi OS ships a self-signed one)

Default
false
CRON_SCHEDULEVariable

When the backup runs (cron: minute hour day month weekday)

Default
0 3 * * *
RETENTION_DAYSVariable

Delete local backups older than N days (0 = keep everything)

Default
30
RUN_TIMEOUTVariable

Seconds one run may take before it is stopped as stuck

Default
1800
UCG_CERT_SHA256Variable

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

LOG_LEVELVariable

DEBUG, INFO, WARNING or ERROR

Default
INFO
RUN_ON_STARTVariable

Run a backup right after the container starts

Default
true
NOTIFY_ON_SUCCESSVariable

Also notify the webhook on success, not only on failure

Default
false
WEBHOOK_URLVariable

Optional: URL for POST notifications (ntfy.sh, Healthchecks.io, Home Assistant webhook). Usually contains a secret

WEBHOOK_FORMATVariable

text (plain text, ntfy.sh/Healthchecks.io) or json (structured fields, Home Assistant)

Default
text