From dd8bfe09dab259290e9ba33a6f24a5fed6aed79e Mon Sep 17 00:00:00 2001 From: Vincent Petry Date: Wed, 15 Sep 2021 14:20:42 +0200 Subject: [PATCH 1/2] Add option for incoming shares for transfer ownership Signed-off-by: Vincent Petry --- admin_manual/configuration_server/occ_command.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/configuration_server/occ_command.rst index 34cd6260084..ee5cfab400c 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/configuration_server/occ_command.rst @@ -726,15 +726,21 @@ entries that have no matching entries in the storage table. Transfer ^^^^^^^^ -You may transfer all files and shares from one user to another. This is useful +You may transfer all files and shares from one user to another. This is useful before removing a user:: sudo -u www-data php occ files:transfer-ownership - + It is also possible to transfer only one directory along with it's contents. This can be useful to restructure your organization or quotas. The ``--path`` argument is given as the path to the directory as seen from the source user:: sudo -u www-data php occ files:transfer-ownership --path="path_to_dir" +In case the incoming shares must be transferred as well, use the argument ``--transfer-incoming-shares``:: + + sudo -u www-data php occ files:transfer-ownership --transfer-incoming-shares=1 --path="path_to_dir" + +As an alternative, the system configuration option ``transferIncomingShares`` in config.php can be set to ``true`` to always transfer incoming shares. + Users may also transfer files or folders selectively by themselves. See `user documentation `_ for details. From 0b1217938c45153b463d8cd2231bb057a7ddaa17 Mon Sep 17 00:00:00 2001 From: Vincent Petry Date: Wed, 15 Sep 2021 14:49:30 +0200 Subject: [PATCH 2/2] Update summary of transfer ownership command Added note about default behavior for incoming shares. Signed-off-by: Vincent Petry --- .../configuration_server/occ_command.rst | 554 +++++++++--------- 1 file changed, 277 insertions(+), 277 deletions(-) diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/configuration_server/occ_command.rst index ee5cfab400c..1bf81f34ffb 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/configuration_server/occ_command.rst @@ -3,13 +3,13 @@ Using the occ command ===================== 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 +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 +``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 @@ -47,14 +47,14 @@ Run occ as your HTTP user ------------------------- 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 in openSUSE is wwwrun, and the HTTP group is www. -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 +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 example, in CentOS 6.5 with SCL-PHP70 installed, the command looks like this:: sudo -u apache /opt/rh/php70/root/usr/bin/php /var/www/html/nextcloud/occ @@ -64,10 +64,10 @@ 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. -Running ``occ`` with no options lists all commands and options, like this +Running ``occ`` with no options lists all commands and options, like this example on Ubuntu:: - sudo -u www-data php occ + sudo -u www-data php occ Nextcloud version 19.0.0 Usage: @@ -81,17 +81,17 @@ example on Ubuntu:: --no-ansi Disable ANSI output -n, --no-interaction Do not ask any interactive question --no-warnings Skip global warnings, show command output only - -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, + -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug Available commands: - check check dependencies of the server + check check dependencies of the server environment help Displays help for a command list Lists commands status show some status information - upgrade run upgrade routines after installation of - a new release. The release has to be + upgrade run upgrade routines after installation of + a new release. The release has to be installed before. This is the same as ``sudo -u www-data php occ list``. @@ -99,26 +99,26 @@ This is the same as ``sudo -u www-data php occ list``. Run it with the ``-h`` option for syntax help:: sudo -u www-data php occ -h - + Display your Nextcloud version:: sudo -u www-data php occ -V Nextcloud version 19.0.0 - + Query your Nextcloud server status:: sudo -u www-data php occ status - installed: true - version: 19.0.0.12 - versionstring: 19.0.0 - - edition: + - edition: -``occ`` has options, commands, and arguments. Options and arguments are +``occ`` has options, commands, and arguments. Options and arguments are optional, while commands are required. The syntax is:: occ [options] command [arguments] - -Get detailed information on individual commands with the ``help`` command, like + +Get detailed information on individual commands with the ``help`` command, like this example for the ``maintenance:mode`` command:: sudo -u www-data php occ help maintenance:mode @@ -135,7 +135,7 @@ this example for the ``maintenance:mode`` command:: --no-ansi Disable ANSI output -n, --no-interaction Do not ask any interactive question --no-warnings Skip global warnings, show command output only - -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, + -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug The ``status`` command from above has an option to define the output format. @@ -208,41 +208,41 @@ Install but don't enable:: sudo -u www-data php occ app:install --keep-disabled twofactor_totp -List all of your installed apps, and show whether they are +List all of your installed apps, and show whether they are enabled or disabled:: sudo -u www-data php occ app:list - + Enable an app, for example the External Storage Support app:: sudo -u www-data php occ app:enable files_external files_external enabled - + Disable an app:: sudo -u www-data php occ app:disable files_external - files_external disabled + files_external disabled You can get the full filepath to an app:: - + sudo -u www-data php occ app:getpath notifications /var/www/nextcloud/apps/notifications To update an app, for instance Contacts:: - - sudo -u www-data php occ app:update contacts + + sudo -u www-data php occ app:update contacts To update all apps:: - + sudo -u www-data php occ app:update --all -.. _background_jobs_selector_label: +.. _background_jobs_selector_label: Background jobs 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 +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 the **Cron** section on your Nextcloud Admin page:: background @@ -283,16 +283,16 @@ You can list all configuration values with one command:: sudo -u www-data php occ config:list -By default, passwords and other sensitive data are omitted from the report, so -the output can be posted publicly (e.g. as part of a bug report). In order to -generate a full backport of all configuration values the ``--private`` flag +By default, passwords and other sensitive data are omitted from the report, so +the output can be posted publicly (e.g. as part of a bug report). In order to +generate a full backport of all configuration values the ``--private`` flag needs to be set:: sudo -u www-data php occ config:list --private -The exported content can also be imported again to allow the fast setup of -similar instances. The import command will only add or update values. Values -that exist in the current configuration, but not in the one that is being +The exported content can also be imported again to allow the fast setup of +similar instances. The import command will only add or update values. Values +that exist in the current configuration, but not in the one that is being imported are left untouched:: sudo -u www-data php occ config:import filename.json @@ -306,7 +306,7 @@ It is also possible to import remote files, by piping the input:: While it is possible to update/set/delete the versions and installation statuses of apps and Nextcloud itself, it is **not** recommended to do this directly. Use the ``occ app:enable``, ``occ app:disable`` and ``occ app:update`` - commands instead. + commands instead. Getting a single configuration value ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -324,24 +324,24 @@ Setting a single configuration value These commands set the value of a single app or system configuration:: - sudo -u www-data php occ config:system:set logtimezone + sudo -u www-data php occ config:system:set logtimezone --value="Europe/Berlin" System config value logtimezone set to Europe/Berlin - sudo -u www-data php occ config:app:set files_sharing + sudo -u www-data php occ config:app:set files_sharing incoming_server2server_share_enabled --value="yes" --type=boolean Config value incoming_server2server_share_enabled for app files_sharing set to yes -The ``config:system:set`` command creates the value, if it does not already +The ``config:system:set`` command creates the value, if it does not already exist. To update an existing value, set ``--update-only``:: - sudo -u www-data php occ config:system:set doesnotexist --value="true" + sudo -u www-data php occ config:system:set doesnotexist --value="true" --type=boolean --update-only Value not updated, as it has not been set before. -Note that in order to write a Boolean, float, or integer value to the -configuration file, you need to specify the type on your command. This -applies only to the ``config:system:set`` command. The following values are +Note that in order to write a Boolean, float, or integer value to the +configuration file, you need to specify the type on your command. This +applies only to the ``config:system:set`` command. The following values are known: * ``boolean`` @@ -351,7 +351,7 @@ known: When you want to e.g. disable the maintenance mode run the following command:: - sudo -u www-data php occ config:system:set maintenance --value=false + sudo -u www-data php occ config:system:set maintenance --value=false --type=boolean Nextcloud is in maintenance mode - no app have been loaded System config value maintenance set to boolean false @@ -372,7 +372,7 @@ second ``name`` in the ``config:system:set`` command, separated by a space. For example, to replace ``sample.tld`` with ``example.com``, ``trusted_domains => 2`` needs to be set:: - sudo -u www-data php occ config:system:set trusted_domains 2 + sudo -u www-data php occ config:system:set trusted_domains 2 --value=example.com System config value trusted_domains => 2 set to string example.com @@ -420,16 +420,16 @@ The delete command will by default not complain if the configuration was not set before. If you want to be notified in that case, set the ``--error-if-not-exists`` flag:: - sudo -u www-data php occ config:system:delete doesnotexist + sudo -u www-data php occ config:system:delete doesnotexist --error-if-not-exists - Config provisioning_api of app appname could not be deleted because it did not + Config provisioning_api of app appname could not be deleted because it did not exist - -.. _dav_label: - + +.. _dav_label: + Dav commands ------------ - + A set of commands to create and manage addressbooks and calendars:: dav @@ -440,12 +440,12 @@ A set of commands to create and manage addressbooks and calendars:: dav:remove-invalid-shares Remove invalid dav shares dav:send-event-reminders Sends event reminders dav:sync-birthday-calendar Synchronizes the birthday calendar - dav:sync-system-addressbook Synchronizes users to the system + dav:sync-system-addressbook Synchronizes users to the system addressbook - - -The syntax for ``dav:create-addressbook`` and ``dav:create-calendar`` is -``dav:create-addressbook [user] [name]``. This example creates the addressbook + + +The syntax for ``dav:create-addressbook`` and ``dav:create-calendar`` is +``dav:create-addressbook [user] [name]``. This example creates the addressbook ``mollybook`` for the user molly:: sudo -u www-data php occ dav:create-addressbook molly mollybook @@ -453,22 +453,22 @@ The syntax for ``dav:create-addressbook`` and ``dav:create-calendar`` is This example creates a new calendar for molly:: sudo -u www-data php occ dav:create-calendar molly mollycal - + Molly will immediately see these in the Calendar and Contacts apps. -``dav:lists-calendars [user]`` will display a table listing the calendars for a given user. +``dav:lists-calendars [user]`` will display a table listing the calendars for a given user. This example will list all calendars for user annie:: sudo -u www-data php occ dav:list-calendars annie - + ``dav::move-calendar [name] [sourceuid] [destinationuid]`` allows the admin -to move a calendar named ``name`` from a user ``sourceuid`` to the user +to move a calendar named ``name`` from a user ``sourceuid`` to the user ``destinationuid``. You can use the force option `-f` to enforce the move if there are conflicts with existing shares. The system will also generate a new unique calendar name in case there is a conflict over the destination user. This example will move calendar named personal from user dennis to user sabine:: - + sudo -u www-data php occ dav:move-calendar personal dennis sabine ``dav:remove-invalid-shares`` will remove invalid shares created by a bug into the calendar app @@ -478,33 +478,33 @@ cron job to send event reminder notifications. See :doc:`../groupware/calendar` for more information on how to use this command. -``dav:sync-birthday-calendar`` adds all birthdays to your calendar from -addressbooks shared with you. This example syncs to your calendar from user +``dav:sync-birthday-calendar`` adds all birthdays to your calendar from +addressbooks shared with you. This example syncs to your calendar from user bernie:: sudo -u www-data php occ dav:sync-birthday-calendar bernie - -``dav:sync-system-addressbook`` synchronizes all users to the system + +``dav:sync-system-addressbook`` synchronizes all users to the system addressbook:: sudo -u www-data php occ dav:sync-system-addressbook -.. _database_conversion_label: - +.. _database_conversion_label: + Database conversion ------------------- -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 -multiple users should use MariaDB, MySQL, or PostgreSQL. You can use ``occ`` to +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 +multiple users should use MariaDB, MySQL, or PostgreSQL. You can use ``occ`` to convert from SQLite to one of these other databases. :: db - db:convert-type Convert the Nextcloud database to the newly + db:convert-type Convert the Nextcloud database to the newly configured one - db:generate-change-script generates the change script from the current + db:generate-change-script generates the change script from the current connected db to db_structure.xml You need: @@ -513,12 +513,12 @@ You need: * The login and password of a database admin user. * The database port number, if it is a non-standard port. -This is example converts SQLite to MySQL/MariaDB:: +This is example converts SQLite to MySQL/MariaDB:: - sudo -u www-data php occ db:convert-type mysql oc_dbuser 127.0.0.1 + sudo -u www-data php occ db:convert-type mysql oc_dbuser 127.0.0.1 oc_database -For a more detailed explanation see +For a more detailed explanation see :doc:`../configuration_database/db_conversion` .. _database_add_indices_label: @@ -541,22 +541,22 @@ Encryption encryption encryption:change-key-storage-root Change key storage root - encryption:decrypt-all Disable server-side encryption and + encryption:decrypt-all Disable server-side encryption and decrypt all files encryption:disable Disable encryption encryption:enable Enable encryption - encryption:enable-master-key Enable the master key. Only available - for fresh installations with no existing - encrypted data! There is also no way to + encryption:enable-master-key Enable the master key. Only available + for fresh installations with no existing + encrypted data! There is also no way to disable it again. encryption:encrypt-all Encrypt all files for all users encryption:list-modules List all available encryption modules encryption:set-default-module Set the encryption default module encryption:show-key-storage-root Show current key storage root encryption:status Lists the current status of encryption - -``encryption:status`` shows whether you have active encryption, and your default -encryption module. To enable encryption you must first enable the Encryption + +``encryption:status`` shows whether you have active encryption, and your default +encryption module. To enable encryption you must first enable the Encryption app, and then run ``encryption:enable``:: sudo -u www-data php occ app:enable encryption @@ -564,69 +564,69 @@ app, and then run ``encryption:enable``:: sudo -u www-data php occ encryption:status - enabled: true - defaultModule: OC_DEFAULT_MODULE - -``encryption:change-key-storage-root`` is for moving your encryption keys to a -different folder. It takes one argument, ``newRoot``, which defines your new + +``encryption:change-key-storage-root`` is for moving your encryption keys to a +different folder. It takes one argument, ``newRoot``, which defines your new root folder:: sudo -u www-data php occ encryption:change-key-storage-root /etc/oc-keys - + You can see the current location of your keys folder:: sudo -u www-data php occ encryption:show-key-storage-root Current key storage root: default storage location (data/) - -``encryption:list-modules`` displays your available encryption modules. You will -see a list of modules only if you have enabled the Encryption app. Use + +``encryption:list-modules`` displays your available encryption modules. You will +see a list of modules only if you have enabled the Encryption app. Use ``encryption:set-default-module [module name]`` to set your desired module. -``encryption:encrypt-all`` encrypts all data files for all users. You must first +``encryption:encrypt-all`` encrypts all data files for all users. You must first put your Nextcloud server into :ref:`maintenance -mode` to prevent any user activity until encryption +mode` to prevent any user activity until encryption is completed. -``encryption:decrypt-all`` decrypts all user data files, or optionally a single +``encryption:decrypt-all`` decrypts all user data files, or optionally a single user:: sudo -u www-data php occ encryption:decrypt freda -Users must have enabled recovery keys on their Personal pages. You must first +Users must have enabled recovery keys on their Personal pages. You must first put your Nextcloud server into :ref:`maintenance -mode ` to prevent any user activity until +mode ` to prevent any user activity until decryption is completed. Note that if you do not have master key/recovery key enabled, you can ONLY decrypt files per user, one user at a time and NOT when in maintenance mode. You will need the users' password to decrypt the files. -Use ``encryption:disable`` to disable your encryption module. You must first put +Use ``encryption:disable`` to disable your encryption module. You must first put your Nextcloud server into :ref:`maintenance mode ` to prevent any user activity. -``encryption:enable-master-key`` creates a new master key, which is used for all -user data instead of individual user keys. This is especially useful to enable -single-sign on. Use this only on fresh installations with no existing data, or -on systems where encryption has not already been enabled. It is not possible to +``encryption:enable-master-key`` creates a new master key, which is used for all +user data instead of individual user keys. This is especially useful to enable +single-sign on. Use this only on fresh installations with no existing data, or +on systems where encryption has not already been enabled. It is not possible to disable it. See :doc:`../configuration_files/encryption_configuration` to learn more. - + .. _federation_sync_label: - + Federation sync --------------- .. note:: This command is only available when the "Federation" app (``federation``) is enabled. - + Synchronize the addressbooks of all federated Nextcloud servers:: - federation:sync-addressbooks Synchronizes addressbooks of all + federation:sync-addressbooks Synchronizes addressbooks of all federated clouds In Nextcloud, servers connected with federation shares can share user -address books, and auto-complete usernames in share dialogs. Use this command +address books, and auto-complete usernames in share dialogs. Use this command to synchronize federated servers:: sudo -u www-data php occ federation:sync-addressbooks @@ -642,23 +642,23 @@ File operations files:cleanup cleanup filecache files:scan rescan filesystem files:scan-app-data rescan the AppData folder - files:transfer-ownership All files' and folders' ownerships are moved to another + files:transfer-ownership All files' and folders' ownerships are moved to another user. Outgoing shares are moved as well. - Incoming shares are not moved because the sharing user - holds the ownership of the respective files and therefore - owns the decision which actual users/groups to be shared with. + 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. Scan ^^^^ -The ``files:scan`` command scans for new files and updates the file cache. You -may rescan all files, per-user, a space-delimited list of users, and limit the -search path. If not using ``--quiet``, statistics will be shown at the end of +The ``files:scan`` command scans for new files and updates the file cache. You +may rescan all files, per-user, a space-delimited list of users, and limit the +search path. If not using ``--quiet``, statistics will be shown at the end of the scan:: sudo -u www-data php occ files:scan --help Usage: - files:scan [-p|--path="..."] [-q|--quiet] [-v|vv|vvv --verbose] [--all] + files:scan [-p|--path="..."] [-q|--quiet] [-v|vv|vvv --verbose] [--all] [user_id1] ... [user_idN] Arguments: @@ -668,7 +668,7 @@ the scan:: --path limit rescan to the user/path given --all will rescan all files of all known users --quiet suppress any output - --verbose files and directories being processed are shown + --verbose files and directories being processed are shown additionally during scanning --unscanned scan only previously unscanned files @@ -678,10 +678,10 @@ Note for option --unscanned: In general there is a background job (through cron) that will do that scan periodically. The --unscanned option makes it possible to trigger this from the CLI. -When using the ``--path`` option, the path must consist of following +When using the ``--path`` option, the path must consist of following components:: - "user_id/files/path" + "user_id/files/path" or "user_id/files/mount_name" or @@ -693,10 +693,10 @@ Example:: --path="/alice/files/Music" -In the example above, the user_id ``alice`` is determined implicitly from the +In the example above, the user_id ``alice`` is determined implicitly from the path component given. -The ``--path``, ``--all`` and ``[user_id]`` parameters are exclusive - only +The ``--path``, ``--all`` and ``[user_id]`` parameters are exclusive - only one must be specified. Scan appdata @@ -720,8 +720,8 @@ with the files on the actual storage.:: Cleanup ^^^^^^^ -``files:cleanup`` tidies up the server's file cache by deleting all file -entries that have no matching entries in the storage table. +``files:cleanup`` tidies up the server's file cache by deleting all file +entries that have no matching entries in the storage table. Transfer ^^^^^^^^ @@ -779,14 +779,14 @@ Commands for managing external storage:: files_external:verify Verify mount configuration files_external:notify Listen for active update notifications for a configured external mount -These commands replicate the functionality in the Nextcloud Web GUI, plus two new -features: ``files_external:export`` and ``files_external:import``. +These commands replicate the functionality in the Nextcloud Web GUI, plus two new +features: ``files_external:export`` and ``files_external:import``. -Use ``files_external:export`` to export all admin mounts to stdout, and -``files_external:export [user_id]`` to export the mounts of the specified -Nextcloud user. +Use ``files_external:export`` to export all admin mounts to stdout, and +``files_external:export [user_id]`` to export the mounts of the specified +Nextcloud user. -Use ``files_external:import [filename]`` to import legacy JSON configurations, +Use ``files_external:import [filename]`` to import legacy JSON configurations, and to copy external mount configurations to another Nextcloud server. .. _integrity_check_label: @@ -801,16 +801,16 @@ Apps which have a ``Featured`` tag MUST be code signed with Nextcloud. Unsigned integrity:check-core Check core integrity using a signature. integrity:sign-app Signs an app using a private key. integrity:sign-core Sign core using a private key - -After creating your signing key, sign your app like this example:: - + +After creating your signing key, sign your app like this example:: + sudo -u www-data php occ integrity:sign-app --privateKey=/Users/lukasreschke/contacts.key --certificate=/Users/lukasreschke/CA/contacts.crt --path=/Users/lukasreschke/Programming/contacts - + Verify your app:: sudo -u www-data php occ integrity:check-app --path=/pathto/app appname - -When it returns nothing, your app is signed correctly. When it returns a message then there is an error. See `Code Signing + +When it returns nothing, your app is signed correctly. When it returns a message then there is an error. See `Code Signing `_ in the Developer manual for more detailed information. .. TODO ON RELEASE: Update version number above on release @@ -820,15 +820,15 @@ When it returns nothing, your app is signed correctly. When it returns a message See :doc:`../issues/code_signing` to learn more. .. _create_javascript_translation_files_label: - + l10n, create JavaScript translation files for apps -------------------------------------------------- This command is for app developers to update their translation mechanism from ownCloud 7 to Nextcloud. -.. _ldap_commands_label: - +.. _ldap_commands_label: + LDAP commands ------------- @@ -836,7 +836,7 @@ LDAP commands These commands are only available when the "LDAP user and group backend" app (``user_ldap``) is enabled. -These LDAP commands appear only when you have enabled the LDAP app. Then +These LDAP commands appear only when you have enabled the LDAP app. Then you can run the following LDAP commands with ``occ``:: ldap @@ -846,84 +846,84 @@ you can run the following LDAP commands with ``occ``:: ldap:search executes a user or group search ldap:set-config modifies an LDAP configuration ldap:show-config shows the LDAP configuration - ldap:show-remnants shows which users are not available on - LDAP anymore, but have remnants in + ldap:show-remnants shows which users are not available on + LDAP anymore, but have remnants in Nextcloud. ldap:test-config tests an LDAP configuration Search for an LDAP user, using this syntax:: - sudo -u www-data php occ ldap:search [--group] [--offset="..."] + sudo -u www-data php occ ldap:search [--group] [--offset="..."] [--limit="..."] search -Searches will match at the beginning of the attribute value only. This example +Searches will match at the beginning of the attribute value only. This example searches for givenNames that start with "rob":: sudo -u www-data php occ ldap:search "rob" - -This will find robbie, roberta, and robin. Broaden the search to find, for + +This will find robbie, roberta, and robin. Broaden the search to find, for example, ``jeroboam`` with the asterisk wildcard:: sudo -u www-data php occ ldap:search "*rob" -User search attributes are set with ``ldap:set-config`` -(below). For example, if your search attributes are -``givenName`` and ``sn`` you can find users by first name + last name very -quickly. For example, you'll find Terri Hanson by searching for ``te ha``. +User search attributes are set with ``ldap:set-config`` +(below). For example, if your search attributes are +``givenName`` and ``sn`` you can find users by first name + last name very +quickly. For example, you'll find Terri Hanson by searching for ``te ha``. Trailing whitespaces are ignored. - -Check if an LDAP user exists. This works only if the Nextcloud server is + +Check if an LDAP user exists. This works only if the Nextcloud server is connected to an LDAP server:: sudo -u www-data php occ ldap:check-user robert - -``ldap:check-user`` will not run a check when it finds a disabled LDAP -connection. This prevents users that exist on disabled LDAP connections from -being marked as deleted. If you know for certain that the user you are searching for -is not in one of the disabled connections, and exists on an active connection, + +``ldap:check-user`` will not run a check when it finds a disabled LDAP +connection. This prevents users that exist on disabled LDAP connections from +being marked as deleted. If you know for certain that the user you are searching for +is not in one of the disabled connections, and exists on an active connection, use the ``--force`` option to force it to check all active LDAP connections:: sudo -u www-data php occ ldap:check-user --force robert -``ldap:create-empty-config`` creates an empty LDAP configuration. The first +``ldap:create-empty-config`` creates an empty LDAP configuration. The first one you create has no ``configID``, like this example:: sudo -u www-data php occ ldap:create-empty-config Created new configuration with configID '' - -This is a holdover from the early days, when there was no option to create -additional configurations. The second, and all subsequent, configurations + +This is a holdover from the early days, when there was no option to create +additional configurations. The second, and all subsequent, configurations that you create are automatically assigned IDs:: - + sudo -u www-data php occ ldap:create-empty-config - Created new configuration with configID 's01' - + Created new configuration with configID 's01' + Then you can list and view your configurations:: sudo -u www-data php occ ldap:show-config - + And view the configuration for a single configID:: sudo -u www-data php occ ldap:show-config s01 - -``ldap:delete-config [configID]`` deletes an existing LDAP configuration:: + +``ldap:delete-config [configID]`` deletes an existing LDAP configuration:: sudo -u www-data php occ ldap:delete s01 Deleted configuration with configID 's01' - -The ``ldap:set-config`` command is for manipulating configurations, like this + +The ``ldap:set-config`` command is for manipulating configurations, like this example that sets search attributes:: - - sudo -u www-data php occ ldap:set-config s01 ldapAttributesForUserSearch + + sudo -u www-data php occ ldap:set-config s01 ldapAttributesForUserSearch "cn;givenname;sn;displayname;mail" - -``ldap:test-config`` tests whether your configuration is correct and can bind to + +``ldap:test-config`` tests whether your configuration is correct and can bind to the server:: sudo -u www-data php occ ldap:test-config s01 The configuration is valid and the connection could be established! - -``ldap:show-remnants`` is for cleaning up the LDAP mappings table, and is + +``ldap:show-remnants`` is for cleaning up the LDAP mappings table, and is documented in :doc:`../configuration_user/user_auth_ldap_cleanup`. .. _logging_commands_label: @@ -941,7 +941,7 @@ These commands view and configure your Nextcloud logging preferences:: Run ``log:file [--] [--enable] [--file] [--rotate-size]`` to see your current logging status:: - sudo -u www-data php occ log:file + sudo -u www-data php occ log:file Log backend Nextcloud: enabled Log file: /opt/nextcloud/data/nextcloud.log Rotate at: disabled @@ -950,7 +950,7 @@ Run ``log:file [--] [--enable] [--file] [--rotate-size]`` to see your current lo * ``--file`` sets a different log file path. * ``--rotate-size`` sets your rotation by log file size in bytes with; 0 disables rotation. -``log:manage [--backend] [--level] [--timezone]`` sets your logging backend, log level, and timezone. The defaults +``log:manage [--backend] [--level] [--timezone]`` sets your logging backend, log level, and timezone. The defaults are ``file``, ``warning``, and ``UTC``. Available options are: * ``--backend [file, syslog, errorlog, systemd]`` @@ -958,11 +958,11 @@ are ``file``, ``warning``, and ``UTC``. Available options are: * ``--timezone`` according to https://www.php.net/manual/en/timezones.php .. _maintenance_commands_label: - + Maintenance commands -------------------- -Use these commands when you upgrade Nextcloud, manage encryption, perform +Use these commands when you upgrade Nextcloud, manage encryption, perform backups and other tasks that require locking users out until you are finished:: maintenance @@ -974,10 +974,10 @@ backups and other tasks that require locking users out until you are finished:: maintenance:theme:update Apply custom theme changes maintenance:update:htaccess Updates the .htaccess file -``maintenance:mode`` locks the sessions of all logged-in users, including -administrators, and displays a status screen warning that the server is in -maintenance mode. Users who are not already logged in cannot log in until -maintenance mode is turned off. When you take the server out of maintenance mode +``maintenance:mode`` locks the sessions of all logged-in users, including +administrators, and displays a status screen warning that the server is in +maintenance mode. Users who are not already logged in cannot log in until +maintenance mode is turned off. When you take the server out of maintenance mode logged-in users must refresh their Web browsers to continue working:: sudo -u www-data php occ maintenance:mode --on @@ -987,16 +987,16 @@ After restoring a backup of your data directory or the database, you should alwa call ``maintenance:data-fingerprint`` once. This changes the ETag for all files in the communication with sync clients, allowing them to realize a file was modified. -The ``maintenance:repair`` command runs automatically during upgrades to clean -up the database, so while you can run it manually there usually isn't a need +The ``maintenance:repair`` command runs automatically during upgrades to clean +up the database, so while you can run it manually there usually isn't a need to:: - + sudo -u www-data php occ maintenance:repair - -``maintenance:mimetype:update-db`` updates the Nextcloud database and file cache -with changed mimetypes found in ``config/mimetypemapping.json``. Run this -command after modifying ``config/mimetypemapping.json``. If you change a -mimetype, run ``maintenance:mimetype:update-db --repair-filecache`` to apply the + +``maintenance:mimetype:update-db`` updates the Nextcloud database and file cache +with changed mimetypes found in ``config/mimetypemapping.json``. Run this +command after modifying ``config/mimetypemapping.json``. If you change a +mimetype, run ``maintenance:mimetype:update-db --repair-filecache`` to apply the change to existing files. Run the ``maintenance:theme:update`` command if the icons of your custom theme are not updated correctly. This updates the mimetypelist.js and cleares the image cache. @@ -1016,16 +1016,16 @@ Use these commands to manage server-wide SSL certificates. These are useful when This example lists your installed certificates:: sudo -u www-data php occ security:certificates - + Import a new certificate:: sudo -u www-data php occ security:import /path/to/certificate - + Remove a certificate:: sudo -u www-data php occ security:remove [certificate name] -.. _trashbin_label: +.. _trashbin_label: Trashbin -------- @@ -1034,37 +1034,37 @@ Trashbin This command is only available when the "Deleted files" app (``files_trashbin``) is enabled. -The ``trashbin:cleanup [--all-users] [--] [...]`` command removes the deleted files of the specified +The ``trashbin:cleanup [--all-users] [--] [...]`` command removes the deleted files of the specified users in a space-delimited list, or all users if --all-users is specified. :: - + trashbin trashbin:cleanup [--all-users] [--] [...] Remove deleted files - -This example removes the deleted files of all users:: - - sudo -u www-data php occ trashbin:cleanup --all-users + +This example removes the deleted files of all users:: + + sudo -u www-data php occ trashbin:cleanup --all-users Remove all deleted files for all users Remove deleted files for users on backend Database freda molly stash - rosa + rosa edward -This example removes the deleted files of users molly and freda:: +This example removes the deleted files of users molly and freda:: sudo -u www-data php occ trashbin:cleanup molly freda Remove deleted files of molly Remove deleted files of freda -.. _user_commands_label: - +.. _user_commands_label: + User commands ------------- -The ``user`` commands create and remove users, reset passwords, display a simple +The ``user`` commands create and remove users, reset passwords, display a simple report showing how many users you have, and when a user was last logged in:: user @@ -1079,67 +1079,67 @@ report showing how many users you have, and when a user was last logged in:: user:setting Read and modify user settings -You can create a new user with their display name, login name, and any group +You can create a new user with their display name, login name, and any group memberships with the ``user:add`` command. The syntax is:: - user:add [--password-from-env] [--display-name[="..."]] [-g|--group[="..."]] + user:add [--password-from-env] [--display-name[="..."]] [-g|--group[="..."]] uid -The ``display-name`` corresponds to the **Full Name** on the Users page in your -Nextcloud Web UI, and the ``uid`` is their **Username**, which is their -login name. This example adds new user Layla Smith, and adds them to the -**users** and **db-admins** groups. Any groups that do not exist are created:: - - sudo -u www-data php occ user:add --display-name="Layla Smith" +The ``display-name`` corresponds to the **Full Name** on the Users page in your +Nextcloud Web UI, and the ``uid`` is their **Username**, which is their +login name. This example adds new user Layla Smith, and adds them to the +**users** and **db-admins** groups. Any groups that do not exist are created:: + + sudo -u www-data php occ user:add --display-name="Layla Smith" --group="users" --group="db-admins" layla - Enter password: - Confirm password: + Enter password: + Confirm password: The user "layla" was created successfully Display name set to "Layla Smith" User "layla" added to group "users" User "layla" added to group "db-admins" -Go to your Users page, and you will see your new user. +Go to your Users page, and you will see your new user. -``password-from-env`` allows you to set the user's password from an environment -variable. This prevents the password from being exposed to all users via the -process list, and will only be visible in the history of the user (root) -running the command. This also permits creating scripts for adding multiple new +``password-from-env`` allows you to set the user's password from an environment +variable. This prevents the password from being exposed to all users via the +process list, and will only be visible in the history of the user (root) +running the command. This also permits creating scripts for adding multiple new users. -To use ``password-from-env`` you must run as "real" root, rather than ``sudo``, -because ``sudo`` strips environment variables. This example adds new user Fred +To use ``password-from-env`` you must run as "real" root, rather than ``sudo``, +because ``sudo`` strips environment variables. This example adds new user Fred Jones:: export OC_PASS=newpassword - su -s /bin/sh www-data -c 'php occ user:add --password-from-env + su -s /bin/sh www-data -c 'php occ user:add --password-from-env --display-name="Fred Jones" --group="users" fred' The user "fred" was created successfully Display name set to "Fred Jones" - User "fred" added to group "users" + User "fred" added to group "users" -You can reset any user's password, including administrators (see +You can reset any user's password, including administrators (see :doc:`../configuration_user/reset_admin_password`):: sudo -u www-data php occ user:resetpassword layla - Enter a new password: - Confirm the new password: + Enter a new password: + Confirm the new password: Successfully reset password for layla - + You may also use ``password-from-env`` to reset passwords:: export OC_PASS=newpassword - su -s /bin/sh www-data -c 'php occ user:resetpassword --password-from-env + su -s /bin/sh www-data -c 'php occ user:resetpassword --password-from-env layla' Successfully reset password for layla - + You can delete users:: sudo -u www-data php occ user:delete fred - -View a user's most recent login:: - - sudo -u www-data php occ user:lastseen layla + +View a user's most recent login:: + + sudo -u www-data php occ user:lastseen layla layla's last login: 09.01.2020 18:46 Read user settings:: @@ -1186,7 +1186,7 @@ authentication servers such as LDAP:: | user directories | 2 | +------------------+----+ -.. _group_commands_label: +.. _group_commands_label: Group commands -------------- @@ -1245,7 +1245,7 @@ List configured groups via the ``group:list`` command. The syntax is:: plain. .. _versions_label: - + Versions -------- @@ -1253,12 +1253,12 @@ Versions This command is only available when the "Versions" app (``files_versions``) is enabled. -Use this command to delete file versions for specific users, or for all users +Use this command to delete file versions for specific users, or for all users when none are specified:: - + versions versions:cleanup Delete versions - + This example deletes all versions for all users:: sudo -u www-data php occ versions:cleanup @@ -1274,18 +1274,18 @@ You can delete versions for specific users in a space-delimited list:: sudo -u www-data php occ versions:cleanup freda molly Delete versions of freda - Delete versions of molly - -.. _command_line_installation_label: - + Delete versions of molly + +.. _command_line_installation_label: + Command line installation ------------------------- -These commands are available only after you have downloaded and unpacked the +These commands are available only after you have downloaded and unpacked the Nextcloud archive, and taken no further installation steps. -You can install Nextcloud entirely from the command line. After downloading the -tarball and copying Nextcloud into the appropriate directories you can use ``occ`` +You can install Nextcloud entirely from the command line. After downloading the +tarball and copying Nextcloud into the appropriate directories you can use ``occ`` commands in place of running the graphical Installation Wizard. Then choose your ``occ`` options. This lists your available options:: @@ -1300,7 +1300,7 @@ Then choose your ``occ`` options. This lists your available options:: Options: --help (-h) Display this help message --quiet (-q) Do not output any message - --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal + --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug --version (-V) Display this application version --ansi Force ANSI output @@ -1317,15 +1317,15 @@ Then choose your ``occ`` options. This lists your available options:: l10n:createjs Create javascript translation files for a given app maintenance maintenance:install install Nextcloud - + Display your ``maintenance:install`` options:: sudo -u www-data php occ help maintenance:install Nextcloud is not installed - only a limited number of commands are available Usage: - maintenance:install [--database="..."] [--database-name="..."] - [--database-host="..."] [--database-user="..."] [--database-pass[="..."]] - [--database-table-prefix[="..."]] [--admin-user="..."] [--admin-pass="..."] + maintenance:install [--database="..."] [--database-name="..."] + [--database-host="..."] [--database-user="..."] [--database-pass[="..."]] + [--database-table-prefix[="..."]] [--admin-user="..."] [--admin-pass="..."] [--data-dir="..."] Options: @@ -1336,11 +1336,11 @@ Display your ``maintenance:install`` options:: --database-pass Password of the database user --admin-user User name of the admin account (default: "admin") --admin-pass Password of the admin account - --data-dir Path to data directory (default: + --data-dir Path to data directory (default: "/var/www/nextcloud/data") --help (-h) Display this help message --quiet (-q) Do not output any message - --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal + --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug --version (-V) Display this application version --ansi Force ANSI output @@ -1350,9 +1350,9 @@ Display your ``maintenance:install`` options:: This example completes the installation:: cd /var/www/nextcloud/ - sudo -u www-data php occ maintenance:install --database - "mysql" --database-name "nextcloud" --database-user "root" --database-pass - "password" --admin-user "admin" --admin-pass "password" + sudo -u www-data php occ maintenance:install --database + "mysql" --database-name "nextcloud" --database-user "root" --database-pass + "password" --admin-user "admin" --admin-pass "password" Nextcloud is not installed - only a limited number of commands are available Nextcloud was successfully installed @@ -1362,13 +1362,13 @@ Supported databases are:: - mysql (MySQL/MariaDB) - pgsql (PostgreSQL) - oci (Oracle - Nextcloud Enterprise edition only) - -.. _command_line_upgrade_label: - + +.. _command_line_upgrade_label: + Command line upgrade -------------------- -These commands are available only after you have downloaded upgraded packages or +These commands are available only after you have downloaded upgraded packages or tar archives, and before you complete the upgrade. List all options, like this example on CentOS Linux:: @@ -1380,36 +1380,36 @@ List all options, like this example on CentOS Linux:: Options: --help (-h) Display this help message. --quiet (-q) Do not output any message. - --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, + --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug. --version (-V) Display this application version. --ansi Force ANSI output. --no-ansi Disable ANSI output. --no-interaction (-n) Do not ask any interactive question -When you are performing an update or upgrade on your Nextcloud server (see the -Maintenance section of this manual), it is better to use ``occ`` to perform the +When you are performing an update or upgrade on your Nextcloud server (see the +Maintenance section of this manual), it is better to use ``occ`` to perform the database upgrade step, rather than the Web GUI, in order to avoid timeouts. PHP -scripts invoked from the Web interface are limited to 3600 seconds. In larger -environments this may not be enough, leaving the system in an inconsistent -state. After performing all the preliminary steps (see -:doc:`../maintenance/upgrade`) use this command to upgrade your databases, +scripts invoked from the Web interface are limited to 3600 seconds. In larger +environments this may not be enough, leaving the system in an inconsistent +state. After performing all the preliminary steps (see +:doc:`../maintenance/upgrade`) use this command to upgrade your databases, like this example on CentOS Linux. Note how it details the steps:: sudo -u www-data php occ upgrade - Nextcloud or one of the apps require upgrade - only a limited number of - commands are available - Turned on maintenance mode - Checked database schema update + Nextcloud or one of the apps require upgrade - only a limited number of + commands are available + Turned on maintenance mode + Checked database schema update Checked database schema update for apps - Updated database - Updating ... - Updated to 0.6.1 + Updated database + Updating ... + Updated to 0.6.1 Updating ... - Updated to 2.1.0 + Updated to 2.1.0 Update successful Turned off maintenance mode - + Enabling verbosity displays timestamps:: sudo -u www-data php occ upgrade -v @@ -1422,8 +1422,8 @@ Enabling verbosity displays timestamps:: 2015-06-23T09:06:15+0000 Update successful 2015-06-23T09:06:15+0000 Turned off maintenance mode -If there is an error it throws an exception, and the error is detailed in your -Nextcloud logfile, so you can use the log output to figure out what went wrong, +If there is an error it throws an exception, and the error is detailed in your +Nextcloud logfile, so you can use the log output to figure out what went wrong, or to use in a bug report:: Turned on maintenance mode