Rclone documentation

docs/clients/rclone/_index.md

@@ -0,0 +1,25 @@
+---
+title: Rclone
+date: 2021-11-17T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/clients/rclone
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## About Rclone
+
+{{< hint ok >}}
+Rclone is a command line program to manage files on cloud storage. It is a feature rich alternative to cloud vendors' web storage interfaces. Over 40 cloud storage products support rclone including S3 object stores, business & consumer file storage services, as well as standard transfer protocols.
+
+Rclone has powerful cloud equivalents to the unix commands rsync, cp, mv, mount, ls, ncdu, tree, rm, and cat. Rclone's familiar syntax includes shell pipeline support, and --dry-run protection. It is used at the command line, in scripts or via its API.
+
+Users call rclone "The Swiss army knife of cloud storage", and "Technology indistinguishable from magic".
+{{< /hint >}}
+
+Source: [Rclone project website](https://rclone.org/)
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/clients/rclone/webdav-sync-basic-auth.md

@@ -0,0 +1,46 @@
+---
+title: WebDAV with Basic Authentication
+date: 2021-11-17T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/clients/rclone
+geekdocFilePath: webdav-sync-basic-auth.md
+geekdocCollapseSection: true
+---
+
+
+## WebDAV with Basic Authentication
+
+{{< hint danger >}}
+Basic Authentication is disabled by default in oCIS because of security considerations. In order to make the following Rclone commands work the oCIS administrator needs to enable Basic Authentication eg. by setting the the environment variable `PROXY_ENABLE_BASIC_AUTH` to `true`. 
+
+Please consider to use [Rclone with OpenID Connect]({{< ref "webdav-sync-oidc.md" >}}) instead.
+{{< /hint >}}
+
+For the usage of a WebDAV remote with Rclone see also the [Rclone documentation](https://rclone.org/webdav/)
+
+## Configure the WebDAV remote
+
+First of all we need to set up our credentials and the WebDAV remote for Rclone. In this example we do this by setting environment variables. You might also set up a named remote or use command line options to achieve the same.
+
+``` bash
+export RCLONE_WEBDAV_VENDOR=owncloud
+export RCLONE_WEBDAV_URL=https://ocis.owncloud.test/remote.php/webdav/
+export RCLONE_WEBDAV_USER=einstein
+export RCLONE_WEBDAV_PASS=$(rclone obscure relativity)
+```
+
+{{< hint info >}}
+Please note that `RCLONE_WEBDAV_PASS` is not set to the actual password, but to the value returned by `rclone obscure <password>`.
+{{< /hint >}}
+
+We now can use Rclone to sync the local folder `/tmp/test` to `/test` in your oCIS home folder.
+
+
+### Sync to the WebDAV remote
+
+``` bash
+rclone sync :local:/tmp :webdav:/test
+```
+
+If your oCIS doesn't use valid SSL certificates, you may need to use `rclone --no-check-certificate sync ...`. 

docs/clients/rclone/webdav-sync-oidc.md

@@ -0,0 +1,66 @@
+---
+title: WebDAV with OpenID Connect
+date: 2021-11-17T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/clients/rclone
+geekdocFilePath: webdav-sync-oidc.md
+geekdocCollapseSection: true
+---
+
+
+## WebDAV with OpenID Connect
+
+Rclone itself is not able to open and maintain an OpenID Connect session. But it is able to still use OpenID Connect for authentication by leveraging a so called OIDC-agent.
+
+### Setting up the OIDC-agent
+
+You need to install the [OIDC-agent](https://github.com/indigo-dc/oidc-agent) from your OS' package repository (eg. [Debian](https://github.com/indigo-dc/oidc-agent#debian-packages) or [MacOS](https://github.com/indigo-dc/oidc-agent#debian-packages)).
+
+
+### Configuring the the OIDC-agent
+
+Run the following command to add a OpenID Connect profile to your OIDC-agent. It will open the login page of OpenID Connect identity provider where you need to log in if you don't have an active session.
+
+``` bash
+oidc-gen \
+ --client-id=oidc-agent \
+ --client-secret="" \
+ --pub \
+ --issuer https://ocis.owncloud.test \
+ --redirect-uri=http://localhost:12345 \
+ --scope max \
+ einstein-ocis-owncloud-test
+```
+
+If you have dynamic client registration enabled on your OpenID Connect identity provider, you can skip the `--client-id`,  `--client-secret` and `--pub` options.
+
+If your're using a dedicated OpenID Connect client for the OIDC-agent, we recommend a public one with the following two redirect URIs: `http://127.0.0.1:*` and `http://localhost:*`. Alternatively you also may use the already existing OIDC client of the ownCloud Desktop Client (`--client-id=xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69` and `--client-secret=UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh`, no `--pub` set)
+
+Please also note that the OIDC-agent will listen on your localhost interface on port 12345 for the time of the intial authentication. If that port is already occupied on your machine, you can easily change that by setting the `--redirect-uri` parameter to a different value.
+
+After a successful login or an already existing session you will be redirected to success page of the OIDC-agent.
+You will now be asked for a password for your account configuration, so that your OIDC session is secured and cannot be used by other people with access to your computer.
+
+
+
+## Configure the WebDAV remote
+
+First of all we need to set up our credentials and the WebDAV remote for Rclone. In this example we do this by setting environment variables. You might also set up a named remote or use command line options to achieve the same.
+
+``` bash
+export RCLONE_WEBDAV_VENDOR=owncloud
+export RCLONE_WEBDAV_URL=https://ocis.owncloud.test/remote.php/webdav/
+export RCLONE_WEBDAV_BEARER_TOKEN_COMMAND="oidc-token einstein-ocis-owncloud-test"
+```
+
+
+### Sync to the WebDAV remote
+
+We now can use Rclone to sync the local folder `/tmp/test` to `/test` in your oCIS home folder.
+
+``` bash
+rclone sync :local:/tmp :webdav:/test
+```
+
+If your oCIS doesn't use valid SSL certificates, you may need to use `rclone --no-check-certificate sync ...`.