Borg - aka "BorgBackup" : Deduplicating archiver with compression and encryption

mail

Borg usage

Installed with the Debian package

borgbackup

Usage

Important note about permissions (source)

To backup :
  • your own files : just run Borg as your normal user
  • files of other users or the operating system : running Borg as root will be required

initialize a repository

borg init --encryption=mode /path/to/repo

create my first backup

Just a point of vocabulary : backup = archive
borg create --stats --progress /path/to/repo::archiveName path/to/data/to/backup
  • archiveName : the file name can be something like yyyy-mm-dd for a daily backup
  • --stats and --progress are there to make Borg more verbose (it's pretty quiet by default)
  • you may also

get information about an archive

borg info /path/to/repo::archiveName

list archives

borg list /path/to/repo

list contents of an archive

borg list /path/to/repo::archiveName
use --json-lines for details

check an archive

compare archives

restore files

delete archive or repository

  • archive : borg delete /path/to/repo::archiveName
  • repository : borg delete /path/to/repo
mail

Borg commands and flags

Flags

Command Flag Usage
check (none)
  • verify the consistency of a repository and its archives. It consists of two major steps :
    1. check the consistency of the repository itself
    2. check the consistency and correctness of
      • the archive metadata
      • archive data, with --verify-data
  • both steps can also be run independently with --repository-only or --archives-only
create -C compression
--compression=compression		 with compression : algorithm,ratio
--list output list of files
-s --stats print statistics for the created archive
delete delete
  • the specified archive from the specified repository
  • the whole specified repository
diff find differences (file contents, user/group/mode) between archives
extract (none) extract the contents of an archive
  • by default, the whole archive is extracted
  • to extract only a subset :
    • provide a list of files / directories to extract
    • use the --pattern* / --exclude* options
data is written to the current directory, there is no option to specify the output directory
-n --dry-run do not actually change any file
info display detailed information about the specified archive
init --encryption=mode with mode:
  • none : anyone can read or alter archives
  • authenticated : archives are not encrypted but modifications will be detected
  • keyfile : stores the encrypted key into ~/.config/borg/keys/
  • repokey : stores the encrypted key into repoDir/config
  • repokey-blake2 : (?)
mode can only be specified when initializing a new repository and can't be changed afterwards
list (none) list the contents of a repository or an archive
--json format output as JSON when listing the contents of a repository
--json-lines format output as JSON when listing the contents of an archive
mount mount archive as a FUSE filesystem to browse its contents or restore individual files
-p --progress show progress
-v --verbose --info verbose mode : display INFO level log entries
mail

Borg concepts and glossary

archive
  • what you get after a single backup operation (run with borg create )
  • contains a backup copy —i.e. snapshot of data— and aka backup
  • one can later extract or mount an archive to restore data
  • Borg archives take advantage of (source) :
    • deduplication : any file chunk is stored only once, allowing daily backups since only changes are stored
    • compression : save space (at the cost of speed / CPU usage)
    • authenticated encryption : you may store archives on not fully trusted targets
repository
  • filesystem directories acting as self-contained stores of archives
  • can be accessed locally via path or remotely via ssh
  • under the hood, repositories contain data blocks and a manifest tracking which blocks are in each archive. If some data hasn't changed from one backup to another, Borg can simply reference an already uploaded data chunk (deduplication)