Security

Borg UI controls backup and restore operations. Treat it as sensitive infrastructure.

This page is about hardening your deployment. For what the software itself stores, encrypts, and sends anywhere else, see What Borg UI Does With Your Data.

First Steps

After installation:

1. Change the default admin password in Settings > Account.
2. Use a strong INITIAL_ADMIN_PASSWORD for new deployments.
3. Keep /data private and backed up.
4. Put the app behind TLS if it is reachable over a network.
5. Keep Borg UI updated.

Protect /data

The /data volume contains:

• SQLite database
• generated secret key
• logs
• encrypted SSH key material
• job metadata

Anyone who can read or modify /data can affect the Borg UI instance.

Docker Socket

Mounting /var/run/docker.sock gives the Borg UI container control over the host Docker daemon.

Only mount it if Docker hook scripts need it:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:rw

Do not mount it for normal backups. If hook scripts only need limited Docker container actions, prefer a Docker socket proxy and set Borg UI's Docker CLI endpoint with DOCKER_HOST=tcp://docker-socket-proxy:2375.

Authentication Modes

Recommended order:

1. Built-in local auth for small/self-hosted deployments.
2. Built-in OIDC for SSO.
3. Trusted-header auth only behind a locked-down reverse proxy.

Never expose trusted-header auth directly to users.

OIDC

Use built-in OIDC when Borg UI should talk directly to the identity provider.

Keep frontend and API on the same public origin. Split-origin setups need explicit CORS/cookie work and are not the default supported path.

See Authentication and SSO for setup details.

Trusted-Header Auth

Trusted-header auth reads identity from proxy-set headers.

Safe only when:

• the Borg UI container is not directly reachable
• the proxy strips incoming user-controlled auth headers
• only the proxy can set the trusted headers

If direct access is possible, a user can spoof headers and impersonate another user.

See Authentication and SSO for header settings.

Metrics

The /metrics endpoint should be private or token-protected.

Recommended:

• enable metrics only when needed
• require a token
• let Prometheus scrape it over a private network
• expose Grafana, not /metrics, to users

Remote SSH Access

Use Remote Machines and SSH keys instead of passwords.

For remote backup users:

• use a dedicated Unix user
• grant only required filesystem access
• restrict Borg keys with borg serve --restrict-to-path where practical
• rotate keys when access changes

Repository Locks

Breaking a Borg lock while another Borg process is active can corrupt or damage a repository.

Before breaking a lock, confirm there is no:

• running backup
• restore
• check
• prune
• compact
• mount
• external Borg process

Password Reset

If an admin is locked out and you have shell access to the container:

docker exec -it borg-web-ui python -m app.scripts.reset_password admin newpassword123

Shell access to the container is equivalent to administrative access.

Reverse Proxy Checklist

• terminate TLS at the proxy
• forward Host, X-Forwarded-For, and X-Forwarded-Proto
• support WebSocket/SSE-style long-running connections
• do not expose trusted-header auth directly
• register OIDC callback URLs using the public URL users actually open

See Reverse Proxy.

Updates

Update with:

docker compose pull
docker compose up -d

Keep /data and Borg repository backups before major upgrades.