From c8c0495724dd43460d29d20759b65efa4b303acd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Thu, 3 Nov 2016 14:15:06 -0400 Subject: [PATCH] faster quickstart move the note about free space after the step by step example. it is unlikely that users will hit out of space conditions on their first run, and at the end of the example, they will see the not anyways. this is to make the documentation less scary for new users and easier to use. --- docs/quickstart.rst | 88 ++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 45 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 3e4e66cb8..8a10ac9b9 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -5,51 +5,8 @@ Quick Start =========== -This chapter will get you started with |project_name|. The first section -presents a simple step by step example that uses |project_name| to backup data. -The next section continues by showing how backups can be automated. - -Important note about free space -------------------------------- - -Before you start creating backups, please make sure that there is *always* -a good amount of free space on the filesystem that has your backup repository -(and also on ~/.cache). A few GB should suffice for most hard-drive sized -repositories. See also :ref:`cache-memory-usage`. - -Borg doesn't use space reserved for root on repository disks (even when run as root), -on file systems which do not support this mechanism (e.g. XFS) we recommend to -reserve some space in Borg itself just to be safe by adjusting the -``additional_free_space`` setting in the ``[repository]`` section of a repositories -``config`` file. A good starting point is ``2G``. - -If |project_name| runs out of disk space, it tries to free as much space as it -can while aborting the current operation safely, which allows to free more space -by deleting/pruning archives. This mechanism is not bullet-proof in some -circumstances [1]_. - -If you *really* run out of disk space, it can be hard or impossible to free space, -because |project_name| needs free space to operate - even to delete backup -archives. - -You can use some monitoring process or just include the free space information -in your backup log files (you check them regularly anyway, right?). - -Also helpful: - -- create a big file as a "space reserve", that you can delete to free space -- if you use LVM: use a LV + a filesystem that you can resize later and have - some unallocated PEs you can add to the LV. -- consider using quotas -- use `prune` regularly - -.. [1] This failsafe can fail in these circumstances: - - - The underlying file system doesn't support statvfs(2), or returns incorrect - data, or the repository doesn't reside on a single file system - - Other tasks fill the disk simultaneously - - Hard quotas (which may not be reflected in statvfs(2)) - +This chapter will get you started with |project_name| and covers +various use cases. A step by step example ---------------------- @@ -117,6 +74,47 @@ A step by step example ``--verbose`` or ``--info``) option to adjust the log level to INFO to get other informational messages. +Important note about free space +------------------------------- + +Before you start creating backups, please make sure that there is *always* +a good amount of free space on the filesystem that has your backup repository +(and also on ~/.cache). A few GB should suffice for most hard-drive sized +repositories. See also :ref:`cache-memory-usage`. + +Borg doesn't use space reserved for root on repository disks (even when run as root), +on file systems which do not support this mechanism (e.g. XFS) we recommend to +reserve some space in Borg itself just to be safe by adjusting the +``additional_free_space`` setting in the ``[repository]`` section of a repositories +``config`` file. A good starting point is ``2G``. + +If |project_name| runs out of disk space, it tries to free as much space as it +can while aborting the current operation safely, which allows to free more space +by deleting/pruning archives. This mechanism is not bullet-proof in some +circumstances [1]_. + +If you *really* run out of disk space, it can be hard or impossible to free space, +because |project_name| needs free space to operate - even to delete backup +archives. + +You can use some monitoring process or just include the free space information +in your backup log files (you check them regularly anyway, right?). + +Also helpful: + +- create a big file as a "space reserve", that you can delete to free space +- if you use LVM: use a LV + a filesystem that you can resize later and have + some unallocated PEs you can add to the LV. +- consider using quotas +- use `prune` regularly + +.. [1] This failsafe can fail in these circumstances: + + - The underlying file system doesn't support statvfs(2), or returns incorrect + data, or the repository doesn't reside on a single file system + - Other tasks fill the disk simultaneously + - Hard quotas (which may not be reflected in statvfs(2)) + Automating backups ------------------