diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 636edc777..3d669fe95 100644 --- a/admin_manual/contents.rst +++ b/admin_manual/contents.rst @@ -22,6 +22,7 @@ Table of contents ai/index webhook_listeners/index windmill_workflows/index + desktop/index configuration_database/index configuration_mimetypes/index maintenance/index diff --git a/admin_manual/desktop/accountcommand.rst b/admin_manual/desktop/accountcommand.rst new file mode 100644 index 000000000..8583c7361 --- /dev/null +++ b/admin_manual/desktop/accountcommand.rst @@ -0,0 +1,20 @@ +========================== +Command-line Account Setup +========================== + +If you want to automate an Account Setup Wizard to allow the user skip entering server URL and local sync folder path in UI, you can use command-line parameters. +When you specify both, the desktop client's Account Setup Wizard will jump straight to opening a browser for account authentication/connection without the need of entering any of the connection details. +The local sync folder will also be selected to the one you specify instead of using default path (/home/Nextcloud) + +The following parameters are supported: + +``--overridelocaldir`` + specify a local dir to be used in the account setup wizard (e.g.: /home/nextcloud-sync-folder) + +``--overrideserverurl`` + specify a server URL to use for the force override to be used in the account setup wizard (e.g.: https://cloud.example.com) + +Examples: + +- ``C:\Program Files\Nextcloud\nextcloud.exe" --overridelocaldir "D:/work/nextcloud-sync-folder" --overrideserverurl https://cloud.example.com`` +- For Linux and mac the same example as above will work but ``nextcloud.exe path`` and ``--overridelocaldir`` value should get changed to platform specific format (e.g. ``no .exe extension`` and ``/home/`` format) diff --git a/admin_manual/desktop/commandline.rst b/admin_manual/desktop/commandline.rst new file mode 100644 index 000000000..070f04bf4 --- /dev/null +++ b/admin_manual/desktop/commandline.rst @@ -0,0 +1,141 @@ +=================== +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 ``nextcloudcmd`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +CentOS + +:: + + $ sudo yum -y install epel-release + $ sudo yum -y install nextcloud-client + +Ubuntu + +:: + + $ sudo add-apt-repository ppa:nextcloud-devs/client + $ sudo apt update + $ sudo apt install nextcloud-client + +Debian + +:: + + $ sudo apt install nextcloud-desktop-cmd + + +Refer to the link + +- https://nextcloud.com/install/#install-clients +- https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client +- https://pkgs.alpinelinux.org/packages?name=nextcloud-client +- https://help.nextcloud.com/t/linux-packages-status/10216 + + +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. + +``--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://:@ diff --git a/admin_manual/desktop/configfile.rst b/admin_manual/desktop/configfile.rst new file mode 100644 index 000000000..89ffbfd5f --- /dev/null +++ b/admin_manual/desktop/configfile.rst @@ -0,0 +1,88 @@ +================== +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: + ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg`` + + +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. + +Some interesting values that can be set on the configuration file are: + ++----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Nextcloud]`` section | ++=================================+===============+========================================================================================================+ +| Variable | Default | Meaning | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``remotePollInterval`` | ``30000`` | Specifies the poll time for the remote repository in milliseconds. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``forceSyncInterval`` | ``7200000`` | The duration of no activity after which a synchronization run shall be triggered automatically. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``fullLocalDiscoveryInterval`` | ``3600000`` | The interval after which the next synchronization will perform a full local discovery. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``notificationRefreshInterval`` | ``300000`` | Specifies the default interval of checking for new server notifications in milliseconds. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ + + ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[General]`` section | ++==================================+==========================+========================================================================================================+ +| Variable | Default | Meaning | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``chunkSize`` | ``10000000`` (10 MB) | Specifies the chunk size of uploaded files in bytes. | +| | | The client will dynamically adjust this size within the maximum and minimum bounds (see below). | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``forceLoginV2`` | ``false`` | If the client should force the new login flow, even though some circumstances might need the old flow. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``minChunkSize`` | ``5000000`` (5 MB) | Specifies the minimum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``maxChunkSize`` | ``5000000000`` (5000 MB) | Specifies the maximum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``targetChunkUploadDuration`` | ``60000`` (1 minute) | Target duration in milliseconds for chunk uploads. | +| | | The client adjusts the chunk size until each chunk upload takes approximately this long. | +| | | Set to 0 to disable dynamic chunk sizing. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``promptDeleteAllFiles`` | ``false`` | If a UI prompt should ask for confirmation if it was detected that all files and folders were deleted. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``timeout`` | ``300`` | The timeout for network connections in seconds. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``moveToTrash`` | ``false`` | If non-locally deleted files should be moved to trash instead of deleting them completely. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``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 does enable 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. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ + + ++----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Proxy]`` section | ++=================================+===============+========================================================================================================+ +| Variable | Default | Meaning | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``host`` | ``127.0.0.1`` | The address of the proxy server. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``port`` | ``8080`` | The port were the proxy is listening. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``type`` | ``2`` | ``0`` for System Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``1`` for SOCKS5 Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``2`` for No Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``3`` for HTTP(S) Proxy. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ diff --git a/admin_manual/desktop/envvars.rst b/admin_manual/desktop/envvars.rst new file mode 100644 index 000000000..e820a5d55 --- /dev/null +++ b/admin_manual/desktop/envvars.rst @@ -0,0 +1,24 @@ +===================== +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: 50\*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: 250\*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. + +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 50 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 250 MB 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/admin_manual/desktop/images/create_debug_archive.png b/admin_manual/desktop/images/create_debug_archive.png new file mode 100644 index 000000000..7159f6bef Binary files /dev/null and b/admin_manual/desktop/images/create_debug_archive.png differ diff --git a/admin_manual/desktop/images/log_output_window.png b/admin_manual/desktop/images/log_output_window.png new file mode 100644 index 000000000..689f99591 Binary files /dev/null and b/admin_manual/desktop/images/log_output_window.png differ diff --git a/admin_manual/desktop/images/save_log_file.png b/admin_manual/desktop/images/save_log_file.png new file mode 100644 index 000000000..f10264b49 Binary files /dev/null and b/admin_manual/desktop/images/save_log_file.png differ diff --git a/admin_manual/desktop/index.rst b/admin_manual/desktop/index.rst new file mode 100644 index 000000000..e6eb0463a --- /dev/null +++ b/admin_manual/desktop/index.rst @@ -0,0 +1,30 @@ +=============== +Desktop Clients +=============== + +Available for Windows, macOS, and various Linux distributions, the Nextcloud +Desktop Sync client enables you to: + +- Specify one or more directories on your computer that you want to synchronize + to the Nextcloud server. +- Always have the latest files synchronized, wherever they are located. + +Your files are always automatically synchronized between your Nextcloud server, computer and mobile device. + +You can find the old documentation here: +* `Nextcloud Desktop Client`_ + +.. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/latest/ + + +.. toctree:: + :maxdepth: 1 + + options + massdeployment + configfile + envvars + commandline + accountcommand + troubleshooting + diff --git a/admin_manual/desktop/massdeployment.rst b/admin_manual/desktop/massdeployment.rst new file mode 100644 index 000000000..54de78842 --- /dev/null +++ b/admin_manual/desktop/massdeployment.rst @@ -0,0 +1,34 @@ +==================================== +Mass Deployment And Account Creation +==================================== + +It is possible to perform mass deployment of the Nextcloud desktop client by passing certain command-line parameters from the deployment step to Nextcloud desktop client executable after the initial setup. +This will allow desktop client to generate a config (.cfg) file that will be used during subsequent launches. +A config file will have a corresponding account written into it similar to if you have added it manually via the desktop client's UI. +The desktop client will exit with code 0 if account has been added successfully, or 1 in case of failure. +Detailed failure message is printed to the desktop client logs. + +The following parameters are supported: + +``--userid`` + (required) userId (username as on the server) to pass when creating an account via command-line. + +``--apppassword`` + (required) appPassword to pass when creating an account via command-line (see the ``login-flow`` section in server documentation on how to generate the app password). + +``--localdirpath`` + (optional) path where to create a local sync folder when creating an account via command-line. If skipped, then default local sync folder path (/home//Nextcloud for Linux/mac or C://Nextcloud for Windows) will be generated by desktop client. + +``--isvfsenabled`` + (optional) whether to set a VFS or non-VFS folder (1 for 'yes' or 0 for 'no') when creating an account via command-line. Default is 0. + +``--remotedirpath`` + (optional) path to a remote subfolder when creating an account via command-line. e.g. If the server has folders "/Photos", "/Documents", "/Music" you can pass "/Music" and then this folder will get set up as remote root. + +``--serverurl`` + (required) a server URL to use when creating an account via command-line. (NOTE: There is another parameter supported by Nextcloud desktop client ``--overrideserverurl`` but it SHOULD NOT be used here as it is intended for setup via UI with wizard) + +Examples: + +- ``C:\Program Files\Nextcloud\nextcloud.exe" --userid admin --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 --localdirpath "D:\\Nextcloud-sync-folder" --remotedirpath /Music --serverurl "https://cloud.example.com" --isvfsenabled 1"`` - this will create a config file for user admin on the server https://cloud.example.com and set a remote root folder to "Music", the local sync folder will get created with VFS mode. +- For Linux and mac the same example as above will work but ``nextcloud.exe path`` and ``--localdirpath`` value should get changed to platform specific format (e.g. ``no .exe extension`` and ``/home/`` format) diff --git a/admin_manual/desktop/options.rst b/admin_manual/desktop/options.rst new file mode 100644 index 000000000..42c4037bc --- /dev/null +++ b/admin_manual/desktop/options.rst @@ -0,0 +1,38 @@ +======= +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/admin_manual/desktop/troubleshooting.rst b/admin_manual/desktop/troubleshooting.rst new file mode 100644 index 000000000..c9b35906f --- /dev/null +++ b/admin_manual/desktop/troubleshooting.rst @@ -0,0 +1,326 @@ +=============== +Troubleshooting +=============== + +The following two general issues can result in failed synchronization: + +- The server setup is incorrect. +- The client contains a bug. + +When reporting bugs, it is helpful if you first determine what part of the +system is causing the issue. + +Identifying Basic Functionality Problems +---------------------------------------- + +:Performing a general Nextcloud Server test: + The first step in troubleshooting synchronization issues is to verify that + you can log on to the Nextcloud web application. To verify connectivity to the + Nextcloud server try logging in via your Web browser. + + If you are not prompted for your username and password, or if a red warning + box appears on the page, your server setup requires modification. Please verify + that your server installation is working correctly. + +:Ensure the WebDAV API is working: + If all desktop clients fail to connect to the Nextcloud Server, but access + using the Web interface functions properly, the problem is often a + misconfiguration of the WebDAV API. + + The Nextcloud Client uses the built-in WebDAV access of the server content. + Verify that you can log on to Nextcloud's WebDAV server. To verify connectivity + with the Nextcloud WebDAV server: + + - Open a browser window and enter the address to the Nextcloud WebDAV server. + + For example, if your Nextcloud instance is installed at + ``http://yourserver.com/nextcloud``, your WebDAV server address is + ``http://yourserver.com/nextcloud/remote.php/dav``. + + If you are prompted for your username and password but, after providing the + correct credentials, authentication fails, please ensure that your + authentication backend is configured properly. + +:Use a WebDAV command line tool to test: + A more sophisticated test method for troubleshooting synchronization issues + is to use a WebDAV command line client and log into the Nextcloud WebDAV server. + One such command line client -- called ``cadaver`` -- is available for Linux + distributions. You can use this application to further verify that the WebDAV + server is running properly using PROPFIND calls. + + As an example, after installing the ``cadaver`` app, you can issue the + ``propget`` command to obtain various properties pertaining to the current + directory and also verify WebDAV server connection. + +"CSync unknown error" +--------------------- + +If you see this error message stop your client, delete the +``.sync_xxxxxxx.db`` file, and then restart your client. +There is a hidden ``.sync_xxxxxxx.db`` file inside the folder of every account +configured on your client. + +.. NOTE:: + Please note that this will also erase some of your settings about which + files to download. + +See https://github.com/owncloud/client/issues/5226 for more discussion of this +issue. + +"Connection closed" message when syncing files +---------------------------------------------- + +This message can be caused by using chunks that are too big or time-outs that +are set too liberally. You can configure the chunking behavior of the client in +the config file. For example, change these settings: + ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``chunkSize`` | ``10000000`` (10 MB) | Specifies the chunk size of uploaded files in bytes. | +| | | The client will dynamically adjust this size within the maximum and minimum bounds (see below). | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``minChunkSize`` | ``1000000`` (1 MB) | Specifies the minimum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``maxChunkSize`` | ``50000000`` (1000 MB) | Specifies the maximum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``targetChunkUploadDuration`` | ``6000`` (1 minute) | Target duration in milliseconds for chunk uploads. | +| | | The client adjusts the chunk size until each chunk upload takes approximately this long. | +| | | Set to 0 to disable dynamic chunk sizing. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ + +Setting ``maxChunkSize`` to 50000000, for example, will decrease the +individual chunk to about 50 mb. This causes additional overhead but +might be required in some situations, for example behind CloudFlare which +has been seen limiting upload chunks to 100mb. In other situations, +limiting ``targetChunkUploadDuration`` can help to avoid time-outs. + +Connection issues with the macOS client on "insecure" connections +----------------------------------------------------------------- +When using macOS devices to connect to a Nextcloud server that uses a what maybe +be classified as an insecure connection (i.e. connecting to a server with a +self-signed certificate, or a certificate with what Apple may consider an +insufficiently secure cipher), the macOS client may not connect to the server. +This is because macOS requires a valid certificate to establish a connection. + +To resolve this issue, you must ensure the server is signed with a certificate +that is accepted by Apple's App Transport Security requirements. More +information on the requirements can be found in Apple's documentation pages. + +https://developer.apple.com/documentation/security/preventing-insecure-network-connections + +Isolating other issues +---------------------- + +Other issues can affect synchronization of your Nextcloud files: + +- If you find that the results of the synchronizations are unreliable, please + ensure that the folder to which you are synchronizing is not shared with + other synchronization applications. + +- Synchronizing the same directory with Nextcloud and other synchronization + software such as Unison, rsync, Microsoft Windows Offline Folders, or other + cloud services such as Dropbox or Microsoft SkyDrive is not supported and + should not be attempted. In the worst case, it is possible that synchronizing + folders or files using Nextcloud and other synchronization software or + services can result in data loss. + +- If you find that only specific files are not synchronized, the + synchronization protocol might be having an effect. Some files are + automatically ignored because they are system files, other files might be + ignored because their filename contains characters that are not supported on + certain file systems. For more information about ignored files, see `ignored-files`. + +- If you are operating your own server, and use the local storage backend (the + default), make sure that Nextcloud has exclusive access to the directory. + + .. warning:: The data directory on the server is exclusive to Nextcloud and must not be modified manually. + +- If you are using a different file backend on the server, you can try to exclude a bug in the + backend by reverting to the built-in backend. + +- If you are experiencing slow upload/download speed or similar performance issues + be aware that those could be caused by on-access virus scanning solutions, either + on the server (like the files_antivirus app) or the client. + +Log Files +--------- + +Effectively debugging software requires as much relevant information as can be +obtained. To assist the Nextcloud support personnel, please try to provide as +many relevant logs as possible. Log output can help with tracking down +problems and, if you report a bug, log output can help to resolve an issue more +quickly. + + .. warning:: Log files contain sensitive information. You may wish to redact sensitive details or to only share limited excerpts. + +Obtaining the Client Log File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create Debug Archive +~~~~~~~~~~~~~~~~~~~~ + +Since the 3.1.0 release we made it easier for users to provide debug information: debug logging is enabled by default with expiration time set to 24 hours and under the "General" settings, you can click on "Create Debug Archive ..." to pick the location of where the desktop client will export the logs and the database to a zip file. + +.. figure:: images/create_debug_archive.png + :alt: Create debug archive + +Keyboard shortcut +~~~~~~~~~~~~~~~~~ + +Another way to obtain the client log file: + +1. Open the Nextcloud Desktop Client. + +2. Press F12 or Ctrl-L on your keyboard. + +The Log Output window opens. + +.. figure:: images/log_output_window.png + :alt: Log output + +3. Click the 'Save' button. + +The Save Log File window opens. + +.. figure:: images/save_log_file.png + :alt: Save logfile + +4. Migrate to a location on your system where you want to save your log file. + +5. Name the log file and click the 'Save' button. + + The log file is saved in the location specified. + +Command line +~~~~~~~~~~~~ + +Alternatively, you can launch the Nextcloud Log Output window using the +``--logwindow`` command. After issuing this command, the Log Output window +opens to show the current log. You can then follow the same procedures +mentioned above to save the log to a file. + + .. note:: You can also open a log window for an already running session, by + restarting the client using the following command: + + * Windows: ``C:\Program Files (x86)\Nextcloud\nextcloud.exe --logwindow`` + * macOS: ``/Applications/nextcloud.app/Contents/MacOS/nextcloud --logwindow`` + * Linux: ``nextcloud --logwindow`` + +Config file +~~~~~~~~~~~ + +The Nextcloud client enables you to save log files directly to a predefined file +or directory. This is a useful option for troubleshooting sporadic issues as +it enables you to log large amounts of data and bypass the limited buffer +settings associated with the log window. + +To enable logging to a directory, stop the client and add the following to the General section in the configuration file: + +:: + + [General] + logDebug=true + logExpire= + logDir= + +Independent of platform you must use slash (/) as a path separator: + + .. note:: + * Correct: C:/Temp + * Not correct: C:\Temp + +As an example, to keep log data for two days in a directory called temp: + +:: + + [General] + logDebug=true + logExpire=48 + logDir=C:/Temp + +Once you restart the client, you will find the log file in the ```` defined in ``logDir``. + + .. note:: You will find the configuration file in the following locations: + + * Microsoft Windows systems: ``%APPDATA%\Nextcloud\nextcloud.cfg`` + * macOS systems: ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg`` + * Linux distributions: ``$HOME/.config/Nextcloud/nextcloud.cfg`` + + +Alternatively, you can start the client in the command line with parameters: + +1. To save to a file, start the client using the ``--logfile `` command, + where ```` is the filename to which you want to save the file. + +2. To save to a directory, start the client using the ``--logdir `` command, where ```` + is an existing directory. + +When using the ``--logdir`` command, each sync run creates a new file. To limit +the amount of data that accumulates over time, you can specify the +``--logexpire `` command. When combined with the ``--logdir`` command, +the client automatically erases saved log data in the directory that is older +than the specified number of hours. + +As an example, to define a test where you keep log data for two days, you can +issue the following command: + +``` +nextcloud --logdir /tmp/nextcloud_logs --logexpire 48 +``` + +Nextcloud server Log File +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Nextcloud server also maintains an Nextcloud specific log file. This log file +must be enabled through the Nextcloud Administration page. On that page, you can +adjust the log level. We recommend that when setting the log file level that +you set it to a verbose level like ``Debug`` or ``Info``. + +You can view the server log file using the web interface or you can open it +directly from the file system in the Nextcloud server data directory. + +.. todo:: Need more information on this. How is the log file accessed? + Need to explore procedural steps in access and in saving this file ... similar + to how the log file is managed for the client. Perhaps it is detailed in the + Admin Guide and a link should be provided from here. I will look into that + when I begin heavily editing the Admin Guide. + +Webserver Log Files +~~~~~~~~~~~~~~~~~~~ + +It can be helpful to view your webserver's error log file to isolate any +Nextcloud-related problems. For Apache on Linux, the error logs are typically +located in the ``/var/log/apache2`` directory. Some helpful files include the +following: + +- ``error_log`` -- Maintains errors associated with PHP code. +- ``access_log`` -- Typically records all requests handled by the server; very + useful as a debugging tool because the log line contains information specific + to each request and its result. + +You can find more information about Apache logging at +``http://httpd.apache.org/docs/current/logs.html``. + +Core Dumps +---------- + +On macOS and Linux systems, and in the unlikely event the client software +crashes, the client is able to write a core dump file. Obtaining a core dump +file can assist Nextcloud Customer Support tremendously in the debugging +process. + +To enable the writing of core dump files, you must define the +``OWNCLOUD_CORE_DUMP`` environment variable on the system. + +For example: + +``` +OWNCLOUD_CORE_DUMP=1 nextcloud +``` + +This command starts the client with core dumping enabled and saves the files in +the current working directory. + +.. note:: Core dump files can be fairly large. Before enabling core dumps on + your system, ensure that you have enough disk space to accommodate these files. + Also, due to their size, we strongly recommend that you properly compress any + core dump files prior to sending them to Nextcloud Customer Support. diff --git a/user_manual/contents.rst b/user_manual/contents.rst index 3bf06c923..b47c55abe 100644 --- a/user_manual/contents.rst +++ b/user_manual/contents.rst @@ -8,7 +8,6 @@ Table of contents :maxdepth: 2 index - whats_new webinterface files/index groupware/index diff --git a/user_manual/images/apps_menu.png b/user_manual/images/apps_menu.png deleted file mode 100644 index dacc4b705..000000000 Binary files a/user_manual/images/apps_menu.png and /dev/null differ diff --git a/user_manual/images/contacts_menu.png b/user_manual/images/contacts_menu.png deleted file mode 100644 index 3d01b9200..000000000 Binary files a/user_manual/images/contacts_menu.png and /dev/null differ diff --git a/user_manual/images/contacts_popup.png b/user_manual/images/contacts_popup.png deleted file mode 100644 index c81df4bbe..000000000 Binary files a/user_manual/images/contacts_popup.png and /dev/null differ diff --git a/user_manual/images/multi_sharing.png b/user_manual/images/multi_sharing.png deleted file mode 100644 index 9700208d4..000000000 Binary files a/user_manual/images/multi_sharing.png and /dev/null differ diff --git a/user_manual/whats_new.rst b/user_manual/whats_new.rst deleted file mode 100644 index 43ed61bda..000000000 --- a/user_manual/whats_new.rst +++ /dev/null @@ -1,25 +0,0 @@ -=========================================== -What's new for users in Nextcloud |version| -=========================================== - -1. Easier way to select a new app: - - .. figure:: images/apps_menu.png - :alt: screenshot of apps menu at top-left of Nextcloud Web GUI - -2. New Contacts menu to reach your colleagues or friends easier: - - .. figure:: images/contacts_menu.png - :alt: screenshot of contacts menu at top-right of Nextcloud Web GUI - -3. A contact popup menu over avatars everywhere: - - .. figure:: images/contacts_popup.png - :alt: screenshot of popup over avatar - -4. Ability to send multiple unique sharing links each with their own settings, by entering email addresses (the recipient will receive an email): - - .. figure:: images/multi_sharing.png - :alt: screenshot of multiple sharing links - -5. Many other improvements and new apps, like screensharing in Video calls, new Circles app for user defined groups, push notifications, notifications of file changes even when shared to another server, undo removal of files from a shared folder even if the removal was done by a recipient, directly sharing to social media and much more.