From 54e485b368b2cbeb4137d3e1a03f0d150ede8e4c Mon Sep 17 00:00:00 2001 From: Klaas Freitag Date: Thu, 13 Mar 2025 17:21:26 +0100 Subject: [PATCH 1/4] Admin information for the new posix storage driver --- .../30-configuration/80-storage-posix.md | 65 ++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/admin/30-configuration/80-storage-posix.md b/docs/admin/30-configuration/80-storage-posix.md index 9ccb1c9c..2b623eb9 100644 --- a/docs/admin/30-configuration/80-storage-posix.md +++ b/docs/admin/30-configuration/80-storage-posix.md @@ -3,4 +3,67 @@ sidebar_position: 8 id: storage-posix title: "Storage: Posix" draft: true ---- \ No newline at end of file +--- + +# PosixFS Storage Driver + +PosixFS is a storage driver that saves OpenClouds files and folders in a folder structure how the user sees that in the web interface or other clients. That is a difference compared to DecomposedFS, which stores files in a technical folder structure that has limited meaning for admins. + +There are two modes to destinguish: + +1. *non collaborative mode* where the filesystem tree in use is exclusively granted to OpenCloud +2. *collaborative mode* where modifications of the underlying file tree are permitted by other processes than OpenCloud + +The *collaborative mode* is not yet available and follow later. + +## Metadata + +To allow OpenCloud to work database less, extra metadata is stored in the extended file attributes of each file. To mitigate size limitations for extended file attributes of file systems, metadata is moved to an extra metadata file if overall size exceeds a certain limit. In that case, only a reference to the meta data file is kept in the extended file attributes. + +## Access Model + +PosixFS in *non collaborative mode* must not be changed manually in the file system while OpenCloud is up and running. The assigned file system tree has to be exclusive granted for OpenClouds access. + +File- and folder permissions must be set to the same user and group that OpenCloud is running under. That is happening autmatically as long as the root directory of the tree is writeable. + +### External Access + +When OpenCloud is shut down, limited manipulation of the underlying file system tree is possible for certain administration tasks such as + +- adding files and folders +- removing files and folders +- renaming files and folders + +:::warning + +Whenever files are manipulated externally of OpenCloud, it is important to remember to + +- shut down OpenCloud before starting +- do not loose the extended file attributes of individual files +- set the file- and folder permissions correctly + +::: + +## Backup + +With PosixFS backup and restore is easy. The entire OpenCloud filesystem tree can be snapshotted regularly and restored as needed. It depends on the filesystem type how that has to be done in detail. + +## Migration + +PosixFS in this so called *non collaborative mode* is the default for new installations of OpenCloud. There is currently no way to migrate OpenCloud installations with DecomposedFS backend to PosixFS. + +If that is needed, data needs to be copied into a new installation of OpenCloud with PosixFS. + +# Configuration + +T collaborative PosixFS storage driver is part of the default OpenCloud bundle. + +Involved configuration settings (environment variables) to enable PosixFS are: + +- `STORAGE_USERS_DRIVER` needs to be set to `posix` +- `STORAGE_USERS_ID_CACHE_STORE` needs to be set to `nats-js-kv` +- `STORAGE_USERS_POSIX_ROOT` can be omitted for default, or set the storage root directory + +--- + + From 9ceacfac037fda60a37b749d63ff21476c823c78 Mon Sep 17 00:00:00 2001 From: Klaas Freitag Date: Fri, 14 Mar 2025 09:41:55 +0100 Subject: [PATCH 2/4] Spelling and wording fixes Co-authored-by: Phil Davis --- docs/admin/30-configuration/80-storage-posix.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/admin/30-configuration/80-storage-posix.md b/docs/admin/30-configuration/80-storage-posix.md index 2b623eb9..2abf868b 100644 --- a/docs/admin/30-configuration/80-storage-posix.md +++ b/docs/admin/30-configuration/80-storage-posix.md @@ -9,20 +9,20 @@ draft: true PosixFS is a storage driver that saves OpenClouds files and folders in a folder structure how the user sees that in the web interface or other clients. That is a difference compared to DecomposedFS, which stores files in a technical folder structure that has limited meaning for admins. -There are two modes to destinguish: +There are two modes to distinguish: 1. *non collaborative mode* where the filesystem tree in use is exclusively granted to OpenCloud 2. *collaborative mode* where modifications of the underlying file tree are permitted by other processes than OpenCloud -The *collaborative mode* is not yet available and follow later. +The *collaborative mode* is not yet available and will follow later. ## Metadata -To allow OpenCloud to work database less, extra metadata is stored in the extended file attributes of each file. To mitigate size limitations for extended file attributes of file systems, metadata is moved to an extra metadata file if overall size exceeds a certain limit. In that case, only a reference to the meta data file is kept in the extended file attributes. +To allow OpenCloud to work database-less, extra metadata is stored in the extended file attributes of each file. To mitigate size limitations for extended file attributes of file systems, metadata is moved to an extra metadata file if overall size exceeds a certain limit. In that case, only a reference to the meta data file is kept in the extended file attributes. ## Access Model -PosixFS in *non collaborative mode* must not be changed manually in the file system while OpenCloud is up and running. The assigned file system tree has to be exclusive granted for OpenClouds access. +PosixFS in *non collaborative mode* must not be changed manually in the file system while OpenCloud is up and running. The assigned file system tree has to be exclusively granted for OpenClouds access. File- and folder permissions must be set to the same user and group that OpenCloud is running under. That is happening autmatically as long as the root directory of the tree is writeable. @@ -36,10 +36,10 @@ When OpenCloud is shut down, limited manipulation of the underlying file system :::warning -Whenever files are manipulated externally of OpenCloud, it is important to remember to +Whenever files are manipulated externally to OpenCloud, it is important to remember to - shut down OpenCloud before starting -- do not loose the extended file attributes of individual files +- do not lose the extended file attributes of individual files - set the file- and folder permissions correctly ::: @@ -56,7 +56,7 @@ If that is needed, data needs to be copied into a new installation of OpenCloud # Configuration -T collaborative PosixFS storage driver is part of the default OpenCloud bundle. +The collaborative PosixFS storage driver is part of the default OpenCloud bundle. Involved configuration settings (environment variables) to enable PosixFS are: From 69180140123825856c4f38143e6220806aa0e89f Mon Sep 17 00:00:00 2001 From: Alex Ackermann Date: Tue, 25 Mar 2025 09:55:44 +0100 Subject: [PATCH 3/4] Remove draft state --- docs/admin/30-configuration/80-storage-posix.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/admin/30-configuration/80-storage-posix.md b/docs/admin/30-configuration/80-storage-posix.md index 2abf868b..c169668d 100644 --- a/docs/admin/30-configuration/80-storage-posix.md +++ b/docs/admin/30-configuration/80-storage-posix.md @@ -2,7 +2,6 @@ sidebar_position: 8 id: storage-posix title: "Storage: Posix" -draft: true --- # PosixFS Storage Driver From f380fe0719c3e2956fb0b79361590165ce0b4280 Mon Sep 17 00:00:00 2001 From: Alex Ackermann Date: Tue, 25 Mar 2025 09:57:48 +0100 Subject: [PATCH 4/4] Remove front matter draft false statements --- docs/admin/10-welcome/20-features.md | 1 - docs/admin/10-welcome/index.md | 1 - docs/admin/20-getting-started/10-requirements.md | 1 - docs/admin/30-configuration/100-storage-decomposeds3.md | 1 - 4 files changed, 4 deletions(-) diff --git a/docs/admin/10-welcome/20-features.md b/docs/admin/10-welcome/20-features.md index d010fb71..7a0b43de 100644 --- a/docs/admin/10-welcome/20-features.md +++ b/docs/admin/10-welcome/20-features.md @@ -2,7 +2,6 @@ sidebar_position: 2 id: features title: Features -draft: false --- diff --git a/docs/admin/10-welcome/index.md b/docs/admin/10-welcome/index.md index 8aac0dc2..c6e0962f 100644 --- a/docs/admin/10-welcome/index.md +++ b/docs/admin/10-welcome/index.md @@ -1,7 +1,6 @@ --- title: Welcome! slug: /admin/intro -draft: false --- # 🙋🏻‍♀️ Welcome to OpenCloud Admin Docs diff --git a/docs/admin/20-getting-started/10-requirements.md b/docs/admin/20-getting-started/10-requirements.md index 32fa814d..c5efe6b8 100644 --- a/docs/admin/20-getting-started/10-requirements.md +++ b/docs/admin/20-getting-started/10-requirements.md @@ -2,7 +2,6 @@ sidebar_position: 1 id: requirements title: Requirements -draft: false description: "Runs on anything from a Raspberry Pi to a data center." --- diff --git a/docs/admin/30-configuration/100-storage-decomposeds3.md b/docs/admin/30-configuration/100-storage-decomposeds3.md index 82b0c0ae..b0f4b72a 100644 --- a/docs/admin/30-configuration/100-storage-decomposeds3.md +++ b/docs/admin/30-configuration/100-storage-decomposeds3.md @@ -2,7 +2,6 @@ sidebar_position: 10 id: storage-decomposeds3 title: "Storage: Decomposeds3" -draft: false --- # Decomposeds3 Storage Driver