standardize occ command documentation

.github/workflows/check-occ-command.yml

@@ -0,0 +1,28 @@
+name: Check occ command syntax
+
+on:
+  pull_request:
+    paths:
+      - '**.rst'
+
+jobs:
+  check-occ-command:
+    name: Check occ command syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run script
+        run: |
+          RST_FILE="$(find ./ -name '*.rst')"
+          mapfile -t RST_FILE <<< "$RST_FILE"
+          for file in "${RST_FILE[@]}"; do
+            if [ "$(grep "php occ" "$file" | grep -v "sudo -E -u www-data php occ" | wc -l)" -gt 0 ]; then
+              printf "%b%s%b\n" "\e[0;31m" "$file does not use the 'sudo -E -u www-data php occ' syntax in some places which is required." "\e[0m"
+              echo "See $(grep "php occ" "$file" | grep -v "sudo -E -u www-data php occ")"
+              FAIL=1
+            fi
+          done
+          if [ -n "$FAIL" ]; then
+            exit 1
+          fi

admin_manual/ai/app_assistant.rst

@@ -17,7 +17,7 @@ You can install the *assistant* app via the "Apps" page in Nextcloud, or by exec
 
 .. code-block::
 
-   php occ app:enable assistant
+   sudo -E -u www-data php occ app:enable assistant
 
 App store
 ---------

admin_manual/ai/app_summary_bot.rst

@@ -87,7 +87,7 @@ After cloning this app *manually* (cloned via git to your apps directory) you wi
 
 .. code-block::
 
-   sudo -u <the_user_the_webserver_is_running_as> php /path/to/your/nextcloud/webroot/occ app_api:app:unregister summary_bot
+   sudo -E -u www-data php occ app_api:app:unregister summary_bot
 
 
 5. Register the Summary Bot so that your Nextcloud instance is aware of it
@@ -96,7 +96,7 @@ After cloning this app *manually* (cloned via git to your apps directory) you wi
 
 .. code-block::
 
-   sudo -u <the_user_the_webserver_is_running_as> php ./occ app_api:app:register summary_bot manual_install --json-info '{ "id": "summary_bot", "name": "Summary Bot", "daemon_config_name": "manual_install", "version": "1.0.0", "secret": "12345", "host": "0.0.0.0", "port": 9031, "scopes": ["AI_PROVIDERS", "TALK", "TALK_BOT"], "protocol": "http"}' --force-scopes --wait-finish
+   sudo -E -u www-data php occ app_api:app:register summary_bot manual_install --json-info '{ "id": "summary_bot", "name": "Summary Bot", "daemon_config_name": "manual_install", "version": "1.0.0", "secret": "12345", "host": "0.0.0.0", "port": 9031, "scopes": ["AI_PROVIDERS", "TALK", "TALK_BOT"], "protocol": "http"}' --force-scopes --wait-finish
 
 
 6. Enable the *Summary Bot* for the selected Chatroom via the three dots menu of the Chatroom (The Bots settings are located inside the *Bots* section)

admin_manual/ai/overview.rst

@@ -218,13 +218,13 @@ It would be best to run one command per screen session or per tmux window/pane t
 
 .. code-block::
 
-   set -e; while true; do sudo -u www-data occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
+   set -e; while true; do sudo -E -u www-data php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
 
 For Nextcloud-AIO you should use this command on the host server.
 
 .. code-block::
 
-   set -e; while true; do docker exec -u www-data -it nextcloud-aio-nextcloud php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
+   set -e; while true; do docker exec -it nextcloud-aio-nextcloud sudo -E -u www-data php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
 
 You may want to adjust the number of workers and the timeout (in seconds) to your needs.
 The logs of the worker can be checked by attaching to the screen or tmux session.
@@ -256,7 +256,7 @@ Systemd service
    #!/bin/sh
    echo "Starting Nextcloud AI Worker $1"
    cd /path/to/nextcloud
-   sudo -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob'
+   sudo -E -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob'
 
 You may want to adjust the timeout to your needs (in seconds).
 

admin_manual/configuration_database/bigint_identifiers.rst

@@ -9,18 +9,18 @@ and activity table has to be triggered manually by a console command.
 
 The command can safely be executed. It will show a success message when there is nothing to do::
 
-    sudo -u www-data php occ db:convert-filecache-bigint
+    sudo -E -u www-data php occ db:convert-filecache-bigint
     All tables already up to date!
 
 or otherwise ask for confirmation, before performing the heavy actions::
 
-    sudo -u www-data php occ db:convert-filecache-bigint
+    sudo -E -u www-data php occ db:convert-filecache-bigint
     This can take up to hours, depending on the number of files in your instance!
     Continue with the conversion (y/n)? [n]
 
 to suppress the confirmation message append ``--no-interaction`` to the argument list::
 
-    sudo -u www-data php occ db:convert-filecache-bigint --no-interaction
+    sudo -E -u www-data php occ db:convert-filecache-bigint --no-interaction
 
 
 .. note:: Similar to a normal update, you should shutdown your Apache or nginx server or enable maintenance

admin_manual/configuration_database/db_conversion.rst

@@ -34,7 +34,7 @@ The ``occ db:convert-type`` command handles all the tasks of the conversion. The
 
 ::
 
-  php occ db:convert-type [options] type username hostname database
+  sudo -E -u www-data php occ db:convert-type [options] type username hostname database
 
 ``type`` should be the target database type. The same values are available here as for the ``config.php`` ``dbtype`` parameter. It should be one of: ``mysql`` for MariaDB/MySQL, 
 ``pgsql`` for PostgreSQL, or ``oci`` for Oracle.
@@ -55,7 +55,7 @@ Let's convert our existing (functioning) sqlite3 installation to be MariaDB/MySQ
 
 ::
 
-  php occ db:convert-type --password="<password>" --port="3306" --all-apps mysql <username> <hostname> nextcloud
+  sudo -E -u www-data php occ db:convert-type --password="<password>" --port="3306" --all-apps mysql <username> <hostname> nextcloud
 
 .. note:: It was unnecessary to specify the port in this example because ``3306`` is already the default. We did so 
    merely for demonstration purposes and completeness in case the reader is using a non-standard port on their target 
@@ -68,7 +68,7 @@ If you are converting to a MySQL/MariaDB database, you will also want to set ``m
 
 ::
 
-   php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
+   sudo -E -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
 
 If you like, you can view the changes that were made by looking for the ``db*`` parameters in your ``config.php`` (you could also use this command before 
 doing the conversion to compare your configuration before/after):

admin_manual/configuration_database/mysql_4byte_support.rst

@@ -43,7 +43,7 @@ The result should look like this::
 3. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already::
 
    $ cd /var/www/nextcloud
-   $ sudo -u www-data php occ maintenance:mode --on
+   $ sudo -E -u www-data php occ maintenance:mode --on
 
 4. Change your databases character set and collation:
 
@@ -53,19 +53,19 @@ The result should look like this::
 
 5. Set the ``mysql.utf8mb4`` config to true in your config.php::
 
-    $ sudo -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
+    $ sudo -E -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
 
 6. Convert all existing tables to the new collation by running the repair step::
 
-    $ sudo -u www-data php occ maintenance:repair
+    $ sudo -E -u www-data php occ maintenance:repair
 
 .. note::
 
     This will also change the `ROW_FORMAT` to `DYNAMIC` for your tables.
 
 7. Disable maintenance mode::
 
-   $ sudo -u www-data php occ maintenance:mode --off
+   $ sudo -E -u www-data php occ maintenance:mode --off
 
 Now you should be able to use Emojis in your file names, calendar events, comments and many more.
 

admin_manual/configuration_files/big_file_upload_configuration.rst

@@ -159,7 +159,7 @@ Adjust chunk size on Nextcloud side
 
 For upload performance improvements in environments with high upload bandwidth, the server's upload chunk size may be adjusted::
 
- sudo -u www-data php occ config:system:set --type int --value 20971520 files.chunked_upload.max_size
+ sudo -E -u www-data php occ config:system:set --type int --value 20971520 files.chunked_upload.max_size
 
 Put in a value in bytes (in this example, 20MB). Set ``--value 0`` for no chunking at all.
 

admin_manual/configuration_files/external_storage/local.rst

@@ -17,7 +17,7 @@ are on Ubuntu Linux::
 
 Important: If you use consecutive commands, make sure, you are user ``www-data``::
 
- sudo -u www-data bash
+ sudo -E -u www-data bash
  cd /path/to/localdir
  mkdir data
 

admin_manual/configuration_files/external_storage_configuration_gui.rst

@@ -158,7 +158,7 @@ Nextcloud may not always be able to find out what has been
 changed remotely (files changed without going through Nextcloud), especially
 when it's very deep in the folder hierarchy of the external storage.
 
-You might need to setup a cron job that runs ``sudo -u www-data php occ files:scan --all``
+You might need to setup a cron job that runs ``sudo -E -u www-data php occ files:scan --all``
 (or replace ``--all`` with the user name, see also :doc:`../occ_command`)
 to trigger a rescan of the user's files periodically (for example every 15 minutes), which includes
 the mounted external storage.

admin_manual/configuration_mimetypes/index.rst

@@ -20,10 +20,10 @@ Once you have made changes to your ``mimetypealiases.json``, use the ``occ``
 command to propagate the changes through the system. This example is for 
 Ubuntu Linux::
 
-  $ sudo -u www-data php occ maintenance:mimetype:update-js
+  $ sudo -E -u www-data php occ maintenance:mimetype:update-js
 
   # you may also need to update the mimetype for existing files, see nextcloud/server#30566
-  $ sudo -u www-data php occ maintenance:mimetype:update-db --repair-filecache
+  $ sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache
 
 See :doc:`../occ_command` to learn more about ``occ``.
 

admin_manual/configuration_server/antivirus_configuration.rst

@@ -189,29 +189,29 @@ Get info about files in the scan queue
 
 ::
 
-    sudo -u www php occ files_antivirus:status [-v]
+    sudo -E -u www-data php occ files_antivirus:status [-v]
 
 
 Manually trigger the background scan
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
-    sudo -u www php occ files_antivirus:background-scan [-v] [-m MAX]
+    sudo -E -u www-data php occ files_antivirus:background-scan [-v] [-m MAX]
 
 Manually scan a single file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
-    sudo -u www php occ files_antivirus:scan <path>
+    sudo -E -u www-data php occ files_antivirus:scan <path>
 
 Mark a file as scanned or unscanned
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
-    sudo -u www php occ files_antivirus:mark <path> <scanned|unscanned>
+    sudo -E -u www-data php occ files_antivirus:mark <path> <scanned|unscanned>
 
 Files marked as scanned will not be scanned for the next four weeks.
 
@@ -230,4 +230,4 @@ Disabling background scan task
 
 You can disable background scan with occ to only scan files during upload::
 
-    sudo -u www php occ config:app:set files_antivirus av_background_scan --value="off"
+    sudo -E -u www-data php occ config:app:set files_antivirus av_background_scan --value="off"

admin_manual/configuration_server/config_sample_php_parameters.rst

@@ -3497,7 +3497,7 @@ Allows to create external storages of type "Local" in the web interface and APIs
 When disabled, it is still possible to create local storages with occ using
 the following command:
 
-% php occ files_external:create /mountpoint local null::null -c datadir=/path/to/data
+% sudo -E -u www-data php occ files_external:create /mountpoint local null::null -c datadir=/path/to/data
 
 Defaults to ``true``
 

admin_manual/configuration_user/authentication.rst

@@ -22,7 +22,7 @@ Nextcloud will delete unused passwords. Passwords set for *remote wipe* are dele
 
 The time spans can be overwritten with configuration::
 
-  php occ config:system:set token_auth_wipe_token_retention --type=int --value 2592000 # 60*60*24*30 - 30 days
-  php occ config:system:set token_auth_token_retention --type=int --value 63072000     # 60*60*24*365*2 - 2 years
+  sudo -E -u www-data php occ config:system:set token_auth_wipe_token_retention --type=int --value 2592000 # 60*60*24*30 - 30 days
+  sudo -E -u www-data php occ config:system:set token_auth_token_retention --type=int --value 63072000     # 60*60*24*365*2 - 2 years
 
 Values are set in **seconds**.

admin_manual/configuration_user/reset_admin_password.rst

@@ -17,7 +17,7 @@ learn more about using the ``occ`` command.
 
 ::
 
- $ sudo -u www-data php /var/www/nextcloud/occ user:resetpassword admin
+ $ sudo -E -u www-data php /var/www/nextcloud/occ user:resetpassword admin
  Enter a new password: 
  Confirm the new password: 
  Successfully reset password for admin

admin_manual/configuration_user/two_factor-auth.rst

@@ -82,7 +82,7 @@ Nextcloud will still consider the provider active for the user at login and show
 
 The associations of removed providers can be cleaned up via :ref:`occ <occ>`::
 
- sudo -u www-data php occ twofactorauth:cleanup <provider_id>
+ sudo -E -u www-data php occ twofactorauth:cleanup <provider_id>
 
 .. warning:: This operation is irreversible. Only run it for providers you do not intend to enable again as then you have to setup the configuration for all users from scratch.
 
@@ -92,7 +92,7 @@ Disabling two-factor authentication
 
 Two-factor providers can be disabled via :ref:`occ <occ>`::
 
- sudo -u www-data php occ twofactorauth:disable <uid> <provider_id>
+ sudo -E -u www-data php occ twofactorauth:disable <uid> <provider_id>
 
 This can be useful if the user forgot or lost their second factor.
 Afterwards users are free to enable this provider again via their personal settings.
@@ -101,4 +101,4 @@ Afterwards users are free to enable this provider again via their personal setti
 
 It is also possible to check the current two-factor user status via :ref:`occ <occ>`::
 
-  sudo -u www-data php occ twofactorauth:state <uid>
+  sudo -E -u www-data php occ twofactorauth:state <uid>

admin_manual/configuration_user/user_auth_ldap.rst

@@ -473,7 +473,7 @@ In new Nextcloud installations the home folder rule is enforced. This means that
 
 In migrated Nextcloud installations the old behavior still applies, which is using the Nextcloud username as the home folder when an LDAP attribute is not set. You may change this enforcing the home folder rule with the ``occ`` command in Nextcloud, like this example on Ubuntu::
 
-  sudo -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1
+  sudo -E -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1
 
 .. _LDAP_User_Profile_Attributes:
 
@@ -494,7 +494,7 @@ Please be aware:
   - Having misformatted data in LDAP will most probably leave you with empty user profile fields
   - Setting the global ``profile.enabled => false`` on ``config.php`` skips the code
 
-By calling ``php occ ldap:check-user --update <uid>`` the users data from LDAP will be displayed and the profile gets updated. To get the correct ``<uid>`` value for any user you can use ``php occ user:list``.
+By calling ``sudo -E -u www-data php occ ldap:check-user --update <uid>`` the users data from LDAP will be displayed and the profile gets updated. To get the correct ``<uid>`` value for any user you can use ``php occ user:list``.
 
 .. note:: After unsetting an attribute name here, the data won't be deleted from user profile. Setting an nonexisting attribute will empty the corresponding profile field.
 
@@ -662,7 +662,7 @@ It is not a per-configuration option.
 
 The value can be modified by::
 
-  sudo -u www-data php occ config:app:set user_ldap updateAttributesInterval --value=86400
+  sudo -E -u www-data php occ config:app:set user_ldap updateAttributesInterval --value=86400
 
 A value of 0 will update it on every of the named occasions.
 
@@ -678,7 +678,7 @@ search against. When a search is executed an exact match is required.
 
 Example usage::
 
-  $ php occ ldap:promote-group --help
+  $ sudo -E -u www-data php occ ldap:promote-group --help
   Description:
     declares the specified group as admin group (only one is possible per LDAP configuration)
 
@@ -693,15 +693,15 @@ Example usage::
   …
 
   # Example
-  $ php occ ldap:promote-group  "Nextcloud Admins"
+  $ sudo -E -u www-data php occ ldap:promote-group  "Nextcloud Admins"
   Promote Nextcloud Admins to the admin group (y|N)? y
   Group Nextcloud Admins was promoted
 
-  $ php occ ldap:promote-group  "Paramount Court"
+  $ sudo -E -u www-data php occ ldap:promote-group  "Paramount Court"
   Promote Nextcloud Admins to the admin group and demote Nextcloud Admins (Group ID: nextcloud_admins) (y|N)? y
   Group Paramount Court was promoted
 
-  $ php occ ldap:promote-group  "Paramount Court"
+  $ sudo -E -u www-data php occ ldap:promote-group  "Paramount Court"
   The specified group is already promoted
 
 .. note:: Note the group ID will only be displayed when it differs from the

admin_manual/configuration_user/user_auth_ldap_cleanup.rst

@@ -36,7 +36,7 @@ minutes later the next 50, and so on.
 The amount of users to check can be set to a custom value via occ command. The
 following example sets it to 300:
 
-``sudo -u www-data php occ config:app:set --value=300 user_ldap cleanUpJobChunkSize``
+``sudo -E -u www-data php occ config:app:set --value=300 user_ldap cleanUpJobChunkSize``
 
 There are two ``occ`` commands to use for examining a table of users marked as
 deleted, and then manually deleting them.  The ``occ`` command is in your 
@@ -46,15 +46,15 @@ your HTTP user. To learn more about ``occ``, see
 
 These examples are for Ubuntu Linux:
 
-1. ``sudo -u www-data php occ ldap:show-remnants`` displays a table with all 
+1. ``sudo -E -u www-data php occ ldap:show-remnants`` displays a table with all 
    users that have been marked as deleted, and their LDAP data.
 
-2. ``sudo -u www-data php occ user:delete [user]`` removes the user's data from the 
+2. ``sudo -E -u www-data php occ user:delete [user]`` removes the user's data from the 
    Nextcloud data directory.
 
 This example shows what the table of users marked as ``deleted`` looks like::
 
- $ sudo -u www-data php occ ldap:show-remnants
+ $ sudo -E -u www-data php occ ldap:show-remnants
  +-----------------+-----------------+------------------+--------------------------------------+
  | Nextcloud name  | Display Name    | LDAP UID         | LDAP DN                              |
  +-----------------+-----------------+------------------+--------------------------------------+
@@ -70,7 +70,7 @@ Following flags can be specified additionally:
 * ``--json``: instead of a table, the output is json-encoded. This makes it easy to process the data programmatically.
 
 
-Then you can run ``sudo -u www-data php occ user:delete aaliyah_brown`` to delete 
+Then you can run ``sudo -E -u www-data php occ user:delete aaliyah_brown`` to delete 
 user aaliyah_brown. You must use the user's Nextcloud name.
 
 Deleting local Nextcloud users