How to Use the Command 'borg' (with Examples)

Borg is a powerful deduplicating backup tool designed to create efficient, secure, and reliable backups. It supports both local and remote backups, making them mountable as a filesystem. This flexibility allows for easy access and restoration of files. Here, we explore various use cases of the Borg command to illustrate its capabilities and versatility in backup management.

Use Case 1: Initialize a Local Repository

Code:

borg init path/to/repo_directory

Motivation:

When you start using Borg for backups, the first step is to initialize a repository where the backups, or “archives,” will be stored. This preparation phase is essential as it prepares the storage location, making it capable of receiving the data you plan to back up. By initializing a repository, you essentially setup the environment for secure and organized storage, which is crucial for efficient backup operations.

Explanation:

• borg init: This initiates the command to start the setup of a new repository.
• path/to/repo_directory: This specifies the path where you want to create the repository. It can be a local directory usually intended for storing backup data.

Example Output:

Enter new passphrase: 
Enter same passphrase again: 
Do you want your passphrase to be displayed for verification? [yN]:

Use Case 2: Backup a Directory Creating an Archive Called “Monday”

Code:

borg create --progress path/to/repo_directory::Monday path/to/source_directory

Motivation:

After setting up your repository, your primary use of Borg will be to create backups. This command allows you to copy data from a specified source to your repository and label it with an easily recognizable name, such as “Monday.” This is useful for organizing daily backups and reduces confusion when multiple backups exist.

Explanation:

• borg create: Initiates the creation of a backup archive.
• --progress: Displays the progress of the backup operation. It provides real-time feedback on the status of your backup.
• path/to/repo_directory::Monday: Indicates the repository and the specific name of the archive (in this case, “Monday”) within the repository.
• path/to/source_directory: Points to the directory containing the data you wish to back up.

Example Output:

Archive name: Monday
Archive id: f4c1e7dea3fb40f084929b908d135306
Start time: Mon, 2023-04-10 12:00:00
End time: Mon, 2023-04-10 12:10:00
Duration: 10 minutes
Number of files: 1200

Use Case 3: List All Archives in a Repository

Code:

borg list path/to/repo_directory

Motivation:

Once you have backups, it’s often necessary to review what archives exist within a repository. Listing all archives allows users to manage, verify, and plan their backup strategies effectively by providing a clear overview of stored data.

Explanation:

• borg list: This command is used to fetch and display all archives contained in the specified repository.
• path/to/repo_directory: The path to the repository whose contents you want to list.

Example Output:

Monday                           Mon, 2023-04-10 12:10:00
Tuesday                          Tue, 2023-04-11 12:10:00
Wednesday                        Wed, 2023-04-12 12:10:00

Use Case 4: Extract a Specific Directory from the “Monday” Archive in a Remote Repository, Excluding All *.ext Files

Code:

borg extract user@host:path/to/repo_directory::Monday path/to/target_directory --exclude '*.ext'

Motivation:

Data retrieval is a critical feature of any backup tool. This use case illustrates how to extract specific directories from a backup while excluding certain file types, useful in scenarios where you only need specific content restored without redundant files.

Explanation:

• borg extract: Triggers the retrieval of files from a specified archive.
• user@host:path/to/repo_directory::Monday: Specifies the location of the remote repository and the archive (Monday) to extract from. The user@host: format is used for accessing remote systems.
• path/to/target_directory: Directory where the extracted files will be placed.
• --exclude '*.ext': This option allows specifying a pattern of files to exclude during extraction, particularly useful for avoiding unnecessary files like temporary files.

Example Output:

Extracting directory `Documents` from archive `Monday`
12 items processed, 2 excluded
Restoration to `path/to/target_directory` completed successfully.

Use Case 5: Prune a Repository by Deleting All Archives Older Than 7 Days, Listing Changes

Code:

borg prune --keep-within 7d --list path/to/repo_directory

Motivation:

Backup management includes not only creating and restoring data but also ensuring that storage resources are utilized efficiently. Pruning old backups that are no longer needed helps in managing storage space. Keeping it tidy by removing older archives ensures timely backups while adhering to retention policies.

Explanation:

• borg prune: This command initiates the deletion process based on specified criteria.
• --keep-within 7d: Tells Borg to keep only those archives created within the last 7 days and prune older ones.
• --list: Provides a detailed list of what is deleted during the pruning process.
• path/to/repo_directory: The repository from which old backups should be pruned.

Example Output:

Keeping archive: Monday Wed, 2023-04-12 02:11:11
Keeping archive: Tuesday Thu, 2023-04-13 02:11:11
Pruning archive: Previous_Friday Fri, 2023-04-06 02:10:11

Use Case 6: Mount a Repository as a FUSE Filesystem

Code:

borg mount path/to/repo_directory::Monday path/to/mountpoint

Motivation:

Mounting a repository as a FUSE filesystem facilitates easy browsing and interaction with backup archives as if they were a regular filesystem. This is extremely useful for situations when you need to verify or interact with backup contents without extracting files.

Explanation:

• borg mount: Activates the mount operation using FUSE (Filesystem in Userspace).
• path/to/repo_directory::Monday: Specifies the archive within the repository to mount.
• path/to/mountpoint: The directory where the filesystem will be available for browsing.

Example Output:

After execution, you’d have the archive’s content accessible directly via the specified mount point directory, akin to browsing any other filesystem directory.

Use Case 7: Display Help on Creating Archives

Code:

borg create --help

Motivation:

Understanding command options is crucial for efficient command usage. Accessing the command help provides a user with an exhaustive list of options, enabling them to tailor backup operations to their specific needs optimally.

Explanation:

• borg create: Part of the command indicating interest in help options related to the create operation.
• --help: Invokes the help section for the create function, listing all relevant arguments and usages.

Example Output:

Displays a detailed overview of all create command parameters, including options for compression, progress reporting, and tag management.

Conclusion

Borg is an incredibly flexible and robust tool for managing backups. From initializing and managing repositories to creating archives and restoring data, it provides comprehensive features to safeguard information effectively. Each use case described demonstrates different aspects of Borg’s functionality, emphasizing its role as a crucial tool in systematic data protection practices.