diff --git a/README.md b/README.md index e1d20cb2c..2936d639e 100644 --- a/README.md +++ b/README.md @@ -4,37 +4,20 @@ [![Report Card](http://goreportcard.com/badge/restic/restic)](http://goreportcard.com/report/restic/restic) [![Coverage Status](https://coveralls.io/repos/restic/restic/badge.svg)](https://coveralls.io/r/restic/restic) -Restic Design Principles -======================== -Restic is a program that does backups right and was designed with the following -principles in mind: +Introduction +============ - * Easy: Doing backups should be a frictionless process, otherwise you might be - tempted to skip it. Restic should be easy to configure and use, so that, in - the event of a data loss, you can just restore it. Likewise, - restoring data should not be complicated. - - * Fast: Backing up your data with restic should only be limited by your - network or hard disk bandwidth so that you can backup your files every day. - Nobody does backups if it takes too much time. Restoring backups should only - transfer data that is needed for the files that are to be restored, so that - this process is also fast. - - * Verifiable: Much more important than backup is restore, so restic enables - you to easily verify that all data can be restored. - - * Secure: Restic uses cryptography to guarantee confidentiality and integrity - of your data. The location the backup data is stored is assumed not to be a - trusted environment (e.g. a shared space where others like system - administrators are able to access your backups). Restic is built to secure - your data against such attackers. - - * Efficient: With the growth of data, additional snapshots should only take - the storage of the actual increment. Even more, duplicate data should be - de-duplicated before it is actually written to the storage back end to save - precious backup space. +restic is a backup program that is fast, efficient and secure. Detailed +information can be found in [the documentation](doc/index.md) and [the user +manual](doc/Manual.md). The [design document](doc/Design.md) lists the +technical background and gives detailed information about the structure of the +repository and the data saved therein. +The latest documentation can be viewed online at +. On the bottom left corner there is +a menu that allows switching to the documentation and user manual for the +latest released version. Build restic ============ @@ -49,26 +32,11 @@ afterwards you'll find the binary in the current directory: restic [OPTIONS] [...] -More documentation can be found on the [website](https://restic.github.io), -especially in the [user manual](https://restic.github.io/manual). +More documentation can be found in the [user manual](doc/Manual.md). At the moment, the only tested compiler for restic is the official Go compiler. Building restic with gccgo may work, but is not supported. -Compatibility -============= - -Backward compatibility for backups is important so that our users are always -able to restore saved data. Therefore restic follows [Semantic -Versioning](http://semver.org) to clearly define which versions are compatible. -The repository and data structures contained therein are considered the "Public -API" in the sense of Semantic Versioning. This goes for all released versions -of restic, this may not be the case for the master branch. - -We guarantee backward compatibility of all repositories within one major version; -as long as we do not increment the major version, data can be read and restored. -We strive to be fully backward compatible to all prior versions. - Contribute and Documentation ============================ @@ -99,17 +67,6 @@ pub 4096R/91A6868BD3F7A907 2014-11-01 sub 4096R/D5FC2ACF4043FDF1 2014-11-01 ``` -Talks -===== - -The following talks will be or have been given about restic: - - * 2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016, Brussels, Belgium - * 2016-01-29: [restic - Backups mal richtig](https://media.ccc.de/v/c4.openchaos.2016.01.restic): Public lecture in German at [CCC Cologne e.V.](https://koeln.ccc.de) in Cologne, Germany - * 2015-08-23: [A Solution to the Backup Inconvenience](https://programm.froscon.de/2015/events/1515.html): Lecture at [FROSCON 2015](https://www.froscon.de) in Bonn, Germany - * 2015-02-01: [Lightning Talk at FOSDEM 2015](https://www.youtube.com/watch?v=oM-MfeflUZ8&t=11m40s): A short introduction (with slightly outdated command line) - * 2015-01-27: [Talk about restic at CCC Aachen](https://videoag.fsmpi.rwth-aachen.de/?view=player&lectureid=4442#content) (in German) - License ======= diff --git a/doc/Manual.md b/doc/Manual.md index 361a12de1..d02a2a5f8 100644 --- a/doc/Manual.md +++ b/doc/Manual.md @@ -28,6 +28,9 @@ In order to build restic from source, execute the following steps: $ go run build.go +At the moment, the only tested compiler for restic is the official Go compiler. +Building restic with gccgo may work, but is not supported. + Usage help is available: $ ./restic --help diff --git a/doc/index.md b/doc/index.md index b0512bfba..9ba805f21 100644 --- a/doc/index.md +++ b/doc/index.md @@ -8,6 +8,9 @@ can find an overview of the documentation. The project's homepage is , the source code repository can be found on GitHub at the URL . +Building and viewing the documentation +-------------------------------------- + The documentation you're currently viewing may not match the version of restic you have installed. If you cloned the repository manually, you can find the right documentation in the directory `doc/`. If you're viewing this online at @@ -23,3 +26,92 @@ installing it, you can edit and view the documentation locally by running: [I 160221 12:33:57 server:271] Serving on http://127.0.0.1:8000 Afterwards visit the URL with a browser. + +Design Principles +----------------- + +Restic is a program that does backups right and was designed with the following +principles in mind: + + * **Easy:** Doing backups should be a frictionless process, otherwise you might be + tempted to skip it. Restic should be easy to configure and use, so that, in + the event of a data loss, you can just restore it. Likewise, + restoring data should not be complicated. + + * **Fast**: Backing up your data with restic should only be limited by your + network or hard disk bandwidth so that you can backup your files every day. + Nobody does backups if it takes too much time. Restoring backups should only + transfer data that is needed for the files that are to be restored, so that + this process is also fast. + + * **Verifiable**: Much more important than backup is restore, so restic enables + you to easily verify that all data can be restored. + + * **Secure**: Restic uses cryptography to guarantee confidentiality and integrity + of your data. The location the backup data is stored is assumed not to be a + trusted environment (e.g. a shared space where others like system + administrators are able to access your backups). Restic is built to secure + your data against such attackers. + + * **Efficient**: With the growth of data, additional snapshots should only take + the storage of the actual increment. Even more, duplicate data should be + de-duplicated before it is actually written to the storage back end to save + precious backup space. + +Compatibility +------------- + +Backward compatibility for backups is important so that our users are always +able to restore saved data. Therefore restic follows [Semantic +Versioning](http://semver.org) to clearly define which versions are compatible. +The repository and data structures contained therein are considered the "Public +API" in the sense of Semantic Versioning. This goes for all released versions +of restic, this may not be the case for the master branch. + +We guarantee backward compatibility of all repositories within one major version; +as long as we do not increment the major version, data can be read and restored. +We strive to be fully backward compatible to all prior versions. + +Contribute and Documentation +---------------------------- + +Contributions are welcome! More information can be found in the document +[`CONTRIBUTING.md`](https://github.com/restic/restic/blob/master/CONTRIBUTING.md). + +Contact +------- + +If you discover a bug, find something surprising or if you would like to +discuss or ask something, please [open a github +issue](https://github.com/restic/restic/issues/new). If you would like to chat +about restic, there is also the IRC channel #restic on irc.freenode.net. + +**Important**: If you discover something that you believe to be a possible +critical security problem, please do *not* open a GitHub issue but send an +email directly to alexander@bumpern.de. If possible, please encrypt your email +using the following PGP key +([0x91A6868BD3F7A907](https://pgp.mit.edu/pks/lookup?op=get&search=0xCF8F18F2844575973F79D4E191A6868BD3F7A907)): + +``` +pub 4096R/91A6868BD3F7A907 2014-11-01 + Key fingerprint = CF8F 18F2 8445 7597 3F79 D4E1 91A6 868B D3F7 A907 + uid Alexander Neumann + sub 4096R/D5FC2ACF4043FDF1 2014-11-01 +``` + +Talks +----- + +The following talks will be or have been given about restic: + + * 2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016, Brussels, Belgium + * 2016-01-29: [restic - Backups mal richtig](https://media.ccc.de/v/c4.openchaos.2016.01.restic): Public lecture in German at [CCC Cologne e.V.](https://koeln.ccc.de) in Cologne, Germany + * 2015-08-23: [A Solution to the Backup Inconvenience](https://programm.froscon.de/2015/events/1515.html): Lecture at [FROSCON 2015](https://www.froscon.de) in Bonn, Germany + * 2015-02-01: [Lightning Talk at FOSDEM 2015](https://www.youtube.com/watch?v=oM-MfeflUZ8&t=11m40s): A short introduction (with slightly outdated command line) + * 2015-01-27: [Talk about restic at CCC Aachen](https://videoag.fsmpi.rwth-aachen.de/?view=player&lectureid=4442#content) (in German) + +License +======= + +Restic is licensed under "BSD 2-Clause License". You can find the complete text +in the file `LICENSE`.