From 4a5d65d38bc2c9bd28ae0af7a7207f0c712250c8 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Thu, 20 Jun 2024 13:21:33 -0400 Subject: [PATCH] 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 854a68ae5..2f0496ece 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