Borgmatic Director UI for professionals

Borgmatic Director UI - Professional Administration Guide

This guide is intended for system administrators and IT professionals who need comprehensive knowledge of the Borgmatic Director UI application, its operating modes, configuration options, and administrative features.

Operating Modes

Borgmatic Director UI supports three operating modes for different deployment scenarios. Understanding these modes is essential for proper deployment planning.

Mode Comparison Matrix

Feature	Standalone	Client	Director
Manage local backups	✅	✅	✅ (via client proxy)
Full local web UI	✅	✅	✅
Connect to Director	❌	✅	❌
Manage multiple machines	❌	❌	✅
Approve client connections	❌	❌	✅
Deploy templates to clients	❌	❌	✅
Aggregate monitoring dashboard	❌	❌	✅
Receive remote commands	❌	✅	❌

1. Standalone Mode (Default)

Standalone mode is the default operating mode. The instance operates independently, managing backups on a single server with no external connections.

Use Cases

Single server deployments
Home labs and personal servers
Small businesses with one backup server
Testing and development environments
Air-gapped or isolated systems

Configuration

No additional configuration required. This is the default state after installation.

# Identity configuration file: /app/data/config/identity.json
{
  "mode": "standalone",
  "instance_id": "auto-generated-uuid",
  "instance_name": "My Backup Server"
}

Available Features

Full backup job management (create, edit, delete, run)
Repository management (local, SSH, S3, Rclone)
Archive browsing and restore
Schedule management
SSH key management
YAML configuration editor
Real-time backup monitoring
Notifications (email, webhooks, etc.)

2. Client Mode

Client mode allows the instance to be remotely managed by a central Director server while retaining full local functionality.

Use Cases

Multiple servers managed by a central IT team
Distributed infrastructure requiring unified management
Managed Service Provider (MSP) client deployments
Branch offices connected to headquarters

Configuration Steps

Navigate to Settings → Operating Mode
Click the toggle to switch from Standalone to Client mode
Configure connection settings:
- Client Name: Human-readable identifier (e.g., "Production Web Server")
- Identification Phrase: Secret phrase shown to Director admin for verification
- Director URL: WebSocket URL (e.g., wss://director.example.com)
- Director Port: Default is 9000
Save and initiate connection
Wait for Director admin to approve the connection request

Authentication Security

Client authentication uses Ed25519 cryptographic keypairs:

Keypair Generation: Client generates Ed25519 keypair on first setup
Registration: Client sends public key + identification phrase to Director
Approval: Director admin verifies phrase and approves connection
Challenge-Response: All subsequent connections authenticated via cryptographic challenge

Authentication Flow:
1. Client → Director: "Register me" + public key + phrase
2. Director Admin: Reviews request, verifies phrase
3. Director Admin: Clicks Approve (optionally locks IP)
4. Director → Client: Issues signed JWT token
5. Future connections:
   - Director: "Sign this random challenge: XYZ123"
   - Client: Signs with private key
   - Director: Verifies signature with stored public key
   - Connection established ✅

Connection Status Indicators

Status	Indicator	Meaning
Connected	🟢 Green	Active connection to Director
Pending	🟡 Yellow	Awaiting Director approval
Disconnected	🔴 Red	No connection (network issue or Director offline)
Rejected	⛔ Blocked	Connection rejected by Director admin

Client Mode Features

All Standalone features remain available
Receives template deployments from Director
Reports status and backup results to Director
Can be monitored remotely via Director dashboard
Automatic reconnection with exponential backoff

3. Director Mode

Director mode transforms the instance into a central management hub that can monitor and control multiple Client instances.

Use Cases

Enterprise IT managing multiple servers
Managed Service Providers (MSPs)
DevOps teams managing infrastructure fleets
Organizations requiring centralized backup oversight

Configuration Steps

Navigate to Settings → Operating Mode
Click "Switch to Director Mode"
Type "switch" to confirm (this is a significant change)
Configure Director settings:
- Listen Port: WebSocket port for client connections (default: 9000)
- SSL/TLS: Enable for production (recommended)
- Auto-Approve: Automatically approve new clients (not recommended)
Restart the server if prompted

Note: Switching to Director mode enables HTTPS and may require server restart. Switching back to Standalone clears all client data.

Network Requirements

┌─────────────────┐     WSS (port 9000)      ┌──────────────────┐
│   Client 1      │ ─────────────────────────>│                  │
│   (behind NAT)  │  outbound connection      │     Director     │
└─────────────────┘                           │                  │
                                              │  Public IP or    │
┌─────────────────┐     WSS (port 9000)       │  Domain name     │
│   Client 2      │ ─────────────────────────>│                  │
│   (firewall)    │  outbound connection      │  Port 9000 open  │
└─────────────────┘                           └──────────────────┘

Director needs a public IP or domain name
Director port 9000 (or configured port) must be accessible
Clients initiate outbound connections (NAT-friendly)
No port forwarding required on client machines
Can use CloudFlare Tunnel or reverse proxy if Director is also behind NAT

Client Management Dashboard

The Director dashboard provides:

Connected Clients: Real-time list of online clients with status
Pending Approvals: New clients awaiting approval
Offline Clients: Previously connected clients that are currently unreachable
Aggregate Statistics: Total backups, repositories, success/failure rates

Client Approval Workflow

New client connects and appears in "Pending Approvals"
Admin reviews:
- Client name
- Identification phrase (verify this matches expected)
- IP address
- Public key fingerprint
Admin decides:
- Approve: Client can connect and be managed
- Approve + Lock IP: Only allow connections from current IP
- Reject: Deny connection permanently

Managing Remote Clients

When in Director mode, a client selector appears in the navigation:

Select a client to view/manage that client's backups, repositories, etc.
All pages (Backups, Repositories, Archives, etc.) show data from selected client
Actions performed affect the selected client
"View All Clients" returns to the aggregate dashboard

Template Deployment

Directors can create and deploy templates to multiple clients:

Backup Templates: Pre-configured backup job definitions
Schedule Templates: Standardized backup schedules
Repository Templates: Common repository configurations

Deployment options:

Deploy to selected clients
Deploy to client groups
Deployed items are created as inactive for security (must be activated locally)

Mode Switching Reference

From	To	Data Impact	Action Required
Standalone	Client	None (non-destructive)	Toggle switch + configure Director URL
Client	Standalone	None (non-destructive)	Toggle switch
Standalone/Client	Director	Enables HTTPS, adds Director features	Type "switch" to confirm + restart
Director	Standalone	Clears all client connection data	Type "switch" to confirm

Dashboard

The Dashboard provides an at-a-glance overview of backup system health and recent activity.

Dashboard Widgets

System Status

Backup Tools Health: Shows installed status and versions of Borg 1.x, Borg 2.x, Borgmatic, and Rclone
Last Health Check: Timestamp of most recent tool verification

Backup Statistics

Total backup jobs configured
Active vs. inactive backups
Last 24-hour success/failure count
Currently running backups

Recent Activity

List of recent backup runs with status
Click to view detailed logs
Filter by status (success, failed, running)

Repository Overview

Total repositories configured
Storage usage (if available)
Repository health status

Backup Jobs

Backup Jobs define what data to back up, where to store it, and when to run.

Creating a Backup Job

Basic Settings

Field	Description	Required
Name	Human-readable identifier for the backup	Yes
Description	Optional notes about the backup purpose	No
Repository	Target repository for storing backups	Yes
Borg Version	Use Borg 1.x or Borg 2.x (must match repository)	Yes
Active	Enable/disable the backup job	Yes

Source Configuration

Field	Description	Example
Source Directories	Paths to back up	`/host/home`, `/host/var/www`
Exclude Patterns	Glob patterns to exclude	`.tmp`, `/node_modules/*`
Exclude If Present	Skip directories containing these files	`.nobackup`, `CACHEDIR.TAG`

Advanced Options

Option	Description	Default
Compression	Compression algorithm and level	`zstd,3`
One File System	Don't cross filesystem boundaries	Enabled
Read Special	Read special files (devices, FIFOs)	Disabled
Numeric Owner	Store numeric user/group IDs	Disabled
No Atime	Don't store access time	Enabled

Retention Policy

Configure how many archives to keep:

Setting	Description	Recommended
Keep Hourly	Number of hourly archives	24
Keep Daily	Number of daily archives	7
Keep Weekly	Number of weekly archives	4
Keep Monthly	Number of monthly archives	6
Keep Yearly	Number of yearly archives	2

Hooks

Execute commands before/after backups:

Hook	When Executed	Use Case
Before Backup	Before archive creation starts	Database dumps, stop services
After Backup	After successful backup	Cleanup temp files, start services
On Error	When backup fails	Send alerts, cleanup

Running Backups

Manual Run: Click the "Run" button on any backup job
Scheduled Run: Automatically triggered by configured schedule
Stop Running: Click "Stop" to abort a running backup

Backup Status

Status	Indicator	Meaning
Idle	⚪ Gray	Not currently running
Running	🔵 Blue (spinner)	Backup in progress
Success	🟢 Green	Last run completed successfully
Failed	🔴 Red	Last run failed
Inactive	⚫ Disabled	Backup job is disabled

Repositories

Repositories are the storage destinations for backup archives.

Repository Types

Local Repository

Path format: /path/to/repository
Use case: Local disk, mounted NAS, attached storage
Performance: Fastest backup/restore speeds
Configuration: Just specify the path

SSH/SFTP Repository

Path format: ssh://user@hostname:port/path
Use case: Remote backup servers, dedicated storage boxes
Authentication: SSH key (recommended) or password
Configuration:
- Host, port, username
- SSH key selection or password
- Remote path (browse with file explorer)

S3/Cloud Storage (Rclone)

Providers: Amazon S3, Backblaze B2, Wasabi, MinIO, Google Cloud, etc.
Storage Modes:
- Local + Cloud Sync: Fast local backups, automatic cloud sync
- Native Cloud (Borg 2.x): Direct S3 writes, no Rclone needed
Configuration:
- Select Rclone remote (pre-configured in Rclone)
- Specify bucket/path
- Choose storage mode

Creating a Repository

Navigate to Repositories → Create Repository
Select repository type (Local, SSH, S3/Rclone)
Configure type-specific settings
Set Borg version (1.x or 2.x)
Enter encryption passphrase
Click Create to initialize the repository

Critical: Save your repository passphrase securely! Without it, your backups cannot be accessed or restored.

Repository Actions

Action	Description	When to Use
Check	Verify repository integrity	Periodically or after errors
Compact (Borg 2.x)	Reclaim space from deleted archives	After pruning many archives
Update Passphrase	Change stored passphrase	If passphrase was entered incorrectly
Delete	Remove repository from UI	Optionally delete data on disk

Archives (View/Restore)

Archives are point-in-time snapshots stored in repositories.

Archive Browser

The Archive Browser provides file-system navigation of backup contents:

Restore Options

Option	Description	Best For
Restore to New Location	Extract to a specified folder	Safest - review before replacing
Download	Download to your browser (ZIP for folders)	Small files, quick access
Restore to Original Location	Put files back where they were	Full disaster recovery

Restore History

Each archive tracks its last restore operation:

Destination path or "Downloaded"
Timestamp of restore
Persisted across sessions

Archive Actions

Action	Description
Browse	Open archive in file browser
Info	View archive metadata (size, file count, etc.)
Delete	Permanently remove archive from repository

Schedules

Schedules automate backup execution at specified intervals.

Schedule Configuration

Field	Description	Example
Schedule Type	Preset or custom cron	Daily, Weekly, Custom
Time	When to run	02:00
Day (weekly)	Day of week for weekly schedules	Sunday
Cron Expression	Custom cron for advanced scheduling	`0 /6 * *`
Timezone	Timezone for schedule evaluation	Europe/Berlin

Cron Expression Reference

# Format: minute hour day-of-month month day-of-week
#         0-59   0-23 1-31         1-12  0-6 (0=Sunday)

0 2 * * *      # Daily at 2:00 AM
0 */6 * * *    # Every 6 hours
0 3 * * 0      # Weekly on Sunday at 3:00 AM
0 4 1 * *      # Monthly on the 1st at 4:00 AM
*/30 * * * *   # Every 30 minutes

Common Schedule Patterns

Pattern	Cron	Use Case
Daily at 2 AM	`0 2 * * *`	Standard daily backup
Every 6 hours	`0 /6 * *`	Frequently changing data
Weekdays at 6 PM	`0 18 * * 1-5`	End of business day
Sunday at 3 AM	`0 3 * * 0`	Weekly full backup

SSH Key Management

SSH keys enable secure, passwordless authentication to remote servers.

Key Operations

Import Existing Key

Click Import SSH Key
Provide a name for the key
Paste the private key content, OR
Click Select from Server to browse server filesystem, OR
Click Upload Key File to upload from your computer
If key is encrypted, enter the passphrase
Click Create

Generate New Key

Click Generate SSH Key
Provide a name
Select key type (Ed25519 recommended, RSA for compatibility)
Click Generate
Copy the public key to remote server's ~/.ssh/authorized_keys

Test Connection

Click the test icon on a key
Enter remote host, username, and port
Click Test Connection
Verify connection succeeds and Borg is detected

Supported Key Types

Type	Format Header	Recommendation
OpenSSH	`-----BEGIN OPENSSH PRIVATE KEY-----`	✅ Recommended (modern)
RSA PEM	`-----BEGIN RSA PRIVATE KEY-----`	✅ Good (legacy compatible)
EC PEM	`-----BEGIN EC PRIVATE KEY-----`	✅ Good
PKCS#8	`-----BEGIN PRIVATE KEY-----`	✅ Good

Key Security

Private keys are stored encrypted in the database
Passphrase-protected keys are supported
Temporary key files are created with mode 0600
Temporary files are cleaned up immediately after use

YAML Editor

The YAML Editor provides direct access to Borgmatic configuration files.

Features

Syntax Highlighting: YAML-aware editor with color coding
Validation: Real-time syntax and schema validation
Backup/Restore: Automatic backups of config changes
File Browser: View all configuration files in /etc/borgmatic.d/

Use Cases

Advanced configuration not exposed in UI
Bulk editing of multiple options
Importing existing Borgmatic configs
Troubleshooting configuration issues

Caution: Manual YAML edits may conflict with UI-managed settings. Use the UI for standard configurations.

Logs

The Logs page provides access to backup execution logs and system events.

Log Types

Log Type	Content	Location
Backup Logs	Individual backup execution output	Per-backup log files
Borgmatic Logs	Borgmatic wrapper output	System logs
Application Logs	Borgmatic UI application events	Container stdout/stderr

Log Features

Real-time Streaming: Watch backup progress live
Search: Find specific entries
Filter by Level: Info, Warning, Error
Download: Export logs for analysis

Settings

General Settings

Setting	Description
Instance Name	Display name for this server
Theme	Light or dark mode
Timezone	Default timezone for schedules

Operating Mode

See the Operating Modes section above.

Notifications

Configure alerts for backup events:

Provider	Configuration
Email (SMTP)	SMTP server, credentials, recipients
Webhook	URL to POST events to
Slack	Webhook URL
Discord	Webhook URL
Gotify	Server URL and token
Ntfy	Topic and server URL

Security Settings

Setting	Description
Change Password	Update admin password
Session Timeout	Auto-logout after inactivity
API Tokens	Generate tokens for API access

Factory Reset

Completely reset the instance:

Removes all configurations
Clears all credentials
Optionally regenerates secret key
Requires typing "RESET" to confirm

Warning: Factory reset is irreversible. Backup your data first!

Environment Variables

Configure the application via environment variables:

Variable	Default	Description
`NODE_ENV`	production	Environment mode (production/development)
`PORT`	3000	HTTP server port
`JWT_SECRET`	(auto-generated)	Secret for JWT token signing
`ADMIN_USERNAME`	admin	Default admin username
`ADMIN_PASSWORD`	admin	Default admin password
`DATA_DIR`	/app/data	Persistent data directory
`TZ`	UTC	Container timezone
`DIRECTOR_PORT`	9000	WebSocket port (Director mode)
`RESTORE_ALLOWED_ROOTS`	/host,/tmp,/data	Allowed restore destination paths
`DEBUG_REPOSITORIES`	false	Enable verbose repository logging

Docker Deployment

Basic Docker Compose

version: '3.8'

services:
  borgmatic-ui:
    image: borgmatic-ui:latest
    container_name: borgmatic-ui
    restart: unless-stopped
    ports:
      - "8080:3000"      # Web UI
      - "9000:9000"      # Director WebSocket (if using Director mode)
    volumes:
      - ./data:/app/data                    # Persistent data
      - ./borgmatic.d:/etc/borgmatic.d      # Borgmatic configs
      - /:/host:ro                          # Host filesystem access
      - ./borg-cache:/root/.cache/borg      # Borg cache
    environment:
      - ADMIN_PASSWORD=change-me-please
      - TZ=Europe/Berlin

Volume Mounts Explained

Mount	Purpose	Required
`/app/data`	Application data, credentials, SSH keys	Yes
`/etc/borgmatic.d`	Generated Borgmatic YAML configs	Yes
`/:/host`	Access to host filesystem for backups	Yes (for local backups)
`/root/.cache/borg`	Borg cache (improves backup speed)	Recommended

Troubleshooting

Common Issues

Problem	Cause	Solution
"Cannot connect to server"	Backend not running or port blocked	Check container logs, verify port mapping
"Authentication failed" (SSH)	Wrong key or not in authorized_keys	Verify public key on remote server
"Passphrase wrong"	Incorrect repository passphrase	Update passphrase in repository settings
"Repository locked"	Previous backup didn't finish	Wait or use "Break Lock" action
Backup stuck at 0%	Network issue or SSH timeout	Check connectivity, test SSH connection
Director: Client not connecting	Firewall, wrong URL, or DNS issue	Verify port 9000 accessible, check client logs

Debug Mode

# Enable verbose logging
docker run -e DEBUG_REPOSITORIES=true ...

# View container logs
docker logs -f borgmatic-ui

# Check real-time backup output
# (visible in the UI during backup execution)

API Access

Borgmatic Director UI provides a REST API for automation and integration.

Authentication

# Login to get JWT token
POST /api/auth/login
Content-Type: application/json
{
  "username": "admin",
  "password": "your-password"
}

# Use token in subsequent requests
Authorization: Bearer <token>

Key Endpoints

# Backups
GET  /api/backups              # List all backup jobs
POST /api/backups/:id/run      # Trigger backup
POST /api/backups/:id/stop     # Stop running backup

# Repositories  
GET  /api/repositories         # List repositories
POST /api/repositories/:id/check  # Check integrity

# Archives
GET  /api/archives/:repo       # List archives
GET  /api/archives/:repo/:archive/browse  # Browse contents

# Health
GET  /api/dashboard/health     # System health
GET  /api/dashboard/tools-health  # Tool versions

Need more help? Check the container logs (docker logs borgmatic-ui) for detailed error messages. Most issues are related to SSH connectivity, passphrases, or file permissions.