From 3b2be022b35b5594e7b2e17f8657632026e9d41e Mon Sep 17 00:00:00 2001 From: Rello Date: Sat, 19 Sep 2026 20:37:29 +0200 Subject: [PATCH 1/4] docs: consolidate desktop advanced configuration Unify desktop configuration reference tables and verify parameters against the desktop source. Keep nextcloudcmd separate and preserve existing documentation URLs with redirects. Assisted-by: Codex:gpt-6-astra --- .../_desktop_account_setup_options.rst | 31 + _shared_assets/static/custom.css | 12 + user_manual/conf.py | 3 + .../desktop/advanced_configuration.rst | 629 ++++++++++++++++++ user_manual/desktop/commandline.rst | 330 +++++---- user_manual/desktop/configfile.rst | 255 ------- user_manual/desktop/conflicts.rst | 6 +- user_manual/desktop/envvars.rst | 25 - user_manual/desktop/index.rst | 4 +- user_manual/desktop/options.rst | 38 -- user_manual/desktop/uninstallation.rst | 10 +- 11 files changed, 887 insertions(+), 456 deletions(-) create mode 100644 _shared_assets/_desktop_account_setup_options.rst create mode 100644 user_manual/desktop/advanced_configuration.rst delete mode 100644 user_manual/desktop/configfile.rst delete mode 100644 user_manual/desktop/envvars.rst delete mode 100644 user_manual/desktop/options.rst diff --git a/_shared_assets/_desktop_account_setup_options.rst b/_shared_assets/_desktop_account_setup_options.rst new file mode 100644 index 00000000000..10dd8e32177 --- /dev/null +++ b/_shared_assets/_desktop_account_setup_options.rst @@ -0,0 +1,31 @@ +.. Shared parameter table for desktop account provisioning commands. + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``--userid `` + - Required + - User ID for the account to create. Use together with ``--serverurl``. + * - ``--serverurl `` + - Required + - Base URL of the Nextcloud server, for example ``https://cloud.example.com``. + * - ``--apppassword `` + - Not set + - App password for the account. If omitted, the account is saved and you must log in from the desktop app later. + * - ``--localdirpath `` + - Suggested folder + - Local sync folder. If omitted, use the folder suggested by the setup wizard. An existing folder must be empty. + Ignored when macOS File Provider mode is enabled. + * - ``--remotedirpath `` + - ``/`` + - Remote folder for the new classic sync connection. Applies when a local sync folder is created. + * - ``--isvfsenabled <0|1>`` + - ``0`` + - Use ``1`` to request virtual files for the new classic sync folder, where supported, or ``0`` to download + files. This does not enable macOS File Provider mode. + diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css index e5f57c06c27..a2bb5f522c1 100644 --- a/_shared_assets/static/custom.css +++ b/_shared_assets/static/custom.css @@ -230,6 +230,18 @@ table.docutils { width: 100%; } +.rst-content table.configuration-table { + width: 100%; + table-layout: fixed; +} + +.rst-content table.configuration-table th, +.rst-content table.configuration-table td, +.rst-content table.configuration-table code { + white-space: normal; + overflow-wrap: anywhere; +} + /* Version picker lists — 2-column grid, emoji as absolute ::before bullet */ .rst-versions .rst-other-versions { padding-left: 26px; diff --git a/user_manual/conf.py b/user_manual/conf.py index 396976156d2..3839e60a3b6 100644 --- a/user_manual/conf.py +++ b/user_manual/conf.py @@ -174,6 +174,9 @@ # https://documatt.gitlab.io/sphinx-reredirects/usage.html redirects = { + 'desktop/options': 'advanced_configuration.html', + 'desktop/configfile': 'advanced_configuration.html', + 'desktop/envvars': 'advanced_configuration.html', # Renamed 2026-06 'desktop/macosvfs': 'desktop/macosfileprovider', } diff --git a/user_manual/desktop/advanced_configuration.rst b/user_manual/desktop/advanced_configuration.rst new file mode 100644 index 00000000000..9429d9a74e6 --- /dev/null +++ b/user_manual/desktop/advanced_configuration.rst @@ -0,0 +1,629 @@ +====================== +Advanced configuration +====================== + +You can configure the desktop app through command-line options, ``nextcloud.cfg``, and environment variables. +Use the app's **Settings** window for options available there; this page describes advanced settings and overrides. +For the separate tool that performs a single synchronization run, see :doc:`commandline`. + +.. contents:: On this page + :local: + :depth: 2 + +Defaults below refer to the standard Nextcloud client. Branded clients, server capabilities, and operating system +policies can change some defaults. Sync-engine settings apply to classic sync, including Windows virtual files. +The macOS File Provider extension handles its own file transfers; these settings do not configure its transfer engine. +See :doc:`macosfileprovider`. + +.. _desktop-command-line-options: + +Command-line options +-------------------- + +Start the desktop app with ``nextcloud [options]``. Use ``nextcloud --help`` to see the options in your installed +version. +Options with a value accept both ``--option value`` and ``--option=value``. + +Quit the running client before applying startup options or environment variables. Starting another instance can forward +commands to the existing process instead of starting a new process with the requested environment. + +General options +^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``--help``, ``-h`` + - Not requested + - Show the available command-line options and exit. + * - ``--version``, ``-v`` + - Not requested + - Show version information and exit. + * - ``--quit``, ``-q`` + - Not requested + - Quit the running desktop client. + * - ``--confdir `` + - Standard location + - Use a different configuration directory. See :ref:`desktop-configuration-file` for the standard locations. + * - ``--background`` + - Not set + - Start without opening the main dialog. + * - ``--set-language `` + - From ``language`` + - Save the interface language and exit. For example, use ``de`` for German. An empty value restores the operating + system language. Start the client again to apply it. + * - ``--overrideserverurl `` + - Not set + - Save ``overrideServerUrl`` for the next account setup and exit. Start the client again to open the setup + wizard. + * - ``--overridelocaldir `` + - Not set + - Save ``overrideLocalDir`` for the next account setup and exit. + * - ``--forcelegacyconfigimport`` + - Not set + - Force import of an available legacy client configuration. Only available in builds that support account + migration. + * - ``--reverse`` + - Normal direction + - Reverse the interface layout direction for this run. + +Logging options +^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``--logwindow``, ``-l`` + - Not set + - Open the log output window. + * - ``--logfile `` + - Not set + - Write logs to this file. Use ``-`` to write to standard output. Takes precedence over ``--logdir``. + * - ``--logdir `` + - From ``logDir`` + - Write rotating log files to this directory. + * - ``--logexpire `` + - From ``logExpire`` + - Set retention for rotating logs. A positive value overrides ``logExpire``; zero or a negative value uses the + configuration setting. + * - ``--logflush`` + - From ``logFlush`` + - Flush the log after each write so that recent messages are available immediately. + * - ``--logdebug`` + - From ``logDebug`` + - Enable debug messages in Nextcloud logging categories. This does not enable all Qt debug categories. + * - ``--debug`` + - Not set + - Also enables debug logging. Prefer ``--logdebug`` when collecting diagnostic logs. + +For example, collect debug output in a file on Linux: + +.. code-block:: bash + + nextcloud --logdebug --logflush --logfile "$HOME/nextcloud-debug.log" + +For persistent logging settings, see :ref:`desktop-general-settings`. + +Account setup options +^^^^^^^^^^^^^^^^^^^^^ + +These options create and save an account, then exit. Start the desktop app again to use the account. + +.. include:: ../../_shared_assets/_desktop_account_setup_options.rst + +For example, create an account and log in from the desktop app afterward: + +.. code-block:: bash + + nextcloud --userid carla --serverurl https://cloud.example.com --localdirpath "$HOME/Nextcloud" + +.. _desktop-configuration-file: + +Configuration file +------------------ + +The client stores its settings in ``nextcloud.cfg`` using the INI format. Quit the client and back up this file before +editing it, then start the client again. Changes made in the app's **Settings** window can overwrite the corresponding +values in the file. + +The standard locations are: + +* Linux: ``$HOME/.config/Nextcloud/nextcloud.cfg``. If ``XDG_CONFIG_HOME`` is set, use + ``$XDG_CONFIG_HOME/Nextcloud/nextcloud.cfg``. +* Windows: ``%APPDATA%\Nextcloud\nextcloud.cfg``. +* macOS, client 33.0.0 and later: + ``$HOME/Library/Containers/com.nextcloud.desktopclient/Data/Library/Preferences/Nextcloud/nextcloud.cfg``. +* Older macOS clients: ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg``. + +``--confdir`` overrides the configuration directory. Branded clients can use a different directory and filename. +In Citrix and other environments with roaming profiles, persist the user's configuration between sessions to retain +account setup. + +The tables identify the INI section for each setting. For example: + +.. code-block:: ini + + [Nextcloud] + remotePollInterval=30000 + + [General] + logDebug=true + logExpire=48 + +Account identities, credentials, sync-folder state, window geometry, caches, migration markers, and updater state are +managed by the client. Use the setup wizard and **Settings** window to change those values. + +Precedence depends on the setting. The environment overrides listed below apply only to their corresponding settings. +For ``skipUpdateCheck`` and ``autoUpdateCheck``, a value in ``[General]`` takes precedence over ``[Nextcloud]``. +On Windows, administrator policies can override those update settings and the folder-size and external-storage settings. + +.. _nextcloud-section: + +``[Nextcloud]`` section +^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``remotePollInterval`` + - ``30000`` ms + - Interval for polling the server for changes. Values below ``5000`` ms fall back to ``30000`` ms. Server push + can reduce the need for polling. + * - ``forceSyncInterval`` + - ``7200000`` ms + - Schedule a sync after this much time has passed since the last sync (2 hours). Values below + ``remotePollInterval`` are raised to that interval. + * - ``fullLocalDiscoveryInterval`` + - ``3600000`` ms + - After this interval (1 hour), the next eligible sync scans the local filesystem fully. Use ``-1`` to disable + periodic full scans. Overridden by ``OWNCLOUD_FULL_LOCAL_DISCOVERY_INTERVAL``. + * - ``notificationRefreshInterval`` + - ``60000`` ms + - Interval for polling server notifications. Values below ``60000`` ms are raised to ``60000`` ms. + * - ``skipUpdateCheck`` + - ``false`` + - Disable update checks and hide the updater interface. + * - ``autoUpdateCheck`` + - ``true`` + - Enable automatic update checks, provided ``skipUpdateCheck`` is false. + * - ``updateCheckInterval`` + - ``36000000`` ms + - Automatic update-check interval (10 hours). Values below ``300000`` ms (5 minutes) are raised to that minimum. + +.. _general-section: +.. _desktop-general-settings: + +``[General]`` section +^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: Synchronization and transfers + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``chunkSize`` + - ``104857600`` bytes + - Initial upload chunk size (100 MiB). The client can adjust it during upload. Server capabilities can replace + it; ``OWNCLOUD_CHUNK_SIZE`` overrides the resulting value. + * - ``minChunkSize`` + - ``5242880`` bytes + - Minimum configured upload chunk size (5 MiB). The sync engine initially bounds it between 5 MB and 5 GB. + Overridden by ``OWNCLOUD_MIN_CHUNK_SIZE``. + * - ``maxChunkSize`` + - ``104857600`` bytes + - Maximum configured upload chunk size (100 MiB). A server-provided maximum takes precedence. + ``OWNCLOUD_MAX_CHUNK_SIZE`` overrides the resulting value. + * - ``timeout`` + - ``300`` seconds + - Default network inactivity timeout. Activity can reset the timer and individual requests can use different + timeouts. A nonzero ``OWNCLOUD_TIMEOUT`` overrides it. + * - ``promptDeleteAllFiles`` + - ``false`` + - Ask for confirmation when all files are detected as deleted or when the number of deleted files exceeds + ``deleteFilesThreshold``. Applies to desktop classic sync; ``nextcloudcmd`` does not show this prompt. + * - ``deleteFilesThreshold`` + - ``100`` files + - Deletion count above which ``promptDeleteAllFiles`` asks for confirmation. Has no effect unless that setting is + enabled. + * - ``moveToTrash`` + - ``false`` + - Move files deleted on the server to the local trash instead of deleting them permanently, where the local + filesystem supports it. + * - ``newBigFolderSizeLimit`` + - ``500`` MB + - Size above which a new remote folder requires confirmation before downloading. Used when + ``useNewBigFolderSizeLimit`` is true; a negative value disables the limit. Does not apply to virtual-file + folders. + * - ``useNewBigFolderSizeLimit`` + - ``true`` + - Enable the folder-size confirmation limit. + * - ``confirmExternalStorage`` + - ``true`` + - Ask before synchronizing newly discovered external storage folders. + * - ``notifyExistingFoldersOverLimit`` + - ``false`` + - Notify when an existing synchronized folder grows beyond the active folder-size limit. Requires that limit to + be enabled and virtual files to be disabled. + * - ``stopSyncingExistingFoldersOverLimit`` + - From ``notifyExistingFoldersOverLimit`` + - Also stop synchronizing such folders until you choose to keep syncing them. Requires + ``notifyExistingFoldersOverLimit`` and the folder-size limit to be enabled. + +For classic desktop sync, the client applies chunk settings from the configuration file, then server capabilities, +then environment overrides. It adjusts the minimum and maximum afterward to include the initial chunk size. +The ``targetChunkUploadDuration`` configuration key is not used by the sync engine; use +``OWNCLOUD_TARGET_CHUNK_UPLOAD_DURATION`` instead. ``forceLoginV2`` is no longer read by the client. + +.. list-table:: Interface and notifications + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``showExperimentalOptions`` + - ``false`` + - Show experimental options in the interface. This does not itself enable experimental features. + * - ``showMainDialogAsNormalWindow`` + - ``false`` + - Show the main dialog as a normal window even when a tray icon is available. + * - ``monoIcons`` + - Platform dependent + - Use monochrome tray icons. Defaults to ``true`` for the standard Nextcloud client on macOS and ``false`` + elsewhere. + * - ``optionalServerNotifications`` + - ``true`` + - Show optional server notifications. Individual notification settings below also apply. + * - ``showChatNotifications`` + - ``true`` + - Show chat notifications when optional server notifications are enabled. + * - ``showCallNotifications`` + - ``true`` + - Show call notifications when optional server notifications are enabled. + * - ``showQuotaWarningNotifications`` + - ``true`` + - Show quota warnings when optional server notifications are enabled. + * - ``showInExplorerNavigationPane`` + - Platform dependent + - Show sync folders in the Windows Explorer navigation pane. Defaults to ``true`` on Windows 10 and later, and + ``false`` on other platforms. + * - ``launchOnSystemStartup`` + - ``true`` + - Store the startup preference. Use **Settings** to change it so that the operating system startup registration + is updated too. + * - ``language`` + - Empty + - Interface language code, for example ``de``. An empty value uses the operating system language. + * - ``updateChannel`` + - Build/server dependent + - Select a supported update channel. Invalid values are ignored. Branded clients and server subscription settings + can restrict the selection. See :doc:`updatechannel`. + * - ``showConfigBackupWarning`` + - ``false`` + - Show a notification listing configuration backups created during startup. + +.. list-table:: Logging + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``logToTemporaryLogDir`` + - ``false`` + - Use a temporary log directory when logging has not already been directed to a file or standard output. Also + enables debug logging and sets retention to 4 hours. + * - ``logDir`` + - ``/logs`` + - Directory for rotating log files. Overridden by ``--logdir``; ``--logfile`` selects a file or standard output + instead. + * - ``logDebug`` + - ``false`` + - Enable Nextcloud debug logging. ``--logdebug`` also enables it. + * - ``logExpire`` + - ``24`` hours + - Retention for rotating logs. A value of ``0`` disables age-based removal. A positive ``--logexpire`` value + overrides this setting. + * - ``logFlush`` + - ``false`` + - Flush the log after every write. ``--logflush`` also enables it. + +Development and debug builds can enable debug logging and immediate flushing regardless of these defaults. + +.. list-table:: Account setup defaults + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``overrideServerUrl`` + - Empty + - Force the server URL in the next account setup and start login automatically. Cleared after successful wizard + setup. Can also be set with ``--overrideserverurl``. + * - ``overrideLocalDir`` + - Empty + - Suggested local directory for account setup. Cleared after successful wizard setup. Can also be set with + ``--overridelocaldir``. + * - ``isVfsEnabled`` + - ``false`` + - Virtual-file preference used with ``overrideServerUrl`` during setup. Does not convert existing sync folders or + enable macOS File Provider mode. + +Per-account network settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the account's network settings in the app where possible. Values below belong to the existing account group inside +``[Accounts]``. In the INI file they appear with the account ID prefix, for example ``0\networkProxyType=0`` for account +``0``. Use the account ID already present in your file. Proxy passwords belong in the system keychain. + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``networkProxyType`` + - ``0`` if absent + - ``0``: system proxy; ``1``: SOCKS5 proxy; ``2``: no proxy; ``3``: HTTP proxy. Account setup or migration can + store a different value. + * - ``networkProxyHostName`` + - Empty + - Proxy hostname. + * - ``networkProxyPort`` + - ``0`` + - Proxy port. Set the actual port when configuring a manual proxy. + * - ``networkProxyNeedsAuth`` + - ``false`` + - Whether the proxy requires authentication. + * - ``networkProxyUser`` + - Empty + - Proxy username. + * - ``networkUploadLimitSetting`` + - ``0`` + - Upload limit mode: ``0`` for unlimited, ``1`` for a manual limit. Negative values are reserved for legacy + migration. + * - ``networkDownloadLimitSetting`` + - ``0`` + - Download limit mode: ``0`` for unlimited, ``1`` for a manual limit. Negative values are reserved for legacy + migration. + * - ``networkUploadLimit`` + - ``0`` KB/s + - Manual upload limit, used when ``networkUploadLimitSetting`` is ``1``. + * - ``networkDownloadLimit`` + - ``0`` KB/s + - Manual download limit, used when ``networkDownloadLimitSetting`` is ``1``. + +.. _legacy-proxy-section: + +Legacy proxy settings +^^^^^^^^^^^^^^^^^^^^^ + +The top-level ``[Proxy]`` section is retained for migration from older clients. Current desktop accounts use the +per-account settings above. Legacy proxy settings can be removed automatically after migration. + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``type`` + - ``0`` + - Legacy proxy type: ``0`` for system proxy, ``1`` for SOCKS5, ``2`` for no proxy, or ``3`` for HTTP proxy. + * - ``host`` + - Empty + - Legacy proxy hostname. + * - ``port`` + - ``0`` + - Legacy proxy port. + * - ``needsAuth`` + - ``false`` + - Whether the legacy proxy requires authentication. + * - ``user`` + - Empty + - Legacy proxy username. + +.. _desktop-environment-variables: + +Environment variables +--------------------- + +Set environment variables before starting the client. A variable set in a terminal applies to processes launched from +that terminal; an already running client or a client launched from the desktop does not automatically inherit it. +For example, temporarily change the network inactivity timeout on Linux: + +.. code-block:: bash + + OWNCLOUD_TIMEOUT=600 nextcloud + +The historic ``OWNCLOUD_`` prefix is still used by the Nextcloud client. Follow the value format in each description: +some switches require ``0`` or ``1``, while others react to any nonempty value, including ``0``. +``Default`` describes behavior when the variable is unset. + +Transfer settings +^^^^^^^^^^^^^^^^^ + +The chunk-size and parallel-job overrides apply after configuration values and server capabilities in desktop classic +sync. ``nextcloudcmd`` also reads these variables, but starts with its sync-engine defaults instead of the desktop app's +chunk configuration. + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``OWNCLOUD_CHUNK_SIZE`` + - Effective chunk size + - Initial chunk size in bytes. Desktop sync starts from ``chunkSize`` or the server-provided size. + ``nextcloudcmd`` defaults to ``104857600`` bytes (100 MiB). + * - ``OWNCLOUD_MIN_CHUNK_SIZE`` + - Effective minimum + - Minimum chunk size in bytes. Desktop sync starts from ``minChunkSize``; ``nextcloudcmd`` defaults to + ``5000000`` bytes (5 MB). + * - ``OWNCLOUD_MAX_CHUNK_SIZE`` + - Effective maximum + - Maximum chunk size in bytes. Desktop sync starts from ``maxChunkSize`` or the server-provided maximum; + ``nextcloudcmd`` defaults to ``5000000000`` bytes (5 GB). + * - ``OWNCLOUD_TARGET_CHUNK_UPLOAD_DURATION`` + - ``60000`` ms + - Target duration for dynamic chunk sizing (1 minute). Use ``0`` to disable dynamic sizing. The similarly named + configuration-file key has no effect. + * - ``OWNCLOUD_MAX_PARALLEL`` + - Server/protocol dependent + - Positive maximum number of parallel sync jobs. Desktop sync uses the server-provided value when available; + otherwise it uses ``20`` for HTTP/2 or ``6`` for HTTP/1. ``nextcloudcmd`` defaults to ``6``. This is not the + number of simultaneous file transfers. + * - ``OWNCLOUD_TIMEOUT`` + - ``timeout`` or 300 seconds + - Network inactivity timeout. A nonzero integer overrides ``timeout`` in the desktop app. ``nextcloudcmd`` + defaults to 300 seconds. Zero or an invalid value uses the normal default. + * - ``OWNCLOUD_HTTP2_ENABLED`` + - Disabled + - Set to ``1`` to allow HTTP/2 for HTTPS requests. Other values disable it. Actual use still depends on the + server and network connection. + * - ``OWNCLOUD_CHUNKING_NG`` + - Server capability + - Set to ``0`` to disable the newer chunked-upload protocol or ``1`` to force it. Other values use the server + capability. Only force it when the server supports it. + * - ``NEXTCLOUD_BULK_UPLOAD`` + - Server capability + - Set to ``0`` to disable bulk uploads or ``1`` to force them. Other values use the server capability. Only force + them when the server supports them. + * - ``OWNCLOUD_PARALLEL_CHUNK`` + - Server dependent + - For the legacy chunked-upload path only: ``0`` or ``false`` disables parallel chunks. Other nonempty values + enable them unless the server disables them. + * - ``OWNCLOUD_LAZYOPS`` + - Disabled + - A nonzero integer adds the ``OC-LazyOps: true`` header to upload requests. Its effect depends on server + support. + +Keep chunk sizes positive. The client adjusts the minimum and maximum to include the initial chunk size. +The environment parser accepts unsigned 32-bit byte values for the three chunk-size overrides, so do not use values +above ``4294967295`` bytes for those variables. + +Synchronization and disk space +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``OWNCLOUD_FULL_LOCAL_DISCOVERY_INTERVAL`` + - ``fullLocalDiscoveryInterval`` + - Desktop classic sync only. Override the full local scan interval in milliseconds. Use ``-1`` to disable + periodic full scans. + * - ``OWNCLOUD_CRITICAL_FREE_SPACE_BYTES`` + - ``512000000`` bytes + - Abort the folder sync when remaining local space is below this threshold (512 MB). The value is bounded between + zero and ``OWNCLOUD_FREE_SPACE_BYTES``. + * - ``OWNCLOUD_FREE_SPACE_BYTES`` + - ``1000000000`` bytes + - Skip or abort downloads that would leave less than this amount of local free space (1 GB). Other + synchronization can continue. + * - ``OWNCLOUD_BLACKLIST_TIME_MIN`` + - ``25`` seconds + - Minimum retry delay for files that failed to synchronize. Values below ``25`` are raised to ``25``. + * - ``OWNCLOUD_BLACKLIST_TIME_MAX`` + - ``86400`` seconds + - Maximum retry delay for files that failed to synchronize (1 day). Only positive values override the default. + * - ``OWNCLOUD_UPLOAD_CONFLICT_FILES`` + - Server capability + - Set to ``1`` to upload conflict copies or ``0`` to prevent their upload. A nonempty value overrides the server + setting. See :doc:`conflicts`. + +.. _low-disk-space: + +Downloads skipped because of the free-space threshold are retried in later sync runs. The critical threshold stops the +whole folder sync. These limits are independent of your server storage quota. + +Checksums +^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``OWNCLOUD_CONTENT_CHECKSUM_TYPE`` + - Server preference, then ``SHA1`` + - Override the preferred upload checksum algorithm. Choose an algorithm supported by both client and server. + * - ``OWNCLOUD_DISABLE_CHECKSUM_UPLOAD`` + - Unset + - Any nonempty value disables sending upload checksums. Unset it to restore normal checksum uploads. + * - ``OWNCLOUD_DISABLE_CHECKSUM_COMPUTATIONS`` + - Unset + - Any nonempty value disables synchronous checksum calculations. Upload and download paths using asynchronous + calculations still run. + +Use checksum overrides only when diagnosing a specific compatibility problem; disabling checksums reduces integrity +checks used during synchronization. + +Troubleshooting +^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``OWNCLOUD_SQLITE_JOURNAL_MODE`` + - ``WAL`` or ``DELETE`` + - Override the sync journal database mode. Normally ``WAL``; ``DELETE`` on Windows FAT filesystems and macOS sync + paths under ``/Volumes/``. Change only when diagnosing a database compatibility problem. + * - ``OWNCLOUD_SQLITE_LOCKING_MODE`` + - ``EXCLUSIVE`` + - Override the SQLite locking mode for the sync journal database. + * - ``OWNCLOUD_SQLITE_TEMP_STORE`` + - SQLite default + - Override the SQLite ``temp_store`` setting for the sync journal database. + * - ``OWNCLOUD_CORE_DUMP`` + - Unset + - On Unix systems, any nonempty value requests an unlimited core-dump size limit for the desktop app. Operating + system restrictions still apply. + * - ``QT_LOGGING_RULES`` + - Qt logging defaults + - Set logging-category filters, for example ``nextcloud.*.debug=true``. This Qt variable also allows selecting + individual categories. + +For ``nextcloudcmd`` credentials, see :ref:`desktop-command-line-credentials`. Its ``NC_USER`` and ``NC_PASSWORD`` +variables do not configure accounts in the desktop app. diff --git a/user_manual/desktop/commandline.rst b/user_manual/desktop/commandline.rst index 7540501df93..43980554ce4 100644 --- a/user_manual/desktop/commandline.rst +++ b/user_manual/desktop/commandline.rst @@ -1,130 +1,204 @@ -============================= -Using the Command-Line Client -============================= - -The Nextcloud Client packages contain a command line client, ``nextcloudcmd``, that can -be used to synchronize Nextcloud files to client machines. - -``nextcloudcmd`` performs a single *sync run* and then exits the synchronization -process. In this manner, ``nextcloudcmd`` processes the differences between -client and server directories and propagates the files to bring both -repositories to the same state. Contrary to the GUI-based client, -``nextcloudcmd`` does not repeat synchronizations on its own. It also does not -monitor for file system changes. - - -Install -~~~~~~~ - -+---------------+---------------------------------------------------------------------------------------------------------+ -| OS | Package | -+===============+=========================================================================================================+ -| Alpine | https://pkgs.alpinelinux.org/package/edge/community/x86_64/nextcloud-client | -+---------------+---------------------------------------------------------------------------------------------------------+ -| Debian | https://packages.debian.org/search?suite=all&arch=any&searchon=names&keywords=nextcloud-desktop-cmd | -+---------------+---------------------------------------------------------------------------------------------------------+ -| Fedora | https://packages.fedoraproject.org/pkgs/nextcloud-client/nextcloud-client/ | -+---------------+---------------------------------------------------------------------------------------------------------+ -| Ubuntu | https://packages.ubuntu.com/search?keywords=nextcloud-desktop-cmd | -+---------------+---------------------------------------------------------------------------------------------------------+ -| Ubuntu (PPA) | https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client | -+---------------+---------------------------------------------------------------------------------------------------------+ -| Windows | https://nextcloud.com/install/#install-clients | -+---------------+---------------------------------------------------------------------------------------------------------+ +.. _using-the-command-line-client: + +=================== +Command-line client +=================== + +``nextcloudcmd`` synchronizes a local directory with a Nextcloud server, then exits. It can perform follow-up syncs +when needed, but it does not continuously monitor local files or poll for server changes like the desktop app. +For options passed to the desktop app's ``nextcloud`` command, see :ref:`desktop-command-line-options`. + +.. _install: + +Installation +------------ + +Install a package that provides ``nextcloudcmd``. Availability depends on your operating system and package: + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 25 75 + + * - Operating system + - Package source + * - Alpine Linux + - `nextcloud-client `__ + * - Debian + - `nextcloud-desktop-cmd + `__ + * - Fedora + - `nextcloud-client `__ + * - Ubuntu + - `nextcloud-desktop-cmd `__ + * - Ubuntu PPA + - `Nextcloud client PPA `__ + * - Windows + - `Nextcloud downloads `__ Usage -~~~~~ - -To invoke ``nextcloudcmd``, you must provide the local and the remote repository -URL using the following command:: - - nextcloudcmd [OPTIONS...] sourcedir nextcloudurl - -where ``sourcedir`` is the local directory and ``nextcloudurl`` is -the server URL. - -Other command line switches supported by ``nextcloudcmd`` include the following: - -``--path`` - Overrides default remote root folder to a specific subfolder on the server(e.g.: /Documents would sync the Documents subfolder on the server) - -``--user``, ``-u`` `` - Use ``user`` as the login name. - -``--password``, ``-p`` `` - Use `password` as the password. - -``-n`` - Use ``netrc(5)`` for login. - -``--non-interactive`` - Do not prompt for questions and tries to read $NC_USER and $NC_PASSWORD from the environment. - -``--silent``, ``--s`` - Inhibits verbose log output. - -``--trust`` - Trust any SSL certificate, including invalid ones. - -``--httpproxy`` `http://[user@pass:]:` - Uses `server` as HTTP proxy. - -``--exclude`` `` - Exclude list file - -``--unsyncedfolders`` `` - File containing the list of unsynced folders (selective sync) - -``--max-sync-retries`` `` - Retries maximum n times (defaults to 3) - -``-h`` - Sync hidden files,do not ignore them - - -Credential Handling -~~~~~~~~~~~~~~~~~~~ - -``nextcloudcmd`` requires the user to specify the username and password using the standard URL pattern, e.g., - -:: - - $ nextcloudcmd /home/user/my_sync_folder https://carla:secret@server/nextcloud - -To synchronize the Nextcloud directory ``Music`` to the local directory -``media/music``, through a proxy listening on port ``8080``, and on a gateway -machine using IP address ``192.168.178.1``, the command line would be:: - - $ nextcloudcmd --httpproxy http://192.168.178.1:8080 --path /Music \ - $HOME/media/music \ - https://server/nextcloud - -``nextcloudcmd`` will prompt for the user name and password, unless they have -been specified on the command line or ``-n`` has been passed. - -Exclude List -~~~~~~~~~~~~ - -``nextcloudcmd`` requires access to an exclude list file. It must either be -installed along with ``nextcloudcmd`` and thus be available in a system location, -be placed next to the binary as ``sync-exclude.lst`` or be explicitly specified -with the ``--exclude`` switch. - -The required file content is one exclude item per line where wildcards are allowed, e.g.: -:: - - ~*.tmp - ._* - ]Thumbs.db - ]photothumb.db - System Volume Information - -Example -~~~~~~~~~~~~ - -- Synchronize a local directory to the specified directory of the nextcloud server - -:: - - $ nextcloudcmd --path / /home/user/ \ - https://:@ +----- + +Use an existing local directory and the base URL of the Nextcloud server: + +.. code-block:: console + + nextcloudcmd [options] local_directory server_url + +.. _example: + +For example, synchronize the remote ``Music`` folder into an existing local folder: + +.. code-block:: bash + + nextcloudcmd --user carla --path /Music "$HOME/media/music" https://cloud.example.com + +The client prompts for the password. You can use an app password from your Nextcloud account's security settings. +Do not append a WebDAV endpoint to the server URL; use ``--path`` for a remote subfolder. + +Run ``nextcloudcmd`` without arguments to display its help, or ``nextcloudcmd --version`` to display its version. +Options with values accept both ``--option value`` and ``--option=value``. + +Options +------- + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``--path `` + - Server root + - Synchronize a remote subfolder, for example ``/Documents``. + * - ``--user ``, ``-u `` + - See credentials below + - Login name. Overrides the username in the server URL. + * - ``--password ``, ``-p `` + - See credentials below + - Password or app password. Overrides the password in the server URL. Command-line passwords may be visible in + process listings and shell history. + * - ``-n`` + - Not set + - Read credentials from a matching host or default entry in ``.netrc``. These replace credentials supplied in the URL or + with ``--user`` and ``--password``. + * - ``--non-interactive`` + - Not set + - Do not prompt for credentials. Read missing credentials from ``NC_USER`` and ``NC_PASSWORD``. + * - ``--silent``, ``-s`` + - Not set + - Suppress Qt log messages. Does not suppress every console message. + * - ``--trust`` + - Not set + - Accept untrusted TLS certificates. Use only for a controlled diagnostic run; normally fix the certificate trust + configuration. + * - ``--httpproxy `` + - No explicit proxy + - Set an HTTP proxy using ``http://hostname:port``. This option does not parse proxy credentials in the URL. + * - ``--exclude `` + - System exclude list + - Add an exclude list. The file must exist. Pattern anchoring depends on its filename; see + :ref:`desktop-command-line-excludes`. + * - ``--exclude-anchored `` + - Not set + - Add an exclude list with patterns anchored at the sync root, regardless of the filename. + * - ``--unsyncedfolders `` + - Not set + - Read remote folders to exclude from synchronization, one relative path per line. Empty lines and lines starting + with ``#`` are ignored. + * - ``--max-sync-retries `` + - ``3`` + - Maximum number of follow-up runs when the sync engine requests another sync. This is not a general retry count + for every failed request. + * - ``--uplimit `` + - ``0`` KB/s + - Upload speed limit in KB/s (1000 bytes per second). Zero means unlimited. + * - ``--downlimit `` + - ``0`` KB/s + - Download speed limit in KB/s (1000 bytes per second). Zero means unlimited. + * - ``-h`` + - Hidden files included + - Include hidden files. This is already the default; ``-h`` does not display help. + * - ``--logdebug`` + - Not set + - Enable Nextcloud debug logging and send log output to standard output. + * - ``--confdir `` + - Standard location + - Use a different configuration directory. Does not make the one-run sync inherit all desktop sync settings. + * - ``--version``, ``-v`` + - Not requested + - Display version information and exit. Run this option without the directory and server arguments. + +.. _credential-handling: +.. _desktop-command-line-credentials: + +Credential handling +------------------- + +Credentials are read in this order: + +1. Username and password in the server URL, if supplied. +2. ``--user`` and ``--password``, which replace the corresponding URL values. +3. A matching host or default ``.netrc`` entry when ``-n`` is used, which replaces both values. +4. Prompts for any missing values, or the environment variables below when ``--non-interactive`` is used. + +Prefer a password prompt or a protected ``.netrc`` file over putting passwords in a command or URL. + +.. list-table:: + :header-rows: 1 + :class: configuration-table + :widths: 32 18 50 + + * - Parameter + - Default + - Description + * - ``NC_USER`` + - Unset + - Username fallback for a one-run sync with ``--non-interactive``. Only used if no username was supplied by the + preceding methods. + * - ``NC_PASSWORD`` + - Unset + - Password fallback for a one-run sync with ``--non-interactive``. Only used if no password was supplied by the + preceding methods. + +These variables do not supply credentials for the account setup mode below. +For transfer overrides shared with the desktop sync engine, see :ref:`desktop-environment-variables`. +``nextcloudcmd`` uses an initial chunk size of 100 MiB, a minimum of 5 MB, a maximum of 5 GB, and 6 parallel jobs unless +overridden by those variables. It does not read the desktop app's chunk-size settings from ``nextcloud.cfg``. + +.. _exclude-list: +.. _desktop-command-line-excludes: + +Exclude lists +------------- + +The client loads the system exclude list when available. You can add your own list with ``--exclude`` or +``--exclude-anchored``. A missing explicitly supplied file is an error. + +With ``--exclude``, a file named ``sync-exclude.lst`` uses the sync root for pattern matching. Other filenames can use +the exclude file's directory as the base. Use ``--exclude-anchored`` when the filename and location should not affect +matching. + +Write one pattern per line. Wildcards are supported, for example: + +.. code-block:: text + + *.tmp + ._* + Thumbs.db + +Account setup +------------- + +``nextcloudcmd`` can also save an account for use by the desktop app. The presence of ``--userid`` selects this mode; +omit the positional local directory and server URL used for a one-run sync. The command exits after setup completes. + +.. include:: ../../_shared_assets/_desktop_account_setup_options.rst + +For example, save an account and log in from the desktop app afterward: + +.. code-block:: bash + + nextcloudcmd --userid carla --serverurl https://cloud.example.com --localdirpath "$HOME/Nextcloud" diff --git a/user_manual/desktop/configfile.rst b/user_manual/desktop/configfile.rst deleted file mode 100644 index 0cd7ace5193..00000000000 --- a/user_manual/desktop/configfile.rst +++ /dev/null @@ -1,255 +0,0 @@ -================== -Configuration File -================== - -The Nextcloud Client reads a configuration file. You can locate this configuration file as follows: - -On Linux distributions: - ``$HOME/.config/Nextcloud/nextcloud.cfg`` - -On Microsoft Windows systems: - ``%APPDATA%\Nextcloud\nextcloud.cfg`` - -On macOS systems: - Starting with version 33.0.0: ``$HOME/Library/Containers/com.nextcloud.desktopclient/Data/Library/Preferences/Nextcloud/nextcloud.cfg`` - - On older versions: ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg`` - -.. note:: - In a Citrix workspace, the user's Roaming profile need to be persisted between sessions. - The failure on doing so will result in users having to set up their account again in every new session. - -The configuration file contains settings using the Microsoft Windows .ini file -format. You can overwrite changes using the Nextcloud configuration dialog. - -.. note:: Use caution when making changes to the Nextcloud Client configuration - file. Incorrect settings can produce unintended results. - -The configuration file also contains account details, sync folder state, window -geometry, cache values, migration markers, and updater state. Those values are -managed by the client and are not documented here for manual editing. - -Some interesting values that can be set on the configuration file are: - - -``[Nextcloud]`` section -======================= - -.. list-table:: - :header-rows: 1 - :widths: 28 22 50 - - * - Variable - - Default - - Meaning - * - ``remotePollInterval`` - - ``30000`` (30 sec) - - Specifies the poll time for the remote repository in milliseconds. Values below ``5000`` are ignored and the default is used instead. - * - ``forceSyncInterval`` - - ``7200000`` (2 hr) - - The duration of no activity after which a synchronization run shall be triggered automatically. If this value is lower than ``remotePollInterval``, the client uses ``remotePollInterval`` instead. - * - ``fullLocalDiscoveryInterval`` - - ``3600000`` (1 hr) - - The interval after which the next synchronization will perform a full local discovery. Set this to ``-1`` to disable periodic full local discovery. - * - ``notificationRefreshInterval`` - - ``60000`` (1 min) - - Specifies the default interval of checking for new server notifications in milliseconds. Values below ``60000`` are raised to ``60000``. - * - ``skipUpdateCheck`` - - ``false`` - - Disables update checks and hides the updater user interface. - * - ``autoUpdateCheck`` - - ``true`` - - Enables automatic update checks when update checks are not skipped. - * - ``updateCheckInterval`` - - ``36000000`` (10 hr) - - Specifies the interval for automatic update checks in milliseconds. Values below ``300000`` (5 min) are raised to ``300000``. - - -``[General]`` section -===================== - -.. list-table:: - :header-rows: 1 - :widths: 28 22 50 - - * - Variable - - Default - - Meaning - * - ``chunkSize`` - - ``104857600`` (100 MiB) - - Specifies the initial chunk size of uploaded files in bytes. The client can dynamically adjust this size within the maximum and minimum bounds. Server capabilities and environment variables can also affect the effective chunk size. - * - ``minChunkSize`` - - ``5242880`` (5 MiB) - - Specifies the minimum configured chunk size of uploaded files in bytes. Values below the protocol minimum are raised by the sync engine. - * - ``maxChunkSize`` - - ``104857600`` (100 MiB) - - Specifies the maximum configured chunk size of uploaded files in bytes. Server capabilities can override this value at runtime. - * - ``forceLoginV2`` - - ``false`` - - If the client should force the new login flow, even though some circumstances might need the old flow. - * - ``promptDeleteAllFiles`` - - ``false`` - - If a UI prompt should ask for confirmation when all files are detected as deleted or when the number of deleted files exceeds ``deleteFilesThreshold``. This only applies to GUI syncs. - * - ``deleteFilesThreshold`` - - ``100`` - - The number of deleted files above which ``promptDeleteAllFiles`` can trigger a confirmation prompt. - * - ``timeout`` - - ``300`` - - The timeout for network connections in seconds. The ``OWNCLOUD_TIMEOUT`` environment variable takes precedence when set. - * - ``moveToTrash`` - - ``false`` - - If files deleted on the server should be moved to the local trash instead of being deleted permanently. - * - ``showExperimentalOptions`` - - ``false`` - - Whether to show experimental options that are still undergoing testing in the user interface. Turning this on does not enable experimental behavior on its own. It enables user interface options that can be used to opt in to experimental features. - * - ``showMainDialogAsNormalWindow`` - - ``false`` - - Whether the main dialog should be shown as a normal window even if tray icons are available. - * - ``monoIcons`` - - ``false`` - - Whether monochrome tray icons should be used. On macOS, the official Nextcloud client defaults this to ``true`` when monochrome icons are available. - * - ``optionalServerNotifications`` - - ``true`` - - Whether optional server notifications should be shown. - * - ``showChatNotifications`` - - ``true`` - - Whether chat notifications should be shown when optional server notifications are enabled. - * - ``showCallNotifications`` - - ``true`` - - Whether call notifications should be shown when optional server notifications are enabled. - * - ``showQuotaWarningNotifications`` - - ``true`` - - Whether quota warning notifications should be shown when optional server notifications are enabled. - * - ``showInExplorerNavigationPane`` - - Platform dependent - - Whether synced folders should be shown in the Windows Explorer navigation pane. The default is ``true`` on Windows 10 and newer, and ``false`` on other platforms. - * - ``launchOnSystemStartup`` - - ``true`` - - Stores whether the option to launch the client on system startup is enabled. - * - ``language`` - - empty - - Enforces a specific language for the user interface. An empty value uses the operating system language. - * - ``updateChannel`` - - Build dependent - - The selected update channel. Invalid values are ignored. Branded clients may only support their default channel. - * - ``newBigFolderSizeLimit`` - - ``500`` (MB) - - Folder size limit in MB used when asking before synchronizing large folders. - * - ``useNewBigFolderSizeLimit`` - - ``true`` - - Enables the large-folder confirmation limit. - * - ``confirmExternalStorage`` - - ``true`` - - Ask before synchronizing external storages. - * - ``notifyExistingFoldersOverLimit`` - - ``false`` - - Notify when existing synced folders grow beyond ``newBigFolderSizeLimit``. - * - ``stopSyncingExistingFoldersOverLimit`` - - Follows ``notifyExistingFoldersOverLimit`` - - Stop syncing existing folders that exceed the configured folder size limit. - * - ``logToTemporaryLogDir`` - - ``false`` - - Write logs to a temporary log directory. - * - ``logDir`` - - ``/logs`` - - Directory for client log files. - * - ``logDebug`` - - ``false`` - - Enable debug logging. - * - ``logExpire`` - - ``24`` - - Log retention time in hours. - * - ``logFlush`` - - ``false`` - - Flush log output immediately. - -.. note:: - Upload sync options can also be overridden by environment variables. - ``OWNCLOUD_CHUNK_SIZE``, ``OWNCLOUD_MIN_CHUNK_SIZE``, - ``OWNCLOUD_MAX_CHUNK_SIZE``, and ``OWNCLOUD_MAX_PARALLEL`` are applied - after configuration values and server capabilities. The dynamic chunk target - duration can be overridden with ``OWNCLOUD_TARGET_CHUNK_UPLOAD_DURATION``. - The ``targetChunkUploadDuration`` key in ``nextcloud.cfg`` is currently not - applied by GUI sync. - - -Legacy ``[Proxy]`` section -========================== - -The top-level ``[Proxy]`` section is the legacy/global proxy configuration. -Current account proxy settings are stored per account in the ``[Accounts]`` -section. Proxy passwords are stored in the system keychain where possible. - -.. list-table:: - :header-rows: 1 - :widths: 28 22 50 - - * - Variable - - Default - - Meaning - * - ``host`` - - empty - - The address of the proxy server. - * - ``port`` - - ``0`` - - The port where the proxy is listening. The settings dialog may show ``8080`` as the manual-proxy UI default when no port is configured. - * - ``needsAuth`` - - ``false`` - - Whether the proxy requires authentication. - * - ``user`` - - empty - - Proxy username. - * - ``type`` - - ``0`` - - ``0`` for System Proxy. - * - - - - - ``1`` for SOCKS5 Proxy. - * - - - - - ``2`` for No Proxy. - * - - - - - ``3`` for HTTP(S) Proxy. - - -Per-account network settings -============================ - -Current proxy and bandwidth settings are stored below the individual account -group in the ``[Accounts]`` section. - -.. list-table:: - :header-rows: 1 - :widths: 32 18 50 - - * - Variable - - Default - - Meaning - * - ``networkProxyType`` - - ``2`` - - Account proxy type. ``0`` is System Proxy, ``1`` is SOCKS5 Proxy, ``2`` is No Proxy, and ``3`` is HTTP(S) Proxy. - * - ``networkProxyHostName`` - - empty - - Account proxy hostname. - * - ``networkProxyPort`` - - ``0`` - - Account proxy port. - * - ``networkProxyNeedsAuth`` - - ``false`` - - Whether the account proxy requires authentication. - * - ``networkProxyUser`` - - empty - - Account proxy username. - * - ``networkUploadLimitSetting`` - - ``0`` - - Upload bandwidth limit mode. ``0`` means no limit and ``1`` means manual limit. Legacy values ``-1`` and ``-2`` are treated as no limit or migration values. - * - ``networkDownloadLimitSetting`` - - ``0`` - - Download bandwidth limit mode. ``0`` means no limit and ``1`` means manual limit. Legacy values ``-1`` and ``-2`` are treated as no limit or migration values. - * - ``networkUploadLimit`` - - ``0`` - - Manual upload limit in KB/s. - * - ``networkDownloadLimit`` - - ``0`` - - Manual download limit in KB/s. diff --git a/user_manual/desktop/conflicts.rst b/user_manual/desktop/conflicts.rst index d32706a272b..b05cca3cd09 100644 --- a/user_manual/desktop/conflicts.rst +++ b/user_manual/desktop/conflicts.rst @@ -54,6 +54,6 @@ However, in some scenarios it makes a lot of sense to upload these conflicting changes such that local work can become visible even if the conflict won't be resolved immediately. -In the future there might be a server-wide switch for this behavior. For now it -can already be tested by setting the environment variable -``OWNCLOUD_UPLOAD_CONFLICT_FILES=1``. +The server can enable conflict uploads. To override the server setting, use +``OWNCLOUD_UPLOAD_CONFLICT_FILES=1`` to enable uploads or ``OWNCLOUD_UPLOAD_CONFLICT_FILES=0`` to disable them. +See :ref:`desktop-environment-variables` for how to apply environment variables. diff --git a/user_manual/desktop/envvars.rst b/user_manual/desktop/envvars.rst deleted file mode 100644 index c214b73cb9e..00000000000 --- a/user_manual/desktop/envvars.rst +++ /dev/null @@ -1,25 +0,0 @@ -===================== -Environment Variables -===================== - -The behavior of the client can also be controlled using environment variables. The value of the environment variables overrides the values in the configuration file. - -The environment variables are: - -- `OWNCLOUD_CHUNK_SIZE` (default: 5242880; 5 MiB) – Specifies the chunk size of uploaded files in bytes. Increasing this value may help with synchronization problems in certain configurations. -- `OWNCLOUD_TIMEOUT` (default: 300 s) – The timeout for network connections in seconds. -- `OWNCLOUD_CRITICAL_FREE_SPACE_BYTES` (default: 512\*1000\*1000 bytes) - The minimum disk space needed for operation. A fatal error is raised if less free space is available. -- `OWNCLOUD_FREE_SPACE_BYTES` (default: 1000\*1000\*1000 bytes) - Downloads that would reduce the free space below this value are skipped. More information available under the "Low Disk Space" section. -- `OWNCLOUD_MAX_PARALLEL` (default: 6) - Maximum number of parallel jobs. -- `OWNCLOUD_BLACKLIST_TIME_MIN` (default: 25 s) - Minimum timeout for blacklisted files. -- `OWNCLOUD_BLACKLIST_TIME_MAX` (default: 24\*60\*60 s; one day) - Maximum timeout for blacklisted files. -- `OWNCLOUD_HTTP2_ENABLED` (default: false) - If the client should communicate with the server using HTTP/2. (This may not be compatible with all server setups) - -Low Disk Space -^^^^^^^^^^^^^^ - -When disk space is low the Nextcloud Client will be unable to synchronize all files. This section describes its behavior in a low disk space situation as well as the options that influence it. - -1. Synchronization of a folder aborts entirely if the remaining disk space falls below 512 MB. This threshold can be adjusted with the ``OWNCLOUD_CRITICAL_FREE_SPACE_BYTES`` environment variable. - -2. Downloads that would reduce the free disk space below 1 GB will be skipped or aborted. The download will be retried regularly and other synchronization is unaffected. This threshold can be adjusted with the ``OWNCLOUD_FREE_SPACE_BYTES`` environment variable. diff --git a/user_manual/desktop/index.rst b/user_manual/desktop/index.rst index cd80a78defa..c53e952448e 100644 --- a/user_manual/desktop/index.rst +++ b/user_manual/desktop/index.rst @@ -13,9 +13,7 @@ synchronized between your computer and your Nextcloud server. usage macosfileprovider commandline - options - configfile - envvars + advanced_configuration autoupdate updatechannel conflicts diff --git a/user_manual/desktop/options.rst b/user_manual/desktop/options.rst deleted file mode 100644 index cf73d287712..00000000000 --- a/user_manual/desktop/options.rst +++ /dev/null @@ -1,38 +0,0 @@ -==================== -Command-Line Options -==================== - -You have the option of starting your Nextcloud desktop client with the -``nextcloud`` command. The following options are supported: - -``nextcloud -h`` or ``nextcloud --help`` - Displays all command options. - -The other options are: - -``--logwindow`` - Opens a window displaying log output. - -``--logfile`` `` - Write log output to the file specified. To write to stdout, specify `-` - as the filename. - -``--logdir`` `` - Writes each synchronization log output in a new file in the specified - directory. - -``--logexpire`` `` - Removes logs older than the value specified (in hours). This command is - used with ``--logdir``. - -``--logflush`` - Clears (flushes) the log file after each write action. - -``--logdebug`` - Also output debug-level messages in the log (equivalent to setting the env var QT_LOGGING_RULES="qt.*=true;*.debug=true"). - -``--confdir`` `` - Uses the specified configuration directory. - -``--background`` - Launch the application in the background (i.e. without opening the main dialog). diff --git a/user_manual/desktop/uninstallation.rst b/user_manual/desktop/uninstallation.rst index fd28044b860..7b41cf0524d 100644 --- a/user_manual/desktop/uninstallation.rst +++ b/user_manual/desktop/uninstallation.rst @@ -12,7 +12,8 @@ In each operating system: 2. *Uninstall* the desktop client. -3. You may also need to take into consideration that uninstalling the desktop client will not remove the :doc:`user's configuration ` file and synced data. +3. You may also need to take into consideration that uninstalling the desktop client will not remove the + :ref:`user's configuration ` file and synced data. For data removal (sync folders), consider using the server feature `remote wipe `_. This feature is available across all clients. @@ -30,7 +31,7 @@ There are two ways of removing the desktop client: msiexec /uninstall Nextcloud-x.y.z-x64.msi /quiet`` -3. The :doc:`user's configuration ` is located at ``%APPDATA%\Nextcloud\nextcloud.cfg``. +3. The :ref:`user's configuration ` is located at ``%APPDATA%\Nextcloud\nextcloud.cfg``. macOS ^^^^^ @@ -53,7 +54,8 @@ Beyond deleting the desktop client from the *Applications* folder, you may also rm -rf "$HOME/Library/Preferences/Nextcloud" rm -f "$HOME/Library/Preferences/com.nextcloud.desktopclient.plist" -3. From version 33.0.0 the :doc:`user's configuration ` is located at ``$HOME/Library/Containers/com.nextcloud.desktopclient/Data/Library/Preferences/Nextcloud/nextcloud.cfg``. +3. From version 33.0.0 the :ref:`user's configuration ` is located at + ``$HOME/Library/Containers/com.nextcloud.desktopclient/Data/Library/Preferences/Nextcloud/nextcloud.cfg``. On older versions it is located at ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg``. Linux @@ -68,5 +70,5 @@ It depends on how you installed the desktop client: sudo apt remove nextcloud-desktop -3. The :doc:`user's configuration ` is located at *$HOME/.config/Nextcloud/nextcloud.cfg*. +3. The :ref:`user's configuration ` is located at *$HOME/.config/Nextcloud/nextcloud.cfg*. From 67dc685979e7b49ddf0143efcfb8946e1b71c6eb Mon Sep 17 00:00:00 2001 From: Rello Date: Tue, 22 Sep 2026 12:32:28 +0200 Subject: [PATCH 2/4] Update _shared_assets/_desktop_account_setup_options.rst Co-authored-by: Jyrki Gadinger Signed-off-by: Rello --- _shared_assets/_desktop_account_setup_options.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_shared_assets/_desktop_account_setup_options.rst b/_shared_assets/_desktop_account_setup_options.rst index 10dd8e32177..397d86e9f57 100644 --- a/_shared_assets/_desktop_account_setup_options.rst +++ b/_shared_assets/_desktop_account_setup_options.rst @@ -10,7 +10,7 @@ - Description * - ``--userid `` - Required - - User ID for the account to create. Use together with ``--serverurl``. + - User ID for the account to create. * - ``--serverurl `` - Required - Base URL of the Nextcloud server, for example ``https://cloud.example.com``. From 7c2e09d5c9848ac4f1ea50babe64ef3379eeb99f Mon Sep 17 00:00:00 2001 From: Rello Date: Tue, 22 Sep 2026 14:32:08 +0200 Subject: [PATCH 3/4] Update user_manual/desktop/advanced_configuration.rst Co-authored-by: Jyrki Gadinger Signed-off-by: Rello --- user_manual/desktop/advanced_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_manual/desktop/advanced_configuration.rst b/user_manual/desktop/advanced_configuration.rst index 9429d9a74e6..aa86e17d5dc 100644 --- a/user_manual/desktop/advanced_configuration.rst +++ b/user_manual/desktop/advanced_configuration.rst @@ -203,7 +203,7 @@ On Windows, administrator policies can override those update settings and the fo - Enable automatic update checks, provided ``skipUpdateCheck`` is false. * - ``updateCheckInterval`` - ``36000000`` ms - - Automatic update-check interval (10 hours). Values below ``300000`` ms (5 minutes) are raised to that minimum. + - Automatic update-check interval (default: 10 hours). Values below ``300000`` ms (5 minutes) are raised to that minimum. .. _general-section: .. _desktop-general-settings: From 58f0ac4d2618f771ea3793fa0b3b566a81d794b3 Mon Sep 17 00:00:00 2001 From: Rello Date: Tue, 22 Sep 2026 15:00:09 +0200 Subject: [PATCH 4/4] docs: link Windows update policy reference Signed-off-by: Rello Assisted-by: Codex:GPT-5 --- user_manual/desktop/advanced_configuration.rst | 1 + user_manual/desktop/autoupdate.rst | 2 ++ 2 files changed, 3 insertions(+) diff --git a/user_manual/desktop/advanced_configuration.rst b/user_manual/desktop/advanced_configuration.rst index aa86e17d5dc..b5d300df27e 100644 --- a/user_manual/desktop/advanced_configuration.rst +++ b/user_manual/desktop/advanced_configuration.rst @@ -166,6 +166,7 @@ managed by the client. Use the setup wizard and **Settings** window to change th Precedence depends on the setting. The environment overrides listed below apply only to their corresponding settings. For ``skipUpdateCheck`` and ``autoUpdateCheck``, a value in ``[General]`` takes precedence over ``[Nextcloud]``. On Windows, administrator policies can override those update settings and the folder-size and external-storage settings. +See :ref:`preventing-automatic-updates-in-windows-environments` for details about update policies. .. _nextcloud-section: diff --git a/user_manual/desktop/autoupdate.rst b/user_manual/desktop/autoupdate.rst index edba53e00aa..e6e422aedea 100644 --- a/user_manual/desktop/autoupdate.rst +++ b/user_manual/desktop/autoupdate.rst @@ -63,6 +63,8 @@ deployment tools and policies. To address this case, it is possible to disable the auto-updater entirely. The following sections describe how to disable the auto-update mechanism for different operating systems. +.. _preventing-automatic-updates-in-windows-environments: + Preventing Automatic Updates in Windows Environments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^