From 13fe8027131178bbfecd16212d836e2de8bf9ee6 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Fri, 9 Jun 2017 16:01:01 +0200 Subject: [PATCH] docs: deployment: hosting repositories --- docs/deployment.rst | 1 + docs/deployment/hosting-repositories.rst | 73 ++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/deployment/hosting-repositories.rst diff --git a/docs/deployment.rst b/docs/deployment.rst index c4e1ef3be..e4fc728a5 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -10,3 +10,4 @@ This chapter details deployment strategies for the following scenarios. :titlesonly: deployment/central-backup-server + deployment/hosting-repositories diff --git a/docs/deployment/hosting-repositories.rst b/docs/deployment/hosting-repositories.rst new file mode 100644 index 000000000..e502d644f --- /dev/null +++ b/docs/deployment/hosting-repositories.rst @@ -0,0 +1,73 @@ +.. include:: ../global.rst.inc +.. highlight:: none + +Hosting repositories +==================== + +This sections shows how to securely provide repository storage for users. +Optionally, each user can have a storage quota. + +Repositories are accessed through SSH. Each user of the service should +have her own login which is only able to access the user's files. +Technically it would be possible to have multiple users share one login, +however, separating them is better. Separate logins increase isolation +and are thus an additional layer of security and safety for both the +provider and the users. + +For example, if a user manages to breach ``borg serve`` then she can +only damage her own data (assuming that the system does not have further +vulnerabilities). + +Use the standard directory structure of the operating system. Each user +is assigned a home directory and repositories of the user reside in her +home directory. + +The following ``~user/.ssh/authorized_keys`` file is the most important +piece for a correct deployment. It allows the user to login via +their public key (which must be provided by the user), and restricts +SSH access to safe operations only. + +:: + + restrict,command="borg serve --restrict-to-repository /home//repository" + + +.. note:: The text shown above needs to be written on a **single** line! + +.. warning:: + + If this file should be automatically updated (e.g. by a web console), + pay **utmost attention** to sanitizing user input. Strip all whitespace + around the user-supplied key, ensure that it **only** contains ASCII + with no control characters and that it consists of three parts separated + by a single space. Ensure that no newlines are contained within the key. + +The `restrict` keyword enables all restrictions, i.e. disables port, agent +and X11 forwarding, as well as disabling PTY allocation and execution of ~/.ssh/rc. +If any future restriction capabilities are added to authorized_keys +files they will be included in this set. + +The `command` keyword forces execution of the specified command line +upon login. This must be ``borg serve``. The `--restrict-to-repository` +option permits access to exactly **one** repository. It can be given +multiple times to permit access to more than one repository. + +The repository may not exist yet; it can be initialized by the user, +which allows for encryption. + +Storage quotas can be enabled by adding the ``--storage-quota`` option +to the ``borg serve`` command line:: + + restrict,command="borg serve --storage-quota 20G ..." ... + +The storage quotas of repositories are completely independent. If a +client is able to access multiple repositories, each repository +can be filled to the specified quota. + +If storage quotas are used, ensure that all deployed Borg releases +support storage quotas. + +Refer to :ref:`internals_storage_quota` for more details on storage quotas. + +Refer to the `sshd(8) `_ +for more details on securing SSH.