Create backup action

actions.yaml

@@ -41,3 +41,6 @@ promote-user-admin:
       description: |
         User name to be promoted to admin.
       type: string
+create-backup:
+  description: |
+    Creates a backup to s3 storage.

config.yaml

@@ -8,6 +8,9 @@ options:
     description: |
       Allows any other homeserver to fetch the server's public rooms directory
       via federation.
+  backup_passphrase:
+    type: string
+    description: Passphrase used to encrypt a backup using gpg with symmetric key.
   enable_mjolnir:
     type: boolean
     default: false

docs/how-to/backup.md

@@ -0,0 +1,36 @@
+# How to back up Synapse
+
+This document shows how to back up Synapse.
+
+## Deploy s3-integrator charm
+
+Synapse gets backed up to a S3 compatible object storage. To get the credentials, the `s3-integrator` is used. Refer to
+[s3-integrator](https://charmhub.io/s3-integrator/) for specific configuration options.
+
+```
+juju deploy s3-integrator --channel edge
+juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<optional-path> region=<region> s3-uri-style=<path or host>
+juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
+```
+
+Integrate with Synapse with:
+
+`juju integrate synapse:backup s3-integrator`
+
+## Configure the passphrase
+
+The backup will be encrypted before being sent using symmetric encryption. You need
+to set the desired password with:
+```
+juju config synapse backup_passphrase=<secret passphase>
+```
+
+## Run the backup
+
+Run the backup with the next command:
+```
+juju run synapse/leader create-backup
+```
+
+A new object should be placed in the S3 compatible object storage. This file is a tar
+file encrypted with the `gpg` command.

src-docs/backup.py.md

@@ -5,14 +5,149 @@
 # <kbd>module</kbd> `backup.py`
 Provides backup functionality for Synapse. 
 
+**Global Variables**
+---------------
+- **AWS_COMMAND**
+- **BACKUP_FILE_PATTERNS**
+- **MEDIA_DIR**
+- **LOCAL_DIR_PATTERN**
+- **S3_MAX_CONCURRENT_REQUESTS**
+- **PASSPHRASE_FILE**
+- **BASH_COMMAND**
+- **BACKUP_ID_FORMAT**
+
+---
+
+<a href="../src/backup.py#L162"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `paths_to_args`
+
+```python
+paths_to_args(paths: Iterable[str]) → str
+```
+
+Given a list of paths, quote and concatenate them for use as cli arguments. 
+
+
+
+**Args:**
+
+ - <b>`paths`</b>:  List of paths 
+
+
+
+**Returns:**
+ paths concatenated and quoted 
+
+
+---
+
+<a href="../src/backup.py#L174"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `get_paths_to_backup`
+
+```python
+get_paths_to_backup(container: Container) → Iterable[str]
+```
+
+Get the list of paths that should be in a backup for Synapse. 
+
+
+
+**Args:**
+
+ - <b>`container`</b>:  Synapse Container. 
+
+
+
+**Returns:**
+ Iterable with the list of paths to backup. 
+
+
+---
+
+<a href="../src/backup.py#L193"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `calculate_size`
+
+```python
+calculate_size(container: Container, paths: Iterable[str]) → int
+```
+
+Return the combined size of all the paths given. 
+
+
+
+**Args:**
+
+ - <b>`container`</b>:  Container where to check the size of the paths. 
+ - <b>`paths`</b>:  Paths to check. 
+
+
+
+**Returns:**
+ Total size in bytes. 
+
+
+
+**Raises:**
+
+ - <b>`BackupError`</b>:  If there was a problem calculating the size. 
+
+
+---
+
+<a href="../src/backup.py#L315"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `create_backup`
+
+```python
+create_backup(
+    container: Container,
+    s3_parameters: S3Parameters,
+    passphrase: str,
+    backup_id: Optional[str] = None
+) → str
+```
+
+Create a backup for Synapse running it in the workload. 
+
+
+
+**Args:**
+
+ - <b>`container`</b>:  Synapse Container 
+ - <b>`s3_parameters`</b>:  S3 parameters for the backup. 
+ - <b>`passphrase`</b>:  Passphrase use to encrypt the backup. 
+ - <b>`backup_id`</b>:  Name of the object in the backup.  It will be autogenerated if it is not set. 
+
+
+
+**Returns:**
+ The backup key used for the backup. 
+
+
+
+**Raises:**
+
+ - <b>`BackupError`</b>:  If there was an error creating the backup. 
+
+
+---
+
+## <kbd>class</kbd> `BackupError`
+Generic backup Exception. 
+
+
+
 
 
 ---
 
 ## <kbd>class</kbd> `S3Client`
 S3 Client Wrapper around boto3 library. 
 
-<a href="../src/backup.py#L77"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L106"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `__init__`
 
@@ -33,7 +168,7 @@ Initialize the S3 client.
 
 ---
 
-<a href="../src/backup.py#L116"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L145"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `can_use_bucket`
 
@@ -87,7 +222,7 @@ Translates s3_uri_style to AWS addressing_style.
 
 ---
 
-<a href="../src/backup.py#L44"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L73"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>classmethod</kbd> `check_endpoint_or_region_set`
 

src-docs/backup_observer.py.md

@@ -16,7 +16,7 @@ S3 Backup relation observer for Synapse.
 ## <kbd>class</kbd> `BackupObserver`
 The S3 backup relation observer. 
 
-<a href="../src/backup_observer.py#L25"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup_observer.py#L28"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `__init__`