From 806d937c2e5ce9a34af240c5e64276ff6a7bc131 Mon Sep 17 00:00:00 2001
From: James Vasile <211863+jvasile@users.noreply.github.com>
Date: Thu, 1 Nov 2018 16:11:05 -0400
Subject: [PATCH] 4081 - Add note about files changing during backup (#4116)

Add note about files changing during backup
---
 docs/quickstart.rst | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 70176dbfa..5e6eb1072 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -95,6 +95,46 @@ borg.
 If you need to access a local repository from different users, you can use the
 same method by using ssh to borg@localhost.
 
+Important note about files changing during the backup process
+-------------------------------------------------------------
+
+Borg does not do anything about the internal consistency of the data
+it backs up.  It just reads and backs up each file in whatever state
+that file is when Borg gets to it.  On an active system, this can lead
+to two kinds of inconsistency:
+
+- By the time Borg backs up a file, it might have changed since the backup process was initiated
+- A file could change while Borg is backing it up, making the file internally inconsistent
+
+If you have a set of files and want to ensure that they are backed up
+in a specific or consistent state, you must take steps to prevent
+changes to those files during the backup process.  There are a few
+common techniques to achieve this.
+
+- Avoid running any programs that might change the files.
+
+- Snapshot files, filesystems, container storage volumes, or logical volumes.  LVM or ZFS might be useful here.
+
+- Dump databases or stop the database servers.
+
+- Shut down virtual machines before backing up their images.
+
+- Shut down containers before backing up their storage volumes.
+
+For some systems Borg might work well enough without these
+precautions.  If you are simply backing up the files on a system that
+isn't very active (e.g. in a typical home directory), Borg usually
+works well enough without further care for consistency.  Log files and
+caches might not be in a perfect state, but this is rarely a problem.
+
+For databases, virtual machines, and containers, there are specific
+techniques for backing them up that do not simply use Borg to backup
+the underlying filesystem.  For databases, check your database
+documentation for techniques that will save the database state between
+transactions.  For virtual machines, consider running the backup on
+the VM itself or mounting the filesystem while the VM is shut down.
+For Docker containers, perhaps docker's "save" command can help.
+
 Automating backups
 ------------------