This marks the first stable release in the Borg 1.1 series. Many improvements and new features +were incorporated into Borg 1.1 since the 1.0 release of Borg in early 2016.
+More than sixty people contributed code to this release — see Contributors on this page — +and 2016-2017 has been a fantastic time for the Borg project.
+Since Borg 1.1 is now stable, it will only receive fixes and minor additions, +no larger new features. Principal development continues in the +Borg 1.2 series.
+This is only a summary of the changes between 1.0 and 1.1. +Check the full changelog +to see all changes.
+Major new features in the 1.1 release series are:
+borg recreate: remove files from existing archives and re-chunk or re-compress them. +This finally allows deduplication between legacy Attic / Borg 0.xx archives and Borg 1.x archives. +This is an experimental feature.
borg diff: show differences between two archives.
borg mount: show all recorded versions of files with the "versions view".
borg list: more formatting options, including generation of hashes and per-file chunk statistics.
borg create: automatic compression mode (-C auto,zlib/lz4/...), faster handling of many files, +experimental support for inclusion patterns (--patterns, --patterns-from), files cache mode control (mtime/ctime)
borg export-tar: streaming export of GNU tar compatible archives.
Archive comments
BLAKE2b256-based encryption modes, and "authenticated" modes that provide data integrity without encryption. +These provide better performance than the existing SHA-256-based modes on most hardware, except where +the x86 SHA extensions are available (e.g. AMD Ryzen).
Repository indices and the Borg cache now use checksums to detect bitrot and other corruption.
A documented JSON API has been added to the most vital commands (borg list, borg info and borg create).
Structured JSON logging is available for all commands.
--prefix has been supplemented with --glob-archives (-a), --sort-by, --last and --first options. +These can be used for borg list, borg info, borg mount, borg check, borg delete and borg prune.
Quality of life improvements:
+options that imply output (--show-rc, --show-version, --list, --stats, --progress) don't need -v/--info to have that output displayed any more.
borg check is silent by default (finally!).
borg can now checkpoint within (big) files, not only between files.
borg delete can delete multiple archives by giving their names.
Automatic removal of stale locks, which should make "borg break-lock" essentially superfluous. +This is enabled by default, see BORG_HOSTNAME_IS_UNIQUE.
Answers to prompts like "Accessing previously unknown repository" are now saved immediately.
Cache synchronization and "borg info" are now faster.
Reduced space usage of chunks.archive.d in the cache by 30-40 %. Existing caches are migrated during a cache sync.
The cache used for remote cache syncs and mounting remote repositories does not grow indefinitely any more, +but adapts to the available space. Good riddance, TMP=/var/tmp!
BORG_PASSCOMMAND makes using key rings and hardware keys much easier.
Documentation improvements:
+The online command reference has been significantly revamped: +better presentation of options, commands are now separate pages +(improves search, and old links still work), many formatting improvements, +revised examples, a new theme, ...
New deployment guides
The internals docs saw many corrections and extensions.
man pages are now provided in source releases.
--help uses ANSI sequence on terminals for basic markup
New asciinema screencasts.
Compatibility notes for upgrading from Borg 1.0 to Borg 1.1:
+No explicit "borg upgrade" is required.
Borg 1.1 uses some new data structures which are backwards-compatible with Borg 1.0.4 and newer.
Borg 1.0 can't make use of Borg 1.1's "compact cache" and will silently ignore it.
The default compression has been changed from "none" to "lz4".
Repositories in the "repokey" and "repokey-blake2" modes with an empty passphrase are now treated as +unencrypted repositories for security checks (e.g. BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK).
borg init:
+-e/--encryption is now a mandatory option with no default value. +Previously the default value was "repokey".
the short form of --append-only (-a) has been removed.
running "borg init" via a "borg serve --append-only" server will not create +an append-only repository any more. Use "borg init --append-only" to initialize an append-only repository.
borg create:
+A new option --files-cache MODE (default MODE is: ctime,size,inode) has been introduced and also the +default cache MODE has changed from "mtime,size,inode" in 1.0.x to "ctime,size,inode" in 1.1.x.
Be prepared that the first "borg create" after you upgrade to 1.1.x will run significantly slower than usual. +This is due to a complete cache rebuild, caused by the changed cache mode. +Passing explicitly --files-cache with the old default: "mtime,size,inode" would avoid the slowdown, +but is not advisable as "ctime" is better as it reflects both file contents and metadata changes, +while "mtime" reflects only file contents changes.
the --exclude-if-present option now supports tagging a folder with any file system +object type (file, folder, etc.), instead of accepting only files as tags.
borg upgrade: the short form of --inplace (-i) has been removed.
borg delete: the short form of --cache-only (-c) has been removed.
"borg migrate-to-repokey" has been renamed to "borg key migrate-to-repokey" with no deprecation notice, +since it is rarely and only manually used.
Deprecated options and commands in Borg 1.1, which will be removed in Borg 1.2:
+"borg change-passphrase" is deprecated, use "borg key change-passphrase" instead. +"borg change-passphrase" will be removed in Borg 1.2.
borg create: the --keep-tag-files option has been deprecated in favour of the new --keep-exclude-tags option. +Both options have the same effect. --keep-tag-files will be removed in Borg 1.2.
borg create: the --ignore-inode option has been deprecated in favour of --files-cache=... modes without "inode". +--ignore-inode will be removed in Borg 1.2.
borg create: the --no-files-cache option has been deprecated in favour of --files-cache=disabled. +--no-files-cache will be removed in Borg 1.2.
We'd like to thank everyone who contributed to Borg, be it code, bug reports, testing, +documentation, creating packages or spreading the word.
+Contributors to the main repository for this release were:
+ + +Special thanks also go to everyone and every organization donating funds +to support development and maintainers:
+ +This marks the first stable release in the Borg 1.2 series. Many improvements and new features +were incorporated into Borg 1.2 since the 1.1 release of Borg in early 2017. Even more changes +were made "under the hood": cleanups and refactors.
+Many people contributed to this release — see the AUTHORS file in the git repo and the +git history for details. Even more people contributed otherwise, e.g. by giving feedback +or helping with testing.
+Special thanks also go to everyone and every organization donating funds to support development +and maintenance!
+Since Borg 1.2 is now stable, it will primarily receive fixes and minor additions, +but not potentially problematic code changes. Principal development continues in the master branch.
+This is only a summary of the changes between 1.1 and 1.2. +Check the full changelog +to see all changes as well as important compatibility and upgrade notes.
+Major new features in the 1.2 release series are:
+create: Internally use file descriptors rather than file names (as much as +possible) to avoid race conditions on active file systems.
create: Externalize file discovery via --paths-from-stdin and --paths-from-command. +Using this, you can just feed a list of full path/filenames into borg and borg +will create a backup archive with the corresponding files (no more, no less).
create: --content-from-command: Create archive using stdout of given command.
create: --compression: New 'obfuscate' pseudo compressor obfuscates compressed +chunk sizes in the repository. You can use this to make chunk size fingerprinting +attacks against your repo much harder. It will use more storage space for +better privacy (and you can decide how much it is worth to you).
create: --chunker-params: New, very fast 'fixed' block size chunker (also +puts less load on the CPU compared to the buzhash chunker). Recommended for +everything with a fixed block size, like disk devices, raw disk images, +files with fixed record sizes (header record can be of different size).
create: Improve sparse file support, much faster, especially when used +together with the 'fixed' chunker.
compact: Separate "borg compact" needs to be used to free repository space. +Borg < 1.2 always compacted at the end of repo-writing commands, so these +will be faster now. Also, you get kind of a "temporary append-only" behaviour +until you invoke borg compact. For some users, less stuff moving around in +the repo directory also might make rclones or rsyncs of their borg repo faster. +"borg compact" can be invoked from the repo server, borg hosting providers can +offer to use off-peak-hours for compaction.
repository: Other optimizations for better speed and less stuff moving around.
check: --max-duration: Incremental, time-limited repo check (crc32 check only). +Users with huge repositories can use this to distribute their repo checks +over multiple free time slots (for example, do a partial check each Sunday, +resulting in a full check after multiple weeks).
mount: Support new/maintained pyfuse3 as an alternative to the old llfuse lib.
import-tar: New complement to export-tar. Import existing tar files or +(together with export-tar) move archives from one borg repo to another. +Please note that currently export-tar + import-tar is a lossy conversion as +it does not support all metadata that borg create/extract supports (like +ACLs, xattrs, flags).
Minimal native Windows support, see Windows readme (WIP).
Other changes:
+create/recreate: Showing the current file name before starting to back it +up makes life easier, especially for very big files which take a while...
create: First ctrl-c (SIGINT) triggers checkpoint creation and then aborts.
create: --remote-buffer: Use an upload buffer for remote repos.
prune: Show which rule was applied to keep archive (kind of self-explanatory).
check: Much faster when recovering data from corrupted segment files.
New BORG_WORKAROUNDS mechanism.
Works with recent Python, msgpack, PyInstaller, etc. versions.
Major setup code refactoring (especially library handling), needs pypi "pkgconfig".
Other major internal refactors / cleanups.
Internal AEAD-style crypto API (not all you see in there is used already).
Internal msgpack-wrapper to avoid current and future compatibility issues.
Improved C code portability / basic MSC compatibility.
Improved documentation (a lot of this was also backported to 1.1.x though).
This is only a summary of the changes between 1.2 and 2.0. +Check the full changelog +to see all changes as well as important compatibility and upgrade notes.
+The "bad" news first:
+This is a breaking release, it is not directly compatible with borg 1.x repos and thus +not a quick upgrade.
+Also, there were cli changes, thus you will need to review/edit your scripts. Wrappers +and GUIs for borg also need to get adapted.
+The good news are:
+if you like, you can efficiently copy your existing archives from old borg 1.x repos to +new borg 2 repos using "borg transfer" (you will need space and time for this, though).
by doing a breaking release, we could:
+fix a lot of long-term issues that could not (easily) be fixed in a non-breaking release
make the code cleaner and simpler, get rid of cruft and legacy
improve security and speed
open doors for new features and applications that were not possible yet
make the docs shorter and using borg easier
this is the first breaking release since many years and we do not plan another one +anytime soon.
added retries for input files (e.g. if there is a read error or file changed while reading)
better, more modern, faster crypto
+new keys/repos only use new crypto: AEAD, AES-OCB, chacha20-poly1305, argon2.
using session keys: more secure and easier to manage, especially in multi-client or multi-repo +contexts. doing this, we could get rid of problematic long term nonce/counter management.
the old crypto code will get removed in borg 2.1 (currently we still need it to read from +your old borg 1.x repos). removing AES-CTR, pbkdf2, encrypt-and-mac, counter/nonce management +will make borg more secure, easier to use and develop.
repos are faster, safer and easier to deal with
+borg rcompress can do a repo-wide efficient recompression.
the new PUT2 data format uses much less crc32 and more xxh64 and offers +a header-only checksum (PUT1 only offered one checksum for header+data). +that way, we can safely read header infos without having to also read all the data.
vastly different speeds in misc. crc32 implementations do not matter any more. +because of this, we can just use python's zlib.crc32 and do not need libdeflate's crc32.
the repo index now also stores "csize" (less random I/O for some ops)
the repo index now has an API to store and query misc. "flags" (can be used e.g. for +bookkeeping of long-running whole-repo operations)
multi-repo improvements
+borg 1.x only could deal with 1 repository per borg invocation. borg 2.0 now also knows +about another repo (see --other-repo option) for some commands, like borg transfer, +borg rcreate, ...
borg rcreate can create "related repositories" of an existing repo, e.g. to use them +for efficient archive transfers using borg transfer.
borg transfer can copy and convert archives from a borg 1.x repo to a related borg 2 repo. +to save time, it will transfer the compressed file content chunks (without compressing them +again). +but, to make your repo more secure, it will decrypt / re-encrypt all the chunks.
borg transfer can copy archives from one borg 2 repo to a related other borg 2 repo, +without doing any conversion.
command line interface cleanups
+no scp style repo parameters any more (parsing ambiguity issues, no :port possible), +just use the better ssh://user@host:port/path .
separated repo and archive, no "::" any more
split some commands that worked on archives and repos into 2 separate commands +(makes the code/docs/help easier)
renamed borg init to borg rcreate for better consistency
added commands / options:
+you will usually need to give either -r (aka --repo) or BORG_REPO env var.
--match-archives now has support for regex or glob/shell style matching
borg key change-location: usable for repokey <-> keyfile location change
borg benchmark cpu (so you can actually see what's fastest for your CPU)
borg import/export-tar --tar-format=GNU/PAX/BORG, support ctime/atime PAX headers. +GNU and PAX are standard formats, while BORG is a very low-level custom format only +for borg usage.
removed commands / options:
+removed -P (aka --prefix) option, use -a (aka --match-archives) instead, e.g.: -a 'PREFIX*'
borg upgrade (was only relevant for attic / old borg)
removed deprecated cli options
using platformdirs python package to determine locations for configs and caches
show files / archives with local timezone offsets, store archive timestamps with tz offset
make user/group/uid/gid optional in archived files
do not store .borg_part files in final archive, simplify statistics (no parts stats any more)
avoid orphan chunks on input files with OSErrors
make sure archive name/comment, stuff that get into JSON is pure valid utf-8 (no surrogate escapes)
internal data format / processing changes
+using msgpack spec 2.0 now, cleanly differentiating between text and binary bytes. +the older msgpack spec attic and borg < 2.0 used did not have the binary type, so +it was not pretty... +also using the msgpack Timestamp data type instead of self-made bigint stuff.
archives: simpler, more symmetric handling of hardlinks ("hlid", all hardlinks have same +chunks list, if any). the old way was just a big pain (e.g. for partial extracting), +ugly and spread all over the code. the new way simplified the code a lot.
item metadata: clean up, remove, rename, fix, precompute stuff
chunks have separate encrypted metadata (size, csize, ctype, clevel). +this saves time for borg rcompress/recreate when recompressing to same compressor, but other level. +this also makes it possible to query size or csize without reading/transmitting/decompressing +the chunk.
remove legacy zlib compression header hack, so zlib works like all the other compressors. +that hack was something we had to do back in the days because attic backup did not have +a compression header at all (because it only supported zlib).
got rid of "csize" (compressed size of a chunk) in chunks index and archives. +this often was just "in the way" and blocked the implementation of other (re)compression +related features.
massively increase the archive metadata stream size limitation (so it is practically +not relevant any more)
source code changes
+borg 1.x borg.archiver (and also the related tests in borg.testsuite.archiver) monster +modules got split into packages of modules, now usually 1 module per borg cli command.
using "black" (automated pep8 source code formatting), this reformatted ALL the code
added infrastructure so we can use "mypy" for type checking
python, packaging and library changes
+minimum requirement: Python 3.9
we unbundled all 3rd party code and require the respective libraries to be +available and installed. this makes packaging easier for dist package maintainers.
discovery is done via pkg-config or (if that does not work) BORG_*_PREFIX env vars.
our setup*.py is now much simpler, a lot moved to setup.cfg and we also use +pyproject.toml now.
we had to stop supporting LibreSSL (e.g. on OpenBSD) due to their different API. +borg on OpenBSD now also uses OpenSSL.
getting rid of legacy stuff
+removed some code only needed to deal with very old attic or borg repos. +users are expected to first upgrade to borg 1.2 before jumping to borg 2.0, +thus we do not have to deal with any ancient stuff any more.
You can learn more about borg future plans there:
+ +Borg 2.0 is currently in beta/rc testing - do not use it for production.
+ +Borg 1.2 is the current stable series of Borg. +The current release is 1.2.5, released on 2023-08-30.
+ +Borg 1.1 is not supported any more, please use Borg 1.2.x. +The current release is 1.1.18, released on 2022-06-05.
+ +Borg 1.0 is not supported any more, please use Borg 1.2.x. +The last release in this series was 1.0.13, released on 2019-02-15.
+ +Borg 0.xx was the development series leading up to the Borg 1.0 release and +is not supported any more. It was active from early 2015 to early 2016 including +releases from 0.23.0 to 0.30.1.
+Here are some commercial service and support providers for borgbackup:
+Waldmann EDV - borgbackup consulting, support, development
borgbase.com - specialized hosting for borg repos
hetzner.de - storage box with borg support
rsync.net - cloud storage platform with borg support
Please first read the docs, the existing issue tracker issues and mailing +list posts -- a lot of stuff is already documented / explained / discussed / +filed there.
+We have quite nice docs including:
+installation
reference of borg commands
examples and a FAQ
internals docs
docs for developers
If you've found a bug or have a concrete feature request, please create a new +ticket on the project's issue tracker.
+For more general questions or discussions, IRC or mailing list are preferred.
+Join us on channel #borgbackup on libera.chat.
+As usual on IRC, just ask or tell directly and then patiently wait for replies. +Stay connected.
+Using a IRC client and a registered nick is the preferred way to use our channel.
+In times of high spammer activity, the registered nick might be even required to +join our channel.
+You could also use the web based IRC client, choose some nickname and join our +channel (you might still need a registered nick to join our channel, see above):
+ +You can also use a matrix protocol based chat client like e.g. +Element to join the +#borgbackup room.
+Note: This room is bridged to the #borgbackup IRC channel on libera.chat.
+To find out about the mailing list, its topic, how to subscribe, how to +unsubscribe and where you can find the archives of the list, see the +mailing list homepage.
+Follow us there for announcements:
+Mastodon: https://fosstodon.org/@borgbackup
Twitter/X: https://twitter.com/borgbackup
Please understand that Twitter/X and mastodon are not suitable for longer / more +complex discussions - use one of the other channels for that.
+See there.
+Please help the software projects you use and love.
+You can support the BorgBackup Project using these options:
+ +PayPal Donations are maybe the easiest way (if you already use PayPal or a credit card) +to directly support a specific developer.
+Waldmann EDV is the company of Thomas Waldmann, borgbackup's main developer and maintainer.
+On Liberapay, you can become a Patron and support us on a regular basis to +create a long term sustainable project.
+The funds are distributed to the borgbackup team members and as a borgbackup +developer you can join the team.
+On Github, you can become a sponsor and support us on a regular basis or alternatively +also do a one-time donation.
+The funds are transferred to OpenCollective Europe (OC EU) then, which is our fiscal host.
+You can also give funds directly via OpenCollective, they also go to OC EU then.
+The funds held by OC EU for us can be used to pay misc. project-related expenses +submitted by borgbackup team members.
+You can give general funds to the borgbackup members (the developers will +then spend the funds as they deem fit, usually to create bounties).
+A bounty is a reward for whoever fixes a specific issue, e.g. to fix a bug, +update the docs, implement a feature, ...
+You can use the above, if you do not have some specific bounty (see below).
+If you want to encourage developers to fix some specific issue or implement some +specific feature suggestion, you can post a new bounty or back an existing one +(they always refer to an issue in our issue tracker).
+As a developer, you can become a Bounty Hunter and win bounties (earn money).
+