From 7981ed7deca1840b99009041c3ac5dfebd7fad35 Mon Sep 17 00:00:00 2001
From: Valentin Lab <valentin.lab@kalysto.org>
Date: Fri, 15 Oct 2021 12:26:35 +0200
Subject: [PATCH] new: add doc to ``sftp`` charm

Signed-off-by: Valentin Lab <valentin.lab@kalysto.org>
---
 sftp/README.org | 75 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 sftp/README.org

diff --git a/sftp/README.org b/sftp/README.org
new file mode 100644
index 0000000..f8c38b0
--- /dev/null
+++ b/sftp/README.org
@@ -0,0 +1,75 @@
+* Presentation
+
+This charm allows you to host a SFTP (using ssh) with it's own user
+database. They can be authenticated with a password or with a SSH key.
+
+You can choose exactly what data will be accessible to them by mount
+binding each directory you want to share from the host in their own
+home directory in the container. (see the examples).
+
+The permissions should be managed through group permissions, directly
+from the host and in the shared directory.
+
+Each user in the container will be part of multiple groups
+(configurable via the options of the charm in your service definition
+of the =compose.yml=), and the GID of the groups will be the same on
+the host and on the container.
+
+* Example configuration
+
+#+begin_src yaml
+  sftp:
+    docker-compose:
+      ports:
+        - "10622:22"
+      volumes:
+        ## Here we allow access to specific directories only by binding
+        ## them in their home directory:
+        - /srv/datastore/data/www/var/www/www.myclientwebsite.com:/home/myclient1/www.myclientwebsite.com:rw
+        - /srv/datastore/data/www/var/www/www.myclientwebsite.com:/home/myclient2/www.myclientwebsite.com:rw
+    options:
+      users:
+        myclient1:
+          ## These groups are created on the container with the given GID
+          ## Note that UID/GID are the same for the container and the host,
+          ## So don't forget to give the appropriate rights from the host on
+          ## the shared directory to ensure that access is effectively granted
+          ## as you want to the customer
+          groups:
+            - sftpaccess-rw:3000
+          password: FaKePaSSw0rdT0Ch4Ng3
+          keys:
+            - "ssh-rsa AAAAB3NzaC2yc2Z..."
+        myclient2:
+          ## These groups are created on the container with the given GID
+          ## Note that UID/GID are the same for the container and the host,
+          ## So don't forget to give the appropriate rights from the host on
+          ## the shared directory to ensure that access is effectively granted
+          ## as you want to the customer
+          groups:
+            - sftpaccess-rw:3000
+          password: FaKePaSSw0rdT0Ch4Ng3
+          keys:
+            - "ssh-rsa AAAAB3NzBC1yc2X..."
+#+end_src
+
+
+In this case, you'll need also to make sure to set up correctly the
+directories you shared, in this example, only
+=/srv/datastore/data/www/var/www/www.myclientwebsite.com= is shared :
+you are expected to set the permissions of the group identified by the
+id `3000`.
+
+Using getfacl/setfacl is the right tool most of the time. If you don't
+have it:
+
+#+begin_src sh
+apt-get install acl
+#+end_src
+
+Then, you could:
+
+#+begin_src sh
+find /srv/datastore/data/www/var/www/www.myclientwebsite.com -type d \
+    -exec getfacl -mR d:g:3000:rwx,d:g:3000:rwx
+#+end_src