Skip to content

Commit d400487

Browse files
committed
docs(admin): address review feedback on external storage change detection
- Reword "Once per direct access" and "Never" bullets for accuracy - Drop overly long trailing clause from etag propagation paragraph - Replace files:scan --all with files_external:scan <mount_id> - Remove --all recommendation and AIO note (resource concerns) - Broaden rename limitation: applies to both scan modes, not just cron Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
1 parent 52064eb commit d400487

1 file changed

Lines changed: 17 additions & 36 deletions

File tree

admin_manual/configuration_files/external_storage_configuration_gui.rst

Lines changed: 17 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -182,10 +182,10 @@ The **Filesystem check frequency** mount option (see
182182
``PROPFIND`` request reaches the Nextcloud server for a path inside the external
183183
storage:
184184

185-
* **Once per direct access** — the server rescans that directory level on the first
186-
``PROPFIND`` per PHP request, then updates the filecache for what it finds there.
187-
* **Never** — the server skips the rescan entirely and always returns the cached
188-
state.
185+
* **Once per direct access** — during ``PROPFIND`` requests made to a given directory,
186+
Nextcloud rescans that directory level then updates the filecache with what it finds there.
187+
* **Never** — the server never rescans the external storage during ``PROPFIND`` requests
188+
and always returns the content stored in its internal index.
189189

190190
This option is *only* about the server's behaviour during a ``PROPFIND``. It does
191191
not trigger any background polling and does not change how desktop clients or
@@ -205,9 +205,7 @@ folder up to the root must also change, giving the client a trail to follow down
205205
to the changed file.
206206

207207
When a change is made outside Nextcloud, no etag is updated. The client sees no
208-
trail from the root and never follows it down to the changed file — even if the
209-
file itself is eventually rescanned at a deeper level, the propagation up to the
210-
root must still happen before the client can discover it.
208+
trail from the root and never follows it down to the changed file.
211209

212210
How to make external changes reliably detectable
213211
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -231,47 +229,30 @@ requirements and how to reduce sync delay.
231229
**B) All other storages — periodic rescan via cron**
232230

233231
For storage types that do not support push notifications, set up a cron job that
234-
rescans the storage periodically:
232+
rescans the external storage periodically using its mount ID:
235233

236234
.. code-block:: console
237235
238-
sudo -E -u www-data php occ files:scan --path="/user/files/MountName"
236+
sudo -E -u www-data php occ files_external:scan <mount_id>
239237
240-
Or to rescan all files for all users (including all external storages):
241-
242-
.. code-block:: console
243-
244-
sudo -E -u www-data php occ files:scan --all
245-
246-
See :doc:`../occ_command` for the full ``files:scan`` reference. A typical
238+
See :doc:`../occ_command` for the full ``files_external:scan`` reference. A typical
247239
interval is every 15 minutes; adjust to balance freshness against server load.
248240

249-
.. note::
250-
On Nextcloud AIO the equivalent command is:
251-
252-
.. code-block:: console
253-
254-
sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ files:scan --all
255-
256-
We also recommend configuring the background job as **Webcron** or **Cron**
257-
(see :doc:`../configuration_server/background_jobs_configuration`) so that
258-
Nextcloud's regular housekeeping runs reliably alongside any custom scan cron job.
259-
260241
Limitation: renames are not detected reliably
261242
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
262243

263-
When using periodic rescanning (option B above), the scanner cannot reliably
264-
detect that an entry was **renamed**. It sees the old name as deleted and the new
265-
name as a newly created entry. This causes **metadata loss**: all shares, tags,
266-
comments, and activity history associated with the old entry are permanently
267-
deleted from Nextcloud's database.
244+
Whenever Nextcloud rescans an external storage — whether via periodic cron
245+
(option B) or on direct access (option A setting **Once per direct access**) —
246+
the scanner cannot reliably detect that an entry was **renamed**. It sees the old
247+
name as deleted and the new name as a newly created entry. This causes
248+
**metadata loss**: all shares, tags, comments, and activity history associated
249+
with the old entry are permanently deleted from Nextcloud's database.
268250

269251
.. warning::
270252
If users rename files or folders directly on the external storage (outside
271-
Nextcloud), that metadata loss is unavoidable when using periodic rescanning.
272-
To preserve metadata, all renames should be done through Nextcloud itself, or
273-
— for SMB — use update notifications (option A) which handles renames via the
274-
SMB change event stream.
253+
Nextcloud), that metadata loss is unavoidable. To preserve metadata, all renames
254+
should be done through Nextcloud itself, or — for SMB — use update notifications
255+
(option A) which handles renames via the SMB change event stream.
275256

276257
.. _trouble-file-encoding-ext-storages:
277258

0 commit comments

Comments
 (0)