mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-27 02:08:54 +00:00
Code Issues Releases Wiki Activity
borg/README.rst

184 lines
7.2 KiB
ReStructuredText
Raw Normal View History

embed the asciinema preview image / link into the README
2015-10-24 21:58:05 +00:00
|screencast|
docs: fix the highlighting default is "python", that's why some help fragments and bash scripts looked strange.
2016-07-11 21:16:53 +00:00
improve README.rst
2015-08-06 14:39:50 +00:00
What is BorgBackup?
fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer.
2016-11-03 17:54:07 +00:00
-------------------
Update README.md with doc|stable shield, minor markup fixes on docs/deployment.rst
2016-01-15 18:06:20 +00:00
improve README.rst
2015-08-06 14:39:50 +00:00
BorgBackup (short: Borg) is a deduplicating backup program.
Optionally, it supports compression and authenticated encryption.
integrate CHANGES-borg.txt into CHANGES and README.rst
2015-05-13 22:37:09 +00:00
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
The main goal of Borg is to provide an efficient and secure way to backup data.
The data deduplication technique used makes Borg suitable for daily backups
since only changes are stored.
The authenticated encryption technique makes it suitable for backups to not
fully trusted targets.
Reference to BorgWeb
2015-07-27 12:45:32 +00:00
fix README links so they work in github
2015-10-07 22:33:43 +00:00
See the `installation manual`_ or, if you have already
make readme a little more readable link to source documents for people that are reading just the README without a web browser hyperlink to the changes document as well
2015-10-07 21:36:34 +00:00
downloaded Borg, ``docs/installation.rst`` to get started with Borg.
improve README.rst
2015-08-06 14:39:50 +00:00
correct install link
2015-11-15 00:13:25 +00:00
.. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html
improve README.rst
2015-08-06 14:39:50 +00:00
updated README
2013-07-03 20:38:17 +00:00
Main features
fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer.
2016-11-03 17:54:07 +00:00
~~~~~~~~~~~~~
update and improve docs use the travis status image as png as svg does not show an image in firefox.
2016-02-27 16:22:56 +00:00
improve README.rst
2015-08-06 14:39:50 +00:00
**Space efficient storage**
Deduplication based on content-defined chunking is used to reduce the number
of bytes stored: each file is split into a number of variable length chunks
and only chunks that have never been seen before are added to the repository.
be clear about what buzhash is used for, fixes #2390 and want it is not used for (deduplication). also say already in the readme that we use a cryptohash for dedupe, so people don't worry.
2017-04-25 21:38:55 +00:00
A chunk is considered duplicate if its id_hash value is identical.
A cryptographically strong hash or MAC function is used as id_hash, e.g.
(hmac-)sha256.
improve README.rst
2015-08-06 14:39:50 +00:00
To deduplicate, all the chunks in the same repository are considered, no
matter whether they come from different machines, from previous backups,
from the same backup or even from the same single file.
Compared to other deduplication approaches, this method does NOT depend on:
Remove trailing whitespace
2016-07-27 13:12:52 +00:00
* file/directory names staying the same: So you can move your stuff around
Fix markup in README.rst Github generated wrong markup, because of a few whitespace errors. This patch fixes the rst markup of the README.rst file.
2016-01-18 15:30:27 +00:00
without killing the deduplication, even between machines sharing a repo.
improve README.rst
2015-08-06 14:39:50 +00:00
Remove trailing whitespace
2016-07-27 13:12:52 +00:00
* complete files or time stamps staying the same: If a big file changes a
little, only a few new chunks need to be stored - this is great for VMs or
Fix markup in README.rst Github generated wrong markup, because of a few whitespace errors. This patch fixes the rst markup of the README.rst file.
2016-01-18 15:30:27 +00:00
raw disks.
improve README.rst
2015-08-06 14:39:50 +00:00
Remove trailing whitespace
2016-07-27 13:12:52 +00:00
* The absolute position of a data chunk inside a file: Stuff may get shifted
Fix markup in README.rst Github generated wrong markup, because of a few whitespace errors. This patch fixes the rst markup of the README.rst file.
2016-01-18 15:30:27 +00:00
and will still be found by the deduplication algorithm.
improve README.rst
2015-08-06 14:39:50 +00:00
**Speed**
* performance critical code (chunking, compression, encryption) is
implemented in C/Cython
* local caching of files/chunks index data
* quick detection of unmodified files
**Data encryption**
All data can be protected using 256-bit AES encryption, data integrity and
readme: add note about clientside encryption
2015-12-03 16:35:52 +00:00
authenticity is verified using HMAC-SHA256. Data is encrypted clientside.
improve README.rst
2015-08-06 14:39:50 +00:00
**Compression**
compression: update / refine docs
2015-08-15 13:45:15 +00:00
All data can be compressed by lz4 (super fast, low compression), zlib
(medium speed and compression) or lzma (low speed, high compression).
improve README.rst
2015-08-06 14:39:50 +00:00
**Off-site backups**
Borg can store data on any remote host accessible over SSH. If Borg is
installed on the remote host, big performance gains can be achieved
compared to using a network filesystem (sshfs, nfs, ...).
**Backups mountable as filesystems**
Backup archives are mountable as userspace filesystems for easy interactive
backup examination and restores (e.g. by using a regular file manager).
don't duplicate OS list we merge the "easy installation" and "platforms" paragraphs together in a neater phrasing
2015-10-07 22:15:30 +00:00
**Easy installation on multiple platforms**
README: minor grammar fix, minor other changes
2015-12-20 15:38:38 +00:00
We offer single-file binaries that do not require installing anything -
you can just run them on these platforms:
don't duplicate OS list we merge the "easy installation" and "platforms" paragraphs together in a neater phrasing
2015-10-07 22:15:30 +00:00
* Linux
* Mac OS X
* FreeBSD
clarify which systems have binaries
2015-10-07 22:37:35 +00:00
* OpenBSD and NetBSD (no xattrs/ACLs support or binaries yet)
* Cygwin (not supported, no binaries yet)
document windows 10 linux subsystem install also add note about remote repos being broken on cygwin.
2016-12-16 23:25:49 +00:00
* Linux Subsystem of Windows 10 (not supported)
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
improve README.rst
2015-08-06 14:39:50 +00:00
**Free and Open Source Software**
* security and functionality can be audited independently
move fork differences to FAQ it seems now that the fork is more of historical value than a current thing. people interested in the differences between borg and attic can look in the FAQ, but I do not see why this is present in the README. a new section regarding compatibility is created to keep that warning in place.
2016-11-03 18:03:48 +00:00
* licensed under the BSD (3-clause) license, see `License`_ for the
complete license
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
Easy to use
fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer.
2016-11-03 17:54:07 +00:00
~~~~~~~~~~~
update and improve docs use the travis status image as png as svg does not show an image in firefox.
2016-02-27 16:22:56 +00:00
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
Initialize a new backup repository and create a backup archive::
docs: use /path/to/repo, fixes #901 /mnt/backup was confusing as people like to mount their backup disk on /mnt/backup, but borg init /mnt/backup does not work if that directory already exists because it is the mountpoint. it would work, if /mnt was the mountpoint, but that is not obvious and also unusual.
2016-04-15 01:35:37 +00:00
$ borg init /path/to/repo
$ borg create /path/to/repo::Saturday1 ~/Documents
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
README: fix code-block without an argument
2016-11-27 19:16:41 +00:00
Now doing another backup, just to show off the great deduplication::
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
docs: use /path/to/repo, fixes #901 /mnt/backup was confusing as people like to mount their backup disk on /mnt/backup, but borg init /mnt/backup does not work if that directory already exists because it is the mountpoint. it would work, if /mnt was the mountpoint, but that is not obvious and also unusual.
2016-04-15 01:35:37 +00:00
$ borg create -v --stats /path/to/repo::Saturday2 ~/Documents
update and improve docs use the travis status image as png as svg does not show an image in firefox.
2016-02-27 16:22:56 +00:00
-----------------------------------------------------------------------------
Archive name: Saturday2
Archive fingerprint: 622b7c53c...
Time (start): Sat, 2016-02-27 14:48:13
Time (end): Sat, 2016-02-27 14:48:14
Duration: 0.88 seconds
Number of files: 163
-----------------------------------------------------------------------------
Original size Compressed size Deduplicated size
This archive: 6.85 MB 6.85 MB 30.79 kB <-- !
All archives: 13.69 MB 13.71 MB 6.88 MB
Unique chunks Total chunks
Chunk index: 167 330
-----------------------------------------------------------------------------
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
update readthedocs urls, fixes #991
2016-04-29 01:19:27 +00:00
For a graphical frontend refer to our complementary project `BorgWeb <https://borgweb.readthedocs.io/>`_.
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
README: how to help the project
2017-05-22 16:22:09 +00:00
Helping, Donations and Bounties
-------------------------------
Your help is always welcome!
Spread the word, give feedback, help with documentation, testing or development.
You can also give monetary support to the project, see there for details:
https://borgbackup.readthedocs.io/en/stable/support.html#bounties-and-fundraisers
move links from the sidebar to the readme it seems sidebar links are not supported by the RTD theme just yet: https://github.com/snide/sphinx_rtd_theme/issues/254
2015-10-13 03:27:59 +00:00
Links
fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer.
2016-11-03 17:54:07 +00:00
-----
move links from the sidebar to the readme it seems sidebar links are not supported by the RTD theme just yet: https://github.com/snide/sphinx_rtd_theme/issues/254
2015-10-13 03:27:59 +00:00
Fix markup in README.rst Github generated wrong markup, because of a few whitespace errors. This patch fixes the rst markup of the README.rst file.
2016-01-18 15:30:27 +00:00
* `Main Web Site <https://borgbackup.readthedocs.org/>`_
update frontpage / support docs less items in frontpage link list add IRC chat link minor other changes
2016-07-04 20:37:24 +00:00
* `Releases <https://github.com/borgbackup/borg/releases>`_,
`PyPI packages <https://pypi.python.org/pypi/borgbackup>`_ and
`ChangeLog <https://github.com/borgbackup/borg/blob/master/docs/changes.rst>`_
README: how to help the project
2017-05-22 16:22:09 +00:00
* `GitHub <https://github.com/borgbackup/borg>`_ and
`Issue Tracker <https://github.com/borgbackup/borg/issues>`_.
update frontpage / support docs less items in frontpage link list add IRC chat link minor other changes
2016-07-04 20:37:24 +00:00
* `Web-Chat (IRC) <http://webchat.freenode.net/?randomnick=1&channels=%23borgbackup&uio=MTY9dHJ1ZSY5PXRydWUa8>`_ and
`Mailing List <https://mail.python.org/mailman/listinfo/borgbackup>`_
Use https on updated license link
2016-01-25 12:33:48 +00:00
* `License <https://borgbackup.readthedocs.org/en/stable/authors.html#license>`_
Update link to security contact Currently this move was only done in master, so point to latest. Might be generally a good idea in case it changes and no release was done since the responsibility changed.
2016-12-22 14:21:42 +00:00
* `Security contact <https://borgbackup.readthedocs.io/en/latest/support.html#security-contact>`_
move links from the sidebar to the readme it seems sidebar links are not supported by the RTD theme just yet: https://github.com/snide/sphinx_rtd_theme/issues/254
2015-10-13 03:27:59 +00:00
move fork differences to FAQ it seems now that the fork is more of historical value than a current thing. people interested in the differences between borg and attic can look in the FAQ, but I do not see why this is present in the README. a new section regarding compatibility is created to keep that warning in place.
2016-11-03 18:03:48 +00:00
Compatibility notes
fix PDF rendering structure without those changes, all of the toctree document headings do not show up. they are considered to be "below" the last heading of the README file. we also remove the "Notes" section from the readme as there is only one note, regarding the fork. we introduce a stub "introduction" element in the toctree, otherwise it is impossible for the PDF rendered to render the README correctly. this is to workaround a bug in the PDF renderer.
2016-11-03 17:54:07 +00:00
-------------------
improve README.rst
2015-08-06 14:39:50 +00:00
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER
update and improve docs use the travis status image as png as svg does not show an image in firefox.
2016-02-27 16:22:56 +00:00
CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0).
fix README links so they work in github
2015-10-07 22:33:43 +00:00
deduplicate and refactor the docs README.rst (shown on github and also at the start of the html docs) shall be like an elevator speech - convince readers in a very short time. this is most important, everything else can come after we got the reader's interest. include README into docs to avoid duplication. also include CHANGES into docs. add developer docs, move examples from tox.ini there add separate support docs remove glossary, most of what was there can be understood by an admin from context move attic and compatibility note to the end
2015-08-06 10:59:51 +00:00
NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES.
THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS.
Added README and fixed time format string typo
2010-10-27 18:40:48 +00:00
fix links in standalone README github and standalone docutils don't parse :ref: tags correctly
2016-11-04 15:26:02 +00:00
Security issues should be reported to the `Security contact`_ (or
add link to security contact in README
2016-11-04 14:31:27 +00:00
see ``docs/suppport.rst`` in the source distribution).
display README correctly on PyPI I have discovered that PyPI is way more sensitive to RST warnings than other platforms: warnings and errors will make the document not show up correctly, which is currently the case here: https://pypi.python.org/pypi/borgbackup/ the suggested changes remove Sphinx-specific markup from the output, namely the badges and `|replacement|` patterns, but also the `higlight` directive. this also requires adding tags to the README to mark the badges to remove and removal of the `none` argument for the `.. code-block::` element which was not having any significant in Sphinx anyways.
2016-11-23 01:01:26 +00:00
.. start-badges
Add bountysource badge (#2581) add bountysource badge, fixes #2558
2017-06-03 12:40:08 +00:00
|doc| |build| |coverage| |bestpractices| |bounties|
.. |bounties| image:: https://api.bountysource.com/badge/team?team_id=78284&style=bounties_posted
:alt: Bounty Source
:target: https://www.bountysource.com/teams/borgbackup
Update README.md with doc|stable shield, minor markup fixes on docs/deployment.rst
2016-01-15 18:06:20 +00:00
.. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable
:alt: Documentation
Use HTTPS everywhere. Especially when the website already redirects to HTTPS.
2016-01-17 21:31:08 +00:00
:target: https://borgbackup.readthedocs.org/en/stable/
fork: s/attic/borg/g, fix URLs, add new section to AUTHORS use borg instead attic except at the places where it was used: - as toplevel package name, directory name, file name - to refer to original attic remove sphinx upload make command, will be replaced by github.io site later remove references to binary downloads and linux packages for now remove some software name references, fix grammar use borgbackup rather than borg-backup (or borg) in URLs, less name collision issues, better search results, no validity issues with "-"
2015-05-09 16:40:55 +00:00
fix travis badge
2016-02-27 18:05:46 +00:00
.. |build| image:: https://api.travis-ci.org/borgbackup/borg.svg
fork: s/attic/borg/g, fix URLs, add new section to AUTHORS use borg instead attic except at the places where it was used: - as toplevel package name, directory name, file name - to refer to original attic remove sphinx upload make command, will be replaced by github.io site later remove references to binary downloads and linux packages for now remove some software name references, fix grammar use borgbackup rather than borg-backup (or borg) in URLs, less name collision issues, better search results, no validity issues with "-"
2015-05-09 16:40:55 +00:00
:alt: Build Status
:target: https://travis-ci.org/borgbackup/borg
add codecov.io badge
2015-08-08 00:34:42 +00:00
Load over SSL (avoids mixed content)
2015-12-07 02:08:32 +00:00
.. |coverage| image:: https://codecov.io/github/borgbackup/borg/coverage.svg?branch=master
add codecov.io badge
2015-08-08 00:34:42 +00:00
:alt: Test Coverage
Load over SSL (avoids mixed content)
2015-12-07 02:08:32 +00:00
:target: https://codecov.io/github/borgbackup/borg?branch=master
Update README.md with doc|stable shield, minor markup fixes on docs/deployment.rst
2016-01-15 18:06:20 +00:00
.. |screencast| image:: https://asciinema.org/a/28691.png
:alt: BorgBackup Installation and Basic Usage
:target: https://asciinema.org/a/28691?autoplay=1&speed=2
add bestpractices badge
2016-09-03 19:11:47 +00:00
.. |bestpractices| image:: https://bestpractices.coreinfrastructure.org/projects/271/badge
:alt: Best Practices Score
:target: https://bestpractices.coreinfrastructure.org/projects/271
display README correctly on PyPI I have discovered that PyPI is way more sensitive to RST warnings than other platforms: warnings and errors will make the document not show up correctly, which is currently the case here: https://pypi.python.org/pypi/borgbackup/ the suggested changes remove Sphinx-specific markup from the output, namely the badges and `|replacement|` patterns, but also the `higlight` directive. this also requires adding tags to the README to mark the badges to remove and removal of the `none` argument for the `.. code-block::` element which was not having any significant in Sphinx anyways.
2016-11-23 01:01:26 +00:00
.. end-badges
Reference in a new issue Copy permalink