diff --git a/docs/deployment.rst b/docs/deployment.rst index c7c3a6ee1..3d4605b2b 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -13,3 +13,4 @@ This chapter details deployment strategies for the following scenarios. deployment/hosting-repositories deployment/automated-local deployment/image-backup + deployment/pull-backup diff --git a/docs/deployment/pull-backup.rst b/docs/deployment/pull-backup.rst new file mode 100644 index 000000000..15d4dddd2 --- /dev/null +++ b/docs/deployment/pull-backup.rst @@ -0,0 +1,176 @@ +.. include:: ../global.rst.inc +.. highlight:: none + +Backing up in pull mode +======================= + +Assuming you have a pull backup system set up with borg, where a backup server +pulls the data from the target via SSHFS. In this mode, the backup client's file +system is mounted remotely on the backup server. Pull mode is even possible if +the SSH connection must be established by the client via a remote tunnel. Other +network file systems like NFS or SMB could be used as well, but SSHFS is very +simple to set up and probably the most secure one. + +There are some restrictions caused by SSHFS. For example, unless you define UID +and GID mappings when mounting via ``sshfs``, owners and groups of the mounted +file system will probably change, and you may not have access to those files if +BorgBackup is not run with root privileges. + +SSHFS is a FUSE file system and uses the SFTP protocol, so there may be also +other unsupported features that the actual implementations of ssfs, libfuse and +sftp on the backup server do not support, like file name encodings, ACLs, xattrs +or bsdflags. So there is no guarantee that you are able to restore a system +completely in every aspect from such a backup. + +.. warning:: + + To mount the client's root file system you will need root access to the + client. This contradicts to the usual threat model of BorgBackup, where + clients don't need to trust the backup server (data is encrypted). In pull + mode the server (when logged in as root) could cause unlimited damage to the + client. Therefore, pull mode should be used only from servers you do fully + trust! + +Creating a backup +----------------- + +Generally, in a pull backup situation there is no direct way for borg to know +the client's original UID:GID name mapping of files, because Borg would use +``/etc/passwd`` and ``/etc/group`` of the backup server to map the names. To +derive the right names, Borg needs to have access to the client's passwd and +group files and use them in the backup process. + +The solution to this problem is chrooting into an sshfs mounted directory. In +this example the whole client root file system is mounted. We use the +stand-alone BorgBackup executable and copy it into the mounted file system to +make Borg available after entering chroot; this can be skipped if Borg is +already installed on the client. + +:: + + # Mount client root file system. + mkdir /tmp/sshfs + sshfs root@host:/ /tmp/sshfs + # Mount BorgBackup repository inside it. + mkdir /tmp/sshfs/borgrepo + mount --bind /path/to/repo /tmp/sshfs/borgrepo + # Make borg executable available. + cp /usr/local/bin/borg /tmp/sshfs/usr/local/bin/borg + # Mount important system directories and enter chroot. + cd /tmp/sshfs + for i in dev proc sys; do mount --bind /$i $i; done + chroot /tmp/sshfs + +Now we are on the backup system but inside a chroot with the client's root file +system. We have a copy of Borg binary in ``/usr/local/bin`` and the repository +in ``/borgrepo``. Borg will back up the client's user/group names, and we can +create the backup, retaining the original paths, excluding the repository: + +:: + + borg create --exclude /borgrepo --files-cache ctime,size /borgrepo::archive / + +For the sake of simplicity only ``/borgrepo`` is excluded here. You may want to +set up an exclude file with additional files and folders to be excluded. Also +note that we have to modify Borg's file change detection behaviour – SSHFS +cannot guarantee stable inode numbers, so we have to supply the +``--files-cache`` option. + +Finally, we need to exit chroot, unmount all the stuff and clean up: + +:: + + exit # exit chroot + rm /tmp/sshfs/usr/local/bin/borg + cd /tmp/sshfs + for i in dev proc sys borgrepo; do umount ./$i; done + rmdir borgrepo + cd ~ + umount /tmp/sshfs + rmdir /tmp/sshfs + +Thanks to secuser on IRC for this how-to! + +Restore methods +--------------- + +The counterpart of a pull backup is a push restore. Depending on the type of +restore – full restore or partial restore – there are different methods to make +sure the correct IDs are restored. + +Partial restore +~~~~~~~~~~~~~~~ + +In case of a partial restore, using the archived UIDs/GIDs might lead to wrong +results if the name-to-ID mapping on the target system has changed compared to +backup time (might be the case e.g. for a fresh OS install). + +The workaround again is chrooting into an sshfs mounted directory, so Borg is +able to map the user/group names of the backup files to the actual IDs on the +client. This example is similar to the backup above – only the Borg command is +different: + +:: + + # Mount client root file system. + mkdir /tmp/sshfs + sshfs root@host:/ /tmp/sshfs + # Mount BorgBackup repository inside it. + mkdir /tmp/sshfs/borgrepo + mount --bind /path/to/repo /tmp/sshfs/borgrepo + # Make borg executable available. + cp /usr/local/bin/borg /tmp/sshfs/usr/local/bin/borg + # Mount important system directories and enter chroot. + cd /tmp/sshfs + for i in dev proc sys; do mount --bind /$i $i; done + chroot /tmp/sshfs + +Now we can run + +:: + + borg extract /borgrepo::archive PATH + +to partially restore whatever we like. Finally, do the clean-up: + +:: + + exit # exit chroot + rm /tmp/sshfs/usr/local/bin/borg + cd /tmp/sshfs + for i in dev proc sys borgrepo; do umount ./$i; done + rmdir borgrepo + cd ~ + umount /tmp/sshfs + rmdir /tmp/sshfs + +Full restore +~~~~~~~~~~~~ + +When doing a full restore, we restore all files (including the ones containing +the ID-to-name mapping, ``/etc/passwd`` and ``/etc/group``). Everything will be +consistent automatically if we restore the numeric IDs stored in the archive. So +there is no need for a chroot environment; we just mount the client file system +and extract a backup, utilizing the ``--numeric-owner`` option: + +:: + + sshfs root@host:/ /mnt/sshfs + cd /mnt/sshfs + borg extract --numeric-owner /path/to/repo::archive + cd ~ + umount /mnt/sshfs + +Simple (lossy) full restore +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using ``borg export-tar`` it is possible to stream a backup to the client and +directly extract it without the need of mounting with SSHFS: + +:: + + borg export-tar /path/to/repo::archive - | ssh root@host 'tar -C / -x' + +Note that in this scenario the tar format is the limiting factor – it cannot +restore all the advanced features that BorgBackup supports. See +:ref:`borg_export-tar` for limitations.