From d2143fac59615991967eb946e75f16b1f18f7a37 Mon Sep 17 00:00:00 2001
From: WesselAtWork <115667066+WesselAtWork@users.noreply.github.com>
Date: Mon, 12 Feb 2024 18:08:22 +0200
Subject: [PATCH] s3fs docs

Signed-off-by: WesselAtWork <115667066+WesselAtWork@users.noreply.github.com>
---
 docs/source/markdown/podman-systemd.unit.5.md | 26 +++++++
 .../source/markdown/podman-volume-create.1.md | 73 ++++++++++++++++++-
 2 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md
index 0ae9b5d8fd..45d8aef316 100644
--- a/docs/source/markdown/podman-systemd.unit.5.md
+++ b/docs/source/markdown/podman-systemd.unit.5.md
@@ -1533,6 +1533,32 @@ Exec=sh -c "sleep inf"
 Pod=test.pod
 ```
 
+Example `s3fs.volume`:
+
+For further details, please see the [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) project.
+Remember to read the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ)
+
+> NOTE: Enabling the cache massively speeds up access and write times on static files/objects.
+
+> However, `use_cache` is [UNBOUNDED](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ#q-how-does-the-local-file-cache-work)!
+
+> Be careful, it will fill up with any files accessed on the s3 bucket through the file system.
+
+Please remember to set `S3_BUCKET`, `PATH`, `AWS_REGION`. `CACHE_DIRECTORY` should be set up by [systemd](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=)
+
+```
+[Service]
+CacheDirectory=s3fs
+ExecStartPre=/usr/local/bin/aws s3api put-object --bucket ${S3_BUCKET} --key ${PATH}/
+
+[Volume]
+Device=${S3_BUCKET}:/${PATH}
+Type=fuse.s3fs
+VolumeName=s3fs-volume
+Options=iam_role,endpoint=${AWS_REGION},use_xattr,listobjectsv2,del_cache,use_cache=${CACHE_DIRECTORY}
+# `iam_role` assumes inside EC2, if not, Use `profile=` instead
+```
+
 ## SEE ALSO
 **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**,
 **[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html)**,
diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md
index ca6e400909..67b97aa7b6 100644
--- a/docs/source/markdown/podman-volume-create.1.md
+++ b/docs/source/markdown/podman-volume-create.1.md
@@ -103,7 +103,7 @@ Create image named volume using the specified local image in containers/storage.
 
 ## QUOTAS
 
-podman volume create uses `XFS project quota controls` for controlling the size and the number of inodes of builtin volumes. The directory used to store the volumes must be an `XFS` file system and be mounted with the `pquota` option.
+`podman volume create` uses `XFS project quota controls` for controlling the size and the number of inodes of builtin volumes. The directory used to store the volumes must be an `XFS` file system and be mounted with the `pquota` option.
 
 Example /etc/fstab entry:
 ```
@@ -129,6 +129,77 @@ All containers are assigned larger project IDs (e.g. >= 100000).
 All volume assigned project IDs larger project IDs starting with 200000.
 This prevents xfs_quota management conflicts with containers/storage.
 
+## MOUNT EXAMPLES
+
+`podman volume create` allows the `type`, `device`, and `o` options to be passed to `mount(8)` when using the `local` driver.
+
+## [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
+
+[s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) or just `s3fs`, is a [fuse](https://github.com/libfuse/libfuse) filesystem that allows s3 prefixes to be mounted as filesystem mounts.
+
+**Installing:**
+```shell
+$ doas dnf install s3fs-fuse
+```
+
+**Simple usage:**
+```shell
+$ s3fs --help
+$ s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
+```
+
+**Equivalent through `mount(8)`**
+```shell
+$ mount -t fuse.s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt
+```
+
+**Equivalent through `podman volume create`**
+```shell
+$ podman volume create s3fs-fuse-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=use_xattr,endpoint=aq-central-1
+```
+
+**The volume can then be mounted in a container with**
+```shell
+$ podman run -v s3fs-fuse-volume:/s3:z --rm -it fedora:latest
+```
+
+Please see the available [options](https://github.com/s3fs-fuse/s3fs-fuse/wiki/Fuse-Over-Amazon#options) on their wiki.
+
+### Using with other container users
+
+The above example works because the volume is mounted as the host user and inside the container `root` is mapped to the user in the host.
+
+If the mount is accessed by a different user inside the container, a "Permission denied" error will be raised.
+
+```shell
+$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
+$ ls /s3
+# ls: /s3: Permission denied
+```
+
+In FUSE-land, mounts are protected for the user who mounted them; specify the `allow_other` mount option if other users need access.
+> Note: This will remove the normal fuse [security measures](https://github.com/libfuse/libfuse/wiki/FAQ#why-dont-other-users-have-access-to-the-mounted-filesystem) on the mount point, after which, the normal filesystem permissions will have to protect it
+
+```shell
+$ podman volume create s3fs-fuse-other-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=allow_other,use_xattr,endpoint=aq-central-1
+$ podman run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it fedora:latest
+$ ls /s3
+```
+
+### The Prefix must exist
+
+`s3fs` will fail to mount if the prefix does not exist in the bucket.
+
+Create a s3-directory by putting an empty object at the desired `prefix/` key
+```shell
+$ aws s3api put-object --bucket bucket --key prefix/
+```
+
+If performance is the priority, please check out the more performant [goofys](https://github.com/kahing/goofys).
+
+> FUSE filesystems exist for [Google Cloud Storage](https://github.com/GoogleCloudPlatform/gcsfuse) and [Azure Blob Storage](https://github.com/Azure/azure-storage-fuse)
+
+
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[podman-volume(1)](podman-volume.1.md)**, **mount(8)**, **xfs_quota(8)**, **xfs_quota(8)**, **projects(5)**, **projid(5)**