From 1a8d31c43136d316c67b69ef7d57336ed6e8391a Mon Sep 17 00:00:00 2001 From: Josh Date: Thu, 20 Jun 2024 12:48:46 -0400 Subject: [PATCH 1/2] docs(occ): Some organizational clean-up of occ chapter Signed-off-by: Josh --- .../configuration_server/occ_command.rst | 216 +++++++++--------- 1 file changed, 114 insertions(+), 102 deletions(-) diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/configuration_server/occ_command.rst index ccd967e1679..854a68ae5d0 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/configuration_server/occ_command.rst @@ -9,48 +9,16 @@ interface. You can perform many common server operations with ``occ``, such as installing and upgrading Nextcloud, manage users, encryption, passwords, LDAP setting, and more. -``occ`` is in the :file:`nextcloud/` directory; for example -:file:`/var/www/nextcloud` on Ubuntu Linux. ``occ`` is a PHP script. **You must -run it as your HTTP user** to ensure that the correct permissions are maintained -on your Nextcloud files and directories. - -occ command Directory ---------------------- +Running ``occ`` +--------------- -* :ref:`http_user_label` -* :ref:`run_commands_in_maintenance_mode` -* :ref:`apps_commands_label` -* :ref:`background_jobs_selector_label` -* :ref:`config_commands_label` -* :ref:`dav_label` -* :ref:`database_conversion_label` -* :ref:`database_add_indices_label` -* :ref:`encryption_label` -* :ref:`federation_sync_label` -* :ref:`file_operations_label` -* :ref:`files_external_label` -* :ref:`integrity_check_label` -* :ref:`create_javascript_translation_files_label` -* :ref:`ldap_commands_label` -* :ref:`logging_commands_label` -* :ref:`maintenance_commands_label` -* :ref:`security_commands_label` -* :ref:`trashbin_label` -* :ref:`user_commands_label` -* :ref:`group_commands_label` -* :ref:`versions_label` -* :ref:`command_line_installation_label` -* :ref:`command_line_upgrade_label` -* :ref:`two_factor_auth_label` -* :ref:`disable_user_label` -* :ref:`system_tags_commands_label` -* :ref:`antivirus_commands_label` -* `Debugging`_ +``occ`` is located in the top of the Nextcloud installation folder; for example +:file:`/var/www/html/occ`. ``occ`` is a PHP script. .. _http_user_label: -Run occ as your HTTP user -------------------------- +**You must run ``occ`` as your HTTP user** to ensure that the correct permissions are maintained +on your Nextcloud files and directories. The HTTP user is different on the various Linux distributions: @@ -175,8 +143,8 @@ Alternatively, you can ``export`` the variable or use the ``-E`` switch for ``su NC_debug=true sudo -E -u www-data php occ status -Enabling autocompletion ------------------------ +Autocompletion +-------------- .. note:: Command autocompletion currently only works if the user you use to execute the occ commands has a profile. ``www-data`` in most cases is ``nologon`` and therefor **cannot** use this feature. @@ -203,10 +171,10 @@ shell's profile (eg. ``~/.bash_profile`` or ``~/.zshrc``). .. _run_commands_in_maintenance_mode: -Run commands in maintenance mode --------------------------------- +Maintenance mode +---------------- -In maintenance mode, apps are not loaded [1]_, so commands from apps are unavailable. Commands integrated into Nextcloud server are available in maintenance mode. +In maintenance mode, apps are not loaded [1]_, so commands from most apps are unavailable. Commands integrated into Nextcloud server are available in maintenance mode. We discourage the use of maintenance mode unless the command explicitly prompts you to do so or unless the commands' documentation explicitly states that maintenance mode should be used. @@ -215,10 +183,43 @@ A command may use events to communicate with other apps. An app can only react t .. [1] Exception: `The settings app is loaded `_ .. [2] `Calendar app event listener for UserDeletedEvent `_ + +``occ`` commands +---------------- + +* :ref:`apps_commands_label` +* :ref:`background_jobs_selector_label` +* :ref:`config_commands_label` +* :ref:`dav_label` +* :ref:`database_conversion_label` +* :ref:`database_add_indices_label` +* :ref:`encryption_label` +* :ref:`federation_sync_label` +* :ref:`file_operations_label` +* :ref:`files_external_label` +* :ref:`integrity_check_label` +* :ref:`create_javascript_translation_files_label` +* :ref:`ldap_commands_label` +* :ref:`logging_commands_label` +* :ref:`maintenance_commands_label` +* :ref:`security_commands_label` +* :ref:`trashbin_label` +* :ref:`user_commands_label` +* :ref:`group_commands_label` +* :ref:`versions_label` +* :ref:`command_line_installation_label` +* :ref:`command_line_upgrade_label` +* :ref:`two_factor_auth_label` +* :ref:`disable_user_label` +* :ref:`system_tags_commands_label` +* :ref:`antivirus_commands_label` +* `Debugging`_ + + .. _apps_commands_label: -Apps commands -------------- +``app`` - Manage apps +--------------------- The ``app`` commands list, enable, and disable apps:: @@ -302,8 +303,8 @@ To show available update(s) without updating:: .. _background_jobs_selector_label: -Background jobs selector ------------------------- +``occ`` ``background`` commands - Background jobs run method selector +------------------------------------------------------------- Use the ``background`` command to select which scheduler you want to use for controlling background jobs, Ajax, Webcron, or Cron. This is the same as using @@ -328,8 +329,8 @@ See :doc:`background_jobs_configuration` to learn more. .. _config_commands_label: -Config commands ---------------- +``config`` - Configure Nextcloud Server and Apps +------------------------------------------------ The ``config`` commands are used to configure the Nextcloud server:: @@ -506,8 +507,8 @@ before. If you want to be notified in that case, set the .. _dav_label: -Dav commands ------------- +``dav`` - Manage DAV (addressbooks, calendars, shares) +------------------------------------------------------ A set of commands to create and manage addressbooks and calendars:: @@ -591,8 +592,24 @@ address book`:: .. _database_conversion_label: -Database conversion -------------------- +``db`` - Database management +---------------------------- + +.. _database_add_indices_label: + +Add missing indices +^^^^^^^^^^^^^^^^^^^ + +It might happen that we add from time to time new indices to already existing database tables, +for example to improve performance. In order to check your database for missing indices run +following command:: + + sudo -u www-data php occ db:add-missing-indices + +Use option ``--dry-run`` to output the SQL queries without running them. + +Conversions +^^^^^^^^^^^ The SQLite database is good for testing, and for Nextcloud servers with small single-user workloads that do not use sync clients, but production servers with @@ -621,23 +638,10 @@ This is example converts SQLite to MySQL/MariaDB:: For a more detailed explanation see :doc:`../configuration_database/db_conversion` -.. _database_add_indices_label: - -Add missing indices -------------------- - -It might happen that we add from time to time new indices to already existing database tables, -for example to improve performance. In order to check your database for missing indices run -following command:: - - sudo -u www-data php occ db:add-missing-indices - -Use option ``--dry-run`` to output the SQL queries without running them. - .. _encryption_label: -Encryption ----------- +``encryption`` - Manage Encryption (Server-Side) +------------------------------------------------ ``occ`` includes a complete set of commands for managing encryption:: @@ -720,8 +724,8 @@ See :doc:`../configuration_files/encryption_configuration` to learn more. .. _federation_sync_label: -Federation sync ---------------- +``federation`` - Manage Federations +----------------------------------- .. note:: This command is only available when the "Federation" app (``federation``) is @@ -740,21 +744,26 @@ to synchronize federated servers:: .. _file_operations_label: -File operations +``files`` - Manage files --------------- -``occ`` has three commands for managing files in Nextcloud:: +``occ`` has various commands for managing files in Nextcloud:: files - files:cleanup Cleanup filecache - files:repair-tree Try and repair malformed filesystem tree structures - files:scan Rescan filesystem - files:scan-app-data Rescan the AppData folder - files:transfer-ownership All files' and folders' ownerships are moved to another - user. Outgoing shares are moved as well. - Incoming shares are not moved by default because the - sharing user holds the ownership of the respective files. - There is however an option to enable moving incoming shares. + files:scan rescan filesystem + files:cleanup cleanup filecache + files:transfer-ownership All files and folders are moved to another user - outgoing shares and incoming user file shares (optionally) are moved as well. + files:scan-app-data rescan the AppData folder + files:repair-tree Try and repair malformed filesystem tree structures + files:get Get the contents of a file + files:put Write contents of a file + files:delete Delete a file or folder + files:copy Copy a file or folder + files:move Move a file or folder + files:object:delete Delete an object from the object store + files:object:get Get the contents of an object + files:object:put Write a file to the object store + files:reminders List file reminders .. _occ_files_scan_label: @@ -913,7 +922,7 @@ See `user documentation Date: Thu, 20 Jun 2024 13:21:33 -0400 Subject: [PATCH 2/2] fixup: continuing adjustments Signed-off-by: Josh Richards --- .../configuration_server/occ_command.rst | 161 ++++++++++-------- 1 file changed, 88 insertions(+), 73 deletions(-) diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/configuration_server/occ_command.rst index 854a68ae5d0..2f0496ece5f 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/configuration_server/occ_command.rst @@ -1,31 +1,41 @@ .. _occ: -===================== -Using the occ command -===================== +============= +Using ``occ`` +============= Nextcloud's ``occ`` command (origins from "ownCloud Console") is Nextcloud's command-line interface. You can perform many common server operations with ``occ``, such as installing and upgrading Nextcloud, manage users, encryption, passwords, LDAP setting, and more. -Running ``occ`` ---------------- +------------ +Introduction +------------ + +Locating ``occ`` +================ ``occ`` is located in the top of the Nextcloud installation folder; for example :file:`/var/www/html/occ`. ``occ`` is a PHP script. .. _http_user_label: -**You must run ``occ`` as your HTTP user** to ensure that the correct permissions are maintained +Running as HTTP User +==================== + +You must run ``occ`` as your HTTP user to ensure that the correct permissions are maintained on your Nextcloud files and directories. The HTTP user is different on the various Linux distributions: -* The HTTP user and group in Debian/Ubuntu is www-data. -* The HTTP user and group in Fedora/CentOS is apache. -* The HTTP user and group in Arch Linux is http. -* The HTTP user in openSUSE is wwwrun, and the HTTP group is www. +* The HTTP user and group in Debian/Ubuntu is ``www-data``. +* The HTTP user and group in Fedora/CentOS is ``apache``. +* The HTTP user and group in Arch Linux is ``http``. +* The HTTP user in openSUSE is ``wwwrun``, and the HTTP group is ``www``. + +PHP Versions +============ If your HTTP server is configured to use a different PHP version than the default (/usr/bin/php), ``occ`` should be run with the same version. For @@ -38,6 +48,61 @@ example, in CentOS 6.5 with SCL-PHP70 installed, the command looks like this:: * ``su --command '/path/to/php ...' username`` -- Note here that the target user specification comes at the end, and the command to execute is specified first. * ``runuser --user username -- /path/to/php ...`` -- This wrapper might be used in container contexts (ex: Docker / ``arm32v7/nextcloud``) where both ``sudo`` and ``su`` wrapper utilities cannot be used. +Environment variables +===================== + +``sudo`` does not forward environment variables by default. Put the variables before the ``php`` command:: + + sudo -u www-data NC_debug=true php occ status + +Alternatively, you can ``export`` the variable or use the ``-E`` switch for ``sudo``:: + + NC_debug=true sudo -E -u www-data php occ status + +Autocompletion +============== + +.. note:: Command autocompletion currently only works if the user you use to execute the occ commands has a profile. + ``www-data`` in most cases is ``nologon`` and therefor **cannot** use this feature. + +Autocompletion is available for bash (and bash based consoles). +To enable it, you have to run **one** of the following commands:: + + # BASH ~4.x, ZSH + source <(/var/www/html/nextcloud/occ _completion --generate-hook) + + # BASH ~3.x, ZSH + /var/www/html/nextcloud/occ _completion --generate-hook | source /dev/stdin + + # BASH (any version) + eval $(/var/www/html/nextcloud/occ _completion --generate-hook) + +This will allow you to use autocompletion with the full path ``/var/www/html/nextcloud/occ ``. + +If you also want to use autocompletion on occ from within the directory without using the full path, +you need to specify ``--program occ`` after the ``--generate-hook``. + +If you want the completion to apply automatically for all new shell sessions, add the command to your +shell's profile (eg. ``~/.bash_profile`` or ``~/.zshrc``). + +.. _run_commands_in_maintenance_mode: + +Maintenance mode +================ + +In maintenance mode, apps are not loaded [1]_, so commands from most apps are unavailable. Commands integrated into Nextcloud server are available in maintenance mode. + +We discourage the use of maintenance mode unless the command explicitly prompts you to do so or unless the commands' documentation explicitly states that maintenance mode should be used. + +A command may use events to communicate with other apps. An app can only react to an event when loaded. Example: The command user:delete deletes a user account. UserDeletedEvent is emitted. Calendar app implements an event listener to delete user data [2]_. In maintenance mode, the Calendar app is not loaded, and hence the user data not deleted. + +.. [1] Exception: `The settings app is loaded `_ +.. [2] `Calendar app event listener for UserDeletedEvent `_ + +----------- +Basic Usage +----------- + Running ``occ`` with no options lists all commands and options, like this example on Ubuntu:: @@ -132,60 +197,10 @@ This output option is available on all list and list-like commands: ``status``, ``check``, ``app:list``, ``config:list``, ``encryption:status`` and ``encryption:list-modules`` -Environment variables -^^^^^^^^^^^^^^^^^^^^^ - -``sudo`` does not forward environment variables by default. Put the variables before the ``php`` command:: - - sudo -u www-data NC_debug=true php occ status - -Alternatively, you can ``export`` the variable or use the ``-E`` switch for ``sudo``:: - - NC_debug=true sudo -E -u www-data php occ status - -Autocompletion --------------- - -.. note:: Command autocompletion currently only works if the user you use to execute the occ commands has a profile. - ``www-data`` in most cases is ``nologon`` and therefor **cannot** use this feature. - -Autocompletion is available for bash (and bash based consoles). -To enable it, you have to run **one** of the following commands:: - - # BASH ~4.x, ZSH - source <(/var/www/html/nextcloud/occ _completion --generate-hook) - # BASH ~3.x, ZSH - /var/www/html/nextcloud/occ _completion --generate-hook | source /dev/stdin - - # BASH (any version) - eval $(/var/www/html/nextcloud/occ _completion --generate-hook) - -This will allow you to use autocompletion with the full path ``/var/www/html/nextcloud/occ ``. - -If you also want to use autocompletion on occ from within the directory without using the full path, -you need to specify ``--program occ`` after the ``--generate-hook``. - -If you want the completion to apply automatically for all new shell sessions, add the command to your -shell's profile (eg. ``~/.bash_profile`` or ``~/.zshrc``). - -.. _run_commands_in_maintenance_mode: - -Maintenance mode ----------------- - -In maintenance mode, apps are not loaded [1]_, so commands from most apps are unavailable. Commands integrated into Nextcloud server are available in maintenance mode. - -We discourage the use of maintenance mode unless the command explicitly prompts you to do so or unless the commands' documentation explicitly states that maintenance mode should be used. - -A command may use events to communicate with other apps. An app can only react to an event when loaded. Example: The command user:delete deletes a user account. UserDeletedEvent is emitted. Calendar app implements an event listener to delete user data [2]_. In maintenance mode, the Calendar app is not loaded, and hence the user data not deleted. - -.. [1] Exception: `The settings app is loaded `_ -.. [2] `Calendar app event listener for UserDeletedEvent `_ - - -``occ`` commands ----------------- +------------------ +Available commands +------------------ * :ref:`apps_commands_label` * :ref:`background_jobs_selector_label` @@ -219,7 +234,7 @@ A command may use events to communicate with other apps. An app can only react t .. _apps_commands_label: ``app`` - Manage apps ---------------------- +===================== The ``app`` commands list, enable, and disable apps:: @@ -303,8 +318,8 @@ To show available update(s) without updating:: .. _background_jobs_selector_label: -``occ`` ``background`` commands - Background jobs run method selector -------------------------------------------------------------- +``background`` - Background jobs run method selector +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the ``background`` command to select which scheduler you want to use for controlling background jobs, Ajax, Webcron, or Cron. This is the same as using @@ -330,7 +345,7 @@ See :doc:`background_jobs_configuration` to learn more. .. _config_commands_label: ``config`` - Configure Nextcloud Server and Apps ------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``config`` commands are used to configure the Nextcloud server:: @@ -745,7 +760,7 @@ to synchronize federated servers:: .. _file_operations_label: ``files`` - Manage files ---------------- +------------------------ ``occ`` has various commands for managing files in Nextcloud:: @@ -923,7 +938,7 @@ See `user documentation