From 06fe8b02de0b31c4ca0b8887eda592eeb1bebb89 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 7 Aug 2026 12:47:15 -0400 Subject: [PATCH 1/6] docs(admin): rewrite deleted files configuration chapter Update, expand, and clarify trash-bin retention policies, size limits, interactions with quotas, background jobs details, and the various commands based on the current files_trashbin implementation. Assisted-by: Copilot:gpt-5.6-luna Signed-off-by: Josh --- .../trashbin_configuration.rst | 381 +++++++++++++++--- 1 file changed, 333 insertions(+), 48 deletions(-) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 2b71abdc564..607f30ff631 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -1,57 +1,342 @@ -========================= -Deleted Items (trash bin) -========================= +============= +Deleted Files +============= -If the trash bin app is enabled (default), this setting defines the policy -for when files and folders in the trash bin will be permanently deleted. +Introduction +------------ + +When a file or folder is deleted, Nextcloud normally moves it to the trash bin +instead of deleting it immediately. This allows the item to be restored later. + +Items in the trash bin are permanently deleted when one of the following occurs: + +- The account owner selects *Delete permanently*. +- The configured retention policy expires the item. +- The effective trash-bin size limit is exceeded and the item is eligible for + removal to free space. + +Logged-in accounts can access their trash bin by selecting *Deleted files* in +the **Files** area of the Nextcloud Web interface. Items in the trash bin can +be restored, downloaded, or permanently deleted. + +For information about using the trash bin as an account holder, see the +:doc:`Deleted files <../user_manual/en/files/deleted_file_management>` section +of the User Manual. + +.. note:: If the *Versions* app is enabled, versions associated with a deleted + file are moved to the trash bin and are restored when the file is restored. + +When a file is restored, Nextcloud attempts to restore it to its original +location. If that location no longer exists or is not writable, the file is +restored to the account's files root. If a file with the same name already +exists, the restored file receives a unique name. + +This functionality is provided by the *Deleted files* app, whose application +ID is ``files_trashbin``. The app provides: + +- The web interface for viewing, restoring, downloading, and permanently + deleting items. +- The trash-bin filesystem integration. +- Automatic expiration through a background job. +- The ``trashbin:size``, ``trashbin:expire``, ``trashbin:cleanup``, and + ``trashbin:restore`` commands. + +Policy Configuration +-------------------- + +The ``files_trashbin`` app uses two related mechanisms to determine when items +are permanently deleted: + +- A time-based retention policy configured with + ``trashbin_retention_obligation``. +- An effective trash-bin size limit, configured explicitly or calculated from + the account's available space. + +The default retention policy is ``auto``. In the default configuration, items +are retained for at least 30 days. After that minimum retention period, eligible +items may be permanently deleted when space is needed. + +The default effective trash-bin size is calculated as follows: + +- For an account with a quota, the trash bin may use up to 50% of the + account's remaining quota space. +- For an account without a quota, the trash bin may use the available + filesystem space. +- If an explicit global or per-account trash-bin size is configured, that + value overrides the calculated default. + +The 50% calculation is based on the account's **remaining** quota space, not +the account's total quota. For example, if an account has a 10 GB quota and is +already using 8 GB, the default trash-bin allowance is calculated from the +remaining 2 GB. + +When the effective trash-bin limit is exceeded, Nextcloud processes the oldest +items first. An item can be removed to free space only when it is eligible +under the configured retention policy. + +The global retention policy is configured with the +``trashbin_retention_obligation`` setting in ``config/config.php``: + +.. code-block:: php + + 'trashbin_retention_obligation' => 'auto', + +Available retention policy values are described below. ``D1`` and ``D2`` are +numbers of days. + +``auto`` + The default policy. This is equivalent to ``auto, auto``. + + Files and folders are retained for at least 30 days. After 30 days, they may + be permanently deleted when space is needed. + +``D1, auto`` + Files and folders are retained for at least ``D1`` days. After that, they + may be permanently deleted when space is needed. + +``auto, D2`` + Files and folders may be permanently deleted when space is needed, + regardless of age. In addition, all items older than ``D2`` days are + permanently deleted automatically, even when space is not currently needed. + +``D1, D2`` + Files and folders are retained for at least ``D1`` days. Items older than + ``D2`` days are permanently deleted automatically. + + If the effective trash-bin size is exceeded, items older than ``D1`` days + may also be deleted early to free space, oldest first. Items younger than + ``D1`` days are protected from size-based cleanup. + + Items older than ``D2`` days are deleted automatically even when space is + not currently needed. If ``D2`` is smaller than ``D1``, Nextcloud adjusts + the effective maximum retention period to ``D1``. + +``disabled`` + Automatic trash-bin expiration is disabled. Files and folders remain in the + trash bin until they are manually deleted or another operation removes them. + +A single numeric value is also accepted. The value is used as the minimum +retention period, while the default maximum retention period is 30 days. If +the resulting maximum period would be shorter than the minimum period, the +maximum is raised to match the minimum. + +For example, ``10`` is equivalent to ``10, 30``: items are retained for at +least 10 days and are automatically deleted once they exceed 30 days. By +contrast, ``45`` is equivalent to ``45, 45``, because the default maximum +of 30 days is shorter than the 45-day minimum and is therefore raised to +match it. .. note:: - If the user quota limit is exceeded due to deleted files in the trash bin, - retention settings will be ignored and files will be cleaned up until - the quota requirements are met. - -The app allows for two settings, a minimum time for trash bin retention, -and a maximum time for trash bin retention. -Minimum time is the number of days a file will be kept, after which it -may be deleted. Maximum time is the number of days at which it is guaranteed -to be deleted. -Both minimum and maximum times can be set together to explicitly define -file and folder deletion. For migration purposes, this setting is installed -initially set to "auto", which is equivalent to the default setting in -Nextcloud. - -You may alter the default pattern in ``config.php``. The default setting is -``auto``, which sets the default pattern:: - - 'trashbin_retention_obligation' => 'auto', - -Available values: - -* ``auto`` - default setting. keeps files and folders in the trash bin for 30 days - and automatically deletes anytime after that if space is needed (note: - files may not be deleted if space is not needed). -* ``D, auto`` - keeps files and folders in the trash bin for D+ days, delete anytime if - space needed (note: files may not be deleted if space is not needed) -* ``auto, D`` - delete all files in the trash bin that are older than D days - automatically, delete other files anytime if space needed -* ``D1, D2`` - keep files and folders in the trash bin for at least D1 days and - delete when exceeds D2 days (note: files will not be deleted automatically if space is needed) -* ``disabled`` - trash bin auto clean disabled, files and folders will be kept forever - -Background job + Unlike ``auto``, ``D1, auto``, and ``auto, D2``, this form (including a + bare numeric value) disables purely space-triggered cleanup of the trash + bin. Items may still be removed early if the trash-bin size limit is + exceeded, but only once they are older than the minimum retention period + (``D1``). + +For clarity, use the explicit ``D1, D2`` form when configuring a numeric +retention policy. + +Trash-bin Size Limits +--------------------- + +The ``trashbin:size`` command configures or displays the effective trash-bin +size. + +To display the global default and any per-account values: + +.. code-block:: console + + sudo -u www-data php occ trashbin:size + +To configure a global trash-bin size: + +.. code-block:: console + + sudo -u www-data php occ trashbin:size 10G + +To configure a size for a specific account: + +.. code-block:: console + + sudo -u www-data php occ trashbin:size --user USER_ID 10G + +The ``size`` argument accepts values understood by Nextcloud's file-size +parser, such as ``500M`` or ``10G``. + +A per-account value takes precedence over the global value. If no per-account +value is configured, the account uses the global value. If neither value is +configured, Nextcloud uses the calculated default based on the account's +remaining quota space or available filesystem space. + +To display the configured value for one account: + +.. code-block:: console + + sudo -u www-data php occ trashbin:size --user USER_ID + +Changing a per-account size schedules cleanup for that account. Changing the +global size causes existing trash bins to be cleaned up, although an account's +trash bin can temporarily exceed the newly configured size until cleanup is +performed or another item is moved to the trash bin. + +Interaction with Quotas +~~~~~~~~~~~~~~~~~~~~~~~ + +An explicit trash-bin size is independent of the account quota. It can +therefore be used for accounts both with and without quotas. + +For accounts with quotas, the following order applies: + +#. A per-account ``trashbin_size`` value is used when configured. +#. Otherwise, the global ``files_trashbin`` ``trashbin_size`` value is used + when configured. +#. Otherwise, the default limit is calculated from 50% of the account's + remaining quota space. + +When no explicit trash-bin size is configured for an account without a quota, +the available filesystem space is used to determine whether the trash bin +needs cleanup. + +Trash-bin cleanup does not necessarily remove all deleted files when an +account exceeds its quota. Items are removed according to the retention policy +and in oldest-first order until the effective trash-bin space requirement is +satisfied. + +Background Jobs +--------------- + +The ``files_trashbin`` app registers a background job for policies with a +configured maximum retention age, such as ``auto, D2`` and ``D1, D2``. The job +runs at a 30-minute interval, processes accounts in batches of 10, and runs +for no more than 30 minutes per invocation. + +For the default ``auto`` policy and other policies without a configured +maximum retention age, the background job does not perform an expiration pass. +For ``disabled``, automatic expiration is disabled. + +Space-based cleanup can instead be scheduled when trash-bin usage or available +space changes. + +The background job is controlled by the ``files_trashbin`` app configuration +value ``background_job_expire_trash``. It is enabled by default. + +To disable the background job: + +.. code-block:: console + + sudo -u www-data php occ config:app:set \ + --value=no files_trashbin background_job_expire_trash + +To re-enable it, remove the override: + +.. code-block:: console + + sudo -u www-data php occ config:app:delete \ + files_trashbin background_job_expire_trash + +When the background job is disabled, administrators can run expiration +manually with ``occ trashbin:expire`` or configure an external system task to +run that command. + +Other Commands -------------- -To permanently delete files a background jobs runs every 30 minutes. -It's possible to deactivate the background job and setup a (system) cron to expire the versions via occ. +The below operations are useful under certain circumstances, but do not typically +need to be used directly. + +Expiring Items Manually +~~~~~~~~~~~~~~~~~~~~~~~ + +To expire eligible items for all accounts: + +.. code-block:: console + + sudo -u www-data php occ trashbin:expire + +To expire eligible items for one or more accounts: + +.. code-block:: console + + sudo -u www-data php occ trashbin:expire USER_ID + +.. code-block:: console + + sudo -u www-data php occ trashbin:expire USER_ID_1 USER_ID_2 + +The command displays a progress bar when processing all accounts. Use +``--quiet`` to suppress the progress bar: + +.. code-block:: console + + sudo -u www-data php occ trashbin:expire --quiet + +For any active retention policy, including the default ``auto`` policy, +``trashbin:expire`` performs a full expiration pass: it deletes items that +exceed the configured maximum age, and it also deletes items to satisfy the +effective trash-bin size limit when needed, subject to the retention +policy's minimum age. + +If trash-bin expiration is disabled (``trashbin_retention_obligation`` set +to ``disabled``), ``trashbin:expire`` does not delete any items and exits +with a non-zero status. + +Space-based cleanup can also be triggered automatically outside of +``trashbin:expire`` and the background job — for example, when a file is +moved to the trash bin or when a change to the account's available space +causes the effective trash-bin limit to be exceeded. + +The trash-bin expiration command is provided by the +``files_trashbin`` app: + +.. code-block:: console + + sudo -u www-data php occ list files_trashbin + +Removing All Trashed Items +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To immediately and permanently delete **all** trashed items for all users +from all configured user backends, bypassing the retention policy entirely, +use ``trashbin:cleanup --all-users``: + +.. code-block:: console + + sudo -u www-data php occ trashbin:cleanup --all-users + +To clean up the trash bin for one or more specific accounts: + +.. code-block:: console + + sudo -u www-data php occ trashbin:cleanup USER_ID_1 USER_ID_2 + +The command requires either one or more account IDs or ``--all-users``. +These forms are mutually exclusive. + +.. danger:: + + This command deletes trashed items unconditionally and does not honor + the configured retention policy. Deleted items cannot be recovered. + +Restoring All Trashed Items +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To restore all trashed items for one or more accounts: + +.. code-block:: console + + sudo -u www-data php occ trashbin:restore USER_ID_1 USER_ID_2 + +To restore trashed items for all users from all configured user backends: + +.. code-block:: console -Deactivate background job: ``occ config:app:set --value=no files_trashbin background_job_expire_trash`` + sudo -u www-data php occ trashbin:restore --all-users -Activate background job: ``occ config:app:delete files_trashbin background_job_expire_trash`` +Account IDs and ``--all-users`` are mutually exclusive. The command requires +one or the other. -Expire versions: ``occ trashbin:expire`` or ``occ trashbin:expire --quiet`` (without the progress bar) +The command supports additional filters, including ``--since``, ``--until``, +and ``--scope`` (``user``, ``groupfolders``, or ``all``), as well as +``--dry-run`` to preview which items would be restored without performing any +action. See ``occ trashbin:restore --help`` for details. From d5acf8b19f065ae69757623714b2a9a55fe57137 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 7 Aug 2026 13:12:02 -0400 Subject: [PATCH 2/6] chore: fixup trashbin_configuration sudo references Signed-off-by: Josh --- .../trashbin_configuration.rst | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 607f30ff631..74d4ed7a85a 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -147,19 +147,19 @@ To display the global default and any per-account values: .. code-block:: console - sudo -u www-data php occ trashbin:size + sudo -E -u www-data php occ trashbin:size To configure a global trash-bin size: .. code-block:: console - sudo -u www-data php occ trashbin:size 10G + sudo -E -u www-data php occ trashbin:size 10G To configure a size for a specific account: .. code-block:: console - sudo -u www-data php occ trashbin:size --user USER_ID 10G + sudo -E -u www-data php occ trashbin:size --user USER_ID 10G The ``size`` argument accepts values understood by Nextcloud's file-size parser, such as ``500M`` or ``10G``. @@ -173,7 +173,7 @@ To display the configured value for one account: .. code-block:: console - sudo -u www-data php occ trashbin:size --user USER_ID + sudo -E -u www-data php occ trashbin:size --user USER_ID Changing a per-account size schedules cleanup for that account. Changing the global size causes existing trash bins to be cleaned up, although an account's @@ -225,14 +225,14 @@ To disable the background job: .. code-block:: console - sudo -u www-data php occ config:app:set \ + sudo -E -u www-data php occ config:app:set \ --value=no files_trashbin background_job_expire_trash To re-enable it, remove the override: .. code-block:: console - sudo -u www-data php occ config:app:delete \ + sudo -E -u www-data php occ config:app:delete \ files_trashbin background_job_expire_trash When the background job is disabled, administrators can run expiration @@ -252,24 +252,24 @@ To expire eligible items for all accounts: .. code-block:: console - sudo -u www-data php occ trashbin:expire + sudo -E -u www-data php occ trashbin:expire To expire eligible items for one or more accounts: .. code-block:: console - sudo -u www-data php occ trashbin:expire USER_ID + sudo -E -u www-data php occ trashbin:expire USER_ID .. code-block:: console - sudo -u www-data php occ trashbin:expire USER_ID_1 USER_ID_2 + sudo -E -u www-data php occ trashbin:expire USER_ID_1 USER_ID_2 The command displays a progress bar when processing all accounts. Use ``--quiet`` to suppress the progress bar: .. code-block:: console - sudo -u www-data php occ trashbin:expire --quiet + sudo -E -u www-data php occ trashbin:expire --quiet For any active retention policy, including the default ``auto`` policy, ``trashbin:expire`` performs a full expiration pass: it deletes items that @@ -291,7 +291,7 @@ The trash-bin expiration command is provided by the .. code-block:: console - sudo -u www-data php occ list files_trashbin + sudo -E -u www-data php occ list files_trashbin Removing All Trashed Items ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -302,13 +302,13 @@ use ``trashbin:cleanup --all-users``: .. code-block:: console - sudo -u www-data php occ trashbin:cleanup --all-users + sudo -E -u www-data php occ trashbin:cleanup --all-users To clean up the trash bin for one or more specific accounts: .. code-block:: console - sudo -u www-data php occ trashbin:cleanup USER_ID_1 USER_ID_2 + sudo -E -u www-data php occ trashbin:cleanup USER_ID_1 USER_ID_2 The command requires either one or more account IDs or ``--all-users``. These forms are mutually exclusive. @@ -325,13 +325,13 @@ To restore all trashed items for one or more accounts: .. code-block:: console - sudo -u www-data php occ trashbin:restore USER_ID_1 USER_ID_2 + sudo -E -u www-data php occ trashbin:restore USER_ID_1 USER_ID_2 To restore trashed items for all users from all configured user backends: .. code-block:: console - sudo -u www-data php occ trashbin:restore --all-users + sudo -E -u www-data php occ trashbin:restore --all-users Account IDs and ``--all-users`` are mutually exclusive. The command requires one or the other. From 5e50c42779cf4a12b383b6afe36a1e9092d83aa3 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 28 Aug 2026 14:09:26 -0400 Subject: [PATCH 3/6] chore(admin): correct link to user admin trash bin ch Signed-off-by: Josh --- admin_manual/configuration_files/trashbin_configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 74d4ed7a85a..9cda6ae8cb8 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -20,8 +20,8 @@ the **Files** area of the Nextcloud Web interface. Items in the trash bin can be restored, downloaded, or permanently deleted. For information about using the trash bin as an account holder, see the -:doc:`Deleted files <../user_manual/en/files/deleted_file_management>` section -of the User Manual. +:doc:`Deleted files ` +section of the User Manual. .. note:: If the *Versions* app is enabled, versions associated with a deleted file are moved to the trash bin and are restored when the file is restored. From 81f097e2c81961ac24953e44df01750a7e3c636b Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 28 Aug 2026 14:11:50 -0400 Subject: [PATCH 4/6] chore: fixup syntax error Signed-off-by: Josh --- admin_manual/configuration_files/trashbin_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 9cda6ae8cb8..b96d82b2585 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -20,7 +20,7 @@ the **Files** area of the Nextcloud Web interface. Items in the trash bin can be restored, downloaded, or permanently deleted. For information about using the trash bin as an account holder, see the -:doc:`Deleted files ` +:doc:`Deleted files `_ section of the User Manual. .. note:: If the *Versions* app is enabled, versions associated with a deleted From 4c6851d2d0b0f989ddd03e1be475231d94d73e5d Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 28 Aug 2026 14:23:58 -0400 Subject: [PATCH 5/6] chore: fixup third time is the charm (oops) Signed-off-by: Josh --- admin_manual/configuration_files/trashbin_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index b96d82b2585..4ee3dc36928 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -20,7 +20,7 @@ the **Files** area of the Nextcloud Web interface. Items in the trash bin can be restored, downloaded, or permanently deleted. For information about using the trash bin as an account holder, see the -:doc:`Deleted files `_ +`Deleted files `_ section of the User Manual. .. note:: If the *Versions* app is enabled, versions associated with a deleted From d4b8c611a7ba13ebfd8bf0069ce5a9b765e75f68 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 28 Aug 2026 21:16:10 -0400 Subject: [PATCH 6/6] fix(admin): note trash bin cmd all users exception Signed-off-by: Josh --- admin_manual/configuration_files/trashbin_configuration.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 4ee3dc36928..fceae00b2ca 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -264,6 +264,11 @@ To expire eligible items for one or more accounts: sudo -E -u www-data php occ trashbin:expire USER_ID_1 USER_ID_2 +When no account IDs are provided, the command automatically discovers accounts +that have previously logged in. This normally covers all accounts that can have +trash-bin contents. For an account with imported or otherwise provisioned +trash-bin data but no recorded login, provide its account ID explicitly. + The command displays a progress bar when processing all accounts. Use ``--quiet`` to suppress the progress bar: