# Intro Help & Documentation

Learn how to use Borgmatic Director UI to manage your backups

Quick Links

[ Overview ](#bkmrk-overview---what-is-b) [ Operating Modes ](#bkmrk-operating-modes-borg) [ Connecting Client ](#bkmrk-connecting-a-client-) [ Repositories ](#bkmrk-setting-up-repositor) [ Backup Jobs ](#bkmrk-creating-backup-jobs) [ Schedules ](#bkmrk-setting-up-schedules) [ Restore ](#bkmrk-viewing-and-restorin) [ Settings ](#bkmrk-settings-overview-th)

Overview - What is Borgmatic UI?

**Borgmatic UI** is a web-based interface for managing{' '} [BorgBackup](https://www.borgbackup.org/){' '} through{' '} [Borgmatic](https://torsion.org/borgmatic/). It provides an intuitive interface for configuring backups, managing repositories, scheduling automated backups, and restoring files.

Key Features

- Create and manage backup jobs with an easy-to-use wizard - Configure repositories (local, SSH, SFTP, S3, Rclone) - Schedule automated backups with cron-like scheduling - Browse and restore files from any backup archive - Multi-node management with Director mode - Real-time backup monitoring and logging

Operating Modes

Borgmatic UI can operate in two main modes, depending on your needs:

Client / Standalone Mode

Run Borgmatic UI on a single machine to manage its local backups. This is the default mode and is perfect for individual servers or workstations.

**Use when:**- You have a single server to back up - You want a simple, self-contained backup solution - You don't need centralized management

**Note:** A standalone instance can later connect to a Director to become a managed client.

Director Mode

A central management server that can monitor and control multiple client instances. The Director doesn't run backups itself – it manages others.

**Use when:**- You have multiple servers to back up - You want centralized monitoring and control - You need to manage backups across your infrastructure

**Features:** Client management, templates, deployments, centralized passphrase vault.

Choosing Your Mode

You choose the operating mode during initial setup. The mode can be changed later in **Settings → Operating Mode**, but this will reset mode-specific configurations.

Connecting a Client to a Director

To connect a Client (or Standalone instance) to a Director for centralized management:

On the Director: Get Connection Details

In the Director's **Settings → Connection Configuration**, find or create a **Connection Token**. Also note the Director's URL (e.g., https://director.example.com:8000).

On the Client: Configure Connection

Go to **Settings → Client Configuration**. Enter: - **Client Name:** A friendly name for this client (e.g., "Web Server 1") - **Director URL:** The full URL including port (use https://) - **Connection Token:** The token from the Director (leave empty if open access)

Save and Connect

Click **Save Configuration**, then **Test Connection** to verify, and finally **Connect** to establish the connection.

Connected!

Once connected, the client will appear in the Director's dashboard and can be managed remotely. The connection uses WebSocket over SSL for real-time communication.

Troubleshooting Connection Issues

- **Connection refused:** Ensure the Director is running and the URL is correct (including https://) - **Invalid token:** Double-check the connection token matches exactly - **SSL errors:** Director mode automatically uses HTTPS – make sure to use https:// in the URL - **Firewall:** Ensure port 8000 (default) is open between client and Director

Switching Between Clients (Director Mode)

When logged into a Director, you can switch between viewing the Director's own interface and any connected client's interface.

Using the Client Selector

In the top navigation bar, you'll see a dropdown showing **"Director"** or the currently selected client's name. Click it to:

- Switch to **Director** - View the Director dashboard with all connected clients - Switch to a **Client** - View that client's backups, schedules, and settings as if you were logged in directly

Director View

- See all connected clients - Manage templates and deployments - Configure the vault for passphrases - View aggregated statistics

Client View

- Manage backup jobs - View/restore archives - Configure schedules - Edit repositories

Quick Access from Dashboard

In the Director Dashboard, each connected client has a **"View"** button. Clicking it switches to that client's view and highlights the dropdown selector so you know where to switch back.

Setting Up Repositories

A **repository** is where your backup data is stored. Before creating backup jobs, you need to set up at least one repository.

Supported Repository Types

Local

Backup to a local directory or mounted drive

SSH/SFTP

Backup to a remote server via SSH

Borg Server

Connect to a dedicated Borg backup server

S3/MinIO

Amazon S3 or compatible object storage

Rclone

Use Rclone for cloud storage (Google Drive, Dropbox, etc.)

Creating a Repository

1. Go to **Repositories** in the sidebar 2. Click **Add Repository** 3. Select the repository type and fill in the details: - **Name:** A friendly name for reference - **Path/URL:** Where the repository will be stored - **Encryption:** Choose encryption mode (repokey-blake2 recommended) - **Passphrase:** A strong password to encrypt your backups 4. Click **Create & Initialize** to create the repository

Important: Save Your Passphrase!

The repository passphrase is required to access your backups. If you lose it, your backup data will be **permanently inaccessible**. Store it securely (e.g., in a password manager).

Creating Backup Jobs

A **backup job** defines what to back up and where. Each job specifies source directories, a target repository, and optional exclusions.

Creating a Backup Job

1. Go to **Backup Jobs** in the sidebar 2. Click **Create Backup Job** 3. Fill in the backup configuration: - **Job Name:** A descriptive name (e.g., "Daily Website Backup") - **Source Directories:** Paths to back up (e.g., /var/www, /home) - **Repository:** Select a configured repository - **Exclusions:** Patterns to exclude (e.g., \*.log, node\_modules/) 4. Click **Save** to create the job

Running Backups

Manual Backup

Click the **Run Now** button on any backup job to start an immediate backup. Progress is shown in real-time.

Scheduled Backup

Set up a schedule (see next section) to run backups automatically at specified times.

Backup Archives

Each time a backup runs, it creates an **archive** – a point-in-time snapshot. Borg uses deduplication, so subsequent backups only store changed data, making them fast and space-efficient.

Setting Up Schedules

**Schedules** automate your backups by running them at specified times. You can create multiple schedules for different backup jobs.

Creating a Schedule

1. Go to **Schedules** in the sidebar 2. Click **Add Schedule** 3. Configure the schedule: - **Backup Job:** Select which job to run - **Frequency:** Daily, Weekly, Monthly, or Custom (cron) - **Time:** When to run the backup - **Days:** For weekly schedules, select which days 4. Click **Save** to activate the schedule

Schedule Examples

Daily at 2:00 AM

0 2 \* \* \*

Every Sunday at midnight

0 0 \* \* 0

Every 6 hours

0 \*/6 \* \* \*

First of every month at 3 AM

0 3 1 \* \*

Best Practices

- Run backups during low-activity periods (e.g., night) - Stagger multiple backup jobs to avoid resource contention - For critical data, consider running backups multiple times per day - Monitor backup logs to ensure schedules are running successfully

Viewing and Restoring Archives

The **View/Restore** page lets you browse your backup archives and restore files when needed.

Browsing Archives

1. Go to **View/Restore** in the sidebar 2. You'll see a list of your repositories 3. Click on a repository to expand it and see archives grouped by backup job 4. Each archive shows: - Creation date and time - Size (original and deduplicated) - Number of files

Restoring Files

Select an Archive

Click the **View** button on the archive you want to restore from.

Browse Files

Navigate through the archive's directory structure to find the files you need.

Select Files to Restore

Check the files or directories you want to restore. You can select individual files or entire folders.

Choose Restore Location

Specify where to restore the files: - **Original location:** Restore files to their original paths - **Custom location:** Restore to a different directory

Start Restore

Click **Restore** and wait for the process to complete. Progress is shown in real-time.

Restore Tips

- Restoring to the original location will overwrite existing files - For safety, consider restoring to a temporary location first - Large restores may take time – don't close the browser window - Check file permissions after restore if needed

Settings Overview

The **Settings** page contains various configuration options depending on your operating mode.

Operating Mode

View and change your current mode (Client/Standalone or Director). Changing modes will reset mode-specific configurations.

Client Configuration

Configure connection to a Director server. Set client name, Director URL, and connection token.

Connection Configuration

(Director only) Manage connection tokens and security settings for client connections.

Domain & Security

Configure custom domains, SSL certificates, and security settings for your installation.

Vault

(Director only) Securely store and manage repository passphrases for connected clients.

System Settings

Configure backup timeouts, concurrent backup limits, log retention, and other system-wide settings.

User Management

(Admin only) Create and manage user accounts, reset passwords, and configure permissions.