Repositories

Explanation for the user about the functionalities of the 'Repositories' menu.

About the Repositories menu #

This is the main view, you will find all the repositories you have created. Borgwarehouse offers you a quick view on the status of each of your repo. You can fold or unfold each repo to display more or less information.

Finally, you can add, edit or delete repositories from this view.

The manage modale #

When you add or edit a repository, you will have a modal displayed with different fields.

Alias #

This field is free and allows you to have more friendly repository names. This value will be displayed in the repo list.

SSH public key #

Here you need to specify the SSH public key of your client machine that you want to save on the server behind the BorgWarehouse interface. Currently, BorgWarehouse accepts three types of SSH public keys: RSA, ed25519 and ed25519-sk.

An SSH public key must be unique (?) . BorgWarehouse will warn you if you try to use an already use one.

Storage size #

This field allows you to define a quota (the unit is in Go and requires integers) for your repository. If you exceed the quota, your client will not be able to backup and you will get an error on your BorgBackup client like :

The storage quota (1.00 GB) has been exceeded (1.00 GB). Try deleting some archives.

At any time, if you exceed your quota, you can change it by editing your repository. This will automatically recalculate the available storage and you can restart a backup from your BorgBackup client.

You can keep an eye on the storage of each repository from the repository list or in the Monitoring section of BorgWarehouse. Finally, you can retrieve this information from the BorgWarehouse API.

Comment #

This field exists to improve the user experience. It allows you to save a comment specific to your repository. The comments are then visible on each repository by moving the mouse over the icon :

Generates commands for use over LAN #

BorgWarehouse generates ready-made commands in the Setup Wizard menu, as well as a quick settings command directly on each repository in the list.

These commands are built with a hostname and port corresponding to these environment variables :

FQDN=bw.yourdomain.com
SSH_SERVER_PORT=22

Most of the time, you’ll be using the Internet for your backups (WAN). On the other hand, for machines on the same network as your server, you can generate commands to go through the LAN network and thus avoid leaving your network to re-enter it (loss of speed, and useless use of your Internet connection).

To do this, you need to add the following two environment variables :

FQDN_LAN=192.168.1.5
SSH_SERVER_PORT_LAN=2222

Then check the checkbox for each repository for which you want commands to be generated for the LAN :

You’ll see a LAN badge on the repository concerned, right next to the copy quicksetting button :

Alerting #

This selector allows you to set the maximum time between two modifications of your repository. If the time is exceeded, the status of your repository will turn red. This status is represented by the red or green dot on the left of the alias in the repository list.

Disable alert on a repository #

Chose “Disabled” in the selector to disable alerts for a single repository. When a repository’s alerts are deactivated, you’ll see a crossed-out bell icon in the repository list, as in this screenshot:

Append-only mode #

This selector lets you enable append-only mode for your BorgBackup repository. Append-only is a property of data storage such that new data can be added to the storage, but where existing data is immutable. So this powerful mode allows you to further increase the security of your backups.

I won’t go into the details of BorgBackup’s documentation. Just keep in mind several points about this mode :

• You can enable/disable this mode on a repository as you wish.
• This mode is activated on the server side, overriding your client configuration. So even if your backup client is compromised, it won’t be able to disable the append-only mode.
• This mode prevents complete deletion of the repository.
• This mode does not prevent archives from being deleted : In fact, it will no longer be visible from your client, but it will still be present in storage. Follow the steps in the BorgBackup documentation to restore a compromised client on a repository in append-only mode.
• This mode generates a transaction file called transactions, located at the root of your repository.
• To save space by pruning, you’ll first need to disable your repository’s append-only mode.

You can activate append-only mode at repository initialization or afterwards via editing, by checking the box :

The padlock icon with a “+” (because you can only add data 😉) in the interface lets you quickly see whether the option is activated or not :

Compact a repository #

Over time, deleting archives (or pruning from your client) leaves unused space inside a BorgBackup repository. The borg compact command frees that space on disk by removing unused segments.

BorgWarehouse lets you trigger a compaction in one click, directly from the repository list. Unfold a repository and click the compact icon (the little package 📦) :

A notification confirms when the compaction is done. A few things to keep in mind :

• The operation runs entirely on the server side and does not require the repository passphrase. BorgWarehouse, by design, never holds your decryption key.
• You can compact several different repositories at the same time. However, the same repository cannot be compacted twice simultaneously: if a compaction is already running on it, a new request is rejected until the first one finishes.
• Depending on the repository size, compaction can take some time and use disk I/O.
• The compact button is not available on archived repositories (see below).

Break the lock on a repository #

BorgBackup locks a repository while an operation is running, to prevent concurrent access. If an operation is interrupted (for example a container restart or a network drop during a backup or a compaction), a stale lock can remain and block the next operations. Your BorgBackup client would then fail with a lock error.

The borg break-lock command releases such a stale lock. This option is available from the repository editing mode, in the maintenance area at the bottom of the modal :

Clicking it opens a confirmation window :

Like compaction, breaking a lock is a server-side, keyless operation: it never needs your repository passphrase.

Archive / unarchive a repository #

Archiving is a way to freeze a repository you no longer actively use, without deleting anything. An archived repository :

• is frozen: the client can no longer connect to it over SSH: no backup, no prune, no restore. This is enforced server-side by disabling the repository’s SSH access, so it works without the repository passphrase.
• stops triggering notifications and is excluded from monitoring / status alerts (it will never turn red).
• becomes read-only in the interface: the edit form is disabled until you unarchive it.
• keeps all its data untouched. Archiving is fully reversible.

You will find the Archive button in the repository editing mode, in the maintenance area next to Break lock :

A confirmation window explains the consequences before archiving :

Once archived, the repository leaves the main list and moves to a hidden archived list. You can show or hide it with the archive button in the toolbar (it displays the number of archived repositories) :

Archived repositories are displayed greyed out to make their state obvious at a glance.

To restore a repository to normal, open it in editing mode and click Unarchive. The client will then be able to connect again and notifications will resume.

Delete a repository #

This option is only accessible from the repository editing mode. You will find the option at the very bottom of the modal :

Deleting a repository deletes all the data saved for this repository. It is impossible to go back after this action. That’s why you will find a confirmation window :