From 1564bffe4415ae044f5b6cd1240ba7c9d403cdbd Mon Sep 17 00:00:00 2001 From: Pascal Bleser Date: Thu, 30 Jul 2026 10:58:14 +0200 Subject: [PATCH 1/3] feat(docs): add documentation for the posixfs scan command * since the posixfs scan command has been augmented with an optional parameter with https://github.com/opencloud-eu/opencloud/issues/3182, this change adds configuration for that command in the first place, which was missing altogether * addresses but does not close #1070 since the `posixfs consistency` command is not documented by this change --- .../admin/maintenance/maintenance-commands.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/admin/maintenance/maintenance-commands.md b/docs/admin/maintenance/maintenance-commands.md index e78f8a88..f8583c95 100644 --- a/docs/admin/maintenance/maintenance-commands.md +++ b/docs/admin/maintenance/maintenance-commands.md @@ -104,6 +104,33 @@ opencloud storage-users trash-bin restore-all Restoring is only possible to the original location. The behavior when the target name already exists can be configured with the available restore options: skipping, replacing, or keeping both items. +### Scanning resources on PosixFS + +When using the [PosixFS Storage Driver](../configuration/storage/posixfs.md) in collaborative mode (with `STORAGE_USERS_POSIX_WATCH_FS` set to `true`), files and directories can be added or manipulated in the storage directly. When files are added, OpenCloud transparently adds metadata to track the files for future changes, as if they were uploaded through OpenCloud. + +Administrators can trigger the storage scan manually. This might be useful during migrations, or when [collaborative mode](../configuration/storage/posixfs.md#posixfs-collaborative-mode) is disabled. + +This is recommended since files that have not been scanned + + * may have a negative performance impact when accessed, since OpenCloud transparently performs a storage scan to ingest previous untracked files when listing a directory through its UIs and APIs (but not recursively) + * prevents those files from being accounted for in directory tree sizes and quotas + +For such cases, use the following command: + +```bash +opencloud posixfs scan [-p ] +``` + +Optionally, one might want to specify a resource to scan, using the optional `--basepath` (or `-p`) option. + +When that resource is a directory, it will recurse and perform a storage scan for all the files contained within that directory and all its subdirectories. + +And when that resource is a regular file instead, it will solely perform a storage scan on that one file. + +Note that in either case, the resource must be underneath the PosixFS storage root, or be the PosixFS storage root itself, as set using `STORAGE_USERS_POSIX_ROOT`; if not, an error will occur. + +When the `--basepath` option is not specified, the default behavior is to start the storage scanning recursively at the root of the PosixFS storage (as defined by `STORAGE_USERS_POSIX_ROOT`). + ## Uploads The `opencloud storage-users uploads sessions` command lists and manages upload sessions. Flags can be combined to filter sessions by state. From 396ae1a24a24afa3e32145a5a7c7b2b502474592 Mon Sep 17 00:00:00 2001 From: Pascal Bleser Date: Mon, 3 Aug 2026 12:13:14 +0200 Subject: [PATCH 2/3] feat(docs): adapt documentation for the posixfs scan command for supporting multiple resources as arguments --- docs/admin/maintenance/maintenance-commands.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/admin/maintenance/maintenance-commands.md b/docs/admin/maintenance/maintenance-commands.md index f8583c95..cf579b8f 100644 --- a/docs/admin/maintenance/maintenance-commands.md +++ b/docs/admin/maintenance/maintenance-commands.md @@ -108,28 +108,28 @@ Restoring is only possible to the original location. The behavior when the targe When using the [PosixFS Storage Driver](../configuration/storage/posixfs.md) in collaborative mode (with `STORAGE_USERS_POSIX_WATCH_FS` set to `true`), files and directories can be added or manipulated in the storage directly. When files are added, OpenCloud transparently adds metadata to track the files for future changes, as if they were uploaded through OpenCloud. -Administrators can trigger the storage scan manually. This might be useful during migrations, or when [collaborative mode](../configuration/storage/posixfs.md#posixfs-collaborative-mode) is disabled. +Administrators can trigger the storage scanning manually. This might be useful during migrations, or when [collaborative mode](../configuration/storage/posixfs.md#posixfs-collaborative-mode) is disabled. -This is recommended since files that have not been scanned +It is recommended practice in such situations, since files that have not been scanned - * may have a negative performance impact when accessed, since OpenCloud transparently performs a storage scan to ingest previous untracked files when listing a directory through its UIs and APIs (but not recursively) + * may have a negative performance impact when accessed, since OpenCloud transparently performs a storage scan to ingest previously untracked files when listing a directory through its UIs and APIs (but not recursively) * prevents those files from being accounted for in directory tree sizes and quotas For such cases, use the following command: ```bash -opencloud posixfs scan [-p ] +opencloud posixfs scan [path path ...] ``` -Optionally, one might want to specify a resource to scan, using the optional `--basepath` (or `-p`) option. +Optionally, one might want to specify resources to scan, using optional arguments that specify paths. -When that resource is a directory, it will recurse and perform a storage scan for all the files contained within that directory and all its subdirectories. +When that path is a directory, it will recurse and perform a storage scan for all the files contained within that directory and all its subdirectories. -And when that resource is a regular file instead, it will solely perform a storage scan on that one file. +And when that path is a regular file instead, it will solely perform a storage scan on that one file. Note that in either case, the resource must be underneath the PosixFS storage root, or be the PosixFS storage root itself, as set using `STORAGE_USERS_POSIX_ROOT`; if not, an error will occur. -When the `--basepath` option is not specified, the default behavior is to start the storage scanning recursively at the root of the PosixFS storage (as defined by `STORAGE_USERS_POSIX_ROOT`). +When no arguments are specified, the default behavior is to start the storage scanning recursively at the root of the PosixFS storage (as defined by `STORAGE_USERS_POSIX_ROOT`). ## Uploads From 1882ab79fe6f112a321bc8a20de1437d94ac8ce3 Mon Sep 17 00:00:00 2001 From: Pascal Bleser Date: Mon, 3 Aug 2026 20:13:30 +0200 Subject: [PATCH 3/3] feat(docs): add documentation for the posixfs scan command option --halt-on-error --- docs/admin/maintenance/maintenance-commands.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/admin/maintenance/maintenance-commands.md b/docs/admin/maintenance/maintenance-commands.md index cf579b8f..1bbfcd70 100644 --- a/docs/admin/maintenance/maintenance-commands.md +++ b/docs/admin/maintenance/maintenance-commands.md @@ -131,6 +131,8 @@ Note that in either case, the resource must be underneath the PosixFS storage ro When no arguments are specified, the default behavior is to start the storage scanning recursively at the root of the PosixFS storage (as defined by `STORAGE_USERS_POSIX_ROOT`). +The optional command-line option `--halt-on-error` (or `-E`) will make the command stop as soon as an error is encountered, whereas the default behaviour is to keep going by skipping paths that yield unrecoverable errors and proceeding to processing the subsequent ones. + ## Uploads The `opencloud storage-users uploads sessions` command lists and manages upload sessions. Flags can be combined to filter sessions by state.