diff --git a/docs/admin/maintenance/maintenance-commands.md b/docs/admin/maintenance/maintenance-commands.md index e78f8a88..1bbfcd70 100644 --- a/docs/admin/maintenance/maintenance-commands.md +++ b/docs/admin/maintenance/maintenance-commands.md @@ -104,6 +104,35 @@ 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 scanning manually. This might be useful during migrations, or when [collaborative mode](../configuration/storage/posixfs.md#posixfs-collaborative-mode) is disabled. + +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 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 [path path ...] +``` + +Optionally, one might want to specify resources to scan, using optional arguments that specify paths. + +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 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 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.