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: Directory Navigation: Click folders to explore Breadcrumb Trail: Navigate back to parent directories Search/Filter: Filter files by name File Preview: View text file contents directly Selection: Check items for restore/download 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 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.