docs: add opendal services (#90)

Add basic service documentation for using opendal. Ref.: rustic-rs/rustic#1278 --------- Signed-off-by: simonsan <[email protected]> Co-authored-by: Alexander Weiss <[email protected]>
rustic-rs · Oct 1, 2024 · 48b20a6 · 48b20a6
1 parent ff43adf
commit 48b20a6
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 4 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -13,7 +13,8 @@
   - [Configuration File](./commands/init/configuration_file.md)
   - [Local Backend](./commands/init/local.md)
   - [REST Server](./commands/init/rest.md)
-  - [Other Services via rclone](./commands/init/rclone.md)
+  - [Supported Services](./commands/init/services.md)
+    - [Other Services via rclone](./commands/init/rclone.md)
   - [Cold Storage](./commands/init/cold_storage.md)
 - [Backing up data](./commands/backup/intro.md)
   - [Creating snapshots](./commands/backup/creating_snapshots.md)

diff --git a/src/commands/init/rclone.md b/src/commands/init/rclone.md
@@ -44,12 +44,20 @@ $ rclone ls b2prod:yggdrasil/foo/bar/baz
     448 bar/baz/keys/4bf9c78049de689d73a56ed0546f83b8416795295cda12ec7fb9465af3900b44
 ```
 
-Rclone can be `configured with environment variables`_, so for instance
-configuring a bandwidth limit for rclone can be achieved by setting the
-`RCLONE_BWLIMIT` environment variable:
+Rclone can be configured with environment variables prefixed by `RCLONE_`, so
+for instance configuring a bandwidth limit for rclone can be achieved by setting
+the `RCLONE_BWLIMIT` environment variable:
 
 ```console
 export RCLONE_BWLIMIT=1M
 ```
 
+As rustic allows to set environment variables in the config profile, you can
+alternatively use:
+
+```toml
+[global.env]
+RCLONE_BWLIMIT = "1M"
+```
+
 For debugging rclone, you can set the environment variable `RCLONE_VERBOSE=2`.
diff --git a/src/commands/init/services.md b/src/commands/init/services.md
@@ -0,0 +1,62 @@
+# Supported Services
+
+rustic integrates `opendal`, a data access layer for many different services.
+The following services are supported:
+
+| Service Name                  | Postfix    |
+| ----------------------------- | ---------- |
+| Backblaze B2                  | `b2`       |
+| SFTP                          | `sftp`     |
+| OpenStack Swift               | `swift`    |
+| Azure Blob Storage            | `azblob`   |
+| Azure Data Lake Storage Gen2  | `azdls`    |
+| Azure File Storage            | `azfile`   |
+| Tencent Cloud Object Storage  | `cos`      |
+| Local Filesystem              | `fs`       |
+| FTP                           | `ftp`      |
+| Dropbox                       | `dropbox`  |
+| Google Drive                  | `gdrive`   |
+| Google Cloud Storage          | `gcs`      |
+| GitHub Actions Cache          | `ghac`     |
+| HTTP                          | `http`     |
+| IPFS based on IPFS MFS API    | `ipmfs`    |
+| In-memory storage             | `memory`   |
+| Huawei Cloud OBS              | `obs`      |
+| Microsoft OneDrive            | `onedrive` |
+| Aliyun Object Storage Service | `oss`      |
+| Amazon S3                     | `s3`       |
+| WebDAV                        | `webdav`   |
+| WebHDFS                       | `webhdfs`  |
+
+## Configuration
+
+The configuration for the services is done via the `rustic` configuration file.
+
+For example, to configure the `Amazon S3` service, you would add the following
+to the configuration file:
+
+```toml
+[repository]
+repository = "opendal:s3"
+password = "password"
+
+# Other options can be given here - note that opendal also support reading config from env
+# files or AWS config dirs, see the opendal S3 docs for more information
+# https://opendal.apache.org/docs/rust/opendal/services/struct.S3.html
+[repository.options]
+access_key_id = "xxx" # this can be ommited, when AWS config is used
+secret_access_key = "xxx" # this can be ommited, when AWS config is used
+bucket = "bucket_name"
+root = "/path/to/repo"
+```
+
+`opendal` is used to access the services. The `s3` postfix is used to specify
+the `Amazon S3` service. For other services, the postfix is replaced with the
+respective service postfix.
+
+You can find more service templates in the
+[rustic repository](https://github.com/rustic-rs/rustic/tree/main/config).
+
+To see the service-dependent options to be set in `[repository.options]`, please
+refer to the
+[opendal service documentation](https://opendal.apache.org/docs/rust/opendal/services/).