Elaborate on Service Discovery troubleshooting

- provide subsections for the different services and configurations
- provide command line `curl` examples to debug the redirects
- provide exmaple config for apache .htaccess to redirect any well known service
- consistently use `NGINX` in headers, and `nginx` in text
- fix some spelling/grammar

Signed-off-by: Martin Rüegg <[email protected]>

Author: martin-rueegg

admin_manual/installation/nginx-root.conf.sample

@@ -118,22 +118,32 @@ server {
         access_log off;
     }
 
-    # Make a regex exception for `/.well-known` so that clients can still
-    # access it despite the existence of the regex rule
-    # `location ~ /(\.|autotest|...)` which would otherwise handle requests
-    # for `/.well-known`.
-    location ^~ /.well-known {
+    # Service Discovery for well-known services
+    # (Do not allow the browse the directory).
+    location =  /.well-known  { return 403; }
+    location =  /.well-known/ { return 403; }
+    location ^~ /.well-known/ {
+        # Using the special prefix syntax (`location ^~ /.well-known/` rather than `location /.well-known/` prevent
+        # the regex evaluation of other location entries (e.g. `location ~ /(\.|autotest|...)`), which would take
+        # precedence over this prefix. See https://nginx.org/en/docs/http/ngx_http_core_module.html#location
+
         # The rules in this block are an adaptation of the rules
         # in `.htaccess` that concern `/.well-known`.
 
         location = /.well-known/carddav { return 301 /remote.php/dav/; }
         location = /.well-known/caldav  { return 301 /remote.php/dav/; }
 
-        location /.well-known/acme-challenge    { try_files $uri $uri/ =404; }
-        location /.well-known/pki-validation    { try_files $uri $uri/ =404; }
+        location = /.well-known/acme-challenge   { return 404; }
+        location   /.well-known/acme-challenge/  { try_files $uri =404; }
+        location = /.well-known/pki-validation   { return 404; }
+        location   /.well-known/pki-validation/  { try_files $uri =404; }
+
+        # Add other exceptions/redirects here if you have other applications that provide a well known service
 
         # Let Nextcloud's API for `/.well-known` URIs handle all other
         # requests by passing them to the front-end controller.
+        # (use permanent redirect as it can be assumed that no new well-known service is provided
+        #  by another application, given that Nextcloud is installed in the webroot.)
         return 301 /index.php$request_uri;
     }
 

admin_manual/installation/nginx-subdir.conf.sample

@@ -61,19 +61,34 @@ server {
         access_log off;
     }
 
-    location ^~ /.well-known {
+    # Service Discovery for well-known services
+    # (Do not allow the browse the directory).
+    location =  /.well-known  { return 403; }
+    location =  /.well-known/ { return 403; }
+    location ^~ /.well-known/ {
+        # Using the special prefix syntax (`location ^~ /.well-known/` rather than `location /.well-known/` prevent
+        # the regex evaluation of other location entries, which would take precedence over this prefix.
+        # See https://nginx.org/en/docs/http/ngx_http_core_module.html#location
+        # Although not strictly necessary within the context of this example (as the colliding rule, e.g. `location ~ /(\.|autotest|...)`,
+        # is now in the subfolder), some other pre-existing or future locations might still have such a rule.
+
         # The rules in this block are an adaptation of the rules
         # in the Nextcloud `.htaccess` that concern `/.well-known`.
 
         location = /.well-known/carddav { return 301 /nextcloud/remote.php/dav/; }
         location = /.well-known/caldav  { return 301 /nextcloud/remote.php/dav/; }
 
-        location /.well-known/acme-challenge    { try_files $uri $uri/ =404; }
-        location /.well-known/pki-validation    { try_files $uri $uri/ =404; }
+        location = /.well-known/acme-challenge   { return 404; }
+        location   /.well-known/acme-challenge/  { try_files $uri =404; }
+        location = /.well-known/pki-validation   { return 404; }
+        location   /.well-known/pki-validation/  { try_files $uri =404; }
+
+        # Add other exceptions/redirects here if you have other applications that provide a well known service
 
         # Let Nextcloud's API for `/.well-known` URIs handle all other
         # requests by passing them to the front-end controller.
-        return 301 /nextcloud/index.php$request_uri;
+        # (use temporary redirect in case new well-known service is provided by another application.)
+        return 302 /nextcloud/index.php$request_uri;
     }
 
     location ^~ /nextcloud {

admin_manual/installation/nginx.rst

@@ -52,7 +52,6 @@ The configuration differs from the "Nextcloud in webroot" configuration above in
 - The string ``/nextcloud`` is prepended to all prefix paths.
 - The root of the domain is mapped to ``/var/www`` rather than ``/var/www/nextcloud``, so that the URI ``/nextcloud`` is mapped to the server directory ``/var/www/nextcloud``.
 - The blocks that handle requests for paths outside of ``/nextcloud`` (i.e. ``/robots.txt`` and ``/.well-known``) are pulled out of the ``location ^~ /nextcloud`` block.
-- The block which handles `/.well-known` doesn't need a regex exception, since the rule which prevents users from accessing hidden folders at the root of the Nextcloud installation no longer matches that path.
 
 .. literalinclude:: nginx-subdir.conf.sample
    :language: nginx