Version 1.2.1 (2022-06-06)
--------------------------
Upgrade notes:
Some things can be recommended for the upgrade process from borg 1.1.x
(please also read the important compatibility notes below):
- do you already want to upgrade? 1.1.x also will get fixes for a while.
- be careful, first upgrade your less critical / smaller repos.
- first upgrade to a recent 1.1.x release - especially if you run some older
1.1.* or even 1.0.* borg release.
- using that, run at least one `borg create` (your normal backup), `prune`
and especially a `check` to see everything is in a good state.
- check the output of `borg check` - if there is anything special, consider
a `borg check --repair` followed by another `borg check`.
- if everything is fine so far (borg check reports no issues), you can consider
upgrading to 1.2.x. if not, please first fix any already existing issue.
- if you want to play safer, first **create a backup of your borg repository**.
- upgrade to latest borg 1.2.x release (you could use the fat binary from
github releases page)
- run `borg compact --cleanup-commits` to clean up a ton of 17 bytes long files
in your repo caused by a borg 1.1 bug
- run `borg check` again (now with borg 1.2.x) and check if there is anything
special.
- run `borg info` (with borg 1.2.x) to build the local pre12-meta cache (can
take significant time, but after that it will be fast) - for more details
see below.
- check the compatibility notes (see below) and adapt your scripts, if needed.
- if you run into any issues, please check the github issue tracker before
posting new issues there or elsewhere.
If you follow this procedure, you can help avoiding that we get a lot of
"borg 1.2" issue reports that are not really 1.2 issues, but existed before
and maybe just were not noticed.
Compatibility notes:
- matching of path patterns has been aligned with borg storing relative paths.
Borg archives file paths without leading slashes. Previously, include/exclude
patterns could contain leading slashes. You should check your patterns and
remove leading slashes.
- dropped support / testing for older Pythons, minimum requirement is 3.8.
In case your OS does not provide Python >= 3.8, consider using our binary,
which does not need an external Python interpreter. Or continue using
borg 1.1.x, which is still supported.
- freeing repository space only happens when "borg compact" is invoked.
- mount: the default for --numeric-ids is False now (same as borg extract)
- borg create --noatime is deprecated. Not storing atime is the default behaviour
now (use --atime if you want to store the atime).
- list: corrected mix-up of "isomtime" and "mtime" formats.
Previously, "isomtime" was the default but produced a verbose human format,
while "mtime" produced a ISO-8601-like format.
The behaviours have been swapped (so "mtime" is human, "isomtime" is ISO-like),
and the default is now "mtime".
"isomtime" is now a real ISO-8601 format ("T" between date and time, not a space).
- create/recreate --list: file status for all files used to get announced *AFTER*
the file (with borg < 1.2). Now, file status is announced *BEFORE* the file
contents are processed. If the file status changes later (e.g. due to an error
or a content change), the updated/final file status will be printed again.
- removed deprecated-since-long stuff (deprecated since):
- command "borg change-passphrase" (2017-02), use "borg key ..."
- option "--keep-tag-files" (2017-01), use "--keep-exclude-tags"
- option "--list-format" (2017-10), use "--format"
- option "--ignore-inode" (2017-09), use "--files-cache" w/o "inode"
- option "--no-files-cache" (2017-09), use "--files-cache=disabled"
- removed BORG_HOSTNAME_IS_UNIQUE env var.
to use borg you must implement one of these 2 scenarios:
- 1) the combination of FQDN and result of uuid.getnode() must be unique
and stable (this should be the case for almost everybody, except when
having duplicate FQDN *and* MAC address or all-zero MAC address)
- 2) if you are aware that 1) is not the case for you, you must set
BORG_HOST_ID env var to something unique.
- exit with 128 + signal number, #5161.
if you have scripts expecting rc == 2 for a signal exit, you need to update
them to check for >= 128.
Fixes:
- create: skip with warning if opening the parent dir of recursion root fails, #6374
- create: fix crash. metadata stream can produce all-zero chunks, #6587
- fix crash when computing stats, escape % chars in archive name, #6500
- fix transaction rollback: use files cache filename as found in txn.active/, #6353
- import-tar: kill filter process in case of borg exceptions, #6401#6681
- import-tar: fix mtime type bug
- ensure_dir: respect umask for created directory modes, #6400
- SaveFile: respect umask for final file mode, #6400
- check archive: improve error handling for corrupt archive metadata block, make
robust_iterator more robust, #4777
- pre12-meta cache: do not use the cache if want_unique is True, #6612
- fix scp-style repo url parsing for ip v6 address, #6526
- mount -o versions: give clear error msg instead of crashing.
it does not make sense to request versions view if you only look at 1 archive,
but the code shall not crash in that case as it did, but give a clear error msg.
- show_progress: add finished=true/false to archive_progress json, #6570
- delete/prune: fix --iec mode output (decimal vs. binary units), #6606
- info: fix authenticated mode repo to show "Encrypted: No", #6462
- diff: support presence change for blkdev, chrdev and fifo items, #6615
New features:
- delete: add repository id and location to prompt, #6453
- borg debug dump-repo-objs --ghost: new --segment=S --offset=O options
Other changes:
- support python 3.11
- allow msgpack 1.0.4, #6716
- load_key: no key is same as empty key, #6441
- give a more helpful error msg for unsupported key formats, #6561
- better error msg for defect or unsupported repo configs, #6566
- docs:
- document borg 1.2 pattern matching behavior change, #6407
Make clear that absolute paths always go into the matcher as if they are
relative (without leading slash). Adapt all examples accordingly.
- authentication primitives: improved security and performance infos
- mention BORG_FILES_CACHE_SUFFIX as alternative to BORG_FILES_CACHE_TTL, #5602
- FAQ: add a hint about --debug-topic=files_cache
- improve borg check --max-duration description
- fix values of TAG bytes, #6515
- borg compact --cleanup-commits also runs a normal compaction, #6324
- virtualization speed tips
- recommend umask for passphrase file perms
- borg 1.2 is security supported
- update link to ubuntu packages, #6485
- use --numeric-ids in pull mode docs
- remove blake2 docs, blake2 code not bundled any more, #6371
- clarify on-disk order and size of segment file log entry fields, #6357
- docs building: do not transform --/--- to unicode dashes
- tests:
- check that borg does not require pytest for normal usage, fixes#6563
- fix OpenBSD symlink mode test failure, #2055
- vagrant:
- darwin64: remove fakeroot, #6314
- update development.lock.txt
- use pyinstaller 4.10 and python 3.9.13 for binary build
- upgrade VMCPUS and xdistn from 4 to 16, maybe this speeds up the tests
- crypto:
- use hmac.compare_digest instead of ==, #6470
- hmac_sha256: replace own cython wrapper code by hmac.digest python stdlib (since py38)
- hmac and blake2b minor optimizations and cleanups
- removed some unused crypto related code, #6472
- avoid losing the key (potential use-after-free). this never could happen in
1.2 due to the way we use the code. The issue was discovered in master after
other changes, so we also "fixed" it here before it bites us.
- setup / build:
- add pyproject.toml, fix sys.path, #6466
- setuptools_scm: also require it via pyproject.toml
- allow extra compiler flags for every extension build
- fix misc. C / Cython compiler warnings, deprecation warnings
- fix zstd.h include for bundled zstd, #6369
- source using python 3.8 features: ``pyupgrade --py38-plus ./**/*.py``
2d507eaf8d