From 97eb3892746bda3b814433f63c1448c20812520d Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Thu, 15 Jun 2023 12:59:04 +0100 Subject: docs/apps: Added ejabberd section. --- doc/book/connect/apps/index.md | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md index 4d556ff8..5e4b9223 100644 --- a/doc/book/connect/apps/index.md +++ b/doc/book/connect/apps/index.md @@ -11,6 +11,7 @@ In this section, we cover the following web applications: | [Peertube](#peertube) | ✅ | Supported with the website endpoint, proxifying private videos unsupported | | [Mastodon](#mastodon) | ✅ | Natively supported | | [Matrix](#matrix) | ✅ | Tested with `synapse-s3-storage-provider` | +| [ejabberd](#ejabberd) | ✅ | `mod_s3_upload` | | [Pixelfed](#pixelfed) | ❓ | Not yet tested | | [Pleroma](#pleroma) | ❓ | Not yet tested | | [Lemmy](#lemmy) | ✅ | Supported with pict-rs | @@ -474,6 +475,52 @@ And add a new line. For example, to run it every 10 minutes: *External link:* [matrix-media-repo Documentation > S3](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html) +## ejabberd + +ejabberd is an XMPP server implementation which, with the `mod_s3_upload` +module in the [ejabberd-contrib](https://github.com/processone/ejabberd-contrib) +repository, can be integrated to store chat media files in Garage. + +For uploads, this module leverages presigned URLs - this allows XMPP clients to +directly send media to Garage. Receiving clients then retrieve this media +through the [static website](@/documentation/cookbook/exposing-websites.md) +functionality. + +As the data itself is publicly accessible to someone with knowledge of the +object URL - users are recommended to use +[E2EE](@/documentation/cookbook/encryption.md) to protect this data-at-rest +from unauthorized access. + +Install the module with: + +```bash +ejabberdctl module_install mod_s3_upload +``` + +Create the required key and bucket with: + +```bash +garage key new --name ejabberd +garage bucket create objects.xmpp-server.fr +garage bucket allow objects.xmpp-server.fr --read --write --key ejabberd +garage bucket website --allow objects.xmpp-server.fr +``` + +The module can then be configured with: + +``` + mod_s3_upload: + #bucket_url: https://objects.xmpp-server.fr.my-garage-instance.mydomain.tld + bucket_url: https://my-garage-instance.mydomain.tld/objects.xmpp-server.fr + access_key_id: GK... + access_key_secret: ... + region: garage + download_url: https://objects.xmpp-server.fr +``` + +Other configuration options can be found in the +[configuration YAML file](https://github.com/processone/ejabberd-contrib/blob/master/mod_s3_upload/conf/mod_s3_upload.yml). + ## Pixelfed [Pixelfed Technical Documentation > Configuration](https://docs.pixelfed.org/technical-documentation/env.html#filesystem) -- cgit v1.2.3 From 6af2cde23f5229302f122453aa50bf15df7625b4 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Thu, 15 Jun 2023 12:59:21 +0100 Subject: cookbook/encryption.md: Added note on XMPP. --- doc/book/cookbook/encryption.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/book/cookbook/encryption.md b/doc/book/cookbook/encryption.md index 8d45a0ee..09438549 100644 --- a/doc/book/cookbook/encryption.md +++ b/doc/book/cookbook/encryption.md @@ -104,5 +104,8 @@ Implementations are very specific to the various applications. Examples: in Matrix are probably encrypted using symmetric encryption, with a key that is distributed in the end-to-end encrypted message that contains the link to the object. -- Aerogramme: use the user's password as a key to decrypt data in the user's bucket +- XMPP: clients normally support either OMEMO / OpenPGP for the E2EE of user + messages. Media files are encrypted per + [XEP-0454](https://xmpp.org/extensions/xep-0454.html). +- Aerogramme: use the user's password as a key to decrypt data in the user's bucket -- cgit v1.2.3 From fb971a5f01547516e9850f0fd34e42ad1d67c777 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Thu, 15 Jun 2023 15:42:12 +0100 Subject: cookbook/encryption.md: Added Cyberduck note. --- doc/book/cookbook/encryption.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/book/cookbook/encryption.md b/doc/book/cookbook/encryption.md index 09438549..21a5cbc6 100644 --- a/doc/book/cookbook/encryption.md +++ b/doc/book/cookbook/encryption.md @@ -109,3 +109,8 @@ Implementations are very specific to the various applications. Examples: [XEP-0454](https://xmpp.org/extensions/xep-0454.html). - Aerogramme: use the user's password as a key to decrypt data in the user's bucket + +- Cyberduck: comes with support for + [Cryptomator](https://docs.cyberduck.io/cryptomator/) which allows users to + create client-side vaults to encrypt files in before they are uploaded to a + cloud storage endpoint. -- cgit v1.2.3 From 185f9e78f3c2ba80424e9e9c7c8ffc58a005c91b Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Thu, 15 Jun 2023 17:57:14 +0100 Subject: operations/durability-repairs.md: Added note about randomized scrub times. --- doc/book/operations/durability-repairs.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/book/operations/durability-repairs.md b/doc/book/operations/durability-repairs.md index b8992f85..79888a5a 100644 --- a/doc/book/operations/durability-repairs.md +++ b/doc/book/operations/durability-repairs.md @@ -26,8 +26,11 @@ their content is correct, by verifying their hash. Any block found to be corrupt (e.g. by bitrot or by an accidental manipulation of the datastore) will be restored from another node that holds a valid copy. -A scrub is run automatically by Garage every 30 days. It can also be launched -manually using `garage repair scrub start`. +Scrubs are automatically scheduled by Garage to run every 25-35 days (the +actual time is randomized to spread load across nodes). The next scheduled run +can be viewed with `garage worker get`. + +A scrub can also be launched manually using `garage repair scrub start`. To view the status of an ongoing scrub, first find the task ID of the scrub worker using `garage worker list`. Then, run `garage worker info ` to @@ -79,7 +82,7 @@ To help make the difference between cases 1 and cases 2 and 3, you may use the `garage block info` command to see which objects hold a reference to each block. In the second case (transient errors), Garage will try to fetch the block again -after a certain time, so the error should disappear natuarlly. You can also +after a certain time, so the error should disappear naturally. You can also request Garage to try to fetch the block immediately using `garage block retry-now` if you have fixed the transient issue. -- cgit v1.2.3 From a5ae566e0be487553839c843ffde4909a8146b4a Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Thu, 15 Jun 2023 18:06:22 +0100 Subject: apps/index.md: Fixed endpoint URL example. --- doc/book/connect/apps/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md index 5e4b9223..83aadec2 100644 --- a/doc/book/connect/apps/index.md +++ b/doc/book/connect/apps/index.md @@ -586,7 +586,7 @@ secret_key = 'abcdef0123456789...' ``` PICTRS__STORE__TYPE=object_storage -PICTRS__STORE__ENDPOINT=http:/my-garage-instance.mydomain.tld:3900 +PICTRS__STORE__ENDPOINT=http://my-garage-instance.mydomain.tld:3900 PICTRS__STORE__BUCKET_NAME=pictrs-data PICTRS__STORE__REGION=garage PICTRS__STORE__ACCESS_KEY=GK... -- cgit v1.2.3