Merge branch 'issue-1' of https://github.com/acataluddi/nextcloud-doc…

…umentation into issue-1

Signed-off-by: Adriano Cataluddi <acataluddi@gmail.com>

.github/workflows/command-rebase.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
       - name: Add reaction on start
-        uses: peter-evans/create-or-update-comment@ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b # v3.0.1
+        uses: peter-evans/create-or-update-comment@c6c9a1a66007646a28c153e2a8580a5bad27bcfa # v3.0.2
         with:
           token: ${{ secrets.COMMAND_BOT_PAT }}
           repository: ${{ github.event.repository.full_name }}
@@ -42,7 +42,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
 
       - name: Add reaction on failure
-        uses: peter-evans/create-or-update-comment@ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b # v3.0.1
+        uses: peter-evans/create-or-update-comment@c6c9a1a66007646a28c153e2a8580a5bad27bcfa # v3.0.2
         if: failure()
         with:
           token: ${{ secrets.COMMAND_BOT_PAT }}

admin_manual/configuration_files/big_file_upload_configuration.rst

@@ -173,4 +173,10 @@ to the actual file on the Nextcloud servers temporary directory. It is recommend
 the size of your temp directory accordingly and also ensure that request timeouts are high
 enough for PHP, webservers or any load balancers involved.
 
+Federated Cloud Sharing
+-----------------------
+
+If you are using `Federated Cloud Sharing <https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/federated_cloud_sharing_configuration.html>`_ and want to share large files, you can increase the timeout values for requests to the federated servers.
+Therefore, you can set ``davstorage.request_timeout`` in your ``config.php``. The default value is 30 seconds.
+
 .. TODO ON RELEASE: Update version number above on release

admin_manual/configuration_files/external_storage/amazons3.rst

@@ -7,8 +7,7 @@ To connect an Amazon S3 (or compatible) bucket to Nextcloud you will need to kno
 - S3 bucket name
 - S3 access key ID
 - S3 secret access key
-- S3 region (if Amazon hosted)
-- S3 hostname (if non-Amazon hosted)
+- S3 region (if Amazon hosted) or S3 hostname (if non-Amazon hosted) [Note: If specifying a hostname, use the generic S3 endpoint hostname, **not** the hostname that contains your bucket name]
 
 In the **Folder name** field enter a folder name to use as the local mountpoint for this
 external storage. If this does not exist it will be created.
@@ -17,7 +16,7 @@ In the **External storage** field select **Amazon S3**.
 
 In the **Authentication** field select **Access key**.
 
-In the **Bucket** field enter your *S3 bucket name*.
+In the **Bucket** field enter your *S3 bucket name*. [Note: Even if non-Amazon hosted, bucket names must meet AWS S3 naming requirements regardless of what your S3 provider/platform considers acceptable - i.e. no underscores]
 
 In the **Access key** field enter your *S3 access key ID*.
 

admin_manual/configuration_files/federated_cloud_sharing_configuration.rst

@@ -109,6 +109,7 @@ manage federated cloud shares:
 * Check ``Set default expiration date`` to require an expiration date on link 
   shares.
 * Check ``Allow public uploads`` to allow two-way file sharing.
+* If you encounter timeouts for downloading or uploading large files, you can use the option ``davstorage.request_timeout`` in your ``config.php`` to increase the timeout. The default value is 30 seconds.
 
 Your Apache Web server must have ``mod_rewrite`` enabled, and you must have 
 ``trusted_domains`` correctly configured in ``config.php`` to allow external 

admin_manual/configuration_files/primary_storage.rst

@@ -166,7 +166,7 @@ Non-Amazon hosted S3:
 
 Minimum required parameters are:
 
-* :code:`bucket`
+* :code:`bucket` [Note: Even if non-Amazon hosted, bucket names must meet AWS S3 naming requirements regardless of what your S3 provider/platform considers acceptable - i.e. no underscores]
 * :code:`key`
 * :code:`secret`
 

admin_manual/configuration_server/config_sample_php_parameters.rst

@@ -372,6 +372,12 @@ which would overwrite this option if it is less than the value in the config.php
 
 Defaults to ``60*60*24`` seconds (24 hours)
 
+::
+
+	'davstorage.request_timeout' => 30,
+
+The timeout in seconds for requests to servers made by the DAV component (e.g., needed for federated shares).
+
 ::
 
 	'session_relaxed_expiry' => false,
@@ -2429,6 +2435,12 @@ or should be used together with the ``log.condition`` setting.
 
 Disable the web based updater
 
+::
+
+	'upgrade.cli-upgrade-link' => '',
+
+Allows to modify the cli-upgrade link in order to link to a different documentation
+
 ::
 
 	'debug' => false,

admin_manual/configuration_server/logging_configuration.rst

@@ -2,7 +2,11 @@
 Logging
 =======
 
-Use your Nextcloud log to review system status, or to help debug problems. You may adjust logging levels, and choose between using the Nextcloud log or your syslog. If additional audit information is required, you can optionally activate the **admin_audit** app, which by default generates a separate audit.log file in the data directory.
+Use your Nextcloud log to review system status, or to help debug problems. You may adjust logging levels, and choose how and where log data is stored. If additional event logging is required, you can optionally activate the **admin_audit** app. 
+
+When ``file`` based logging is utilized, both the Nextcloud log and, optionally, the **admit_audit** app log can be viewed within the Nextcloud interface under *Administration settings -> Logging* (this functionality is provided by the **logreader** app).
+
+Further configuration and usage details for both the standard Nextcloud log and the optional **admin_audit** app log can be found below. 
 
 Log level
 ---------
@@ -131,34 +135,55 @@ Log field breakdown
 
 Empty value are written as two dashes: ``--``.
 
-Admin audit log
----------------
+Admin audit log (Optional)
+--------------------------
+
+By enabling the **admin_audit** app, additional information about various events can be logged. Similar to the normal logging, the audit log can be provided to any of the existing logging mechanisms in :file:`config/config.php`. The default behavior, if no parameters are specified after the app is enabled, is ``file`` based logging to a file called ``audit.log`` stored in the ``datadirectory``.
 
-If ``loglevel`` in ``config.php`` is set to ``2`` or higher, audit logging needs to be triggered explicitly by adding the following setting to to ``config.php``:
+If you wish to override this and log to syslog instead the following would be one approach:
 
 ::
 
-	'log.condition' => [
-		'apps' => ['admin_audit'],
+	"log_type_audit" => "syslog",
+	"syslog_tag_audit" => "Nextcloud",
+	"logfile_audit" => "",
+
+Log level interaction
+~~~~~~~~~~~~~~~~~~~~~
+
+If system ``loglevel`` in ``config.php`` is set to ``2`` or higher, audit logging needs to be triggered explicitly by adding the following setting to to ``config.php``:
+
+::
+
+	"log.condition" => [
+		"apps" => ["admin_audit"],
 	],
 
+Find detailed documentation on auditable events for enterprises in our `customer portal <https://portal.nextcloud.com/article/using-the-audit-log-44.html>`_.
+
+Integrating into the Web Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The built-in NC ``logreader`` app (which is what provides the *Administration settings->Logging* interface) only accesses the file-based ``nextcloud.log``. The **admin_audit** app log output, however, can be integrated into the web interface by configuring it to *also* log to the ``nextcloud.log``.
 
-Similar to the normal logging, the audit log can be written to any of the existing logging mechanism in :file:`config/config.php`:
+Add the following to your ``config.php`` (adjusting the path to your own ``nextcloud.log`` path):
 
 ::
 
-	"log_type_audit" => "syslog",
-	"syslog_tag_audit" => "Nextcloud",
-	"logfile_audit" => "",
+	'log.condition' => [
+		'apps' => [ 'admin_audit'],
+	],
+	'logfile_audit' => '/var/www/html/data/nextcloud.log',
+
+Configuring through admin_audit app settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Previously the logfile could be defined in the app config. This config is still used when the system config is not provided:
+Previously the audit logfile was defined in the app config. This config is still used when the system config is not provided, but is considered a legacy parameter.
 
 ::
 
 	occ config:app:set admin_audit logfile --value=/var/log/nextcloud/audit.log
 
-Find detailed documentation on auditable events for enterprises in our `customer portal <https://portal.nextcloud.com/article/using-the-audit-log-44.html>`_.
-
 .. _PHP date function: http://www.php.net/manual/en/function.date.php
 
 Workflow log

admin_manual/configuration_server/occ_command.rst

@@ -161,6 +161,17 @@ This output option is available on all list and list-like commands:
 ``status``, ``check``, ``app:list``, ``config:list``, ``encryption:status``
 and ``encryption:list-modules``
 
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+
+``sudo`` does not forward environment variables by default. Put the variables before the ``php`` command::
+
+  sudo -u www-data NC_debug=true php occ status
+
+Alternatively, you can ``export`` the variable or use the ``-E`` switch for ``sudo``::
+
+  NC_debug=true sudo -E -u www-data php occ status
+
 Enabling autocompletion
 -----------------------
 

admin_manual/installation/nginx.rst

@@ -12,15 +12,19 @@ NGINX configuration
     These configurations examples were originally provided by `@josh4trunks <https://github.com/josh4trunks>`_
     and are exclusively community-maintained. (Thank you contributors!)
 
--  You need to insert the following code into **your Nginx configuration file.**
--  Adjust **server_name**, **root**, **ssl_certificate** and
-   **ssl_certificate_key** to suit your needs.
--  Make sure your SSL certificates are readable by the server (see `nginx HTTP
-   SSL Module documentation <https://wiki.nginx.org/HttpSslModule>`_).
--  Be careful about line breaks if you copy the examples, as long lines may be
-   broken for page formatting.
--  Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their
-   ``php.ini``.
+- You need to insert the following code into **your Nginx configuration file**. Choose the appropriate example based on whether you are deploying :ref:`nginx_webroot_example` (i.e. :code:`https://cloud.example.com/`) or :ref:`nginx_subdir_example` (i.e. :code:`https://cloud.example.com/nextcloud`).
+- Adjust the server directive under :code:`upstream php-handler` to match your PHP installation's configured FPM listener (a misconfiguration here will result in a :code:`502 Bad Gateway` - see :ref:`nginx_php_handler_tips` for details)
+- Adjust the existing :code:`server_name` directives found under *both* :code:`server` sections to your real hostname
+- Adjust :code:`root` to the webroot of your Nextcloud installation 
+- Adjust the :code:`ssl_certificate` and :code:`ssl_certificate_key` directives to the real paths for your signed 
+  certificate and private key. Make sure your SSL certificates are readable by the nginx server process (see `nginx HTTPS SSL 
+  Module documentation <https://wiki.nginx.org/HttpSslModule>`_).
+- Be careful about line breaks if you copy the examples, as long lines may be
+  broken for page display and result in an invalid configuration files.
+- Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their
+  ``php.ini``.
+
+.. nginx_webroot_example:
 
 Nextcloud in the webroot of NGINX
 ---------------------------------
@@ -32,6 +36,8 @@ webroot of your nginx installation. In this example it is
 .. literalinclude:: nginx-root.conf.sample
    :language: nginx
 
+.. nginx_subdir_example:
+
 Nextcloud in a subdir of the NGINX webroot
 ------------------------------------------
 
@@ -53,6 +59,25 @@ The configuration differs from the "Nextcloud in webroot" configuration above in
 Tips and tricks
 ---------------
 
+.. nginx_php_handler_tips:
+
+PHP-Handler Configuration / Avoiding "502 Bad Gateway"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :code:`server` line within the :code:`upstream php-handler` above needs to be adjusted to reflect your local PHP FPM configuration. It must match whatever is configured for the :code:`listen` directive within the PHP FPM pool you'll be using for NC.
+
+Many Linux distributions define a listener for a default PHP-FPM pool called :code:`www` in a file called :code:`www.conf` located somewhere like :code:`/etc/php/8.1/pool.d`.
+
+Look for the line that is set to something like: 
+
+:code:`listen = /var/run/php/php-fpm.sock`
+or
+:code:`listen = 127.0.0.1:9000`
+
+If PHP FPM will be running on the same host as NGINX (it's probably a safe assumption it will be if you're unsure), it is recommended you use the UNIX socket (i.e. :code:`/var/run/php/php-fpm.sock`) rather than TCP (:code:`127.0.0.1:9000`) for maximum performance (though either will work as long as your NGINX and PHP FPM configurations match).
+
+After deciding how you'd prefer to connect NGINX with PHP FPM (and, if necessary, updating your local PHP FPM configuration and restarting FPM), set your NGINX configuration's :code:`upstream php-handler` :code:`server` to match your preference (Note: If using UNIX sockets, prepend :code:`unix:` in the NGINX configuration, but *not* in your PHP FPM :code:`www.conf`). 
+
 Suppressing log messages
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

admin_manual/installation/system_requirements.rst

@@ -108,13 +108,13 @@ of our mobile apps.
 Files App
 ^^^^^^^^^
 
-- **iOS** 14.0+
+- **iOS** 15.0+
 - **Android** 6.0+
 
 Talk App
 ^^^^^^^^
 
-- **iOS** 14.0+
+- **iOS** 15.0+
 - **Android** 6.0+
 - **Nextcloud Server** 14.0+
 - **Nextcloud Talk** 4.0+

admin_manual/issues/general_troubleshooting.rst

@@ -260,14 +260,23 @@ document root of your Web server and add the following lines::
 
     <IfModule mod_rewrite.c>
       RewriteEngine on
-      RewriteRule ^/\.well-known/carddav /nextcloud/remote.php/dav [R=301,L]
-      RewriteRule ^/\.well-known/caldav /nextcloud/remote.php/dav [R=301,L]
-      RewriteRule ^/\.well-known/webfinger /nextcloud/index.php/.well-known/webfinger [R=301,L]
-      RewriteRule ^/\.well-known/nodeinfo /nextcloud/index.php/.well-known/nodeinfo [R=301,L]
+      RewriteRule ^\.well-known/carddav /nextcloud/remote.php/dav [R=301,L]
+      RewriteRule ^\.well-known/caldav /nextcloud/remote.php/dav [R=301,L]
+      RewriteRule ^\.well-known/webfinger /nextcloud/index.php/.well-known/webfinger [R=301,L]
+      RewriteRule ^\.well-known/nodeinfo /nextcloud/index.php/.well-known/nodeinfo [R=301,L]
     </IfModule>
 
 Make sure to change /nextcloud to the actual subfolder your Nextcloud instance is running in.
 
+.. note:: If you put the above directives directly into an Apache
+   configuration file (usually within ``/etc/apache2/``)
+   instead of ``.htaccess``, you need to prepend the first argument of
+   each ``RewriteRule`` option with a forward slash ``/``, for example
+   ``^/\.well-known/carddav``.
+   This is because Apache normalizes paths for the use in ``.htaccess``
+   files by dropping any number of leading slashes, but it does not
+   do so for the use in its main configuration files.
+
 If you are running NGINX, make sure ``location = /.well-known/carddav {`` and ``location = /.well-known/caldav {`` are properly configured as described in :doc:`../installation/nginx`, adapt to use a subfolder if necessary.
 
 Now change the URL in the client settings to just use:

developer_manual/basics/dependency_injection.rst

@@ -391,7 +391,6 @@ Types:
 * ``\OCP\ITempManager``
 * ``\OCP\Route\IRouter``
 * ``\OCP\ISearch``
-* ``\OCP\ISearch``
 * ``\OCP\Security\ICrypto``
 * ``\OCP\Security\IHasher``
 * ``\OCP\Security\ISecureRandom``
@@ -448,8 +447,8 @@ What not to inject:
 Accessing the container from anywhere
 -------------------------------------
 
-Sometimes it can be hard to inject some service inside legacy code, in these case
-you can use :code:`OCP\Server::get(MyService::class)`. This should only be used in
+Sometimes it can be hard to inject some service inside legacy code, in these cases
+you can use :code:`OCP\Server::get(MyService::class)`. This should only be used as
 the last resort, as this makes your code more complicated to unit test and is
 considered an anti-pattern.