pull-backup.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. .. include:: ../global.rst.inc
  2. .. highlight:: none
  3. .. _pull_backup:
  4. Backing up in pull mode
  5. =======================
  6. Assuming you have a pull backup system set up with borg, where a backup server
  7. pulls the data from the target via SSHFS. In this mode, the backup client's file
  8. system is mounted remotely on the backup server. Pull mode is even possible if
  9. the SSH connection must be established by the client via a remote tunnel. Other
  10. network file systems like NFS or SMB could be used as well, but SSHFS is very
  11. simple to set up and probably the most secure one.
  12. There are some restrictions caused by SSHFS. For example, unless you define UID
  13. and GID mappings when mounting via ``sshfs``, owners and groups of the mounted
  14. file system will probably change, and you may not have access to those files if
  15. BorgBackup is not run with root privileges.
  16. SSHFS is a FUSE file system and uses the SFTP protocol, so there may be also
  17. other unsupported features that the actual implementations of sshfs, libfuse and
  18. sftp on the backup server do not support, like file name encodings, ACLs, xattrs
  19. or bsdflags. So there is no guarantee that you are able to restore a system
  20. completely in every aspect from such a backup.
  21. .. warning::
  22. To mount the client's root file system you will need root access to the
  23. client. This contradicts to the usual threat model of BorgBackup, where
  24. clients don't need to trust the backup server (data is encrypted). In pull
  25. mode the server (when logged in as root) could cause unlimited damage to the
  26. client. Therefore, pull mode should be used only from servers you do fully
  27. trust!
  28. .. warning::
  29. Additionally, while being chrooted into the client's root file system,
  30. code from the client will be executed. Thus, you should only do that when
  31. fully trusting the client.
  32. .. warning::
  33. The chroot method was chosen to get the right user and group name-id
  34. mappings, assuming they only come from files (/etc/passwd and group).
  35. This assumption might be wrong, e.g. if users/groups also come from
  36. ldap or other providers.
  37. Thus, it might be better to use ``--numeric-owner`` and not archive any
  38. user or group names (but just the numeric IDs) and not use chroot.
  39. Creating a backup
  40. -----------------
  41. Generally, in a pull backup situation there is no direct way for borg to know
  42. the client's original UID:GID name mapping of files, because Borg would use
  43. ``/etc/passwd`` and ``/etc/group`` of the backup server to map the names. To
  44. derive the right names, Borg needs to have access to the client's passwd and
  45. group files and use them in the backup process.
  46. The solution to this problem is chrooting into an sshfs mounted directory. In
  47. this example the whole client root file system is mounted. We use the
  48. stand-alone BorgBackup executable and copy it into the mounted file system to
  49. make Borg available after entering chroot; this can be skipped if Borg is
  50. already installed on the client.
  51. ::
  52. # Mount client root file system.
  53. mkdir /tmp/sshfs
  54. sshfs root@host:/ /tmp/sshfs
  55. # Mount BorgBackup repository inside it.
  56. mkdir /tmp/sshfs/borgrepo
  57. mount --bind /path/to/repo /tmp/sshfs/borgrepo
  58. # Make borg executable available.
  59. cp /usr/local/bin/borg /tmp/sshfs/usr/local/bin/borg
  60. # Mount important system directories and enter chroot.
  61. cd /tmp/sshfs
  62. for i in dev proc sys; do mount --bind /$i $i; done
  63. chroot /tmp/sshfs
  64. Now we are on the backup system but inside a chroot with the client's root file
  65. system. We have a copy of Borg binary in ``/usr/local/bin`` and the repository
  66. in ``/borgrepo``. Borg will back up the client's user/group names, and we can
  67. create the backup, retaining the original paths, excluding the repository:
  68. ::
  69. borg create --exclude /borgrepo --files-cache ctime,size /borgrepo::archive /
  70. For the sake of simplicity only ``/borgrepo`` is excluded here. You may want to
  71. set up an exclude file with additional files and folders to be excluded. Also
  72. note that we have to modify Borg's file change detection behaviour – SSHFS
  73. cannot guarantee stable inode numbers, so we have to supply the
  74. ``--files-cache`` option.
  75. Finally, we need to exit chroot, unmount all the stuff and clean up:
  76. ::
  77. exit # exit chroot
  78. rm /tmp/sshfs/usr/local/bin/borg
  79. cd /tmp/sshfs
  80. for i in dev proc sys borgrepo; do umount ./$i; done
  81. rmdir borgrepo
  82. cd ~
  83. umount /tmp/sshfs
  84. rmdir /tmp/sshfs
  85. Thanks to secuser on IRC for this how-to!
  86. Restore methods
  87. ---------------
  88. The counterpart of a pull backup is a push restore. Depending on the type of
  89. restore – full restore or partial restore – there are different methods to make
  90. sure the correct IDs are restored.
  91. Partial restore
  92. ~~~~~~~~~~~~~~~
  93. In case of a partial restore, using the archived UIDs/GIDs might lead to wrong
  94. results if the name-to-ID mapping on the target system has changed compared to
  95. backup time (might be the case e.g. for a fresh OS install).
  96. The workaround again is chrooting into an sshfs mounted directory, so Borg is
  97. able to map the user/group names of the backup files to the actual IDs on the
  98. client. This example is similar to the backup above – only the Borg command is
  99. different:
  100. ::
  101. # Mount client root file system.
  102. mkdir /tmp/sshfs
  103. sshfs root@host:/ /tmp/sshfs
  104. # Mount BorgBackup repository inside it.
  105. mkdir /tmp/sshfs/borgrepo
  106. mount --bind /path/to/repo /tmp/sshfs/borgrepo
  107. # Make borg executable available.
  108. cp /usr/local/bin/borg /tmp/sshfs/usr/local/bin/borg
  109. # Mount important system directories and enter chroot.
  110. cd /tmp/sshfs
  111. for i in dev proc sys; do mount --bind /$i $i; done
  112. chroot /tmp/sshfs
  113. Now we can run
  114. ::
  115. borg extract /borgrepo::archive PATH
  116. to partially restore whatever we like. Finally, do the clean-up:
  117. ::
  118. exit # exit chroot
  119. rm /tmp/sshfs/usr/local/bin/borg
  120. cd /tmp/sshfs
  121. for i in dev proc sys borgrepo; do umount ./$i; done
  122. rmdir borgrepo
  123. cd ~
  124. umount /tmp/sshfs
  125. rmdir /tmp/sshfs
  126. Full restore
  127. ~~~~~~~~~~~~
  128. When doing a full restore, we restore all files (including the ones containing
  129. the ID-to-name mapping, ``/etc/passwd`` and ``/etc/group``). Everything will be
  130. consistent automatically if we restore the numeric IDs stored in the archive. So
  131. there is no need for a chroot environment; we just mount the client file system
  132. and extract a backup, utilizing the ``--numeric-owner`` option:
  133. ::
  134. sshfs root@host:/ /mnt/sshfs
  135. cd /mnt/sshfs
  136. borg extract --numeric-owner /path/to/repo::archive
  137. cd ~
  138. umount /mnt/sshfs
  139. Simple (lossy) full restore
  140. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  141. Using ``borg export-tar`` it is possible to stream a backup to the client and
  142. directly extract it without the need of mounting with SSHFS:
  143. ::
  144. borg export-tar /path/to/repo::archive - | ssh root@host 'tar -C / -x'
  145. Note that in this scenario the tar format is the limiting factor – it cannot
  146. restore all the advanced features that BorgBackup supports. See
  147. :ref:`borg_export-tar` for limitations.
  148. ssh-agent
  149. =========
  150. In this scenario *borg-server* initiates an SSH connection to *borg-client* and forwards the authentication
  151. agent connection.
  152. After that, it works similar to the push mode:
  153. *borg-client* initiates another SSH connection back to *borg-server* using the forwarded authentication agent
  154. connection to authenticate itself, starts ``borg serve`` and communicates with it.
  155. Using this method requires ssh access of user *borgs* to *borgc@borg-client*, where:
  156. * *borgs* is the user on the server side with read/write access to local borg repository.
  157. * *borgc* is the user on the client side with read access to files meant to be backed up.
  158. Applying this method for automated backup operations
  159. ----------------------------------------------------
  160. Assume that the borg-client host is untrusted.
  161. Therefore we do some effort to prevent a hostile user on the borg-client side to do something harmful.
  162. In case of a fully trusted borg-client the method could be simplified.
  163. Preparing the server side
  164. ~~~~~~~~~~~~~~~~~~~~~~~~~
  165. Do this once for each client on *borg-server* to allow *borgs* to connect itself on *borg-server* using a
  166. dedicated ssh key:
  167. ::
  168. borgs@borg-server$ install -m 700 -d ~/.ssh/
  169. borgs@borg-server$ ssh-keygen -N '' -t rsa -f ~/.ssh/borg-client_key
  170. borgs@borg-server$ { echo -n 'command="borg serve --append-only --restrict-to-repo ~/repo",restrict '; cat ~/.ssh/borg-client_key.pub; } >> ~/.ssh/authorized_keys
  171. borgs@borg-server$ chmod 600 ~/.ssh/authorized_keys
  172. ``install -m 700 -d ~/.ssh/``
  173. Create directory ~/.ssh with correct permissions if it does not exist yet.
  174. ``ssh-keygen -N '' -t rsa -f ~/.ssh/borg-client_key``
  175. Create an ssh key dedicated to communication with borg-client.
  176. .. note::
  177. Another more complex approach is using a unique ssh key for each pull operation.
  178. This is more secure as it guarantees that the key will not be used for other purposes.
  179. ``{ echo -n 'command="borg serve --append-only --restrict-to-repo ~/repo",restrict '; cat ~/.ssh/borg-client_key.pub; } >> ~/.ssh/authorized_keys``
  180. Add borg-client's ssh public key to ~/.ssh/authorized_keys with forced command and restricted mode.
  181. The borg client is restricted to use one repo at the specified path and to append-only operation.
  182. Commands like *delete*, *prune* and *compact* have to be executed another way, for example directly on *borg-server*
  183. side or from a privileged, less restricted client (using another authorized_keys entry).
  184. ``chmod 600 ~/.ssh/authorized_keys``
  185. Fix permissions of ~/.ssh/authorized_keys.
  186. Pull operation
  187. ~~~~~~~~~~~~~~
  188. Initiating borg command execution from *borg-server* (e.g. init)::
  189. borgs@borg-server$ (
  190. eval $(ssh-agent) > /dev/null
  191. ssh-add -q ~/.ssh/borg-client_key
  192. echo 'your secure borg key passphrase' | \
  193. ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) borg --rsh 'ssh -o StrictHostKeyChecking=no' init --encryption repokey ssh://borgs@borg-server/~/repo"
  194. kill "${SSH_AGENT_PID}"
  195. )
  196. Parentheses around commands are needed to avoid interference with a possibly already running ssh-agent.
  197. Parentheses are not needed when using a dedicated bash process.
  198. ``eval $(ssh-agent) > /dev/null``
  199. Run the SSH agent in the background and export related environment variables to the current bash session.
  200. ``ssh-add -q ~/.ssh/borg-client_key``
  201. Load the SSH private key dedicated to communication with the borg-client into the SSH agent.
  202. Look at ``man 1 ssh-add`` for a more detailed explanation.
  203. .. note::
  204. Care needs to be taken when loading keys into the SSH agent. Users on the *borg-client* having read/write permissions
  205. to the agent's UNIX-domain socket (at least borgc and root in our case) can access the agent on *borg-server* through
  206. the forwarded connection and can authenticate using any of the identities loaded into the agent
  207. (look at ``man 1 ssh`` for more detailed explanation). Therefore there are some security considerations:
  208. * Private keys loaded into the agent must not be used to enable access anywhere else.
  209. * The keys meant to be loaded into the agent must be specified explicitly, not from default locations.
  210. * The *borg-client*'s entry in *borgs@borg-server:~/.ssh/authorized_keys* must be as restrictive as possible.
  211. ``echo 'your secure borg key passphrase' | ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) borg --rsh 'ssh -o StrictHostKeyChecking=no' init --encryption repokey ssh://borgs@borg-server/~/repo"``
  212. Run the *borg init* command on *borg-client*.
  213. *ssh://borgs@borg-server/~/repo* refers to the repository *repo* within borgs's home directory on *borg-server*.
  214. *StrictHostKeyChecking=no* is used to automatically add host keys to *~/.ssh/known_hosts* without user intervention.
  215. ``kill "${SSH_AGENT_PID}"``
  216. Kill ssh-agent with loaded keys when it is not needed anymore.