Skip to content

Commit 56f52f7

Browse files
ThomasWaldmannThomasWaldmann
committed
borg 2.0 infos
1 parent ed071c0 commit 56f52f7

File tree

1 file changed

+133
-6
lines changed

1 file changed

+133
-6
lines changed

‎releases/borg-2.0.rst

Lines changed: 133 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Borg 2.0 (preliminary information)
2-
==================================
1+
Borg 2.0 (preliminary infos)
2+
============================
33

44
`« back to all releases <.>`_
55

@@ -13,11 +13,138 @@ This is only a summary of the changes between 1.2 and 2.0.
1313
Check the `full changelog <https://borgbackup.readthedocs.io/en/master/changes.html>`_
1414
to see all changes as well as important compatibility and upgrade notes.
1515

16+
Breaking compatibility
17+
~~~~~~~~~~~~~~~~~~~~~~
1618

17-
Major new features in the 2.0 release series are:
19+
**The "bad" news first:**
1820

19-
...
21+
This is a breaking release, it is not directly compatible with borg 1.x repos and thus
22+
not a quick upgrade.
2023

21-
Other changes:
24+
Also, there were cli changes, thus you will need to review/edit your scripts. Wrappers
25+
and GUIs for borg also need to get adapted.
2226

23-
...
27+
**The good news are:**
28+
29+
- if you like, you can efficiently copy your existing archives from old borg 1.x repos to
30+
new borg 2 repos using "borg transfer" (you will need space and time for this, though).
31+
- by doing a breaking release, we could:
32+
33+
- fix a lot of long-term issues that could not (easily) be fixed in a non-breaking release
34+
- make the code cleaner and simpler, get rid of cruft and legacy
35+
- improve security and speed
36+
- open doors for new features and applications that were not possible yet
37+
- make the docs shorter and using borg easier
38+
- this is the first breaking release since many years and we do not plan another one
39+
anytime soon.
40+
41+
Major new features
42+
~~~~~~~~~~~~~~~~~~
43+
44+
- better, more modern, faster crypto
45+
46+
- new keys/repos only use new crypto: AEAD, AES-OCB, chacha20-poly1305, argon2.
47+
- using session keys: more secure and easier to manage, especially in multi-client or multi-repo
48+
contexts. doing this, we could get rid of problematic long term nonce/counter management.
49+
- faster by AEAD: adding the chunk ID into the AD part automatically makes sure we get the
50+
right data: if we can authenticate/decrypt it, it is the data for the ID we asked for.
51+
older borg needed an additional MAC(plaintext of chunk) step to make sure.
52+
- the old crypto code will get removed in borg 2.1 (currently we still need it to read from
53+
your old borg 1.x repos). removing AES-CTR, pbkdf2, encrypt-and-mac, counter/nonce management
54+
will make borg more secure, easier to use and develop.
55+
56+
- repos are faster, safer and easier to deal with
57+
58+
- the new PUT2 data format uses much less crc32 and more xxh64 and offers
59+
a header-only checksum (PUT1 only offered one checksum for header+data).
60+
that way, we can safely read header infos without having to also read all the data.
61+
- vastly different speeds in misc. crc32 implementations do not matter any more.
62+
because of this, we can just use python's zlib.crc32 and do not need libdeflate's crc32.
63+
- the repo index now also stores "size" (less random I/O for some ops)
64+
- the repo index now has an API to store and query misc. "flags" (can be used e.g. for
65+
bookkeeping of long-running whole-repo operations)
66+
67+
- multi-repo improvements
68+
69+
- borg 1.x only could deal with 1 repository per borg invocation. borg 2.0 now also knows
70+
about another repo (see --other-repo option) for some commands, like borg transfer,
71+
borg rcreate, ...
72+
- borg rcreate can create "related repositories" of an existing repo, e.g. to use them
73+
for efficient archive transfers using borg transfer.
74+
- borg transfer can copy and convert archives from a borg 1.x repo to a related borg 2 repo.
75+
to save time, it will not decompress / recompress the file content chunks.
76+
but, to make your repo more secure, it will decrypt / re-encrypt all the chunks.
77+
- borg transfer can copy archives from one borg 2 repo to a related other borg 2 repo,
78+
without doing any conversion.
79+
80+
- command line interface cleanups
81+
82+
- no scp style repo parameters any more (parsing issues, no :port possible),
83+
just use the better ssh://user@host:port/path .
84+
- separated repo and archive, no "::" any more
85+
- split some commands that worked on archives and repos into 2 separate commands
86+
(makes the code/docs/help easier)
87+
- renamed borg init to borg rcreate for better consistency
88+
89+
- added commands / options:
90+
91+
- you will usually need to give either -r (aka --repo) or BORG_REPO env var.
92+
- borg key change-location: usable for repokey <-> keyfile location change
93+
- borg benchmark cpu (so you can actually see what's fastest for your CPU)
94+
- borg import/export-tar --tar-format=GNU/PAX/BORG, support ctime/atime PAX headers.
95+
GNU and PAX are standard formats, while BORG is a very low-level custom format only
96+
for borg usage.
97+
98+
- removed commands / options:
99+
100+
- removed -P (aka --prefix) option, use -a (aka --glob-archives) instead, e.g.: -a 'PREFIX*'
101+
- borg upgrade (was only relevant for attic / old borg)
102+
- removed deprecated cli options
103+
104+
Other changes
105+
~~~~~~~~~~~~~
106+
107+
- internal data format / processing changes
108+
109+
- using msgpack spec 2.0 now, cleanly differentiating between text and binary bytes.
110+
the older msgpack spec attic and borg < 2.0 used did not have the binary type, so
111+
it was not pretty...
112+
also using the msgpack Timestamp data type instead of self-made bigint stuff.
113+
- archives: simpler, more symmetric handling of hardlinks ("hlid", all hardlinks have same
114+
chunks list, if any). the old way was just a big pain (e.g. for partial extracting),
115+
ugly and spread all over the code. the new way simplified the code a lot.
116+
- item metadata: clean up, remove, rename, fix, precompute stuff
117+
- chunks: compression header now also stores the level (not only the type).
118+
this saves time for borg recreate when recompressing to same compressor, but other level.
119+
- remove legacy zlib compression header hack, so zlib works like all the other compressors.
120+
that hack was something we had to do back in the days because attic backup did not have
121+
a compression header at all (because it only supported zlib).
122+
- got rid of "csize" (compressed size of a chunk) in chunks index and archives.
123+
this often was just "in the way" and blocked the implementation of other (re)compression
124+
related features.
125+
- massively increase the archive metadata stream size limitation (so it is practically
126+
not relevant any more)
127+
128+
- source code changes
129+
130+
- borg 1.x borg.archiver monster module got split into a package of modules,
131+
now usually 1 module per borg cli command.
132+
- using "black" (automated pep8 source code formatting), this reformatted ALL the code
133+
- added infrastructure so we can use "mypy" for type checking
134+
135+
- python, packaging and library changes
136+
137+
- minimum requirement: Python 3.9
138+
- we unbundled all 3rd party code and require the respective libraries to be
139+
available and installed. this makes packaging easier for dist package maintainers.
140+
- discovery is done via pkg-config or (if that does not work) BORG_*_PREFIX env vars.
141+
- our setup*.py is now much simpler, a lot moved to setup.cfg and we also use
142+
pyproject.toml now.
143+
- we had to stop supporting LibreSSL (e.g. on OpenBSD) due to their different API.
144+
borg on OpenBSD now also uses OpenSSL.
145+
146+
- getting rid of legacy stuff
147+
148+
- removed some code only needed to deal with very old attic or borg repos.
149+
users are expected to first upgrade to borg 1.2 before jumping to borg 2.0,
150+
thus we do not have to deal with any ancient stuff any more.

0 commit comments

Comments
 (0)