Merge pull request #4323 from ThomasWaldmann/backports-14

1.1-maint backports (14)

docs/changes.rst

@@ -632,6 +632,9 @@ Compatibility notes:
   unexpected) was rather confusing and unexplainable at first to users.
   If you want that "do not backup NODUMP-flagged files" behaviour, use:
   borg create --exclude-nodump ...
+- If you are on Linux and do not need bsdflags archived, consider using
+  ``--nobsdflags`` with ``borg create`` to avoid additional syscalls and
+  speed up backup creation.
 
 Fixes:
 

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
 ------------------
 
@@ -179,16 +219,14 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
     # use highest exit code as global exit code
     global_exit=$(( backup_exit > prune_exit ? backup_exit : prune_exit ))
 
-    if [ ${global_exit} -eq 1 ];
-    then
-        info "Backup and/or Prune finished with a warning"
+    if [ ${global_exit} -eq 0 ]; then
+        info "Backup and Prune finished successfully"
+    elif [ ${global_exit} -eq 1 ]; then
+        info "Backup and/or Prune finished with warnings"
+    else
+        info "Backup and/or Prune finished with errors"
     fi
-
-    if [ ${global_exit} -gt 1 ];
-    then
-        info "Backup and/or Prune finished with an error"
-    fi
-
+    
     exit ${global_exit}
 
 Pitfalls with shell variables and environment variables